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}