Skip to main content

publet_core/
error.rs

1//! Error types for object parsing and verification.
2
3use thiserror::Error;
4
5/// A way in which bytes failed the canonical serialization profile.
6///
7/// Section 4.1 requires an implementation to *reject* non-canonical bytes
8/// rather than repair them, so every variant here is a hard failure. The
9/// variants are distinct because the command-line tools name the violated
10/// rule on stderr, and the conformance scenarios assert on that name.
11#[derive(Debug, Error, PartialEq, Eq, Clone)]
12#[non_exhaustive]
13pub enum CanonError {
14    /// Input ended in the middle of an item.
15    #[error("truncated input: needed {needed} more byte(s) at offset {offset}")]
16    Truncated {
17        /// Byte offset where the shortfall was detected.
18        offset: usize,
19        /// How many further bytes the item required.
20        needed: usize,
21    },
22
23    /// Bytes remained after a complete top-level item.
24    #[error("trailing data: {count} byte(s) after the top-level item")]
25    TrailingData {
26        /// Number of unconsumed bytes.
27        count: usize,
28    },
29
30    /// An item's argument -- an integer, a length, or a simple value such as
31    /// `null` -- used a longer encoding than necessary.
32    #[error("shortest-form integers: value {value} encoded in {used} byte(s) at offset {offset}")]
33    NonShortestInteger {
34        /// Byte offset of the item's head.
35        offset: usize,
36        /// The decoded argument.
37        value: u64,
38        /// Additional bytes the encoder used for the argument.
39        used: usize,
40    },
41
42    /// An indefinite-length string, array, or map was present.
43    #[error("no indefinite length: indefinite-length item at offset {offset}")]
44    IndefiniteLength {
45        /// Byte offset of the item's head.
46        offset: usize,
47    },
48
49    /// A floating point value was present.
50    #[error("no floating point: float at offset {offset}")]
51    Float {
52        /// Byte offset of the item's head.
53        offset: usize,
54    },
55
56    /// A map key was not a text string.
57    #[error("text map keys: non-text key at offset {offset}")]
58    NonTextKey {
59        /// Byte offset of the offending key.
60        offset: usize,
61    },
62
63    /// Two map keys were equal.
64    #[error("unique map keys: duplicate key {key:?} at offset {offset}")]
65    DuplicateKey {
66        /// Byte offset of the repeated key.
67        offset: usize,
68        /// The repeated key.
69        key: String,
70    },
71
72    /// Map keys were not in ascending UTF-8 byte order.
73    #[error("sorted map keys: {previous:?} precedes {current:?} at offset {offset}")]
74    UnsortedKeys {
75        /// Byte offset of the out-of-order key.
76        offset: usize,
77        /// The preceding key.
78        previous: String,
79        /// The key that should have come first.
80        current: String,
81    },
82
83    /// A text string was not valid UTF-8.
84    #[error("valid UTF-8: invalid sequence at offset {offset}")]
85    InvalidUtf8 {
86        /// Byte offset of the string's contents.
87        offset: usize,
88    },
89
90    /// A text string was not in Unicode Normalization Form C.
91    #[error("NFC normalization: {text:?} is not in NFC at offset {offset}")]
92    NotNfc {
93        /// Byte offset of the string's contents.
94        offset: usize,
95        /// The offending text.
96        text: String,
97    },
98
99    /// A major type or simple value outside the profile was present.
100    #[error("unsupported item: {detail} at offset {offset}")]
101    Unsupported {
102        /// Byte offset of the item's head.
103        offset: usize,
104        /// What was encountered.
105        detail: &'static str,
106    },
107
108    /// Nesting exceeded the implementation limit.
109    #[error("nesting too deep: limit {limit} exceeded at offset {offset}")]
110    TooDeep {
111        /// Byte offset where the limit was reached.
112        offset: usize,
113        /// The configured limit.
114        limit: usize,
115    },
116
117    /// The item was larger than Section 4.5 permits.
118    #[error("object too large: {size} bytes exceeds the {limit} byte limit")]
119    TooLarge {
120        /// Size of the input.
121        size: usize,
122        /// The configured ceiling.
123        limit: usize,
124    },
125}
126
127impl CanonError {
128    /// The short rule name this violation maps to.
129    ///
130    /// Stable across releases: the conformance scenarios match on it.
131    ///
132    /// # Example
133    ///
134    /// ```
135    /// use publet_core::cbor::decode;
136    ///
137    /// let error = decode(&[0xa2, 0x61, b'b', 0x01, 0x61, b'a', 0x02]).unwrap_err(); // {"b": 1, "a": 2}
138    /// assert_eq!(error.rule(), "sorted map keys");
139    /// ```
140    #[must_use]
141    pub fn rule(&self) -> &'static str {
142        match self {
143            Self::Truncated { .. } => "complete items",
144            Self::TrailingData { .. } => "single top-level item",
145            Self::NonShortestInteger { .. } => "shortest-form integers",
146            Self::IndefiniteLength { .. } => "no indefinite length",
147            Self::Float { .. } => "no floating point",
148            Self::NonTextKey { .. } => "text map keys",
149            Self::DuplicateKey { .. } => "unique map keys",
150            Self::UnsortedKeys { .. } => "sorted map keys",
151            Self::InvalidUtf8 { .. } => "valid UTF-8",
152            Self::NotNfc { .. } => "NFC normalization",
153            Self::Unsupported { .. } => "supported item types",
154            Self::TooDeep { .. } => "nesting limit",
155            Self::TooLarge { .. } => "object size limit",
156        }
157    }
158}