use std::marker::PhantomData;
use std::sync::Arc;
use bytes::{BufMut, Bytes, BytesMut};
#[cfg(any(
target_os = "linux",
target_os = "freebsd",
target_os = "macos"
))]
use orbit_core::RingEventFd;
use orbit_core::fleet::FleetLaneCursor;
use orbit_core::{Fleet, NetId64, NodeId, OrbitEpoch};
mod layout;
use layout::EventRecord;
pub use layout::{
DefaultEventLayout, EVENT_PAYLOAD_MAX, EVENT_RING_CAPACITY,
EVENT_RING_KIND, EVENT_RING_PAYLOAD_CAPACITY, EVENT_RING_SPEC, EventLayout,
};
pub type Result<T, E = Error> = std::result::Result<T, E>;
#[derive(Debug)]
pub enum Error {
FrameTooLarge { topic_len: usize, payload_len: usize, max_payload: usize },
Io(std::io::Error),
InvalidLayout(&'static str),
}
impl std::fmt::Display for Error {
fn fmt(
&self,
f: &mut std::fmt::Formatter<'_>,
) -> std::fmt::Result {
match self {
Self::FrameTooLarge { topic_len, payload_len, max_payload } => {
write!(
f,
"orbit event frame too large: topic_len={topic_len} payload_len={payload_len} max_payload={max_payload}"
)
}
Self::Io(error) => write!(f, "orbit event io error: {error}"),
Self::InvalidLayout(reason) => {
write!(f, "orbit event layout invalid: {reason}")
}
}
}
}
impl std::error::Error for Error {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
match self {
Self::Io(error) => Some(error),
Self::FrameTooLarge { .. } | Self::InvalidLayout(_) => None,
}
}
}
const HEADER_LEN: usize = 2 + 2 + 8;
const FRAME_KIND_EVENT: u8 = 1;
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct FleetEventCursor {
inner: FleetLaneCursor,
}
impl FleetEventCursor {
pub const fn from_start() -> Self {
Self { inner: FleetLaneCursor::from_counter(0) }
}
pub const fn from_counter(next_counter: u64) -> Self {
Self { inner: FleetLaneCursor::from_counter(next_counter) }
}
pub fn minimum_lane_next_counter(&self) -> u64 {
self.inner.minimum_lane_next_counter()
}
#[deprecated(
note = "use minimum_lane_next_counter; this is not a global cursor or checkpoint"
)]
pub fn next_counter(&self) -> u64 {
self.minimum_lane_next_counter()
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct FleetEvent {
pub id: NetId64,
pub topic: String,
pub payload: Vec<u8>,
pub timestamp_ms: u64,
}
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct FleetEventPoll {
pub events: Vec<FleetEvent>,
pub lagged: u64,
}
impl FleetEventPoll {
pub fn is_empty(&self) -> bool {
self.events.is_empty() && self.lagged == 0
}
}
pub struct FleetEventBus<L: EventLayout = DefaultEventLayout> {
fleet: Arc<Fleet>,
_layout: PhantomData<L>,
}
impl<L: EventLayout> Clone for FleetEventBus<L> {
fn clone(&self) -> Self {
Self { fleet: Arc::clone(&self.fleet), _layout: PhantomData }
}
}
impl FleetEventBus<DefaultEventLayout> {
pub fn new(fleet: Arc<Fleet>) -> Self {
Self { fleet, _layout: PhantomData }
}
}
impl<L: EventLayout> FleetEventBus<L> {
pub const PAYLOAD_MAX: usize = L::RING_SPEC.payload_capacity;
pub fn with_layout(fleet: Arc<Fleet>) -> Result<Self> {
layout::validate::<L>()?;
Ok(Self { fleet, _layout: PhantomData })
}
pub fn node_id(&self) -> NodeId {
self.fleet.node_id()
}
pub fn cursor_at_head(&self) -> FleetEventCursor {
FleetEventCursor {
inner: self.fleet.lane_cursor_at_head::<EventRecord<L>>(),
}
}
pub const fn cursor_from_start(&self) -> FleetEventCursor {
let _ = self;
FleetEventCursor::from_start()
}
pub fn reset_ring(&self) -> Result<()> {
self.fleet.reset_ring::<EventRecord<L>>().map_err(Error::Io)
}
#[cfg(any(
target_os = "linux",
target_os = "freebsd",
target_os = "macos"
))]
pub fn event_fd(&self) -> Result<RingEventFd> {
self.fleet.ring_event_fd::<EventRecord<L>>().map_err(Error::Io)
}
pub fn publish(
&self,
topic: &str,
payload: &[u8],
) -> Result<NetId64> {
let timestamp = OrbitEpoch::now();
let frame = encode_frame(
topic.as_bytes(),
payload,
timestamp,
Self::PAYLOAD_MAX,
)?;
#[cfg(any(
target_os = "linux",
target_os = "freebsd",
target_os = "macos"
))]
let id = self
.fleet
.publish_notified::<EventRecord<L>>(
FRAME_KIND_EVENT,
timestamp.as_unix_ms(),
frame,
)
.map_err(Error::Io)?;
#[cfg(not(any(
target_os = "linux",
target_os = "freebsd",
target_os = "macos"
)))]
let id = self.fleet.publish::<EventRecord<L>>(
FRAME_KIND_EVENT,
timestamp.as_unix_ms(),
frame,
);
Ok(id)
}
pub fn poll(
&self,
cursor: &mut FleetEventCursor,
) -> FleetEventPoll {
self.poll_where(cursor, |_| true)
}
fn poll_where(
&self,
cursor: &mut FleetEventCursor,
keep: impl Fn(&[u8]) -> bool,
) -> FleetEventPoll {
let ring_poll =
self.fleet.poll_lanes::<EventRecord<L>>(&mut cursor.inner);
let mut lagged = ring_poll.loss.total();
let mut events = Vec::new();
for frame in ring_poll.frames {
let Some(decoded) = decode_frame(&frame.payload) else {
lagged = lagged.saturating_add(1);
continue;
};
if !keep(decoded.topic) {
continue;
}
events.push(FleetEvent {
id: frame.id,
topic: String::from_utf8_lossy(decoded.topic).into_owned(),
payload: decoded.payload.to_vec(),
timestamp_ms: decoded.timestamp.as_unix_ms(),
});
}
FleetEventPoll { events, lagged }
}
pub fn poll_topic(
&self,
cursor: &mut FleetEventCursor,
topic: &str,
) -> FleetEventPoll {
self.poll_where(cursor, |candidate| candidate == topic.as_bytes())
}
}
struct DecodedFrame<'a> {
topic: &'a [u8],
payload: &'a [u8],
timestamp: OrbitEpoch,
}
fn encode_frame(
topic: &[u8],
payload: &[u8],
timestamp: OrbitEpoch,
max_payload: usize,
) -> Result<Bytes> {
let total = HEADER_LEN + topic.len() + payload.len();
if topic.len() > u16::MAX as usize
|| payload.len() > u16::MAX as usize
|| total > max_payload
{
return Err(Error::FrameTooLarge {
topic_len: topic.len(),
payload_len: payload.len(),
max_payload,
});
}
let mut buf = BytesMut::with_capacity(total);
buf.put_u16_le(topic.len() as u16);
buf.put_u16_le(payload.len() as u16);
buf.put_u64_le(timestamp.as_unix_ms());
buf.put_slice(topic);
buf.put_slice(payload);
Ok(buf.freeze())
}
fn decode_frame(payload: &Bytes) -> Option<DecodedFrame<'_>> {
if payload.len() < HEADER_LEN {
return None;
}
let topic_len = u16::from_le_bytes(payload[0..2].try_into().ok()?) as usize;
let payload_len =
u16::from_le_bytes(payload[2..4].try_into().ok()?) as usize;
let timestamp = OrbitEpoch::from_unix_ms(u64::from_le_bytes(
payload[4..12].try_into().ok()?,
));
let topic_start = HEADER_LEN;
let topic_end = topic_start.checked_add(topic_len)?;
let payload_end = topic_end.checked_add(payload_len)?;
if payload.len() < payload_end {
return None;
}
Some(DecodedFrame {
topic: &payload[topic_start..topic_end],
payload: &payload[topic_end..payload_end],
timestamp,
})
}
#[cfg(test)]
mod tests {
use std::sync::Arc;
use orbit_core::{Fleet, OrbitEpoch, RingSpec};
use super::{EventLayout, FleetEventBus};
struct WideLayout;
impl EventLayout for WideLayout {
const RING_KIND: u8 = 221;
const RING_SPEC: RingSpec = RingSpec::per_node(16, 8_192);
}
#[test]
fn polls_events_since_cursor() {
let fleet = Arc::new(Fleet::join("event_poll", 1).expect("fleet"));
let bus = FleetEventBus::new(fleet);
let mut cursor = bus.cursor_from_start();
bus.publish("worker.booted", b"w1").expect("publish first");
bus.publish("cache.reset", b"all").expect("publish second");
let poll = bus.poll(&mut cursor);
assert_eq!(poll.lagged, 0);
assert_eq!(poll.events.len(), 2);
assert_eq!(poll.events[0].topic, "worker.booted");
assert_eq!(poll.events[0].payload, b"w1");
assert_eq!(poll.events[1].topic, "cache.reset");
assert_eq!(poll.events[1].payload, b"all");
assert!(bus.poll(&mut cursor).is_empty());
}
#[test]
fn minimum_lane_next_counter_can_stay_zero_after_all_events_are_read() {
let fleet = Arc::new(Fleet::join("event_lane_min", 2).expect("fleet"));
let bus = FleetEventBus::new(fleet);
let mut cursor = bus.cursor_from_start();
for _ in 0..3 {
bus.publish("test.event", b"payload").expect("publish");
}
let poll = bus.poll(&mut cursor);
assert_eq!(poll.events.len(), 3);
assert_eq!(poll.lagged, 0);
assert_eq!(cursor.minimum_lane_next_counter(), 0);
assert!(bus.poll(&mut cursor).is_empty());
bus.publish("test.event", b"next").expect("publish");
let poll = bus.poll(&mut cursor);
assert_eq!(poll.events.len(), 1);
assert_eq!(poll.events[0].payload, b"next");
assert_eq!(poll.lagged, 0);
assert_eq!(cursor.minimum_lane_next_counter(), 0);
}
#[test]
fn cursor_at_head_only_reads_future_events() {
let fleet = Arc::new(Fleet::join("event_head", 1).expect("fleet"));
let bus = FleetEventBus::new(fleet);
bus.publish("old", b"ignored").expect("publish old");
let mut cursor = bus.cursor_at_head();
bus.publish("new", b"seen").expect("publish new");
let poll = bus.poll(&mut cursor);
assert_eq!(poll.events.len(), 1);
assert_eq!(poll.events[0].topic, "new");
}
#[test]
fn topic_filter_advances_cursor() {
let fleet = Arc::new(Fleet::join("event_topic", 1).expect("fleet"));
let bus = FleetEventBus::new(fleet);
let mut cursor = bus.cursor_from_start();
bus.publish("a", b"1").expect("publish a");
bus.publish("b", b"2").expect("publish b");
let poll = bus.poll_topic(&mut cursor, "b");
assert_eq!(poll.events.len(), 1);
assert_eq!(poll.events[0].payload, b"2");
assert!(bus.poll(&mut cursor).is_empty());
}
#[test]
fn event_frame_contract_uses_the_compile_time_geometry() {
let expected = orbit_core::compile::usize_from_env(
option_env!("ORBIT_EVENT_RING_PAYLOAD_CAPACITY"),
512,
);
assert_eq!(super::EVENT_PAYLOAD_MAX, expected);
let largest_payload =
vec![0_u8; super::EVENT_PAYLOAD_MAX - super::HEADER_LEN - 1];
let frame = super::encode_frame(
b"x",
&largest_payload,
OrbitEpoch::ZERO,
expected,
)
.expect("frame must fit");
assert_eq!(frame.len(), super::EVENT_PAYLOAD_MAX);
let oversized_payload = vec![0_u8; largest_payload.len() + 1];
assert!(matches!(
super::encode_frame(b"x", &oversized_payload, OrbitEpoch::ZERO, expected),
Err(super::Error::FrameTooLarge {
max_payload,
..
}) if max_payload == expected
));
}
#[test]
fn reports_lag_when_cursor_falls_behind_capacity() {
let fleet = Arc::new(Fleet::join("event_lag", 1).expect("fleet"));
let bus = FleetEventBus::new(fleet);
let mut cursor = bus.cursor_from_start();
for value in 0..=super::EVENT_RING_SPEC.capacity {
bus.publish("n", value.to_string().as_bytes())
.expect("publish event");
}
let poll = bus.poll(&mut cursor);
assert_eq!(poll.lagged, 1);
assert_eq!(poll.events.len(), super::EVENT_RING_SPEC.capacity);
assert_eq!(poll.events[0].payload, b"1");
}
#[test]
fn a_second_layout_is_a_separate_ring_with_its_own_frame_size() {
let fleet = Arc::new(Fleet::join("event_layout", 1).expect("fleet"));
let fleet_bus = FleetEventBus::new(Arc::clone(&fleet));
let wide_bus =
FleetEventBus::<WideLayout>::with_layout(fleet).expect("layout");
let mut fleet_cursor = fleet_bus.cursor_from_start();
let mut wide_cursor = wide_bus.cursor_from_start();
let wide_payload = vec![7_u8; super::EVENT_PAYLOAD_MAX];
assert!(fleet_bus.publish("wide", &wide_payload).is_err());
wide_bus.publish("wide", &wide_payload).expect("wide frame fits");
fleet_bus.publish("small", b"1").expect("small frame fits");
let wide = wide_bus.poll(&mut wide_cursor);
assert_eq!(wide.events.len(), 1);
assert_eq!(wide.events[0].payload, wide_payload);
let small = fleet_bus.poll(&mut fleet_cursor);
assert_eq!(small.events.len(), 1);
assert_eq!(small.events[0].topic, "small");
}
}