Skip to main content

astrs_operator_api/
error.rs

1//! [`OpError`] — everything an operator or its host can report.
2//!
3//! Kept separate from [`astrs_data::DataError`] and [`astrs_data::ipc::IpcError`]
4//! the same way `astrs-data`'s own IPC layer keeps its error type separate
5//! from the columnar core's (see that crate's `ipc::error` docs): an
6//! operator failure and a malformed payload are different problems with
7//! different recovery paths, and wrapping keeps each one's context intact
8//! instead of flattening everything into strings.
9
10use astrs_wire::IdError;
11
12/// The result type every [`crate::Operator`] method and every
13/// [`crate::OpOutput`] send returns.
14pub type OpResult<T> = Result<T, OpError>;
15
16/// A failure inside the operator host's boundary (blueprint §9.3).
17///
18/// `#[non_exhaustive]`: the append-only evolution rule (blueprint §3.4)
19/// applies to this crate's error type too.
20#[derive(Debug, thiserror::Error)]
21#[non_exhaustive]
22pub enum OpError {
23    /// [`crate::OpOutput::send_bytes`], [`crate::OpOutput::send_batch`] or
24    /// [`crate::OpOutput::send`] was given a name that is not a valid
25    /// [`astrs_wire::DataId`].
26    #[error("output {id:?} is not a valid data id: {source}")]
27    InvalidOutputId {
28        /// The offending name, as given.
29        id: String,
30        /// Why [`astrs_wire::DataId::new`] rejected it.
31        #[source]
32        source: IdError,
33    },
34
35    /// [`crate::OpOutput::send`] or [`crate::OpOutput::send_batch`] failed to
36    /// build the outgoing [`astrs_data::RecordBatch`].
37    #[error(transparent)]
38    Encode(#[from] astrs_data::DataError),
39
40    /// [`crate::OpOutput::send`] or [`crate::OpOutput::send_batch`] failed to
41    /// encode the outgoing batch as an Arrow IPC payload.
42    #[error(transparent)]
43    Ipc(#[from] astrs_data::ipc::IpcError),
44
45    /// [`crate::OperatorRegistry::register`] was given a name already
46    /// registered.
47    #[error("operator {name:?} is already registered")]
48    DuplicateOperator {
49        /// The name that collided.
50        name: String,
51    },
52
53    /// [`crate::OperatorRegistry::build`] was asked for a name with no
54    /// registered constructor.
55    #[error("no operator registered as {name:?}")]
56    UnknownOperator {
57        /// The name that was requested.
58        name: String,
59    },
60
61    /// An operator reported its own domain failure.
62    ///
63    /// The escape hatch for operator authors whose failure does not fit any
64    /// of the structured variants above — still typed (a `String`, not a
65    /// panic), and still routed through the same `NodeFailed` reporting path
66    /// (blueprint §9.3: "panics are caught, reported as `NodeFailed`").
67    #[error("operator failed: {message}")]
68    Failed {
69        /// A human-readable description of the failure.
70        message: String,
71    },
72}
73
74impl OpError {
75    /// Builds an [`OpError::InvalidOutputId`] without repeating the id at
76    /// every call site.
77    #[must_use]
78    pub fn invalid_output_id(id: impl Into<String>, source: IdError) -> Self {
79        Self::InvalidOutputId {
80            id: id.into(),
81            source,
82        }
83    }
84
85    /// Builds an [`OpError::Failed`] from any displayable message.
86    ///
87    /// ```
88    /// use astrs_operator_api::OpError;
89    ///
90    /// let err = OpError::failed("model did not load");
91    /// assert_eq!(err.to_string(), "operator failed: model did not load");
92    /// ```
93    #[must_use]
94    pub fn failed(message: impl Into<String>) -> Self {
95        Self::Failed {
96            message: message.into(),
97        }
98    }
99}
100
101#[cfg(test)]
102mod tests {
103    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
104
105    use super::*;
106
107    #[test]
108    fn invalid_output_id_reports_the_offending_name() {
109        let source = astrs_wire::DataId::new("bad id").unwrap_err();
110        let err = OpError::invalid_output_id("bad id", source);
111        let message = err.to_string();
112        assert!(message.starts_with("output \"bad id\" is not a valid data id: "));
113        assert!(matches!(err, OpError::InvalidOutputId { .. }));
114    }
115
116    #[test]
117    fn duplicate_and_unknown_operator_messages() {
118        assert_eq!(
119            OpError::DuplicateOperator {
120                name: "crop".to_owned()
121            }
122            .to_string(),
123            "operator \"crop\" is already registered"
124        );
125        assert_eq!(
126            OpError::UnknownOperator {
127                name: "nope".to_owned()
128            }
129            .to_string(),
130            "no operator registered as \"nope\""
131        );
132    }
133
134    #[test]
135    fn encode_and_ipc_errors_convert_via_from() {
136        let data_err: OpError = astrs_data::DataError::MessageRowCount { actual: 2 }.into();
137        assert!(matches!(data_err, OpError::Encode(_)));
138    }
139
140    #[test]
141    fn failed_builds_a_readable_message() {
142        assert_eq!(OpError::failed("boom").to_string(), "operator failed: boom");
143    }
144}