use evento_core::cursor::{Args, PageInfo, Value};
use evento_core::{Event, EventFilter, RoutingKey, TenantFilter, WriteError};
use serde::{de::DeserializeOwned, Deserialize, Serialize};
use ulid::Ulid;
pub const MAGIC: [u8; 2] = *b"Er";
pub const FORMAT_VERSION: u8 = 6;
const HEADER_LEN: usize = 4;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum RecordKind {
ClientFrame = 1,
ServerFrame = 2,
}
impl RecordKind {
fn from_byte(b: u8) -> Option<Self> {
match b {
1 => Some(Self::ClientFrame),
2 => Some(Self::ServerFrame),
_ => None,
}
}
}
pub const MAX_FRAME_LENGTH: usize = 64 * 1024 * 1024;
pub fn encode_tagged<T: Serialize>(kind: RecordKind, value: &T) -> anyhow::Result<Vec<u8>> {
let payload = bitcode::serialize(value)?;
let mut out = Vec::with_capacity(HEADER_LEN + payload.len());
out.extend_from_slice(&MAGIC);
out.push(FORMAT_VERSION);
out.push(kind as u8);
out.extend_from_slice(&payload);
Ok(out)
}
pub fn decode_tagged<T: DeserializeOwned>(expected: RecordKind, bytes: &[u8]) -> anyhow::Result<T> {
if bytes.len() < HEADER_LEN {
anyhow::bail!("frame too short: {} bytes", bytes.len());
}
if bytes[0..2] != MAGIC {
anyhow::bail!("bad frame magic");
}
let version = bytes[2];
if version != FORMAT_VERSION {
anyhow::bail!(
"unsupported wire format version {version} (this build speaks {FORMAT_VERSION})"
);
}
let kind = RecordKind::from_byte(bytes[3])
.ok_or_else(|| anyhow::anyhow!("unknown frame kind {}", bytes[3]))?;
if kind != expected {
anyhow::bail!("frame kind mismatch: expected {expected:?}, found {kind:?}");
}
Ok(bitcode::deserialize(&bytes[HEADER_LEN..])?)
}
#[derive(Debug, Serialize, Deserialize)]
pub enum ClientFrame {
Request {
id: u64,
request: Request,
},
Watch {
watch: u64,
filters: Option<Vec<EventFilter>>,
routing_key: Option<RoutingKey>,
tenant: TenantFilter,
},
Unwatch {
watch: u64,
},
}
#[derive(Debug, Serialize, Deserialize)]
pub enum ServerFrame {
Response {
id: u64,
response: Response,
stable_timestamp: Option<u64>,
},
Notify {
watches: Vec<u64>,
stable_timestamp: Option<u64>,
},
}
#[derive(Debug, Serialize, Deserialize)]
pub enum Request {
Hello {
token: Option<Token>,
},
Write {
#[serde(with = "wire_events")]
events: Vec<Event>,
},
Replicate {
#[serde(with = "wire_events")]
events: Vec<Event>,
},
Read {
aggregators: Option<Vec<EventFilter>>,
routing_key: Option<RoutingKey>,
tenant: TenantFilter,
args: Args,
to_micros: Option<u64>,
},
LatestTimestamp {
aggregators: Option<Vec<EventFilter>>,
routing_key: Option<RoutingKey>,
tenant: TenantFilter,
},
GetSubscriberCursor {
key: String,
},
IsSubscriberRunning {
key: String,
worker_id: Ulid,
},
SubscriberStatus {
key: String,
worker_id: Ulid,
},
LatestVersion {
tenant: String,
aggregate_type: String,
aggregate_id: String,
},
StreamRoutingKey {
tenant: String,
aggregate_type: String,
aggregate_id: String,
},
UpsertSubscriber {
key: String,
worker_id: Ulid,
},
Acknowledge {
key: String,
worker_id: Ulid,
cursor: Value,
lag: u64,
},
GetSnapshot {
tenant: String,
aggregate_type: String,
projection: String,
aggregate_revision: String,
id: String,
},
SaveSnapshot {
tenant: String,
aggregate_type: String,
projection: String,
aggregate_revision: String,
id: String,
data: Vec<u8>,
cursor: Value,
},
DeleteSnapshot {
tenant: String,
aggregate_type: String,
projection: String,
id: String,
},
}
#[derive(Debug, Serialize, Deserialize)]
pub enum Response {
Hello(Result<HelloOk, Rejection>),
Write(Result<(), WireWriteError>),
Read(Result<WireReadResult, String>),
LatestTimestamp(Result<u64, String>),
SubscriberCursor(Result<Option<Value>, String>),
SubscriberRunning(Result<bool, String>),
SubscriberStatus(Result<evento_core::SubscriberStatus, String>),
LatestVersion(Result<u16, String>),
StreamRoutingKey(Result<Option<Option<String>>, String>),
Acknowledge(Result<bool, String>),
Unit(Result<(), String>),
Snapshot(Result<Option<(Vec<u8>, Value)>, String>),
}
#[derive(Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct Token(pub String);
impl std::fmt::Debug for Token {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str("Token(******)")
}
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct HelloOk {
pub default_routing_key: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub enum Rejection {
Unauthorized,
Unavailable(String),
}
impl std::fmt::Display for Rejection {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Rejection::Unauthorized => f.write_str("unauthorized"),
Rejection::Unavailable(reason) => write!(f, "unavailable: {reason}"),
}
}
}
impl std::error::Error for Rejection {}
#[derive(Debug, Serialize, Deserialize)]
pub struct WireReadResult {
pub cursors: Vec<Value>,
#[serde(with = "wire_events")]
pub events: Vec<Event>,
pub page_info: PageInfo,
}
impl From<evento_core::cursor::ReadResult<Event>> for WireReadResult {
fn from(result: evento_core::cursor::ReadResult<Event>) -> Self {
let (cursors, events) = result.edges.into_iter().map(|e| (e.cursor, e.node)).unzip();
WireReadResult {
cursors,
events,
page_info: result.page_info,
}
}
}
impl From<WireReadResult> for evento_core::cursor::ReadResult<Event> {
fn from(wire: WireReadResult) -> Self {
evento_core::cursor::ReadResult {
edges: wire
.cursors
.into_iter()
.zip(wire.events)
.map(|(cursor, node)| evento_core::cursor::Edge { cursor, node })
.collect(),
page_info: wire.page_info,
}
}
}
#[derive(Debug, Serialize, Deserialize)]
pub enum WireWriteError {
InvalidOriginalVersion,
MissingData,
Other(String),
Unavailable(String),
}
impl From<&WriteError> for WireWriteError {
fn from(e: &WriteError) -> Self {
match e {
WriteError::InvalidOriginalVersion => WireWriteError::InvalidOriginalVersion,
WriteError::MissingData => WireWriteError::MissingData,
WriteError::Unavailable(cause) => WireWriteError::Unavailable(cause.to_string()),
other => WireWriteError::Other(other.to_string()),
}
}
}
impl From<WireWriteError> for WriteError {
fn from(e: WireWriteError) -> Self {
match e {
WireWriteError::InvalidOriginalVersion => WriteError::InvalidOriginalVersion,
WireWriteError::MissingData => WriteError::MissingData,
WireWriteError::Other(msg) => WriteError::Unknown(anyhow::anyhow!(msg)),
WireWriteError::Unavailable(cause) => WriteError::Unavailable(anyhow::anyhow!(cause)),
}
}
}
mod wire_events {
use evento_core::{metadata::Metadata, Event};
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use ulid::Ulid;
#[derive(Serialize, Deserialize)]
struct WireEvent {
id: Ulid,
aggregate_id: String,
aggregate_type: String,
version: u16,
name: String,
routing_key: Option<String>,
tenant: String,
data: Vec<u8>,
metadata: Vec<u8>,
timestamp: u64,
timestamp_subsec: u32,
}
impl From<&Event> for WireEvent {
fn from(e: &Event) -> Self {
WireEvent {
id: e.id,
aggregate_id: e.aggregate_id.clone(),
aggregate_type: e.aggregate_type.clone(),
version: e.version,
name: e.name.clone(),
routing_key: e.routing_key.clone(),
tenant: e.tenant.clone(),
data: e.data.clone(),
metadata: bitcode::encode(&e.metadata),
timestamp: e.timestamp,
timestamp_subsec: e.timestamp_subsec,
}
}
}
impl TryFrom<WireEvent> for Event {
type Error = bitcode::Error;
fn try_from(w: WireEvent) -> Result<Self, Self::Error> {
Ok(Event {
id: w.id,
aggregate_id: w.aggregate_id,
aggregate_type: w.aggregate_type,
version: w.version,
name: w.name,
routing_key: w.routing_key,
tenant: w.tenant,
data: w.data,
metadata: bitcode::decode::<Metadata>(&w.metadata)?,
timestamp: w.timestamp,
timestamp_subsec: w.timestamp_subsec,
})
}
}
pub fn serialize<S: Serializer>(events: &[Event], s: S) -> Result<S::Ok, S::Error> {
let wire: Vec<WireEvent> = events.iter().map(WireEvent::from).collect();
wire.serialize(s)
}
pub fn deserialize<'de, D: Deserializer<'de>>(d: D) -> Result<Vec<Event>, D::Error> {
Vec::<WireEvent>::deserialize(d)?
.into_iter()
.map(|w| Event::try_from(w).map_err(serde::de::Error::custom))
.collect()
}
}
#[cfg(test)]
mod tests {
use super::*;
use evento_core::metadata::Metadata;
fn sample_event() -> Event {
let mut metadata = Metadata::default();
metadata.set_requested_by("tester");
Event {
id: Ulid::generate(),
aggregate_id: "agg-1".to_owned(),
aggregate_type: "account".to_owned(),
version: 7,
name: "opened".to_owned(),
routing_key: Some("eu".to_owned()),
tenant: "acme".to_owned(),
data: vec![1, 2, 3],
metadata,
timestamp: 1_700_000_000,
timestamp_subsec: 42,
}
}
#[test]
fn round_trips_each_kind() {
for kind in [RecordKind::ClientFrame, RecordKind::ServerFrame] {
let value = (42u64, "hello".to_string());
let bytes = encode_tagged(kind, &value).unwrap();
let back: (u64, String) = decode_tagged(kind, &bytes).unwrap();
assert_eq!(back, value);
}
}
#[test]
fn rejects_bad_magic() {
let mut bytes = encode_tagged(RecordKind::ClientFrame, &7u64).unwrap();
bytes[0] = b'X';
let err = decode_tagged::<u64>(RecordKind::ClientFrame, &bytes).unwrap_err();
assert!(err.to_string().contains("magic"));
}
#[test]
fn rejects_unknown_version() {
let mut bytes = encode_tagged(RecordKind::ClientFrame, &7u64).unwrap();
bytes[2] = FORMAT_VERSION + 1;
let err = decode_tagged::<u64>(RecordKind::ClientFrame, &bytes).unwrap_err();
assert!(err.to_string().contains("format version"));
}
#[test]
fn rejects_kind_mismatch() {
let bytes = encode_tagged(RecordKind::ClientFrame, &7u64).unwrap();
let err = decode_tagged::<u64>(RecordKind::ServerFrame, &bytes).unwrap_err();
assert!(err.to_string().contains("kind mismatch"));
}
#[test]
fn rejects_truncated_input() {
let bytes = [b'E', b'r', FORMAT_VERSION]; let err = decode_tagged::<u64>(RecordKind::ClientFrame, &bytes).unwrap_err();
assert!(err.to_string().contains("too short"));
}
#[test]
fn event_round_trip() {
let event = sample_event();
let frame = ClientFrame::Request {
id: 9,
request: Request::Write {
events: vec![event.clone()],
},
};
let bytes = encode_tagged(RecordKind::ClientFrame, &frame).unwrap();
let back: ClientFrame = decode_tagged(RecordKind::ClientFrame, &bytes).unwrap();
let ClientFrame::Request {
id,
request: Request::Write { events },
} = back
else {
panic!("wrong frame");
};
assert_eq!(id, 9);
assert_eq!(events, vec![event]);
}
#[test]
fn watch_round_trip() {
let frame = ClientFrame::Watch {
watch: 3,
filters: Some(vec![EventFilter::by_event_raw("account", "opened")]),
routing_key: Some(RoutingKey::Value(Some("eu".to_owned()))),
tenant: TenantFilter::Only("acme".to_owned()),
};
let bytes = encode_tagged(RecordKind::ClientFrame, &frame).unwrap();
let back: ClientFrame = decode_tagged(RecordKind::ClientFrame, &bytes).unwrap();
let ClientFrame::Watch {
watch,
filters,
routing_key,
tenant,
} = back
else {
panic!("wrong frame");
};
assert_eq!(watch, 3);
assert_eq!(
filters,
Some(vec![EventFilter::by_event_raw("account", "opened")])
);
assert!(matches!(
routing_key,
Some(RoutingKey::Value(Some(key))) if key == "eu"
));
assert_eq!(tenant, TenantFilter::Only("acme".to_owned()));
let frame = ServerFrame::Notify {
watches: vec![3, 7],
stable_timestamp: Some(9),
};
let bytes = encode_tagged(RecordKind::ServerFrame, &frame).unwrap();
let back: ServerFrame = decode_tagged(RecordKind::ServerFrame, &bytes).unwrap();
assert!(matches!(
back,
ServerFrame::Notify { watches, stable_timestamp: Some(9) } if watches == [3, 7]
));
}
#[test]
fn hello_round_trip() {
let hello = ClientFrame::Request {
id: 0,
request: Request::Hello {
token: Some(Token("secret".to_owned())),
},
};
let bytes = encode_tagged(RecordKind::ClientFrame, &hello).unwrap();
let back: ClientFrame = decode_tagged(RecordKind::ClientFrame, &bytes).unwrap();
let ClientFrame::Request {
request: Request::Hello { token: Some(token) },
..
} = back
else {
panic!("wrong frame");
};
assert_eq!(token.0, "secret");
assert!(!format!("{token:?}").contains("secret"), "{token:?}");
for response in [
Response::Hello(Ok(HelloOk {
default_routing_key: Some("eu".to_owned()),
})),
Response::Hello(Err(Rejection::Unavailable("down".to_owned()))),
] {
let frame = ServerFrame::Response {
id: 0,
response,
stable_timestamp: None,
};
let bytes = encode_tagged(RecordKind::ServerFrame, &frame).unwrap();
let back: ServerFrame = decode_tagged(RecordKind::ServerFrame, &bytes).unwrap();
let ServerFrame::Response {
response: Response::Hello(reply),
..
} = back
else {
panic!("wrong frame");
};
match reply {
Ok(ok) => assert_eq!(ok.default_routing_key.as_deref(), Some("eu")),
Err(err) => assert_eq!(err.to_string(), "unavailable: down"),
}
}
}
#[test]
fn read_result_round_trip() {
let event = sample_event();
let read = evento_core::cursor::ReadResult {
edges: vec![evento_core::cursor::Edge {
cursor: Value("cur".to_owned()),
node: event,
}],
page_info: PageInfo {
has_previous_page: true,
has_next_page: false,
start_cursor: Some(Value("cur".to_owned())),
end_cursor: Some(Value("cur".to_owned())),
},
};
let wire = WireReadResult::from(read.clone());
let bytes = bitcode::serialize(&wire).unwrap();
let back: WireReadResult = bitcode::deserialize(&bytes).unwrap();
assert_eq!(evento_core::cursor::ReadResult::<Event>::from(back), read);
}
#[test]
fn write_error_round_trip() {
let cases = [
WriteError::InvalidOriginalVersion,
WriteError::MissingData,
WriteError::Unknown(anyhow::anyhow!("boom")),
WriteError::Unavailable(anyhow::anyhow!("backlog at cap")),
];
for original in cases {
let wire = WireWriteError::from(&original);
let bytes = bitcode::serialize(&wire).unwrap();
let back: WireWriteError = bitcode::deserialize(&bytes).unwrap();
let back = WriteError::from(back);
assert_eq!(back.to_string(), original.to_string(), "message fidelity");
assert_eq!(
matches!(back, WriteError::Unavailable(_)),
matches!(original, WriteError::Unavailable(_)),
"a transient refusal stays one across the wire"
);
}
}
}