rapidproto 0.1.0-alpha.2

Runtime for the Protobuf decoders that rapidproto-build generates.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
//! The wire-decode primitives generated decoders build on: value-threaded free functions, and
//! [`PackedVarints`] for a packed varint run. Generated code and benches call them. Users see only
//! [`WireType`], which `stream` re-exports for `UnknownField::wire_type`.
//!
//! # Value threading
//!
//! Each function takes the not-yet-consumed `&[u8]` BY VALUE and returns the slice past what it read
//! (writing any decoded value to an out-param), reporting failure as a bare [`ErrorKind`]. Threading the
//! slice keeps it in registers across the field loop, the way the C++ reader threads a bare pointer; a
//! `&mut` cursor across a non-inlined call would spill it to the stack every field.
//!
//! # Error byte offsets are relative to the decode frame's body
//!
//! A [`DecodeError`](crate::DecodeError)'s offset is relative to the message body currently being
//! decoded -- for a failure inside a nested length-delimited sub-message it is relative to that
//! sub-message, not the top-level input (matching the C++ decoder, which re-anchors the body start per
//! sub-message and per map entry). The free functions deliberately carry no offset (they return only
//! [`ErrorKind`]), leaving the caller to assign it from the frame's slice: a generated decoder working on
//! a sub-message body computes `body.len() - rest.len()`. Keeping the offset off the hot path (computed
//! only on failure) is why the readers thread just the slice.
//!
//! One deliberate divergence from the C++ reader: a failure *inside* a group -- whether being
//! [`skip`]ped (an unknown/dropped field) or decoded via [`read_group`] (a materialized group field) --
//! is reported at the group field's start, not at the deep byte where it was detected (the
//! value-threaded readers return a bare kind and the caller still holds the field-start slice). C++
//! reports the deep position within the body. The offset here is diagnostic only.
//!
//! # Safety
//!
//! Every reader returns `Result`, never panics, and never reads out of bounds on arbitrary input (the
//! decoder runs on untrusted bytes) -- entirely in safe Rust, no `unsafe`. Values are returned raw;
//! interpreting a varint as zigzag/bool, or a fixed field as a float, is the caller's step (see
//! [`zigzag32`]/[`zigzag64`]).

use crate::error::ErrorKind;

/// How a field's value is encoded on the wire.
///
/// An unknown field reports it through [`UnknownField::wire_type`](crate::stream::UnknownField::wire_type).
/// Cast it with `as u8` to get the numeric wire type, the low 3 bits of the field's tag.
// Each variant is pinned to its wire code, so generated decoders can use it as a raw tag component.
#[repr(u8)]
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum WireType {
    /// Wire type 0, a varint: `int32`, `int64`, `uint32`, `uint64`, `sint32`, `sint64`, `bool` and
    /// enums.
    Varint = 0,
    /// Wire type 1, 8 bytes: `fixed64`, `sfixed64` and `double`.
    I64 = 1,
    /// Wire type 2, length-delimited: `string`, `bytes`, messages and packed `repeated` fields.
    Len = 2,
    /// Wire type 3, the start of a group.
    SGroup = 3,
    /// Wire type 4, the end of a group.
    EGroup = 4,
    /// Wire type 5, 4 bytes: `fixed32`, `sfixed32` and `float`.
    I32 = 5,
}

impl WireType {
    /// Map the low 3 bits of a tag to a wire type, or `None` for the two unused codes (6, 7).
    #[inline]
    pub(crate) fn from_bits(bits: u32) -> Option<WireType> {
        match bits {
            0 => Some(WireType::Varint),
            1 => Some(WireType::I64),
            2 => Some(WireType::Len),
            3 => Some(WireType::SGroup),
            4 => Some(WireType::EGroup),
            5 => Some(WireType::I32),
            _ => None,
        }
    }
}

/// A decoded field tag: the 1-based field number and its wire type.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct Tag {
    /// The field number (always >= 1; a 0 field number is rejected as an invalid tag).
    pub field: u32,
    /// The field's wire type.
    pub wire: WireType,
}

/// The largest legal Protobuf field number (`2^29 - 1`); a tag above it is malformed, matching the
/// C++ reader. (The 19000..=19999 reserved range is a schema rule, not a wire-decode one.)
const MAX_FIELD_NUMBER: u32 = (1 << 29) - 1;

/// How deep [`skip`] and [`read_group`] let groups nest, counting the outermost group. Deeper
/// nesting fails with [`ErrorKind::DepthLimitExceeded`], which bounds recursion on untrusted input.
/// Matches the C++ reader's `kMaxGroupDepth`.
const MAX_GROUP_DEPTH: u32 = 100;

// ── Value-threaded wire readers ────────────────────────────────────────────────────────────────
// The hot decode primitives. Each takes the not-yet-consumed bytes BY VALUE and returns the slice past
// what it read (writing any decoded value to an out-param), or the failing `ErrorKind`. Threading the
// slice rather than a `&mut` cursor is what keeps it in registers across a field loop -- a mutable
// reference would make the cursor's address escape and force ptr + len to the stack every field (the
// C++ reader threads a bare pointer for the same reason). Generated `decode` bodies call these
// directly. `#[inline]`, so the `Result` is folded into the caller's branches rather than returned
// through memory. All safe Rust: no `unsafe`, no panic, no out-of-bounds read on arbitrary input. The
// caller derives the error's byte offset from the slice it still holds (unchanged on the error path).

