Skip to main content

cadkit_core/
error.rs

1//! Error type shared by all cadkit crates.
2
3/// Result alias using [`Error`].
4pub type Result<T, E = Error> = std::result::Result<T, E>;
5
6/// Why reading or writing failed.
7///
8/// Readers fail only when nothing sensible can be produced; recoverable issues
9/// become [`crate::Warning`]s on the document instead.
10#[derive(Debug, thiserror::Error)]
11#[non_exhaustive]
12pub enum Error {
13    /// Input ended before a structure was complete.
14    #[error("unexpected end of data at offset {offset}: needed {needed} more bytes")]
15    Truncated {
16        /// Offset where the read started.
17        offset: u64,
18        /// Bytes that were missing.
19        needed: u64,
20    },
21    /// Input violates the format.
22    #[error("invalid data at offset {offset}: {message}")]
23    Invalid {
24        /// Offset of the offending data.
25        offset: u64,
26        /// What is wrong.
27        message: String,
28    },
29    /// Valid input that uses a feature cadkit does not implement.
30    #[error("unsupported: {0}")]
31    Unsupported(String),
32    /// Input or output would exceed a configured [`crate::Limits`] value or a capacity of
33    /// the file format.
34    #[error("limit exceeded: {message}")]
35    LimitExceeded {
36        /// Which limit was hit.
37        limit: LimitKind,
38        /// What was being counted when it was hit.
39        message: String,
40    },
41    /// Document JSON written for a [`crate::SchemaVersion`] this crate cannot read.
42    #[error("unsupported document schema version {found}; this cadkit reads version {supported}")]
43    SchemaVersion {
44        /// Version found in the input.
45        found: u64,
46        /// Version this crate reads.
47        supported: u32,
48    },
49    /// Input is not a recognized drawing format.
50    #[error("unrecognized file format")]
51    UnknownFormat,
52    /// I/O failure.
53    #[error(transparent)]
54    Io(#[from] std::io::Error),
55}
56
57/// The limit behind an [`Error::LimitExceeded`].
58#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
59#[non_exhaustive]
60pub enum LimitKind {
61    /// [`crate::Limits::max_input_bytes`].
62    InputBytes,
63    /// [`crate::Limits::max_decompressed_bytes`], the budget for decoded and generated data.
64    DecompressedBytes,
65    /// [`crate::Limits::max_objects`].
66    Objects,
67    /// [`crate::Limits::max_depth`].
68    Depth,
69    /// [`crate::Limits::max_string_bytes`].
70    StringBytes,
71    /// [`crate::Limits::max_vertices`].
72    Vertices,
73    /// [`crate::Limits::max_total_vertices`].
74    TotalVertices,
75    /// A computation work budget, such as `WalkOptions::max_work` or a validation budget.
76    Work,
77    /// The size cap of an output being written.
78    Output,
79    /// A value does not fit a field of the file format or the host's address range;
80    /// no configured limit is involved.
81    Capacity,
82}
83
84impl Error {
85    /// Shorthand for [`Error::LimitExceeded`].
86    pub fn limit(limit: LimitKind, message: String) -> Self {
87        Self::LimitExceeded { limit, message }
88    }
89
90    /// Shorthand for [`Error::Invalid`].
91    pub fn invalid(offset: u64, message: impl Into<String>) -> Self {
92        Self::Invalid {
93            offset,
94            message: message.into(),
95        }
96    }
97}