commonware_codec/
error.rs

1//! Error types for codec operations.
2
3#[cfg(not(feature = "std"))]
4use alloc::boxed::Box;
5use thiserror::Error;
6
7/// Error type for codec operations
8#[derive(Error, Debug)]
9pub enum Error {
10    /// Indicates that the input buffer (`Buf`) did not contain enough bytes to read
11    /// the next piece of data required by a [crate::Read] implementation.
12    /// This suggests the input data is truncated or incomplete.
13    #[error("Unexpected End-of-Buffer: Not enough bytes remaining to read data")]
14    EndOfBuffer,
15
16    /// Indicates that after successfully decoding a value using a method like
17    /// [crate::Decode::decode_cfg], there were still unconsumed bytes remaining
18    /// in the input buffer.
19    ///
20    /// This usually means the input data contained more than just the expected encoded value.
21    /// The contained `usize` is the number of bytes that remained unconsumed.
22    #[error("Extra Data: {0} bytes remained in buffer after decoding")]
23    ExtraData(usize),
24
25    /// A variable-length integer (varint), often used for encoding lengths,
26    /// could not be decoded correctly. This might happen if:
27    /// - The varint encoding itself is malformed (e.g., too long).
28    /// - The decoded varint value exceeds the capacity of the target integer type.
29    ///
30    /// See the [crate::varint] module for encoding details.
31    #[error("Invalid {0}-byte varint")]
32    InvalidVarint(usize),
33
34    /// Same as `InvalidVarint`, but specifically for `usize`-sized varints.
35    #[error("Invalid usize-sized varint")]
36    InvalidUsize,
37
38    /// A byte representing a boolean was expected to be `0` (false) or `1` (true),
39    /// but a different value was encountered during decoding.
40    #[error("Invalid Bool: Expected 0 or 1, found different value")]
41    InvalidBool,
42
43    /// An enum variant was expected, but the decoded value did not match any
44    /// of the expected variants.
45    #[error("Invalid Enum: Expected a valid enum variant, found {0}")]
46    InvalidEnum(u8),
47
48    /// A length prefix (e.g., for `Vec<T>`, `Bytes`, `HashMap<K, V>`) was decoded,
49    /// but its value fell outside the permitted range.
50    ///
51    /// This range is typically configured via a [crate::RangeCfg]
52    /// passed within the `Cfg` parameter to [crate::Read::read_cfg].
53    /// The contained `usize` is the invalid length that was decoded.
54    #[error("Invalid Length: Decoded length {0} is outside the allowed range")]
55    InvalidLength(usize),
56
57    /// A semantic validation error occurred during decoding, indicating the data,
58    /// while perhaps structurally valid, does not meet application-specific criteria.
59    ///
60    /// - The first `&'static str` provides context (e.g., the name of the type being decoded).
61    /// - The second `&'static str` provides a specific error message.
62    ///
63    /// Example: Trying to decode a `HashMap` where keys were not in ascending order.
64    #[error("Validation Error: Context({0}), Message({1})")]
65    Invalid(&'static str, &'static str),
66
67    /// An error occurred in underlying code (e.g., external library call, complex validation)
68    /// and has been wrapped into a codec [enum@Error].
69    ///
70    /// - The `&'static str` provides context about the operation being performed.
71    /// - The boxed error is the original source error.
72    ///
73    /// Allows propagating custom errors through the codec reading process.
74    #[error("Wrapped Error: Context({0})")]
75    Wrapped(
76        &'static str,
77        #[source] Box<dyn core::error::Error + Send + Sync>,
78    ),
79}
commonware_codec/error.rs

commonware_codec/
error.rs
