Skip to main content

astrs_data/
error.rs

1//! The crate-wide error type.
2//!
3//! `astrs-data` funnels every recoverable failure through [`DataError`]. The
4//! variants are deliberately structured (fields, not pre-formatted strings) so
5//! callers — the node API, the daemon, the CLI diagnostics — can react to a
6//! specific failure without parsing text.
7//!
8//! [`DataError`] is `Clone + PartialEq + Eq`, which keeps assertions in tests
9//! and in the conformance zoo readable:
10//!
11//! ```
12//! use astrs_data::{Bitmap, DataError};
13//!
14//! let bits = Bitmap::new_set(10);
15//! assert_eq!(
16//!     bits.try_slice(8, 5).unwrap_err(),
17//!     DataError::SliceOutOfBounds { offset: 8, len: 5, available: 10 }
18//! );
19//! ```
20
21use crate::datatype::DataType;
22use crate::urn::TypeUrnError;
23
24/// Result alias used throughout `astrs-data`.
25pub type Result<T, E = DataError> = core::result::Result<T, E>;
26
27/// Every recoverable failure the columnar core can report.
28///
29/// The enum is `#[non_exhaustive]`: stages 2 and 3 (Arrow IPC, kernels) extend
30/// it at the tail, and downstream crates must keep a wildcard arm.
31#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
32#[non_exhaustive]
33pub enum DataError {
34    /// A requested buffer capacity cannot be expressed as a valid allocation
35    /// layout (it overflows `isize::MAX` once padded to the 64-byte alignment).
36    #[error("buffer capacity overflow: {requested} bytes cannot be allocated")]
37    CapacityOverflow {
38        /// The capacity, in bytes, that was requested.
39        requested: usize,
40    },
41
42    /// The global allocator refused an allocation.
43    #[error("allocation of {bytes} bytes failed")]
44    AllocationFailed {
45        /// Size of the failed allocation, in bytes.
46        bytes: usize,
47    },
48
49    /// A buffer is shorter than the layout it is supposed to back.
50    #[error("buffer holds {actual} bytes but {required} are required")]
51    BufferTooSmall {
52        /// Bytes the layout needs.
53        required: usize,
54        /// Bytes the buffer actually holds.
55        actual: usize,
56    },
57
58    /// A byte window cannot be reinterpreted as a typed slice because its
59    /// start address is not aligned for the element type.
60    #[error("buffer address is {actual}-byte aligned but {required}-byte alignment is required")]
61    UnalignedBuffer {
62        /// Alignment the element type requires, in bytes.
63        required: usize,
64        /// Largest power-of-two alignment the buffer address actually has.
65        actual: usize,
66    },
67
68    /// A byte window cannot be reinterpreted as a typed slice because its
69    /// length is not a whole number of elements.
70    #[error("buffer length {len} is not a multiple of the {width}-byte element width")]
71    BufferLengthNotMultiple {
72        /// Length of the byte window.
73        len: usize,
74        /// Width of one element, in bytes.
75        width: usize,
76    },
77
78    /// String data failed UTF-8 validation.
79    #[error("invalid UTF-8 in string values: first error at byte {valid_up_to}")]
80    InvalidUtf8 {
81        /// Index of the first byte that is not part of a valid sequence.
82        valid_up_to: usize,
83    },
84
85    /// An offset in a `Utf8`/`LargeUtf8` array splits a multi-byte code point.
86    ///
87    /// The concatenated value region can be valid UTF-8 while an individual
88    /// slice boundary is not — both checks are required.
89    #[error("offset {offset} (entry {index}) is not a UTF-8 character boundary")]
90    OffsetNotCharBoundary {
91        /// Index of the offending entry in the offset buffer.
92        index: usize,
93        /// The byte offset that fell inside a code point.
94        offset: usize,
95    },
96
97    /// An offset buffer does not have `len + 1` entries.
98    #[error("offset buffer holds {actual} entries but {expected} are required")]
99    OffsetBufferLength {
100        /// Entries required (`array length + 1`).
101        expected: usize,
102        /// Entries present.
103        actual: usize,
104    },
105
106    /// An offset buffer is not monotonically non-decreasing.
107    #[error("offsets are not monotonic: entry {index} ({offset}) precedes entry {index}-1")]
108    NonMonotonicOffsets {
109        /// Index of the first offset smaller than its predecessor.
110        index: usize,
111        /// Value of that offset.
112        offset: i64,
113    },
114
115    /// An offset buffer contains a negative entry.
116    #[error("offset entry {index} is negative ({offset})")]
117    NegativeOffset {
118        /// Index of the negative entry.
119        index: usize,
120        /// Value of that entry.
121        offset: i64,
122    },
123
124    /// The last offset points past the end of the values buffer.
125    #[error("offset entry {index} ({offset}) exceeds the {values_len}-byte value region")]
126    OffsetOutOfBounds {
127        /// Index of the offending entry.
128        index: usize,
129        /// Value of that entry.
130        offset: usize,
131        /// Length of the region the offsets index into.
132        values_len: usize,
133    },
134
135    /// A validity bitmap does not cover exactly the array's logical length.
136    #[error("validity bitmap covers {validity_len} slots but the array has {array_len}")]
137    ValidityLengthMismatch {
138        /// Logical length of the array.
139        array_len: usize,
140        /// Number of bits in the supplied bitmap.
141        validity_len: usize,
142    },
143
144    /// Two bitmaps of different lengths were combined.
145    #[error("bitmap length mismatch: {left} vs {right}")]
146    BitmapLengthMismatch {
147        /// Length of the left operand.
148        left: usize,
149        /// Length of the right operand.
150        right: usize,
151    },
152
153    /// A checked `try_slice` request left the available range.
154    ///
155    /// The infallible `slice` methods clamp instead of reporting this.
156    #[error("slice [{offset}, {offset}+{len}) leaves the available range of {available}")]
157    SliceOutOfBounds {
158        /// Start of the requested window.
159        offset: usize,
160        /// Length of the requested window.
161        len: usize,
162        /// Length actually available.
163        available: usize,
164    },
165
166    /// A checked element access left the array.
167    #[error("index {index} is out of bounds for length {len}")]
168    IndexOutOfBounds {
169        /// The index that was requested.
170        index: usize,
171        /// Length of the collection.
172        len: usize,
173    },
174
175    /// A `FixedSizeBinary`/`FixedSizeList` width is not a positive value.
176    #[error("fixed size must be positive, got {size}")]
177    InvalidFixedSize {
178        /// The rejected width.
179        size: i32,
180    },
181
182    /// A nested array's child does not have the length its parent implies.
183    #[error("child array holds {actual} values but the parent implies {expected}")]
184    ChildLengthMismatch {
185        /// Length the parent layout implies.
186        expected: usize,
187        /// Length the child actually has.
188        actual: usize,
189    },
190
191    /// A value's data type does not match the type its container declares.
192    #[error("type mismatch: expected {expected}, found {actual}")]
193    TypeMismatch {
194        /// Type the container declares.
195        expected: Box<DataType>,
196        /// Type actually supplied.
197        actual: Box<DataType>,
198    },
199
200    /// A dynamic downcast on an [`crate::array::ArrayRef`] failed.
201    #[error("cannot downcast an array of type {actual} to {expected}")]
202    DowncastFailed {
203        /// Rust type name of the requested concrete array.
204        expected: &'static str,
205        /// Data type of the array actually held.
206        actual: Box<DataType>,
207    },
208
209    /// A record batch was built with a column count that disagrees with its
210    /// schema.
211    #[error("schema declares {fields} field(s) but {columns} column(s) were supplied")]
212    ColumnCountMismatch {
213        /// Number of fields in the schema.
214        fields: usize,
215        /// Number of columns supplied.
216        columns: usize,
217    },
218
219    /// A record batch column has a different length from the batch.
220    #[error("column {index} ({name}) holds {actual} rows but the batch has {expected}")]
221    ColumnLengthMismatch {
222        /// Position of the offending column.
223        index: usize,
224        /// Name of the field the column belongs to.
225        name: String,
226        /// Row count the batch declares.
227        expected: usize,
228        /// Row count the column has.
229        actual: usize,
230    },
231
232    /// A column carries nulls for a field the schema declares non-nullable.
233    #[error("column {index} ({name}) holds {null_count} null(s) in a non-nullable field")]
234    NullsInNonNullableColumn {
235        /// Position of the offending column.
236        index: usize,
237        /// Name of the field.
238        name: String,
239        /// Number of nulls found.
240        null_count: usize,
241    },
242
243    /// A schema declares the same field name twice.
244    #[error("duplicate field name {name:?} in schema")]
245    DuplicateFieldName {
246        /// The repeated name.
247        name: String,
248    },
249
250    /// A field lookup by name found nothing.
251    #[error("no field named {name:?} in schema")]
252    FieldNotFound {
253        /// The name that was looked up.
254        name: String,
255    },
256
257    /// A struct array was built without children and without an explicit
258    /// length, so its logical length is undefined.
259    #[error("a struct array with no child columns needs an explicit length")]
260    UnknownStructLength,
261
262    /// A type URN could not be parsed or resolved.
263    #[error(transparent)]
264    TypeUrn(#[from] TypeUrnError),
265
266    /// A [`crate::tensor::TensorView`] was built from a flat buffer whose
267    /// length does not equal the product of the requested shape.
268    #[error("tensor shape implies {expected} elements but the buffer holds {actual}")]
269    TensorShapeMismatch {
270        /// Product of the requested shape's dimensions.
271        expected: usize,
272        /// Length of the buffer actually supplied.
273        actual: usize,
274    },
275
276    /// A [`crate::tensor::TensorView`] shape's dimensions multiply out to
277    /// more elements than `usize` can count.
278    ///
279    /// Reported instead of letting the product silently wrap (or panic on a
280    /// debug build) — no real buffer can back such a shape, so this is
281    /// always a caller/decode mistake, never a size this crate could ever
282    /// satisfy.
283    #[error("tensor shape {shape:?} needs more elements than usize can represent")]
284    TensorShapeOverflow {
285        /// The requested shape, verbatim.
286        shape: Vec<usize>,
287    },
288
289    /// A [`crate::tensor::TensorView`] index did not name one component per
290    /// dimension.
291    #[error("tensor index has {actual} component(s) but the tensor has {expected} dimension(s)")]
292    TensorRankMismatch {
293        /// The tensor's dimensionality.
294        expected: usize,
295        /// Components the index actually supplied.
296        actual: usize,
297    },
298
299    /// A [`crate::tensor::TensorView`] axis operation named an axis the
300    /// tensor does not have.
301    #[error("axis {axis} is out of bounds for a {ndim}-dimensional tensor")]
302    TensorAxisOutOfBounds {
303        /// The axis that was requested.
304        axis: usize,
305        /// The tensor's dimensionality.
306        ndim: usize,
307    },
308
309    /// A [`crate::tensor::TensorView`] index's component for one axis is not
310    /// smaller than that axis's extent.
311    #[error("index {index} is out of bounds for axis {axis} (extent {dim})")]
312    TensorIndexOutOfBounds {
313        /// The axis the offending component belongs to.
314        axis: usize,
315        /// The component's value.
316        index: usize,
317        /// The axis's extent.
318        dim: usize,
319    },
320
321    /// A row-level accessor (for example
322    /// [`crate::tensor::ImageView::from_struct_row`]) found a null in a
323    /// field the layout declares non-nullable.
324    #[error("field {field:?} is null at row {row}, but the layout declares it non-nullable")]
325    RequiredFieldIsNull {
326        /// The field's name.
327        field: String,
328        /// The row at which it was found null.
329        row: usize,
330    },
331
332    /// [`crate::kernel::concat()`] (or a `Large*` narrowing
333    /// [`crate::kernel::cast()`]) needed more offset range than the
334    /// destination's offset width can express.
335    #[error("concatenated length {total} exceeds the {max}-byte/-element offset width")]
336    OffsetWidthOverflow {
337        /// Bytes or child elements the result would need.
338        total: usize,
339        /// The offset type's maximum representable value.
340        max: usize,
341    },
342
343    /// [`crate::kernel::cast()`] has no defined conversion between two types
344    /// (for example `Bool` to anything, or `Timestamp` to `Duration`
345    /// directly — the type system treats those as different units on
346    /// purpose; go through `Int64` explicitly if a conversion is really
347    /// intended).
348    #[error("no defined cast from {from} to {to}")]
349    UnsupportedCast {
350        /// The source type.
351        from: Box<DataType>,
352        /// The requested destination type.
353        to: Box<DataType>,
354    },
355
356    /// [`crate::kernel::cast()`] under [`crate::kernel::OverflowPolicy::Error`]
357    /// found a value that does not fit the destination type.
358    #[error("value at index {index} does not fit while casting {from} to {to}")]
359    CastOverflow {
360        /// The source type.
361        from: Box<DataType>,
362        /// The destination type.
363        to: Box<DataType>,
364        /// The offending row.
365        index: usize,
366    },
367
368    /// [`crate::kernel::filter()`]'s mask is a different length from the array
369    /// it is filtering.
370    #[error("filter mask holds {mask_len} value(s) but the array has {array_len}")]
371    MaskLengthMismatch {
372        /// The array's length.
373        array_len: usize,
374        /// The mask's length.
375        mask_len: usize,
376    },
377
378    /// [`crate::kernel::take()`] was given an index that is negative, does not
379    /// fit `usize`, or is not smaller than the source's length.
380    #[error("take index at position {position} does not name a row (source has {len})")]
381    TakeIndexInvalid {
382        /// The offending index's position within the indices array.
383        position: usize,
384        /// The source array's length.
385        len: usize,
386    },
387
388    /// [`crate::message::AstrsMessage::from_record_batch`] requires exactly
389    /// one row per message (blueprint §6.1's "one record batch per message"
390    /// convention), and the batch supplied did not have one.
391    #[error("expected exactly one message row but the batch has {actual}")]
392    MessageRowCount {
393        /// The batch's actual row count.
394        actual: usize,
395    },
396
397    /// A `[T; N]`-shaped message field ([`crate::message::AstrsMessage`])
398    /// decoded a slice with a different length than `N`.
399    ///
400    /// Unreachable in practice — [`crate::array::FixedSizeListArray`]
401    /// guarantees every row's child slice is exactly `N` elements wide by
402    /// construction — but `TryFrom<&[T]> for [T; N]` is still fallible at
403    /// the type level, so a `#[derive(AstrsMessage)]` decoder must handle
404    /// the branch rather than `unwrap`/`expect` it away.
405    #[error("fixed-size field {field:?} decoded {actual} element(s), expected {expected}")]
406    MessageFixedArrayLength {
407        /// The field's name.
408        field: String,
409        /// The array size the layout declares.
410        expected: usize,
411        /// The number of elements actually decoded.
412        actual: usize,
413    },
414}
415
416impl DataError {
417    /// Builds a [`DataError::TypeMismatch`] without repeating the boxing at
418    /// every call site.
419    ///
420    /// ```
421    /// use astrs_data::{DataError, DataType};
422    ///
423    /// let err = DataError::type_mismatch(DataType::Int32, DataType::Int64);
424    /// assert_eq!(err.to_string(), "type mismatch: expected Int32, found Int64");
425    /// ```
426    #[must_use]
427    pub fn type_mismatch(expected: DataType, actual: DataType) -> Self {
428        Self::TypeMismatch {
429            expected: Box::new(expected),
430            actual: Box::new(actual),
431        }
432    }
433
434    /// Builds a [`DataError::DowncastFailed`] for the concrete array type `A`.
435    #[must_use]
436    pub fn downcast_failed<A: ?Sized>(actual: DataType) -> Self {
437        Self::DowncastFailed {
438            expected: core::any::type_name::<A>(),
439            actual: Box::new(actual),
440        }
441    }
442
443    /// Builds a [`DataError::UnsupportedCast`] without repeating the boxing
444    /// at every call site.
445    #[must_use]
446    pub fn unsupported_cast(from: DataType, to: DataType) -> Self {
447        Self::UnsupportedCast {
448            from: Box::new(from),
449            to: Box::new(to),
450        }
451    }
452
453    /// Builds a [`DataError::CastOverflow`] without repeating the boxing at
454    /// every call site.
455    #[must_use]
456    pub fn cast_overflow(from: DataType, to: DataType, index: usize) -> Self {
457        Self::CastOverflow {
458            from: Box::new(from),
459            to: Box::new(to),
460            index,
461        }
462    }
463
464    /// Returns `true` when the error describes a malformed buffer layout
465    /// rather than a caller mistake.
466    ///
467    /// Stage 2 uses this to decide whether a decode failure should be reported
468    /// as a protocol violation (peer sent garbage) or as a local bug.
469    ///
470    /// ```
471    /// use astrs_data::DataError;
472    ///
473    /// assert!(DataError::InvalidUtf8 { valid_up_to: 3 }.is_layout_violation());
474    /// assert!(!DataError::IndexOutOfBounds { index: 9, len: 2 }.is_layout_violation());
475    /// ```
476    #[must_use]
477    pub const fn is_layout_violation(&self) -> bool {
478        matches!(
479            self,
480            Self::BufferTooSmall { .. }
481                | Self::UnalignedBuffer { .. }
482                | Self::BufferLengthNotMultiple { .. }
483                | Self::InvalidUtf8 { .. }
484                | Self::OffsetNotCharBoundary { .. }
485                | Self::OffsetBufferLength { .. }
486                | Self::NonMonotonicOffsets { .. }
487                | Self::NegativeOffset { .. }
488                | Self::OffsetOutOfBounds { .. }
489                | Self::ValidityLengthMismatch { .. }
490                | Self::ChildLengthMismatch { .. }
491                | Self::TensorShapeMismatch { .. }
492                | Self::TensorShapeOverflow { .. }
493                | Self::RequiredFieldIsNull { .. }
494        )
495    }
496}
497
498#[cfg(test)]
499mod tests {
500    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
501
502    use super::*;
503
504    #[test]
505    fn display_is_actionable() {
506        let err = DataError::ColumnLengthMismatch {
507            index: 1,
508            name: "name".to_owned(),
509            expected: 3,
510            actual: 2,
511        };
512        assert_eq!(
513            err.to_string(),
514            "column 1 (name) holds 2 rows but the batch has 3"
515        );
516    }
517
518    #[test]
519    fn type_urn_errors_flatten() {
520        let err: DataError = TypeUrnError::Empty.into();
521        assert_eq!(err.to_string(), TypeUrnError::Empty.to_string());
522    }
523
524    #[test]
525    fn helpers_construct_boxed_variants() {
526        let err = DataError::downcast_failed::<u32>(DataType::Utf8);
527        match err {
528            DataError::DowncastFailed { expected, actual } => {
529                assert_eq!(expected, "u32");
530                assert_eq!(*actual, DataType::Utf8);
531            }
532            other => panic!("unexpected variant: {other:?}"),
533        }
534    }
535
536    #[test]
537    fn layout_violations_are_classified() {
538        assert!(
539            DataError::NonMonotonicOffsets {
540                index: 1,
541                offset: -1
542            }
543            .is_layout_violation()
544        );
545        assert!(!DataError::UnknownStructLength.is_layout_violation());
546        assert!(
547            !DataError::CapacityOverflow {
548                requested: usize::MAX
549            }
550            .is_layout_violation()
551        );
552    }
553
554    #[test]
555    fn errors_compare_by_value() {
556        assert_eq!(
557            DataError::IndexOutOfBounds { index: 1, len: 0 },
558            DataError::IndexOutOfBounds { index: 1, len: 0 }
559        );
560        assert_ne!(
561            DataError::IndexOutOfBounds { index: 1, len: 0 },
562            DataError::IndexOutOfBounds { index: 2, len: 0 }
563        );
564    }
565}