Skip to main content

astrs_data/
message.rs

1//! [`AstrsMessage`] — the trait a typed message implements to cross into
2//! columnar space (blueprint §9.1, §9.2).
3//!
4//! ```text
5//! #[derive(AstrsMessage)]                       // astrs-operator-macros
6//! #[astrs(urn = "std/vision/v1/Detections")]
7//! struct Detections { boxes: Vec<[f32; 4]>, scores: Vec<f32>, labels: Vec<u32> }
8//! ```
9//!
10//! The derive above (blueprint §9.1's canonical example) maps each field onto
11//! the closed columnar type set (§6.1) and implements this trait: struct
12//! fields become the columns of one [`crate::datatype::DataType::Struct`],
13//! wrapped in a one-row [`RecordBatch`] per the "one message per batch"
14//! convention.
15//!
16//! # Ownership
17//!
18//! This trait is declared here, in `astrs-data`, rather than in the crate
19//! that actually derives it (`astrs-operator-macros`) or the crate blueprint
20//! §9.1 shows using it (`astrs-node-api`): every one of those sits in a
21//! *higher* layer than `astrs-data` (blueprint §4.1's strictly-downward
22//! dependency rule), and `astrs-idl`'s planned ROS 2 codegen (§10.3) — a
23//! *sibling* Layer 2 crate to the node/operator APIs, generating types that
24//! implement both `CdrSerde` and `AstrsMessage` — needs to implement it too,
25//! without depending upward on either. `astrs-data` is the one crate every
26//! future implementor already depends on for its columnar types, so it is
27//! the only layer-legal home for the trait itself. `astrs-node-api` and the
28//! top-level `astrs` facade should re-export it (alongside the
29//! `#[derive(AstrsMessage)]` macro from `astrs-operator-macros`) from their
30//! own preludes once they land.
31//!
32//! # What the trait does not do
33//!
34//! It does not validate `URN` against the [`crate::urn`] registry itself —
35//! that is a runtime lookup ([`crate::urn::layout_of_str`]), and a message
36//! type's `data_type()` is a compile-time-fixed Rust value. A caller that
37//! wants the cross-check runs it explicitly:
38//!
39//! ```
40//! use astrs_data::urn::layout_of_str;
41//! use astrs_data::{AstrsMessage, DataType, Field, RecordBatch};
42//!
43//! struct Ping { value: f64 }
44//!
45//! impl AstrsMessage for Ping {
46//!     const URN: &'static str = "std/core/v1/Float64";
47//!
48//!     fn data_type() -> DataType {
49//!         DataType::Float64
50//!     }
51//!
52//!     fn to_record_batch(&self) -> astrs_data::Result<RecordBatch> {
53//!         use astrs_data::array::{Float64Array, IntoArrayRef};
54//!         Ok(RecordBatch::from_payload(
55//!             Float64Array::from_values([self.value]).into_array_ref(),
56//!         ))
57//!     }
58//!
59//!     fn from_record_batch(batch: &RecordBatch) -> astrs_data::Result<Self> {
60//!         use astrs_data::array::{ArrayExt, Float64Array};
61//!         use astrs_data::DataError;
62//!
63//!         if batch.num_rows() != 1 {
64//!             return Err(DataError::MessageRowCount { actual: batch.num_rows() });
65//!         }
66//!         let column = batch
67//!             .payload_column()
68//!             .ok_or(DataError::ColumnCountMismatch { fields: 1, columns: 0 })?;
69//!         let value = column
70//!             .try_downcast::<Float64Array>()?
71//!             .get(0)
72//!             .ok_or_else(|| DataError::RequiredFieldIsNull { field: "value".to_owned(), row: 0 })?;
73//!         Ok(Self { value })
74//!     }
75//! }
76//!
77//! let ping = Ping { value: 2.5 };
78//! let batch = ping.to_record_batch()?;
79//! assert_eq!(Ping::from_record_batch(&batch)?.value, 2.5);
80//! assert_eq!(layout_of_str(Ping::URN), Ok(Ping::data_type()));
81//! # Ok::<(), astrs_data::DataError>(())
82//! ```
83
84use crate::datatype::{DataType, Schema};
85use crate::error::Result;
86use crate::record_batch::RecordBatch;
87use crate::urn::{TypeUrn, TypeUrnError};
88
89/// A Rust type that maps onto a single-column AstRS payload (blueprint
90/// §6.1, §9.2).
91///
92/// See the [module documentation](self) for why this trait lives in
93/// `astrs-data` and what it deliberately leaves to callers.
94pub trait AstrsMessage: Sized {
95    /// The type URN this message's columnar layout is declared against
96    /// (blueprint §24.3), e.g. `"std/vision/v1/Detections"`.
97    const URN: &'static str;
98
99    /// The columnar layout [`AstrsMessage::to_record_batch`] produces and
100    /// [`AstrsMessage::from_record_batch`] expects.
101    fn data_type() -> DataType;
102
103    /// The single-column [`Schema`] wrapping [`AstrsMessage::data_type`]
104    /// under [`crate::DATA_COLUMN`] (blueprint §6.1).
105    #[must_use]
106    fn schema() -> Schema {
107        Schema::payload(Self::data_type(), false)
108    }
109
110    /// Parses [`AstrsMessage::URN`].
111    ///
112    /// # Errors
113    ///
114    /// Whatever [`TypeUrn::parse`] reports, wrapped through
115    /// [`crate::DataError::TypeUrn`]. A malformed constant is a programmer
116    /// error rather than a data error, but the parse is still fallible at
117    /// the type level — a `#[derive(AstrsMessage)]` impl's constant has
118    /// already passed the macro's own syntax check (see
119    /// `astrs-operator-macros`), so this should only ever fail for a
120    /// hand-written implementation.
121    fn type_urn() -> Result<TypeUrn, TypeUrnError> {
122        TypeUrn::parse(Self::URN)
123    }
124
125    /// Encodes one message into a one-row [`RecordBatch`] (blueprint §6.1's
126    /// "one record batch per message").
127    ///
128    /// # Errors
129    ///
130    /// A [`crate::DataError`] from whichever columnar constructor rejects
131    /// the value. Practically unreachable for a `#[derive(AstrsMessage)]`
132    /// impl, since the derive only emits calls that cannot disagree with
133    /// its own [`AstrsMessage::data_type`], but the trait stays fallible for
134    /// hand-written implementors.
135    fn to_record_batch(&self) -> Result<RecordBatch>;
136
137    /// Decodes one message from a one-row [`RecordBatch`].
138    ///
139    /// # Errors
140    ///
141    /// [`crate::DataError::MessageRowCount`] when `batch` does not hold
142    /// exactly one row, or another [`crate::DataError`] when a column's
143    /// shape or nullability disagrees with [`AstrsMessage::data_type`].
144    fn from_record_batch(batch: &RecordBatch) -> Result<Self>;
145}
146
147#[cfg(test)]
148mod tests {
149    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
150
151    use super::*;
152    use crate::array::{ArrayExt, Float64Array, IntoArrayRef, StructArray};
153    use crate::datatype::Field;
154    use crate::error::DataError;
155
156    /// A minimal hand-written implementor, exercising the trait's default
157    /// methods and error paths without needing the derive macro (which
158    /// lives in a higher-layer crate — see the module docs).
159    #[derive(Debug, PartialEq)]
160    struct Ping {
161        value: f64,
162    }
163
164    impl AstrsMessage for Ping {
165        const URN: &'static str = "std/core/v1/PingMsg";
166
167        fn data_type() -> DataType {
168            DataType::strukt([Field::required("value", DataType::Float64)])
169        }
170
171        fn to_record_batch(&self) -> Result<RecordBatch> {
172            let DataType::Struct(fields) = Self::data_type() else {
173                unreachable!("Ping::data_type is always a Struct")
174            };
175            let column = Float64Array::from_values([self.value]).into_array_ref();
176            let strukt = StructArray::try_new(fields, vec![column], None)?;
177            Ok(RecordBatch::from_payload(strukt.into_array_ref()))
178        }
179
180        fn from_record_batch(batch: &RecordBatch) -> Result<Self> {
181            if batch.num_rows() != 1 {
182                return Err(DataError::MessageRowCount {
183                    actual: batch.num_rows(),
184                });
185            }
186            let column = batch
187                .payload_column()
188                .ok_or(DataError::ColumnCountMismatch {
189                    fields: 1,
190                    columns: 0,
191                })?;
192            let strukt = column.try_downcast::<StructArray>()?;
193            let value_column = strukt
194                .columns()
195                .first()
196                .ok_or(DataError::ColumnCountMismatch {
197                    fields: 1,
198                    columns: 0,
199                })?;
200            let value = value_column
201                .try_downcast::<Float64Array>()?
202                .get(0)
203                .ok_or_else(|| DataError::RequiredFieldIsNull {
204                    field: "value".to_owned(),
205                    row: 0,
206                })?;
207            Ok(Self { value })
208        }
209    }
210
211    #[test]
212    fn round_trips_through_a_record_batch() {
213        let ping = Ping { value: 2.5 };
214        let batch = ping.to_record_batch().unwrap();
215        assert_eq!(batch.num_rows(), 1);
216        assert_eq!(Ping::from_record_batch(&batch).unwrap(), ping);
217    }
218
219    #[test]
220    fn schema_wraps_data_type_in_the_payload_column() {
221        let schema = Ping::schema();
222        assert_eq!(schema.len(), 1);
223        assert_eq!(
224            schema.field(0).map(Field::data_type),
225            Some(&Ping::data_type())
226        );
227        assert_eq!(schema.field(0).map(Field::name), Some(crate::DATA_COLUMN));
228    }
229
230    #[test]
231    fn type_urn_parses_the_constant() {
232        let urn = Ping::type_urn().unwrap();
233        assert_eq!(urn.as_str(), Ping::URN);
234    }
235
236    #[test]
237    fn decode_rejects_a_batch_that_is_not_exactly_one_row() {
238        let DataType::Struct(fields) = Ping::data_type() else {
239            unreachable!()
240        };
241        let column = Float64Array::from_values([1.0, 2.0]).into_array_ref();
242        let strukt = StructArray::try_new(fields, vec![column], None).unwrap();
243        let batch = RecordBatch::from_payload(strukt.into_array_ref());
244        assert_eq!(
245            Ping::from_record_batch(&batch).unwrap_err(),
246            DataError::MessageRowCount { actual: 2 }
247        );
248
249        let empty = StructArray::try_new_with_len(
250            Ping::data_type().children().into_iter().cloned().collect(),
251            vec![Float64Array::new_null(0).into_array_ref()],
252            0,
253            None,
254        )
255        .unwrap();
256        let empty_batch = RecordBatch::from_payload(empty.into_array_ref());
257        assert_eq!(
258            Ping::from_record_batch(&empty_batch).unwrap_err(),
259            DataError::MessageRowCount { actual: 0 }
260        );
261    }
262
263    #[test]
264    fn decode_rejects_a_null_required_field() {
265        let DataType::Struct(fields) = Ping::data_type() else {
266            unreachable!()
267        };
268        let column = Float64Array::new_null(1).into_array_ref();
269        let strukt = StructArray::try_new(fields, vec![column], None).unwrap();
270        let batch = RecordBatch::from_payload(strukt.into_array_ref());
271        assert_eq!(
272            Ping::from_record_batch(&batch).unwrap_err(),
273            DataError::RequiredFieldIsNull {
274                field: "value".to_owned(),
275                row: 0,
276            }
277        );
278    }
279
280    #[test]
281    fn decode_rejects_the_wrong_shape() {
282        // A payload column that isn't a `Struct` at all.
283        let column = Float64Array::from_values([1.0]).into_array_ref();
284        let batch = RecordBatch::from_payload(column);
285        assert!(Ping::from_record_batch(&batch).is_err());
286    }
287
288    #[test]
289    fn message_error_variants_report_useful_context() {
290        let row_count = DataError::MessageRowCount { actual: 3 };
291        assert_eq!(
292            row_count.to_string(),
293            "expected exactly one message row but the batch has 3"
294        );
295
296        let fixed = DataError::MessageFixedArrayLength {
297            field: "quat".to_owned(),
298            expected: 4,
299            actual: 3,
300        };
301        assert_eq!(
302            fixed.to_string(),
303            "fixed-size field \"quat\" decoded 3 element(s), expected 4"
304        );
305    }
306}