use core::fmt;
use std::collections::BTreeMap;
use oxicode::{Decode, Encode};
use serde::{Deserialize, Serialize};
use crate::common::duration::DurationMs;
use crate::common::log::LogLevel;
use crate::ids::{DataId, DataflowId, MachineName, NodeId, OperatorId, PortRef, TypeUrn};
use crate::metadata::Parameter;
pub const DEFAULT_QUEUE_SIZE: u32 = 10;
pub const DEFAULT_SHM_POOL_SIZE: u64 = 8 * 1024 * 1024;
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Encode, Decode)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum NodeSource {
#[oxicode(variant = 0)]
Executable {
path: String,
},
#[oxicode(variant = 1)]
Runtime {
operators: Vec<OperatorSpec>,
},
#[oxicode(variant = 2)]
Dynamic,
#[oxicode(variant = 3)]
Ros2Bridge {
config: String,
},
#[oxicode(variant = 4)]
Recorder {
path: String,
},
}
impl NodeSource {
#[must_use]
pub const fn is_spawned(&self) -> bool {
!matches!(self, Self::Dynamic)
}
#[must_use]
pub const fn kind_name(&self) -> &'static str {
match self {
Self::Executable { .. } => "executable",
Self::Runtime { .. } => "runtime",
Self::Dynamic => "dynamic",
Self::Ros2Bridge { .. } => "ros2_bridge",
Self::Recorder { .. } => "recorder",
}
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Encode, Decode)]
pub struct OperatorSpec {
pub id: OperatorId,
pub registry_name: String,
pub config: BTreeMap<String, Parameter>,
}
impl OperatorSpec {
#[must_use]
pub fn new(id: OperatorId, registry_name: impl Into<String>) -> Self {
Self {
id,
registry_name: registry_name.into(),
config: BTreeMap::new(),
}
}
}
#[derive(
Debug,
Clone,
Copy,
Default,
PartialEq,
Eq,
PartialOrd,
Ord,
Hash,
Serialize,
Deserialize,
Encode,
Decode,
)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum QueuePolicy {
#[default]
#[oxicode(variant = 0)]
DropOldest,
#[oxicode(variant = 1)]
Backpressure,
}
impl QueuePolicy {
pub const ALL: &'static [Self] = &[Self::DropOldest, Self::Backpressure];
#[must_use]
pub const fn buffers_beyond_capacity(self) -> bool {
matches!(self, Self::Backpressure)
}
#[must_use]
pub const fn overflow_multiplier(self) -> u32 {
match self {
Self::DropOldest => 1,
Self::Backpressure => 10,
}
}
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::DropOldest => "drop_oldest",
Self::Backpressure => "backpressure",
}
}
}
impl fmt::Display for QueuePolicy {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
#[derive(
Debug,
Clone,
Copy,
Default,
PartialEq,
Eq,
PartialOrd,
Ord,
Hash,
Serialize,
Deserialize,
Encode,
Decode,
)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum PriorityLane {
#[default]
#[oxicode(variant = 0)]
Data,
#[oxicode(variant = 1)]
Control,
}
#[derive(
Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, Encode, Decode,
)]
#[serde(rename_all = "kebab-case")]
#[non_exhaustive]
pub enum NodePattern {
#[oxicode(variant = 0)]
ServiceServer,
#[oxicode(variant = 1)]
ServiceClient,
#[oxicode(variant = 2)]
ActionServer,
#[oxicode(variant = 3)]
ActionClient,
}
impl NodePattern {
pub const ALL: &'static [Self] = &[
Self::ServiceServer,
Self::ServiceClient,
Self::ActionServer,
Self::ActionClient,
];
#[must_use]
pub const fn is_server(self) -> bool {
matches!(self, Self::ServiceServer | Self::ActionServer)
}
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::ServiceServer => "service-server",
Self::ServiceClient => "service-client",
Self::ActionServer => "action-server",
Self::ActionClient => "action-client",
}
}
}
impl fmt::Display for NodePattern {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
#[derive(
Debug,
Clone,
Copy,
Default,
PartialEq,
Eq,
PartialOrd,
Ord,
Hash,
Serialize,
Deserialize,
Encode,
Decode,
)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum RestartPolicy {
#[default]
#[oxicode(variant = 0)]
Never,
#[oxicode(variant = 1)]
OnFailure,
#[oxicode(variant = 2)]
Always,
}
impl RestartPolicy {
pub const ALL: &'static [Self] = &[Self::Never, Self::OnFailure, Self::Always];
#[must_use]
pub const fn should_restart(self, success: bool) -> bool {
match self {
Self::Never => false,
Self::OnFailure => !success,
Self::Always => true,
}
}
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Never => "never",
Self::OnFailure => "on_failure",
Self::Always => "always",
}
}
}
impl fmt::Display for RestartPolicy {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Encode, Decode)]
pub struct RestartConfig {
pub policy: RestartPolicy,
pub max_restarts: Option<u32>,
pub restart_delay: DurationMs,
pub max_restart_delay: DurationMs,
pub restart_window: DurationMs,
}
impl RestartConfig {
#[must_use]
pub const fn never() -> Self {
Self {
policy: RestartPolicy::Never,
max_restarts: None,
restart_delay: DurationMs::new(100),
max_restart_delay: DurationMs::new(30_000),
restart_window: DurationMs::new(60_000),
}
}
#[must_use]
pub fn backoff_for(&self, restarts_so_far: u32) -> DurationMs {
let factor = 1u64.checked_shl(restarts_so_far).unwrap_or(u64::MAX);
self.restart_delay
.checked_mul(factor)
.unwrap_or(self.max_restart_delay)
.min(self.max_restart_delay)
}
#[must_use]
pub const fn budget_exhausted(&self, restarts_in_window: u32) -> bool {
match self.max_restarts {
Some(max) => restarts_in_window >= max,
None => false,
}
}
}
impl Default for RestartConfig {
fn default() -> Self {
Self::never()
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Encode, Decode)]
pub struct LogConfig {
pub send_stdout_as: Option<DataId>,
pub min_log_level: LogLevel,
pub max_log_size: Option<u64>,
pub max_rotated_files: Option<u32>,
}
impl Default for LogConfig {
fn default() -> Self {
Self {
send_stdout_as: None,
min_log_level: LogLevel::Info,
max_log_size: None,
max_rotated_files: None,
}
}
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, Encode, Decode)]
pub struct DeploySpec {
pub machine: Option<MachineName>,
pub labels: BTreeMap<String, String>,
pub working_dir: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Encode, Decode)]
pub struct InputSpec {
pub id: DataId,
pub source: PortRef,
pub queue_size: u32,
pub queue_policy: QueuePolicy,
pub timeout: Option<DurationMs>,
pub priority_lane: PriorityLane,
pub type_urn: Option<TypeUrn>,
pub deadline: Option<DurationMs>,
}
impl InputSpec {
#[must_use]
pub fn new(id: DataId, source: PortRef) -> Self {
Self {
id,
source,
queue_size: DEFAULT_QUEUE_SIZE,
queue_policy: QueuePolicy::DropOldest,
timeout: None,
priority_lane: PriorityLane::Data,
type_urn: None,
deadline: None,
}
}
#[must_use]
pub const fn with_queue(mut self, size: u32, policy: QueuePolicy) -> Self {
self.queue_size = size;
self.queue_policy = policy;
self
}
#[must_use]
pub fn with_type(mut self, urn: TypeUrn) -> Self {
self.type_urn = Some(urn);
self
}
#[must_use]
pub const fn effective_capacity(&self) -> u32 {
self.queue_size
.saturating_mul(self.queue_policy.overflow_multiplier())
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Encode, Decode)]
pub struct OutputSpec {
pub id: DataId,
pub type_urn: Option<TypeUrn>,
pub shm_pool_size: Option<u64>,
}
impl OutputSpec {
#[must_use]
pub const fn new(id: DataId) -> Self {
Self {
id,
type_urn: None,
shm_pool_size: None,
}
}
#[must_use]
pub fn with_type(mut self, urn: TypeUrn) -> Self {
self.type_urn = Some(urn);
self
}
#[must_use]
pub const fn pool_size(&self) -> u64 {
match self.shm_pool_size {
Some(size) => size,
None => DEFAULT_SHM_POOL_SIZE,
}
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Encode, Decode)]
pub struct NodeSpawnSpec {
pub dataflow: DataflowId,
pub node: NodeId,
pub generation: u64,
pub source: NodeSource,
pub args: Vec<String>,
pub env: BTreeMap<String, String>,
pub working_dir: Option<String>,
pub inputs: Vec<InputSpec>,
pub outputs: Vec<OutputSpec>,
pub restart: RestartConfig,
pub logging: LogConfig,
pub deploy: DeploySpec,
pub cpu_affinity: Vec<u16>,
pub spawn_deadline: Option<DurationMs>,
pub health_check_timeout: Option<DurationMs>,
pub finish_grace: Option<DurationMs>,
pub pattern: Option<NodePattern>,
}
impl NodeSpawnSpec {
#[must_use]
pub fn new(dataflow: DataflowId, node: NodeId, generation: u64, source: NodeSource) -> Self {
Self {
dataflow,
node,
generation,
source,
args: Vec::new(),
env: BTreeMap::new(),
working_dir: None,
inputs: Vec::new(),
outputs: Vec::new(),
restart: RestartConfig::never(),
logging: LogConfig::default(),
deploy: DeploySpec::default(),
cpu_affinity: Vec::new(),
spawn_deadline: None,
health_check_timeout: None,
finish_grace: None,
pattern: None,
}
}
#[must_use]
pub fn with_input(mut self, input: InputSpec) -> Self {
self.inputs.push(input);
self
}
#[must_use]
pub fn with_output(mut self, output: OutputSpec) -> Self {
self.outputs.push(output);
self
}
#[must_use]
pub const fn with_restart(mut self, restart: RestartConfig) -> Self {
self.restart = restart;
self
}
#[must_use]
pub fn input(&self, id: &DataId) -> Option<&InputSpec> {
self.inputs.iter().find(|input| &input.id == id)
}
#[must_use]
pub fn output(&self, id: &DataId) -> Option<&OutputSpec> {
self.outputs.iter().find(|output| &output.id == id)
}
#[must_use]
pub fn segment_prefix(&self) -> String {
format!("{}/{}/{}", self.dataflow, self.node, self.generation)
}
#[must_use]
pub const fn is_restart(&self) -> bool {
self.generation > 1
}
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
use crate::codec::round_trip;
fn spec() -> NodeSpawnSpec {
NodeSpawnSpec::new(
DataflowId::from_u128(0x11),
NodeId::new("detector").unwrap(),
2,
NodeSource::Executable {
path: "./bin/detector".into(),
},
)
.with_input(
InputSpec::new(
DataId::new("frames").unwrap(),
PortRef::from_parts("camera", "image").unwrap(),
)
.with_queue(4, QueuePolicy::Backpressure)
.with_type(TypeUrn::new("std/media/v1/Image").unwrap()),
)
.with_output(
OutputSpec::new(DataId::new("boxes").unwrap())
.with_type(TypeUrn::new("std/vision/v1/Detections").unwrap()),
)
.with_restart(RestartConfig {
policy: RestartPolicy::OnFailure,
max_restarts: Some(5),
restart_delay: DurationMs::new(100),
max_restart_delay: DurationMs::from_secs(30),
restart_window: DurationMs::from_secs(60),
})
}
#[test]
fn spawn_specs_round_trip() {
let spec = spec();
assert_eq!(round_trip(&spec).unwrap(), spec);
}
#[test]
fn a_minimal_spawn_spec_round_trips() {
let spec = NodeSpawnSpec::new(
DataflowId::NIL,
NodeId::new("n").unwrap(),
1,
NodeSource::Dynamic,
);
assert_eq!(round_trip(&spec).unwrap(), spec);
}
#[test]
fn every_node_source_round_trips_and_names_itself() {
let sources = [
NodeSource::Executable { path: "p".into() },
NodeSource::Runtime {
operators: vec![OperatorSpec::new(
OperatorId::new("op").unwrap(),
"crate::Op",
)],
},
NodeSource::Dynamic,
NodeSource::Ros2Bridge {
config: "{}".into(),
},
NodeSource::Recorder {
path: "out.arec".into(),
},
];
let mut names = std::collections::BTreeSet::new();
for source in sources {
assert!(names.insert(source.kind_name()));
assert_eq!(round_trip(&source).unwrap(), source);
}
assert_eq!(names.len(), 5);
}
#[test]
fn only_dynamic_sources_are_unspawned() {
assert!(!NodeSource::Dynamic.is_spawned());
assert!(NodeSource::Executable { path: "p".into() }.is_spawned());
assert!(NodeSource::Recorder { path: "p".into() }.is_spawned());
}
#[test]
fn port_lookup_finds_declared_ports() {
let spec = spec();
assert!(spec.input(&DataId::new("frames").unwrap()).is_some());
assert!(spec.input(&DataId::new("absent").unwrap()).is_none());
assert!(spec.output(&DataId::new("boxes").unwrap()).is_some());
assert!(spec.output(&DataId::new("absent").unwrap()).is_none());
}
#[test]
fn segment_prefix_matches_the_documented_shape() {
let spec = spec();
assert_eq!(
spec.segment_prefix(),
format!("{}/detector/2", DataflowId::from_u128(0x11))
);
assert!(spec.is_restart());
let first = NodeSpawnSpec::new(
DataflowId::NIL,
NodeId::new("n").unwrap(),
1,
NodeSource::Dynamic,
);
assert!(!first.is_restart());
}
#[test]
fn queue_policies_describe_their_capacity() {
assert_eq!(QueuePolicy::DropOldest.overflow_multiplier(), 1);
assert_eq!(QueuePolicy::Backpressure.overflow_multiplier(), 10);
assert!(!QueuePolicy::DropOldest.buffers_beyond_capacity());
assert!(QueuePolicy::Backpressure.buffers_beyond_capacity());
assert_eq!(QueuePolicy::DropOldest.to_string(), "drop_oldest");
assert_eq!(QueuePolicy::Backpressure.to_string(), "backpressure");
}
#[test]
fn effective_capacity_reflects_the_policy() {
let source = PortRef::from_parts("a", "b").unwrap();
let id = DataId::new("in").unwrap();
let dropping = InputSpec::new(id.clone(), source.clone());
assert_eq!(dropping.queue_size, DEFAULT_QUEUE_SIZE);
assert_eq!(dropping.effective_capacity(), DEFAULT_QUEUE_SIZE);
let buffering = InputSpec::new(id, source).with_queue(7, QueuePolicy::Backpressure);
assert_eq!(buffering.effective_capacity(), 70);
}
#[test]
fn effective_capacity_saturates() {
let input = InputSpec::new(
DataId::new("in").unwrap(),
PortRef::from_parts("a", "b").unwrap(),
)
.with_queue(u32::MAX, QueuePolicy::Backpressure);
assert_eq!(input.effective_capacity(), u32::MAX);
}
#[test]
fn output_pool_size_falls_back_to_the_default() {
let output = OutputSpec::new(DataId::new("o").unwrap());
assert_eq!(output.pool_size(), DEFAULT_SHM_POOL_SIZE);
let sized = OutputSpec {
shm_pool_size: Some(4096),
..OutputSpec::new(DataId::new("o").unwrap())
};
assert_eq!(sized.pool_size(), 4096);
}
#[test]
fn restart_policies_decide_correctly() {
for &policy in RestartPolicy::ALL {
assert_eq!(round_trip(&policy).unwrap(), policy);
}
assert!(!RestartPolicy::Never.should_restart(true));
assert!(!RestartPolicy::Never.should_restart(false));
assert!(!RestartPolicy::OnFailure.should_restart(true));
assert!(RestartPolicy::OnFailure.should_restart(false));
assert!(RestartPolicy::Always.should_restart(true));
assert!(RestartPolicy::Always.should_restart(false));
assert_eq!(RestartPolicy::default(), RestartPolicy::Never);
assert_eq!(RestartPolicy::OnFailure.to_string(), "on_failure");
}
#[test]
fn backoff_doubles_then_caps() {
let config = RestartConfig {
policy: RestartPolicy::Always,
max_restarts: Some(2),
restart_delay: DurationMs::new(50),
max_restart_delay: DurationMs::new(1_000),
restart_window: DurationMs::from_secs(60),
};
assert_eq!(config.backoff_for(0), DurationMs::new(50));
assert_eq!(config.backoff_for(1), DurationMs::new(100));
assert_eq!(config.backoff_for(2), DurationMs::new(200));
assert_eq!(config.backoff_for(4), DurationMs::new(800));
assert_eq!(config.backoff_for(5), DurationMs::new(1_000));
for restarts in [31u32, 32, 63, 64, 100, u32::MAX] {
assert_eq!(config.backoff_for(restarts), DurationMs::new(1_000));
}
}
#[test]
fn budget_exhaustion_respects_unlimited() {
let mut config = RestartConfig::never();
config.max_restarts = None;
assert!(!config.budget_exhausted(u32::MAX));
config.max_restarts = Some(0);
assert!(config.budget_exhausted(0));
config.max_restarts = Some(3);
assert!(!config.budget_exhausted(2));
assert!(config.budget_exhausted(3));
assert!(config.budget_exhausted(4));
}
#[test]
fn defaults_are_conservative() {
assert_eq!(RestartConfig::default(), RestartConfig::never());
assert_eq!(RestartConfig::never().policy, RestartPolicy::Never);
assert_eq!(LogConfig::default().min_log_level, LogLevel::Info);
assert!(LogConfig::default().send_stdout_as.is_none());
assert!(DeploySpec::default().machine.is_none());
assert_eq!(PriorityLane::default(), PriorityLane::Data);
}
#[test]
fn patterns_name_themselves_and_split_by_role() {
for pattern in NodePattern::ALL.iter().copied() {
assert_eq!(round_trip(&pattern).unwrap(), pattern);
assert_eq!(pattern.to_string(), pattern.as_str());
assert!(pattern.as_str().contains('-'));
}
assert!(NodePattern::ServiceServer.is_server());
assert!(NodePattern::ActionServer.is_server());
assert!(!NodePattern::ServiceClient.is_server());
assert!(!NodePattern::ActionClient.is_server());
}
#[test]
fn deploy_and_log_config_round_trip() {
let deploy = DeploySpec {
machine: Some(MachineName::new("robot-1").unwrap()),
labels: BTreeMap::from([("gpu".to_owned(), "true".to_owned())]),
working_dir: Some("/tmp/x".to_owned()),
};
assert_eq!(round_trip(&deploy).unwrap(), deploy);
let logging = LogConfig {
send_stdout_as: Some(DataId::new("stdout").unwrap()),
min_log_level: LogLevel::Debug,
max_log_size: Some(1 << 20),
max_rotated_files: Some(3),
};
assert_eq!(round_trip(&logging).unwrap(), logging);
}
#[test]
fn operator_specs_round_trip_with_configuration() {
let mut operator = OperatorSpec::new(OperatorId::new("nms").unwrap(), "vision::Nms");
operator
.config
.insert("threshold".to_owned(), Parameter::Float(0.5));
assert_eq!(round_trip(&operator).unwrap(), operator);
}
}