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}