/// Read a base-128 varint (up to 10 bytes). `take(10)` caps the trip count so the loop unrolls like
/// the C++ reader's fixed 10-iteration one; the over-long check sits in the terminator branch (hit
/// once for the only well-formed case). `Truncated` at end of input; `VarintOverflow` for an over-long
/// encoding (10th byte above bit 0, or ten continuation bytes) -- a context-neutral kind, since this
/// reads values and length prefixes, not only tags.
#[inline(always)]
pub fn read_varint<'a>(rest: &'a [u8], out: &mut u64) -> Result<&'a [u8], ErrorKind> {
    // Single-byte fast path, kept tiny and `#[inline(always)]` so it folds into the caller's decode
    // loop and keeps the value-threaded slice in registers (ptr+len), with no spill. This is the
    // overwhelmingly common case (small scalar values and 1-byte length prefixes). It MUST stay small:
    // a plain `#[inline]` on the full loop below does NOT inline at a message decoder's many call sites
    // (LLVM's cost model declines the 10-iteration body in a large `rp_decode_into`), so every field would
    // otherwise pay an out-of-line call + a stack round-trip of ptr/len/value -- defeating the
    // value-threaded design. Multibyte and all error cases go out-of-line to `read_varint_cold`, which
    // the `#[cold]` keeps off this hot path, so the fast path remains inline-sized. Like the C++
    // reader's inline 1-byte fast path; C++ keeps its multibyte loop in the same body, whereas here it
    // is outlined so the Rust fast path stays small enough for LLVM to inline it at every call site
    // (`read_varint_inline` keeps it in the body, for decoders with few call sites).
    if let Some((&b0, tail)) = rest.split_first() {
        if b0 & 0x80 == 0 {
            *out = u64::from(b0);
            return Ok(tail);
        }
    }
    read_varint_cold(rest, out)
}

// The multibyte / empty / malformed continuation of `read_varint`: everything the 1-byte fast path did
// not handle. `#[cold]` + `#[inline(never)]` so it stays out-of-line and the MAIN per-field decode loop
// (`read_varint`'s many call sites) keeps only the tiny fast path inline. A thin wrapper over the fully
// inlined [`read_varint_full`].
#[cold]
#[inline(never)]
fn read_varint_cold<'a>(rest: &'a [u8], out: &mut u64) -> Result<&'a [u8], ErrorKind> {
    read_varint_full(rest, out)
}

/// [`read_varint`] with the multibyte decode inline too, so a multibyte value costs no call. It makes
/// every call site larger, which pays off in a decode loop with few of them: the generated stream
/// decoders read values with it, since only the fields a visitor selects keep their reads, and
/// [`skip_field`] skips varints with it. The arena decoders read every field and use [`read_varint`].
#[inline(always)]
pub fn read_varint_inline<'a>(rest: &'a [u8], out: &mut u64) -> Result<&'a [u8], ErrorKind> {
    if let Some((&b0, tail)) = rest.split_first() {
        if b0 & 0x80 == 0 {
            *out = u64::from(b0);
            return Ok(tail);
        }
    }
    read_varint_full(rest, out)
}

/// The complete varint decode, fully inlined: one `#[inline(always)]` loop with no out-of-line
/// `#[cold]` tail. The arena's per-element read over a packed span (`packed_varint`), where inlining
/// the whole decode avoids the out-of-line call [`read_varint`] makes per multibyte value -- matching
/// the C++ `RP_FLATTEN`ed small packed kernel -- and the multibyte half of [`read_varint_inline`].
/// (The stream decoders' packed loops use [`PackedVarints`].) NOT for the arena's typed per-field
/// reads: inlining the full loop at their many call sites spills the value-threaded slice (see
/// `read_varint`). Re-reads from `rest` (including byte 0) so it is a correct standalone decode.
/// `VarintOverflow` on an over-long encoding (10th byte above bit 0, or ten continuation bytes),
/// `Truncated` if the input runs out mid-varint.
#[inline(always)]
pub(crate) fn read_varint_full<'a>(rest: &'a [u8], out: &mut u64) -> Result<&'a [u8], ErrorKind> {
    let mut result: u64 = 0;
    let mut shift: u32 = 0;
    for (i, &byte) in rest.iter().take(10).enumerate() {
        result |= u64::from(byte & 0x7f) << shift;
        if byte & 0x80 == 0 {
            if i == 9 && byte > 0x01 {
                return Err(ErrorKind::VarintOverflow);
            }
            *out = result;
            return Ok(&rest[i + 1..]);
        }
        shift += 7;
    }
    // Fell through without a terminator: ten continuation bytes (an over-long encoding that cannot fit
    // 64 bits) vs fewer bytes than the varint needs (the input ran out mid-varint).
    if rest.len() >= 10 {
        Err(ErrorKind::VarintOverflow)
    } else {
        Err(ErrorKind::Truncated)
    }
}

/// The varints of a packed run (a packed repeated varint field's payload), read front to back; the
/// generated stream decoders read packed varint fields with it. Use it rather than [`read_varint`] in a
/// loop: it decodes multibyte varints inline, where `read_varint` calls out of line, and it walks the
/// run with one pointer against an end pointer, where a `&[u8]` advances a pointer and a length.
pub struct PackedVarints<'a> {
    run: &'a [u8],
    rest: core::slice::Iter<'a, u8>,
}

impl<'a> PackedVarints<'a> {
    /// The varints of `run`, a packed field's payload.
    #[inline(always)]
    #[must_use]
    pub fn new(run: &'a [u8]) -> Self {
        Self {
            run,
            rest: run.iter(),
        }
    }

    /// The next varint, `Ok(None)` at the end of the run, or the error for a malformed one (as
    /// [`read_varint`] reports it), after which [`remaining`](Self::remaining) starts at that varint.
    #[inline(always)]
    pub fn read(&mut self) -> Result<Option<u64>, ErrorKind> {
        let Some(&b0) = self.rest.next() else {
            return Ok(None);
        };
        if b0 & 0x80 == 0 {
            return Ok(Some(u64::from(b0)));
        }
        // Byte `i` of a varint of up to 10; `i` bytes are consumed when byte `i` is missing.
        let mut value = u64::from(b0 & 0x7f);
        for i in 1..10 {
            let Some(&byte) = self.rest.next() else {
                return Err(self.rewind_by(i, ErrorKind::Truncated));
            };
            value |= u64::from(byte & 0x7f) << (7 * i);
            if byte & 0x80 == 0 {
                if i == 9 && byte > 0x01 {
                    return Err(self.rewind_by(10, ErrorKind::VarintOverflow));
                }
                return Ok(Some(value));
            }
        }
        Err(self.rewind_by(10, ErrorKind::VarintOverflow))
    }

