Skip to main content

orbit_event/
lib.rs

1//! `OrbitEventBus` — append-only event stream over one Orbit ring.
2//!
3//! Events are not cache entries and not metrics snapshots. Cache reads
4//! ask "what is the newest value for this key?" Metrics reads ask "what
5//! is the newest sample for each node?" Event reads ask "which frames
6//! have appeared since my cursor?"
7//!
8//! One event SHM segment carries all topics, with one writer lane per fleet
9//! node. The topic is carried inside the frame payload, so adding a new event
10//! type does not allocate another SHM segment. Subscribers keep one cursor per
11//! node lane and do not assume a total order across nodes.
12
13use std::sync::Arc;
14use std::time::{SystemTime, UNIX_EPOCH};
15
16use bytes::{BufMut, Bytes, BytesMut};
17
18#[cfg(any(target_os = "linux", target_os = "freebsd"))]
19use orbit_rs::RingEventFd;
20use orbit_rs::fleet::FleetLaneCursor;
21use orbit_rs::{Fleet, NetId64, NodeId, OrbitTyped, RingSpec};
22
23pub type Result<T, E = Error> = std::result::Result<T, E>;
24
25/// Failures produced by the Orbit event semantic layer.
26#[derive(Debug)]
27pub enum Error {
28    /// A topic and payload envelope cannot fit in one configured event frame.
29    FrameTooLarge {
30        topic_len: usize,
31        payload_len: usize,
32        max_payload: usize,
33    },
34    /// The underlying Orbit ring operation failed.
35    Io(std::io::Error),
36}
37
38impl std::fmt::Display for Error {
39    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
40        match self {
41            Self::FrameTooLarge {
42                topic_len,
43                payload_len,
44                max_payload,
45            } => write!(
46                f,
47                "orbit event frame too large: topic_len={topic_len} payload_len={payload_len} max_payload={max_payload}"
48            ),
49            Self::Io(error) => write!(f, "orbit event io error: {error}"),
50        }
51    }
52}
53
54impl std::error::Error for Error {
55    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
56        match self {
57            Self::Io(error) => Some(error),
58            Self::FrameTooLarge { .. } => None,
59        }
60    }
61}
62
63/// Event frame payload limit for V0. This is the event lane's own SHM
64/// payload capacity; non-Unix keeps the same contract so callers do not
65/// accidentally rely on unbounded in-memory frames.
66pub const EVENT_RING_SPEC: RingSpec = RingSpec::per_node(1024, 256);
67pub const EVENT_PAYLOAD_MAX: usize = EVENT_RING_SPEC.payload_capacity;
68
69const HEADER_LEN: usize = 2 + 2 + 8;
70const FRAME_KIND_EVENT: u8 = 1;
71pub const EVENT_RING_KIND: u8 = 220;
72
73/// Dedicated per-node-lane ring kind for raw Orbit events.
74#[derive(Clone, Debug)]
75struct OrbitEventRecord;
76
77impl OrbitTyped for OrbitEventRecord {
78    // Hand-picked V0 kind. Build-time KIND allocation will replace
79    // these manual values later.
80    const KIND: u8 = EVENT_RING_KIND;
81    const RING_SPEC: RingSpec = EVENT_RING_SPEC;
82}
83
84/// Cursor for one event subscriber.
85///
86/// The cursor stores one next counter per node lane. It is intentionally
87/// caller-owned so different consumers can advance independently.
88#[derive(Clone, Debug, PartialEq, Eq)]
89pub struct OrbitEventCursor {
90    inner: FleetLaneCursor,
91}
92
93impl OrbitEventCursor {
94    /// Start from the beginning of the ring history that is still
95    /// available.
96    pub const fn from_start() -> Self {
97        Self {
98            inner: FleetLaneCursor::from_counter(0),
99        }
100    }
101
102    /// Start from a known next counter.
103    pub const fn from_counter(next_counter: u64) -> Self {
104        Self {
105            inner: FleetLaneCursor::from_counter(next_counter),
106        }
107    }
108
109    /// The lowest next counter among the node lanes.
110    pub fn next_counter(&self) -> u64 {
111        self.inner.minimum_next_counter()
112    }
113}
114
115/// One decoded event from the shared event ring.
116#[derive(Clone, Debug, PartialEq, Eq)]
117pub struct OrbitEvent {
118    pub id: NetId64,
119    pub topic: String,
120    pub payload: Vec<u8>,
121    pub timestamp_ms: u64,
122}
123
124/// Result of polling an event cursor.
125#[derive(Clone, Debug, Default, PartialEq, Eq)]
126pub struct OrbitEventPoll {
127    pub events: Vec<OrbitEvent>,
128    /// Number of counters that could not be delivered because the
129    /// subscriber lagged past the ring capacity, a slot was empty, or a
130    /// slot had already wrapped to another counter.
131    pub lagged: u64,
132}
133
134impl OrbitEventPoll {
135    pub fn is_empty(&self) -> bool {
136        self.events.is_empty() && self.lagged == 0
137    }
138}
139
140/// Fleet-shared raw event bus. Cheap to clone.
141#[derive(Clone)]
142pub struct OrbitEventBus {
143    fleet: Arc<Fleet>,
144}
145
146impl OrbitEventBus {
147    pub fn new(fleet: Arc<Fleet>) -> Self {
148        Self { fleet }
149    }
150
151    pub fn node_id(&self) -> NodeId {
152        self.fleet.node_id()
153    }
154
155    /// Cursor that starts after all events currently in the ring.
156    /// Useful for subscribers that only want future events.
157    pub fn cursor_at_head(&self) -> OrbitEventCursor {
158        OrbitEventCursor {
159            inner: self.fleet.lane_cursor_at_head::<OrbitEventRecord>(),
160        }
161    }
162
163    /// Cursor that starts at counter 0 and replays whatever history has
164    /// not wrapped out of the ring.
165    pub const fn cursor_from_start(&self) -> OrbitEventCursor {
166        let _ = self;
167        OrbitEventCursor::from_start()
168    }
169
170    /// Clear the shared event ring.
171    ///
172    /// Intended for owner-controlled boot-time cleanup before peer
173    /// processes publish events into the ring. This prevents stale
174    /// events from a previous process lifetime from being replayed or
175    /// counted as current runtime state.
176    pub fn reset_ring(&self) -> Result<()> {
177        self.fleet
178            .reset_ring::<OrbitEventRecord>()
179            .map_err(Error::Io)
180    }
181
182    /// Create this process' native fd readiness bridge for the event ring.
183    ///
184    /// The returned fd is local to this process. Publishers notify a shared
185    /// generation after committing an event; the bridge converts that
186    /// broadcast into local fd readiness suitable for epoll/kqueue/AsyncFd.
187    /// Drain the fd, then poll the ring with this subscriber's cursor.
188    #[cfg(any(target_os = "linux", target_os = "freebsd"))]
189    pub fn event_fd(&self) -> Result<RingEventFd> {
190        self.fleet
191            .ring_event_fd::<OrbitEventRecord>()
192            .map_err(Error::Io)
193    }
194
195    /// Publish one event under `topic`.
196    pub fn publish(&self, topic: &str, payload: &[u8]) -> Result<NetId64> {
197        let timestamp_ms = now_ms();
198        let frame = encode_frame(topic.as_bytes(), payload, timestamp_ms)?;
199        #[cfg(any(target_os = "linux", target_os = "freebsd"))]
200        let id = self
201            .fleet
202            .publish_notified::<OrbitEventRecord>(FRAME_KIND_EVENT, timestamp_ms, frame)
203            .map_err(Error::Io)?;
204        #[cfg(not(any(target_os = "linux", target_os = "freebsd")))]
205        let id = self
206            .fleet
207            .publish::<OrbitEventRecord>(FRAME_KIND_EVENT, timestamp_ms, frame);
208        Ok(id)
209    }
210
211    /// Poll all events since `cursor`, advancing the cursor to the
212    /// current ring head. If the cursor has fallen behind the ring
213    /// capacity, older overwritten counters are reported as `lagged`.
214    pub fn poll(&self, cursor: &mut OrbitEventCursor) -> OrbitEventPoll {
215        let ring_poll = self.fleet.poll_lanes::<OrbitEventRecord>(&mut cursor.inner);
216        let mut lagged = ring_poll.loss.total();
217        let mut events = Vec::new();
218        for frame in ring_poll.frames {
219            let Some(decoded) = decode_frame(&frame.payload) else {
220                lagged = lagged.saturating_add(1);
221                continue;
222            };
223            events.push(OrbitEvent {
224                id: frame.id,
225                topic: String::from_utf8_lossy(decoded.topic).into_owned(),
226                payload: decoded.payload.to_vec(),
227                timestamp_ms: decoded.timestamp_ms,
228            });
229        }
230
231        OrbitEventPoll { events, lagged }
232    }
233
234    /// Poll and keep only events whose topic matches `topic`.
235    ///
236    /// The cursor still advances past all events, including filtered
237    /// topics. Use separate cursors for independent consumers.
238    pub fn poll_topic(&self, cursor: &mut OrbitEventCursor, topic: &str) -> OrbitEventPoll {
239        let mut poll = self.poll(cursor);
240        poll.events.retain(|event| event.topic == topic);
241        poll
242    }
243}
244
245struct DecodedFrame<'a> {
246    topic: &'a [u8],
247    payload: &'a [u8],
248    timestamp_ms: u64,
249}
250
251fn encode_frame(topic: &[u8], payload: &[u8], timestamp_ms: u64) -> Result<Bytes> {
252    let total = HEADER_LEN + topic.len() + payload.len();
253    if topic.len() > u16::MAX as usize
254        || payload.len() > u16::MAX as usize
255        || total > EVENT_PAYLOAD_MAX
256    {
257        return Err(Error::FrameTooLarge {
258            topic_len: topic.len(),
259            payload_len: payload.len(),
260            max_payload: EVENT_PAYLOAD_MAX,
261        });
262    }
263
264    let mut buf = BytesMut::with_capacity(total);
265    buf.put_u16_le(topic.len() as u16);
266    buf.put_u16_le(payload.len() as u16);
267    buf.put_u64_le(timestamp_ms);
268    buf.put_slice(topic);
269    buf.put_slice(payload);
270    Ok(buf.freeze())
271}
272
273fn decode_frame(payload: &Bytes) -> Option<DecodedFrame<'_>> {
274    if payload.len() < HEADER_LEN {
275        return None;
276    }
277
278    let topic_len = u16::from_le_bytes(payload[0..2].try_into().ok()?) as usize;
279    let payload_len = u16::from_le_bytes(payload[2..4].try_into().ok()?) as usize;
280    let timestamp_ms = u64::from_le_bytes(payload[4..12].try_into().ok()?);
281    let topic_start = HEADER_LEN;
282    let topic_end = topic_start.checked_add(topic_len)?;
283    let payload_end = topic_end.checked_add(payload_len)?;
284    if payload.len() < payload_end {
285        return None;
286    }
287
288    Some(DecodedFrame {
289        topic: &payload[topic_start..topic_end],
290        payload: &payload[topic_end..payload_end],
291        timestamp_ms,
292    })
293}
294
295fn now_ms() -> u64 {
296    SystemTime::now()
297        .duration_since(UNIX_EPOCH)
298        .map(|d| d.as_millis().min(u128::from(u64::MAX)) as u64)
299        .unwrap_or(0)
300}
301
302#[cfg(test)]
303mod tests {
304    use std::sync::Arc;
305
306    use super::OrbitEventBus;
307    use orbit_rs::Fleet;
308
309    #[test]
310    fn polls_events_since_cursor() {
311        let fleet = Arc::new(Fleet::join("event_poll", 1).expect("fleet"));
312        let bus = OrbitEventBus::new(fleet);
313        let mut cursor = bus.cursor_from_start();
314
315        bus.publish("worker.booted", b"w1").expect("publish first");
316        bus.publish("cache.reset", b"all").expect("publish second");
317
318        let poll = bus.poll(&mut cursor);
319        assert_eq!(poll.lagged, 0);
320        assert_eq!(poll.events.len(), 2);
321        assert_eq!(poll.events[0].topic, "worker.booted");
322        assert_eq!(poll.events[0].payload, b"w1");
323        assert_eq!(poll.events[1].topic, "cache.reset");
324        assert_eq!(poll.events[1].payload, b"all");
325
326        assert!(bus.poll(&mut cursor).is_empty());
327    }
328
329    #[test]
330    fn cursor_at_head_only_reads_future_events() {
331        let fleet = Arc::new(Fleet::join("event_head", 1).expect("fleet"));
332        let bus = OrbitEventBus::new(fleet);
333
334        bus.publish("old", b"ignored").expect("publish old");
335        let mut cursor = bus.cursor_at_head();
336        bus.publish("new", b"seen").expect("publish new");
337
338        let poll = bus.poll(&mut cursor);
339        assert_eq!(poll.events.len(), 1);
340        assert_eq!(poll.events[0].topic, "new");
341    }
342
343    #[test]
344    fn topic_filter_advances_cursor() {
345        let fleet = Arc::new(Fleet::join("event_topic", 1).expect("fleet"));
346        let bus = OrbitEventBus::new(fleet);
347        let mut cursor = bus.cursor_from_start();
348
349        bus.publish("a", b"1").expect("publish a");
350        bus.publish("b", b"2").expect("publish b");
351
352        let poll = bus.poll_topic(&mut cursor, "b");
353        assert_eq!(poll.events.len(), 1);
354        assert_eq!(poll.events[0].payload, b"2");
355        assert!(bus.poll(&mut cursor).is_empty());
356    }
357
358    #[test]
359    fn reports_lag_when_cursor_falls_behind_capacity() {
360        let fleet = Arc::new(Fleet::join("event_lag", 1).expect("fleet"));
361        let bus = OrbitEventBus::new(fleet);
362        let mut cursor = bus.cursor_from_start();
363
364        for value in 0..=super::EVENT_RING_SPEC.capacity {
365            bus.publish("n", value.to_string().as_bytes())
366                .expect("publish event");
367        }
368
369        let poll = bus.poll(&mut cursor);
370        assert_eq!(poll.lagged, 1);
371        assert_eq!(poll.events.len(), super::EVENT_RING_SPEC.capacity);
372        assert_eq!(poll.events[0].payload, b"1");
373    }
374}