po_wire/
error.rs

1//! Error types for the PO wire format.
2//!
3//! All errors are `no_std` compatible and carry precise diagnostic information
4//! for debugging malformed frames without allocating.
5
6use core::fmt;
7
8/// Errors that occur during frame encoding or decoding.
9#[derive(Debug, Clone, Copy, PartialEq, Eq)]
10pub enum WireError {
11    /// The output buffer is too small to hold the encoded data.
12    BufferTooSmall {
13        /// Minimum bytes needed to complete the operation.
14        needed: usize,
15        /// Bytes actually available in the buffer.
16        available: usize,
17    },
18
19    /// The input buffer does not contain enough data for a complete decode.
20    /// This is NOT a fatal error — it means "read more bytes and try again".
21    Incomplete {
22        /// Minimum additional bytes needed (estimate).
23        needed_min: usize,
24        /// Bytes currently available.
25        available: usize,
26    },
27
28    /// A VarInt encoding is malformed (overflow or invalid prefix).
29    InvalidVarInt,
30
31    /// The frame type nibble does not map to a known `FrameType`.
32    UnknownFrameType(u8),
33
34    /// The payload length declared in the header exceeds the configured maximum.
35    PayloadTooLarge {
36        /// Declared payload length.
37        declared: u64,
38        /// Maximum allowed by configuration.
39        max_allowed: u64,
40    },
41}
42
43impl fmt::Display for WireError {
44    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
45        match self {
46            Self::BufferTooSmall { needed, available } => {
47                write!(f, "buffer too small: need {needed} bytes, have {available}")
48            }
49            Self::Incomplete { needed_min, available } => {
50                write!(f, "incomplete input: need at least {needed_min} bytes, have {available}")
51            }
52            Self::InvalidVarInt => write!(f, "malformed VarInt encoding"),
53            Self::UnknownFrameType(t) => write!(f, "unknown frame type: {t:#04x}"),
54            Self::PayloadTooLarge { declared, max_allowed } => {
55                write!(f, "payload too large: {declared} bytes (max {max_allowed})")
56            }
57        }
58    }
59}
60
61#[cfg(feature = "std")]
62impl std::error::Error for WireError {}
po_wire/error.rs

po_wire/
error.rs
