packetwire 0.1.0

Bounded deterministic binary packet codec with stream and datagram framing
Documentation
use std::fmt;

use crate::PacketId;

/// Result type returned by protocol encoding and decoding operations.
pub type Result<T> = std::result::Result<T, ProtocolError>;

/// A malformed value, invalid frame, unknown packet, or configured limit
/// violation encountered by the protocol codec.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ProtocolError {
    /// A payload ended before a fixed number of bytes could be read.
    UnexpectedEnd {
        /// Number of bytes required by the current read.
        needed: usize,
        /// Number of bytes available at the cursor.
        remaining: usize,
    },
    /// A binary writer would exceed its configured output limit.
    WriteLimitExceeded {
        /// Output length that the rejected write would produce.
        attempted: usize,
        /// Configured maximum output length.
        limit: usize,
    },
    /// A declared or encoded frame body exceeds the configured maximum.
    FrameTooLarge {
        /// Declared or attempted frame body length.
        length: u64,
        /// Configured maximum frame body length.
        maximum: usize,
    },
    /// A stream decoder would retain too much unread data.
    BufferedDataLimitExceeded {
        /// Buffered length that the rejected append would produce.
        attempted: usize,
        /// Configured maximum buffered length.
        limit: usize,
    },
    /// The frame body cannot contain the required packet ID.
    InvalidFrameLength(u64),
    /// A byte stream or datagram ended before its declared frame was complete.
    IncompleteFrame {
        /// Number of incomplete bytes received.
        buffered: usize,
    },
    /// A varint used more bytes than its value requires.
    NonCanonicalVarInt {
        /// Decoded integer value.
        value: u64,
        /// Number of bytes used by the rejected representation.
        encoded_length: usize,
    },
    /// A value cannot fit in the QUIC-style variable-length integer format.
    VarIntOutOfRange {
        /// Rejected integer value.
        value: u64,
    },
    /// A decoded packet ID does not fit the protocol's `u16` ID space.
    PacketIdOutOfRange(u64),
    /// The selected packet set does not contain the received ID.
    UnknownPacketId(PacketId),
    /// A decoder for one concrete packet type received another type's ID.
    PacketIdMismatch {
        /// ID declared by the requested packet type.
        expected: PacketId,
        /// ID found in the frame.
        actual: PacketId,
    },
    /// A packet decoder returned without consuming its complete payload.
    TrailingPayload {
        /// ID of the packet whose decoder left bytes unread.
        packet_id: PacketId,
        /// Number of unread payload bytes.
        remaining: usize,
    },
    /// A datagram contained data after its one permitted frame.
    TrailingFrameData(usize),
    /// A length-prefixed payload value exceeds its decode limit.
    LengthLimitExceeded {
        /// Kind of value being decoded, such as `"string"` or `"collection"`.
        kind: &'static str,
        /// Length declared by the payload.
        length: u64,
        /// Configured maximum length for that value kind.
        maximum: usize,
    },
    /// A boolean used a byte other than `0` or `1`.
    InvalidBool(u8),
    /// String bytes were not valid UTF-8.
    InvalidUtf8,
    /// An explicitly tagged enum contained an unknown tag.
    InvalidEnumTag {
        /// Rust enum type that rejected the tag.
        type_name: &'static str,
        /// Unknown integer tag.
        tag: u64,
    },
}

