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}