use astrs_data::ipc::IpcError;
use astrs_data::{DataError, TypeUrnError};
use astrs_scheduler::SchedulerError;
use astrs_shm::ShmError;
use astrs_transport::TransportError;
use astrs_wire::{DataId, IdError, NodeConfigError, StopCause, WireError};
pub type Result<T, E = NodeError> = core::result::Result<T, E>;
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum NodeError {
#[error("node configuration: {0}")]
Config(#[source] NodeConfigError),
#[error("environment variable {name} is not set (was this node spawned by an AstRS daemon?)")]
MissingEnv {
name: &'static str,
},
#[error("environment variable {name}={value} is invalid: {reason}")]
BadEnv {
name: &'static str,
value: String,
reason: String,
},
#[error("could not reach the daemon: {}", format_attempts(.attempts))]
Connect {
attempts: Vec<(String, String)>,
},
#[error("handshake with the daemon failed: {0}")]
Handshake(String),
#[error("the daemon refused this node's registration: {0}")]
Registration(String),
#[error("the daemon connection closed")]
DaemonGone,
#[error("transport: {0}")]
Transport(#[source] TransportError),
#[error("wire protocol: {0}")]
Wire(#[source] WireError),
#[error("payload: {0}")]
Data(#[source] DataError),
#[error("payload encoding: {0}")]
Ipc(#[source] IpcError),
#[error("type: {0}")]
TypeUrn(#[source] TypeUrnError),
#[error("shared memory: {0}")]
Shm(#[source] ShmError),
#[error("identifier: {0}")]
Id(#[source] IdError),
#[error("scheduler: {0}")]
Scheduler(#[source] SchedulerError),
#[error("this node has no output named `{output}`")]
UnknownOutput {
output: DataId,
},
#[error("this node has no input named `{input}`")]
UnknownInput {
input: DataId,
},
#[error("port `{port}` is declared as `{declared}`, but the handle is typed `{requested}`")]
TypeMismatch {
port: DataId,
declared: String,
requested: String,
},
#[error("payload of {len} bytes exceeds the {max}-byte limit")]
PayloadTooLarge {
len: usize,
max: usize,
},
#[error(
"{method} blocks, and this is a current-thread tokio runtime; call {alternative} instead"
)]
BlockingInAsync {
method: &'static str,
alternative: &'static str,
},
#[error("the dataflow stopped this node")]
Stopped,
#[error("the supervising process {parent_pid} exited; this node is orphaned")]
Orphaned {
parent_pid: u32,
},
#[error("{operation} timed out after {millis} ms")]
Timeout {
operation: &'static str,
millis: u64,
},
#[error("the daemon request queue is full ({depth} messages)")]
Backpressure {
depth: usize,
},
#[error("could not start a runtime for this node: {0}")]
Runtime(String),
#[error("{0}")]
Pattern(String),
#[error("test harness: {0}")]
Testing(String),
}
impl NodeError {
#[must_use]
pub const fn is_shutdown(&self) -> bool {
matches!(self, Self::Stopped | Self::Orphaned { .. })
}
#[must_use]
pub const fn is_retryable(&self) -> bool {
matches!(
self,
Self::Backpressure { .. } | Self::Timeout { .. } | Self::Connect { .. }
)
}
#[must_use]
pub const fn is_usage_error(&self) -> bool {
matches!(
self,
Self::UnknownOutput { .. }
| Self::UnknownInput { .. }
| Self::TypeMismatch { .. }
| Self::BlockingInAsync { .. }
| Self::Pattern(_)
)
}
#[must_use]
pub const fn exit_code(&self) -> i32 {
if self.is_shutdown() { 0 } else { 1 }
}
#[must_use]
pub const fn kind_name(&self) -> &'static str {
match self {
Self::Config(_) => "config",
Self::MissingEnv { .. } => "missing_env",
Self::BadEnv { .. } => "bad_env",
Self::Connect { .. } => "connect",
Self::Handshake(_) => "handshake",
Self::Registration(_) => "registration",
Self::DaemonGone => "daemon_gone",
Self::Transport(_) => "transport",
Self::Wire(_) => "wire",
Self::Data(_) => "data",
Self::Ipc(_) => "ipc",
Self::TypeUrn(_) => "type_urn",
Self::Shm(_) => "shm",
Self::Id(_) => "id",
Self::Scheduler(_) => "scheduler",
Self::UnknownOutput { .. } => "unknown_output",
Self::UnknownInput { .. } => "unknown_input",
Self::TypeMismatch { .. } => "type_mismatch",
Self::PayloadTooLarge { .. } => "payload_too_large",
Self::BlockingInAsync { .. } => "blocking_in_async",
Self::Stopped => "stopped",
Self::Orphaned { .. } => "orphaned",
Self::Timeout { .. } => "timeout",
Self::Backpressure { .. } => "backpressure",
Self::Runtime(_) => "runtime",
Self::Pattern(_) => "pattern",
Self::Testing(_) => "testing",
}
}
#[must_use]
pub const fn stop_cause(&self) -> Option<StopCause> {
match self {
Self::Stopped => Some(StopCause::Requested),
Self::Orphaned { .. } | Self::DaemonGone => Some(StopCause::DaemonShutdown),
_ => None,
}
}
}
fn format_attempts(attempts: &[(String, String)]) -> String {
if attempts.is_empty() {
return "no endpoints were configured".to_owned();
}
attempts
.iter()
.map(|(endpoint, reason)| format!("{endpoint} ({reason})"))
.collect::<Vec<_>>()
.join("; ")
}
impl From<NodeConfigError> for NodeError {
fn from(error: NodeConfigError) -> Self {
Self::Config(error)
}
}
impl From<TransportError> for NodeError {
fn from(error: TransportError) -> Self {
Self::Transport(error)
}
}
impl From<WireError> for NodeError {
fn from(error: WireError) -> Self {
Self::Wire(error)
}
}
impl From<DataError> for NodeError {
fn from(error: DataError) -> Self {
Self::Data(error)
}
}
impl From<IpcError> for NodeError {
fn from(error: IpcError) -> Self {
Self::Ipc(error)
}
}
impl From<TypeUrnError> for NodeError {
fn from(error: TypeUrnError) -> Self {
Self::TypeUrn(error)
}
}
impl From<ShmError> for NodeError {
fn from(error: ShmError) -> Self {
Self::Shm(error)
}
}
impl From<IdError> for NodeError {
fn from(error: IdError) -> Self {
Self::Id(error)
}
}
impl From<SchedulerError> for NodeError {
fn from(error: SchedulerError) -> Self {
Self::Scheduler(error)
}
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
fn every_variant() -> Vec<NodeError> {
vec![
NodeError::Config(NodeConfigError::Base64(
astrs_wire::Base64Error::NonCanonicalTail,
)),
NodeError::MissingEnv {
name: "ASTRS_NODE_CONFIG",
},
NodeError::BadEnv {
name: "ASTRS_TYPE_CHECK",
value: "loud".to_owned(),
reason: "expected off, warn or error".to_owned(),
},
NodeError::Connect {
attempts: vec![("uds:/tmp/x".to_owned(), "refused".to_owned())],
},
NodeError::Handshake("refused".to_owned()),
NodeError::Registration("wrong generation".to_owned()),
NodeError::DaemonGone,
NodeError::Transport(TransportError::Closed {
reason: astrs_transport::CloseReason::Eof,
}),
NodeError::Wire(WireError::MissingCrc),
NodeError::Data(DataError::AllocationFailed { bytes: 8 }),
NodeError::Ipc(IpcError::EmptyStream),
NodeError::TypeUrn(TypeUrnError::UnknownType {
urn: "std/core/v1/Nope".to_owned(),
}),
NodeError::Shm(ShmError::Closed {
name: "astrs-test".to_owned(),
}),
NodeError::Id(astrs_wire::DataId::new("bad name").unwrap_err()),
NodeError::Scheduler(SchedulerError::DuplicateInput(
astrs_wire::DataId::new("x").unwrap(),
)),
NodeError::UnknownOutput {
output: astrs_wire::DataId::new("nope").unwrap(),
},
NodeError::UnknownInput {
input: astrs_wire::DataId::new("nope").unwrap(),
},
NodeError::TypeMismatch {
port: astrs_wire::DataId::new("image").unwrap(),
declared: "std/media/v1/Image".to_owned(),
requested: "std/core/v1/Float64".to_owned(),
},
NodeError::PayloadTooLarge { len: 1, max: 0 },
NodeError::BlockingInAsync {
method: "EventStream::recv",
alternative: "EventStream::recv_async",
},
NodeError::Stopped,
NodeError::Orphaned { parent_pid: 7 },
NodeError::Timeout {
operation: "ext_load",
millis: 500,
},
NodeError::Backpressure { depth: 64 },
NodeError::Runtime("no threads".to_owned()),
NodeError::Pattern("respond() without a request_id".to_owned()),
NodeError::Testing("no such node".to_owned()),
]
}
#[test]
fn every_variant_renders_and_classifies() {
for error in every_variant() {
assert!(!error.to_string().is_empty(), "{error:?}");
assert!(!error.kind_name().is_empty(), "{error:?}");
assert!(error.exit_code() == 0 || error.exit_code() == 1);
let _: &dyn std::error::Error = &error;
}
}
#[test]
fn kind_names_are_unique() {
let mut names: Vec<&str> = every_variant().iter().map(NodeError::kind_name).collect();
let total = names.len();
names.sort_unstable();
names.dedup();
assert_eq!(names.len(), total, "kind names must identify a variant");
}
#[test]
fn shutdown_errors_exit_zero() {
assert!(NodeError::Stopped.is_shutdown());
assert_eq!(NodeError::Stopped.exit_code(), 0);
assert!(NodeError::Orphaned { parent_pid: 3 }.is_shutdown());
assert_eq!(NodeError::Orphaned { parent_pid: 3 }.exit_code(), 0);
assert!(!NodeError::DaemonGone.is_shutdown());
assert_eq!(NodeError::DaemonGone.exit_code(), 1);
}
#[test]
fn retryable_and_usage_classes_are_disjoint() {
for error in every_variant() {
assert!(
!(error.is_retryable() && error.is_usage_error()),
"{error:?} cannot be both"
);
}
assert!(NodeError::Backpressure { depth: 1 }.is_retryable());
assert!(
NodeError::BlockingInAsync {
method: "a",
alternative: "b"
}
.is_usage_error()
);
}
#[test]
fn stop_causes_are_reported_only_for_endings() {
assert_eq!(NodeError::Stopped.stop_cause(), Some(StopCause::Requested));
assert_eq!(
NodeError::DaemonGone.stop_cause(),
Some(StopCause::DaemonShutdown)
);
assert_eq!(NodeError::Handshake(String::new()).stop_cause(), None);
}
#[test]
fn connect_errors_list_every_attempt() {
let error = NodeError::Connect {
attempts: vec![
(
"uds:/run/astrs/daemon.sock".to_owned(),
"refused".to_owned(),
),
("tcp:127.0.0.1:7408".to_owned(), "timed out".to_owned()),
],
};
let text = error.to_string();
assert!(text.contains("daemon.sock"), "{text}");
assert!(text.contains("127.0.0.1:7408"), "{text}");
assert!(
text.contains("refused") && text.contains("timed out"),
"{text}"
);
let empty = NodeError::Connect {
attempts: Vec::new(),
};
assert!(empty.to_string().contains("no endpoints"));
}
#[test]
fn conversions_wrap_rather_than_flatten() {
let wire: NodeError = WireError::MissingCrc.into();
assert_eq!(wire.kind_name(), "wire");
let id: NodeError = astrs_wire::DataId::new("").unwrap_err().into();
assert_eq!(id.kind_name(), "id");
let shm: NodeError = ShmError::Closed {
name: "astrs-test".to_owned(),
}
.into();
assert_eq!(shm.kind_name(), "shm");
let data: NodeError = DataError::AllocationFailed { bytes: 8 }.into();
assert_eq!(data.kind_name(), "data");
}
}