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 [`Read`](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    /// [`Decode::decode_cfg`](crate::Decode::decode_cfg), there were still
16    /// unconsumed bytes remaining 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 [`varint`](crate::varint) module for encoding details.
29    #[error("Invalid Varint: Malformed or value out of range")]
30    InvalidVarint,
31
32    /// A byte representing a boolean was expected to be `0` (false) or `1` (true),
33    /// but a different value was encountered during decoding.
34    #[error("Invalid Bool: Expected 0 or 1, found different value")]
35    InvalidBool,
36
37    /// An enum variant was expected, but the decoded value did not match any
38    /// of the expected variants.
39    #[error("Invalid Enum: Expected a valid enum variant, found {0}")]
40    InvalidEnum(u8),
41
42    /// A length prefix (e.g., for `Vec<T>`, `Bytes`, `HashMap<K, V>`) was decoded,
43    /// but its value fell outside the permitted range.
44    ///
45    /// This range is typically configured via a [`RangeConfig`](crate::RangeConfig)
46    /// passed within the `Cfg` parameter to [`Read::read_cfg`](crate::Read::read_cfg).
47    /// The contained `usize` is the invalid length that was decoded.
48    #[error("Invalid Length: Decoded length {0} is outside the allowed range")]
49    InvalidLength(usize),
50
51    /// A semantic validation error occurred during decoding, indicating the data,
52    /// while perhaps structurally valid, does not meet application-specific criteria.
53    ///
54    /// - The first `&'static str` provides context (e.g., the name of the type being decoded).
55    /// - The second `&'static str` provides a specific error message.
56    ///
57    /// Example: Trying to decode a `HashMap` where keys were not in ascending order.
58    #[error("Validation Error: Context({0}), Message({1})")]
59    Invalid(&'static str, &'static str),
60
61    /// An error occurred in underlying code (e.g., external library call, complex validation)
62    /// and has been wrapped into a codec [`enum@Error`].
63    ///
64    /// - The `&'static str` provides context about the operation being performed.
65    /// - The boxed [`std::error::Error`] is the original source error.
66    ///
67    /// Allows propagating custom errors through the codec reading process.
68    #[error("Wrapped Error: Context({0}), Source({1})")]
69    Wrapped(&'static str, Box<dyn std::error::Error + Send + Sync>),
70}
commonware_codec/error.rs

commonware_codec/
error.rs
