Skip to main content

xs/processor/
mod.rs

1pub mod action;
2pub mod actor;
3pub mod lifecycle;
4pub mod service;
5
6use crate::store::{FollowOption, Frame, ReadError, ReadItem, ReadOptions, Store};
7use scru128::Scru128Id;
8use tokio::sync::mpsc;
9
10pub enum Lifecycle {
11    Historical(Frame),
12    Threshold(Frame),
13    Live(Frame),
14}
15
16/// Reads the stream for a supervisor: the frames already stored, then
17/// `xs.threshold`, then each new frame, each one tagged with which of those
18/// it is (`Lifecycle::Historical`, `Threshold`, `Live`).
19///
20/// If the supervisor falls too far behind new frames, the store ends the
21/// read (ADR 0008). This reader then opens it again just after the last
22/// frame it returned, so the frames it missed are read from the store
23/// (ADR 0009). No frame is returned twice or skipped.
24pub struct LifecycleReader {
25    store: Store,
26    rx: mpsc::Receiver<ReadItem>,
27    past_threshold: bool,
28    /// The last stored frame handed out: where a reopened read starts.
29    last: Option<Scru128Id>,
30}
31
32impl LifecycleReader {
33    /// Follow the whole stream: stored frames, `xs.threshold`, then live.
34    pub fn follow(store: &Store) -> Self {
35        Self {
36            rx: Self::open(store, None),
37            store: store.clone(),
38            past_threshold: false,
39            last: None,
40        }
41    }
42
43    fn open(store: &Store, after: Option<Scru128Id>) -> mpsc::Receiver<ReadItem> {
44        store.read(
45            ReadOptions::builder()
46                .follow(FollowOption::On)
47                .maybe_after(after)
48                .build(),
49        )
50    }
51
52    /// The next frame, tagged stored, threshold or live. `Ok(None)` when
53    /// the read ends.
54    pub async fn recv(&mut self) -> Result<Option<Lifecycle>, crate::error::Error> {
55        loop {
56            let Some(item) = self.rx.recv().await else {
57                return Ok(None);
58            };
59            match item {
60                Ok(frame) => {
61                    if let Some(event) = self.classify(frame) {
62                        return Ok(Some(event));
63                    }
64                }
65                Err(ReadError::Lagged { skipped }) => {
66                    eprintln!(
67                        "supervisor fell behind the live stream ({skipped} frames skipped); reading them from the store"
68                    );
69                    self.rx = Self::open(&self.store, self.last);
70                }
71            }
72        }
73    }
74
75    /// Tag the frame stored, threshold or live. `None` for a second
76    /// `xs.threshold`: a reopened read sends one again, but the supervisor
77    /// is already past it.
78    fn classify(&mut self, frame: Frame) -> Option<Lifecycle> {
79        if frame.topic == "xs.threshold" {
80            if self.past_threshold {
81                return None;
82            }
83            self.past_threshold = true;
84            return Some(Lifecycle::Threshold(frame));
85        }
86        // Heartbeats are made up on the way out, not stored: they are no
87        // place to resume from.
88        if frame.topic != "xs.pulse" {
89            self.last = Some(frame.id);
90        }
91        Some(if self.past_threshold {
92            Lifecycle::Live(frame)
93        } else {
94            Lifecycle::Historical(frame)
95        })
96    }
97}
98
99#[cfg(test)]
100mod tests {
101    use super::*;
102    use crate::store::FOLLOW_BUFFER;
103    use std::time::Duration;
104    use tokio::time::timeout;
105
106    /// A supervisor that falls behind new frames reads the ones it missed
107    /// from the store and continues (ADR 0009): each frame arrives once, in
108    /// order, including the one appended after the burst.
109    #[tokio::test]
110    async fn test_supervisor_catches_up_after_falling_behind_live() {
111        let temp_dir = tempfile::tempdir().unwrap();
112        let store = Store::new(temp_dir.path().to_path_buf()).unwrap();
113        let mut reader = LifecycleReader::follow(&store);
114        assert!(matches!(
115            reader.recv().await.unwrap(),
116            Some(Lifecycle::Threshold(_))
117        ));
118
119        // Overrun the buffer without taking anything.
120        let burst = FOLLOW_BUFFER * 2;
121        let mut sent = Vec::new();
122        for _ in 0..burst {
123            sent.push(store.append(Frame::builder("filler").build()).unwrap().id);
124        }
125        let marker = store
126            .append(Frame::builder("xs.actor.late.create").build())
127            .unwrap();
128        sent.push(marker.id);
129
130        let mut got = Vec::new();
131        while got.len() < sent.len() {
132            match timeout(Duration::from_secs(10), reader.recv()).await {
133                Ok(Ok(Some(Lifecycle::Live(frame)))) => got.push(frame.id),
134                Ok(Ok(Some(_))) => {
135                    panic!("a second threshold, or a historical frame, after the first")
136                }
137                Ok(Ok(None)) => panic!("the read ended after {} frames", got.len()),
138                Ok(Err(err)) => panic!("the supervisor stopped: {err}"),
139                Err(_) => panic!("stalled after {} of {} frames", got.len(), sent.len()),
140            }
141        }
142        assert_eq!(got, sent, "every frame once, in order");
143    }
144}