Skip to main content

buffa/
encoding.rs

1// Modified by ReallyMe Technologies Limited.
2//! Wire format encoding and decoding primitives.
3//!
4//! Implements the protobuf binary wire format: varints, fixed-width integers,
5//! length-delimited fields, and tag parsing.
6
7use crate::encode_sink::EncodeSink;
8use bytes::Buf;
9
10use crate::error::DecodeError;
11
12/// The maximum valid protobuf field number, 2^29 − 1.
13///
14/// The wire-format tag packs `(field_number << 3) | wire_type` into a
15/// u32-decodable varint; the low 3 bits carry the wire type, leaving 29
16/// bits for the field number. See the [protobuf encoding spec][spec].
17///
18/// [spec]: https://protobuf.dev/programming-guides/encoding/#structure
19pub const MAX_FIELD_NUMBER: u32 = (1 << 29) - 1;
20
21/// The first field number of the band reserved for the protobuf
22/// implementation, 19000.
23///
24/// Field numbers in `FIRST_RESERVED_FIELD_NUMBER..=LAST_RESERVED_FIELD_NUMBER`
25/// may not be declared by user messages or extensions; `protoc` refuses them
26/// and so does `DescriptorPool` when loading a descriptor set. Extension
27/// *ranges* may still span the band, as in `descriptor.proto`'s own
28/// `extensions 1000 to max;`. See the [language guide][spec].
29///
30/// [spec]: https://protobuf.dev/programming-guides/proto3/#assigning
31pub const FIRST_RESERVED_FIELD_NUMBER: u32 = 19_000;
32
33/// The last field number of the implementation-reserved band, 19999
34/// (inclusive). See [`FIRST_RESERVED_FIELD_NUMBER`].
35pub const LAST_RESERVED_FIELD_NUMBER: u32 = 19_999;
36
37/// Protobuf wire types.
38///
39/// Only wire types 0–5 are currently defined by the protobuf specification;
40/// values 6 and 7 are reserved for future use.  This enum is
41/// `#[non_exhaustive]` so that adding new wire types in a future crate
42/// version is not a breaking change for downstream match arms.
43#[derive(Clone, Copy, Debug, PartialEq, Eq)]
44#[repr(u8)]
45#[non_exhaustive]
46pub enum WireType {
47    Varint = 0,
48    Fixed64 = 1,
49    LengthDelimited = 2,
50    StartGroup = 3,
51    EndGroup = 4,
52    Fixed32 = 5,
53}
54
55impl WireType {
56    /// Converts a raw `u32` wire type value to a [`WireType`] variant.
57    ///
58    /// # Errors
59    ///
60    /// Returns [`DecodeError::InvalidWireType`] if `value` is not a
61    /// recognised wire type (i.e. not in 0–5).
62    pub fn from_u32(value: u32) -> Result<Self, DecodeError> {
63        match value {
64            0 => Ok(Self::Varint),
65            1 => Ok(Self::Fixed64),
66            2 => Ok(Self::LengthDelimited),
67            3 => Ok(Self::StartGroup),
68            4 => Ok(Self::EndGroup),
69            5 => Ok(Self::Fixed32),
70            _ => Err(DecodeError::InvalidWireType(value)),
71        }
72    }
73}
74
75/// A parsed field tag (field number + wire type).
76#[derive(Clone, Copy, Debug, PartialEq, Eq)]
77pub struct Tag {
78    field_number: u32,
79    wire_type: WireType,
80}
81
82impl Tag {
83    /// Create a new tag.
84    ///
85    /// Generated `write_to` code calls this once per set field with a
86    /// constant field number; `#[inline]` lets the range assert const-fold
87    /// away and the tag collapse into the caller, instead of an out-of-line
88    /// call per field write in non-LTO builds.
89    ///
90    /// # Panics
91    ///
92    /// Panics if `field_number` is not in the valid range
93    /// `[1, MAX_FIELD_NUMBER]`. This is a programming error (generated
94    /// code always uses valid field numbers); the panic fires in all
95    /// build profiles.
96    #[inline]
97    pub fn new(field_number: u32, wire_type: WireType) -> Self {
98        assert!(
99            (1..=MAX_FIELD_NUMBER).contains(&field_number),
100            "field_number must be in [1, {MAX_FIELD_NUMBER}], got {field_number}"
101        );
102        Self {
103            field_number,
104            wire_type,
105        }
106    }
107
108    /// Returns the field number carried by this tag.
109    #[inline]
110    pub fn field_number(&self) -> u32 {
111        self.field_number
112    }
113
114    /// Returns the wire type carried by this tag.
115    #[inline]
116    pub fn wire_type(&self) -> WireType {
117        self.wire_type
118    }
119
120    /// Encode a tag to a buffer.
121    #[inline]
122    pub fn encode(&self, buf: &mut impl EncodeSink) {
123        // Cast to u64 before shifting to avoid overflow for large (invalid)
124        // field numbers; valid field numbers fit in 29 bits so the result
125        // always fits in 32 bits when the field number is in range.
126        let value = ((self.field_number as u64) << 3) | (self.wire_type as u64);
127        encode_varint(value, buf);
128    }
129
130    /// Decode a tag from a buffer.
131    ///
132    /// Single-byte tags (field numbers 1–15, any wire type) are validated
133    /// straight from the first byte, without the `Result<u64, _>` that
134    /// [`decode_varint`] returns. A longer tag continues in
135    /// `decode_varint_multibyte`, so the one-byte check is not repeated.
136    #[inline]
137    pub fn decode(buf: &mut impl Buf) -> Result<Self, DecodeError> {
138        // Fast path: one-byte tag. Covers field numbers 1–15 with any
139        // wire type (bits 0-2 = wire type, bits 3-6 = field number, bit 7
140        // clear). For protos that keep frequently-used fields in the 1–15
141        // range — which the style guides recommend — this is the only
142        // branch the decode loop ever takes.
143        if let Some(&first) = buf.chunk().first() {
144            if first < 0x80 {
145                buf.advance(1);
146                return Self::from_raw_u32(u32::from(first));
147            }
148        }
149
150        // Multi-byte tag (field number ≥ 16).
151        let value = decode_varint_multibyte(buf)?;
152        // A tag value above u32::MAX implies a field number above 2^29 – 1
153        // (the protobuf maximum), since the lower three bits carry the wire
154        // type and the remaining bits carry the field number.
155        if value > u32::MAX as u64 {
156            return Err(DecodeError::InvalidFieldNumber);
157        }
158        Self::from_raw_u32(value as u32)
159    }
160
161    /// Construct a tag from its raw u32 wire representation
162    /// (`field_number << 3 | wire_type`).
163    ///
164    /// Validates the wire type and rejects field number 0. `decode` guards
165    /// against values above `u32::MAX` before casting down and calling this.
166    #[inline]
167    fn from_raw_u32(value: u32) -> Result<Self, DecodeError> {
168        let wire_type = WireType::from_u32(value & 0x07)?;
169        let field_number = value >> 3;
170        if field_number == 0 {
171            return Err(DecodeError::InvalidFieldNumber);
172        }
173        // `field_number` is a u32 right-shifted by 3, so it is bounded by
174        // u32::MAX >> 3 = MAX_FIELD_NUMBER. No upper range check required.
175        Ok(Self {
176            field_number,
177            wire_type,
178        })
179    }
180}
181
182/// Encode a varint to a buffer.
183///
184/// Terminates in at most 10 iterations (⌈ 64/7 ⌉) for any `u64` input
185/// because `value >>= 7` monotonically decreases and eventually satisfies
186/// `value < 0x80`. An unbounded `loop` is used intentionally: a bounded
187/// `for _ in 0..10` adds loop-counter overhead that LLVM cannot eliminate
188/// (it cannot prove the inner `return` always fires), and this function is
189/// called for every tag and varint field on the encode hot path.
190#[inline]
191pub fn encode_varint(mut value: u64, buf: &mut impl EncodeSink) {
192    loop {
193        if value < 0x80 {
194            buf.put_u8(value as u8);
195            return;
196        }
197        buf.put_u8(((value & 0x7F) | 0x80) as u8);
198        value >>= 7;
199    }
200}
201
202/// Count the varints in a packed payload, i.e. the number of bytes whose
203/// continuation bit is clear (`b < 0x80`).
204///
205/// Every varint ends in exactly one such terminator byte, so for a well-formed
206/// packed payload this is the exact element count, computed in a single pass.
207/// The result is always `<= payload.len()` — equal only when every value is
208/// single-byte — so it never over-counts the way the raw byte length does for
209/// multi-byte varints. A truncated final varint (no terminator) makes the
210/// result one short, which is harmless when sizing a buffer: it costs at most
211/// one extra reallocation, and decoding then errors on the malformed bytes
212/// anyway.
213///
214/// Generated `decode_view` code uses this to size a packed varint field's
215/// backing storage in a single allocation.
216#[must_use]
217#[inline]
218pub fn count_varints(payload: &[u8]) -> usize {
219    payload.iter().filter(|&&b| b < 0x80).count()
220}
221
222/// Drive a well-formed packed varint payload element-by-element with the
223/// per-element dispatch hoisted out of the loop.
224///
225/// Precondition (checked by the caller): the payload's final byte has its
226/// continuation bit clear. Every suffix of such a payload also ends with a
227/// clear continuation bit, so the slice decoder's precondition holds at every
228/// element position and the loop needs no per-element chunk or remaining
229/// checks — the 1-2-byte common cases decode inline, longer elements fall
230/// through to the unrolled slice decoder.
231#[inline]
232pub(crate) fn for_each_packed_varint(
233    payload: &[u8],
234    mut f: impl FnMut(u64),
235) -> Result<(), DecodeError> {
236    debug_assert!(payload.is_empty() || payload[payload.len() - 1] < 0x80);
237    let mut i = 0;
238    while i < payload.len() {
239        let b0 = payload[i];
240        if b0 < 0x80 {
241            f(u64::from(b0));
242            i += 1;
243            continue;
244        }
245        // payload[i + 1] is in bounds: b0 has its continuation bit set, and
246        // the final byte does not, so i + 1 < payload.len().
247        let b1 = payload[i + 1];
248        if b1 < 0x80 {
249            f(u64::from(b0 & 0x7f) | u64::from(b1) << 7);
250            i += 2;
251            continue;
252        }
253        let (value, advance) = decode_varint_slice_always(&payload[i..])?;
254        f(value);
255        i += advance;
256    }
257    Ok(())
258}
259
260/// Decode a varint from a buffer.
261///
262/// Uses a chunk-based strategy for performance:
263/// 1. Single-byte fast path for values < 128 (common for tags, small lengths).
264/// 2. Unrolled slice decode when the contiguous chunk is large enough.
265/// 3. Byte-at-a-time fallback for non-contiguous or fragmented buffers.
266///
267/// Only the single-byte check is inlinable into callers; paths 2 and 3 run in
268/// an out-of-line function that calls `buf.chunk()` again. That second call
269/// is free for `&[u8]` and `Bytes` and a real call for `Chain`, `Take` and
270/// `dyn Buf`.
271///
272/// # Errors
273///
274/// Returns [`DecodeError::UnexpectedEof`] if the buffer ends before the
275/// varint's last byte, and [`DecodeError::VarintTooLong`] if the varint is
276/// longer than ten bytes or its tenth byte sets bits above bit 63. After an
277/// error the position of `buf` is unspecified.
278// Plain `#[inline]`, not `#[inline(always)]`: the check is a load, a compare
279// and a pointer bump, so a one-byte varint (a length prefix, a small scalar)
280// skips the out-of-line call and the `Result<u64, _>` returned through
281// memory. The rest of the decoder stays out of line; see
282// `decode_varint_packed` for why force-inlining all of it is not done.
283#[inline]
284pub fn decode_varint(buf: &mut impl Buf) -> Result<u64, DecodeError> {
285    if let Some(&first) = buf.chunk().first() {
286        if first < 0x80 {
287            buf.advance(1);
288            return Ok(u64::from(first));
289        }
290    }
291    decode_varint_multibyte(buf)
292}
293
294/// The out-of-line remainder of `decode_varint`: an empty chunk, or a varint
295/// of two or more bytes. Correct for any buffer, including one whose first
296/// byte is below `0x80`, but its callers have already handled that case.
297#[inline(never)]
298pub(crate) fn decode_varint_multibyte(buf: &mut impl Buf) -> Result<u64, DecodeError> {
299    let chunk = buf.chunk();
300    let len = chunk.len();
301    if len == 0 {
302        return Err(DecodeError::UnexpectedEof);
303    }
304
305    // Keep this branch condition in sync with `decode_varint_packed`; packed
306    // repeated loops duplicate this body to preserve the force-inlined path.
307    // The chunk either contains the full varint (len > 10, or the last byte
308    // in the chunk has its continuation bit clear) or it may be split across
309    // chunks. In the first case we can decode directly from the slice.
310    if len > 10 || chunk[len - 1] < 0x80 {
311        let (value, advance) = decode_varint_slice(chunk)?;
312        buf.advance(advance);
313        Ok(value)
314    } else {
315        decode_varint_slow(buf)
316    }
317}
318
319/// [`decode_varint`] with the fast paths force-inlined, for packed-repeated
320/// element loops only.
321///
322/// Packed payloads decode one varint per element in a tight generated loop,
323/// where the out-of-line `decode_varint_slice` call boundary is a measured
324/// ~16–28% cost on packed-varint-dense decode/merge (bare-metal A/B at the
325/// layout-normalized profile, 2026-06; other sites quoting this figure
326/// reference this doc rather than restating it). Force-inlining is
327/// intentionally restricted to this entry point: applying it to
328/// [`decode_varint`] globally regresses large view-decode functions
329/// (code-size/front-end pressure), so singular-field decoding inlines only
330/// the one-byte check and calls `decode_varint_multibyte` for the rest. The
331/// fragmented-buffer fallback stays out of line and cold.
332///
333/// This function deliberately duplicates the one-byte check in
334/// [`decode_varint`] and the dispatch in `decode_varint_multibyte`: sharing
335/// them would re-couple the functions in the inliner and reintroduce the
336/// placement instability this split exists to avoid. Keep them in sync. The
337/// `len > 10 || chunk[len - 1] < 0x80` condition is the precondition the
338/// slice decoders' assertions rely on for bounds-check elimination.
339#[inline(always)]
340pub(crate) fn decode_varint_packed(buf: &mut impl Buf) -> Result<u64, DecodeError> {
341    let chunk = buf.chunk();
342    let len = chunk.len();
343    if len == 0 {
344        return Err(DecodeError::UnexpectedEof);
345    }
346
347    let first = chunk[0];
348    if first < 0x80 {
349        buf.advance(1);
350        return Ok(u64::from(first));
351    }
352
353    if len > 10 || chunk[len - 1] < 0x80 {
354        let (value, advance) = decode_varint_slice_always(chunk)?;
355        buf.advance(advance);
356        Ok(value)
357    } else {
358        decode_varint_slow(buf)
359    }
360}
361
362// One body, two emission forms: `decode_varint_slice` (compiler-judged
363// `#[inline]`, inlinable into `decode_varint_multibyte`, the path for singular
364// fields) and `decode_varint_slice_always` (force-inlined, used only by
365// `decode_varint_packed` in packed-repeated element loops). A macro rather
366// than a delegating wrapper: a thin wrapper gets merged by the inliner,
367// which changes both callers' inlining decisions — the macro keeps the two
368// functions physically independent. The caller contract / `# Panics`
369// docs are passed through each invocation below so both emitted functions
370// carry them.
371macro_rules! decode_varint_slice_fn {
372    ($(#[$attr:meta])* fn $name:ident) => {
373        $(#[$attr])*
374        fn $name(bytes: &[u8]) -> Result<(u64, usize), DecodeError> {
375    // These assertions are always satisfied by the callers' dispatch
376    // logic and exist so the optimizer can prove all subsequent indexing is
377    // in-bounds, eliminating per-byte bounds checks after inlining.
378    assert!(!bytes.is_empty());
379    assert!(bytes.len() > 10 || bytes[bytes.len() - 1] < 0x80);
380
381    // Unrolled varint decoding split into three 32-bit accumulators to reduce
382    // 64-bit arithmetic on 32-bit targets and improve pipelining everywhere.
383
384    let mut b: u8 = bytes[0];
385    let mut part0: u32 = u32::from(b);
386    if b < 0x80 {
387        return Ok((u64::from(part0), 1));
388    }
389    part0 -= 0x80;
390
391    b = bytes[1];
392    part0 += u32::from(b) << 7;
393    if b < 0x80 {
394        return Ok((u64::from(part0), 2));
395    }
396    part0 -= 0x80 << 7;
397
398    b = bytes[2];
399    part0 += u32::from(b) << 14;
400    if b < 0x80 {
401        return Ok((u64::from(part0), 3));
402    }
403    part0 -= 0x80 << 14;
404
405    b = bytes[3];
406    part0 += u32::from(b) << 21;
407    if b < 0x80 {
408        return Ok((u64::from(part0), 4));
409    }
410    part0 -= 0x80 << 21;
411
412    let value = u64::from(part0);
413
414    b = bytes[4];
415    let mut part1: u32 = u32::from(b);
416    if b < 0x80 {
417        return Ok((value + (u64::from(part1) << 28), 5));
418    }
419    part1 -= 0x80;
420
421    b = bytes[5];
422    part1 += u32::from(b) << 7;
423    if b < 0x80 {
424        return Ok((value + (u64::from(part1) << 28), 6));
425    }
426    part1 -= 0x80 << 7;
427
428    b = bytes[6];
429    part1 += u32::from(b) << 14;
430    if b < 0x80 {
431        return Ok((value + (u64::from(part1) << 28), 7));
432    }
433    part1 -= 0x80 << 14;
434
435    b = bytes[7];
436    part1 += u32::from(b) << 21;
437    if b < 0x80 {
438        return Ok((value + (u64::from(part1) << 28), 8));
439    }
440    part1 -= 0x80 << 21;
441
442    let value = value + (u64::from(part1) << 28);
443
444    b = bytes[8];
445    let mut part2: u32 = u32::from(b);
446    if b < 0x80 {
447        return Ok((value + (u64::from(part2) << 56), 9));
448    }
449    part2 -= 0x80;
450
451    b = bytes[9];
452    part2 += u32::from(b) << 7;
453
454    // 10th byte: only bit 0 maps to bit 63 of the result. A byte >= 0x02
455    // means either overflow bits are set or the continuation bit implies an
456    // 11th byte — both are malformed.
457    if b >= 0x02 {
458        return Err(DecodeError::VarintTooLong);
459    }
460
461    Ok((value + (u64::from(part2) << 56), 10))
462        }
463    };
464}
465
466decode_varint_slice_fn!(
467    /// Decode a varint from a contiguous byte slice, returning the value and
468    /// the number of bytes consumed. See the macro note above for why this
469    /// body is emitted twice.
470    ///
471    /// The caller must ensure that `bytes` is non-empty and that either
472    /// `bytes.len() > 10` or the last byte in `bytes` has its continuation
473    /// bit clear (< 0x80). Under these conditions every index up to the
474    /// terminating byte is guaranteed to be in bounds, so no per-byte bounds
475    /// check is needed beyond the initial assertions.
476    ///
477    /// # Panics
478    ///
479    /// Panics if `bytes` is empty or if the last byte has its continuation
480    /// bit set while `bytes.len() <= 10`. These conditions are guaranteed by
481    /// the callers (`decode_varint_multibyte` / `decode_varint_packed`), so the
482    /// assertions serve as optimizer hints.
483    #[inline]
484    fn decode_varint_slice
485);
486decode_varint_slice_fn!(
487    /// Force-inlined twin of [`decode_varint_slice`] for packed loops; same
488    /// caller contract and `# Panics` conditions (see its doc).
489    #[inline(always)]
490    fn decode_varint_slice_always
491);
492
493/// Byte-at-a-time varint decode for non-contiguous or fragmented buffers.
494///
495/// This is the slow path used when the contiguous chunk from `buf.chunk()`
496/// does not contain the complete varint. Marked `#[cold]` because this path
497/// is rarely taken with typical `Bytes` or `&[u8]` inputs.
498#[inline(never)]
499#[cold]
500fn decode_varint_slow(buf: &mut impl Buf) -> Result<u64, DecodeError> {
501    let mut value: u64 = 0;
502    let mut shift: u32 = 0;
503    let limit = core::cmp::min(10, buf.remaining());
504    for _ in 0..limit {
505        let byte = buf.get_u8();
506        if shift < 63 {
507            value |= ((byte & 0x7F) as u64) << shift;
508            if byte < 0x80 {
509                return Ok(value);
510            }
511            shift += 7;
512        } else {
513            // 10th byte: only bit 0 maps to bit 63 of the result. A byte
514            // > 0x01 means either data overflow (bits 1-6 set) or an 11th
515            // byte (continuation bit 0x80 set). This is equivalent to the
516            // `b >= 0x02` check in `decode_varint_slice`.
517            if byte > 0x01 {
518                return Err(DecodeError::VarintTooLong);
519            }
520            value |= (byte as u64) << 63;
521            return Ok(value);
522        }
523    }
524    Err(DecodeError::UnexpectedEof)
525}
526
527/// Compute the encoded length of a varint.
528#[inline]
529pub const fn varint_len(value: u64) -> usize {
530    // ceil(significant bits / 7) without a branch or a real division (`/ 64`
531    // is a shift). `value | 1` makes zero count as one bit, and
532    // `(9 * log2 + 73) / 64` equals `log2 / 7 + 1` for every log2 in 0..=63
533    // (protobuf's VarintSize64).
534    let log2 = 63 - (value | 1).leading_zeros();
535    ((log2 * 9 + 73) / 64) as usize
536}
537
538/// Skip one field value from `buf` according to the wire type in `tag`.
539///
540/// Used by generated [`Message::merge`](crate::message::Message::merge)
541/// implementations to advance past unknown or unrecognised fields during
542/// decoding.  After this call `buf` is positioned immediately after the
543/// skipped field, ready for the next tag.
544///
545///
546/// # Errors
547///
548/// Returns an error if the buffer is too short, if a length-delimited payload
549/// length overflows `usize`, or if the wire type is a group.
550#[inline]
551pub fn skip_field(tag: Tag, buf: &mut impl Buf) -> Result<(), DecodeError> {
552    skip_field_depth(tag, buf, crate::RECURSION_LIMIT)
553}
554
555/// Skip an unknown wire field while enforcing explicit unknown-field rejection.
556///
557/// A decode started with a zero allowance rejects before reading the payload.
558/// Discarded fields do not materialize records and therefore do not consume a
559/// positive storage allowance. Default decoding remains unchanged.
560///
561/// # Errors
562///
563/// Returns [`DecodeError::UnknownFieldLimitExceeded`] when unknown fields are
564/// explicitly rejected, or a wire-format or recursion error for malformed input.
565pub fn skip_unknown_field(
566    tag: Tag,
567    buf: &mut impl Buf,
568    ctx: crate::DecodeContext<'_>,
569) -> Result<(), DecodeError> {
570    ctx.check_unknown_field()?;
571    skip_field_depth(tag, buf, ctx.depth())
572}
573
574/// Verify a decoded tag carries the expected wire type.
575///
576/// Generated `merge_field` / view-decode arms call this once per field arm
577/// before reading the payload, replacing an inline comparison + error
578/// construction at every arm. The mismatch path is delegated to the
579/// `#[cold]` [`wire_type_mismatch`] so the hot decode loop carries only the
580/// comparison.
581///
582/// # Errors
583///
584/// Returns [`DecodeError::WireTypeMismatch`] when `tag`'s wire type is not
585/// `expected`.
586#[inline]
587pub fn check_wire_type(tag: Tag, expected: WireType) -> Result<(), DecodeError> {
588    if tag.wire_type() != expected {
589        return Err(wire_type_mismatch(tag, expected));
590    }
591    Ok(())
592}
593
594/// Construct a [`DecodeError::WireTypeMismatch`] for `tag`.
595///
596/// Out of line and `#[cold]`: error construction never belongs in the
597/// per-field decode loop's instruction stream. Also called directly by
598/// generated repeated-field arms that accept two wire types (packed +
599/// unpacked) and report the packed `LengthDelimited` form as expected.
600#[cold]
601pub fn wire_type_mismatch(tag: Tag, expected: WireType) -> DecodeError {
602    DecodeError::WireTypeMismatch {
603        field_number: tag.field_number(),
604        expected: expected as u8,
605        actual: tag.wire_type() as u8,
606    }
607}
608
609/// Skip a field's payload, with an explicit recursion depth budget for groups.
610///
611/// Generated code must call this (not [`skip_field`]) when a decode context
612/// is in scope (passing `ctx.depth()`), to prevent unknown group fields from
613/// resetting the recursion budget and allowing depth-doubling attacks.
614///
615/// `depth` is the remaining nesting budget. For group fields this function
616/// calls itself recursively, decrementing `depth` by one each level.
617/// Unlike [`decode_unknown_field`], skipping materializes nothing, so this
618/// function deliberately takes only the depth — it never consumes the
619/// unknown-field allowance.
620///
621/// # Errors
622///
623/// Returns an error if the buffer is too short, if a length-delimited payload
624/// length overflows `usize`, if the wire type is `EndGroup` (malformed stream),
625/// or if group nesting exceeds `depth`.
626pub fn skip_field_depth(tag: Tag, buf: &mut impl Buf, depth: u32) -> Result<(), DecodeError> {
627    match tag.wire_type() {
628        WireType::Varint => {
629            decode_varint(buf)?;
630        }
631        WireType::Fixed64 => {
632            if buf.remaining() < 8 {
633                return Err(DecodeError::UnexpectedEof);
634            }
635            buf.advance(8);
636        }
637        WireType::LengthDelimited => {
638            let len = decode_varint(buf)?;
639            let len = usize::try_from(len).map_err(|_| DecodeError::MessageTooLarge)?;
640            if buf.remaining() < len {
641                return Err(DecodeError::UnexpectedEof);
642            }
643            buf.advance(len);
644        }
645        WireType::Fixed32 => {
646            if buf.remaining() < 4 {
647                return Err(DecodeError::UnexpectedEof);
648            }
649            buf.advance(4);
650        }
651        WireType::StartGroup => {
652            let depth = depth
653                .checked_sub(1)
654                .ok_or(DecodeError::RecursionLimitExceeded)?;
655            // Skip nested fields until the matching EndGroup tag.
656            loop {
657                let nested_tag = Tag::decode(buf)?;
658                if nested_tag.wire_type() == WireType::EndGroup {
659                    if nested_tag.field_number() != tag.field_number() {
660                        return Err(DecodeError::InvalidEndGroup(nested_tag.field_number()));
661                    }
662                    break;
663                }
664                skip_field_depth(nested_tag, buf, depth)?;
665            }
666        }
667        // EndGroup is consumed by the StartGroup handler above; seeing one
668        // here means the stream is malformed.
669        wt => {
670            return Err(DecodeError::InvalidWireType(wt as u8 as u32));
671        }
672    }
673    Ok(())
674}
675
676/// What [`register_unknown_record`] charged for one span: the slot count
677/// and the maximum group-nesting depth. `UnknownFieldsView` accumulates
678/// these so `to_owned` can replay under exactly the budget decode charged.
679pub(crate) struct UnknownSpanCharge {
680    /// Slots charged — one per field at every nesting level, matching the
681    /// `UnknownField`s [`decode_unknown_field`] materializes for the span.
682    pub fields: usize,
683    /// Deepest group nesting in the span — the recursion depth
684    /// [`decode_unknown_field`] needs to re-materialize it.
685    pub depth: u32,
686}
687
688/// Charge `ctx`'s unknown-field allowance with exactly the slots
689/// [`decode_unknown_field`] consumes when `span` is re-materialized: one per
690/// `(tag, value)` record, plus one per field nested inside unknown groups.
691///
692/// That count is simply the number of non-`EndGroup` tags in the span
693/// (`decode_unknown_field` materializes one `UnknownField` per field at
694/// every nesting level, and `EndGroup` tags close groups rather than start
695/// fields), so a flat scan suffices — no recursion, and no re-validation of
696/// group framing. `span` must hold complete records whose group tags are
697/// balanced and matched, which every caller guarantees by capturing the
698/// span from a successful [`skip_field_depth`] walk.
699///
700/// This is the decode-time accounting twin of [`decode_unknown_field`]:
701/// zero-copy view decoding stores the raw record bytes and defers
702/// materialization to `UnknownFieldsView::to_owned`, so it charges the
703/// allowance here instead, keeping decode-time and replay-time counts
704/// identical.
705pub(crate) fn register_unknown_record(
706    span: &[u8],
707    ctx: crate::DecodeContext<'_>,
708) -> Result<UnknownSpanCharge, DecodeError> {
709    let mut cur = span;
710    let mut charge = UnknownSpanCharge {
711        fields: 0,
712        depth: 0,
713    };
714    let mut depth = 0u32;
715    while !cur.is_empty() {
716        let tag = Tag::decode(&mut cur)?;
717        match tag.wire_type() {
718            WireType::EndGroup => depth = depth.saturating_sub(1),
719            WireType::StartGroup => {
720                ctx.register_unknown_field()?;
721                charge.fields = charge.fields.saturating_add(1);
722                depth = depth.saturating_add(1);
723                charge.depth = charge.depth.max(depth);
724            }
725            // Non-group payloads never recurse, so the depth argument is
726            // unused — pass zero rather than threading `ctx.depth()`.
727            _ => {
728                ctx.register_unknown_field()?;
729                charge.fields = charge.fields.saturating_add(1);
730                skip_field_depth(tag, &mut cur, 0)?;
731            }
732        }
733    }
734    Ok(charge)
735}
736
737/// Decode one unknown field's value from `buf` and return it as an
738/// [`UnknownField`](crate::unknown_fields::UnknownField).
739///
740/// The `tag` must already have been decoded; this function reads only the
741/// payload that follows it on the wire. Groups are decoded recursively until
742/// their matching `EndGroup` tag.
743///
744/// `ctx` carries the remaining nesting depth and the shared unknown-field
745/// allowance.  For group fields this function calls itself recursively,
746/// consuming one depth level each time.  When the depth reaches zero
747/// [`DecodeError::RecursionLimitExceeded`] is returned.  Construct a fresh
748/// [`DecodeContext`](crate::DecodeContext) at the outermost call site;
749/// generated code passes the `ctx` value received by the enclosing `merge`.
750///
751/// # Errors
752///
753/// Returns an error if the buffer is truncated, the wire type is
754/// `EndGroup` (which indicates a structural mismatch in the wire data),
755/// the recursion limit is exceeded, or the unknown-field limit is
756/// exceeded.
757///
758/// # Allocation
759///
760/// Unknown fields can occupy far more memory decoded than encoded: a
761/// 2-byte varint field becomes a ~40-byte
762/// [`UnknownField`](crate::UnknownField), so an input-size cap alone does
763/// **not** bound decoder memory. Every decoded field consumes one slot of
764/// the context's shared unknown-field allowance **before** it is
765/// materialized; when the allowance is exhausted decoding fails with
766/// [`DecodeError::UnknownFieldLimitExceeded`]. Length-delimited payload
767/// bytes are bounded by the input itself (the `buf.remaining() < len`
768/// check forces the sender to actually deliver them), so they are not
769/// counted against the limit — cap the input size to bound them.
770pub fn decode_unknown_field(
771    tag: Tag,
772    buf: &mut impl Buf,
773    ctx: crate::DecodeContext<'_>,
774) -> Result<crate::unknown_fields::UnknownField, DecodeError> {
775    use crate::unknown_fields::{UnknownField, UnknownFieldData, UnknownFields};
776
777    // Every decoded field occupies one `UnknownField` slot in its parent's
778    // vector — consume an allowance slot up front so runs of tiny fields
779    // (2 wire bytes each) cannot amplify into unbounded heap growth.
780    ctx.register_unknown_field()?;
781    let data = match tag.wire_type() {
782        WireType::Varint => UnknownFieldData::Varint(decode_varint(buf)?),
783        WireType::Fixed64 => {
784            if buf.remaining() < 8 {
785                return Err(DecodeError::UnexpectedEof);
786            }
787            UnknownFieldData::Fixed64(buf.get_u64_le())
788        }
789        WireType::Fixed32 => {
790            if buf.remaining() < 4 {
791                return Err(DecodeError::UnexpectedEof);
792            }
793            UnknownFieldData::Fixed32(buf.get_u32_le())
794        }
795        WireType::LengthDelimited => {
796            let len = decode_varint(buf)?;
797            let len = usize::try_from(len).map_err(|_| DecodeError::MessageTooLarge)?;
798            if buf.remaining() < len {
799                return Err(DecodeError::UnexpectedEof);
800            }
801            let mut data = alloc::vec![0u8; len];
802            buf.copy_to_slice(&mut data);
803            UnknownFieldData::LengthDelimited(data)
804        }
805        WireType::StartGroup => {
806            let ctx = ctx.descend()?;
807            let group_field_number = tag.field_number();
808            // Read nested fields until the matching EndGroup tag.
809            let mut nested = UnknownFields::new();
810            loop {
811                let nested_tag = Tag::decode(buf)?;
812                if nested_tag.wire_type() == WireType::EndGroup {
813                    // Per the protobuf spec the EndGroup tag must carry the same
814                    // field number as the opening StartGroup tag.
815                    if nested_tag.field_number() != group_field_number {
816                        return Err(DecodeError::InvalidEndGroup(nested_tag.field_number()));
817                    }
818                    break;
819                }
820                nested.push(decode_unknown_field(nested_tag, buf, ctx)?);
821            }
822            UnknownFieldData::Group(nested)
823        }
824        wt => return Err(DecodeError::InvalidWireType(wt as u8 as u32)),
825    };
826    Ok(UnknownField {
827        number: tag.field_number(),
828        data,
829    })
830}
831
832#[cfg(test)]
833mod tests {
834    #[test]
835    fn discarded_unknowns_preserve_storage_budgets_and_validate_groups() {
836        use core::cell::Cell;
837        let allowance = Cell::new(0);
838        let ctx = crate::DecodeContext::new(8, &allowance);
839        let tag = Tag::new(1, WireType::Varint);
840        let mut payload = &[1][..];
841        assert_eq!(
842            skip_unknown_field(tag, &mut payload, ctx),
843            Err(DecodeError::UnknownFieldLimitExceeded)
844        );
845        assert_eq!(payload, &[1]);
846        for (wire, budget, expected) in [
847            (&[0x10, 1, 0x0c][..], 2, Ok(())),
848            (&[0x10, 1, 0x0c][..], 1, Ok(())),
849            (&[0x14][..], 2, Err(DecodeError::InvalidEndGroup(2))),
850            (&[0x10][..], 2, Err(DecodeError::UnexpectedEof)),
851        ] {
852            allowance.set(budget);
853            let ctx = crate::DecodeContext::new(8, &allowance);
854            let mut payload = wire;
855            assert_eq!(
856                skip_unknown_field(Tag::new(1, WireType::StartGroup), &mut payload, ctx),
857                expected
858            );
859            assert_eq!(allowance.get(), budget);
860        }
861        allowance.set(2);
862        let mut payload = &[0x0c][..];
863        assert_eq!(
864            skip_unknown_field(
865                Tag::new(1, WireType::StartGroup),
866                &mut payload,
867                crate::DecodeContext::new(0, &allowance)
868            ),
869            Err(DecodeError::RecursionLimitExceeded)
870        );
871    }
872
873    use super::*;
874
875    #[test]
876    fn test_check_wire_type_match() {
877        let tag = Tag::new(3, WireType::Varint);
878        assert!(check_wire_type(tag, WireType::Varint).is_ok());
879    }
880
881    #[test]
882    fn test_check_wire_type_mismatch() {
883        let tag = Tag::new(3, WireType::Varint);
884        match check_wire_type(tag, WireType::LengthDelimited) {
885            Err(DecodeError::WireTypeMismatch {
886                field_number,
887                expected,
888                actual,
889            }) => {
890                assert_eq!(field_number, 3);
891                assert_eq!(expected, WireType::LengthDelimited as u8);
892                assert_eq!(actual, WireType::Varint as u8);
893            }
894            other => panic!("expected WireTypeMismatch, got {other:?}"),
895        }
896    }
897
898    #[test]
899    fn test_wire_type_mismatch_constructor() {
900        let tag = Tag::new(7, WireType::Fixed32);
901        let err = wire_type_mismatch(tag, WireType::Fixed64);
902        match err {
903            DecodeError::WireTypeMismatch {
904                field_number,
905                expected,
906                actual,
907            } => {
908                assert_eq!(field_number, 7);
909                assert_eq!(expected, 1);
910                assert_eq!(actual, 5);
911            }
912            other => panic!("expected WireTypeMismatch, got {other:?}"),
913        }
914    }
915
916    #[test]
917    fn test_varint_roundtrip() {
918        let test_values: &[u64] = &[0, 1, 127, 128, 255, 300, 16384, u64::MAX];
919        for &v in test_values {
920            let mut buf = Vec::new();
921            encode_varint(v, &mut buf);
922            assert_eq!(buf.len(), varint_len(v), "varint_len mismatch for {v}");
923            let decoded = decode_varint(&mut buf.as_slice()).unwrap();
924            assert_eq!(v, decoded, "roundtrip failed for {v}");
925        }
926    }
927
928    #[test]
929    fn test_varint_len_at_every_bit_length() {
930        // Both sides of every 7-bit group boundary, and of every bit length,
931        // since the branch-free formula works on the bit length.
932        let mut values = vec![0u64, u64::MAX];
933        for bits in 1..64 {
934            let pow = 1u64 << bits;
935            values.extend([pow - 1, pow, pow + 1]);
936        }
937        for v in values {
938            let mut buf = Vec::new();
939            encode_varint(v, &mut buf);
940            assert_eq!(varint_len(v), buf.len(), "varint_len mismatch for {v}");
941        }
942        // Still usable in const contexts.
943        const LENS: [usize; 3] = [varint_len(0), varint_len(127), varint_len(u64::MAX)];
944        assert_eq!(LENS, [1, 1, 10]);
945    }
946
947    #[test]
948    fn test_decode_varint_packed_parity() {
949        // `decode_varint_packed` must agree with `decode_varint` on every
950        // path: single-byte fast path, multi-byte slice path, and the
951        // fragmented-buffer slow path.
952        let test_values: &[u64] = &[0, 1, 127, 128, 255, 300, 16384, 1 << 28, 1 << 56, u64::MAX];
953        for &v in test_values {
954            let mut buf = Vec::new();
955            encode_varint(v, &mut buf);
956            let plain = decode_varint(&mut buf.as_slice()).unwrap();
957            let packed = decode_varint_packed(&mut buf.as_slice()).unwrap();
958            assert_eq!(plain, packed, "parity failed for {v}");
959            if buf.len() > 1 {
960                // Split mid-varint so the packed decoder takes the
961                // fragmented-buffer slow path.
962                let mid = buf.len() / 2;
963                let first = bytes::Bytes::copy_from_slice(&buf[..mid]);
964                let second = bytes::Bytes::copy_from_slice(&buf[mid..]);
965                let mut chain = first.chain(second);
966                assert_eq!(
967                    decode_varint_packed(&mut chain).unwrap(),
968                    v,
969                    "fragmented parity failed for {v}"
970                );
971                assert_eq!(chain.remaining(), 0);
972            }
973        }
974    }
975
976    #[test]
977    fn test_decode_varint_packed_errors_match_plain() {
978        // Empty buffer.
979        assert_eq!(
980            decode_varint_packed(&mut [].as_slice()),
981            Err(DecodeError::UnexpectedEof)
982        );
983        // Truncated multi-byte varint (continuation bit set, no next byte).
984        assert_eq!(
985            decode_varint_packed(&mut [0x80u8].as_slice()),
986            Err(DecodeError::UnexpectedEof)
987        );
988        // 11-byte varint: continuation bits past the 10-byte maximum.
989        let mut too_long = vec![0x80u8; 10];
990        too_long.push(0x01);
991        assert_eq!(
992            decode_varint_packed(&mut too_long.as_slice()),
993            Err(DecodeError::VarintTooLong)
994        );
995        assert_eq!(
996            decode_varint(&mut too_long.as_slice()),
997            Err(DecodeError::VarintTooLong)
998        );
999        // Exactly 10 bytes with overflow bits in the last byte: taken via
1000        // the `chunk[len - 1] < 0x80` disjunct, hitting the `b >= 0x02`
1001        // check inside the force-inlined slice body — the only branch of
1002        // the always-twin that valid encodings never reach.
1003        let mut overflow10 = vec![0x80u8; 9];
1004        overflow10.push(0x02);
1005        assert_eq!(
1006            decode_varint_packed(&mut overflow10.as_slice()),
1007            Err(DecodeError::VarintTooLong)
1008        );
1009        assert_eq!(
1010            decode_varint(&mut overflow10.as_slice()),
1011            Err(DecodeError::VarintTooLong)
1012        );
1013        // VarintTooLong via the fragmented-buffer slow path: split the
1014        // 11-byte malformed varint across two chunks.
1015        let first = bytes::Bytes::copy_from_slice(&too_long[..5]);
1016        let second = bytes::Bytes::copy_from_slice(&too_long[5..]);
1017        let mut chain = first.chain(second);
1018        assert_eq!(
1019            decode_varint_packed(&mut chain),
1020            Err(DecodeError::VarintTooLong)
1021        );
1022    }
1023
1024    #[test]
1025    fn test_tag_roundtrip() {
1026        let tag = Tag::new(1, WireType::Varint);
1027        let mut buf = Vec::new();
1028        tag.encode(&mut buf);
1029        let decoded = Tag::decode(&mut buf.as_slice()).unwrap();
1030        assert_eq!(tag, decoded);
1031    }
1032
1033    #[test]
1034    fn test_tag_high_field_number() {
1035        let tag = Tag::new(MAX_FIELD_NUMBER, WireType::LengthDelimited);
1036        let mut buf = Vec::new();
1037        tag.encode(&mut buf);
1038        let decoded = Tag::decode(&mut buf.as_slice()).unwrap();
1039        assert_eq!(tag, decoded);
1040    }
1041
1042    #[test]
1043    fn test_zero_field_number_rejected() {
1044        // Field number 0 is invalid in protobuf
1045        let mut buf = Vec::new();
1046        encode_varint(0b0000_0000, &mut buf); // field 0, wire type 0
1047        let result = Tag::decode(&mut buf.as_slice());
1048        assert!(result.is_err());
1049    }
1050
1051    #[test]
1052    fn test_oversize_field_number_rejected() {
1053        // Field number 2^29 = 536_870_912 encodes to a tag value of
1054        // 536_870_912 << 3 = 2^32, which exceeds u32::MAX and is rejected
1055        // by the overflow check in Tag::decode.
1056        let mut buf = Vec::new();
1057        encode_varint(536_870_912u64 << 3, &mut buf);
1058        assert_eq!(
1059            Tag::decode(&mut buf.as_slice()),
1060            Err(DecodeError::InvalidFieldNumber)
1061        );
1062    }
1063
1064    #[test]
1065    fn test_tag_single_byte_fast_path() {
1066        // The fast path handles all one-byte tags: field numbers 1-15,
1067        // any wire type. Verify the boundary at both ends and that invalid
1068        // wire types / field 0 are still rejected through the fast path.
1069        #[rustfmt::skip]
1070        let cases: &[(u8, Option<(u32, WireType)>)] = &[
1071            (0x08, Some((1,  WireType::Varint))),          // field 1, wire 0 — smallest valid
1072            (0x0A, Some((1,  WireType::LengthDelimited))), // field 1, wire 2
1073            (0x7D, Some((15, WireType::Fixed32))),         // field 15, wire 5 — largest one-byte
1074            (0x78, Some((15, WireType::Varint))),          // field 15, wire 0
1075            (0x00, None),                                  // field 0 — invalid through fast path
1076            (0x07, None),                                  // field 0, wire 7 — invalid wire type also caught
1077            (0x0E, None),                                  // field 1, wire 6 — invalid wire type
1078        ];
1079        for &(byte, expected) in cases {
1080            let buf = [byte];
1081            let result = Tag::decode(&mut &buf[..]);
1082            match expected {
1083                Some((fn_, wt)) => {
1084                    let t = result.unwrap_or_else(|e| panic!("byte {byte:#04x}: {e:?}"));
1085                    assert_eq!(t.field_number(), fn_, "byte {byte:#04x}");
1086                    assert_eq!(t.wire_type(), wt, "byte {byte:#04x}");
1087                }
1088                None => assert!(result.is_err(), "byte {byte:#04x} should be rejected"),
1089            }
1090        }
1091    }
1092
1093    #[test]
1094    fn test_tag_field_16_takes_slow_path() {
1095        // Field number 16 with wire type 0 encodes as [0x80, 0x01] — two
1096        // bytes, so it should take the multi-byte path via decode_varint_multibyte.
1097        let tag = Tag::new(16, WireType::Varint);
1098        let mut buf = Vec::new();
1099        tag.encode(&mut buf);
1100        assert_eq!(buf, [0x80, 0x01]); // continuation bit set on first byte
1101        let decoded = Tag::decode(&mut buf.as_slice()).unwrap();
1102        assert_eq!(decoded.field_number(), 16);
1103        assert_eq!(decoded.wire_type(), WireType::Varint);
1104    }
1105
1106    #[test]
1107    fn test_varint_u64_max_roundtrip() {
1108        // u64::MAX requires all 10 bytes with the 10th byte == 0x01.
1109        let mut buf = Vec::new();
1110        encode_varint(u64::MAX, &mut buf);
1111        assert_eq!(buf.len(), 10);
1112        assert_eq!(buf[9], 0x01); // 10th byte must be exactly 0x01
1113        let decoded = decode_varint(&mut buf.as_slice()).unwrap();
1114        assert_eq!(decoded, u64::MAX);
1115    }
1116
1117    #[test]
1118    fn test_varint_10th_byte_overflow_rejected() {
1119        // 10th byte with overflow bits set (0x02–0x7F) must be rejected.
1120        // This encodes a value that would overflow u64.
1121        let mut buf: Vec<u8> = vec![0xFF; 9]; // 9 continuation bytes
1122        buf.push(0x02); // 10th byte: bit 1 set → overflow
1123        assert_eq!(
1124            decode_varint(&mut buf.as_slice()),
1125            Err(DecodeError::VarintTooLong)
1126        );
1127    }
1128
1129    #[test]
1130    fn test_varint_11th_byte_rejected() {
1131        // 10th byte with continuation bit set implies an 11th byte → always malformed.
1132        let buf: Vec<u8> = vec![0xFF; 10]; // 10 continuation bytes
1133        assert_eq!(
1134            decode_varint(&mut buf.as_slice()),
1135            Err(DecodeError::VarintTooLong)
1136        );
1137    }
1138
1139    #[test]
1140    fn test_skip_field_varint() {
1141        // Encode field 1 = varint 300, then check skip consumes it.
1142        let mut buf = Vec::new();
1143        let tag = Tag::new(1, WireType::Varint);
1144        tag.encode(&mut buf);
1145        encode_varint(300, &mut buf);
1146        // Prepend a second tag/value to verify skip stops at the right byte.
1147        let mut combined = buf.clone();
1148        let tag2 = Tag::new(2, WireType::Varint);
1149        tag2.encode(&mut combined);
1150        encode_varint(1, &mut combined);
1151
1152        let slice = &mut combined.as_slice();
1153        let t = Tag::decode(slice).unwrap();
1154        skip_field(t, slice).unwrap();
1155        // After skipping field 1, we should see tag 2.
1156        let t2 = Tag::decode(slice).unwrap();
1157        assert_eq!(t2.field_number(), 2);
1158    }
1159
1160    #[test]
1161    fn test_skip_field_fixed32() {
1162        let mut buf = Vec::new();
1163        Tag::new(1, WireType::Fixed32).encode(&mut buf);
1164        buf.extend_from_slice(&[0xAA, 0xBB, 0xCC, 0xDD]);
1165
1166        let slice = &mut buf.as_slice();
1167        let t = Tag::decode(slice).unwrap();
1168        skip_field(t, slice).unwrap();
1169        assert!(slice.is_empty());
1170    }
1171
1172    #[test]
1173    fn test_skip_field_fixed64() {
1174        let mut buf = Vec::new();
1175        Tag::new(1, WireType::Fixed64).encode(&mut buf);
1176        buf.extend_from_slice(&[0u8; 8]);
1177
1178        let slice = &mut buf.as_slice();
1179        let t = Tag::decode(slice).unwrap();
1180        skip_field(t, slice).unwrap();
1181        assert!(slice.is_empty());
1182    }
1183
1184    #[test]
1185    fn test_skip_field_length_delimited() {
1186        let mut buf = Vec::new();
1187        Tag::new(1, WireType::LengthDelimited).encode(&mut buf);
1188        encode_varint(3, &mut buf); // length = 3
1189        buf.extend_from_slice(&[0xAA, 0xBB, 0xCC]);
1190
1191        let slice = &mut buf.as_slice();
1192        let t = Tag::decode(slice).unwrap();
1193        skip_field(t, slice).unwrap();
1194        assert!(slice.is_empty());
1195    }
1196
1197    #[test]
1198    fn test_skip_field_truncated_returns_error() {
1199        let mut buf = Vec::new();
1200        Tag::new(1, WireType::Fixed32).encode(&mut buf);
1201        buf.extend_from_slice(&[0x01, 0x02]); // only 2 bytes, not 4
1202
1203        let slice = &mut buf.as_slice();
1204        let t = Tag::decode(slice).unwrap();
1205        assert_eq!(skip_field(t, slice), Err(DecodeError::UnexpectedEof));
1206    }
1207
1208    #[test]
1209    fn test_skip_field_start_group_empty_buf() {
1210        let tag = Tag::new(1, WireType::StartGroup);
1211        let mut buf: &[u8] = &[];
1212        assert_eq!(skip_field(tag, &mut buf), Err(DecodeError::UnexpectedEof));
1213    }
1214
1215    #[test]
1216    fn test_skip_field_start_group_with_end() {
1217        // Build: StartGroup(1) already consumed, then varint field 2 = 42,
1218        // then EndGroup(1).
1219        let mut data = Vec::new();
1220        Tag::new(2, WireType::Varint).encode(&mut data);
1221        encode_varint(42, &mut data);
1222        Tag::new(1, WireType::EndGroup).encode(&mut data);
1223
1224        let tag = Tag::new(1, WireType::StartGroup);
1225        let mut buf: &[u8] = &data;
1226        assert_eq!(skip_field(tag, &mut buf), Ok(()));
1227        assert!(buf.is_empty());
1228    }
1229
1230    #[test]
1231    fn test_skip_field_start_group_wrong_end() {
1232        // EndGroup with mismatched field number.
1233        let mut data = Vec::new();
1234        Tag::new(99, WireType::EndGroup).encode(&mut data);
1235
1236        let tag = Tag::new(1, WireType::StartGroup);
1237        let mut buf: &[u8] = &data;
1238        assert_eq!(
1239            skip_field(tag, &mut buf),
1240            Err(DecodeError::InvalidEndGroup(99))
1241        );
1242    }
1243
1244    #[test]
1245    fn test_skip_field_end_group_returns_invalid_wire_type() {
1246        let tag = Tag::new(1, WireType::EndGroup);
1247        let mut buf: &[u8] = &[];
1248        assert_eq!(
1249            skip_field(tag, &mut buf),
1250            Err(DecodeError::InvalidWireType(4))
1251        );
1252    }
1253
1254    // ---- decode_unknown_field: group recursion limit ----------------------
1255
1256    /// Build the bytes that follow an already-decoded StartGroup tag for
1257    /// `field_number`: zero or more inner fields then the matching EndGroup.
1258    fn encode_group_payload(field_number: u32, inner: &[u8]) -> Vec<u8> {
1259        let mut buf = inner.to_vec();
1260        Tag::new(field_number, WireType::EndGroup).encode(&mut buf);
1261        buf
1262    }
1263
1264    #[test]
1265    fn test_decode_unknown_field_group_at_depth_1_succeeds() {
1266        // depth = 1: checked_sub(1) = 0, which is the floor but still Ok.
1267        let payload = encode_group_payload(1, &[]);
1268        let tag = Tag::new(1, WireType::StartGroup);
1269        let result = decode_unknown_field(tag, &mut payload.as_slice(), crate::test_ctx(1));
1270        assert!(result.is_ok());
1271    }
1272
1273    #[test]
1274    fn test_decode_unknown_field_group_at_depth_0_exceeds_limit() {
1275        // depth = 0: checked_sub(1) returns None → RecursionLimitExceeded.
1276        let payload = encode_group_payload(1, &[]);
1277        let tag = Tag::new(1, WireType::StartGroup);
1278        assert_eq!(
1279            decode_unknown_field(tag, &mut payload.as_slice(), crate::test_ctx(0)),
1280            Err(DecodeError::RecursionLimitExceeded)
1281        );
1282    }
1283
1284    // ---- decode_unknown_field: unknown-field limit -------------------------
1285
1286    /// Group-amplification payload: the body of a group containing `n`
1287    /// minimal (2-byte) varint fields. Each inflates to a ~40-byte
1288    /// `UnknownField`, so wire size amplifies ~20× in memory.
1289    fn group_amp_body(n: usize) -> Vec<u8> {
1290        let mut inner = Vec::with_capacity(2 * n);
1291        for _ in 0..n {
1292            inner.push(0x08); // field 1, Varint
1293            inner.push(0x00); // value 0
1294        }
1295        encode_group_payload(1, &inner)
1296    }
1297
1298    #[test]
1299    fn test_group_amplification_exhausts_limit() {
1300        // 1000 nested 2-byte varints, but only 100 unknown-field slots:
1301        // the decoder must refuse long before materializing them all.
1302        let payload = group_amp_body(1000);
1303        let limit = core::cell::Cell::new(100);
1304        let ctx = crate::DecodeContext::new(crate::RECURSION_LIMIT, &limit);
1305        let tag = Tag::new(1, WireType::StartGroup);
1306        assert_eq!(
1307            decode_unknown_field(tag, &mut payload.as_slice(), ctx),
1308            Err(DecodeError::UnknownFieldLimitExceeded)
1309        );
1310    }
1311
1312    #[test]
1313    fn test_group_amplification_within_limit_succeeds() {
1314        // The same payload decodes fine when the limit covers it.
1315        let payload = group_amp_body(1000);
1316        let limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
1317        let ctx = crate::DecodeContext::new(crate::RECURSION_LIMIT, &limit);
1318        let tag = Tag::new(1, WireType::StartGroup);
1319        let field = decode_unknown_field(tag, &mut payload.as_slice(), ctx).unwrap();
1320        let crate::unknown_fields::UnknownFieldData::Group(nested) = field.data else {
1321            panic!("expected group");
1322        };
1323        assert_eq!(nested.iter().count(), 1000);
1324        // The allowance recorded all 1001 UnknownField slots (1000 nested +
1325        // the group itself).
1326        assert_eq!(
1327            limit.get(),
1328            crate::DEFAULT_UNKNOWN_FIELD_LIMIT - 1001,
1329            "every decoded field must consume one slot"
1330        );
1331    }
1332
1333    #[test]
1334    fn test_limit_shared_across_sibling_fields() {
1335        // Two sibling unknown fields decoded under one context draw from the
1336        // same allowance: one slot admits the first field but not the second.
1337        let limit = core::cell::Cell::new(1);
1338        let ctx = crate::DecodeContext::new(crate::RECURSION_LIMIT, &limit);
1339        let tag = Tag::new(1, WireType::Varint);
1340        let mut payload: &[u8] = &[0x00];
1341        decode_unknown_field(tag, &mut payload, ctx).expect("first field fits");
1342        let mut payload: &[u8] = &[0x00];
1343        assert_eq!(
1344            decode_unknown_field(tag, &mut payload, ctx),
1345            Err(DecodeError::UnknownFieldLimitExceeded)
1346        );
1347    }
1348
1349    #[test]
1350    fn test_length_delimited_payload_counts_as_one_field() {
1351        // A large length-delimited payload consumes exactly one slot — its
1352        // bytes are bounded by the input, not by the field limit.
1353        let mut payload = Vec::new();
1354        encode_varint(4096, &mut payload);
1355        payload.extend_from_slice(&[0u8; 4096]);
1356        let limit = core::cell::Cell::new(1);
1357        let ctx = crate::DecodeContext::new(crate::RECURSION_LIMIT, &limit);
1358        let tag = Tag::new(1, WireType::LengthDelimited);
1359        decode_unknown_field(tag, &mut payload.as_slice(), ctx).expect("one slot suffices");
1360        assert_eq!(limit.get(), 0);
1361        // With no slots left, even a minimal field is refused.
1362        let mut tiny: &[u8] = &[0x00];
1363        assert_eq!(
1364            decode_unknown_field(Tag::new(1, WireType::Varint), &mut tiny, ctx),
1365            Err(DecodeError::UnknownFieldLimitExceeded)
1366        );
1367    }
1368
1369    #[test]
1370    fn test_length_delimited_truncated_still_reports_eof() {
1371        // A truncated payload reports UnexpectedEof: the declared length is
1372        // never allocated unless the sender actually delivers the bytes.
1373        let mut payload = Vec::new();
1374        encode_varint(4096, &mut payload);
1375        payload.extend_from_slice(&[0u8; 16]); // 16 of 4096 bytes
1376        let limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
1377        let ctx = crate::DecodeContext::new(crate::RECURSION_LIMIT, &limit);
1378        let tag = Tag::new(1, WireType::LengthDelimited);
1379        assert_eq!(
1380            decode_unknown_field(tag, &mut payload.as_slice(), ctx),
1381            Err(DecodeError::UnexpectedEof)
1382        );
1383    }
1384
1385    #[test]
1386    fn test_decode_unknown_field_end_group_mismatched_field_number() {
1387        // Group opened as field 1 but closed with field 2's EndGroup tag.
1388        let mut payload = Vec::new();
1389        Tag::new(2, WireType::EndGroup).encode(&mut payload); // wrong field number
1390        let tag = Tag::new(1, WireType::StartGroup);
1391        assert_eq!(
1392            decode_unknown_field(tag, &mut payload.as_slice(), crate::test_ctx(1)),
1393            Err(DecodeError::InvalidEndGroup(2))
1394        );
1395    }
1396
1397    #[test]
1398    fn test_decode_unknown_field_all_wire_types() {
1399        // Table-driven: each wire type → expected UnknownFieldData variant.
1400        // Covers Fixed32, Fixed64, LengthDelimited, and StartGroup with
1401        // nested fields (the Varint and empty-group cases are above).
1402        use crate::unknown_fields::{UnknownField, UnknownFieldData};
1403
1404        struct Case {
1405            tag: Tag,
1406            payload: Vec<u8>,
1407            expected: UnknownFieldData,
1408        }
1409        let cases = vec![
1410            // Varint: 300 encoded as [0xAC, 0x02].
1411            Case {
1412                tag: Tag::new(1, WireType::Varint),
1413                payload: {
1414                    let mut b = Vec::new();
1415                    encode_varint(300, &mut b);
1416                    b
1417                },
1418                expected: UnknownFieldData::Varint(300),
1419            },
1420            // Fixed32: 0xDEADBEEF little-endian.
1421            Case {
1422                tag: Tag::new(2, WireType::Fixed32),
1423                payload: 0xDEAD_BEEF_u32.to_le_bytes().to_vec(),
1424                expected: UnknownFieldData::Fixed32(0xDEAD_BEEF),
1425            },
1426            // Fixed64: full-width value little-endian.
1427            Case {
1428                tag: Tag::new(3, WireType::Fixed64),
1429                payload: 0x1234_5678_9ABC_DEF0_u64.to_le_bytes().to_vec(),
1430                expected: UnknownFieldData::Fixed64(0x1234_5678_9ABC_DEF0),
1431            },
1432            // LengthDelimited: len-prefix 3 + bytes "abc".
1433            Case {
1434                tag: Tag::new(4, WireType::LengthDelimited),
1435                payload: {
1436                    let mut b = Vec::new();
1437                    encode_varint(3, &mut b);
1438                    b.extend_from_slice(b"abc");
1439                    b
1440                },
1441                expected: UnknownFieldData::LengthDelimited(b"abc".to_vec()),
1442            },
1443            // StartGroup with nested varint field 1 = 42.
1444            Case {
1445                tag: Tag::new(5, WireType::StartGroup),
1446                payload: {
1447                    let mut inner = Vec::new();
1448                    Tag::new(1, WireType::Varint).encode(&mut inner);
1449                    encode_varint(42, &mut inner);
1450                    encode_group_payload(5, &inner)
1451                },
1452                expected: UnknownFieldData::Group({
1453                    let mut fields = crate::unknown_fields::UnknownFields::new();
1454                    fields.push(UnknownField {
1455                        number: 1,
1456                        data: UnknownFieldData::Varint(42),
1457                    });
1458                    fields
1459                }),
1460            },
1461        ];
1462
1463        for case in cases {
1464            let got = decode_unknown_field(
1465                case.tag,
1466                &mut case.payload.as_slice(),
1467                crate::test_ctx(crate::RECURSION_LIMIT),
1468            )
1469            .unwrap_or_else(|e| panic!("decode failed for tag {:?}: {e}", case.tag));
1470            assert_eq!(got.number, case.tag.field_number());
1471            assert_eq!(got.data, case.expected, "tag {:?}", case.tag);
1472        }
1473    }
1474
1475    #[test]
1476    fn test_decode_unknown_field_eof_rejection() {
1477        // Each fixed-width / length-delimited wire type with truncated payload.
1478        #[rustfmt::skip]
1479        let cases: &[(Tag, &[u8])] = &[
1480            // Fixed32 needs 4 bytes; give 3.
1481            (Tag::new(1, WireType::Fixed32), &[0x01, 0x02, 0x03]),
1482            // Fixed64 needs 8 bytes; give 7.
1483            (Tag::new(2, WireType::Fixed64), &[0; 7]),
1484            // LengthDelimited: len=10 but only 2 payload bytes.
1485            (Tag::new(3, WireType::LengthDelimited), &[0x0A, 0xAA, 0xBB]),
1486        ];
1487        for &(tag, payload) in cases {
1488            assert_eq!(
1489                decode_unknown_field(
1490                    tag,
1491                    &mut &payload[..],
1492                    crate::test_ctx(crate::RECURSION_LIMIT)
1493                ),
1494                Err(DecodeError::UnexpectedEof),
1495                "tag {tag:?}"
1496            );
1497        }
1498    }
1499
1500    #[test]
1501    fn test_decode_unknown_field_invalid_wire_type() {
1502        // EndGroup as a top-level tag is invalid (only valid inside a group).
1503        let tag = Tag::new(1, WireType::EndGroup);
1504        assert_eq!(
1505            decode_unknown_field(tag, &mut &[][..], crate::test_ctx(crate::RECURSION_LIMIT)),
1506            Err(DecodeError::InvalidWireType(4))
1507        );
1508    }
1509
1510    #[test]
1511    fn test_decode_unknown_field_round_trip_via_unknown_fields() {
1512        // Encode an UnknownFields set → decode each back → compare.
1513        // Verifies decode_unknown_field ⇔ UnknownFields::write_to parity
1514        // across all wire types.
1515        use crate::unknown_fields::{UnknownField, UnknownFieldData, UnknownFields};
1516
1517        let mut original = UnknownFields::new();
1518        original.push(UnknownField {
1519            number: 1,
1520            data: UnknownFieldData::Varint(u64::MAX),
1521        });
1522        original.push(UnknownField {
1523            number: 2,
1524            data: UnknownFieldData::Fixed32(0xFFFF_FFFF),
1525        });
1526        original.push(UnknownField {
1527            number: 3,
1528            data: UnknownFieldData::Fixed64(0),
1529        });
1530        original.push(UnknownField {
1531            number: 4,
1532            data: UnknownFieldData::LengthDelimited(vec![]),
1533        });
1534        original.push(UnknownField {
1535            number: 5,
1536            data: UnknownFieldData::LengthDelimited(vec![0xFF; 200]),
1537        });
1538
1539        let mut buf = Vec::new();
1540        original.write_to(&mut buf);
1541        assert_eq!(original.encoded_len(), buf.len());
1542
1543        // Decode all fields back.
1544        let mut decoded = UnknownFields::new();
1545        let mut cur = buf.as_slice();
1546        while !cur.is_empty() {
1547            let tag = Tag::decode(&mut cur).unwrap();
1548            decoded.push(
1549                decode_unknown_field(tag, &mut cur, crate::test_ctx(crate::RECURSION_LIMIT))
1550                    .unwrap(),
1551            );
1552        }
1553        assert_eq!(decoded, original);
1554    }
1555
1556    // ---- decode_varint_slice: direct slice decode --------------------------
1557
1558    #[test]
1559    fn test_decode_varint_slice_all_sizes() {
1560        // Exercise the unrolled slice decoder for every varint length (1–10 bytes).
1561        let test_values: &[u64] = &[
1562            0,        // 1 byte
1563            128,      // 2 bytes
1564            1 << 14,  // 3 bytes
1565            1 << 21,  // 4 bytes
1566            1 << 28,  // 5 bytes
1567            1 << 35,  // 6 bytes
1568            1 << 42,  // 7 bytes
1569            1 << 49,  // 8 bytes
1570            1 << 56,  // 9 bytes
1571            u64::MAX, // 10 bytes
1572        ];
1573        for &v in test_values {
1574            let mut buf = Vec::new();
1575            encode_varint(v, &mut buf);
1576            let (decoded, advance) = decode_varint_slice(&buf).unwrap();
1577            assert_eq!(v, decoded, "decode_varint_slice failed for {v}");
1578            assert_eq!(buf.len(), advance, "advance mismatch for {v}");
1579        }
1580    }
1581
1582    #[test]
1583    fn test_decode_varint_slice_overflow_rejected() {
1584        // 10th byte with overflow bit: 9 continuation bytes + 0x02.
1585        let mut buf: Vec<u8> = vec![0xFF; 9];
1586        buf.push(0x02);
1587        assert_eq!(decode_varint_slice(&buf), Err(DecodeError::VarintTooLong));
1588    }
1589
1590    // ---- decode_varint_slow: byte-at-a-time fallback -----------------------
1591
1592    #[test]
1593    fn test_decode_varint_slow_roundtrip() {
1594        let test_values: &[u64] = &[
1595            0,
1596            1,
1597            127,
1598            128,
1599            300,
1600            16384,
1601            // Power-of-7 transition boundaries (2^7, 2^14, 2^21, ...).
1602            1 << 7,
1603            (1 << 7) - 1,
1604            1 << 14,
1605            (1 << 14) - 1,
1606            1 << 21,
1607            1 << 28,
1608            1 << 35,
1609            1 << 42,
1610            1 << 49,
1611            1 << 56,
1612            1 << 63,
1613            u64::MAX,
1614        ];
1615        for &v in test_values {
1616            let mut buf = Vec::new();
1617            encode_varint(v, &mut buf);
1618            let decoded = decode_varint_slow(&mut buf.as_slice()).unwrap();
1619            assert_eq!(v, decoded, "slow path roundtrip failed for {v}");
1620        }
1621    }
1622
1623    #[test]
1624    fn test_decode_varint_slow_overflow_rejected() {
1625        let mut buf: Vec<u8> = vec![0xFF; 9];
1626        buf.push(0x02);
1627        assert_eq!(
1628            decode_varint_slow(&mut buf.as_slice()),
1629            Err(DecodeError::VarintTooLong)
1630        );
1631    }
1632
1633    #[test]
1634    fn test_decode_varint_empty_buffer() {
1635        let mut buf: &[u8] = &[];
1636        assert_eq!(decode_varint(&mut buf), Err(DecodeError::UnexpectedEof));
1637    }
1638
1639    #[test]
1640    fn test_decode_varint_slow_path_via_fragmented_buffer() {
1641        // Exercise the slow path through `decode_varint` by using a
1642        // `Chain` buffer where the varint straddles two chunks. The
1643        // first chunk ends with a continuation byte, so `chunk()[last]`
1644        // has its high bit set, triggering the slow-path dispatch.
1645        use bytes::Buf;
1646
1647        let test_values: &[u64] = &[128, 300, 16384, 1 << 28, u64::MAX];
1648        for &v in test_values {
1649            let mut encoded = Vec::new();
1650            encode_varint(v, &mut encoded);
1651            // Split in the middle so each chunk ends/starts on a
1652            // continuation byte.
1653            let mid = encoded.len() / 2;
1654            let first_half = bytes::Bytes::copy_from_slice(&encoded[..mid]);
1655            let second_half = bytes::Bytes::copy_from_slice(&encoded[mid..]);
1656            let mut chain = first_half.chain(second_half);
1657            let decoded = decode_varint(&mut chain).unwrap();
1658            assert_eq!(v, decoded, "fragmented buffer roundtrip failed for {v}");
1659            assert_eq!(chain.remaining(), 0);
1660        }
1661    }
1662
1663    #[test]
1664    fn test_decode_varint_single_byte_fast_path() {
1665        // Values 0–127 should hit the single-byte fast path, and leave
1666        // whatever follows for the next read.
1667        for v in 0..=127u64 {
1668            let mut buf = Vec::new();
1669            encode_varint(v, &mut buf);
1670            assert_eq!(buf.len(), 1);
1671            buf.push(0xff);
1672            let mut rest = buf.as_slice();
1673            assert_eq!(decode_varint(&mut rest), Ok(v));
1674            assert_eq!(rest, [0xff]);
1675        }
1676    }
1677
1678    // ---- decode_varint, decode_varint_multibyte, decode_varint_packed ------
1679    //
1680    // The three decoders must agree on every buffer type: a contiguous slice,
1681    // a `Bytes`, and a `Chain` cut at every offset, which puts a chunk
1682    // boundary inside every varint.
1683
1684    type Decoder<B> = fn(&mut B) -> Result<u64, DecodeError>;
1685
1686    fn decoders<B: Buf>() -> [(&'static str, Decoder<B>); 3] {
1687        [
1688            ("decode_varint", |b| decode_varint(b)),
1689            ("decode_varint_multibyte", |b| decode_varint_multibyte(b)),
1690            ("decode_varint_packed", |b| decode_varint_packed(b)),
1691        ]
1692    }
1693
1694    /// One decoder on one buffer: a label, the result, and the bytes consumed.
1695    type Outcome = (String, Result<u64, DecodeError>, usize);
1696
1697    /// Decode `bytes` with every decoder on every buffer type. The consumed
1698    /// count is only meaningful after `Ok`: the position after an error is
1699    /// unspecified.
1700    fn decode_everywhere(bytes: &[u8]) -> Vec<Outcome> {
1701        fn run<B: Buf>(out: &mut Vec<Outcome>, kind: &str, total: usize, make: impl Fn() -> B) {
1702            for (name, decode) in decoders::<B>() {
1703                let mut buf = make();
1704                let result = decode(&mut buf);
1705                out.push((format!("{name} on {kind}"), result, total - buf.remaining()));
1706            }
1707        }
1708        let total = bytes.len();
1709        let mut out = Vec::new();
1710        run(&mut out, "&[u8]", total, || bytes);
1711        run(&mut out, "Bytes", total, || {
1712            bytes::Bytes::copy_from_slice(bytes)
1713        });
1714        for split in 0..=total {
1715            let kind = format!("Chain split at {split}");
1716            run(&mut out, &kind, total, || {
1717                bytes::Bytes::copy_from_slice(&bytes[..split])
1718                    .chain(bytes::Bytes::copy_from_slice(&bytes[split..]))
1719            });
1720        }
1721        out
1722    }
1723
1724    #[test]
1725    fn test_decode_varint_boundary_values_on_every_buffer() {
1726        // The first value of each encoded length, and the last of the one
1727        // before it.
1728        let mut values = vec![0u64, u64::MAX];
1729        for bits in (7..=63).step_by(7) {
1730            values.extend([(1u64 << bits) - 1, 1 << bits, (1 << bits) + 1]);
1731        }
1732        for v in values {
1733            let mut bytes = Vec::new();
1734            encode_varint(v, &mut bytes);
1735            for (label, result, consumed) in decode_everywhere(&bytes) {
1736                assert_eq!(result, Ok(v), "{label}, value {v}");
1737                assert_eq!(consumed, bytes.len(), "{label}, value {v}");
1738            }
1739        }
1740    }
1741
1742    #[test]
1743    fn test_decode_varint_errors_on_every_buffer() {
1744        let mut max = Vec::new();
1745        encode_varint(u64::MAX, &mut max);
1746        // Every proper prefix of a ten-byte varint ends on a continuation byte.
1747        let mut cases: Vec<(Vec<u8>, DecodeError)> = (0..max.len())
1748            .map(|len| (max[..len].to_vec(), DecodeError::UnexpectedEof))
1749            .collect();
1750        // An eleventh byte, and overflow bits in the tenth.
1751        let mut eleven = vec![0x80u8; 10];
1752        eleven.push(0x01);
1753        let mut overflow = vec![0xffu8; 9];
1754        overflow.push(0x02);
1755        cases.push((eleven, DecodeError::VarintTooLong));
1756        cases.push((overflow, DecodeError::VarintTooLong));
1757        for (bytes, expected) in cases {
1758            for (label, result, _) in decode_everywhere(&bytes) {
1759                assert_eq!(result, Err(expected.clone()), "{label}, {bytes:02x?}");
1760            }
1761        }
1762    }
1763
1764    /// A byte-at-a-time decoder with no fast paths: the value and the number
1765    /// of bytes consumed, or the error.
1766    fn reference_varint(bytes: &[u8]) -> Result<(u64, usize), DecodeError> {
1767        let mut value = 0u64;
1768        for i in 0..10 {
1769            let Some(&b) = bytes.get(i) else {
1770                return Err(DecodeError::UnexpectedEof);
1771            };
1772            if i == 9 {
1773                // Only bit 0 of the tenth byte maps to bit 63.
1774                if b > 1 {
1775                    return Err(DecodeError::VarintTooLong);
1776                }
1777                return Ok((value | (u64::from(b) << 63), 10));
1778            }
1779            value |= u64::from(b & 0x7f) << (7 * i);
1780            if b < 0x80 {
1781                return Ok((value, i + 1));
1782            }
1783        }
1784        unreachable!("the tenth byte returns")
1785    }
1786
1787    #[test]
1788    fn test_decode_varint_matches_a_reference_on_random_input() {
1789        // xorshift64*: deterministic, so a failure reproduces.
1790        let mut state = 0x9e37_79b9_7f4a_7c15u64;
1791        let mut next = move || {
1792            state ^= state >> 12;
1793            state ^= state << 25;
1794            state ^= state >> 27;
1795            state.wrapping_mul(0x2545_f491_4f6c_dd1d)
1796        };
1797        for _ in 0..4000 {
1798            let len = (next() % 13) as usize;
1799            // Bias towards continuation bits so that long varints occur.
1800            let bytes: Vec<u8> = (0..len)
1801                .map(|_| {
1802                    let r = next();
1803                    if r & 3 == 0 {
1804                        (r >> 8) as u8 & 0x7f
1805                    } else {
1806                        (r >> 8) as u8 | 0x80
1807                    }
1808                })
1809                .collect();
1810            let expected = reference_varint(&bytes);
1811            for (label, result, consumed) in decode_everywhere(&bytes) {
1812                match &expected {
1813                    Ok((value, used)) => {
1814                        assert_eq!(result, Ok(*value), "{label}, {bytes:02x?}");
1815                        assert_eq!(consumed, *used, "{label}, {bytes:02x?}");
1816                    }
1817                    Err(e) => assert_eq!(result, Err(e.clone()), "{label}, {bytes:02x?}"),
1818                }
1819            }
1820        }
1821    }
1822
1823    #[test]
1824    fn test_tag_decode_consumes_exactly_the_tag() {
1825        // Field 15 is the last one-byte tag and field 16 the first that
1826        // takes two. A trailing byte shows where the tag ends, at every chunk
1827        // boundary.
1828        for (field, len) in [
1829            (1, 1),
1830            (15, 1),
1831            (16, 2),
1832            (2047, 2),
1833            (2048, 3),
1834            (MAX_FIELD_NUMBER, 5),
1835        ] {
1836            let tag = Tag::new(field, WireType::LengthDelimited);
1837            let mut bytes = Vec::new();
1838            tag.encode(&mut bytes);
1839            assert_eq!(bytes.len(), len, "field {field}");
1840            bytes.push(0xff);
1841            for split in 0..=bytes.len() {
1842                let first = bytes::Bytes::copy_from_slice(&bytes[..split]);
1843                let second = bytes::Bytes::copy_from_slice(&bytes[split..]);
1844                let mut chain = first.chain(second);
1845                assert_eq!(
1846                    Tag::decode(&mut chain),
1847                    Ok(tag),
1848                    "field {field}, split {split}"
1849                );
1850                assert_eq!(chain.remaining(), 1, "field {field}, split {split}");
1851            }
1852        }
1853        // A two-byte encoding of field number zero, and a truncated tag.
1854        assert_eq!(
1855            Tag::decode(&mut [0x80u8, 0x00].as_slice()),
1856            Err(DecodeError::InvalidFieldNumber)
1857        );
1858        assert_eq!(
1859            Tag::decode(&mut [0x80u8].as_slice()),
1860            Err(DecodeError::UnexpectedEof)
1861        );
1862    }
1863
1864    #[test]
1865    fn test_count_varints() {
1866        // Empty payload: no elements.
1867        assert_eq!(count_varints(&[]), 0);
1868        // Single-byte values: count == byte count.
1869        assert_eq!(count_varints(&[0x01, 0x02, 0x7F]), 3);
1870        // Build a packed payload of varints of mixed widths and confirm the
1871        // count matches the number encoded — never the byte length.
1872        let values: &[u64] = &[0, 1, 127, 128, 300, 16_384, u64::MAX];
1873        let mut payload = Vec::new();
1874        for &v in values {
1875            encode_varint(v, &mut payload);
1876        }
1877        assert!(payload.len() > values.len(), "payload should be multi-byte");
1878        assert_eq!(count_varints(&payload), values.len());
1879        // Never exceeds the byte-length upper bound.
1880        assert!(count_varints(&payload) <= payload.len());
1881        // A negative int32/int64 sign-extends to all-ones = a 10-byte varint,
1882        // i.e. one element in 10 bytes — the worst case the old `payload.len()`
1883        // bound over-reserved 10x.
1884        let mut neg64 = Vec::new();
1885        encode_varint(u64::MAX, &mut neg64);
1886        assert_eq!(neg64.len(), 10);
1887        assert_eq!(count_varints(&neg64), 1);
1888        // Truncated final varint (no terminator) under-counts by one, not over.
1889        assert_eq!(count_varints(&[0x80, 0x80]), 0);
1890        assert_eq!(count_varints(&[0x05, 0x80]), 1);
1891    }
1892
1893    // --- 32-bit specific tests ---
1894    // These exercise the `MessageTooLarge` error path in `skip_field` and
1895    // `decode_unknown_field` when a length-delimited field has a varint length
1896    // prefix that exceeds `usize::MAX` on 32-bit targets.
1897
1898    /// Varint encoding of 0x1_0000_0000 (u32::MAX + 1) — exceeds 32-bit usize.
1899    #[cfg(target_pointer_width = "32")]
1900    const OVERSIZED_VARINT: &[u8] = &[0x80, 0x80, 0x80, 0x80, 0x10];
1901
1902    #[test]
1903    #[cfg(target_pointer_width = "32")]
1904    fn skip_field_rejects_oversized_length_on_32bit() {
1905        let tag = Tag::new(1, WireType::LengthDelimited);
1906        let mut buf: &[u8] = OVERSIZED_VARINT;
1907        assert_eq!(skip_field(tag, &mut buf), Err(DecodeError::MessageTooLarge));
1908    }
1909
1910    #[test]
1911    #[cfg(target_pointer_width = "32")]
1912    fn decode_unknown_field_rejects_oversized_length_on_32bit() {
1913        let tag = Tag::new(1, WireType::LengthDelimited);
1914        let mut buf: &[u8] = OVERSIZED_VARINT;
1915        assert_eq!(
1916            decode_unknown_field(tag, &mut buf, crate::test_ctx(crate::RECURSION_LIMIT)),
1917            Err(DecodeError::MessageTooLarge)
1918        );
1919    }
1920}