astrs_data/ipc/error.rs
1//! [`IpcError`] — everything that can go wrong encoding or decoding an Arrow
2//! IPC stream.
3//!
4//! The IPC layer keeps its own error type rather than extending
5//! [`crate::DataError`]: a malformed *stream* and an invalid
6//! *array* are different failures with different recovery paths, and the
7//! decoder wants to name the exact flatbuffer field it choked on. Array
8//! construction errors surfacing from the columnar core are wrapped in
9//! [`IpcError::Data`].
10//!
11//! Every decode-side variant carries enough context to locate the problem in
12//! a hex dump: a byte position, a table and field name, or the offending
13//! numeric code.
14//!
15//! ```
16//! use astrs_data::ipc::{IpcError, IpcStreamReader};
17//!
18//! // A stream that stops in the middle of the metadata length prefix.
19//! let err = IpcStreamReader::from_slice(&[0xFF, 0xFF, 0xFF, 0xFF, 0x10]).unwrap_err();
20//! assert!(matches!(err, IpcError::UnexpectedEndOfStream { .. }));
21//! ```
22
23use std::fmt;
24
25use crate::error::DataError;
26
27/// The result type of the IPC layer.
28pub type Result<T, E = IpcError> = std::result::Result<T, E>;
29
30/// A failure encoding or decoding an Arrow IPC stream.
31///
32/// `#[non_exhaustive]`: the append-only evolution rule (blueprint §3.4)
33/// applies to error enums too.
34#[derive(Debug, thiserror::Error)]
35#[non_exhaustive]
36pub enum IpcError {
37 /// The underlying reader or writer failed.
38 #[error("io error while {context}: {source}")]
39 Io {
40 /// What the layer was doing when the I/O failed.
41 context: &'static str,
42 /// The originating error.
43 #[source]
44 source: std::io::Error,
45 },
46
47 /// An array could not be rebuilt from its decoded buffers.
48 #[error(transparent)]
49 Data(#[from] DataError),
50
51 /// The stream ended in the middle of a message.
52 #[error(
53 "stream ended after {available} byte(s) while {expected} more were required ({context})"
54 )]
55 UnexpectedEndOfStream {
56 /// What the decoder was reading.
57 context: &'static str,
58 /// Bytes still available.
59 available: usize,
60 /// Bytes the decoder needed.
61 expected: usize,
62 },
63
64 /// The 4-byte word introducing a message was neither the continuation
65 /// marker nor a plausible legacy length.
66 #[error("invalid message prefix {marker:#010x} at byte {position}")]
67 InvalidContinuation {
68 /// The word that was read.
69 marker: u32,
70 /// Byte offset of the word within the stream.
71 position: usize,
72 },
73
74 /// The encapsulated-message header declared a negative metadata length.
75 #[error("negative metadata length {length} at byte {position}")]
76 NegativeMetadataLength {
77 /// The declared length.
78 length: i32,
79 /// Byte offset of the length prefix.
80 position: usize,
81 },
82
83 /// A declared length exceeded the configured cap.
84 #[error("{what} of {} exceeds the {} cap", ByteCount(*length), ByteCount(*cap))]
85 TooLarge {
86 /// Which length was too large ("metadata", "body", "payload").
87 what: &'static str,
88 /// The declared length.
89 length: u64,
90 /// The cap that was exceeded.
91 cap: u64,
92 },
93
94 /// The flatbuffer metadata is structurally invalid.
95 #[error("malformed flatbuffer at byte {position}: {context}")]
96 MalformedFlatbuffer {
97 /// What the reader was trying to do.
98 context: &'static str,
99 /// Byte offset within the metadata block.
100 position: usize,
101 },
102
103 /// A required flatbuffer field was absent.
104 #[error("missing required field {field} of table {table}")]
105 MissingField {
106 /// The flatbuffer table name, as in `Schema.fbs`/`Message.fbs`.
107 table: &'static str,
108 /// The absent field name.
109 field: &'static str,
110 },
111
112 /// `Message.version` named a metadata version this decoder does not read.
113 #[error("unsupported Arrow metadata version {version} (V4 and V5 are supported)")]
114 UnsupportedMetadataVersion {
115 /// The raw enum value.
116 version: i16,
117 },
118
119 /// `Schema.endianness` was big-endian.
120 #[error("unsupported endianness {endianness} (only little-endian streams are read)")]
121 UnsupportedEndianness {
122 /// The raw enum value.
123 endianness: i16,
124 },
125
126 /// `Message.header_type` named a message kind AstRS does not implement.
127 #[error("unsupported message header {header} ({name})")]
128 UnsupportedMessageHeader {
129 /// The raw union discriminant.
130 header: u8,
131 /// A human-readable name for the discriminant.
132 name: &'static str,
133 },
134
135 /// A message of the wrong kind turned up where another was required.
136 #[error("expected a {expected} message, found {found}")]
137 UnexpectedMessage {
138 /// The message the decoder needed.
139 expected: &'static str,
140 /// The message it found.
141 found: &'static str,
142 },
143
144 /// The stream carried no schema message.
145 #[error("stream is empty: no schema message")]
146 EmptyStream,
147
148 /// `Field.type` named a type outside the closed P0 set (blueprint §6.1).
149 #[error("unsupported Arrow type {code} ({name}) for field {field:?}")]
150 UnsupportedType {
151 /// The raw `Type` union discriminant.
152 code: u8,
153 /// A human-readable name for the discriminant.
154 name: &'static str,
155 /// The field that carried it.
156 field: String,
157 },
158
159 /// A supported type family carried an unsupported parameter — a 96-bit
160 /// integer, a microsecond timestamp, a time zone.
161 #[error("unsupported {family} parameters for field {field:?}: {detail}")]
162 UnsupportedTypeParameters {
163 /// The type family (`Int`, `Timestamp`, ...).
164 family: &'static str,
165 /// The field that carried it.
166 field: String,
167 /// What exactly is unsupported.
168 detail: String,
169 },
170
171 /// A nested type declared the wrong number of children.
172 #[error(
173 "field {field:?} of type {family} declares {actual} child field(s), {expected} expected"
174 )]
175 ChildCountMismatch {
176 /// The field name.
177 field: String,
178 /// The type family.
179 family: &'static str,
180 /// Children the type requires.
181 expected: usize,
182 /// Children the message declared.
183 actual: usize,
184 },
185
186 /// The record batch declared fewer field nodes or buffers than the schema
187 /// needs, or left some unconsumed.
188 #[error("record batch declares {actual} {what}, the schema needs {expected}")]
189 LayoutCountMismatch {
190 /// `"field node(s)"` or `"buffer(s)"`.
191 what: &'static str,
192 /// What the schema implies.
193 expected: usize,
194 /// What the message declared.
195 actual: usize,
196 },
197
198 /// A `Buffer` entry pointed outside the message body.
199 #[error("buffer {index} at ({offset}, {length}) leaves the {body_len}-byte body")]
200 BufferOutOfBounds {
201 /// Index within the `buffers` vector.
202 index: usize,
203 /// Declared body-relative offset.
204 offset: i64,
205 /// Declared length.
206 length: i64,
207 /// Actual body length.
208 body_len: usize,
209 },
210
211 /// A buffer was shorter than the field node's row count requires.
212 #[error(
213 "buffer {index} ({role}) holds {actual} byte(s), {required} required for {rows} row(s)"
214 )]
215 BufferTooShort {
216 /// Index within the `buffers` vector.
217 index: usize,
218 /// `"validity"`, `"offsets"` or `"values"`.
219 role: &'static str,
220 /// Bytes the buffer holds.
221 actual: usize,
222 /// Bytes the layout requires.
223 required: usize,
224 /// Row count from the field node.
225 rows: usize,
226 },
227
228 /// A `FieldNode` declared a negative or absurd length.
229 #[error("field node {index} declares length {length} and null count {null_count}")]
230 InvalidFieldNode {
231 /// Index within the `nodes` vector.
232 index: usize,
233 /// Declared length.
234 length: i64,
235 /// Declared null count.
236 null_count: i64,
237 },
238
239 /// Columns of a record batch disagreed with `RecordBatch.length`.
240 #[error("record batch declares {declared} row(s) but column {column} holds {actual}")]
241 RowCountMismatch {
242 /// `RecordBatch.length`.
243 declared: usize,
244 /// The offending column index.
245 column: usize,
246 /// The column's own length.
247 actual: usize,
248 },
249
250 /// The body carried a compression codec; AstRS negotiates compression at
251 /// the route level instead (blueprint §6.4).
252 #[error("body compression (codec {codec}) is not supported in AstRS payloads")]
253 UnsupportedCompression {
254 /// The raw `CompressionType` value.
255 codec: i8,
256 },
257
258 /// A dictionary-encoded field or a `DictionaryBatch` message turned up.
259 #[error("dictionary encoding is not part of the AstRS 0.1.0 type set")]
260 UnsupportedDictionary,
261
262 /// [`decode_payload`](crate::ipc::decode_payload) requires exactly one
263 /// record batch.
264 #[error("payload holds {count} record batch(es), exactly one is required")]
265 NotASinglePayload {
266 /// Batches found in the stream.
267 count: usize,
268 },
269
270 /// A type nested deeper than the codec's recursion limit.
271 ///
272 /// Both codecs recurse, so an unbounded nesting depth is a stack overflow
273 /// waiting for a hostile stream; the limit is
274 /// [`MAX_NESTING_DEPTH`](crate::ipc::layout::MAX_NESTING_DEPTH).
275 #[error("type nests {depth} level(s) deep, the limit is {limit}")]
276 NestingTooDeep {
277 /// The depth reached.
278 depth: usize,
279 /// The configured limit.
280 limit: usize,
281 },
282
283 /// [`write_ipc_stream`](crate::ipc::write_ipc_stream) was handed no
284 /// batches, so it has no schema to open the stream with.
285 #[error("cannot write a stream without a schema: no record batches were given")]
286 MissingSchema,
287
288 /// A batch's schema differs from the one the stream opened with.
289 ///
290 /// The streaming format has exactly one schema message, so every batch
291 /// must match it. Use one stream per schema, or cast the batch first.
292 #[error("record batch {index} does not match the schema the stream opened with")]
293 SchemaMismatch {
294 /// Position of the offending batch within the stream.
295 index: usize,
296 },
297}
298
299impl IpcError {
300 /// Wraps an I/O error with the operation that produced it.
301 #[must_use]
302 pub fn io(context: &'static str, source: std::io::Error) -> Self {
303 Self::Io { context, source }
304 }
305
306 /// Builds an [`IpcError::MalformedFlatbuffer`].
307 #[must_use]
308 pub const fn malformed(context: &'static str, position: usize) -> Self {
309 Self::MalformedFlatbuffer { context, position }
310 }
311
312 /// Builds an [`IpcError::MissingField`].
313 #[must_use]
314 pub const fn missing(table: &'static str, field: &'static str) -> Self {
315 Self::MissingField { table, field }
316 }
317
318 /// Returns `true` when the error means "the input bytes are not a valid
319 /// Arrow IPC stream", as opposed to an I/O failure or an unsupported but
320 /// well-formed feature.
321 ///
322 /// Route supervisors use this to decide between retrying a leg and
323 /// declaring a producer broken.
324 ///
325 /// ```
326 /// use astrs_data::ipc::IpcError;
327 ///
328 /// let malformed = IpcError::malformed("reading a vtable", 12);
329 /// assert!(malformed.is_malformed());
330 /// assert!(!IpcError::UnsupportedDictionary.is_malformed());
331 /// ```
332 #[must_use]
333 pub const fn is_malformed(&self) -> bool {
334 matches!(
335 self,
336 Self::UnexpectedEndOfStream { .. }
337 | Self::InvalidContinuation { .. }
338 | Self::NegativeMetadataLength { .. }
339 | Self::MalformedFlatbuffer { .. }
340 | Self::MissingField { .. }
341 | Self::LayoutCountMismatch { .. }
342 | Self::BufferOutOfBounds { .. }
343 | Self::BufferTooShort { .. }
344 | Self::InvalidFieldNode { .. }
345 | Self::RowCountMismatch { .. }
346 | Self::ChildCountMismatch { .. }
347 | Self::NestingTooDeep { .. }
348 )
349 }
350
351 /// Returns `true` when the stream is well-formed Arrow that carries a
352 /// feature outside the AstRS 0.1.0 set (blueprint §6.1).
353 ///
354 /// ```
355 /// use astrs_data::ipc::IpcError;
356 ///
357 /// assert!(IpcError::UnsupportedDictionary.is_unsupported());
358 /// ```
359 #[must_use]
360 pub const fn is_unsupported(&self) -> bool {
361 matches!(
362 self,
363 Self::UnsupportedMetadataVersion { .. }
364 | Self::UnsupportedEndianness { .. }
365 | Self::UnsupportedMessageHeader { .. }
366 | Self::UnsupportedType { .. }
367 | Self::UnsupportedTypeParameters { .. }
368 | Self::UnsupportedCompression { .. }
369 | Self::UnsupportedDictionary
370 )
371 }
372}
373
374/// Formats a byte count with a unit, for the size-cap error messages.
375pub(crate) struct ByteCount(pub u64);
376
377impl fmt::Display for ByteCount {
378 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
379 const UNITS: [&str; 5] = ["B", "KiB", "MiB", "GiB", "TiB"];
380 let mut value = self.0 as f64;
381 let mut unit = 0usize;
382 while value >= 1024.0 && unit + 1 < UNITS.len() {
383 value /= 1024.0;
384 unit += 1;
385 }
386 if unit == 0 {
387 write!(f, "{} {}", self.0, UNITS[unit])
388 } else {
389 write!(f, "{value:.1} {}", UNITS[unit])
390 }
391 }
392}
393
394#[cfg(test)]
395mod tests {
396 #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
397
398 use super::*;
399
400 #[test]
401 fn io_errors_carry_context() {
402 let err = IpcError::io(
403 "writing the schema message",
404 std::io::Error::new(std::io::ErrorKind::BrokenPipe, "gone"),
405 );
406 let text = err.to_string();
407 assert!(text.contains("writing the schema message"), "{text}");
408 assert!(text.contains("gone"), "{text}");
409 }
410
411 #[test]
412 fn malformed_classification_is_exclusive() {
413 let malformed = [
414 IpcError::malformed("x", 0),
415 IpcError::missing("Message", "header"),
416 IpcError::UnexpectedEndOfStream {
417 context: "metadata",
418 available: 1,
419 expected: 8,
420 },
421 ];
422 for err in malformed {
423 assert!(err.is_malformed(), "{err}");
424 assert!(!err.is_unsupported(), "{err}");
425 }
426 let unsupported = [
427 IpcError::UnsupportedDictionary,
428 IpcError::UnsupportedMetadataVersion { version: 1 },
429 IpcError::UnsupportedCompression { codec: 0 },
430 ];
431 for err in unsupported {
432 assert!(err.is_unsupported(), "{err}");
433 assert!(!err.is_malformed(), "{err}");
434 }
435 }
436
437 #[test]
438 fn data_errors_convert() {
439 let err: IpcError = DataError::UnknownStructLength.into();
440 assert!(matches!(err, IpcError::Data(_)));
441 assert!(!err.is_malformed());
442 }
443
444 #[test]
445 fn byte_count_formats_units() {
446 assert_eq!(ByteCount(512).to_string(), "512 B");
447 assert_eq!(ByteCount(2048).to_string(), "2.0 KiB");
448 assert_eq!(ByteCount(256 * 1024 * 1024).to_string(), "256.0 MiB");
449 }
450
451 #[test]
452 fn messages_name_the_offending_value() {
453 let err = IpcError::UnsupportedType {
454 code: 17,
455 name: "Map",
456 field: "labels".into(),
457 };
458 let text = err.to_string();
459 assert!(text.contains("Map"), "{text}");
460 assert!(text.contains("labels"), "{text}");
461
462 let err = IpcError::BufferOutOfBounds {
463 index: 3,
464 offset: 64,
465 length: 4096,
466 body_len: 128,
467 };
468 assert!(err.to_string().contains("128-byte body"));
469 }
470}