use core::fmt;
use oxicode::{Decode, Encode};
use serde::{Deserialize, Serialize};
use crate::common::duration::DurationMs;
use crate::common::node::NodeSpawnSpec;
use crate::common::route::{RouteCloseReason, RouteDowngradeReason, ShmSegmentSpec};
use crate::common::status::{NodeExitCause, StopCause};
use crate::frame::FrameKind;
use crate::ids::{DataId, NodeId, OperatorId, ParamKey, PortRef, SessionId};
use crate::messages::control::types::ParamScope;
use crate::messages::daemon_node::types::ExtensionKey;
use crate::messages::impl_wire_message;
use crate::metadata::{Metadata, Parameter};
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Encode, Decode)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum NodeEvent {
#[oxicode(variant = 0)]
Input {
id: DataId,
source: PortRef,
metadata: Metadata,
payload: Vec<u8>,
},
#[oxicode(variant = 1)]
InputClosed {
id: DataId,
source: PortRef,
reason: RouteCloseReason,
},
#[oxicode(variant = 2)]
InputRecovered {
id: DataId,
source: PortRef,
generation: u64,
},
#[oxicode(variant = 3)]
Stop {
cause: StopCause,
grace: Option<DurationMs>,
},
#[oxicode(variant = 4)]
Reload {
operator: Option<OperatorId>,
path: Option<String>,
},
#[oxicode(variant = 5)]
AllInputsClosed,
#[oxicode(variant = 6)]
NodeFailed {
peer: NodeId,
cause: NodeExitCause,
},
#[oxicode(variant = 7)]
Restarted {
peer: NodeId,
generation: u64,
},
#[oxicode(variant = 8)]
ParamUpdate {
scope: ParamScope,
key: ParamKey,
value: Parameter,
},
#[oxicode(variant = 9)]
ParamDeleted {
scope: ParamScope,
key: ParamKey,
},
#[oxicode(variant = 10)]
ExtDropped {
key: ExtensionKey,
reason: String,
},
#[oxicode(variant = 11)]
RouteUpgrade {
output: DataId,
segment: ShmSegmentSpec,
consumers: Vec<PortRef>,
},
#[oxicode(variant = 12)]
RouteDowngrade {
output: DataId,
reason: RouteDowngradeReason,
},
#[oxicode(variant = 13)]
Registered {
spec: Box<NodeSpawnSpec>,
session: SessionId,
},
#[oxicode(variant = 14)]
ExtValue {
key: ExtensionKey,
value: Option<Vec<u8>>,
},
#[oxicode(variant = 15)]
InputRouteUpgrade {
input: DataId,
source: PortRef,
segment: ShmSegmentSpec,
consumer: PortRef,
},
#[oxicode(variant = 16)]
InputRouteDowngrade {
input: DataId,
reason: RouteDowngradeReason,
},
#[oxicode(variant = 17)]
DeadlineViolated {
peer: NodeId,
input: DataId,
budget: DurationMs,
latency: DurationMs,
},
}
impl NodeEvent {
#[must_use]
pub const fn input(&self) -> Option<&DataId> {
match self {
Self::Input { id, .. }
| Self::InputClosed { id, .. }
| Self::InputRecovered { id, .. } => Some(id),
Self::InputRouteUpgrade { input, .. } | Self::InputRouteDowngrade { input, .. } => {
Some(input)
}
_ => None,
}
}
#[must_use]
pub const fn output(&self) -> Option<&DataId> {
match self {
Self::RouteUpgrade { output, .. } | Self::RouteDowngrade { output, .. } => Some(output),
_ => None,
}
}
#[must_use]
pub const fn is_input(&self) -> bool {
matches!(self, Self::Input { .. })
}
#[must_use]
pub fn payload_len(&self) -> usize {
match self {
Self::Input { payload, .. } => payload.len(),
Self::ExtValue {
value: Some(value), ..
} => value.len(),
_ => 0,
}
}
#[must_use]
pub const fn is_terminal(&self) -> bool {
matches!(self, Self::Stop { .. } | Self::AllInputsClosed)
}
#[must_use]
pub fn is_fault(&self) -> bool {
match self {
Self::NodeFailed { .. } => true,
Self::InputClosed { reason, .. } => !reason.is_expected(),
Self::RouteDowngrade { reason, .. } | Self::InputRouteDowngrade { reason, .. } => {
reason.is_capacity_pressure()
}
_ => false,
}
}
#[must_use]
pub const fn is_route_change(&self) -> bool {
matches!(
self,
Self::RouteUpgrade { .. }
| Self::RouteDowngrade { .. }
| Self::InputRouteUpgrade { .. }
| Self::InputRouteDowngrade { .. }
)
}
#[must_use]
pub const fn is_input_route_change(&self) -> bool {
matches!(
self,
Self::InputRouteUpgrade { .. } | Self::InputRouteDowngrade { .. }
)
}
#[must_use]
pub const fn peer(&self) -> Option<&NodeId> {
match self {
Self::NodeFailed { peer, .. } | Self::Restarted { peer, .. } => Some(peer),
_ => None,
}
}
#[must_use]
pub fn bitwise_eq(&self, other: &Self) -> bool {
match (self, other) {
(
Self::Input {
id: left_id,
source: left_source,
metadata: left_metadata,
payload: left_payload,
},
Self::Input {
id: right_id,
source: right_source,
metadata: right_metadata,
payload: right_payload,
},
) => {
left_id == right_id
&& left_source == right_source
&& left_metadata.bitwise_eq(right_metadata)
&& left_payload == right_payload
}
(
Self::ParamUpdate {
scope: left_scope,
key: left_key,
value: left_value,
},
Self::ParamUpdate {
scope: right_scope,
key: right_key,
value: right_value,
},
) => {
left_scope == right_scope
&& left_key == right_key
&& left_value.bitwise_eq(right_value)
}
_ => self == other,
}
}
}
impl fmt::Display for NodeEvent {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Input {
id,
source,
payload,
..
} => write!(f, "input {id} from {source} ({} byte(s))", payload.len()),
Self::InputClosed { id, reason, .. } => write!(f, "input {id} closed: {reason}"),
Self::InputRecovered { id, generation, .. } => {
write!(f, "input {id} recovered at generation {generation}")
}
Self::Stop { cause, .. } => write!(f, "stop: {cause}"),
Self::Reload { operator, .. } => match operator {
Some(operator) => write!(f, "reload operator {operator}"),
None => f.write_str("reload node"),
},
Self::AllInputsClosed => f.write_str("all inputs closed"),
Self::NodeFailed { peer, cause } => write!(f, "peer {peer} failed: {cause}"),
Self::Restarted { peer, generation } => {
write!(f, "peer {peer} restarted as generation {generation}")
}
Self::ParamUpdate { scope, key, value } => write!(f, "{scope}: {key} = {value}"),
Self::ParamDeleted { scope, key } => write!(f, "{scope}: {key} deleted"),
Self::ExtDropped { key, reason } => write!(f, "extension {key} dropped: {reason}"),
Self::RouteUpgrade {
output,
segment,
consumers,
} => write!(
f,
"upgrade {output} to {} ({} consumer(s))",
segment.name,
consumers.len()
),
Self::RouteDowngrade { output, reason } => {
write!(f, "downgrade {output}: {reason}")
}
Self::Registered { spec, .. } => write!(
f,
"registered {}/{} as generation {}",
spec.dataflow, spec.node, spec.generation
),
Self::ExtValue { key, value } => match value {
Some(value) => write!(f, "{key} = {} byte(s)", value.len()),
None => write!(f, "{key} is unset"),
},
Self::InputRouteUpgrade {
input,
source,
segment,
..
} => write!(f, "upgrade input {input} from {source} to {}", segment.name),
Self::InputRouteDowngrade { input, reason } => {
write!(f, "downgrade input {input}: {reason}")
}
Self::DeadlineViolated {
peer,
input,
budget,
latency,
} => write!(
f,
"peer {peer} violated its deadline on {input}: {}ms over a {}ms budget",
latency.as_millis().saturating_sub(budget.as_millis()),
budget.as_millis(),
),
}
}
}
impl_wire_message!(
NodeEvent,
FrameKind::NodeEvent,
[
"Input",
"InputClosed",
"InputRecovered",
"Stop",
"Reload",
"AllInputsClosed",
"NodeFailed",
"Restarted",
"ParamUpdate",
"ParamDeleted",
"ExtDropped",
"RouteUpgrade",
"RouteDowngrade",
"Registered",
"ExtValue",
"InputRouteUpgrade",
"InputRouteDowngrade",
"DeadlineViolated",
],
fn variant_index(&self) -> u16 {
match self {
Self::Input { .. } => 0,
Self::InputClosed { .. } => 1,
Self::InputRecovered { .. } => 2,
Self::Stop { .. } => 3,
Self::Reload { .. } => 4,
Self::AllInputsClosed => 5,
Self::NodeFailed { .. } => 6,
Self::Restarted { .. } => 7,
Self::ParamUpdate { .. } => 8,
Self::ParamDeleted { .. } => 9,
Self::ExtDropped { .. } => 10,
Self::RouteUpgrade { .. } => 11,
Self::RouteDowngrade { .. } => 12,
Self::Registered { .. } => 13,
Self::ExtValue { .. } => 14,
Self::InputRouteUpgrade { .. } => 15,
Self::InputRouteDowngrade { .. } => 16,
Self::DeadlineViolated { .. } => 17,
}
}
);
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use astrs_time::HlcTimestamp;
use super::*;
use crate::codec::{WireDecode, WireEncode, round_trip};
use crate::common::route::Plane;
use crate::frame::{FrameFlags, FrameLimits};
use crate::messages::WireMessage;
use crate::messages::samples::node_events;
#[test]
fn the_family_freezes_the_thirteen_normative_variants_first() {
assert_eq!(
&NodeEvent::VARIANT_NAMES[..13],
&[
"Input",
"InputClosed",
"InputRecovered",
"Stop",
"Reload",
"AllInputsClosed",
"NodeFailed",
"Restarted",
"ParamUpdate",
"ParamDeleted",
"ExtDropped",
"RouteUpgrade",
"RouteDowngrade",
]
);
assert_eq!(NodeEvent::VARIANT_NAMES.len(), 18);
assert_eq!(
&NodeEvent::VARIANT_NAMES[13..],
&[
"Registered",
"ExtValue",
"InputRouteUpgrade",
"InputRouteDowngrade",
"DeadlineViolated",
],
"tail appends stay at the tail, in the order they were added"
);
}
#[test]
fn every_variant_reports_and_encodes_its_frozen_index() {
let samples = node_events().unwrap();
assert_eq!(samples.len(), NodeEvent::VARIANT_NAMES.len());
for (index, sample) in samples.iter().enumerate() {
let index = u16::try_from(index).unwrap();
assert_eq!(sample.variant_index(), index, "{sample:?}");
assert_eq!(u16::from(sample.encode_to_vec().unwrap()[0]), index);
}
}
#[test]
fn every_variant_round_trips_through_a_frame() {
let limits = FrameLimits::uds();
for sample in node_events().unwrap() {
let bytes = sample.to_frame(FrameFlags::EMPTY, &limits).unwrap();
let decoded = NodeEvent::from_bytes(&bytes, &limits).unwrap();
assert!(decoded.bitwise_eq(&sample), "{sample:?}");
}
}
#[test]
fn trailing_bytes_after_an_event_are_refused() {
for sample in node_events().unwrap() {
let mut bytes = sample.encode_to_vec().unwrap();
bytes.push(3);
assert!(matches!(
NodeEvent::decode_exact(&bytes),
Err(crate::error::WireError::TrailingBytes { .. })
));
}
}
#[test]
fn an_input_carries_its_id_metadata_and_bytes() {
let event = NodeEvent::Input {
id: DataId::new("frames").unwrap(),
source: "camera/image".parse().unwrap(),
metadata: Metadata::new(HlcTimestamp::new(1_000, 1)),
payload: vec![9; 64],
};
assert!(event.is_input());
assert_eq!(event.input().map(DataId::as_str), Some("frames"));
assert_eq!(event.payload_len(), 64);
assert!(!event.is_fault());
assert_eq!(round_trip(&event).unwrap(), event);
}
#[test]
fn faults_are_distinguished_from_orderly_progress() {
assert!(
NodeEvent::NodeFailed {
peer: NodeId::new("camera").unwrap(),
cause: NodeExitCause::Panic {
message: "boom".to_owned()
},
}
.is_fault()
);
assert!(
!NodeEvent::InputClosed {
id: DataId::new("frames").unwrap(),
source: "camera/image".parse().unwrap(),
reason: RouteCloseReason::ProducerFinished,
}
.is_fault(),
"a producer finishing is not a fault"
);
assert!(
NodeEvent::InputClosed {
id: DataId::new("frames").unwrap(),
source: "camera/image".parse().unwrap(),
reason: RouteCloseReason::PlaneFailed {
plane: Plane::Quic,
message: "reset".to_owned(),
},
}
.is_fault()
);
assert!(
NodeEvent::RouteDowngrade {
output: DataId::new("image").unwrap(),
reason: RouteDowngradeReason::PoolExhausted,
}
.is_fault(),
"pool exhaustion is the metric §6.2 insists on surfacing"
);
assert!(
!NodeEvent::RouteDowngrade {
output: DataId::new("image").unwrap(),
reason: RouteDowngradeReason::ConsumerDetached {
consumer: "detector/frames".parse().unwrap(),
},
}
.is_fault()
);
}
#[test]
fn route_changes_name_their_output() {
let upgrade = NodeEvent::RouteUpgrade {
output: DataId::new("image").unwrap(),
segment: ShmSegmentSpec::new("astrs/df/camera/3/image", 3, 32, 1 << 20),
consumers: vec!["detector/frames".parse().unwrap()],
};
assert!(upgrade.is_route_change());
assert_eq!(upgrade.output().map(DataId::as_str), Some("image"));
let downgrade = NodeEvent::RouteDowngrade {
output: DataId::new("image").unwrap(),
reason: RouteDowngradeReason::PoolExhausted,
};
assert!(downgrade.is_route_change());
assert!(!NodeEvent::AllInputsClosed.is_route_change());
}
#[test]
fn input_route_changes_name_their_input() {
let upgrade = NodeEvent::InputRouteUpgrade {
input: DataId::new("frames").unwrap(),
source: "camera/image".parse().unwrap(),
segment: ShmSegmentSpec::new("astrs/df/camera/3/image", 3, 32, 1 << 20),
consumer: "detector/frames".parse().unwrap(),
};
assert!(upgrade.is_route_change());
assert!(upgrade.is_input_route_change());
assert_eq!(upgrade.input().map(DataId::as_str), Some("frames"));
assert_eq!(
upgrade.output(),
None,
"an input-side change names no output"
);
assert_eq!(round_trip(&upgrade).unwrap(), upgrade);
let downgrade = NodeEvent::InputRouteDowngrade {
input: DataId::new("frames").unwrap(),
reason: RouteDowngradeReason::SegmentClosed { generation: 3 },
};
assert!(downgrade.is_input_route_change());
assert!(!downgrade.is_fault(), "a closed segment is not congestion");
assert!(
NodeEvent::InputRouteDowngrade {
input: DataId::new("frames").unwrap(),
reason: RouteDowngradeReason::PoolExhausted,
}
.is_fault(),
"pool exhaustion is the metric §6.2 insists on surfacing, both ends"
);
assert_eq!(round_trip(&downgrade).unwrap(), downgrade);
assert!(
!NodeEvent::RouteUpgrade {
output: DataId::new("image").unwrap(),
segment: ShmSegmentSpec::new("astrs/df/camera/3/image", 3, 32, 1 << 20),
consumers: Vec::new(),
}
.is_input_route_change()
);
}
#[test]
fn terminal_events_wind_the_node_down() {
assert!(NodeEvent::AllInputsClosed.is_terminal());
assert!(
NodeEvent::Stop {
cause: StopCause::Requested,
grace: None
}
.is_terminal()
);
assert!(
!NodeEvent::Reload {
operator: None,
path: None
}
.is_terminal()
);
}
#[test]
fn peer_events_name_their_peer() {
let peer = NodeId::new("camera").unwrap();
assert_eq!(
NodeEvent::Restarted {
peer: peer.clone(),
generation: 2
}
.peer(),
Some(&peer)
);
assert_eq!(NodeEvent::AllInputsClosed.peer(), None);
}
#[test]
fn nan_values_survive_the_wire() {
let mut metadata = Metadata::new(HlcTimestamp::new(1, 0));
metadata.insert("nan", f64::NAN).unwrap();
let input = NodeEvent::Input {
id: DataId::new("frames").unwrap(),
source: "camera/image".parse().unwrap(),
metadata,
payload: Vec::new(),
};
assert!(round_trip(&input).unwrap().bitwise_eq(&input));
let param = NodeEvent::ParamUpdate {
scope: ParamScope::Global,
key: ParamKey::new("gain").unwrap(),
value: Parameter::Float(f64::NAN),
};
assert!(round_trip(¶m).unwrap().bitwise_eq(¶m));
}
#[test]
fn display_names_every_variant_without_panicking() {
for sample in node_events().unwrap() {
assert!(!sample.to_string().is_empty());
}
}
}