    /// The rest of the run: from the next varint, or after an error from the malformed one.
    #[inline(always)]
    #[must_use]
    pub fn remaining(&self) -> &'a [u8] {
        self.rest.as_slice()
    }

    // Point `rest` back at the malformed varint, of which `consumed` bytes were read, for its error.
    #[inline(always)]
    fn rewind_by(&mut self, consumed: usize, kind: ErrorKind) -> ErrorKind {
        self.rest = rewind(self.run, self.rest.len(), consumed);
        kind
    }
}

// `run` from the malformed varint on, given the `left` bytes after its `consumed` ones. Out of line and
// by value, so the reader itself never has its address taken and stays in registers.
#[cold]
fn rewind(run: &[u8], left: usize, consumed: usize) -> core::slice::Iter<'_, u8> {
    run[run.len() - left - consumed..].iter()
}

/// Read the next field tag, or report clean end of input as `Ok(None)`. A single `split_first`
/// distinguishes end from a tag (no separate `is_empty` the loop condition would duplicate), then the
/// fused 1-byte / 2-byte decode runs inline. The hand-written bench decoders loop on this; generated
/// decoders peek the tag byte and call [`read_tag`] for a longer tag.
#[inline]
pub fn read_tag_or_end<'a>(rest: &'a [u8], out: &mut Tag) -> Result<Option<&'a [u8]>, ErrorKind> {
    match rest.split_first() {
        None => Ok(None),
        Some((&first, tail)) => read_tag_from(first, tail, rest, out).map(Some),
    }
}

/// Read a field tag, erroring (`Truncated`) at end of input. Same fused decode as
/// [`read_tag_or_end`], for callers that require a tag.
/// `InvalidTag` for field 0, a field above `2^29 - 1`, or a wire type of 6/7.
#[inline]
pub fn read_tag<'a>(rest: &'a [u8], out: &mut Tag) -> Result<&'a [u8], ErrorKind> {
    match rest.split_first() {
        None => Err(ErrorKind::Truncated),
        Some((&first, tail)) => read_tag_from(first, tail, rest, out),
    }
}

/// The shared fused tag decode: `first`/`tail` are `rest.split_first()` (so `rest` is non-empty).
/// Decodes a 1-byte tag (fields 1..=15) or a 2-byte tag (fields 16..=2047) inline -- the common cases
/// -- and falls through to the general multibyte varint otherwise. Mirrors the C++ fused paths; the
/// 2-byte fusion is measured -31% on a >15-field decode without it.
#[inline]
fn read_tag_from<'a>(
    first: u8,
    tail: &'a [u8],
    rest: &'a [u8],
    out: &mut Tag,
) -> Result<&'a [u8], ErrorKind> {
    if first & 0x80 == 0 {
        // Fused 1-byte tag: field 1..=15, wire in the low 3 bits.
        let field = u32::from(first >> 3);
        if field != 0 {
            if let Some(wire) = WireType::from_bits(u32::from(first & 0x07)) {
                *out = Tag { field, wire };
                return Ok(tail);
            }
        }
        // field 0 or a reserved wire type (6/7): fall through for a uniform error.
    } else if let Some((&second, rest2)) = tail.split_first() {
        // Fused 2-byte tag: `first` has the continuation bit; `second - 1 < 0x7f` means the second
        // byte terminates (no continuation) and is nonzero, so the value is 128..=16383 -> field
        // 16..=2047, never 0 and within range. A reserved wire type (6/7) still falls through. Matches
        // the C++ fused 2-byte path's `(u8)(p[1]-1) < 0x7F` guard.
        if second.wrapping_sub(1) < 0x7f {
            let value = (u32::from(first) & 0x7f) | (u32::from(second) << 7);
            if let Some(wire) = WireType::from_bits(value & 0x07) {
                *out = Tag {
                    field: value >> 3,
                    wire,
                };
                return Ok(rest2);
            }
        }
        // non-canonical 2-byte, 3+ byte, or reserved wire type: fall through.
    }
    read_tag_general(rest, out)
}

/// The tag general case: a 3+ byte tag, or a 1-/2-byte tag the fast paths rejected. Reads the full
/// varint and range-checks it. `#[inline]` so the whole reader (incl. this cold path) folds into the
/// caller -- that lets the `Tag` out-param scalarize to registers instead of escaping to the stack
/// (the C++ reader gets the same via `flatten`); the cold multibyte code just sits after the return.
#[inline]
fn read_tag_general<'a>(rest: &'a [u8], out: &mut Tag) -> Result<&'a [u8], ErrorKind> {
    let mut raw = 0u64;
    let rest = read_varint(rest, &mut raw)?;
    let field = raw >> 3;
    if field == 0 || field > u64::from(MAX_FIELD_NUMBER) {
        return Err(ErrorKind::InvalidTag);
    }
    let wire = WireType::from_bits((raw & 0x07) as u32).ok_or(ErrorKind::InvalidTag)?;
    *out = Tag {
        field: field as u32,
        wire,
    };
    Ok(rest)
}

/// Read a fixed 32-bit little-endian value (fixed32/sfixed32/float bits). `Truncated` if fewer than 4
/// bytes remain.
#[inline]
pub fn read_fixed32<'a>(rest: &'a [u8], out: &mut u32) -> Result<&'a [u8], ErrorKind> {
    match rest.first_chunk::<4>() {
        Some(bytes) => {
            *out = u32::from_le_bytes(*bytes);
            Ok(&rest[4..])
        }
        None => Err(ErrorKind::Truncated),
    }
}

/// Read a fixed 64-bit little-endian value (fixed64/sfixed64/double bits). `Truncated` if fewer than 8
/// bytes remain.
#[inline]
pub fn read_fixed64<'a>(rest: &'a [u8], out: &mut u64) -> Result<&'a [u8], ErrorKind> {
    match rest.first_chunk::<8>() {
        Some(bytes) => {
            *out = u64::from_le_bytes(*bytes);
            Ok(&rest[8..])
        }
        None => Err(ErrorKind::Truncated),
    }
}

