Skip to main content

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}