apalis-rtui 0.1.0-rc.1

A drop-in replacement for apalis-board: HTTP surface, live updates, and the apalis-tui dashboard
Documentation
use apalis_rtui_types::LogEntry;
use futures::channel::mpsc::{SendError, Sender, channel};
use std::sync::{Arc, Mutex};

use crate::api::sse::Client;

/// A broadcaster that sends log entries to multiple connected SSE clients.
#[derive(Debug)]
pub struct TracingBroadcaster {
    clients: Vec<Sender<LogEntry>>,
}

impl Default for TracingBroadcaster {
    fn default() -> Self {
        Self::new()
    }
}

impl TracingBroadcaster {
    /// Create a new `TracingBroadcaster` wrapped in an `Arc<Mutex<>>`.
    #[must_use]
    pub fn create() -> Arc<Mutex<Self>> {
        Arc::new(Mutex::new(Self::new()))
    }

    /// Create a new `TracingBroadcaster`.
    #[must_use]
    pub fn new() -> Self {
        Self {
            clients: Vec::new(),
        }
    }

    /// Create a new client and register it with the broadcaster.
    pub fn new_client(&mut self) -> Client {
        let (tx, rx) = channel(100);

        self.clients.push(tx);
        Client(rx)
    }

    /// Send a log entry to all connected clients, and drop every client that has disconnected.
    ///
    /// One client is never allowed to starve another. A client whose 100-slot channel is full
    /// misses this entry and keeps its place, and the fan-out carries on to the clients behind
    /// it. That matters here beyond a browser tab going quiet: `EventRing`'s feeder registers as
    /// an ordinary client, so `/events/status`, `/events/activity` and the per-task route all
    /// read this stream, and a short-circuit on a stalled `/events` reader would freeze them for
    /// the whole process. `EventRing::record` fans out the same way.
    ///
    /// # Errors
    ///
    /// Never returns an error. The [`Result`] is kept because this is the published signature.
    pub fn send(&mut self, msg: &LogEntry) -> Result<(), SendError> {
        self.clients.retain_mut(|client| {
            match client.try_send(msg.clone()) {
                Ok(()) => true,
                // A full channel is a slow reader, so keep it and let it catch up. A
                // disconnected one is gone for good, so drop it: without this the vector grows
                // by one entry per SSE connection the process has ever served.
                Err(error) => !error.is_disconnected(),
            }
        });
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use apalis_rtui_types::{Entry, LogLevel, Span};
    use futures::StreamExt as _;

    use super::*;

    fn frame(message: &str) -> LogEntry {
        LogEntry {
            span: Some(Span {
                attempt: 1,
                task_id: "01K7EXAMPLE".to_owned(),
                name: "task".to_owned(),
            }),
            level: LogLevel::Debug,
            timestamp: "2024-01-01T00:00:00Z".to_owned(),
            target: "apalis::layers::tracing::on_request".to_owned(),
            entry: Entry {
                message: Some(message.to_owned()),
                entry_type: None,
            },
        }
    }

    /// A client that stopped reading must not cut off the clients behind it. The first one here
    /// is filled past its 100-slot channel before the second one even exists, which is the shape
    /// a backgrounded browser tab and the `EventRing` feeder take on a live server.
    #[test]
    fn a_full_client_does_not_starve_a_healthy_one() {
        let mut broadcaster = TracingBroadcaster::new();
        let _stalled = broadcaster.new_client();
        for seq in 0..200 {
            broadcaster
                .send(&frame(&format!("fill {seq}")))
                .expect("send never fails");
        }

        let healthy = broadcaster.new_client();
        for seq in 0..5 {
            broadcaster
                .send(&frame(&format!("live {seq}")))
                .expect("send never fails");
        }
        drop(broadcaster);

        let received: Vec<_> = futures::executor::block_on(healthy.0.collect::<Vec<_>>());
        assert_eq!(received.len(), 5, "the healthy client got every live frame");
    }

    /// A disconnected client leaves the vector, so a server the dashboard reconnects to every
    /// 1500ms does not accumulate one dead sender per attempt.
    #[test]
    fn a_disconnected_client_is_pruned() {
        let mut broadcaster = TracingBroadcaster::new();
        let kept = broadcaster.new_client();
        let dropped = broadcaster.new_client();
        assert_eq!(broadcaster.clients.len(), 2);

        drop(dropped);
        broadcaster.send(&frame("after drop")).expect("send");
        assert_eq!(broadcaster.clients.len(), 1);

        drop(kept);
        broadcaster.send(&frame("after both")).expect("send");
        assert_eq!(broadcaster.clients.len(), 0);
    }
}