/// Read a length-delimited payload (a varint length then that many bytes), writing the borrowed
/// payload to `out`. `Truncated` if the declared length does not fit the remaining input.
#[inline]
pub fn read_length_delimited<'a>(
    rest: &'a [u8],
    out: &mut &'a [u8],
) -> Result<&'a [u8], ErrorKind> {
    let mut len = 0u64;
    let rest = read_varint(rest, &mut len)?;
    // A length that does not fit a usize cannot fit the remaining input either.
    let len = usize::try_from(len).map_err(|_| ErrorKind::Truncated)?;
    if len > rest.len() {
        return Err(ErrorKind::Truncated);
    }
    let (payload, tail) = rest.split_at(len);
    *out = payload;
    Ok(tail)
}

/// Skip the value of the field whose `tag` was just read, such as an unknown or dropped field, and
/// return the slice past it. A group ([`WireType::SGroup`]) is skipped through its matching end tag,
/// the one with the same field number, as in the C++ reader. Groups nest at most
/// `MAX_GROUP_DEPTH` deep. `tag.field` matters only for groups.
pub fn skip(rest: &[u8], tag: Tag) -> Result<&[u8], ErrorKind> {
    skip_depth(rest, tag, 0)
}

fn skip_depth(rest: &[u8], tag: Tag, depth: u32) -> Result<&[u8], ErrorKind> {
    match tag.wire {
        WireType::Varint => {
            let mut v = 0;
            read_varint(rest, &mut v)
        }
        WireType::I64 => {
            let mut v = 0;
            read_fixed64(rest, &mut v)
        }
        WireType::I32 => {
            let mut v = 0;
            read_fixed32(rest, &mut v)
        }
        WireType::Len => {
            let mut p: &[u8] = &[];
            read_length_delimited(rest, &mut p)
        }
        // A group-end with no matching start: malformed.
        WireType::EGroup => Err(ErrorKind::InvalidWireType),
        WireType::SGroup => {
            if depth >= MAX_GROUP_DEPTH {
                return Err(ErrorKind::DepthLimitExceeded);
            }
            let mut rest = rest;
            loop {
                let mut inner = Tag {
                    field: 0,
                    wire: WireType::Varint,
                };
                rest = read_tag(rest, &mut inner)?;
                if inner.wire == WireType::EGroup {
                    // The end tag must close THIS group: its field number must match. A mismatched end
                    // group is a malformed nesting (the C++ reader rejects it too).
                    if inner.field != tag.field {
                        return Err(ErrorKind::InvalidWireType);
                    }
                    break;
                }
                rest = skip_depth(rest, inner, depth + 1)?;
            }
            Ok(rest)
        }
    }
}

/// Read a proto2 group. `rest` starts at the group body, just past the start tag, and `field` is the
/// group's field number. Scans to the matching end tag, the one with field number `field`; groups
/// nest at most `MAX_GROUP_DEPTH` deep. Writes the group body, the bytes between the start tag and
/// that end tag, to `out` and returns the slice past the end tag. The generated decoder then decodes
/// `out` as the group message, as it decodes a length-delimited payload. Mirrors C++
/// `wire::read_group`.
#[inline]
pub fn read_group<'a>(
    rest: &'a [u8],
    field: u32,
    out: &mut &'a [u8],
) -> Result<&'a [u8], ErrorKind> {
    let body_start = rest;
    let mut rest = rest;
    loop {
        // The slice at the next tag: the body ends here when that tag is the matching end-group.
        let at_tag = rest;
        let mut inner = Tag {
            field: 0,
            wire: WireType::Varint,
        };
        rest = read_tag(rest, &mut inner)?;
        if inner.wire == WireType::EGroup {
            // The end tag must close THIS group (field number matches), like `skip` and the C++ reader.
            if inner.field != field {
                return Err(ErrorKind::InvalidWireType);
            }
            // Body = [body_start, the matching end-group tag): the content to decode as the message.
            let body_len = body_start.len() - at_tag.len();
            *out = &body_start[..body_len];
            break;
        }
        // Advance past this inner field's value (nested groups skipped to their own end via `skip_depth`,
        // capped by `MAX_GROUP_DEPTH`), so the scan stops only at THIS group's matching end and the nested
        // content stays inside the returned body span. The cap bounds a group body's nesting; the
        // generated decoder's own `rp_depth`/`MAX_DECODE_DEPTH` cap independently bounds decode recursion.
        rest = skip_depth(rest, inner, 1)?;
    }
    Ok(rest)
}

/// Skip a field the generated decoder does not read, given its raw tag key (`field << 3 | wire_code`
/// -- the value the decode loop's one-byte peek hub dispatches on, or the constant key of a stream
/// decoder's unselected field or an arena decoder's dropped field). Reconstructs the wire type and
/// skips the field's value, returning the slice past it.
///
/// `rest` is positioned at the field's VALUE (the tag already consumed), like [`skip`]. The key may
/// be unvalidated: the hot loop's one-byte fast path builds it straight from the tag byte without the
/// field/wire checks [`read_tag`] makes, so a malformed one-byte tag (field number 0, or a reserved
/// wire code 6/7) reaches here and is rejected as `InvalidTag` -- the same kind [`read_tag`] would
/// have raised, only detected after the tag byte rather than before it. (Multi-byte tags still go
/// through [`read_tag`] in the hot loop, so a malformed one never reaches this function.)
///
/// The scalar wire types skip inline, failing as [`skip`] does; a group, a stray end-group and a
/// malformed key go out of line.
#[inline(always)]
pub fn skip_field(rest: &[u8], key: u32) -> Result<&[u8], ErrorKind> {
    let wire = key & 0x07;
    if key >> 3 != 0 {
        if wire == 0 {
            // Inlined, the value is dead, so this is a scan for the varint's last byte.
            let mut v = 0;
            return read_varint_inline(rest, &mut v);
        }
        if wire == 2 {
            let mut p: &[u8] = &[];
            return read_length_delimited(rest, &mut p);
        }
        if wire == 1 {
            return rest.get(8..).ok_or(ErrorKind::Truncated);
        }
        if wire == 5 {
            return rest.get(4..).ok_or(ErrorKind::Truncated);
        }
    }
    skip_field_cold(rest, key)
}

