1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
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>();
}
}