use core::fmt;
use astrs_time::HlcTimestamp;
use oxicode::{Decode, Encode};
use serde::{Deserialize, Serialize};
use crate::common::route::{RouteAcceptance, RouteCloseReason, RouteSpec};
use crate::frame::FrameKind;
use crate::ids::{RouteId, TypeUrn};
use crate::messages::impl_wire_message;
use crate::metadata::Metadata;
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Encode, Decode)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum PeerEvent {
#[oxicode(variant = 0)]
RouteSetup {
route_id: RouteId,
route: RouteSpec,
generation: u64,
type_urn: Option<TypeUrn>,
max_payload_bytes: u64,
pool_hint_bytes: Option<u64>,
},
#[oxicode(variant = 1)]
RouteAccept {
route_id: RouteId,
acceptance: RouteAcceptance,
},
#[oxicode(variant = 2)]
RouteTeardown {
route_id: RouteId,
reason: RouteCloseReason,
},
#[oxicode(variant = 3)]
Output {
route_id: RouteId,
seq: u64,
metadata: Metadata,
payload: Vec<u8>,
},
#[oxicode(variant = 4)]
OutputClosed {
route_id: RouteId,
final_seq: u64,
reason: RouteCloseReason,
},
#[oxicode(variant = 5)]
Ping {
nonce: u64,
sent_at: HlcTimestamp,
is_reply: bool,
},
}
impl PeerEvent {
#[must_use]
pub const fn ping(nonce: u64, sent_at: HlcTimestamp) -> Self {
Self::Ping {
nonce,
sent_at,
is_reply: false,
}
}
#[must_use]
pub const fn pong(&self) -> Option<Self> {
match self {
Self::Ping {
nonce,
sent_at,
is_reply: false,
} => Some(Self::Ping {
nonce: *nonce,
sent_at: *sent_at,
is_reply: true,
}),
_ => None,
}
}
#[must_use]
pub const fn route_id(&self) -> Option<RouteId> {
match self {
Self::RouteSetup { route_id, .. }
| Self::RouteAccept { route_id, .. }
| Self::RouteTeardown { route_id, .. }
| Self::Output { route_id, .. }
| Self::OutputClosed { route_id, .. } => Some(*route_id),
Self::Ping { .. } => None,
}
}
#[must_use]
pub const fn is_payload(&self) -> bool {
matches!(self, Self::Output { .. })
}
#[must_use]
pub fn payload(&self) -> Option<&[u8]> {
match self {
Self::Output { payload, .. } => Some(payload),
_ => None,
}
}
#[must_use]
pub fn payload_len(&self) -> usize {
self.payload().map_or(0, <[u8]>::len)
}
#[must_use]
pub const fn is_terminal(&self) -> bool {
matches!(self, Self::RouteTeardown { .. } | Self::OutputClosed { .. })
}
#[must_use]
pub fn bitwise_eq(&self, other: &Self) -> bool {
match (self, other) {
(
Self::Output {
route_id: left_route,
seq: left_seq,
metadata: left_meta,
payload: left_payload,
},
Self::Output {
route_id: right_route,
seq: right_seq,
metadata: right_meta,
payload: right_payload,
},
) => {
left_route == right_route
&& left_seq == right_seq
&& left_meta.bitwise_eq(right_meta)
&& left_payload == right_payload
}
_ => self == other,
}
}
}
impl fmt::Display for PeerEvent {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::RouteSetup {
route_id, route, ..
} => write!(f, "route setup {route_id} for {}", route.key),
Self::RouteAccept {
route_id,
acceptance,
} => write!(f, "route {route_id} {acceptance}"),
Self::RouteTeardown { route_id, reason } => {
write!(f, "route {route_id} torn down: {reason}")
}
Self::Output {
route_id,
seq,
payload,
..
} => write!(
f,
"route {route_id} output #{seq} ({} bytes)",
payload.len()
),
Self::OutputClosed {
route_id,
final_seq,
reason,
} => write!(
f,
"route {route_id} output closed after #{final_seq}: {reason}"
),
Self::Ping {
nonce, is_reply, ..
} => {
if *is_reply {
write!(f, "pong {nonce}")
} else {
write!(f, "ping {nonce}")
}
}
}
}
}
impl_wire_message!(
PeerEvent,
FrameKind::PeerEvent,
[
"RouteSetup",
"RouteAccept",
"RouteTeardown",
"Output",
"OutputClosed",
"Ping",
],
fn variant_index(&self) -> u16 {
match self {
Self::RouteSetup { .. } => 0,
Self::RouteAccept { .. } => 1,
Self::RouteTeardown { .. } => 2,
Self::Output { .. } => 3,
Self::OutputClosed { .. } => 4,
Self::Ping { .. } => 5,
}
}
);
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
use crate::codec::{WireDecode, WireEncode, round_trip};
use crate::common::route::{RouteKey, RouteRejection};
use crate::common::{Plane, RouteSpec};
use crate::frame::{Compression, FrameFlags, FrameLimits};
use crate::ids::DataflowId;
use crate::messages::WireMessage;
fn route_key() -> RouteKey {
RouteKey::new(
DataflowId::from_u128(0x11),
"camera/image".parse().unwrap(),
"detector/frames".parse().unwrap(),
)
}
fn samples() -> Vec<PeerEvent> {
vec![
PeerEvent::RouteSetup {
route_id: RouteId::FIRST,
route: RouteSpec::new(route_key()).with_plane(Plane::Quic),
generation: 3,
type_urn: Some(TypeUrn::new("std/media/v1/Image").unwrap()),
max_payload_bytes: 1 << 20,
pool_hint_bytes: Some(8 << 20),
},
PeerEvent::RouteAccept {
route_id: RouteId::FIRST,
acceptance: RouteAcceptance::accepted(Plane::Quic, Compression::Lz4, 1 << 20),
},
PeerEvent::RouteTeardown {
route_id: RouteId::FIRST,
reason: RouteCloseReason::DataflowStopped,
},
PeerEvent::Output {
route_id: RouteId::FIRST,
seq: 42,
metadata: Metadata::new(HlcTimestamp::new(9, 1)),
payload: vec![7; 16],
},
PeerEvent::OutputClosed {
route_id: RouteId::FIRST,
final_seq: 42,
reason: RouteCloseReason::ProducerFinished,
},
PeerEvent::ping(0xFEED, HlcTimestamp::new(1, 0)),
]
}
#[test]
fn the_family_has_exactly_the_frozen_variants() {
assert_eq!(PeerEvent::VARIANT_NAMES.len(), 6);
assert_eq!(
PeerEvent::VARIANT_NAMES,
&[
"RouteSetup",
"RouteAccept",
"RouteTeardown",
"Output",
"OutputClosed",
"Ping",
]
);
}
#[test]
fn every_variant_reports_and_encodes_its_frozen_index() {
let samples = samples();
assert_eq!(samples.len(), PeerEvent::VARIANT_NAMES.len());
for (index, sample) in samples.iter().enumerate() {
let index = u16::try_from(index).unwrap();
assert_eq!(sample.variant_index(), index, "{sample:?}");
let bytes = sample.encode_to_vec().unwrap();
assert_eq!(u16::from(bytes[0]), index, "{sample:?}");
assert_eq!(
sample.variant_name(),
PeerEvent::VARIANT_NAMES[usize::from(index)]
);
}
}
#[test]
fn every_variant_round_trips() {
for sample in samples() {
assert_eq!(round_trip(&sample).unwrap(), sample);
}
}
#[test]
fn every_variant_round_trips_through_a_frame() {
let limits = FrameLimits::network();
for sample in samples() {
let bytes = sample.to_frame(FrameFlags::CRC, &limits).unwrap();
assert_eq!(PeerEvent::from_bytes(&bytes, &limits).unwrap(), sample);
}
}
#[test]
fn trailing_bytes_after_a_payload_are_refused() {
for sample in samples() {
let mut bytes = sample.encode_to_vec().unwrap();
bytes.push(0);
assert!(matches!(
PeerEvent::decode_exact(&bytes),
Err(crate::error::WireError::TrailingBytes { .. })
));
}
}
#[test]
fn route_accessors_answer_for_every_variant() {
for sample in samples() {
match &sample {
PeerEvent::Ping { .. } => assert!(sample.route_id().is_none()),
_ => assert_eq!(sample.route_id(), Some(RouteId::FIRST)),
}
}
}
#[test]
fn only_output_carries_payload() {
for sample in samples() {
if matches!(sample, PeerEvent::Output { .. }) {
assert!(sample.is_payload());
assert_eq!(sample.payload_len(), 16);
} else {
assert!(!sample.is_payload());
assert_eq!(sample.payload_len(), 0);
assert!(sample.payload().is_none());
}
}
}
#[test]
fn terminal_events_are_the_two_closing_ones() {
let terminal: Vec<&'static str> = samples()
.iter()
.filter(|event| event.is_terminal())
.map(PeerEvent::variant_name)
.collect();
assert_eq!(terminal, vec!["RouteTeardown", "OutputClosed"]);
}
#[test]
fn a_probe_echoes_once_and_only_once() {
let probe = PeerEvent::ping(9, HlcTimestamp::new(4, 2));
let echo = probe.pong().unwrap();
match echo {
PeerEvent::Ping {
nonce,
sent_at,
is_reply,
} => {
assert_eq!(nonce, 9);
assert_eq!(sent_at, HlcTimestamp::new(4, 2));
assert!(is_reply);
}
other => panic!("expected a Ping, got {other:?}"),
}
assert!(probe.pong().unwrap().pong().is_none());
assert!(
PeerEvent::RouteTeardown {
route_id: RouteId::FIRST,
reason: RouteCloseReason::ConsumerGone,
}
.pong()
.is_none()
);
}
#[test]
fn rejections_round_trip_with_their_causes() {
let rejections = [
RouteRejection::UnknownDataflow,
RouteRejection::UnknownPort {
port: "detector/frames".parse().unwrap(),
},
RouteRejection::TypeMismatch {
expected: Some(TypeUrn::new("std/media/v1/Image").unwrap()),
found: None,
},
RouteRejection::PlaneUnavailable { plane: Plane::Shm },
RouteRejection::PayloadTooLarge { limit: 1024 },
RouteRejection::Unauthorized,
RouteRejection::ShuttingDown,
RouteRejection::Duplicate {
route_id: RouteId::new(2),
},
RouteRejection::Other {
message: "no".to_owned(),
},
];
for (index, reason) in rejections.into_iter().enumerate() {
let event = PeerEvent::RouteAccept {
route_id: RouteId::FIRST,
acceptance: RouteAcceptance::Rejected {
reason: reason.clone(),
},
};
assert_eq!(round_trip(&event).unwrap(), event);
let bytes = reason.encode_to_vec().unwrap();
assert_eq!(usize::from(bytes[0]), index, "{reason:?}");
}
}
#[test]
fn close_reasons_round_trip_with_their_causes() {
let reasons = [
RouteCloseReason::ProducerFinished,
RouteCloseReason::ProducerCrashed { generation: 4 },
RouteCloseReason::ConsumerGone,
RouteCloseReason::DataflowStopped,
RouteCloseReason::PlaneFailed {
plane: Plane::Tcp,
message: "reset".to_owned(),
},
RouteCloseReason::Superseded {
route_id: RouteId::new(5),
},
RouteCloseReason::DaemonShutdown,
RouteCloseReason::Error {
message: "boom".to_owned(),
},
];
for (index, reason) in reasons.into_iter().enumerate() {
let bytes = reason.encode_to_vec().unwrap();
assert_eq!(usize::from(bytes[0]), index, "{reason:?}");
assert_eq!(round_trip(&reason).unwrap(), reason);
}
}
#[test]
fn nan_metadata_survives_the_wire_even_though_it_is_not_partial_eq() {
let mut metadata = Metadata::new(HlcTimestamp::new(1, 0));
metadata.insert("nan", f64::NAN).unwrap();
let event = PeerEvent::Output {
route_id: RouteId::FIRST,
seq: 0,
metadata,
payload: vec![1],
};
let decoded = round_trip(&event).unwrap();
assert_ne!(decoded, event);
assert!(decoded.bitwise_eq(&event));
}
#[test]
fn display_names_every_variant_without_panicking() {
for sample in samples() {
let text = sample.to_string();
assert!(!text.is_empty(), "{sample:?} rendered empty");
}
}
#[test]
fn a_large_output_stays_within_the_frame_limit() {
let limits = FrameLimits::network();
let event = PeerEvent::Output {
route_id: RouteId::FIRST,
seq: 1,
metadata: Metadata::new(HlcTimestamp::new(1, 0)),
payload: vec![0x5A; 1 << 16],
};
let bytes = event.to_frame(FrameFlags::CRC, &limits).unwrap();
assert_eq!(PeerEvent::from_bytes(&bytes, &limits).unwrap(), event);
}
#[test]
fn an_output_over_the_limit_is_refused_before_encoding() {
let tight = FrameLimits::uds().with_max_payload_bytes(64);
let event = PeerEvent::Output {
route_id: RouteId::FIRST,
seq: 1,
metadata: Metadata::new(HlcTimestamp::new(1, 0)),
payload: vec![0; 1024],
};
assert!(matches!(
event.to_frame(FrameFlags::EMPTY, &tight),
Err(crate::error::WireError::FrameTooLarge { .. })
));
}
#[test]
fn serde_round_trips_the_family_for_diagnostics() {
for sample in samples() {
let json = serde_json::to_string(&sample).unwrap();
let back: PeerEvent = serde_json::from_str(&json).unwrap();
assert_eq!(back, sample);
}
}
}