// `skip_field` for a group, an end-group or a malformed key.
#[cold]
#[inline(never)]
fn skip_field_cold(rest: &[u8], key: u32) -> Result<&[u8], ErrorKind> {
    let field = key >> 3;
    if field == 0 {
        return Err(ErrorKind::InvalidTag);
    }
    let wire = WireType::from_bits(key & 0x07).ok_or(ErrorKind::InvalidTag)?;
    skip(rest, Tag { field, wire })
}

/// Decode a zigzag-encoded 32-bit signed integer (sint32) from its varint value.
#[inline]
#[must_use]
pub fn zigzag32(value: u32) -> i32 {
    ((value >> 1) as i32) ^ -((value & 1) as i32)
}

/// Decode a zigzag-encoded 64-bit signed integer (sint64) from its varint value.
#[inline]
#[must_use]
pub fn zigzag64(value: u64) -> i64 {
    ((value >> 1) as i64) ^ -((value & 1) as i64)
}

#[cfg(test)]
mod tests {
    use super::*;

    fn kind(input: &[u8]) -> ErrorKind {
        let mut v = 0;
        read_varint(input, &mut v).unwrap_err()
    }

    // A tag for `skip`; the field number matters only for matching a group's end tag.
    fn tag(field: u32, wire: WireType) -> Tag {
        Tag { field, wire }
    }

    #[test]
    fn varint_values_and_advance() {
        let mut v = 0u64;
        assert_eq!(read_varint(&[0x00], &mut v).unwrap(), &[] as &[u8]);
        assert_eq!(v, 0);

        // 300 = 0xAC 0x02; a trailing byte stays unconsumed.
        assert_eq!(read_varint(&[0xac, 0x02, 0x7f], &mut v).unwrap(), &[0x7f]);
        assert_eq!(v, 300);

        // u64::MAX is ten bytes, last byte 0x01.
        let max = [0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x01];
        assert_eq!(read_varint(&max, &mut v).unwrap(), &[] as &[u8]);
        assert_eq!(v, u64::MAX);

        // The exact fast/cold split: 0x7f is the max single-byte value (inline fast path, 1 byte
        // consumed); 0x80 0x01 == 128 is the smallest value that falls to the multibyte cold path
        // (2 bytes). Pins the boundary the inline fast path introduces.
        assert_eq!(read_varint(&[0x7f], &mut v).unwrap(), &[] as &[u8]);
        assert_eq!(v, 127);
        assert_eq!(read_varint(&[0x80, 0x01], &mut v).unwrap(), &[] as &[u8]);
        assert_eq!(v, 128);
        // A trailing byte after a single-byte value stays unconsumed (fast path advances exactly 1).
        assert_eq!(read_varint(&[0x7f, 0xaa], &mut v).unwrap(), &[0xaa]);
        assert_eq!(v, 127);
    }

    #[test]
    fn varint_rejects_truncated_and_overlong() {
        assert_eq!(kind(&[]), ErrorKind::Truncated);
        assert_eq!(kind(&[0x80]), ErrorKind::Truncated); // continuation bit, no more bytes
        assert_eq!(kind(&[0x80; 5]), ErrorKind::Truncated);
        // Ten continuation bytes: an over-long encoding that cannot fit 64 bits -> VarintOverflow,
        // a context-neutral kind (not InvalidTag -- this reader also decodes values and lengths).
        assert_eq!(kind(&[0x80; 10]), ErrorKind::VarintOverflow);
        // Tenth byte sets bits above bit 0 -> over-long.
        assert_eq!(
            kind(&[0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x02]),
            ErrorKind::VarintOverflow
        );
    }

    #[test]
    fn read_varint_inline_agrees_with_read_varint() {
        let mut max = vec![0xff; 9];
        max.extend([0x01, 0xaa]);
        let overlong_tenth = [0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x02];
        for input in [
            &[][..],
            &[0x7f, 0xaa],
            &[0x80, 0x01],
            &[0xac, 0x02, 0x7f],
            &max,
            &[0x80],
            &[0x80; 10],
            &overlong_tenth,
        ] {
            let (mut inline, mut split) = (0u64, 0u64);
            assert_eq!(
                read_varint_inline(input, &mut inline),
                read_varint(input, &mut split),
                "{input:02x?}"
            );
            assert_eq!(inline, split, "{input:02x?}");
        }
    }

    // Every varint of `run` through `PackedVarints`, then the error and its offset in `run`, if any.
    fn packed_varints(run: &[u8]) -> (Vec<u64>, Option<(ErrorKind, usize)>) {
        let mut varints = PackedVarints::new(run);
        let mut values = Vec::new();
        loop {
            match varints.read() {
                Ok(Some(v)) => values.push(v),
                Ok(None) => return (values, None),
                Err(k) => return (values, Some((k, run.len() - varints.remaining().len()))),
            }
        }
    }

    #[test]
    fn packed_varints_values() {
        assert_eq!(packed_varints(&[]), (vec![], None));
        // 1 byte, the 1/2-byte boundary, 2 bytes, the 10-byte maximum, 0.
        let mut run = vec![0x7f, 0x80, 0x01, 0xac, 0x02];
        run.extend([0xff; 9]);
        run.extend([0x01, 0x00]);
        assert_eq!(
            packed_varints(&run),
            (vec![127, 128, 300, u64::MAX, 0], None)
        );
    }

    #[test]
    fn packed_varints_reject_as_read_varint_does() {
        let overlong_tenth = [0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x02];
        for bad in [
            &[0x80][..],
            &[0x80; 5],
            &[0x80; 9],
            &[0x80; 10],
            &[0x80; 11],
            &overlong_tenth,
        ] {
            // After one good varint, so the error must point back at the malformed one, offset 1.
            let mut run = vec![0x05];
            run.extend_from_slice(bad);
            assert_eq!(
                packed_varints(&run),
                (vec![5], Some((kind(bad), 1))),
                "{bad:02x?}"
            );
        }
    }

