use core::fmt;
use oxicode::{Decode, Encode};
use serde::{Deserialize, Serialize};
use crate::common::node::QueuePolicy;
use crate::frame::Compression;
use crate::ids::{DataflowId, PortRef};
pub const COMPRESSION_THRESHOLD_BYTES: u64 = 16 * 1024;
#[derive(
Debug,
Clone,
Copy,
Default,
PartialEq,
Eq,
PartialOrd,
Ord,
Hash,
Serialize,
Deserialize,
Encode,
Decode,
)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum Plane {
#[default]
#[oxicode(variant = 0)]
Uds,
#[oxicode(variant = 1)]
Shm,
#[oxicode(variant = 2)]
Tcp,
#[oxicode(variant = 3)]
Quic,
}
impl Plane {
pub const ALL: &'static [Self] = &[Self::Uds, Self::Shm, Self::Tcp, Self::Quic];
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Uds => "uds",
Self::Shm => "shm",
Self::Tcp => "tcp",
Self::Quic => "quic",
}
}
#[must_use]
pub const fn is_zero_copy(self) -> bool {
matches!(self, Self::Shm)
}
#[must_use]
pub const fn is_remote(self) -> bool {
matches!(self, Self::Tcp | Self::Quic)
}
#[must_use]
pub const fn needs_crc(self) -> bool {
self.is_remote()
}
#[must_use]
pub const fn allows_compression(self) -> bool {
self.is_remote()
}
}
impl fmt::Display for Plane {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
#[derive(
Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, Encode, Decode,
)]
pub struct RouteKey {
pub dataflow: DataflowId,
pub producer: PortRef,
pub consumer: PortRef,
}
impl RouteKey {
#[must_use]
pub const fn new(dataflow: DataflowId, producer: PortRef, consumer: PortRef) -> Self {
Self {
dataflow,
producer,
consumer,
}
}
}
impl fmt::Display for RouteKey {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}:{}->{}", self.dataflow, self.producer, self.consumer)
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Encode, Decode)]
pub struct RouteSpec {
pub key: RouteKey,
pub plane: Plane,
pub compression: Compression,
pub queue_size: u32,
pub queue_policy: QueuePolicy,
pub segment: Option<String>,
}
impl RouteSpec {
#[must_use]
pub fn new(key: RouteKey) -> Self {
Self {
key,
plane: Plane::Uds,
compression: Compression::None,
queue_size: crate::common::node::DEFAULT_QUEUE_SIZE,
queue_policy: QueuePolicy::DropOldest,
segment: None,
}
}
#[must_use]
pub const fn with_plane(mut self, plane: Plane) -> Self {
self.plane = plane;
self
}
#[must_use]
pub const fn with_compression(mut self, compression: Compression) -> Self {
self.compression = compression;
self
}
#[must_use]
pub fn with_segment(mut self, segment: impl Into<String>) -> Self {
self.segment = Some(segment.into());
self
}
#[must_use]
pub const fn compression_applies_to(&self, len: u64) -> bool {
self.compression.is_enabled()
&& self.plane.allows_compression()
&& len >= COMPRESSION_THRESHOLD_BYTES
}
#[must_use]
pub const fn is_upgraded(&self) -> bool {
self.plane.is_zero_copy()
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Encode, Decode)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum RouteAcceptance {
#[oxicode(variant = 0)]
Accepted {
plane: Plane,
compression: Compression,
max_payload_bytes: u64,
},
#[oxicode(variant = 1)]
Rejected {
reason: RouteRejection,
},
}
impl RouteAcceptance {
#[must_use]
pub const fn accepted(plane: Plane, compression: Compression, max_payload_bytes: u64) -> Self {
Self::Accepted {
plane,
compression,
max_payload_bytes,
}
}
#[must_use]
pub const fn is_accepted(&self) -> bool {
matches!(self, Self::Accepted { .. })
}
#[must_use]
pub const fn plane(&self) -> Option<Plane> {
match self {
Self::Accepted { plane, .. } => Some(*plane),
Self::Rejected { .. } => None,
}
}
#[must_use]
pub const fn compression(&self) -> Option<Compression> {
match self {
Self::Accepted { compression, .. } => Some(*compression),
Self::Rejected { .. } => None,
}
}
#[must_use]
pub const fn max_payload_bytes(&self) -> Option<u64> {
match self {
Self::Accepted {
max_payload_bytes, ..
} => Some(*max_payload_bytes),
Self::Rejected { .. } => None,
}
}
#[must_use]
pub const fn rejection(&self) -> Option<&RouteRejection> {
match self {
Self::Accepted { .. } => None,
Self::Rejected { reason } => Some(reason),
}
}
}
impl fmt::Display for RouteAcceptance {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Accepted {
plane,
compression,
max_payload_bytes,
} => write!(
f,
"accepted on {plane} (compression {compression}, ≤ {max_payload_bytes} B)"
),
Self::Rejected { reason } => write!(f, "rejected: {reason}"),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Encode, Decode)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum RouteRejection {
#[oxicode(variant = 0)]
UnknownDataflow,
#[oxicode(variant = 1)]
UnknownPort {
port: PortRef,
},
#[oxicode(variant = 2)]
TypeMismatch {
expected: Option<crate::ids::TypeUrn>,
found: Option<crate::ids::TypeUrn>,
},
#[oxicode(variant = 3)]
PlaneUnavailable {
plane: Plane,
},
#[oxicode(variant = 4)]
PayloadTooLarge {
limit: u64,
},
#[oxicode(variant = 5)]
Unauthorized,
#[oxicode(variant = 6)]
ShuttingDown,
#[oxicode(variant = 7)]
Duplicate {
route_id: crate::ids::RouteId,
},
#[oxicode(variant = 8)]
Other {
message: String,
},
}
impl RouteRejection {
#[must_use]
pub const fn is_transient(&self) -> bool {
matches!(
self,
Self::UnknownDataflow | Self::ShuttingDown | Self::UnknownPort { .. }
)
}
#[must_use]
pub const fn kind_name(&self) -> &'static str {
match self {
Self::UnknownDataflow => "unknown_dataflow",
Self::UnknownPort { .. } => "unknown_port",
Self::TypeMismatch { .. } => "type_mismatch",
Self::PlaneUnavailable { .. } => "plane_unavailable",
Self::PayloadTooLarge { .. } => "payload_too_large",
Self::Unauthorized => "unauthorized",
Self::ShuttingDown => "shutting_down",
Self::Duplicate { .. } => "duplicate",
Self::Other { .. } => "other",
}
}
}
impl fmt::Display for RouteRejection {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::UnknownDataflow => f.write_str("unknown dataflow"),
Self::UnknownPort { port } => write!(f, "unknown port {port}"),
Self::TypeMismatch { expected, found } => {
let expected = expected.as_ref().map_or("any", |urn| urn.as_str());
let found = found.as_ref().map_or("any", |urn| urn.as_str());
write!(f, "type mismatch: expected {expected}, found {found}")
}
Self::PlaneUnavailable { plane } => write!(f, "plane {plane} unavailable"),
Self::PayloadTooLarge { limit } => {
write!(f, "payload ceiling above the peer's {limit} B limit")
}
Self::Unauthorized => f.write_str("not authorised for this dataflow"),
Self::ShuttingDown => f.write_str("peer is shutting down"),
Self::Duplicate { route_id } => write!(f, "route {route_id} already open"),
Self::Other { message } => f.write_str(message),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Encode, Decode)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum RouteCloseReason {
#[oxicode(variant = 0)]
ProducerFinished,
#[oxicode(variant = 1)]
ProducerCrashed {
generation: u64,
},
#[oxicode(variant = 2)]
ConsumerGone,
#[oxicode(variant = 3)]
DataflowStopped,
#[oxicode(variant = 4)]
PlaneFailed {
plane: Plane,
message: String,
},
#[oxicode(variant = 5)]
Superseded {
route_id: crate::ids::RouteId,
},
#[oxicode(variant = 6)]
DaemonShutdown,
#[oxicode(variant = 7)]
Error {
message: String,
},
#[oxicode(variant = 8)]
Disconnected,
}
impl RouteCloseReason {
#[must_use]
pub const fn is_expected(&self) -> bool {
matches!(
self,
Self::ProducerFinished
| Self::DataflowStopped
| Self::DaemonShutdown
| Self::Disconnected
)
}
#[must_use]
pub const fn kind_name(&self) -> &'static str {
match self {
Self::ProducerFinished => "producer_finished",
Self::ProducerCrashed { .. } => "producer_crashed",
Self::ConsumerGone => "consumer_gone",
Self::DataflowStopped => "dataflow_stopped",
Self::PlaneFailed { .. } => "plane_failed",
Self::Superseded { .. } => "superseded",
Self::DaemonShutdown => "daemon_shutdown",
Self::Error { .. } => "error",
Self::Disconnected => "disconnected",
}
}
}
impl fmt::Display for RouteCloseReason {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::ProducerFinished => f.write_str("producer finished the output"),
Self::ProducerCrashed { generation } => {
write!(f, "producer generation {generation} crashed")
}
Self::ConsumerGone => f.write_str("consumer is gone"),
Self::DataflowStopped => f.write_str("dataflow stopped"),
Self::PlaneFailed { plane, message } => write!(f, "{plane} plane failed: {message}"),
Self::Superseded { route_id } => write!(f, "superseded by route {route_id}"),
Self::DaemonShutdown => f.write_str("daemon shutting down"),
Self::Error { message } => f.write_str(message),
Self::Disconnected => f.write_str("edge removed by an operator"),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Encode, Decode)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum RouteDowngradeReason {
#[oxicode(variant = 0)]
ConsumerDetached {
consumer: PortRef,
},
#[oxicode(variant = 1)]
ConsumerCrashed {
consumer: PortRef,
},
#[oxicode(variant = 2)]
RemoteConsumerAdded {
consumer: PortRef,
},
#[oxicode(variant = 3)]
SegmentClosed {
generation: u64,
},
#[oxicode(variant = 4)]
PoolExhausted,
#[oxicode(variant = 5)]
DaemonRequest {
message: String,
},
}
impl RouteDowngradeReason {
#[must_use]
pub const fn is_capacity_pressure(&self) -> bool {
matches!(self, Self::PoolExhausted)
}
#[must_use]
pub const fn kind_name(&self) -> &'static str {
match self {
Self::ConsumerDetached { .. } => "consumer_detached",
Self::ConsumerCrashed { .. } => "consumer_crashed",
Self::RemoteConsumerAdded { .. } => "remote_consumer_added",
Self::SegmentClosed { .. } => "segment_closed",
Self::PoolExhausted => "pool_exhausted",
Self::DaemonRequest { .. } => "daemon_request",
}
}
}
impl fmt::Display for RouteDowngradeReason {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::ConsumerDetached { consumer } => write!(f, "consumer {consumer} detached"),
Self::ConsumerCrashed { consumer } => write!(f, "consumer {consumer} crashed"),
Self::RemoteConsumerAdded { consumer } => {
write!(f, "remote consumer {consumer} joined")
}
Self::SegmentClosed { generation } => {
write!(f, "segment for generation {generation} closed")
}
Self::PoolExhausted => f.write_str("shm pool exhausted"),
Self::DaemonRequest { message } => f.write_str(message),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Encode, Decode)]
pub struct ShmSegmentSpec {
pub name: String,
pub generation: u64,
pub slot_count: u32,
pub slot_size: u64,
}
impl ShmSegmentSpec {
#[must_use]
pub fn new(name: impl Into<String>, generation: u64, slot_count: u32, slot_size: u64) -> Self {
Self {
name: name.into(),
generation,
slot_count,
slot_size,
}
}
#[must_use]
pub const fn capacity_bytes(&self) -> u64 {
(self.slot_count as u64).saturating_mul(self.slot_size)
}
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
use crate::codec::round_trip;
fn key() -> RouteKey {
RouteKey::new(
DataflowId::from_u128(0x2B),
"camera/image".parse().unwrap(),
"detector/frames".parse().unwrap(),
)
}
#[test]
fn planes_round_trip_and_classify() {
let mut names = std::collections::BTreeSet::new();
for plane in Plane::ALL.iter().copied() {
assert_eq!(round_trip(&plane).unwrap(), plane);
assert!(names.insert(plane.as_str()));
assert_eq!(plane.to_string(), plane.as_str());
}
assert_eq!(names.len(), 4);
assert_eq!(Plane::default(), Plane::Uds);
}
#[test]
fn plane_properties_match_the_blueprint() {
assert!(Plane::Shm.is_zero_copy());
assert!(!Plane::Uds.is_zero_copy());
assert!(Plane::Tcp.is_remote());
assert!(Plane::Quic.is_remote());
assert!(!Plane::Uds.is_remote());
assert!(!Plane::Shm.is_remote());
assert!(Plane::Quic.needs_crc());
assert!(Plane::Tcp.needs_crc());
assert!(!Plane::Uds.needs_crc());
assert!(!Plane::Shm.needs_crc());
for plane in Plane::ALL.iter().copied() {
assert_eq!(plane.allows_compression(), plane.is_remote());
}
}
#[test]
fn route_keys_render_and_round_trip() {
let key = key();
assert_eq!(
key.to_string(),
format!("{}:camera/image->detector/frames", key.dataflow)
);
assert_eq!(round_trip(&key).unwrap(), key);
}
#[test]
fn route_keys_order_by_dataflow_then_endpoints() {
let mut keys = [
RouteKey::new(
DataflowId::from_u128(2),
"a/o".parse().unwrap(),
"b/i".parse().unwrap(),
),
RouteKey::new(
DataflowId::from_u128(1),
"z/o".parse().unwrap(),
"b/i".parse().unwrap(),
),
RouteKey::new(
DataflowId::from_u128(1),
"a/o".parse().unwrap(),
"b/i".parse().unwrap(),
),
];
keys.sort();
assert_eq!(keys[0].dataflow, DataflowId::from_u128(1));
assert_eq!(keys[0].producer.node().as_str(), "a");
assert_eq!(keys[2].dataflow, DataflowId::from_u128(2));
}
#[test]
fn a_new_route_starts_on_the_reliable_path() {
let route = RouteSpec::new(key());
assert_eq!(route.plane, Plane::Uds);
assert_eq!(route.compression, Compression::None);
assert!(!route.is_upgraded());
assert!(route.segment.is_none());
assert_eq!(route.queue_size, crate::common::node::DEFAULT_QUEUE_SIZE);
}
#[test]
fn upgrading_to_shm_marks_the_route_upgraded() {
let route = RouteSpec::new(key())
.with_plane(Plane::Shm)
.with_segment("dataflow/camera/1");
assert!(route.is_upgraded());
assert_eq!(route.segment.as_deref(), Some("dataflow/camera/1"));
assert_eq!(round_trip(&route).unwrap(), route);
}
#[test]
fn compression_needs_a_codec_a_remote_plane_and_the_threshold() {
let plain = RouteSpec::new(key()).with_plane(Plane::Quic);
assert!(!plain.compression_applies_to(u64::MAX), "no codec selected");
let local = RouteSpec::new(key())
.with_plane(Plane::Shm)
.with_compression(Compression::Lz4);
assert!(!local.compression_applies_to(u64::MAX), "shm is zero copy");
let remote = RouteSpec::new(key())
.with_plane(Plane::Quic)
.with_compression(Compression::Lz4);
assert!(!remote.compression_applies_to(COMPRESSION_THRESHOLD_BYTES - 1));
assert!(remote.compression_applies_to(COMPRESSION_THRESHOLD_BYTES));
assert!(remote.compression_applies_to(COMPRESSION_THRESHOLD_BYTES + 1));
}
#[test]
fn the_compression_threshold_matches_the_blueprint() {
assert_eq!(COMPRESSION_THRESHOLD_BYTES, 16 * 1024);
}
#[test]
fn route_specs_round_trip_on_every_plane() {
for plane in Plane::ALL.iter().copied() {
for compression in Compression::ALL.iter().copied() {
let route = RouteSpec::new(key())
.with_plane(plane)
.with_compression(compression);
assert_eq!(round_trip(&route).unwrap(), route);
}
}
}
}