zc2 0.0.47

P2P compute broker with yen-denominated billing, WAL, and broker mesh support
//! The agent's event stream behind `GET /v2/events` (ADR ZC-0019 §3).
//!
//! Every event gets the next id from one counter. The last [`RING`] events
//! are kept, so a client that reconnects with `Last-Event-ID` gets what it
//! missed; one that fell further behind than the ring reaches (or names an id
//! this agent never issued, e.g. after an agent restart) gets a single
//! `resync` event instead, and re-fetches `/v2/summary`.

use serde::Serialize;
use std::collections::VecDeque;
use std::sync::Mutex;
use tokio::sync::broadcast;

/// How many events a reconnecting client can catch up on.
pub const RING: usize = 256;

/// The event types ADR ZC-0019 §3 names, plus `resync`, which is only ever
/// sent to one client and never stored.
pub const TYPES: &[&str] = &[
    "summary.changed",
    "job.started",
    "job.finished",
    "policy.changed",
    "sandbox.state",
    "squad.changed",
    "env.state",
    "problem.raised",
    "problem.cleared",
    "submission.state",
];

#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct Event {
    pub id: u64,
    #[serde(rename = "type")]
    pub kind: String,
    /// RFC 3339 UTC, whole seconds, with a `Z`, like every summary timestamp.
    pub at: String,
    pub data: serde_json::Value,
}

/// What a reconnecting client is owed.
#[derive(Debug, PartialEq)]
pub enum Replay {
    /// Every event after the one it last saw (possibly none).
    Events(Vec<Event>),
    /// Too far behind, or an id from another agent run: re-fetch the summary.
    Resync,
}

pub struct EventBus {
    ring: Mutex<VecDeque<Event>>,
    /// The id the next event gets. Starts at 1, so `Last-Event-ID: 0` means
    /// "from the beginning of this run".
    next: Mutex<u64>,
    tx: broadcast::Sender<Event>,
}

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

impl EventBus {
    pub fn new() -> Self {
        let (tx, _) = broadcast::channel(RING);
        Self {
            ring: Mutex::new(VecDeque::with_capacity(RING)),
            next: Mutex::new(1),
            tx,
        }
    }

    /// Record and broadcast one event. Returns its id.
    pub fn publish(&self, kind: &str, data: serde_json::Value) -> u64 {
        debug_assert!(TYPES.contains(&kind), "unknown event type {kind}");
        // Taken in this order everywhere: `next` then `ring`, so ids enter
        // the ring in order and `subscribe` sees a consistent cut.
        let mut next = self.next.lock().unwrap();
        let id = *next;
        *next += 1;
        let event = Event {
            id,
            kind: kind.to_string(),
            at: chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
            data,
        };
        let mut ring = self.ring.lock().unwrap();
        if ring.len() == RING {
            ring.pop_front();
        }
        ring.push_back(event.clone());
        // No receivers is fine: nobody is listening right now.
        let _ = self.tx.send(event);
        id
    }

    /// The id the last published event got (0 before the first).
    pub fn last_id(&self) -> u64 {
        *self.next.lock().unwrap() - 1
    }

    /// A live receiver plus what the client missed since `last_seen`, taken
    /// under one lock so no event falls between the replay and the live feed.
    pub fn subscribe(&self, last_seen: Option<u64>) -> (Replay, broadcast::Receiver<Event>) {
        let next = self.next.lock().unwrap();
        let ring = self.ring.lock().unwrap();
        let rx = self.tx.subscribe();
        let replay = match last_seen {
            None => Replay::Events(vec![]),
            Some(seen) if seen >= *next => Replay::Resync, // not from this run
            Some(seen) => {
                let oldest = ring.front().map_or(*next, |e| e.id);
                // Everything after `seen` must still be in the ring.
                if seen + 1 < oldest {
                    Replay::Resync
                } else {
                    Replay::Events(ring.iter().filter(|e| e.id > seen).cloned().collect())
                }
            }
        };
        (replay, rx)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    #[test]
    fn ids_increase_and_a_reconnect_gets_what_it_missed() {
        let bus = EventBus::new();
        assert_eq!(bus.last_id(), 0);
        let a = bus.publish("job.started", json!({"id": "j1"}));
        let b = bus.publish("job.finished", json!({"id": "j1"}));
        assert_eq!((a, b, bus.last_id()), (1, 2, 2));

        let (replay, _) = bus.subscribe(Some(1));
        match replay {
            Replay::Events(ev) => {
                assert_eq!(ev.len(), 1);
                assert_eq!((ev[0].id, ev[0].kind.as_str()), (2, "job.finished"));
            }
            other => panic!("{other:?}"),
        }
        assert_eq!(bus.subscribe(Some(2)).0, Replay::Events(vec![]));
        assert_eq!(bus.subscribe(None).0, Replay::Events(vec![]));
        let (replay, _) = bus.subscribe(Some(0));
        assert!(matches!(replay, Replay::Events(ref e) if e.len() == 2));
    }

    #[test]
    fn too_far_behind_or_from_another_run_is_a_resync() {
        let bus = EventBus::new();
        for i in 0..(RING + 10) {
            bus.publish("summary.changed", json!({ "n": i }));
        }
        assert_eq!(
            bus.subscribe(Some(1)).0,
            Replay::Resync,
            "fell off the ring"
        );
        assert_eq!(
            bus.subscribe(Some(10_000)).0,
            Replay::Resync,
            "an id this run never issued"
        );
        let last = bus.last_id();
        match bus.subscribe(Some(last - 3)).0 {
            Replay::Events(ev) => assert_eq!(ev.len(), 3),
            other => panic!("{other:?}"),
        }
        // The oldest kept event is still replayable from the id just before it.
        let oldest = last - RING as u64 + 1;
        match bus.subscribe(Some(oldest - 1)).0 {
            Replay::Events(ev) => assert_eq!(ev.len(), RING),
            other => panic!("{other:?}"),
        }
    }

    #[test]
    fn a_subscriber_receives_events_published_after_it_subscribed() {
        let bus = EventBus::new();
        bus.publish("summary.changed", json!({}));
        let (_, mut rx) = bus.subscribe(None);
        bus.publish("problem.raised", json!({"code": "uv_missing"}));
        let e = rx.try_recv().unwrap();
        assert_eq!((e.id, e.kind.as_str()), (2, "problem.raised"));
        let wire = serde_json::to_value(&e).unwrap();
        assert_eq!(wire["type"], "problem.raised");
        assert!(wire["at"].as_str().unwrap().ends_with('Z'));
    }
}