    #[test]
    fn tag_decode_and_rejections() {
        let read = |input: &[u8]| {
            let mut t = tag(0, WireType::Varint);
            read_tag(input, &mut t).map(|_| t)
        };
        // field 1, wire Len: (1 << 3) | 2 = 0x0a.
        assert_eq!(read(&[0x0a]), Ok(tag(1, WireType::Len)));
        // At end of input there is no tag to read.
        assert_eq!(read(&[]), Err(ErrorKind::Truncated));

        // field 0 is invalid.
        assert_eq!(read(&[0x00]), Err(ErrorKind::InvalidTag));
        // wire type 7 (the high 3 bits set) is invalid: (1 << 3) | 7 = 0x0f.
        assert_eq!(read(&[0x0f]), Err(ErrorKind::InvalidTag));

        // The max field number (2^29 - 1) with wire Len is accepted; one past it is rejected.
        let encode = |value: u64| {
            let mut buf = Vec::new();
            let mut v = value;
            loop {
                let byte = (v & 0x7f) as u8;
                v >>= 7;
                if v == 0 {
                    buf.push(byte);
                    break;
                }
                buf.push(byte | 0x80);
            }
            buf
        };
        let max_tag = (u64::from(MAX_FIELD_NUMBER) << 3) | 2;
        let over_tag = ((u64::from(MAX_FIELD_NUMBER) + 1) << 3) | 2;
        assert_eq!(read(&encode(max_tag)).unwrap().field, MAX_FIELD_NUMBER);
        assert_eq!(read(&encode(over_tag)), Err(ErrorKind::InvalidTag));

        // The slice past the tag comes back: the trailing byte stays unconsumed.
        let mut t = tag(0, WireType::Varint);
        assert_eq!(read_tag(&[0x0a, 0xff], &mut t).unwrap(), &[0xff]);
        assert_eq!(t, tag(1, WireType::Len));

        // Fused 2-byte tag path: field 18 varint = (18 << 3) | 0 = 144 -> varint 0x90 0x01. The fused
        // path and the general path must agree, and the trailing byte stays unconsumed.
        assert_eq!(read_tag(&[0x90, 0x01, 0x7f], &mut t).unwrap(), &[0x7f]);
        assert_eq!(t, tag(18, WireType::Varint));
        // A 2-byte tag with a reserved wire type (6) falls through and is rejected: field 18 wire 6 =
        // 150 -> 0x96 0x01.
        assert_eq!(read(&[0x96, 0x01]), Err(ErrorKind::InvalidTag));
        // A tag truncated mid-varint (continuation bit set, no next byte) is Truncated, not a panic.
        assert_eq!(read(&[0x88]), Err(ErrorKind::Truncated));
    }

    #[test]
    fn fixed_and_length_delimited() {
        let mut x = 0u32;
        assert_eq!(
            read_fixed32(&[0x78, 0x56, 0x34, 0x12, 0xff], &mut x).unwrap(),
            &[0xff]
        );
        assert_eq!(x, 0x1234_5678);
        assert_eq!(read_fixed32(&[0, 0, 0], &mut x), Err(ErrorKind::Truncated));

        let mut y = 0u64;
        assert_eq!(
            read_fixed64(&[1, 2, 3, 4, 5, 6, 7, 8], &mut y).unwrap(),
            &[] as &[u8]
        );
        assert_eq!(y, 0x0807_0605_0403_0201);
        assert_eq!(read_fixed64(&[0; 7], &mut y), Err(ErrorKind::Truncated));

        // length 3 then "abc", with a trailing byte.
        let mut payload: &[u8] = &[];
        assert_eq!(
            read_length_delimited(&[0x03, b'a', b'b', b'c', b'z'], &mut payload).unwrap(),
            b"z"
        );
        assert_eq!(payload, b"abc");
        // A length past the end is truncated.
        assert_eq!(
            read_length_delimited(&[0x05, b'a'], &mut payload),
            Err(ErrorKind::Truncated)
        );
    }

    #[test]
    fn skip_every_wire_type_including_nested_groups() {
        // varint, i64, i32, len, each leaving a trailing byte unconsumed.
        assert_eq!(
            skip(&[0xac, 0x02, 0x7f], tag(1, WireType::Varint)),
            Ok(&[0x7f][..])
        );
        assert_eq!(skip(&[0; 9], tag(1, WireType::I64)), Ok(&[0][..]));
        assert_eq!(skip(&[0; 5], tag(1, WireType::I32)), Ok(&[0][..]));
        assert_eq!(
            skip(&[0x02, b'h', b'i', 0x7f], tag(1, WireType::Len)),
            Ok(&[0x7f][..])
        );

        // A group: start-tag already consumed by the caller, so skip() is given the SGroup tag and
        // consumes through the matching end. Body: field 1 varint (0x08 0x01), inner group (0x0b ...
        // 0x0c), then this group's end (0x0c). Tags: SGroup=(f<<3)|3, EGroup=(f<<3)|4 -- all field 1.
        let group = [
            0x08, 0x01, /*inner start f1*/ 0x0b, /*inner end f1*/ 0x0c,
            /*end f1*/ 0x0c,
        ];
        assert_eq!(skip(&group, tag(1, WireType::SGroup)), Ok(&[][..]));

        // A stray group-end is malformed.
        assert_eq!(
            skip(&[], tag(1, WireType::EGroup)),
            Err(ErrorKind::InvalidWireType)
        );

        // A group closed by an end tag with a DIFFERENT field number is malformed (matches the C++
        // reader, which pairs end groups by field number). Start field 1 (skip arg), end field 2
        // (0x14 = (2<<3)|4) -> rejected.
        assert_eq!(
            skip(&[0x14], tag(1, WireType::SGroup)),
            Err(ErrorKind::InvalidWireType)
        );
        // The same body closed by the matching field-1 end (0x0c) is accepted.
        assert_eq!(skip(&[0x0c], tag(1, WireType::SGroup)), Ok(&[][..]));
    }

