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}