Skip to main content

symqtt_codec/
error.rs

1//! Codec error types for encoding and decoding MQTT packets
2
3use thiserror::Error;
4
5use crate::PacketType;
6
7/// Errors that may occur while decoding an MQTT packet from the wire
8#[derive(Debug, Clone, PartialEq, Eq, Error)]
9#[non_exhaustive]
10pub enum DecodeError {
11    /// The buffer does not contain enough bytes to complete the operation
12    #[error("insufficient bytes: need {needed} more")]
13    InsufficientBytes {
14        /// Additional bytes required to finish decoding
15        needed: usize,
16    },
17
18    /// The variable-length encoding (remaining length) is malformed
19    #[error("malformed remaining length")]
20    MalformedRemainingLength,
21
22    /// The byte sequence is not valid UTF-8 or violates MQTT string rules
23    #[error("invalid utf-8 string: {reason}")]
24    InvalidUtf8 {
25        /// Why the string was rejected
26        reason: &'static str,
27    },
28
29    /// The packet type nibble is outside the valid range 1..=15
30    #[error("invalid packet type: {value}")]
31    InvalidPacketType {
32        /// Raw packet-type nibble
33        value: u8,
34    },
35
36    /// The fixed-header flags are invalid for the given packet type
37    #[error("invalid packet flags: type={packet_type:?}, flags=0x{flags:02x}")]
38    InvalidFlags {
39        /// Packet type whose flags were invalid
40        packet_type: PacketType,
41        /// Raw flags nibble
42        flags: u8,
43    },
44
45    /// A protocol-level constraint is violated
46    #[error("protocol error: {reason}")]
47    ProtocolError {
48        /// Description of the violated constraint
49        reason: &'static str,
50    },
51
52    /// Bytes remain after the body was fully parsed, so the announced remaining
53    /// length does not match the structure the packet type defines
54    #[error("trailing bytes after packet body: {count} unconsumed")]
55    TrailingBytes {
56        /// Number of leftover bytes
57        count: usize,
58    },
59
60    /// Property identifier not allowed for this packet type [MQTTv5-2.2.2.2]
61    #[error("invalid property {id:#04x} for {packet_type:?}")]
62    InvalidProperty {
63        /// Packet that carried the property
64        packet_type: PacketType,
65        /// Raw property identifier
66        id: u8,
67    },
68
69    /// Same non-repeatable property appears more than once
70    #[error("duplicate property {id:#04x}")]
71    DuplicateProperty {
72        /// Raw property identifier
73        id: u8,
74    },
75
76    /// Reason code value is invalid for this packet type
77    #[error("invalid reason code {value:#04x} for {packet_type:?}")]
78    InvalidReasonCode {
79        /// Packet that carried the reason code
80        packet_type: PacketType,
81        /// Raw reason code
82        value: u8,
83    },
84}
85
86/// Errors that may occur while encoding an MQTT packet to the wire
87#[derive(Debug, Clone, PartialEq, Eq, Error)]
88#[non_exhaustive]
89pub enum EncodeError {
90    /// The total remaining length would exceed the protocol maximum (268,435,455 bytes)
91    #[error("packet too large: remaining length would exceed 268_435_455")]
92    PacketTooLarge,
93
94    /// A UTF-8 string exceeds the 65,535-byte length limit [MQTT-1.5.3]
95    #[error("string too long: {len} bytes exceeds 65535 limit")]
96    StringTooLong {
97        /// Actual string length in bytes
98        len: usize,
99    },
100
101    /// A UTF-8 string contains the forbidden null character U+0000 [MQTT-1.5.3-2]
102    #[error("string contains null character (U+0000)")]
103    StringContainsNull,
104
105    /// The packet fields form an invalid combination
106    #[error("invalid packet state: {reason}")]
107    InvalidState {
108        /// Description of the invalid combination
109        reason: &'static str,
110    },
111}