    #[test]
    fn skip_group_depth_is_capped() {
        // A run of group-start tags with no ends must hit the depth cap, not recurse unboundedly.
        let starts = vec![0x0b_u8; (MAX_GROUP_DEPTH as usize) + 5];
        assert_eq!(
            skip(&starts, tag(1, WireType::SGroup)),
            Err(ErrorKind::DepthLimitExceeded)
        );
    }

    #[test]
    fn groups_nest_up_to_max_group_depth() {
        // `levels` nested field-1 groups, the outer start tag already read: the inner start tags
        // (0x0b), then every end tag (0x0c).
        let nested = |levels: usize| {
            let mut buf = vec![0x0b_u8; levels - 1];
            buf.resize(2 * levels - 1, 0x0c);
            buf
        };
        let (at_cap, over_cap) = (
            nested(MAX_GROUP_DEPTH as usize),
            nested(MAX_GROUP_DEPTH as usize + 1),
        );
        let mut body: &[u8] = &[];
        assert_eq!(skip(&at_cap, tag(1, WireType::SGroup)), Ok(&[][..]));
        assert_eq!(read_group(&at_cap, 1, &mut body), Ok(&[][..]));
        assert_eq!(
            skip(&over_cap, tag(1, WireType::SGroup)),
            Err(ErrorKind::DepthLimitExceeded)
        );
        assert_eq!(
            read_group(&over_cap, 1, &mut body),
            Err(ErrorKind::DepthLimitExceeded)
        );
    }

    #[test]
    fn read_group_returns_the_body_span_and_the_tail() {
        // Start tag already consumed by the caller. Body: field-1 varint (0x08 0x01), a nested group
        // field 2 (start 0x13, end 0x14), then THIS group's end (field 1 -> 0x0c); 0xde 0xad trail.
        let buf = [0x08, 0x01, 0x13, 0x14, 0x0c, 0xde, 0xad];
        let mut body: &[u8] = &[];
        let tail = read_group(&buf, 1, &mut body).unwrap();
        // Body is everything up to (not including) the matching end tag -- the nested group included.
        assert_eq!(body, &[0x08, 0x01, 0x13, 0x14]);
        assert_eq!(tail, &[0xde, 0xad]);
    }

    #[test]
    fn read_group_rejects_mismatched_end_and_caps_depth() {
        let mut body: &[u8] = &[];
        // An end tag for a different field number does not close this group.
        assert_eq!(
            read_group(&[0x14], 1, &mut body).unwrap_err(),
            ErrorKind::InvalidWireType
        );
        // A run of start tags with no ends hits the depth cap, never recursing unboundedly.
        let starts = vec![0x0b_u8; (MAX_GROUP_DEPTH as usize) + 5];
        assert_eq!(
            read_group(&starts, 1, &mut body).unwrap_err(),
            ErrorKind::DepthLimitExceeded
        );
    }

    #[test]
    fn skip_field_dispatches_on_the_raw_key() {
        // A raw key is `field << 3 | wire_code`; skip_field reconstructs the wire type and skips the
        // value at `rest` (the tag already consumed), agreeing with `skip` given the same tag.
        let key = |field: u32, wire: WireType| (field << 3) | u32::from(wire as u8);
        // Varint value 300 (0xac 0x02) for field 1.
        assert_eq!(
            skip_field(&[0xac, 0x02, 0x7f], key(1, WireType::Varint)).unwrap(),
            &[0x7f]
        );
        // Len payload "hi" for field 2.
        assert_eq!(
            skip_field(&[0x02, b'h', b'i', 0xff], key(2, WireType::Len)).unwrap(),
            &[0xff]
        );
        // I32 / I64 consume exactly 4 / 8 bytes.
        assert_eq!(
            skip_field(&[0; 4], key(3, WireType::I32)).unwrap(),
            &[] as &[u8]
        );
        assert_eq!(
            skip_field(&[0; 8], key(4, WireType::I64)).unwrap(),
            &[] as &[u8]
        );

        // A field number of 0 (a malformed one-byte tag like 0x04 = field 0, wire 4) is InvalidTag --
        // the kind read_tag raises for the same tag, just detected one byte later.
        assert_eq!(skip_field(&[], 0x04).unwrap_err(), ErrorKind::InvalidTag);
        // A reserved wire code (7) is InvalidTag: field 1, wire 7 -> key 0x0f.
        assert_eq!(skip_field(&[], 0x0f).unwrap_err(), ErrorKind::InvalidTag);
        // Field 0 with a scalar wire type is InvalidTag too, though its value would skip.
        for key in [0x00, 0x01, 0x02, 0x05] {
            assert_eq!(
                skip_field(&[0; 16], key),
                Err(ErrorKind::InvalidTag),
                "{key:#x}"
            );
        }
        // A large (multi-byte) field number round-trips through the key losslessly: field 2^29 - 1,
        // wire Len, skipping an empty payload.
        let big = key(MAX_FIELD_NUMBER, WireType::Len);
        assert_eq!(skip_field(&[0x00], big).unwrap(), &[] as &[u8]);
    }

    #[test]
    fn skip_field_agrees_with_skip() {
        // The inline scalar skips and the out-of-line group path, success and error alike.
        let mut max = vec![0xff; 9];
        max.extend([0x01, 0xaa]);
        let overlong_tenth = [0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x02];
        let inputs: &[&[u8]] = &[
            &[],
            &[0x7f, 0xaa],
            &[0xac, 0x02, 0x7f],
            &max,
            &[0x80],
            &[0x80; 10],
            &overlong_tenth,
            &[0x02, 1, 2, 3],
            &[0x03, 1, 2],
            &[0; 7],
            &[0x0c, 0xaa],
        ];
        for wire in [
            WireType::Varint,
            WireType::I64,
            WireType::Len,
            WireType::SGroup,
            WireType::EGroup,
            WireType::I32,
        ] {
            for &input in inputs {
                let key = (1 << 3) | u32::from(wire as u8);
                assert_eq!(
                    skip_field(input, key),
                    skip(input, tag(1, wire)),
                    "{wire:?} {input:02x?}"
                );
            }
        }
    }

