commonware_codec/
error.rs

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

commonware_codec/
error.rs