impl fmt::Display for ProtocolError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::UnexpectedEnd { needed, remaining } => write!(
                formatter,
                "unexpected end of input: needed {needed} bytes, only {remaining} remain"
            ),
            Self::WriteLimitExceeded { attempted, limit } => write!(
                formatter,
                "binary output would be {attempted} bytes, exceeding the {limit}-byte limit"
            ),
            Self::FrameTooLarge { length, maximum } => write!(
                formatter,
                "frame length {length} exceeds the configured {maximum}-byte maximum"
            ),
            Self::BufferedDataLimitExceeded { attempted, limit } => write!(
                formatter,
                "decoder would buffer {attempted} bytes, exceeding its {limit}-byte limit"
            ),
            Self::InvalidFrameLength(length) => {
                write!(formatter, "invalid frame body length {length}")
            }
            Self::IncompleteFrame { buffered } => write!(
                formatter,
                "byte stream or datagram ended with an incomplete frame ({buffered} bytes buffered)"
            ),
            Self::NonCanonicalVarInt {
                value,
                encoded_length,
            } => write!(
                formatter,
                "value {value} used a non-canonical {encoded_length}-byte varint"
            ),
            Self::VarIntOutOfRange { value } => write!(
                formatter,
                "value {value} exceeds the 62-bit variable-integer maximum"
            ),
            Self::PacketIdOutOfRange(value) => {
                write!(formatter, "packet ID {value} does not fit in 16 bits")
            }
            Self::UnknownPacketId(id) => write!(formatter, "unknown packet ID {id}"),
            Self::PacketIdMismatch { expected, actual } => write!(
                formatter,
                "packet ID mismatch: expected {expected}, received {actual}"
            ),
            Self::TrailingPayload {
                packet_id,
                remaining,
            } => write!(
                formatter,
                "packet {packet_id} left {remaining} unread payload bytes"
            ),
            Self::TrailingFrameData(remaining) => {
                write!(
                    formatter,
                    "datagram contains {remaining} trailing frame bytes"
                )
            }
            Self::LengthLimitExceeded {
                kind,
                length,
                maximum,
            } => write!(
                formatter,
                "{kind} length {length} exceeds the configured maximum of {maximum}"
            ),
            Self::InvalidBool(value) => {
                write!(formatter, "invalid boolean byte {value}; expected 0 or 1")
            }
            Self::InvalidUtf8 => formatter.write_str("string payload is not valid UTF-8"),
            Self::InvalidEnumTag { type_name, tag } => {
                write!(formatter, "invalid {type_name} enum tag {tag}")
            }
        }
    }
}

impl std::error::Error for ProtocolError {}

#[cfg(test)]
#[cfg_attr(coverage_nightly, coverage(off))]
mod tests {
    use super::*;

    #[test]
    fn every_error_has_a_stable_display_message() {
        let cases = [
            (
                ProtocolError::UnexpectedEnd {
                    needed: 4,
                    remaining: 2,
                },
                "unexpected end of input: needed 4 bytes, only 2 remain",
            ),
            (
                ProtocolError::WriteLimitExceeded {
                    attempted: 9,
                    limit: 8,
                },
                "binary output would be 9 bytes, exceeding the 8-byte limit",
            ),
            (
                ProtocolError::FrameTooLarge {
                    length: 10,
                    maximum: 9,
                },
                "frame length 10 exceeds the configured 9-byte maximum",
            ),
            (
                ProtocolError::BufferedDataLimitExceeded {
                    attempted: 6,
                    limit: 5,
                },
                "decoder would buffer 6 bytes, exceeding its 5-byte limit",
            ),
            (
                ProtocolError::InvalidFrameLength(0),
                "invalid frame body length 0",
            ),
            (
                ProtocolError::IncompleteFrame { buffered: 3 },
                "byte stream or datagram ended with an incomplete frame (3 bytes buffered)",
            ),
            (
                ProtocolError::NonCanonicalVarInt {
                    value: 1,
                    encoded_length: 2,
                },
                "value 1 used a non-canonical 2-byte varint",
            ),
            (
                ProtocolError::VarIntOutOfRange { value: u64::MAX },
                "value 18446744073709551615 exceeds the 62-bit variable-integer maximum",
            ),
            (
                ProtocolError::PacketIdOutOfRange(65_536),
                "packet ID 65536 does not fit in 16 bits",
            ),
            (
                ProtocolError::UnknownPacketId(PacketId::new(7)),
                "unknown packet ID 0x0007",
            ),
            (
                ProtocolError::PacketIdMismatch {
                    expected: PacketId::new(1),
                    actual: PacketId::new(2),
                },
                "packet ID mismatch: expected 0x0001, received 0x0002",
            ),
            (
                ProtocolError::TrailingPayload {
                    packet_id: PacketId::new(3),
                    remaining: 4,
                },
                "packet 0x0003 left 4 unread payload bytes",
            ),
            (
                ProtocolError::TrailingFrameData(5),
                "datagram contains 5 trailing frame bytes",
            ),
            (
                ProtocolError::LengthLimitExceeded {
                    kind: "string",
                    length: 12,
                    maximum: 8,
                },
                "string length 12 exceeds the configured maximum of 8",
            ),
            (
                ProtocolError::InvalidBool(2),
                "invalid boolean byte 2; expected 0 or 1",
            ),
            (
                ProtocolError::InvalidUtf8,
                "string payload is not valid UTF-8",
            ),
            (
                ProtocolError::InvalidEnumTag {
                    type_name: "Level",
                    tag: 9,
                },
                "invalid Level enum tag 9",
            ),
        ];

        for (error, expected) in cases {
            assert_eq!(error.to_string(), expected);
        }
    }

    #[test]
    fn protocol_error_implements_standard_error() {
        fn assert_error<T: std::error::Error>() {}
        assert_error::<ProtocolError>();
    }
}