    #[test]
    fn zigzag_round_trips_known_values() {
        assert_eq!(zigzag32(0), 0);
        assert_eq!(zigzag32(1), -1);
        assert_eq!(zigzag32(2), 1);
        assert_eq!(zigzag32(4_294_967_294), i32::MAX);
        assert_eq!(zigzag32(4_294_967_295), i32::MIN);
        assert_eq!(zigzag64(0), 0);
        assert_eq!(zigzag64(1), -1);
        assert_eq!(zigzag64(u64::MAX), i64::MIN);
    }

    #[test]
    fn never_panics_on_arbitrary_or_truncated_input() {
        // Every prefix of a plausible message, and some adversarial byte runs, must yield Ok or Err
        // -- never a panic (the decoder runs on untrusted bytes).
        let samples: &[&[u8]] = &[
            &[
                0x08, 0xac, 0x02, 0x12, 0x03, b'a', b'b', b'c', 0x1d, 1, 2, 3, 4,
            ],
            &[0xff; 32],
            &[0x80; 32],
            &[0x0b, 0x0b, 0x0b, 0x12, 0xff],
        ];
        for sample in samples {
            for end in 0..=sample.len() {
                let mut rest = &sample[..end];
                let mut field_tag = tag(0, WireType::Varint);
                // Drive a field loop to exhaustion or first error; just must not panic.
                while let Ok(Some(value)) = read_tag_or_end(rest, &mut field_tag) {
                    match skip(value, field_tag) {
                        Ok(next) => rest = next,
                        Err(_) => break,
                    }
                }
            }
        }
    }

    #[test]
    fn wire_type_repr_is_the_wire_code() {
        // `#[repr(u8)]` pins each variant to its on-wire code, so generated decoders can use it raw.
        assert_eq!(WireType::Varint as u8, 0);
        assert_eq!(WireType::I64 as u8, 1);
        assert_eq!(WireType::Len as u8, 2);
        assert_eq!(WireType::SGroup as u8, 3);
        assert_eq!(WireType::EGroup as u8, 4);
        assert_eq!(WireType::I32 as u8, 5);
    }

    #[test]
    fn read_tag_or_end_fused_end_one_two_and_three_byte() {
        let mut t = tag(0, WireType::Varint);
        // Clean end of input.
        assert_eq!(read_tag_or_end(&[], &mut t).unwrap(), None);
        // 1-byte tag: field 1, Len.
        assert_eq!(
            read_tag_or_end(&[0x0a, 0x00], &mut t).unwrap(),
            Some(&[0x00][..])
        );
        assert_eq!(t, tag(1, WireType::Len));
        // 2-byte fused tag: field 18 varint = 0x90 0x01 (consumes exactly 2).
        assert_eq!(
            read_tag_or_end(&[0x90, 0x01], &mut t).unwrap(),
            Some(&[][..])
        );
        assert_eq!(t, tag(18, WireType::Varint));
        // 3-byte tag: field 2048 (just past the fused 2-byte range) via the general path. (2048 << 3)
        // = 16384 -> 0x80 0x80 0x01, with a trailing byte.
        assert_eq!(
            read_tag_or_end(&[0x80, 0x80, 0x01, 0x42], &mut t).unwrap(),
            Some(&[0x42][..])
        );
        assert_eq!(t, tag(2048, WireType::Varint));
        // Malformed tag (reserved wire type 7): (1 << 3) | 7 = 0x0f.
        assert_eq!(
            read_tag_or_end(&[0x0f], &mut t).unwrap_err(),
            ErrorKind::InvalidTag
        );
    }

    #[test]
    fn fused_2byte_and_general_paths_agree_for_a_mid_range_field() {
        // Field 18 varint, canonical 2-byte tag (0x90 0x01) goes through the fused 2-byte path; a
        // NON-canonical 3-byte encoding of the same tag (0x90 0x81 0x00) fails the 2-byte guard
        // (second byte 0x81 has the continuation bit) and goes through the general path. Both must
        // decode to the identical tag -- the fast and general paths cannot disagree for 16..=2047.
        let mut fused = tag(0, WireType::Varint);
        let mut general = tag(0, WireType::Varint);
        assert!(read_tag(&[0x90, 0x01], &mut fused).unwrap().is_empty());
        assert!(read_tag(&[0x90, 0x81, 0x00], &mut general)
            .unwrap()
            .is_empty());
        assert_eq!(fused, general);
        assert_eq!(fused, tag(18, WireType::Varint));
    }

    #[test]
    fn varint_overflow_surfaces_through_read_tag() {
        // An over-long tag varint (eleven continuation bytes) falls through to the general varint and
        // overflows -> VarintOverflow (context-neutral), not InvalidTag.
        let mut t = tag(0, WireType::Varint);
        assert_eq!(
            read_tag(&[0xff; 11], &mut t).unwrap_err(),
            ErrorKind::VarintOverflow
        );
    }

    #[test]
    fn length_delimited_rejects_huge_and_overflowing_length() {
        // A length far past the input is Truncated.
        let mut p: &[u8] = &[];
        assert_eq!(
            read_length_delimited(&[0xff, 0xff, 0xff, 0xff, 0x0f, b'x'], &mut p),
            Err(ErrorKind::Truncated)
        );
        // A length varint that itself overflows 64 bits is VarintOverflow.
        assert_eq!(
            read_length_delimited(&[0xff; 11], &mut p).unwrap_err(),
            ErrorKind::VarintOverflow
        );
    }

    #[test]
    fn skip_matches_nested_groups_with_differing_fields() {
        // Outer group field 1; body = inner group field 2 (start 0x13, end 0x14), then the outer end
        // (0x0c). Tags: f2 SGroup=(2<<3)|3=0x13, f2 EGroup=(2<<3)|4=0x14, f1 EGroup=0x0c.
        assert_eq!(
            skip(&[0x13, 0x14, 0x0c], tag(1, WireType::SGroup)),
            Ok(&[][..])
        );
        // The inner (field-2) group closed by a field-1 end tag (0x0c) is a mismatch -> rejected.
        assert_eq!(
            skip(&[0x13, 0x0c, 0x0c], tag(1, WireType::SGroup)),
            Err(ErrorKind::InvalidWireType)
        );
    }
}