symqtt-codec 0.1.0

MQTT 3.1.1/5.0 packet codec — role-neutral, runtime-free
Documentation
//! Codec error types for encoding and decoding MQTT packets

use thiserror::Error;

use crate::PacketType;

/// Errors that may occur while decoding an MQTT packet from the wire
#[derive(Debug, Clone, PartialEq, Eq, Error)]
#[non_exhaustive]
pub enum DecodeError {
    /// The buffer does not contain enough bytes to complete the operation
    #[error("insufficient bytes: need {needed} more")]
    InsufficientBytes {
        /// Additional bytes required to finish decoding
        needed: usize,
    },

    /// The variable-length encoding (remaining length) is malformed
    #[error("malformed remaining length")]
    MalformedRemainingLength,

    /// The byte sequence is not valid UTF-8 or violates MQTT string rules
    #[error("invalid utf-8 string: {reason}")]
    InvalidUtf8 {
        /// Why the string was rejected
        reason: &'static str,
    },

    /// The packet type nibble is outside the valid range 1..=15
    #[error("invalid packet type: {value}")]
    InvalidPacketType {
        /// Raw packet-type nibble
        value: u8,
    },

    /// The fixed-header flags are invalid for the given packet type
    #[error("invalid packet flags: type={packet_type:?}, flags=0x{flags:02x}")]
    InvalidFlags {
        /// Packet type whose flags were invalid
        packet_type: PacketType,
        /// Raw flags nibble
        flags: u8,
    },

    /// A protocol-level constraint is violated
    #[error("protocol error: {reason}")]
    ProtocolError {
        /// Description of the violated constraint
        reason: &'static str,
    },

    /// Bytes remain after the body was fully parsed, so the announced remaining
    /// length does not match the structure the packet type defines
    #[error("trailing bytes after packet body: {count} unconsumed")]
    TrailingBytes {
        /// Number of leftover bytes
        count: usize,
    },

    /// Property identifier not allowed for this packet type [MQTTv5-2.2.2.2]
    #[error("invalid property {id:#04x} for {packet_type:?}")]
    InvalidProperty {
        /// Packet that carried the property
        packet_type: PacketType,
        /// Raw property identifier
        id: u8,
    },

    /// Same non-repeatable property appears more than once
    #[error("duplicate property {id:#04x}")]
    DuplicateProperty {
        /// Raw property identifier
        id: u8,
    },

    /// Reason code value is invalid for this packet type
    #[error("invalid reason code {value:#04x} for {packet_type:?}")]
    InvalidReasonCode {
        /// Packet that carried the reason code
        packet_type: PacketType,
        /// Raw reason code
        value: u8,
    },
}

/// Errors that may occur while encoding an MQTT packet to the wire
#[derive(Debug, Clone, PartialEq, Eq, Error)]
#[non_exhaustive]
pub enum EncodeError {
    /// The total remaining length would exceed the protocol maximum (268,435,455 bytes)
    #[error("packet too large: remaining length would exceed 268_435_455")]
    PacketTooLarge,

    /// A UTF-8 string exceeds the 65,535-byte length limit [MQTT-1.5.3]
    #[error("string too long: {len} bytes exceeds 65535 limit")]
    StringTooLong {
        /// Actual string length in bytes
        len: usize,
    },

    /// A UTF-8 string contains the forbidden null character U+0000 [MQTT-1.5.3-2]
    #[error("string contains null character (U+0000)")]
    StringContainsNull,

    /// The packet fields form an invalid combination
    #[error("invalid packet state: {reason}")]
    InvalidState {
        /// Description of the invalid combination
        reason: &'static str,
    },
}