net_wire/quic/frame/
parse.rs

1//! QUIC frame parsing diagnostics.
2
3use core::fmt;
4
5use super::super::varint::{QuicVarIntLen, QuicVarIntParseError};
6
7/// Identifies a semantic field in a QUIC frame.
8#[derive(Clone, Copy, Debug, Eq, PartialEq)]
9#[non_exhaustive]
10pub enum QuicFrameField {
11    /// The CRYPTO frame's offset field.
12    CryptoOffset,
13    /// The CRYPTO frame's data-length field.
14    CryptoLength,
15    /// The CRYPTO frame's opaque data bytes.
16    CryptoData,
17    /// The frame's token-length field.
18    TokenLength,
19    /// The frame's opaque token bytes.
20    Token,
21    /// The frame's stream-ID field.
22    StreamId,
23    /// The STREAM frame's offset field.
24    StreamOffset,
25    /// The STREAM frame's data-length field.
26    StreamLength,
27    /// The STREAM frame's opaque data bytes.
28    StreamData,
29    /// The frame's maximum-data field.
30    MaximumData,
31    /// The frame's maximum-stream-data field.
32    MaximumStreamData,
33    /// The frame's maximum-streams field.
34    MaximumStreams,
35    /// The frame's application-error-code field.
36    ApplicationErrorCode,
37    /// The CONNECTION_CLOSE frame's error-code field.
38    ConnectionCloseErrorCode,
39    /// The transport CONNECTION_CLOSE frame's triggering-frame-type field.
40    TriggeringFrameType,
41    /// The CONNECTION_CLOSE frame's reason-phrase-length field.
42    ReasonPhraseLength,
43    /// The CONNECTION_CLOSE frame's opaque reason-phrase bytes.
44    ReasonPhrase,
45    /// The frame's final-size field.
46    FinalSize,
47    /// The frame's opaque path-validation data.
48    PathData,
49    /// The frame's connection-ID sequence-number field.
50    SequenceNumber,
51    /// The frame's retire-prior-to field.
52    RetirePriorTo,
53    /// The frame's connection-ID-length field.
54    ConnectionIdLength,
55    /// The frame's opaque connection-ID bytes.
56    ConnectionId,
57    /// The frame's stateless-reset-token bytes.
58    StatelessResetToken,
59    /// The ACK frame's largest-acknowledged field.
60    LargestAcknowledged,
61    /// The ACK frame's acknowledgment-delay field.
62    AckDelay,
63    /// The ACK frame's additional-range count field.
64    AckRangeCount,
65    /// The ACK frame's first acknowledgment-range field.
66    FirstAckRange,
67    /// An ACK frame's additional-range gap field.
68    AckGap,
69    /// An ACK frame's additional-range length field.
70    AckRangeLength,
71    /// The ACK_ECN frame's ECT(0) count field.
72    Ect0Count,
73    /// The ACK_ECN frame's ECT(1) count field.
74    Ect1Count,
75    /// The ACK_ECN frame's ECN-CE count field.
76    EcnCeCount,
77}
78
79/// Failure to parse a QUIC plaintext frame sequence.
80#[derive(Clone, Copy, Debug, Eq, PartialEq)]
81pub enum QuicFrameParseError {
82    /// The supplied plaintext frame sequence contains no frames.
83    EmptySequence,
84    /// The frame-type variable integer is incomplete at the indicated sequence offset.
85    FrameType {
86        /// Absolute byte offset of the frame type from the sequence start.
87        offset: usize,
88        /// Exact variable-integer parsing failure.
89        error: QuicVarIntParseError,
90    },
91    /// A semantic frame field variable integer is incomplete at the indicated sequence offset.
92    Field {
93        /// Semantic field whose variable integer could not be parsed.
94        field: QuicFrameField,
95        /// Absolute byte offset of the field from the sequence start.
96        offset: usize,
97        /// Exact variable-integer parsing failure.
98        error: QuicVarIntParseError,
99    },
100    /// A semantic frame field exceeds its RFC-defined maximum value.
101    FieldValueOutOfRange {
102        /// Semantic field whose decoded value exceeds its maximum.
103        field: QuicFrameField,
104        /// Absolute byte offset of the field from the sequence start.
105        offset: usize,
106        /// Decoded field value.
107        value: u64,
108        /// Greatest permitted field value.
109        maximum: u64,
110    },
111    /// A semantic frame field exceeds the decoded value of another field.
112    FieldValueExceedsField {
113        /// Semantic field whose decoded value is too large.
114        field: QuicFrameField,
115        /// Absolute byte offset of the field from the sequence start.
116        offset: usize,
117        /// Decoded field value.
118        value: u64,
119        /// Semantic field supplying the maximum value.
120        maximum_field: QuicFrameField,
121        /// Decoded maximum-field value.
122        maximum: u64,
123    },
124    /// A decoded frame byte range exceeds its RFC-defined maximum end offset.
125    FieldRangeOutOfRange {
126        /// Semantic field encoding the decoded range start.
127        field: QuicFrameField,
128        /// Absolute byte offset of the encoded range-start field from the sequence start.
129        offset: usize,
130        /// Decoded range start.
131        start: u64,
132        /// Decoded range length.
133        length: u64,
134        /// Greatest permitted decoded range end.
135        maximum: u64,
136    },
137    /// A decoded bounded-byte field length cannot be represented as `usize` on this target.
138    LengthNotRepresentable {
139        /// Semantic field whose length cannot be represented.
140        field: QuicFrameField,
141        /// Absolute byte offset of the encoded length from the sequence start.
142        offset: usize,
143        /// Decoded wire length.
144        value: u64,
145    },
146    /// An implicit bounded-byte field length cannot be represented as `u64`.
147    ImplicitLengthNotRepresentable {
148        /// Semantic field whose implicit length cannot be represented.
149        field: QuicFrameField,
150        /// Absolute byte offset of the bounded byte field from the sequence start.
151        offset: usize,
152        /// Native byte length derived from the supplied slice.
153        length: usize,
154    },
155    /// Computing the end of a bounded-byte field overflows `usize`.
156    LengthOverflow {
157        /// Semantic bounded-byte field whose end cannot be represented.
158        field: QuicFrameField,
159        /// Absolute byte offset of the bounded byte field from the sequence start.
160        offset: usize,
161        /// Representable bounded byte-field length.
162        length: usize,
163    },
164    /// A bounded-byte field is incomplete.
165    IncompleteBytes {
166        /// Semantic bounded-byte field that is incomplete.
167        field: QuicFrameField,
168        /// Absolute byte offset of the bounded byte field from the sequence start.
169        offset: usize,
170        /// Bytes required by the bounded byte field.
171        required: usize,
172        /// Bytes available for the bounded byte field.
173        available: usize,
174    },
175    /// A semantically required nonempty field is empty.
176    EmptyField {
177        /// Semantic field that must not be empty.
178        field: QuicFrameField,
179        /// Absolute byte offset of the field from the sequence start.
180        offset: usize,
181    },
182    /// Computing an ACK range packet number would be negative.
183    AckRangeUnderflow {
184        /// ACK field whose encoded value caused the underflow.
185        field: QuicFrameField,
186        /// Absolute byte offset of the encoded field from the sequence start.
187        offset: usize,
188        /// Packet number before subtracting this field.
189        base: u64,
190        /// Decoded field value being subtracted.
191        value: u64,
192        /// Additional fixed adjustment applied after `value`.
193        adjustment: u64,
194    },
195    /// The frame type has no safe boundary without implementing its type-specific layout.
196    UnsupportedFrameType {
197        /// Decoded raw frame-type value.
198        value: u64,
199        /// Exact encoded frame-type width.
200        length: QuicVarIntLen,
201        /// Absolute byte offset of the frame type from the sequence start.
202        offset: usize,
203    },
204}
205
206impl fmt::Display for QuicFrameParseError {
207    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
208        match self {
209            Self::EmptySequence => write!(f, "QUIC plaintext frame sequence is empty"),
210            Self::FrameType { offset, error } => write!(
211                f,
212                "QUIC frame type at offset {offset} cannot be parsed: {error}"
213            ),
214            Self::Field {
215                field,
216                offset,
217                error,
218            } => write!(
219                f,
220                "QUIC frame {field:?} field at offset {offset} cannot be parsed: {error}"
221            ),
222            Self::FieldValueOutOfRange {
223                field,
224                offset,
225                value,
226                maximum,
227            } => write!(
228                f,
229                "QUIC frame {field:?} field at offset {offset} has value {value}, exceeding maximum {maximum}"
230            ),
231            Self::FieldValueExceedsField {
232                field,
233                offset,
234                value,
235                maximum_field,
236                maximum,
237            } => write!(
238                f,
239                "QUIC frame {field:?} field at offset {offset} has value {value}, exceeding {maximum_field:?} value {maximum}"
240            ),
241            Self::FieldRangeOutOfRange {
242                field,
243                offset,
244                start,
245                length,
246                maximum,
247            } => write!(
248                f,
249                "QUIC frame {field:?} range at offset {offset} has start {start} plus length {length}, exceeding maximum end {maximum}"
250            ),
251            Self::LengthNotRepresentable {
252                field,
253                offset,
254                value,
255            } => write!(
256                f,
257                "QUIC frame {field:?} length at offset {offset} has unrepresentable value {value}"
258            ),
259            Self::ImplicitLengthNotRepresentable {
260                field,
261                offset,
262                length,
263            } => write!(
264                f,
265                "QUIC frame {field:?} implicit length at offset {offset} cannot represent native length {length} as u64"
266            ),
267            Self::LengthOverflow {
268                field,
269                offset,
270                length,
271            } => write!(
272                f,
273                "QUIC frame {field:?} bounded field at offset {offset} overflows with length {length}"
274            ),
275            Self::IncompleteBytes {
276                field,
277                offset,
278                required,
279                available,
280            } => write!(
281                f,
282                "QUIC frame {field:?} bytes at offset {offset} are incomplete: need {required} bytes, have {available}"
283            ),
284            Self::EmptyField { field, offset } => write!(
285                f,
286                "QUIC frame {field:?} field at offset {offset} must be nonempty"
287            ),
288            Self::AckRangeUnderflow {
289                field,
290                offset,
291                base,
292                value,
293                adjustment,
294            } => write!(
295                f,
296                "QUIC ACK {field:?} field at offset {offset} underflows: {base} minus {value} minus {adjustment}"
297            ),
298            Self::UnsupportedFrameType {
299                value,
300                length,
301                offset,
302            } => write!(
303                f,
304                "QUIC frame type {value} at offset {offset} with encoded width {} is unsupported",
305                length.byte_len()
306            ),
307        }
308    }
309}
net_wire/quic/frame/parse.rs

net_wire/quic/frame/
parse.rs
