1use 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#[derive(Debug)]
27pub enum Error {
28 FrameTooLarge {
30 topic_len: usize,
31 payload_len: usize,
32 max_payload: usize,
33 },
34 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
63pub 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#[derive(Clone, Debug)]
75struct OrbitEventRecord;
76
77impl OrbitTyped for OrbitEventRecord {
78 const KIND: u8 = EVENT_RING_KIND;
81 const RING_SPEC: RingSpec = EVENT_RING_SPEC;
82}
83
84#[derive(Clone, Debug, PartialEq, Eq)]
89pub struct OrbitEventCursor {
90 inner: FleetLaneCursor,
91}
92
93impl OrbitEventCursor {
94 pub const fn from_start() -> Self {
97 Self {
98 inner: FleetLaneCursor::from_counter(0),
99 }
100 }
101
102 pub const fn from_counter(next_counter: u64) -> Self {
104 Self {
105 inner: FleetLaneCursor::from_counter(next_counter),
106 }
107 }
108
109 pub fn next_counter(&self) -> u64 {
111 self.inner.minimum_next_counter()
112 }
113}
114
115#[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#[derive(Clone, Debug, Default, PartialEq, Eq)]
126pub struct OrbitEventPoll {
127 pub events: Vec<OrbitEvent>,
128 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#[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 pub fn cursor_at_head(&self) -> OrbitEventCursor {
158 OrbitEventCursor {
159 inner: self.fleet.lane_cursor_at_head::<OrbitEventRecord>(),
160 }
161 }
162
163 pub const fn cursor_from_start(&self) -> OrbitEventCursor {
166 let _ = self;
167 OrbitEventCursor::from_start()
168 }
169
170 pub fn reset_ring(&self) -> Result<()> {
177 self.fleet
178 .reset_ring::<OrbitEventRecord>()
179 .map_err(Error::Io)
180 }
181
182 #[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 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 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 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}