Skip to main content

buffa/
types.rs

1// Modified by ReallyMe Technologies Limited.
2//! Protobuf scalar type encoding strategies.
3//!
4//! Each protobuf scalar type has a specific wire encoding. This module provides
5//! encode/decode functions for every scalar type, grouped by wire type.
6//!
7//! | Proto type   | Rust type | Wire type        | Encode fn            |
8//! |-------------|-----------|------------------|----------------------|
9//! | double      | f64       | Fixed64          | `encode_double`      |
10//! | float       | f32       | Fixed32          | `encode_float`       |
11//! | int32       | i32       | Varint           | `encode_int32`       |
12//! | int64       | i64       | Varint           | `encode_int64`       |
13//! | uint32      | u32       | Varint           | `encode_uint32`      |
14//! | uint64      | u64       | Varint           | `encode_uint64`      |
15//! | sint32      | i32       | Varint (zigzag)  | `encode_sint32`      |
16//! | sint64      | i64       | Varint (zigzag)  | `encode_sint64`      |
17//! | fixed32     | u32       | Fixed32          | `encode_fixed32`     |
18//! | fixed64     | u64       | Fixed64          | `encode_fixed64`     |
19//! | sfixed32    | i32       | Fixed32          | `encode_sfixed32`    |
20//! | sfixed64    | i64       | Fixed64          | `encode_sfixed64`    |
21//! | bool        | bool      | Varint           | `encode_bool`        |
22//! | string      | String    | LengthDelimited  | `encode_string`      |
23//! | bytes       | `Vec<u8>` | LengthDelimited  | `encode_bytes`       |
24//!
25//! Each `encode_<type>` also has a fused `put_<type>_field` sibling that
26//! writes the field tag and the payload in one call (plus
27//! [`put_len_delimited_header`] / [`put_group_start`] / [`put_group_end`]
28//! for message and group framing). Generated `write_to` bodies use the
29//! fused forms; the `encode_*` primitives remain the building blocks for
30//! packed payloads and hand-written codecs.
31//!
32//! On the decode side, the varint-family decoders have force-inlined
33//! `_packed` twins ([`decode_int32_packed`] etc.) for per-element use
34//! inside packed-repeated loops, where removing the per-element call
35//! boundary is a large measured win. They are not general-purpose
36//! replacements — see [`decode_int32_packed`] for the trade-off — and
37//! fixed-width types have no twins because their decoders have no
38//! out-of-line fast path to remove.
39//!
40//! # Wire format reference
41//!
42//! Fixed-width types are encoded as little-endian bytes on the wire, per the
43//! protobuf encoding specification:
44//! <https://protobuf.dev/programming-guides/encoding/#non-varint_numbers>
45//!
46//! - Wire type 5 (Fixed32): `float`, `fixed32`, `sfixed32` — 4 bytes LE
47//! - Wire type 1 (Fixed64): `double`, `fixed64`, `sfixed64` — 8 bytes LE
48//!
49//! Varint types (wire type 0) are encoded using the variable-length base-128
50//! encoding. Signed types without zigzag (`int32`, `int64`) sign-extend to 64
51//! bits before encoding; negative `int32` values therefore always occupy 10
52//! bytes. Use `sint32`/`sint64` (zigzag) when negative values are common.
53//! <https://protobuf.dev/programming-guides/encoding/#signed-ints>
54
55use crate::encode_sink::EncodeSink;
56use alloc::string::String;
57use alloc::vec::Vec;
58mod field_payload;
59use bytes::{Buf, Bytes};
60pub use field_payload::FieldPayload;
61
62use crate::encoding::{decode_varint, encode_varint, varint_len, Tag, WireType};
63use crate::error::DecodeError;
64
65/// Validate UTF-8 and return the borrowed `&str`.
66///
67/// With the `fast-utf8` feature (on by default) this dispatches to
68/// [`smoothutf8::from_utf8`], which is faster than [`core::str::from_utf8`]
69/// on the short ASCII strings typical of protobuf field values and (when
70/// `std` is also enabled) delegates inputs of 128 bytes or more to
71/// `simdutf8`. Without the feature, it is exactly `core::str::from_utf8`.
72/// Either way the check is the full Unicode §3.9 well-formedness rule, so
73/// the `from_utf8_unchecked` calls that consume the result are sound.
74// The explicit `return`s are required by the mutually-exclusive `#[cfg]` arms.
75#[allow(clippy::needless_return)]
76#[inline(always)]
77pub(crate) fn validate_str(bytes: &[u8]) -> Result<&str, DecodeError> {
78    #[cfg(feature = "fast-utf8")]
79    return smoothutf8::from_utf8(bytes).ok_or(DecodeError::InvalidUtf8);
80    #[cfg(not(feature = "fast-utf8"))]
81    return core::str::from_utf8(bytes).map_err(|_| DecodeError::InvalidUtf8);
82}
83
84/// Validate `buf[..len]` as UTF-8, where `buf` is a surrounding wire-buffer
85/// slice that may extend past the field.
86///
87/// When at least [`smoothutf8::SLACK`] readable bytes follow `len`
88/// (`buf.len() >= len + SLACK`), this takes [`smoothutf8::verify_with_slack`],
89/// which skips the per-string tail copy that dominates on inputs shorter than
90/// 16 bytes. The slack check is a runtime branch; in a protobuf decode it is
91/// almost always taken — only a string ending within `SLACK` bytes of the
92/// buffer's end falls back to the safe path.
93///
94/// This is the per-field-conditional integration of `verify_with_slack`. The
95/// preferred shape — pad the wire buffer once at ingest with `SLACK` zero
96/// bytes and call `verify_with_slack` unconditionally — requires the caller
97/// (typically connectrpc-rs) to append the padding before `.freeze()`; that
98/// is a follow-up. Until then the per-field branch costs one `cmp/jbe` that
99/// is taken for every field except one ending in the last `SLACK` bytes of
100/// the buffer, so a 1-bit predictor handles it.
101///
102/// # Safety
103///
104/// The caller must have established `len <= buf.len()` (the EOF check that
105/// precedes every call site does).
106// The explicit `return`s are required by the mutually-exclusive `#[cfg]` arms.
107#[allow(clippy::needless_return)]
108#[inline(always)]
109pub(crate) unsafe fn validate_str_in(buf: &[u8], len: usize) -> Result<&str, DecodeError> {
110    debug_assert!(len <= buf.len());
111    // SAFETY: caller established `len <= buf.len()`; that bound also makes
112    // `len + SLACK` non-overflowing (`buf.len() <= isize::MAX`).
113    let field = unsafe { buf.get_unchecked(..len) };
114    #[cfg(feature = "fast-utf8")]
115    {
116        // `len + SLACK` cannot overflow: `len <= buf.len() <= isize::MAX`.
117        let ok = if buf.len() >= len + smoothutf8::SLACK {
118            // SAFETY: `len + SLACK <= buf.len()` was just checked above,
119            // satisfying `verify_with_slack`'s precondition that
120            // `range.end + SLACK` bytes of `buf` are readable; `0 <= len`
121            // satisfies `range.start <= range.end`.
122            unsafe { smoothutf8::verify_with_slack(buf, 0..len) }
123        } else {
124            smoothutf8::verify(field)
125        };
126        return if ok {
127            // SAFETY: `verify`/`verify_with_slack` confirmed `field` is
128            // well-formed UTF-8; their correctness is mechanically verified
129            // against the same Unicode §3.9 rule as `core::str::from_utf8`.
130            Ok(unsafe { core::str::from_utf8_unchecked(field) })
131        } else {
132            Err(DecodeError::InvalidUtf8)
133        };
134    }
135    #[cfg(not(feature = "fast-utf8"))]
136    return core::str::from_utf8(field).map_err(|_| DecodeError::InvalidUtf8);
137}
138
139// ---------------------------------------------------------------------------
140// ZigZag encoding (for sint32/sint64)
141// ---------------------------------------------------------------------------
142
143/// ZigZag encode a signed 32-bit integer.
144///
145/// Maps signed integers to unsigned integers so that values with small
146/// absolute value have small varint encodings:
147///   0 → 0, -1 → 1, 1 → 2, -2 → 3, 2 → 4, ...
148///
149/// Spec: <https://protobuf.dev/programming-guides/encoding/#signed-ints>
150#[inline]
151pub(crate) fn zigzag_encode_i32(value: i32) -> u32 {
152    ((value << 1) ^ (value >> 31)) as u32
153}
154
155/// ZigZag decode an unsigned 32-bit integer to signed.
156#[inline]
157pub(crate) fn zigzag_decode_i32(value: u32) -> i32 {
158    ((value >> 1) as i32) ^ (-((value & 1) as i32))
159}
160
161/// ZigZag encode a signed 64-bit integer.
162#[inline]
163pub(crate) fn zigzag_encode_i64(value: i64) -> u64 {
164    ((value << 1) ^ (value >> 63)) as u64
165}
166
167/// ZigZag decode an unsigned 64-bit integer to signed.
168#[inline]
169pub(crate) fn zigzag_decode_i64(value: u64) -> i64 {
170    ((value >> 1) as i64) ^ (-((value & 1) as i64))
171}
172
173// ---------------------------------------------------------------------------
174// Varint types (wire type 0)
175// ---------------------------------------------------------------------------
176
177/// Encode an `int32` value as a varint (wire type 0).
178///
179/// Negative values are sign-extended to 64 bits before encoding, always
180/// producing a 10-byte varint. Use [`encode_sint32`] when negative values are
181/// common.
182#[inline]
183pub fn encode_int32(value: i32, buf: &mut impl EncodeSink) {
184    // Sign-extend to i64 then reinterpret as u64 per the protobuf spec.
185    encode_varint(value as i64 as u64, buf);
186}
187
188/// Decode an `int32` value from a varint.
189///
190/// The low 32 bits of the decoded varint are returned; upper bits are
191/// truncated (consistent with the protobuf spec for 32-bit integer types).
192#[inline]
193pub fn decode_int32(buf: &mut impl Buf) -> Result<i32, DecodeError> {
194    let v = decode_varint(buf)?;
195    Ok(v as i32)
196}
197
198/// Encode an `int64` value as a varint (wire type 0).
199#[inline]
200pub fn encode_int64(value: i64, buf: &mut impl EncodeSink) {
201    encode_varint(value as u64, buf);
202}
203
204/// Decode an `int64` value from a varint.
205#[inline]
206pub fn decode_int64(buf: &mut impl Buf) -> Result<i64, DecodeError> {
207    let v = decode_varint(buf)?;
208    Ok(v as i64)
209}
210
211/// Encode a `uint32` value as a varint (wire type 0).
212#[inline]
213pub fn encode_uint32(value: u32, buf: &mut impl EncodeSink) {
214    encode_varint(value as u64, buf);
215}
216
217/// Decode a `uint32` value from a varint.
218///
219/// The low 32 bits of the decoded varint are returned; upper bits are
220/// truncated.
221#[inline]
222pub fn decode_uint32(buf: &mut impl Buf) -> Result<u32, DecodeError> {
223    let v = decode_varint(buf)?;
224    Ok(v as u32)
225}
226
227/// Encode a `uint64` value as a varint (wire type 0).
228#[inline]
229pub fn encode_uint64(value: u64, buf: &mut impl EncodeSink) {
230    encode_varint(value, buf);
231}
232
233/// Decode a `uint64` value from a varint.
234#[inline]
235pub fn decode_uint64(buf: &mut impl Buf) -> Result<u64, DecodeError> {
236    decode_varint(buf)
237}
238
239/// Encode a `sint32` value as a varint using ZigZag encoding (wire type 0).
240///
241/// ZigZag maps signed integers to unsigned so that values with small absolute
242/// magnitude produce short varints. Prefer this over [`encode_int32`] when the
243/// field regularly holds negative values.
244#[inline]
245pub fn encode_sint32(value: i32, buf: &mut impl EncodeSink) {
246    encode_varint(zigzag_encode_i32(value) as u64, buf);
247}
248
249/// Decode a `sint32` value from a ZigZag-encoded varint.
250#[inline]
251pub fn decode_sint32(buf: &mut impl Buf) -> Result<i32, DecodeError> {
252    let v = decode_varint(buf)?;
253    // Truncate to u32 before ZigZag decode (spec: upper bits are discarded
254    // for 32-bit types).
255    Ok(zigzag_decode_i32(v as u32))
256}
257
258/// Encode a `sint64` value as a varint using ZigZag encoding (wire type 0).
259#[inline]
260pub fn encode_sint64(value: i64, buf: &mut impl EncodeSink) {
261    encode_varint(zigzag_encode_i64(value), buf);
262}
263
264/// Decode a `sint64` value from a ZigZag-encoded varint.
265#[inline]
266pub fn decode_sint64(buf: &mut impl Buf) -> Result<i64, DecodeError> {
267    let v = decode_varint(buf)?;
268    Ok(zigzag_decode_i64(v))
269}
270
271/// Encode a `bool` value as a varint (wire type 0).
272///
273/// `true` encodes to `0x01`, `false` to `0x00`.
274#[inline]
275pub fn encode_bool(value: bool, buf: &mut impl EncodeSink) {
276    // Both values are < 0x80, so a single byte is a valid varint.
277    buf.put_u8(value as u8);
278}
279
280/// Decode a `bool` value from a varint.
281///
282/// Per the protobuf spec, zero decodes as `false`; any non-zero value decodes
283/// as `true`.
284#[inline]
285pub fn decode_bool(buf: &mut impl Buf) -> Result<bool, DecodeError> {
286    let v = decode_varint(buf)?;
287    Ok(v != 0)
288}
289
290// ---------------------------------------------------------------------------
291// Packed-loop decode variants — varint types
292// ---------------------------------------------------------------------------
293
294/// Force-inlined variant of [`decode_int32`] for packed-repeated element
295/// loops; identical semantics, decodes **one element** per call.
296///
297/// Generated packed-field decode loops call this once per element over the
298/// length-delimited sub-buffer; removing the per-element out-of-line call
299/// is a measured ~16–28% win on packed-varint-dense shapes (see
300/// `encoding::decode_varint_packed` for the measurement anchor). It is
301/// **not** a faster general-purpose [`decode_int32`]: each call site
302/// expands the full unrolled varint decoder (a few hundred bytes), so
303/// using it outside a tight per-element loop bloats the enclosing function
304/// and typically loses to the plain version. Prefer [`decode_int32`] for
305/// singular fields and anything that is not a packed loop.
306///
307/// Only varint-family types have `_packed` twins — fixed-width decoders
308/// ([`decode_fixed32`] etc.) have no out-of-line fast path to remove.
309#[inline(always)]
310pub fn decode_int32_packed(buf: &mut impl Buf) -> Result<i32, DecodeError> {
311    let v = crate::encoding::decode_varint_packed(buf)?;
312    Ok(v as i32)
313}
314
315/// Force-inlined variant of [`decode_int64`] for packed-repeated element
316/// loops; identical semantics, decodes one element per call. Not a faster
317/// general-purpose decoder — see [`decode_int32_packed`] for when to use
318/// the `_packed` family and when to prefer the plain version.
319#[inline(always)]
320pub fn decode_int64_packed(buf: &mut impl Buf) -> Result<i64, DecodeError> {
321    let v = crate::encoding::decode_varint_packed(buf)?;
322    Ok(v as i64)
323}
324
325/// Force-inlined variant of [`decode_uint32`] for packed-repeated element
326/// loops; identical semantics, decodes one element per call. Not a faster
327/// general-purpose decoder — see [`decode_int32_packed`] for when to use
328/// the `_packed` family and when to prefer the plain version.
329#[inline(always)]
330pub fn decode_uint32_packed(buf: &mut impl Buf) -> Result<u32, DecodeError> {
331    let v = crate::encoding::decode_varint_packed(buf)?;
332    Ok(v as u32)
333}
334
335/// Force-inlined variant of [`decode_uint64`] for packed-repeated element
336/// loops; identical semantics, decodes one element per call. Not a faster
337/// general-purpose decoder — see [`decode_int32_packed`] for when to use
338/// the `_packed` family and when to prefer the plain version.
339#[inline(always)]
340pub fn decode_uint64_packed(buf: &mut impl Buf) -> Result<u64, DecodeError> {
341    crate::encoding::decode_varint_packed(buf)
342}
343
344/// Force-inlined variant of [`decode_sint32`] for packed-repeated element
345/// loops; identical semantics, decodes one element per call. Not a faster
346/// general-purpose decoder — see [`decode_int32_packed`] for when to use
347/// the `_packed` family and when to prefer the plain version.
348#[inline(always)]
349pub fn decode_sint32_packed(buf: &mut impl Buf) -> Result<i32, DecodeError> {
350    let v = crate::encoding::decode_varint_packed(buf)?;
351    // Truncate to u32 before ZigZag decode (spec: upper bits are discarded
352    // for 32-bit types).
353    Ok(zigzag_decode_i32(v as u32))
354}
355
356/// Force-inlined variant of [`decode_sint64`] for packed-repeated element
357/// loops; identical semantics, decodes one element per call. Not a faster
358/// general-purpose decoder — see [`decode_int32_packed`] for when to use
359/// the `_packed` family and when to prefer the plain version.
360#[inline(always)]
361pub fn decode_sint64_packed(buf: &mut impl Buf) -> Result<i64, DecodeError> {
362    let v = crate::encoding::decode_varint_packed(buf)?;
363    Ok(zigzag_decode_i64(v))
364}
365
366/// Force-inlined variant of [`decode_bool`] for packed-repeated element
367/// loops; identical semantics, decodes one element per call. Not a faster
368/// general-purpose decoder — see [`decode_int32_packed`] for when to use
369/// the `_packed` family and when to prefer the plain version.
370#[inline(always)]
371pub fn decode_bool_packed(buf: &mut impl Buf) -> Result<bool, DecodeError> {
372    let v = crate::encoding::decode_varint_packed(buf)?;
373    Ok(v != 0)
374}
375
376// ---------------------------------------------------------------------------
377// Bulk packed decode — varint types
378// ---------------------------------------------------------------------------
379
380/// Stamp a bulk packed-payload extender over a varint-family element type.
381macro_rules! extend_packed_varint_fn {
382    ($(#[$doc:meta])* $name:ident, $ty:ty, $decode_one:ident, $conv:expr) => {
383        $(#[$doc])*
384        ///
385        /// Requires the payload's final byte to have its continuation bit
386        /// clear (true of every well-formed packed payload); payloads that
387        /// violate it fall back to the per-element decoder so truncated
388        /// trailing elements keep their exact error and partial-extension
389        /// behavior.
390        ///
391        /// `reserve` is the caller's pre-allocation hint: generated view
392        /// code passes the exact count from
393        /// [`crate::encoding::count_varints`], generated owned code passes
394        /// the payload byte length (an upper bound) — each path keeps the
395        /// allocation policy it had with the per-element loop.
396        #[inline]
397        pub fn $name(payload: &[u8], out: &mut Vec<$ty>, reserve: usize) -> Result<(), DecodeError> {
398            out.reserve(reserve);
399            match payload.last() {
400                None => Ok(()),
401                Some(&last) if last < 0x80 => {
402                    crate::encoding::for_each_packed_varint(payload, |v| out.push($conv(v)))
403                }
404                Some(_) => {
405                    // Unterminated trailing element: per-element loop for
406                    // exact error parity.
407                    let mut cur = payload;
408                    while !cur.is_empty() {
409                        out.push($decode_one(&mut cur)?);
410                    }
411                    Ok(())
412                }
413            }
414        }
415    };
416}
417
418extend_packed_varint_fn!(
419    /// Decode an entire packed `int32` payload into `out` in one pass.
420    extend_packed_int32, i32, decode_int32, |v| v as i32
421);
422extend_packed_varint_fn!(
423    /// Decode an entire packed `int64` payload into `out` in one pass.
424    extend_packed_int64, i64, decode_int64, |v| v as i64
425);
426extend_packed_varint_fn!(
427    /// Decode an entire packed `uint32` payload into `out` in one pass.
428    extend_packed_uint32, u32, decode_uint32, |v| v as u32
429);
430extend_packed_varint_fn!(
431    /// Decode an entire packed `uint64` payload into `out` in one pass.
432    extend_packed_uint64, u64, decode_uint64, |v| v
433);
434extend_packed_varint_fn!(
435    /// Decode an entire packed `sint32` payload into `out` in one pass.
436    extend_packed_sint32, i32, decode_sint32, |v| zigzag_decode_i32(v as u32)
437);
438extend_packed_varint_fn!(
439    /// Decode an entire packed `sint64` payload into `out` in one pass.
440    extend_packed_sint64, i64, decode_sint64, zigzag_decode_i64
441);
442extend_packed_varint_fn!(
443    /// Decode an entire packed `bool` payload into `out` in one pass.
444    extend_packed_bool, bool, decode_bool, |v| v != 0
445);
446
447// ---------------------------------------------------------------------------
448// Encoded size helpers — varint types
449// ---------------------------------------------------------------------------
450
451/// Encoded length of an `int32` value in bytes.
452///
453/// Negative values sign-extend to 64 bits and always produce a 10-byte varint.
454#[inline]
455pub fn int32_encoded_len(value: i32) -> usize {
456    varint_len(value as i64 as u64)
457}
458
459/// Encoded length of an `int64` value in bytes.
460#[inline]
461pub fn int64_encoded_len(value: i64) -> usize {
462    varint_len(value as u64)
463}
464
465/// Encoded length of a `uint32` value in bytes.
466#[inline]
467pub fn uint32_encoded_len(value: u32) -> usize {
468    varint_len(value as u64)
469}
470
471/// Encoded length of a `uint64` value in bytes.
472#[inline]
473pub fn uint64_encoded_len(value: u64) -> usize {
474    varint_len(value)
475}
476
477/// Encoded length of a `sint32` value in bytes.
478#[inline]
479pub fn sint32_encoded_len(value: i32) -> usize {
480    varint_len(zigzag_encode_i32(value) as u64)
481}
482
483/// Encoded length of a `sint64` value in bytes.
484#[inline]
485pub fn sint64_encoded_len(value: i64) -> usize {
486    varint_len(zigzag_encode_i64(value))
487}
488
489/// Encoded size of a `bool` value: always 1 byte.
490pub const BOOL_ENCODED_LEN: usize = 1;
491
492// ---------------------------------------------------------------------------
493// Fixed-width 32-bit types (wire type 5)
494// ---------------------------------------------------------------------------
495
496/// Encode a `float` value as 4 bytes little-endian (wire type 5).
497#[inline]
498pub fn encode_float(value: f32, buf: &mut impl EncodeSink) {
499    buf.put_f32_le(value);
500}
501
502/// Decode a `float` value from 4 bytes little-endian.
503#[inline]
504pub fn decode_float(buf: &mut impl Buf) -> Result<f32, DecodeError> {
505    if buf.remaining() < 4 {
506        return Err(DecodeError::UnexpectedEof);
507    }
508    Ok(buf.get_f32_le())
509}
510
511/// Encode a `fixed32` value as 4 bytes little-endian (wire type 5).
512#[inline]
513pub fn encode_fixed32(value: u32, buf: &mut impl EncodeSink) {
514    buf.put_u32_le(value);
515}
516
517/// Decode a `fixed32` value from 4 bytes little-endian.
518#[inline]
519pub fn decode_fixed32(buf: &mut impl Buf) -> Result<u32, DecodeError> {
520    if buf.remaining() < 4 {
521        return Err(DecodeError::UnexpectedEof);
522    }
523    Ok(buf.get_u32_le())
524}
525
526/// Encode an `sfixed32` value as 4 bytes little-endian (wire type 5).
527///
528/// `sfixed32` is a signed 32-bit integer stored as its two's complement
529/// representation in little-endian order — identical bit pattern to `fixed32`.
530#[inline]
531pub fn encode_sfixed32(value: i32, buf: &mut impl EncodeSink) {
532    buf.put_i32_le(value);
533}
534
535/// Decode an `sfixed32` value from 4 bytes little-endian.
536#[inline]
537pub fn decode_sfixed32(buf: &mut impl Buf) -> Result<i32, DecodeError> {
538    if buf.remaining() < 4 {
539        return Err(DecodeError::UnexpectedEof);
540    }
541    Ok(buf.get_i32_le())
542}
543
544// ---------------------------------------------------------------------------
545// Fixed-width 64-bit types (wire type 1)
546// ---------------------------------------------------------------------------
547
548/// Encode a `double` value as 8 bytes little-endian (wire type 1).
549#[inline]
550pub fn encode_double(value: f64, buf: &mut impl EncodeSink) {
551    buf.put_f64_le(value);
552}
553
554/// Decode a `double` value from 8 bytes little-endian.
555#[inline]
556pub fn decode_double(buf: &mut impl Buf) -> Result<f64, DecodeError> {
557    if buf.remaining() < 8 {
558        return Err(DecodeError::UnexpectedEof);
559    }
560    Ok(buf.get_f64_le())
561}
562
563/// Encode a `fixed64` value as 8 bytes little-endian (wire type 1).
564#[inline]
565pub fn encode_fixed64(value: u64, buf: &mut impl EncodeSink) {
566    buf.put_u64_le(value);
567}
568
569/// Decode a `fixed64` value from 8 bytes little-endian.
570#[inline]
571pub fn decode_fixed64(buf: &mut impl Buf) -> Result<u64, DecodeError> {
572    if buf.remaining() < 8 {
573        return Err(DecodeError::UnexpectedEof);
574    }
575    Ok(buf.get_u64_le())
576}
577
578/// Encode an `sfixed64` value as 8 bytes little-endian (wire type 1).
579///
580/// `sfixed64` is a signed 64-bit integer stored as its two's complement
581/// representation in little-endian order — identical bit pattern to `fixed64`.
582#[inline]
583pub fn encode_sfixed64(value: i64, buf: &mut impl EncodeSink) {
584    buf.put_i64_le(value);
585}
586
587/// Decode an `sfixed64` value from 8 bytes little-endian.
588#[inline]
589pub fn decode_sfixed64(buf: &mut impl Buf) -> Result<i64, DecodeError> {
590    if buf.remaining() < 8 {
591        return Err(DecodeError::UnexpectedEof);
592    }
593    Ok(buf.get_i64_le())
594}
595
596// ---------------------------------------------------------------------------
597// Bulk packed decode — fixed-width types
598// ---------------------------------------------------------------------------
599
600/// Stamp a bulk packed-payload extender over a fixed-width element type.
601macro_rules! extend_packed_fixed_fn {
602    ($(#[$doc:meta])* $name:ident, $ty:ty, $width:expr) => {
603        $(#[$doc])*
604        ///
605        /// The payload length is validated against the element width up
606        /// front, so a malformed payload fails with [`DecodeError::UnexpectedEof`]
607        /// — the same error the per-element loop produces at the trailing
608        /// partial element — and leaves `out` unmodified rather than
609        /// partially extended.
610        ///
611        /// `from_le_bytes` over [`slice::chunks_exact`] is endian-correct on
612        /// every target and compiles to a bulk copy on little-endian ones,
613        /// which is where the win over the per-element loop comes from: one
614        /// bounds regime for the whole payload instead of a remaining-bytes
615        /// check per element.
616        #[inline]
617        pub fn $name(payload: &[u8], out: &mut Vec<$ty>) -> Result<(), DecodeError> {
618            if payload.len() % $width != 0 {
619                return Err(DecodeError::UnexpectedEof);
620            }
621            out.reserve(payload.len() / $width);
622            out.extend(payload.chunks_exact($width).map(|chunk| {
623                <$ty>::from_le_bytes(chunk.try_into().expect("chunks_exact yields width-sized chunks"))
624            }));
625            Ok(())
626        }
627    };
628}
629
630extend_packed_fixed_fn!(
631    /// Decode an entire packed `float` payload into `out` in one pass.
632    extend_packed_float, f32, 4
633);
634extend_packed_fixed_fn!(
635    /// Decode an entire packed `fixed32` payload into `out` in one pass.
636    extend_packed_fixed32, u32, 4
637);
638extend_packed_fixed_fn!(
639    /// Decode an entire packed `sfixed32` payload into `out` in one pass.
640    extend_packed_sfixed32, i32, 4
641);
642extend_packed_fixed_fn!(
643    /// Decode an entire packed `double` payload into `out` in one pass.
644    extend_packed_double, f64, 8
645);
646extend_packed_fixed_fn!(
647    /// Decode an entire packed `fixed64` payload into `out` in one pass.
648    extend_packed_fixed64, u64, 8
649);
650extend_packed_fixed_fn!(
651    /// Decode an entire packed `sfixed64` payload into `out` in one pass.
652    extend_packed_sfixed64, i64, 8
653);
654
655// ---------------------------------------------------------------------------
656// Encoded size helpers (fixed-width types are constant-size)
657// ---------------------------------------------------------------------------
658
659/// Encoded size of a `float`, `fixed32`, or `sfixed32` value: always 4 bytes.
660pub const FIXED32_ENCODED_LEN: usize = 4;
661
662/// Encoded size of a `double`, `fixed64`, or `sfixed64` value: always 8 bytes.
663pub const FIXED64_ENCODED_LEN: usize = 8;
664
665// ---------------------------------------------------------------------------
666// Fused tag + payload field writers
667// ---------------------------------------------------------------------------
668//
669// Generated `write_to` bodies pair every payload write with a tag write.
670// These helpers fuse the two so each field arm is one call; the presence
671// check (`if !x.is_empty()`, `if let Some(v)`, …) stays in generated code
672// where the per-field semantics are visible. They are `#[inline(always)]`
673// shims over the `Tag::encode` + `encode_*` primitives: with the field number a
674// literal at every call site, forced inlining lets the optimizer const-fold the
675// tag to constant byte store(s) — recovering the codegen the pre-fusion
676// two-statement expansion produced. The fold relies on `Tag::encode` /
677// `encode_varint` continuing to inline at constant input. Plain `#[inline]` was
678// not sufficient: the inliner declined it for the larger string/bytes variants,
679// silently reintroducing a per-call runtime tag varint (~6-9% on encode-heavy
680// paths). They are shared by owned and view `write_to` impls (duck-typed:
681// `&String` / `&str` and `&Vec<u8>` / `&[u8]` both coerce to the borrowed
682// parameter).
683
684/// Stamp a fused `put_<type>_field` writer over an existing `encode_<type>`.
685macro_rules! put_field_fn {
686    ($(#[$doc:meta])* $name:ident, $value:ty, $wire:expr, $encode:ident) => {
687        $(#[$doc])*
688        ///
689        #[doc = concat!(
690            "Fused tag+payload sibling of [`", stringify!($encode), "`]; ",
691            "exists so generated `write_to` bodies are one call per field."
692        )]
693        // `#[inline(always)]`, applied uniformly by the macro. It is load-bearing
694        // for the larger string/bytes variants — the inliner declined the plain
695        // `#[inline]` hint there, leaving `field_number` a runtime arg that
696        // re-encodes the tag varint per call — and harmless for the small scalar
697        // variants (already inlined). With the field number a literal at the call
698        // site, inlining const-folds the tag to constant byte store(s): one byte
699        // for field numbers 1-15, a few for larger numbers.
700        #[inline(always)]
701        pub fn $name(field_number: u32, value: $value, buf: &mut impl EncodeSink) {
702            Tag::new(field_number, $wire).encode(buf);
703            $encode(value, buf);
704        }
705    };
706}
707
708put_field_fn!(
709    /// Write a tagged `int32` field (tag + varint payload).
710    put_int32_field, i32, WireType::Varint, encode_int32
711);
712put_field_fn!(
713    /// Write a tagged `int64` field (tag + varint payload).
714    put_int64_field, i64, WireType::Varint, encode_int64
715);
716put_field_fn!(
717    /// Write a tagged `uint32` field (tag + varint payload).
718    put_uint32_field, u32, WireType::Varint, encode_uint32
719);
720put_field_fn!(
721    /// Write a tagged `uint64` field (tag + varint payload).
722    put_uint64_field, u64, WireType::Varint, encode_uint64
723);
724put_field_fn!(
725    /// Write a tagged `sint32` field (tag + zigzag varint payload).
726    put_sint32_field, i32, WireType::Varint, encode_sint32
727);
728put_field_fn!(
729    /// Write a tagged `sint64` field (tag + zigzag varint payload).
730    put_sint64_field, i64, WireType::Varint, encode_sint64
731);
732put_field_fn!(
733    /// Write a tagged `bool` field (tag + one-byte payload).
734    put_bool_field, bool, WireType::Varint, encode_bool
735);
736put_field_fn!(
737    /// Write a tagged `fixed32` field (tag + 4-byte payload).
738    put_fixed32_field, u32, WireType::Fixed32, encode_fixed32
739);
740put_field_fn!(
741    /// Write a tagged `fixed64` field (tag + 8-byte payload).
742    put_fixed64_field, u64, WireType::Fixed64, encode_fixed64
743);
744put_field_fn!(
745    /// Write a tagged `sfixed32` field (tag + 4-byte payload).
746    put_sfixed32_field, i32, WireType::Fixed32, encode_sfixed32
747);
748put_field_fn!(
749    /// Write a tagged `sfixed64` field (tag + 8-byte payload).
750    put_sfixed64_field, i64, WireType::Fixed64, encode_sfixed64
751);
752put_field_fn!(
753    /// Write a tagged `float` field (tag + 4-byte payload).
754    put_float_field, f32, WireType::Fixed32, encode_float
755);
756put_field_fn!(
757    /// Write a tagged `double` field (tag + 8-byte payload).
758    put_double_field, f64, WireType::Fixed64, encode_double
759);
760put_field_fn!(
761    /// Write a tagged `string` field (tag + length-prefixed UTF-8 payload).
762    put_string_field, &str, WireType::LengthDelimited, encode_string
763);
764put_field_fn!(
765    /// Write a tagged `bytes` field (tag + length-prefixed payload).
766    put_bytes_field, &[u8], WireType::LengthDelimited, encode_bytes
767);
768
769/// A value a `bytes` field can encode from: every [`ProtoBytes`]
770/// representation, plus the borrowed `&[u8]` that view types carry.
771///
772/// This exists so [`put_shared_bytes_field`] can serve the duck-typed
773/// `write_to` bodies codegen shares between owned messages and views. The
774/// borrowed form has no owned handle to share ([`as_shared`](Self::as_shared)
775/// is `None`); a [`Rope`](crate::Rope) sink can still capture it zero-copy
776/// through its backing-buffer containment check.
777pub trait AsSharedBytes {
778    /// The value's bytes.
779    fn as_bytes_slice(&self) -> &[u8];
780
781    /// A reference-counted handle to exactly the bytes of
782    /// [`as_bytes_slice`](Self::as_bytes_slice), when one exists.
783    #[inline]
784    fn as_shared(&self) -> Option<Bytes> {
785        None
786    }
787}
788
789impl<B: ProtoBytes> AsSharedBytes for B {
790    #[inline]
791    fn as_bytes_slice(&self) -> &[u8] {
792        self.as_ref()
793    }
794
795    #[inline]
796    fn as_shared(&self) -> Option<Bytes> {
797        ProtoBytes::as_shared(self)
798    }
799}
800
801// View `bytes` fields are `&'a [u8]`. No overlap with the blanket impl:
802// `&[u8]` does not implement `ProtoBytes`, and never can — `ProtoBytes`
803// requires `From<Vec<u8>>`, and `impl From<Vec<u8>> for &[u8]` is
804// orphan-forbidden for every crate (all three types/traits are foreign to
805// any crate that would try), so the disjointness is permanent.
806impl AsSharedBytes for &[u8] {
807    #[inline]
808    fn as_bytes_slice(&self) -> &[u8] {
809        self
810    }
811}
812
813/// Write a tagged `bytes` field, splicing the payload into segmented sinks
814/// by reference count when the value can produce a [`Bytes`] handle.
815///
816/// Generated `write_to` bodies use this for every `bytes` field. The
817/// zero-copy attempt runs only when the sink declares
818/// [`IS_SEGMENTED`](EncodeSink::IS_SEGMENTED) — for contiguous sinks
819/// (`Vec<u8>`, `BytesMut`, every other `BufMut`) the constant is `false`,
820/// the branch const-folds away, and the payload is copied exactly as
821/// [`put_bytes_field`] would, with no refcount traffic. Into a
822/// [`Rope`](crate::Rope), `bytes::Bytes` fields (and custom [`ProtoBytes`]
823/// representations implementing `as_shared`) become refcount-shared
824/// segments; `Vec<u8>` and view `&[u8]` values fall back to
825/// [`EncodeSink::put_slice`], where the rope's backing-buffer capture can
826/// still apply.
827#[inline(always)]
828pub fn put_shared_bytes_field<B: AsSharedBytes, S: EncodeSink>(
829    field_number: u32,
830    value: &B,
831    buf: &mut S,
832) {
833    Tag::new(field_number, WireType::LengthDelimited).encode(buf);
834    encode_shared_bytes(value, buf);
835}
836
837/// Encode a length-delimited `bytes` value (varint length prefix + payload,
838/// no tag), splicing the payload into segmented sinks by reference count
839/// when the value can produce a [`Bytes`] handle.
840///
841/// The tagless sibling of [`put_shared_bytes_field`] and the shared-aware
842/// counterpart of [`encode_bytes`]; map value codecs use it directly (the
843/// map entry writes the value tag itself).
844#[inline(always)]
845pub fn encode_shared_bytes<B: AsSharedBytes, S: EncodeSink>(value: &B, buf: &mut S) {
846    let slice = value.as_bytes_slice();
847    encode_varint(slice.len() as u64, buf);
848    if S::IS_SEGMENTED {
849        if let Some(shared) = value.as_shared() {
850            debug_assert_eq!(
851                shared.len(),
852                slice.len(),
853                "as_shared must view exactly as_bytes_slice's bytes"
854            );
855            buf.put_shared(shared);
856            return;
857        }
858    }
859    buf.put_slice(slice);
860}
861
862/// Write a length-delimited field header: tag + payload-length varint.
863///
864/// Used for sub-message fields (the payload follows via `write_to`, its
865/// length coming from the [`SizeCache`](crate::SizeCache)) and for packed
866/// repeated fields (the payload loop follows).
867///
868/// The arguments are `(field_number, len)` — both plain integers, so
869/// transposing them can compile (integer literals infer either width) but
870/// emits a structurally-valid-but-wrong header.
871///
872/// `len` is `u64`, like all size arithmetic feeding the encode path;
873/// callers holding a `u32` (e.g. from
874/// [`SizeCache::consume_next`](crate::SizeCache::consume_next)) widen with
875/// `u64::from`.
876#[inline(always)]
877pub fn put_len_delimited_header(field_number: u32, len: u64, buf: &mut impl EncodeSink) {
878    Tag::new(field_number, WireType::LengthDelimited).encode(buf);
879    encode_varint(len, buf);
880}
881
882/// Write a group field's `StartGroup` tag.
883#[inline(always)]
884pub fn put_group_start(field_number: u32, buf: &mut impl EncodeSink) {
885    Tag::new(field_number, WireType::StartGroup).encode(buf);
886}
887
888/// Write a group field's `EndGroup` tag.
889#[inline(always)]
890pub fn put_group_end(field_number: u32, buf: &mut impl EncodeSink) {
891    Tag::new(field_number, WireType::EndGroup).encode(buf);
892}
893
894// ---------------------------------------------------------------------------
895// Length-delimited types (wire type 2): string and bytes
896// ---------------------------------------------------------------------------
897
898/// Encode a `string` value as a varint length prefix followed by UTF-8 bytes
899/// (wire type 2).
900#[inline]
901pub fn encode_string(value: &str, buf: &mut impl EncodeSink) {
902    encode_varint(value.len() as u64, buf);
903    buf.put_slice(value.as_bytes());
904}
905
906/// Append exactly `len` bytes from `buf` to `dst`, chunk by chunk, publishing
907/// them (extending `dst.len()`) only once every byte has been written.
908///
909/// This is `Buf::copy_to_slice` into `dst`'s spare capacity, without the
910/// zero-fill a `resize` would cost and without ever letting `dst`'s length
911/// cover memory this call did not initialise: `chunk()` / `advance()` are safe,
912/// user-implementable methods, so if one of them unwinds part-way through, or
913/// `chunk()` runs dry before `len` bytes have been copied (a `Buf` whose
914/// `remaining()` over-reports), the bytes already written are simply spare
915/// capacity again. The caller must have checked `buf.remaining() >= len`.
916///
917/// # Panics
918///
919/// If `buf.chunk()` returns an empty slice before `len` bytes have been copied.
920/// The stock `copy_to_slice` spins forever on such a `Buf`; this one names it.
921#[inline]
922fn copy_into_spare(buf: &mut impl Buf, dst: &mut Vec<u8>, len: usize) {
923    dst.reserve(len);
924    let start = dst.len();
925    let spare = &mut dst.spare_capacity_mut()[..len];
926    let mut written = 0;
927    while written < len {
928        let chunk = buf.chunk();
929        let n = chunk.len().min(len - written);
930        assert!(
931            n > 0,
932            "Buf::chunk returned an empty slice with {} bytes still to read",
933            len - written
934        );
935        // SAFETY: `MaybeUninit<u8>` has the same layout as `u8`, and the
936        // destination `spare[written..written + n]` lies within the `len`
937        // reserved slots (`written + n <= len` by the `min` above), so the
938        // write is in bounds. It cannot overlap `chunk`: `dst` is a `&mut
939        // Vec` and therefore uniquely borrowed for this call, while `chunk`
940        // is borrowed from `buf`.
941        unsafe {
942            core::ptr::copy_nonoverlapping(
943                chunk.as_ptr(),
944                spare.as_mut_ptr().add(written).cast::<u8>(),
945                n,
946            );
947        }
948        buf.advance(n);
949        written += n;
950    }
951    // SAFETY: the loop exits only with `written == len`, so `dst[start..start
952    // + len]` was fully initialised above and `start + len <= dst.capacity()`
953    // by the `reserve`. Every early exit (a panic in `chunk`/`advance`, or the
954    // assertion) leaves `dst.len() == start`.
955    unsafe { dst.set_len(start + len) };
956}
957
958/// Decode a `string` value: read a varint length prefix, then that many bytes,
959/// and validate that the bytes are valid UTF-8.
960///
961/// # Errors
962///
963/// - [`DecodeError::UnexpectedEof`] if the buffer has fewer bytes than the
964///   declared length.
965/// - [`DecodeError::MessageTooLarge`] if the declared length overflows `usize`.
966/// - [`DecodeError::InvalidUtf8`] if the bytes are not valid UTF-8.
967///
968/// # Panics
969///
970/// If `buf.chunk()` returns an empty slice before `buf.remaining()` bytes have
971/// been read — a `Buf` that violates its own contract.
972#[inline]
973pub fn decode_string(buf: &mut impl Buf) -> Result<String, DecodeError> {
974    let len = decode_varint(buf)?;
975    let len = usize::try_from(len).map_err(|_| DecodeError::MessageTooLarge)?;
976    if buf.remaining() < len {
977        return Err(DecodeError::UnexpectedEof);
978    }
979    let chunk = buf.chunk();
980    if chunk.len() >= len {
981        // Field is contiguous in the source: validate against the source
982        // chunk, then own. `validate_str_in` itself checks
983        // `chunk.len() >= len + SLACK` and takes the slack-buffer fast path
984        // when satisfied (the common case — the chunk continues past this
985        // field whenever more wire data follows), else the safe path. Advance
986        // the cursor regardless of validity, matching the
987        // consume-before-validate behaviour below.
988        //
989        // SAFETY: `chunk.len() >= len` was just checked.
990        let r = unsafe { validate_str_in(chunk, len) }.map(alloc::borrow::ToOwned::to_owned);
991        buf.advance(len);
992        return r;
993    }
994    // Non-contiguous: own first (the source has no single slice to validate
995    // against), then validate the owned bytes via the safe path.
996    let mut bytes = Vec::with_capacity(len);
997    copy_into_spare(buf, &mut bytes, len);
998    validate_str(&bytes)?;
999    // SAFETY: `validate_str` just confirmed `bytes` is well-formed UTF-8.
1000    Ok(unsafe { String::from_utf8_unchecked(bytes) })
1001}
1002
1003/// Merge a length-delimited string into an existing `String`, reusing its
1004/// heap allocation when possible.
1005///
1006/// Reads a varint length prefix, then that many bytes from `buf`, validates
1007/// UTF-8, and replaces the contents of `value` without deallocating its
1008/// backing buffer (provided the existing capacity is sufficient).
1009///
1010/// # Errors
1011///
1012/// - [`DecodeError::UnexpectedEof`] if the buffer has fewer bytes than the
1013///   declared length.
1014/// - [`DecodeError::MessageTooLarge`] if the declared length overflows `usize`.
1015/// - [`DecodeError::InvalidUtf8`] if the bytes are not valid UTF-8.
1016///
1017/// # Panics
1018///
1019/// If `buf.chunk()` returns an empty slice before `buf.remaining()` bytes have
1020/// been read — a `Buf` that violates its own contract. `value` is left empty.
1021#[inline]
1022pub fn merge_string(value: &mut String, buf: &mut impl Buf) -> Result<(), DecodeError> {
1023    let len = decode_varint(buf)?;
1024    let len = usize::try_from(len).map_err(|_| DecodeError::MessageTooLarge)?;
1025    if buf.remaining() < len {
1026        return Err(DecodeError::UnexpectedEof);
1027    }
1028    let chunk = buf.chunk();
1029    if chunk.len() >= len {
1030        // Field is contiguous in the source: validate against the source
1031        // chunk, then copy into `value` reusing its allocation.
1032        // `validate_str_in` itself checks `chunk.len() >= len + SLACK` and
1033        // takes the slack-buffer fast path when satisfied, else the safe
1034        // path. Advance the cursor regardless of validity.
1035        //
1036        // SAFETY: `chunk.len() >= len` was just checked.
1037        let r: Result<(), DecodeError> = match unsafe { validate_str_in(chunk, len) } {
1038            Ok(s) => {
1039                value.clear();
1040                value.push_str(s);
1041                Ok(())
1042            }
1043            Err(e) => {
1044                value.clear(); // leave in a valid (empty) state on error
1045                Err(e)
1046            }
1047        };
1048        buf.advance(len);
1049        return r;
1050    }
1051    // Non-contiguous: own first into `value`'s buffer, then validate via the
1052    // safe path.
1053    //
1054    // SAFETY: `as_mut_vec` requires that the vec contains valid UTF-8 when
1055    // the String is next used as a string. It is cleared (trivially valid)
1056    // before the copy and stays empty if the copy unwinds; we validate UTF-8
1057    // below before returning Ok, and clear the vec on validation failure.
1058    let vec = unsafe { value.as_mut_vec() };
1059    vec.clear();
1060    copy_into_spare(buf, vec, len);
1061    // Validate UTF-8 on the new content.
1062    if validate_str(vec).is_err() {
1063        vec.clear(); // leave in a valid state on error
1064        return Err(DecodeError::InvalidUtf8);
1065    }
1066    Ok(())
1067}
1068
1069/// The raw, length-delimited payload of a `string` or `bytes` field, handed to
1070/// [`ProtoString::from_wire`] / [`ProtoBytes::from_wire`] so a representation can
1071/// construct itself directly from the wire — validating (or skipping validation)
1072/// and choosing borrow-vs-own on its own terms.
1073///
1074/// By default the decoder hands over a borrowed payload when the field's
1075/// bytes are contiguous in the current input chunk (the common case for slice-
1076/// and `Bytes`-backed sources) and an owned [`Bytes`] otherwise (e.g. a field
1077/// straddling a `Chain` boundary). The exception is a [`ProtoBytes`] type that
1078/// sets [`PREFERS_OWNED_PAYLOAD`](ProtoBytes::PREFERS_OWNED_PAYLOAD):
1079/// the default [`ProtoBytes::decode_length_delimited`] hands it an owned
1080/// payload for every `bytes` field. A
1081/// representation validates-and-borrows with [`to_str`](Self::to_str), reads
1082/// the raw bytes with [`as_slice`](Self::as_slice) (always zero-copy), or takes
1083/// ownership with [`into_bytes`](Self::into_bytes) (zero-copy only for an owned
1084/// payload).
1085///
1086/// Opaque so that a borrowed payload can carry the surrounding wire-buffer tail
1087/// for the slack-aware UTF-8 validator without exposing it to consumers; use the
1088/// accessors above and the [`borrowed`](Self::borrowed) / [`owned`](Self::owned)
1089/// constructors.
1090#[derive(Clone)]
1091pub struct WirePayload<'a>(WirePayloadRepr<'a>);
1092
1093impl core::fmt::Debug for WirePayload<'_> {
1094    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
1095        // Print only the field bytes, never the surrounding tail (which for a
1096        // decoder-constructed payload is subsequent fields' wire bytes).
1097        f.debug_struct("WirePayload")
1098            .field("bytes", &self.as_slice())
1099            .field("owned", &self.is_owned())
1100            .finish()
1101    }
1102}
1103
1104#[derive(Clone)]
1105enum WirePayloadRepr<'a> {
1106    /// `chunk[..len]` is the field; `chunk[len..]` is the surrounding
1107    /// wire-buffer tail (empty when constructed via `WirePayload::borrowed`).
1108    /// Invariant: `len <= chunk.len()`.
1109    Borrowed {
1110        chunk: &'a [u8],
1111        len: usize,
1112    },
1113    Owned(Bytes),
1114}
1115
1116impl<'a> WirePayload<'a> {
1117    /// A payload borrowing exactly `field` (no surrounding wire buffer).
1118    ///
1119    /// Tests and hand-built payloads use this; the decoder uses an internal
1120    /// constructor that also carries the surrounding tail so
1121    /// [`to_str`](Self::to_str) can take the slack-aware fast path.
1122    #[inline]
1123    #[must_use]
1124    pub const fn borrowed(field: &'a [u8]) -> Self {
1125        Self(WirePayloadRepr::Borrowed {
1126            chunk: field,
1127            len: field.len(),
1128        })
1129    }
1130
1131    /// A payload owning `bytes`.
1132    #[inline]
1133    #[must_use]
1134    pub const fn owned(bytes: Bytes) -> Self {
1135        Self(WirePayloadRepr::Owned(bytes))
1136    }
1137
1138    /// `chunk[..len]` is the field; `chunk[len..]` is readable tail. The caller
1139    /// has established `len <= chunk.len()` (the EOF check before every call).
1140    #[inline]
1141    pub(crate) fn borrowed_in(chunk: &'a [u8], len: usize) -> Self {
1142        debug_assert!(len <= chunk.len());
1143        Self(WirePayloadRepr::Borrowed { chunk, len })
1144    }
1145
1146    /// Borrow the field's bytes (zero-copy in both variants).
1147    #[inline]
1148    #[must_use]
1149    pub fn as_slice(&self) -> &[u8] {
1150        match &self.0 {
1151            WirePayloadRepr::Borrowed { chunk, len } => &chunk[..*len],
1152            WirePayloadRepr::Owned(b) => b,
1153        }
1154    }
1155
1156    /// Field length in bytes.
1157    #[inline]
1158    #[must_use]
1159    pub fn len(&self) -> usize {
1160        match &self.0 {
1161            WirePayloadRepr::Borrowed { len, .. } => *len,
1162            WirePayloadRepr::Owned(b) => b.len(),
1163        }
1164    }
1165
1166    /// Whether the field is empty.
1167    #[inline]
1168    #[must_use]
1169    pub fn is_empty(&self) -> bool {
1170        self.len() == 0
1171    }
1172
1173    /// Whether this payload owns its bytes (and so [`into_bytes`](Self::into_bytes)
1174    /// is zero-copy). A `from_wire` impl that wants the [`Bytes`] only when it's
1175    /// free can branch on this and fall back to [`as_slice`](Self::as_slice)
1176    /// otherwise.
1177    #[inline]
1178    #[must_use]
1179    pub fn is_owned(&self) -> bool {
1180        matches!(self.0, WirePayloadRepr::Owned(_))
1181    }
1182
1183    /// Borrow the payload as a `&str` if it is valid UTF-8.
1184    ///
1185    /// Convenience for [`ProtoString::from_wire`] implementations; uses
1186    /// buffa's UTF-8 validator (so it picks up the `fast-utf8` feature when
1187    /// enabled) and returns the same [`DecodeError::InvalidUtf8`] the
1188    /// built-in `String` representation would. For a borrowed payload that
1189    /// carries surrounding wire-buffer tail (the decoder's common case) this
1190    /// reaches the slack-aware fast path; the `borrowed`/`owned` constructors
1191    /// have no tail, so they take the plain validator.
1192    ///
1193    /// # Errors
1194    ///
1195    /// Returns [`DecodeError::InvalidUtf8`] if the bytes are not valid UTF-8.
1196    #[inline]
1197    #[must_use = "the validated `&str` is the only way to use the payload as a string"]
1198    pub fn to_str(&self) -> Result<&str, DecodeError> {
1199        match &self.0 {
1200            // SAFETY: the `Borrowed` invariant is `len <= chunk.len()`,
1201            // satisfying `validate_str_in`'s precondition. Established at
1202            // `borrowed_in` (debug-asserted) by the decoder's preceding EOF
1203            // check, and at `borrowed` by `len = field.len()`.
1204            WirePayloadRepr::Borrowed { chunk, len } => unsafe { validate_str_in(chunk, *len) },
1205            WirePayloadRepr::Owned(b) => validate_str(b),
1206        }
1207    }
1208
1209    /// Take ownership of the field's bytes as [`Bytes`].
1210    ///
1211    /// Zero-copy for an owned payload; a borrowed payload is copied. A
1212    /// [`ProtoBytes`] type that keeps this `Bytes` sets
1213    /// [`PREFERS_OWNED_PAYLOAD`](ProtoBytes::PREFERS_OWNED_PAYLOAD), so that
1214    /// the decoder hands it an owned payload. With the const at `false`, every
1215    /// contiguous field is copied here.
1216    #[inline]
1217    #[must_use]
1218    pub fn into_bytes(self) -> Bytes {
1219        match self.0 {
1220            WirePayloadRepr::Borrowed { chunk, len } => Bytes::copy_from_slice(&chunk[..len]),
1221            WirePayloadRepr::Owned(b) => b,
1222        }
1223    }
1224}
1225
1226/// Decode a length prefix and check it against the bytes left in `buf`.
1227///
1228/// # Errors
1229///
1230/// - [`DecodeError::UnexpectedEof`] if the buffer is shorter than the declared
1231///   length.
1232/// - [`DecodeError::MessageTooLarge`] if the declared length overflows `usize`.
1233#[inline]
1234fn read_payload_len(buf: &mut impl Buf) -> Result<usize, DecodeError> {
1235    let len = decode_varint(buf)?;
1236    let len = usize::try_from(len).map_err(|_| DecodeError::MessageTooLarge)?;
1237    if buf.remaining() < len {
1238        return Err(DecodeError::UnexpectedEof);
1239    }
1240    Ok(len)
1241}
1242
1243/// Pass the next `len` bytes of `buf` to `f` as a [`WirePayload`], advancing
1244/// `buf` past them. The caller guarantees `buf.remaining() >= len`.
1245///
1246/// When `prefer_owned` is false, the payload is `Borrowed` if the whole field
1247/// is contiguous in the current chunk (zero-copy), and `Owned` otherwise. When
1248/// it is true, the payload is always `Owned`. An `Owned` payload comes from
1249/// [`Buf::copy_to_bytes`], which shares the allocation of a `Bytes` input. `f`
1250/// returns an owned value, so its borrow of `buf` ends with the call.
1251///
1252/// On any error the `buf` cursor position is unspecified: a decode error aborts
1253/// the whole decode, so the buffer is not left in a recoverable state.
1254#[inline]
1255fn read_payload_of_len<R>(
1256    buf: &mut impl Buf,
1257    len: usize,
1258    prefer_owned: bool,
1259    f: impl FnOnce(WirePayload<'_>) -> Result<R, DecodeError>,
1260) -> Result<R, DecodeError> {
1261    let chunk = buf.chunk();
1262    if chunk.len() >= len && !prefer_owned {
1263        // Whole field is contiguous: hand over a borrowed payload carrying the
1264        // full remaining chunk (so `to_str` can take the slack-aware path).
1265        let r = f(WirePayload::borrowed_in(chunk, len))?;
1266        buf.advance(len);
1267        Ok(r)
1268    } else {
1269        // The field spans chunks, or the caller prefers an owned payload. An
1270        // empty field gets a fresh `Bytes`: splitting zero bytes off the end
1271        // of a `Bytes` input returns a handle that keeps the input allocated.
1272        let bytes = if len == 0 {
1273            Bytes::new()
1274        } else {
1275            buf.copy_to_bytes(len)
1276        };
1277        f(WirePayload::owned(bytes))
1278    }
1279}
1280
1281/// Pass the whole of a field payload bounded by `payload` to `f`, consuming it.
1282///
1283/// Reads through the underlying buffer so that a borrowed payload keeps the
1284/// surrounding chunk tail.
1285#[inline]
1286fn read_bounded_payload<B: Buf, R>(
1287    payload: &mut FieldPayload<B>,
1288    prefer_owned: bool,
1289    f: impl FnOnce(WirePayload<'_>) -> Result<R, DecodeError>,
1290) -> Result<R, DecodeError> {
1291    let len = payload.remaining();
1292    let r = read_payload_of_len(payload.inner.get_mut(), len, prefer_owned, f)?;
1293    payload.inner.set_limit(0);
1294    Ok(r)
1295}
1296
1297/// Read a field's length prefix, then hand exactly that many bytes to
1298/// `decode`. Bytes `decode` leaves unread are skipped, so `buf` always ends
1299/// after the field on success.
1300#[inline]
1301fn decode_length_delimited_with<T, B: Buf>(
1302    buf: &mut B,
1303    decode: impl FnOnce(&mut FieldPayload<&mut B>) -> Result<T, DecodeError>,
1304) -> Result<T, DecodeError> {
1305    let len = read_payload_len(buf)?;
1306    let mut payload = FieldPayload::new(buf, len);
1307    let value = decode(&mut payload)?;
1308    let unread = payload.remaining();
1309    payload.advance(unread);
1310    Ok(value)
1311}
1312
1313/// Compute the encoded byte count of a `string` value (varint length prefix +
1314/// UTF-8 byte count), excluding the field tag.
1315#[inline]
1316pub fn string_encoded_len(value: &str) -> usize {
1317    let len = value.len();
1318    varint_len(len as u64) + len
1319}
1320
1321/// The bound generated code places on the Rust type used for a proto `string`
1322/// field.
1323///
1324/// buffa implements it for the default [`String`]. Select another representation
1325/// with `buffa_build`'s `string_type` / `string_type_custom`. There is
1326/// intentionally **no blanket impl**, and a foreign type cannot implement this
1327/// trait (orphan rule) — wrap it in a local newtype that implements the trait;
1328/// see `examples/custom-types` in the buffa repository for the canonical
1329/// template (and `buffa-smolstr` in the same repository for a self-contained
1330/// `smol_str` newtype).
1331///
1332/// The bounds are exactly what generated code requires of a string field:
1333///
1334/// - `from_wire` (the required method, below) — the binary decode constructor.
1335/// - `Clone + PartialEq + Default + Debug` — for the `#[derive(...)]` and the
1336///   hand-written `Debug` impl on message structs, and for `clear()` (which
1337///   resets the field to [`Default`] rather than relying on a `String`-specific
1338///   `clear`, since a substituted type may be immutable).
1339/// - `Send + Sync` — so a message owning such a field stays `Send + Sync`;
1340///   without this bound an exotic string type could silently make every
1341///   containing message thread-unsafe.
1342/// - `Deref<Target = str>` and [`AsRef<str>`] — generated code borrows the field
1343///   as `&str` by plain reference coercion (`&self.field` where
1344///   [`encode_string`] / [`string_encoded_len`] expect `&str`), so the
1345///   representation must `Deref` to `str`; `AsRef<str>` is also required for the
1346///   call sites that ask for it explicitly.
1347/// - `From<String>` — constructs fields from owned JSON strings, text-format
1348///   parsing, and proto2 defaults.
1349/// - [`copy_from_str`](ProtoString::copy_from_str) — copies borrowed JSON
1350///   strings in non-optional singular fields, and the text of string view
1351///   fields of custom representations, into owned storage. Binary decoding uses
1352///   [`decode_length_delimited`](ProtoString::decode_length_delimited), whose
1353///   default calls [`from_wire`](ProtoString::from_wire).
1354///
1355/// For the default `String` representation every conversion is the identity, so
1356/// the generic path costs nothing relative to the specialized one.
1357///
1358/// # Contract
1359///
1360/// The bounds are structural and cannot capture these invariants; an
1361/// implementation must uphold them:
1362///
1363/// - `Default` is the empty string — generated `clear()` resets to
1364///   `Default::default()` and implicit-presence encoding skips empty values, so
1365///   a non-empty `Default` silently drops or corrupts cleared fields.
1366/// - `Deref`, `AsRef`, and the constructors observe the same content — encoding
1367///   borrows via `Deref` / `AsRef` and the view / reflect paths read the same
1368///   way; if they disagree, a value encodes differently than it reads back.
1369/// - `from_wire` and any `decode_length_delimited` override are
1370///   value-equivalent to `From<String>` / `copy_from_str` — binary decode uses
1371///   them while JSON / text / view→owned use the other
1372///   constructors, so a representation must not transform the text (e.g.
1373///   case-fold) in one path but not the other.
1374/// - `copy_from_str(s)` is value-equivalent to `From::from(s.to_owned())` — an
1375///   override exists only to skip the intermediate `String`, so it must not
1376///   change the resulting value.
1377///
1378/// # Limitations
1379///
1380/// The requirements below depend on where the custom string appears. See the user
1381/// guide's "String and bytes field representations" section for the full table.
1382///
1383/// - **Must be crate-local.** A custom type in a `repeated` element or `map`
1384///   slot needs codegen-emitted `ReflectElement` / `ReflectMapKey` impls (for
1385///   vtable reflection), which the orphan rule permits only when the type is
1386///   local to the generating crate. A *foreign* custom type in those positions
1387///   fails to compile — wrap it in a crate-local newtype.
1388/// - **JSON needs native `serde` outside non-optional singular fields.** A custom
1389///   string in an optional, repeated, map, or oneof field uses its own `serde`,
1390///   so it must implement
1391///   `Serialize` / `Deserialize` (and, for an external type, enable its `serde`
1392///   feature). Non-optional singular custom strings use the `proto_string`
1393///   with-module and need no `serde` impl.
1394/// - **A `map` key needs `Hash + Eq`** (default / `HashMap` container) or `Ord`
1395///   (`map_type(BTreeMap)`); the bound is enforced at the generated field type.
1396/// - **No `Arbitrary` impl required.** Under `generate_arbitrary`, codegen
1397///   attaches a generic builder to a custom string field, and to a `map` field
1398///   with a custom string key or value.
1399#[rustversion::attr(
1400    since(1.78),
1401    diagnostic::on_unimplemented(
1402        message = "`{Self}` cannot be used as a buffa custom string type",
1403        note = "Implement `ProtoString` and its supertraits on your type. \
1404                If the type is defined in another crate, wrap it in a crate-local newtype first. \
1405                See `examples/custom-types` in the buffa repository for a template."
1406    )
1407)]
1408pub trait ProtoString:
1409    Clone
1410    + PartialEq
1411    + Default
1412    + core::fmt::Debug
1413    + Send
1414    + Sync
1415    + core::ops::Deref<Target = str>
1416    + AsRef<str>
1417    + From<String>
1418{
1419    /// Copy text into storage that does not borrow from `value`.
1420    ///
1421    /// The default constructs a [`String`] and passes it to `From<String>`.
1422    /// Unlike `From<&str>`, this method does not tie the result's lifetime to
1423    /// the input, so a type can retain a separate borrowing `From<&str>`
1424    /// implementation.
1425    ///
1426    /// Override it if the type stores short strings inline or shares them. The
1427    /// default cannot call `From<&str>`, so a type with a cheaper
1428    /// borrowed-text constructor that does not override this method pays the
1429    /// intermediate `String` allocation wherever generated code copies borrowed
1430    /// text: view-to-owned conversion of singular, optional, repeated, map and
1431    /// oneof string fields, and JSON deserialization of non-optional singular
1432    /// fields. The values are unchanged; only the cost differs.
1433    /// `#[derive(buffa_remote_derive::ProtoString)]` forwards this method to
1434    /// the remote type's `From<&str>`, so derived types are already covered.
1435    #[inline]
1436    fn copy_from_str(value: &str) -> Self {
1437        Self::from(String::from(value))
1438    }
1439
1440    /// Construct the representation from a decoded `string` field's wire payload.
1441    ///
1442    /// This is the decode constructor: it owns the validation/ownership choice,
1443    /// so a representation can borrow-and-inline a short string (no transient
1444    /// heap allocation) or validate UTF-8 only when it must. Validate-and-borrow
1445    /// with [`WirePayload::to_str`] (which uses buffa's UTF-8 validator and so
1446    /// picks up the `fast-utf8` feature), or read raw bytes with
1447    /// [`WirePayload::as_slice`]. There is
1448    /// intentionally no blanket impl — every representation provides its own
1449    /// optimal `from_wire`; `From<String>` and [`Self::copy_from_str`] remain
1450    /// for ordinary JSON, text, and view→owned paths. Selected JSON policies
1451    /// call their policy deserializer, and guarded arbitrary construction calls
1452    /// `from_wire` directly with borrowed input. Binary decode calls `from_wire`
1453    /// through the default
1454    /// [`decode_length_delimited`](Self::decode_length_delimited); a type that
1455    /// overrides that method still provides `from_wire` for direct callers.
1456    ///
1457    /// # Errors
1458    ///
1459    /// Returns [`DecodeError::InvalidUtf8`] if the payload is not valid UTF-8. A
1460    /// representation that enforces additional invariants can reject the value
1461    /// with [`DecodeError::Custom`] (carrying a static reason), or return any
1462    /// other [`DecodeError`] variant.
1463    fn from_wire(payload: WirePayload<'_>) -> Result<Self, DecodeError>;
1464
1465    /// Decode one field payload, given exactly the bytes of that field.
1466    ///
1467    /// Generated code and [`decode_string_to`] call this after reading the field's length
1468    /// prefix and checking it against the input, so `payload` holds exactly
1469    /// that field and `payload.remaining()` is its validated length. The
1470    /// default passes a [`WirePayload`] to [`Self::from_wire`].
1471    /// Override it when the representation must also control temporary
1472    /// allocations, for example to copy a fragmented field straight into
1473    /// storage that is wiped on drop rather than through an intermediate
1474    /// [`Bytes`].
1475    ///
1476    /// An override must accept and reject exactly the payloads that
1477    /// `from_wire` does, including rejecting invalid UTF-8, and produce an equal value. Bytes it leaves
1478    /// unread are skipped. The opaque [`FieldPayload`] exposes only bounded
1479    /// [`Buf`] operations; its limit and underlying buffer cannot be accessed.
1480    ///
1481    /// # Errors
1482    ///
1483    /// Returns the representation's error for a rejected payload. On error
1484    /// the input position is unspecified: a decode error aborts the whole
1485    /// decode.
1486    fn decode_length_delimited(payload: &mut FieldPayload<impl Buf>) -> Result<Self, DecodeError> {
1487        read_bounded_payload(payload, false, Self::from_wire)
1488    }
1489}
1490
1491impl ProtoString for String {
1492    #[inline]
1493    fn from_wire(payload: WirePayload<'_>) -> Result<Self, DecodeError> {
1494        payload.to_str().map(alloc::borrow::ToOwned::to_owned)
1495    }
1496}
1497
1498// The default representation must always satisfy the bound; freeze that
1499// invariant against future changes to the trait's supertraits.
1500const _: fn() = || {
1501    fn assert_proto_string<S: ProtoString>() {}
1502    assert_proto_string::<String>();
1503};
1504
1505/// Decode a length-delimited `string` into a configurable [`ProtoString`] type
1506/// by dispatching to [`ProtoString::decode_length_delimited`].
1507///
1508/// The default hook hands a wire payload to `from_wire`, which decides
1509/// validation and borrow-vs-own, so an
1510/// inline-capable type avoids the transient `String` allocation that a
1511/// `From<String>` path would force. Generated code uses the in-place
1512/// [`merge_string`] for default `String` fields (allocation reuse) and this
1513/// helper for every other [`ProtoString`] type.
1514///
1515/// # Errors
1516///
1517/// - [`DecodeError::UnexpectedEof`] if the buffer is shorter than the declared
1518///   length.
1519/// - [`DecodeError::MessageTooLarge`] if the declared length overflows `usize`.
1520/// - [`DecodeError::InvalidUtf8`] (or another error) as returned by the
1521///   representation's [`from_wire`](ProtoString::from_wire).
1522#[inline]
1523pub fn decode_string_to<S: ProtoString>(buf: &mut impl Buf) -> Result<S, DecodeError> {
1524    decode_length_delimited_with(buf, |payload| S::decode_length_delimited(payload))
1525}
1526
1527/// Encode a `bytes` value as a varint length prefix followed by raw bytes
1528/// (wire type 2).
1529#[inline]
1530pub fn encode_bytes(value: &[u8], buf: &mut impl EncodeSink) {
1531    encode_varint(value.len() as u64, buf);
1532    buf.put_slice(value);
1533}
1534
1535/// Decode a `bytes` value: read a varint length prefix, then that many bytes.
1536///
1537/// See also [`decode_bytes_to_bytes`] for a [`Bytes`]-returning variant that
1538/// is zero-copy when `buf` is itself `Bytes`-backed.
1539///
1540/// # Errors
1541///
1542/// - [`DecodeError::UnexpectedEof`] if the buffer has fewer bytes than the
1543///   declared length.
1544/// - [`DecodeError::MessageTooLarge`] if the declared length overflows `usize`.
1545///
1546/// # Panics
1547///
1548/// If `buf.chunk()` returns an empty slice before `buf.remaining()` bytes have
1549/// been read — a `Buf` that violates its own contract.
1550#[inline]
1551pub fn decode_bytes(buf: &mut impl Buf) -> Result<Vec<u8>, DecodeError> {
1552    let len = decode_varint(buf)?;
1553    let len = usize::try_from(len).map_err(|_| DecodeError::MessageTooLarge)?;
1554    if buf.remaining() < len {
1555        return Err(DecodeError::UnexpectedEof);
1556    }
1557    let mut bytes = Vec::with_capacity(len);
1558    copy_into_spare(buf, &mut bytes, len);
1559    Ok(bytes)
1560}
1561
1562/// Decode a `bytes` value into a [`Bytes`]: read a varint length prefix,
1563/// then take that many bytes via [`Buf::copy_to_bytes`].
1564///
1565/// When `buf` is itself backed by [`Bytes`], `copy_to_bytes` is a zero-copy
1566/// refcount bump (via `split_to`); for `&[u8]` and other inputs it falls
1567/// back to an allocation + copy, equivalent to wrapping [`decode_bytes`] in
1568/// `Bytes::from`.
1569///
1570/// # Memory retention
1571///
1572/// In the zero-copy case the returned `Bytes` aliases the source allocation,
1573/// so the entire source buffer is retained until every aliased `Bytes`
1574/// drops. To detach a field from a large source buffer, deep-copy it with
1575/// `Bytes::copy_from_slice(&field)`.
1576///
1577/// # Errors
1578///
1579/// - [`DecodeError::UnexpectedEof`] if the buffer has fewer bytes than the
1580///   declared length.
1581/// - [`DecodeError::MessageTooLarge`] if the declared length overflows `usize`.
1582#[inline]
1583pub fn decode_bytes_to_bytes(buf: &mut impl Buf) -> Result<Bytes, DecodeError> {
1584    let len = decode_varint(buf)?;
1585    let len = usize::try_from(len).map_err(|_| DecodeError::MessageTooLarge)?;
1586    if buf.remaining() < len {
1587        return Err(DecodeError::UnexpectedEof);
1588    }
1589    if len == 0 {
1590        // Splitting zero bytes off the end of a `Bytes` input returns a handle
1591        // that keeps the input allocated.
1592        return Ok(Bytes::new());
1593    }
1594    Ok(buf.copy_to_bytes(len))
1595}
1596
1597/// The bound generated code places on the Rust type used for a proto `bytes`
1598/// field.
1599///
1600/// buffa implements it for the default [`Vec<u8>`] and for
1601/// [`bytes::Bytes`](crate::bytes::Bytes) (which decodes zero-copy from a
1602/// `Bytes`-backed buffer). Select another representation with `buffa_build`'s
1603/// `bytes_type` / `bytes_type_custom`. There is intentionally **no blanket
1604/// impl**, and a foreign type cannot implement this trait (orphan rule) — wrap
1605/// it in a local newtype that implements the trait; see
1606/// `examples/custom-types` in the buffa repository for the canonical template.
1607///
1608/// This is the `bytes`-side twin of [`ProtoString`]; the bounds are exactly what
1609/// generated code requires of a `bytes` field:
1610///
1611/// - `from_wire` (the required method, below) — the binary decode constructor.
1612/// - `Clone + PartialEq + Default + Debug` — for the `#[derive(...)]` and the
1613///   hand-written `Debug` impl on message structs, and for `clear()` when the
1614///   field has no declared default (a substituted type may be immutable).
1615/// - `Send + Sync` — so a message owning such a field stays `Send + Sync`.
1616/// - `Deref<Target = [u8]>` and [`AsRef<[u8]>`](AsRef) — generated code
1617///   reads the field's bytes through these bounds: the size pass borrows
1618///   `&[u8]` where [`bytes_encoded_len`] expects it, and the write pass goes
1619///   through [`put_shared_bytes_field`] / [`AsSharedBytes`], whose blanket
1620///   impl reads via `AsRef<[u8]>`.
1621/// - `From<Vec<u8>>` — used by the JSON and view→owned paths, and by `Default`
1622///   and `clear()` to construct declared field defaults. Binary decode uses
1623///   [`decode_length_delimited`](ProtoBytes::decode_length_delimited) instead,
1624///   whose default calls [`from_wire`](ProtoBytes::from_wire). Note that `From<&[u8]>` is
1625///   deliberately *not* required: `bytes::Bytes` implements it only for
1626///   `&'static [u8]`, so requiring it would exclude `Bytes` itself.
1627///
1628/// For the default `Vec<u8>` representation every conversion is the identity, so
1629/// the generic path costs nothing relative to the specialized one.
1630///
1631/// # Contract
1632///
1633/// The bounds are structural and cannot capture these invariants; an
1634/// implementation must uphold them:
1635///
1636/// - `Default` is the empty value — generated `clear()` resets to
1637///   `Default::default()` and implicit-presence encoding skips empty values, so
1638///   a non-empty `Default` silently drops or corrupts cleared fields.
1639/// - `Deref`, `AsRef`, and the constructors observe the same content — encoding
1640///   borrows via `Deref` / `AsRef` and the view / reflect paths read the same
1641///   way; if they disagree, a value encodes differently than it reads back.
1642/// - `from_wire` and any `decode_length_delimited` override are
1643///   value-equivalent to `From<Vec<u8>>` — binary decode uses them while JSON / view→owned use `From`, so a representation must not
1644///   transform the bytes in one path but not the other.
1645///
1646/// # Limitations
1647///
1648/// - **`repeated` elements and `map<K, bytes>` values must be crate-local.** A
1649///   custom type used as the element of a `repeated` field — or as a
1650///   `map<K, bytes>` value — needs codegen-emitted `ReflectElement` (vtable) and
1651///   base64 `ProtoElemJson` (JSON) impls, which the orphan rule permits only when
1652///   the type is local to the generating crate. A *foreign* custom type in that
1653///   position fails to compile — wrap it in a crate-local newtype. Singular,
1654///   optional, and oneof uses work with a foreign type directly. (A custom
1655///   `bytes` map value is honored just like the built-in `bytes::Bytes`; only the
1656///   `map<bytes, bytes>` carve-out keeps `Vec<u8>` values.)
1657/// - **No `Arbitrary` impl required.** Under the `arbitrary` feature codegen
1658///   attaches a generic builder, so a custom type needs no native
1659///   `arbitrary::Arbitrary` impl.
1660#[rustversion::attr(
1661    since(1.78),
1662    diagnostic::on_unimplemented(
1663        message = "`{Self}` cannot be used as a buffa custom bytes type",
1664        note = "buffa owns `ProtoBytes`, so a foreign type can't implement it directly (orphan rule). \
1665                Wrap it in a crate-local newtype and implement `ProtoBytes` on the newtype. \
1666                See the `custom-types` example in the buffa repository for a template."
1667    )
1668)]
1669pub trait ProtoBytes:
1670    Clone
1671    + PartialEq
1672    + Default
1673    + core::fmt::Debug
1674    + Send
1675    + Sync
1676    + core::ops::Deref<Target = [u8]>
1677    + AsRef<[u8]>
1678    + From<Vec<u8>>
1679{
1680    /// Whether the default
1681    /// [`decode_length_delimited`](Self::decode_length_delimited) implementation hands
1682    /// [`from_wire`](Self::from_wire) an owned [`WirePayload`] for every field,
1683    /// including a field that is
1684    /// contiguous in the input.
1685    ///
1686    /// Set it to `true` for a type that keeps the [`Bytes`] from
1687    /// [`WirePayload::into_bytes`], such as a wrapper around `Bytes`. The
1688    /// decoder then takes each payload with [`Buf::copy_to_bytes`]: a `Bytes`
1689    /// input shares its allocation with the payload, while a `&[u8]` input,
1690    /// and a field that spans two chunks of a `Chain`, are copied.
1691    ///
1692    /// Leave it `false` for a type that copies the bytes from
1693    /// [`WirePayload::as_slice`], such as one that stores short values inline.
1694    /// With `true`, such a type copies twice from an input that cannot share:
1695    /// once into a temporary `Bytes` and once into the value.
1696    ///
1697    /// This const controls only the default decode implementation. `from_wire`
1698    /// still has to accept a borrowed payload, which any caller can build with
1699    /// [`WirePayload::borrowed`].
1700    ///
1701    /// # Memory retention
1702    ///
1703    /// A value that shares the input keeps the whole input buffer allocated
1704    /// until every `Bytes` that shares it, including each clone of the value,
1705    /// is dropped. To detach a value from a large input, replace it with a
1706    /// copy, for example `B::from(value.to_vec())`. Users of the type meet this
1707    /// cost, so repeat it in the type's own documentation.
1708    ///
1709    /// # Example
1710    ///
1711    /// A wrapper around `Bytes` that shares the input on decode, and that a
1712    /// segmented sink splices by reference count on encode:
1713    ///
1714    /// ```
1715    /// use buffa::bytes::Bytes;
1716    /// use buffa::types::{decode_bytes_to, encode_bytes, ProtoBytes, WirePayload};
1717    /// use buffa::DecodeError;
1718    ///
1719    /// #[derive(Clone, Debug, Default, PartialEq)]
1720    /// struct Shared(Bytes);
1721    ///
1722    /// impl core::ops::Deref for Shared {
1723    ///     type Target = [u8];
1724    ///     fn deref(&self) -> &[u8] {
1725    ///         &self.0
1726    ///     }
1727    /// }
1728    /// impl AsRef<[u8]> for Shared {
1729    ///     fn as_ref(&self) -> &[u8] {
1730    ///         &self.0
1731    ///     }
1732    /// }
1733    /// impl From<Vec<u8>> for Shared {
1734    ///     fn from(bytes: Vec<u8>) -> Self {
1735    ///         Self(Bytes::from(bytes))
1736    ///     }
1737    /// }
1738    /// impl ProtoBytes for Shared {
1739    ///     const PREFERS_OWNED_PAYLOAD: bool = true;
1740    ///
1741    ///     fn from_wire(payload: WirePayload<'_>) -> Result<Self, DecodeError> {
1742    ///         Ok(Self(payload.into_bytes()))
1743    ///     }
1744    ///
1745    ///     fn as_shared(&self) -> Option<Bytes> {
1746    ///         Some(self.0.clone())
1747    ///     }
1748    /// }
1749    ///
1750    /// let mut wire = Vec::new();
1751    /// encode_bytes(b"payload", &mut wire);
1752    /// let mut input = Bytes::from(wire);
1753    /// let payload_start = input.as_ptr() as usize + 1; // after the length prefix
1754    ///
1755    /// let value: Shared = decode_bytes_to(&mut input)?;
1756    /// assert_eq!(&value[..], b"payload");
1757    /// // The value points into the input: decoding copied no bytes.
1758    /// assert_eq!(value.0.as_ptr() as usize, payload_start);
1759    /// # Ok::<(), DecodeError>(())
1760    /// ```
1761    const PREFERS_OWNED_PAYLOAD: bool = false;
1762
1763    /// Construct the representation from a decoded `bytes` field's wire payload.
1764    ///
1765    /// The decode constructor: it chooses between borrowing the payload
1766    /// ([`WirePayload::as_slice`]) and taking ownership
1767    /// ([`WirePayload::into_bytes`]). A contiguous field arrives borrowed
1768    /// unless the type sets
1769    /// [`PREFERS_OWNED_PAYLOAD`](Self::PREFERS_OWNED_PAYLOAD).
1770    ///
1771    /// Binary decode calls `from_wire` through the default
1772    /// [`decode_length_delimited`](Self::decode_length_delimited). A type that
1773    /// overrides that method still provides `from_wire` for direct callers.
1774    /// The ordinary JSON, text format, view→owned conversion, declared field
1775    /// defaults and arbitrary paths use `From<Vec<u8>>`. Selected JSON policies
1776    /// use their policy deserializer, and guarded arbitrary construction calls
1777    /// `from_wire` directly with borrowed input.
1778    ///
1779    /// # Errors
1780    ///
1781    /// The built-in representations are infallible. A representation that
1782    /// enforces additional invariants (e.g. a fixed length) can reject the
1783    /// value with [`DecodeError::Custom`] (carrying a static reason), or return
1784    /// any other [`DecodeError`] variant.
1785    fn from_wire(payload: WirePayload<'_>) -> Result<Self, DecodeError>;
1786
1787    /// Decode one field payload, given exactly the bytes of that field.
1788    ///
1789    /// Generated code and [`decode_bytes_to`] call this after reading the field's length
1790    /// prefix and checking it against the input, so `payload` holds exactly
1791    /// that field and `payload.remaining()` is its validated length. The
1792    /// default passes a [`WirePayload`] to [`Self::from_wire`], honoring
1793    /// [`Self::PREFERS_OWNED_PAYLOAD`].
1794    /// Override it when the representation must also control temporary
1795    /// allocations, for example to copy a fragmented field straight into
1796    /// storage that is wiped on drop rather than through an intermediate
1797    /// [`Bytes`].
1798    ///
1799    /// An override must accept and reject exactly the payloads that
1800    /// `from_wire` does, and produce an equal value. Bytes it leaves
1801    /// unread are skipped. The opaque [`FieldPayload`] exposes only bounded
1802    /// [`Buf`] operations; its limit and underlying buffer cannot be accessed.
1803    ///
1804    /// # Errors
1805    ///
1806    /// Returns the representation's error for a rejected payload. On error
1807    /// the input position is unspecified: a decode error aborts the whole
1808    /// decode.
1809    ///
1810    /// # Example
1811    ///
1812    /// A representation that copies the field into one allocation of the
1813    /// field's exact size, also when the field spans input chunks:
1814    ///
1815    /// ```
1816    /// use buffa::bytes::Buf;
1817    /// use buffa::FieldPayload;
1818    /// use buffa::types::{decode_bytes_to, encode_bytes, ProtoBytes, WirePayload};
1819    /// use buffa::DecodeError;
1820    ///
1821    /// #[derive(Clone, Debug, Default, PartialEq)]
1822    /// struct Exact(Vec<u8>);
1823    ///
1824    /// impl core::ops::Deref for Exact {
1825    ///     type Target = [u8];
1826    ///     fn deref(&self) -> &[u8] {
1827    ///         &self.0
1828    ///     }
1829    /// }
1830    /// impl AsRef<[u8]> for Exact {
1831    ///     fn as_ref(&self) -> &[u8] {
1832    ///         &self.0
1833    ///     }
1834    /// }
1835    /// impl From<Vec<u8>> for Exact {
1836    ///     fn from(bytes: Vec<u8>) -> Self {
1837    ///         Self(bytes)
1838    ///     }
1839    /// }
1840    /// impl ProtoBytes for Exact {
1841    ///     fn from_wire(payload: WirePayload<'_>) -> Result<Self, DecodeError> {
1842    ///         Ok(Self(payload.as_slice().to_vec()))
1843    ///     }
1844    ///
1845    ///     fn decode_length_delimited(payload: &mut FieldPayload<impl Buf>) -> Result<Self, DecodeError> {
1846    ///         // The length is already checked against the input, so this
1847    ///         // reservation never exceeds the bytes actually present.
1848    ///         let mut out = Vec::with_capacity(payload.remaining());
1849    ///         while payload.has_remaining() {
1850    ///             let chunk = payload.chunk();
1851    ///             out.extend_from_slice(chunk);
1852    ///             let read = chunk.len();
1853    ///             payload.advance(read);
1854    ///         }
1855    ///         Ok(Self(out))
1856    ///     }
1857    /// }
1858    ///
1859    /// let mut wire = Vec::new();
1860    /// encode_bytes(b"payload", &mut wire);
1861    /// let (head, tail) = wire.split_at(3);
1862    /// let mut input = head.chain(tail);
1863    /// let value: Exact = decode_bytes_to(&mut input)?;
1864    /// assert_eq!(&value[..], b"payload");
1865    /// assert_eq!(value.0.capacity(), b"payload".len());
1866    /// # Ok::<(), DecodeError>(())
1867    /// ```
1868    fn decode_length_delimited(payload: &mut FieldPayload<impl Buf>) -> Result<Self, DecodeError> {
1869        read_bounded_payload(payload, Self::PREFERS_OWNED_PAYLOAD, Self::from_wire)
1870    }
1871
1872    /// The representation's bytes as a reference-counted [`Bytes`] handle,
1873    /// when one exists.
1874    ///
1875    /// This is the encode-side hook for segmented sinks: a representation
1876    /// that stores its bytes as (or can cheaply produce) a `Bytes` returns
1877    /// `Some`, letting [`put_shared_bytes_field`] splice the field into a
1878    /// [`Rope`](crate::Rope) by reference count.
1879    ///
1880    /// The default returns `None`, which means "copy me" — always correct.
1881    ///
1882    /// # Correctness
1883    ///
1884    /// The returned handle must view **exactly** the bytes of
1885    /// `self.as_ref()`. A violation (stale handle, different slicing, a
1886    /// reused scratch buffer) produces a corrupt encoding — and only when
1887    /// the sink is segmented: contiguous sinks never call the handle, so
1888    /// the bug is invisible in ordinary tests. Implementations overriding
1889    /// this method should test their encode path against a
1890    /// [`Rope`](crate::Rope) explicitly (a `debug_assert` in
1891    /// [`put_shared_bytes_field`] catches length mismatches, not aliasing).
1892    #[inline]
1893    fn as_shared(&self) -> Option<Bytes> {
1894        None
1895    }
1896}
1897
1898impl ProtoBytes for Vec<u8> {
1899    #[inline]
1900    fn from_wire(payload: WirePayload<'_>) -> Result<Self, DecodeError> {
1901        Ok(payload.as_slice().to_vec())
1902    }
1903}
1904
1905impl ProtoBytes for Bytes {
1906    const PREFERS_OWNED_PAYLOAD: bool = true;
1907
1908    #[inline]
1909    fn from_wire(payload: WirePayload<'_>) -> Result<Self, DecodeError> {
1910        Ok(payload.into_bytes())
1911    }
1912
1913    #[inline]
1914    fn as_shared(&self) -> Option<Bytes> {
1915        Some(self.clone())
1916    }
1917}
1918
1919// The two built-in representations must always satisfy the bound; freeze that
1920// invariant against future changes to the trait's supertraits.
1921const _: fn() = || {
1922    fn assert_proto_bytes<B: ProtoBytes>() {}
1923    assert_proto_bytes::<Vec<u8>>();
1924    assert_proto_bytes::<Bytes>();
1925};
1926
1927/// Decode a length-delimited `bytes` value into a configurable [`ProtoBytes`]
1928/// type.
1929///
1930/// This is the generic counterpart to [`decode_bytes`], dispatching to
1931/// [`ProtoBytes::decode_length_delimited`]. Its default hook hands the field's wire payload to
1932/// [`ProtoBytes::from_wire`]. Under that default, a contiguous payload is borrowed
1933/// unless `B` sets [`ProtoBytes::PREFERS_OWNED_PAYLOAD`], as `Bytes` does. With
1934/// the const set, the payload is an owned [`Bytes`] that shares a `Bytes`
1935/// input, and the value keeps that input allocated; see the const.
1936///
1937/// Generated code calls this function for custom [`ProtoBytes`] fields and map
1938/// values. `Vec<u8>` fields use [`merge_bytes`] (singular and optional fields,
1939/// which reuse the allocation) or [`decode_bytes`], and `bytes::Bytes` fields
1940/// use [`decode_bytes_to_bytes`].
1941///
1942/// # Errors
1943///
1944/// - [`DecodeError::UnexpectedEof`] if the buffer is shorter than the declared
1945///   length.
1946/// - [`DecodeError::MessageTooLarge`] if the declared length overflows `usize`.
1947/// - Any error returned by the representation's
1948///   [`from_wire`](ProtoBytes::from_wire).
1949#[inline]
1950pub fn decode_bytes_to<B: ProtoBytes>(buf: &mut impl Buf) -> Result<B, DecodeError> {
1951    decode_length_delimited_with(buf, |payload| B::decode_length_delimited(payload))
1952}
1953
1954// ---------------------------------------------------------------------------
1955// Pluggable repeated-field collections (ProtoList)
1956// ---------------------------------------------------------------------------
1957
1958/// The owned collection type backing a proto `repeated` field.
1959///
1960/// The default is [`Vec<T>`]; `buffa_build`'s `repeated_type_custom` knob
1961/// substitutes any type that implements `ProtoList<T>` — for example a
1962/// `SmallVec`-backed inline collection that avoids a heap allocation for short
1963/// repeated fields. The wire format is identical regardless of the collection;
1964/// only the in-memory owned type changes, and view types keep borrowing
1965/// `&[T]`.
1966///
1967/// There is intentionally no blanket impl — the built-in `Vec<T>` impl below is
1968/// the only one buffa provides. Because `ProtoList` is a buffa-owned trait, a
1969/// *foreign* collection (e.g. `smallvec::SmallVec`) cannot implement it
1970/// directly (orphan rule). Always wrap a foreign collection in a **crate-local
1971/// newtype** and implement `ProtoList` on the newtype, exactly like the
1972/// `ProtoString` newtype pattern (see `examples/custom-types` in the buffa
1973/// repository). This holds
1974/// even for binary-only builds — the generated decode/clear paths require
1975/// `Field: ProtoList`.
1976///
1977/// # Contract
1978///
1979/// - The collection must be **growable**: [`push`](Self::push) is infallible
1980///   (no `try_push`), so the decoder appends one element per wire element with
1981///   no way to reject an oversized field. A truly capacity-bounded collection
1982///   (e.g. a fixed-capacity `ArrayVec`) will **panic** on input larger than its
1983///   capacity rather than return a decode error — do not use one as a
1984///   `ProtoList`. `SmallVec` is fine because it spills to the heap.
1985/// - The supertraits and methods must agree on contents: `push` appends one
1986///   element in order, [`Deref<Target = [T]>`](core::ops::Deref) exposes the
1987///   elements as a slice in that same order (the encode and `compute_size`
1988///   paths iterate it), [`FromIterator`] rebuilds the collection for the
1989///   view→owned conversion, [`From<Vec<T>>`](From) is the ergonomic constructor
1990///   for building a field by hand (`vec![..].into()`, mirroring `ProtoBytes`'s
1991///   `From<Vec<u8>>`), and [`Default`] produces the empty collection (the
1992///   field's cleared state).
1993/// - A **generic** newtype's [`Default`] must be hand-written (not
1994///   `#[derive]`d), or the derive forces a spurious `T: Default` bound; expect a
1995///   `clippy::derivable_impls` lint there and `#[allow]` it (see the example).
1996///
1997/// # Limitations (for a *custom* collection)
1998///
1999/// - **Reflection / vtable:** a collection used under the reflection or vtable
2000///   path must implement `buffa_descriptor`'s `ReflectList`. It is not
2001///   derivable, but a `Vec`-backed newtype can delegate all three methods to
2002///   the inner `Vec<T>: ReflectList` impl (which requires `T: ReflectElement`).
2003/// - **JSON / connectrpc:** a collection used in a JSON-enabled build must
2004///   implement `serde::Serialize` / `Deserialize` (its own impls, or the
2005///   newtype's). Note that frameworks built on buffa may require the message's
2006///   serde derive unconditionally — for example `connectrpc` bounds its handler
2007///   and client message types on `Serialize` / `DeserializeOwned` even when JSON
2008///   is never used at runtime — so a custom collection used through such a
2009///   framework must be serde-capable regardless.
2010/// - **`arbitrary`:** under the `arbitrary` feature a collection must implement
2011///   `arbitrary::Arbitrary` (trivially derivable on a newtype). Not needed on
2012///   a field whose element is a custom string type or a non-default bytes
2013///   type: generated code builds that field through `From<Vec<T>>`.
2014///
2015/// # Examples
2016///
2017/// A minimal crate-local newtype wrapping `smallvec::SmallVec` for binary use:
2018///
2019/// ```rust,ignore
2020/// #[derive(Clone, PartialEq, Debug)]
2021/// pub struct SmallList<T>(pub smallvec::SmallVec<[T; 4]>);
2022///
2023/// // Hand-written so it does not require `T: Default`.
2024/// #[allow(clippy::derivable_impls)]
2025/// impl<T> Default for SmallList<T> {
2026///     fn default() -> Self { SmallList(smallvec::SmallVec::new()) }
2027/// }
2028/// impl<T> core::ops::Deref for SmallList<T> {
2029///     type Target = [T];
2030///     fn deref(&self) -> &[T] { &self.0 }
2031/// }
2032/// impl<T> FromIterator<T> for SmallList<T> {
2033///     fn from_iter<I: IntoIterator<Item = T>>(it: I) -> Self {
2034///         SmallList(smallvec::SmallVec::from_iter(it))
2035///     }
2036/// }
2037/// impl<T> From<Vec<T>> for SmallList<T> {        // enables `vec![..].into()`
2038///     fn from(v: Vec<T>) -> Self { SmallList(smallvec::SmallVec::from_vec(v)) }
2039/// }
2040/// impl<T: Clone + PartialEq + core::fmt::Debug + Send + Sync> buffa::ProtoList<T>
2041///     for SmallList<T>
2042/// {
2043///     fn push(&mut self, v: T) { self.0.push(v); }
2044///     fn clear(&mut self) { self.0.clear(); }
2045///     // reserve left as the advisory no-op default, so a byte-count hint
2046///     // never spills the inline storage.
2047/// }
2048/// ```
2049///
2050/// Then point a field at it: `repeated_type_custom("::my_crate::SmallList<*>")`.
2051#[rustversion::attr(
2052    since(1.78),
2053    diagnostic::on_unimplemented(
2054        message = "`{Self}` cannot be used as a buffa custom list type",
2055        note = "buffa owns `ProtoList`, so a foreign type can't implement it directly (orphan rule). \
2056                Wrap it in a crate-local newtype and implement `ProtoList` on the newtype. \
2057                See the `custom-types` example in the buffa repository for a template."
2058    )
2059)]
2060pub trait ProtoList<T>:
2061    Default
2062    + Clone
2063    + PartialEq
2064    + core::fmt::Debug
2065    + Send
2066    + Sync
2067    + FromIterator<T>
2068    + From<Vec<T>>
2069    + core::ops::Deref<Target = [T]>
2070{
2071    /// Append one decoded element to the end of the collection. Infallible —
2072    /// the collection must be growable (see the trait's `# Contract`).
2073    fn push(&mut self, value: T);
2074
2075    /// Remove all elements (the field's cleared / default state), retaining
2076    /// capacity where the underlying type allows.
2077    fn clear(&mut self);
2078
2079    /// Best-effort capacity hint from the packed-scalar decoder, sized in
2080    /// elements.
2081    ///
2082    /// This is **advisory**: the default implementation does nothing, so a
2083    /// bounded inline collection is never forced to pre-allocate (or spill its
2084    /// inline storage) from an attacker-influenced length prefix. The built-in
2085    /// `Vec<T>` impl overrides it to call [`Vec::reserve`]. The decoder invokes
2086    /// it through the trait (so an inherent `reserve` on the collection does not
2087    /// shadow this advisory contract); decoders may pass a loose upper bound, so
2088    /// never rely on the requested capacity being honored.
2089    #[inline]
2090    fn reserve(&mut self, additional: usize) {
2091        let _ = additional;
2092    }
2093}
2094
2095impl<T> ProtoList<T> for Vec<T>
2096where
2097    T: Clone + PartialEq + core::fmt::Debug + Send + Sync,
2098{
2099    #[inline]
2100    fn push(&mut self, value: T) {
2101        Vec::push(self, value);
2102    }
2103
2104    #[inline]
2105    fn clear(&mut self) {
2106        Vec::clear(self);
2107    }
2108
2109    #[inline]
2110    fn reserve(&mut self, additional: usize) {
2111        Vec::reserve(self, additional);
2112    }
2113}
2114
2115// The default representation must always satisfy the bound; freeze that
2116// invariant against future changes to the trait's supertraits.
2117const _: fn() = || {
2118    fn assert_proto_list<C: ProtoList<T>, T>() {}
2119    assert_proto_list::<Vec<u32>, u32>();
2120};
2121
2122/// Merge length-delimited bytes into an existing `Vec<u8>`, reusing its
2123/// heap allocation when possible.
2124///
2125/// Reads a varint length prefix, then that many bytes from `buf`, and
2126/// replaces the contents of `value` without deallocating its backing buffer
2127/// (provided the existing capacity is sufficient).
2128///
2129/// # Errors
2130///
2131/// - [`DecodeError::UnexpectedEof`] if the buffer has fewer bytes than the
2132///   declared length.
2133/// - [`DecodeError::MessageTooLarge`] if the declared length overflows `usize`.
2134///
2135/// # Panics
2136///
2137/// If `buf.chunk()` returns an empty slice before `buf.remaining()` bytes have
2138/// been read — a `Buf` that violates its own contract. `value` is left empty.
2139#[inline]
2140pub fn merge_bytes(value: &mut Vec<u8>, buf: &mut impl Buf) -> Result<(), DecodeError> {
2141    let len = decode_varint(buf)?;
2142    let len = usize::try_from(len).map_err(|_| DecodeError::MessageTooLarge)?;
2143    if buf.remaining() < len {
2144        return Err(DecodeError::UnexpectedEof);
2145    }
2146    value.clear();
2147    copy_into_spare(buf, value, len);
2148    Ok(())
2149}
2150
2151/// Compute the encoded byte count of a `bytes` value (varint length prefix +
2152/// byte count), excluding the field tag.
2153#[inline]
2154pub fn bytes_encoded_len(value: &[u8]) -> usize {
2155    let len = value.len();
2156    varint_len(len as u64) + len
2157}
2158
2159/// Borrow a `string` value directly from the input buffer (zero-copy).
2160///
2161/// Reads a varint length prefix, then borrows that many bytes from `buf` as a
2162/// `&'a str`. The returned slice shares the lifetime `'a` of the input buffer,
2163/// so no allocation is required.
2164///
2165/// # Errors
2166///
2167/// - [`DecodeError::UnexpectedEof`] if the buffer has fewer bytes than the
2168///   declared length.
2169/// - [`DecodeError::MessageTooLarge`] if the declared length overflows `usize`.
2170/// - [`DecodeError::InvalidUtf8`] if the bytes are not valid UTF-8.
2171#[inline]
2172pub fn borrow_str<'a>(buf: &mut &'a [u8]) -> Result<&'a str, DecodeError> {
2173    let len = decode_varint(buf)?;
2174    let len = usize::try_from(len).map_err(|_| DecodeError::MessageTooLarge)?;
2175    if buf.len() < len {
2176        return Err(DecodeError::UnexpectedEof);
2177    }
2178    // Validate against the surrounding slice (so the slack-buffer fast path
2179    // can read past `len` when the wire buffer continues), then advance the
2180    // cursor unconditionally — matching `decode_string` (which consumes the
2181    // bytes before validating them) and protobuf error-recovery
2182    // semantics: the field payload has been consumed regardless of whether
2183    // its contents were valid.
2184    //
2185    // SAFETY: `buf.len() >= len` was established by the EOF check above.
2186    let s = unsafe { validate_str_in(buf, len) };
2187    *buf = &buf[len..];
2188    s
2189}
2190
2191/// Borrow a `bytes` value directly from the input buffer (zero-copy).
2192///
2193/// Reads a varint length prefix, then borrows that many bytes from `buf` as a
2194/// `&'a [u8]`. The returned slice shares the lifetime `'a` of the input
2195/// buffer, so no allocation is required.
2196///
2197/// # Errors
2198///
2199/// - [`DecodeError::UnexpectedEof`] if the buffer has fewer bytes than the
2200///   declared length.
2201/// - [`DecodeError::MessageTooLarge`] if the declared length overflows `usize`.
2202#[inline]
2203pub fn borrow_bytes<'a>(buf: &mut &'a [u8]) -> Result<&'a [u8], DecodeError> {
2204    let len = decode_varint(buf)?;
2205    let len = usize::try_from(len).map_err(|_| DecodeError::MessageTooLarge)?;
2206    if buf.len() < len {
2207        return Err(DecodeError::UnexpectedEof);
2208    }
2209    let bytes = &buf[..len];
2210    *buf = &buf[len..];
2211    Ok(bytes)
2212}
2213
2214/// Borrows the raw bytes of a group body from `buf`.
2215///
2216/// The opening StartGroup tag has already been consumed by the caller.
2217/// This function scans forward, skipping nested fields, until the matching
2218/// EndGroup tag with `field_number` is found. Returns the sub-slice
2219/// containing the group body (excluding the EndGroup tag) and advances
2220/// `buf` past the EndGroup tag.
2221///
2222/// `depth` is the remaining nesting budget for fields *inside* the group
2223/// body (i.e. the same value passed to the inner view decoder). Nested
2224/// `StartGroup` fields encountered while scanning for the EndGroup tag
2225/// consume from this budget.
2226///
2227/// # Errors
2228///
2229/// - [`DecodeError::UnexpectedEof`] if the buffer ends before the EndGroup tag.
2230/// - [`DecodeError::InvalidEndGroup`] if an EndGroup with a mismatched field
2231///   number is encountered.
2232/// - [`DecodeError::RecursionLimitExceeded`] if a nested `StartGroup` inside
2233///   the body exceeds the `depth` budget.
2234pub fn borrow_group<'a>(
2235    buf: &mut &'a [u8],
2236    field_number: u32,
2237    depth: u32,
2238) -> Result<&'a [u8], DecodeError> {
2239    let start = *buf;
2240    // Scan forward to find the EndGroup tag, tracking how many bytes we consume.
2241    let mut scan: &[u8] = start;
2242    loop {
2243        if scan.is_empty() {
2244            return Err(DecodeError::UnexpectedEof);
2245        }
2246        // Remember position before decoding the tag so we can compute the
2247        // body length without recomputing the tag's encoded size.
2248        let before_tag = scan.len();
2249        let tag = crate::encoding::Tag::decode(&mut scan)?;
2250        if tag.wire_type() == crate::encoding::WireType::EndGroup {
2251            if tag.field_number() != field_number {
2252                return Err(DecodeError::InvalidEndGroup(tag.field_number()));
2253            }
2254            // The group body is everything from start up to (but not
2255            // including) the EndGroup tag we just decoded.
2256            let body_len = start.len() - before_tag;
2257            let body = &start[..body_len];
2258            *buf = scan;
2259            return Ok(body);
2260        }
2261        crate::encoding::skip_field_depth(tag, &mut scan, depth)?;
2262    }
2263}
2264
2265#[cfg(test)]
2266mod tests {
2267    use super::*;
2268
2269    #[derive(Clone, Default, PartialEq, Debug)]
2270    struct PayloadOwnership {
2271        bytes: Vec<u8>,
2272        was_owned: bool,
2273    }
2274
2275    impl core::ops::Deref for PayloadOwnership {
2276        type Target = [u8];
2277
2278        fn deref(&self) -> &[u8] {
2279            &self.bytes
2280        }
2281    }
2282
2283    impl AsRef<[u8]> for PayloadOwnership {
2284        fn as_ref(&self) -> &[u8] {
2285            &self.bytes
2286        }
2287    }
2288
2289    impl From<Vec<u8>> for PayloadOwnership {
2290        fn from(bytes: Vec<u8>) -> Self {
2291            Self {
2292                bytes,
2293                was_owned: false,
2294            }
2295        }
2296    }
2297
2298    impl ProtoBytes for PayloadOwnership {
2299        fn from_wire(payload: WirePayload<'_>) -> Result<Self, DecodeError> {
2300            Ok(Self {
2301                bytes: payload.as_slice().to_vec(),
2302                was_owned: payload.is_owned(),
2303            })
2304        }
2305    }
2306
2307    #[derive(Clone, Default, PartialEq, Debug)]
2308    struct SharedBytes(Bytes);
2309
2310    impl core::ops::Deref for SharedBytes {
2311        type Target = [u8];
2312
2313        fn deref(&self) -> &[u8] {
2314            &self.0
2315        }
2316    }
2317
2318    impl AsRef<[u8]> for SharedBytes {
2319        fn as_ref(&self) -> &[u8] {
2320            &self.0
2321        }
2322    }
2323
2324    impl From<Vec<u8>> for SharedBytes {
2325        fn from(bytes: Vec<u8>) -> Self {
2326            Self(Bytes::from(bytes))
2327        }
2328    }
2329
2330    impl ProtoBytes for SharedBytes {
2331        const PREFERS_OWNED_PAYLOAD: bool = true;
2332
2333        fn from_wire(payload: WirePayload<'_>) -> Result<Self, DecodeError> {
2334            Ok(Self(payload.into_bytes()))
2335        }
2336    }
2337
2338    // ── UTF-8 validation shims ────────────────────────────────────────────
2339
2340    #[test]
2341    fn validate_str_accepts_valid_rejects_invalid() {
2342        assert_eq!(validate_str(b"hello").unwrap(), "hello");
2343        assert_eq!(validate_str("héllo 🌍".as_bytes()).unwrap(), "héllo 🌍");
2344        assert_eq!(validate_str(b""), Ok(""));
2345        assert!(matches!(
2346            validate_str(&[0xC0, 0x80]), // overlong NUL
2347            Err(DecodeError::InvalidUtf8)
2348        ));
2349    }
2350
2351    #[test]
2352    fn validate_str_in_slack_and_tail_paths_agree() {
2353        // SAFETY: every call below has `len <= buf.len()`.
2354        unsafe {
2355            // 8-byte slack after the field → takes the slack-buffer fast path.
2356            let with_slack = b"hello\x00\x00\x00\x00\x00\x00\x00\x00";
2357            assert_eq!(validate_str_in(with_slack, 5).unwrap(), "hello");
2358            // No slack (field fills the buffer) → safe fallback.
2359            assert_eq!(validate_str_in(b"hello", 5).unwrap(), "hello");
2360            // Invalid input rejected on both paths.
2361            let bad_with_slack = b"\xC0\x80padpadpa";
2362            assert!(matches!(
2363                validate_str_in(bad_with_slack, 2),
2364                Err(DecodeError::InvalidUtf8)
2365            ));
2366            assert!(matches!(
2367                validate_str_in(&[0xC0, 0x80], 2),
2368                Err(DecodeError::InvalidUtf8)
2369            ));
2370            // Slack region is *not* validated: trailing junk past `len` is ignored.
2371            let junk_slack = b"ok\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF";
2372            assert_eq!(validate_str_in(junk_slack, 2).unwrap(), "ok");
2373        }
2374    }
2375
2376    #[test]
2377    fn borrow_str_uses_surrounding_buffer_for_slack() {
2378        // Two length-delimited string fields back-to-back: the first has the
2379        // second's bytes as slack, the second falls back to the safe path.
2380        let mut wire = alloc::vec::Vec::new();
2381        for s in ["hi", "tail-no-slack"] {
2382            wire.push(s.len() as u8);
2383            wire.extend_from_slice(s.as_bytes());
2384        }
2385        let mut cur: &[u8] = &wire;
2386        assert_eq!(borrow_str(&mut cur).unwrap(), "hi");
2387        assert_eq!(borrow_str(&mut cur).unwrap(), "tail-no-slack");
2388        assert!(cur.is_empty());
2389    }
2390
2391    #[test]
2392    fn wire_payload_to_str() {
2393        assert_eq!(WirePayload::borrowed(b"abc").to_str().unwrap(), "abc");
2394        assert!(matches!(
2395            WirePayload::borrowed(&[0xFF]).to_str(),
2396            Err(DecodeError::InvalidUtf8)
2397        ));
2398        // Decoder-constructed payload with surrounding tail: `to_str` reaches
2399        // `validate_str_in` and the tail is excluded from the result.
2400        let wire = b"abc\x00\x00\x00\x00\x00\x00\x00\x00trailing";
2401        assert_eq!(WirePayload::borrowed_in(wire, 3).to_str().unwrap(), "abc");
2402        assert_eq!(WirePayload::borrowed_in(wire, 3).as_slice(), b"abc");
2403        assert_eq!(WirePayload::borrowed_in(wire, 3).len(), 3);
2404        // Tail bytes after an invalid field don't rescue it.
2405        assert!(matches!(
2406            WirePayload::borrowed_in(b"\xFFtailtailtail", 1).to_str(),
2407            Err(DecodeError::InvalidUtf8)
2408        ));
2409        // Owned path is unchanged.
2410        let p = WirePayload::owned(Bytes::from_static(b"hi"));
2411        assert_eq!(p.to_str().unwrap(), "hi");
2412        assert!(p.is_owned());
2413        assert!(!WirePayload::borrowed(b"hi").is_owned());
2414        assert!(WirePayload::borrowed(b"").is_empty());
2415        // Debug never prints the surrounding tail.
2416        let dbg = alloc::format!("{:?}", WirePayload::borrowed_in(wire, 3));
2417        assert!(dbg.contains("[97, 98, 99]"), "{dbg}");
2418        assert!(!dbg.contains("trailing"), "{dbg}");
2419    }
2420
2421    /// A custom string representation that enforces an extra invariant in
2422    /// `from_wire`, to prove a representation can surface `DecodeError::Custom`
2423    /// through `decode_string_to`.
2424    #[derive(Clone, PartialEq, Default, Debug)]
2425    struct Tiny(alloc::string::String);
2426    impl core::ops::Deref for Tiny {
2427        type Target = str;
2428        fn deref(&self) -> &str {
2429            &self.0
2430        }
2431    }
2432    impl AsRef<str> for Tiny {
2433        fn as_ref(&self) -> &str {
2434            &self.0
2435        }
2436    }
2437    impl From<alloc::string::String> for Tiny {
2438        fn from(s: alloc::string::String) -> Self {
2439            Tiny(s)
2440        }
2441    }
2442    impl From<&str> for Tiny {
2443        fn from(s: &str) -> Self {
2444            Tiny(s.into())
2445        }
2446    }
2447    impl ProtoString for Tiny {
2448        fn from_wire(p: WirePayload<'_>) -> Result<Self, DecodeError> {
2449            let s = core::str::from_utf8(p.as_slice()).map_err(|_| DecodeError::InvalidUtf8)?;
2450            if s.len() > 3 {
2451                return Err(DecodeError::Custom("string too long"));
2452            }
2453            Ok(Tiny(s.into()))
2454        }
2455    }
2456
2457    #[test]
2458    fn from_wire_can_surface_custom_decode_error() {
2459        // Length-delimited "hello" (len 5) — rejected by Tiny's from_wire.
2460        let mut buf: &[u8] = b"\x05hello";
2461        assert_eq!(
2462            decode_string_to::<Tiny>(&mut buf).unwrap_err(),
2463            DecodeError::Custom("string too long"),
2464        );
2465        // A value within the limit decodes normally.
2466        let mut ok: &[u8] = b"\x02hi";
2467        assert_eq!(
2468            decode_string_to::<Tiny>(&mut ok).unwrap(),
2469            Tiny("hi".into())
2470        );
2471    }
2472
2473    /// Each fused writer must emit exactly tag-then-payload.
2474    #[test]
2475    fn put_field_fns_match_tag_plus_encode() {
2476        macro_rules! check {
2477            ($put:ident, $encode:ident, $wire:expr, $value:expr) => {{
2478                let mut fused = Vec::new();
2479                $put(7, $value, &mut fused);
2480                let mut split = Vec::new();
2481                Tag::new(7, $wire).encode(&mut split);
2482                $encode($value, &mut split);
2483                assert_eq!(fused, split, stringify!($put));
2484            }};
2485        }
2486        check!(put_int32_field, encode_int32, WireType::Varint, -5i32);
2487        check!(put_int64_field, encode_int64, WireType::Varint, -5i64);
2488        check!(put_uint32_field, encode_uint32, WireType::Varint, 300u32);
2489        check!(put_uint64_field, encode_uint64, WireType::Varint, 300u64);
2490        check!(put_sint32_field, encode_sint32, WireType::Varint, -5i32);
2491        check!(put_sint64_field, encode_sint64, WireType::Varint, -5i64);
2492        check!(put_bool_field, encode_bool, WireType::Varint, true);
2493        check!(put_fixed32_field, encode_fixed32, WireType::Fixed32, 9u32);
2494        check!(put_fixed64_field, encode_fixed64, WireType::Fixed64, 9u64);
2495        check!(
2496            put_sfixed32_field,
2497            encode_sfixed32,
2498            WireType::Fixed32,
2499            -9i32
2500        );
2501        check!(
2502            put_sfixed64_field,
2503            encode_sfixed64,
2504            WireType::Fixed64,
2505            -9i64
2506        );
2507        check!(put_float_field, encode_float, WireType::Fixed32, 1.5f32);
2508        check!(put_double_field, encode_double, WireType::Fixed64, 1.5f64);
2509        check!(
2510            put_string_field,
2511            encode_string,
2512            WireType::LengthDelimited,
2513            "hi"
2514        );
2515        check!(
2516            put_bytes_field,
2517            encode_bytes,
2518            WireType::LengthDelimited,
2519            &[1u8, 2][..]
2520        );
2521    }
2522
2523    #[test]
2524    fn put_len_delimited_header_and_group_tags() {
2525        let mut fused = Vec::new();
2526        put_len_delimited_header(3, 5, &mut fused);
2527        let mut split = Vec::new();
2528        Tag::new(3, WireType::LengthDelimited).encode(&mut split);
2529        encode_varint(5, &mut split);
2530        assert_eq!(fused, split);
2531
2532        let mut fused = Vec::new();
2533        put_group_start(4, &mut fused);
2534        put_group_end(4, &mut fused);
2535        let mut split = Vec::new();
2536        Tag::new(4, WireType::StartGroup).encode(&mut split);
2537        Tag::new(4, WireType::EndGroup).encode(&mut split);
2538        assert_eq!(fused, split);
2539    }
2540
2541    // -----------------------------------------------------------------------
2542    // ZigZag tests
2543    // -----------------------------------------------------------------------
2544
2545    #[test]
2546    fn test_zigzag_i32() {
2547        // Table from the spec:
2548        // https://protobuf.dev/programming-guides/encoding/#signed-ints
2549        assert_eq!(zigzag_encode_i32(0), 0);
2550        assert_eq!(zigzag_encode_i32(-1), 1);
2551        assert_eq!(zigzag_encode_i32(1), 2);
2552        assert_eq!(zigzag_encode_i32(-2), 3);
2553        assert_eq!(zigzag_encode_i32(2147483647), 4294967294);
2554        assert_eq!(zigzag_encode_i32(-2147483648), 4294967295);
2555
2556        for v in [0, -1, 1, -2, 2, i32::MAX, i32::MIN] {
2557            assert_eq!(zigzag_decode_i32(zigzag_encode_i32(v)), v);
2558        }
2559    }
2560
2561    #[test]
2562    fn test_zigzag_i64() {
2563        assert_eq!(zigzag_encode_i64(0), 0);
2564        assert_eq!(zigzag_encode_i64(-1), 1);
2565        assert_eq!(zigzag_encode_i64(1), 2);
2566        assert_eq!(zigzag_encode_i64(-2), 3);
2567
2568        for v in [0, -1, 1, -2, 2, i64::MAX, i64::MIN] {
2569            assert_eq!(zigzag_decode_i64(zigzag_encode_i64(v)), v);
2570        }
2571    }
2572
2573    // -----------------------------------------------------------------------
2574    // Float (32-bit IEEE 754) tests
2575    // -----------------------------------------------------------------------
2576
2577    #[test]
2578    fn test_float_roundtrip() {
2579        let values: &[f32] = &[
2580            0.0,
2581            -0.0,
2582            1.0,
2583            -1.0,
2584            f32::MIN,
2585            f32::MAX,
2586            f32::MIN_POSITIVE,
2587            f32::EPSILON,
2588            f32::INFINITY,
2589            f32::NEG_INFINITY,
2590            core::f32::consts::PI,
2591            1.0e-38, // near subnormal boundary
2592            1.0e38,  // large value
2593        ];
2594        for &v in values {
2595            let mut buf = Vec::new();
2596            encode_float(v, &mut buf);
2597            assert_eq!(buf.len(), 4, "float should encode to exactly 4 bytes");
2598            let decoded = decode_float(&mut buf.as_slice()).unwrap();
2599            assert_eq!(
2600                v.to_bits(),
2601                decoded.to_bits(),
2602                "bit-exact roundtrip for {v}"
2603            );
2604        }
2605    }
2606
2607    #[test]
2608    fn test_float_nan_roundtrip() {
2609        // NaN must round-trip with the same bit pattern.
2610        let nan = f32::NAN;
2611        let mut buf = Vec::new();
2612        encode_float(nan, &mut buf);
2613        let decoded = decode_float(&mut buf.as_slice()).unwrap();
2614        assert!(decoded.is_nan());
2615        assert_eq!(nan.to_bits(), decoded.to_bits());
2616    }
2617
2618    #[test]
2619    fn test_float_little_endian() {
2620        // 1.0f32 = 0x3F800000 in IEEE 754.
2621        // Little-endian: [0x00, 0x00, 0x80, 0x3F]
2622        let mut buf = Vec::new();
2623        encode_float(1.0, &mut buf);
2624        assert_eq!(buf, &[0x00, 0x00, 0x80, 0x3F]);
2625    }
2626
2627    #[test]
2628    fn test_float_decode_truncated() {
2629        let buf: &[u8] = &[0x00, 0x00, 0x80]; // only 3 bytes
2630        let result = decode_float(&mut &buf[..]);
2631        assert!(result.is_err());
2632    }
2633
2634    // -----------------------------------------------------------------------
2635    // Double (64-bit IEEE 754) tests
2636    // -----------------------------------------------------------------------
2637
2638    #[test]
2639    fn test_double_roundtrip() {
2640        let values: &[f64] = &[
2641            0.0,
2642            -0.0,
2643            1.0,
2644            -1.0,
2645            f64::MIN,
2646            f64::MAX,
2647            f64::MIN_POSITIVE,
2648            f64::EPSILON,
2649            f64::INFINITY,
2650            f64::NEG_INFINITY,
2651            core::f64::consts::PI,
2652            1.0e-307, // near subnormal boundary
2653            1.0e308,  // large value
2654        ];
2655        for &v in values {
2656            let mut buf = Vec::new();
2657            encode_double(v, &mut buf);
2658            assert_eq!(buf.len(), 8, "double should encode to exactly 8 bytes");
2659            let decoded = decode_double(&mut buf.as_slice()).unwrap();
2660            assert_eq!(
2661                v.to_bits(),
2662                decoded.to_bits(),
2663                "bit-exact roundtrip for {v}"
2664            );
2665        }
2666    }
2667
2668    #[test]
2669    fn test_double_nan_roundtrip() {
2670        let nan = f64::NAN;
2671        let mut buf = Vec::new();
2672        encode_double(nan, &mut buf);
2673        let decoded = decode_double(&mut buf.as_slice()).unwrap();
2674        assert!(decoded.is_nan());
2675        assert_eq!(nan.to_bits(), decoded.to_bits());
2676    }
2677
2678    #[test]
2679    fn test_double_little_endian() {
2680        // 1.0f64 = 0x3FF0000000000000 in IEEE 754.
2681        // Little-endian: [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xF0, 0x3F]
2682        let mut buf = Vec::new();
2683        encode_double(1.0, &mut buf);
2684        assert_eq!(buf, &[0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xF0, 0x3F]);
2685    }
2686
2687    #[test]
2688    fn test_double_decode_truncated() {
2689        let buf: &[u8] = &[0x00; 7]; // only 7 bytes
2690        let result = decode_double(&mut &buf[..]);
2691        assert!(result.is_err());
2692    }
2693
2694    // -----------------------------------------------------------------------
2695    // fixed32 / sfixed32 tests
2696    // -----------------------------------------------------------------------
2697
2698    #[test]
2699    fn test_fixed32_roundtrip() {
2700        let values: &[u32] = &[0, 1, 255, 256, 65535, u32::MAX, 0xDEAD_BEEF];
2701        for &v in values {
2702            let mut buf = Vec::new();
2703            encode_fixed32(v, &mut buf);
2704            assert_eq!(buf.len(), 4);
2705            let decoded = decode_fixed32(&mut buf.as_slice()).unwrap();
2706            assert_eq!(v, decoded);
2707        }
2708    }
2709
2710    #[test]
2711    fn test_fixed32_little_endian() {
2712        let mut buf = Vec::new();
2713        encode_fixed32(0x01020304, &mut buf);
2714        assert_eq!(buf, &[0x04, 0x03, 0x02, 0x01]);
2715    }
2716
2717    #[test]
2718    fn test_sfixed32_roundtrip() {
2719        let values: &[i32] = &[0, 1, -1, 127, -128, i32::MAX, i32::MIN, 0x7FFF_FFFF];
2720        for &v in values {
2721            let mut buf = Vec::new();
2722            encode_sfixed32(v, &mut buf);
2723            assert_eq!(buf.len(), 4);
2724            let decoded = decode_sfixed32(&mut buf.as_slice()).unwrap();
2725            assert_eq!(v, decoded);
2726        }
2727    }
2728
2729    #[test]
2730    fn test_sfixed32_negative_encoding() {
2731        // -1i32 is 0xFFFFFFFF in two's complement.
2732        // Little-endian: [0xFF, 0xFF, 0xFF, 0xFF]
2733        let mut buf = Vec::new();
2734        encode_sfixed32(-1, &mut buf);
2735        assert_eq!(buf, &[0xFF, 0xFF, 0xFF, 0xFF]);
2736    }
2737
2738    #[test]
2739    fn test_fixed32_decode_truncated() {
2740        let result = decode_fixed32(&mut &[0x01, 0x02, 0x03][..]);
2741        assert!(result.is_err());
2742    }
2743
2744    // -----------------------------------------------------------------------
2745    // fixed64 / sfixed64 tests
2746    // -----------------------------------------------------------------------
2747
2748    #[test]
2749    fn test_fixed64_roundtrip() {
2750        let values: &[u64] = &[
2751            0,
2752            1,
2753            255,
2754            65535,
2755            u32::MAX as u64,
2756            u64::MAX,
2757            0xDEAD_BEEF_CAFE_BABE,
2758        ];
2759        for &v in values {
2760            let mut buf = Vec::new();
2761            encode_fixed64(v, &mut buf);
2762            assert_eq!(buf.len(), 8);
2763            let decoded = decode_fixed64(&mut buf.as_slice()).unwrap();
2764            assert_eq!(v, decoded);
2765        }
2766    }
2767
2768    #[test]
2769    fn test_fixed64_little_endian() {
2770        let mut buf = Vec::new();
2771        encode_fixed64(0x0102030405060708, &mut buf);
2772        assert_eq!(buf, &[0x08, 0x07, 0x06, 0x05, 0x04, 0x03, 0x02, 0x01]);
2773    }
2774
2775    #[test]
2776    fn test_sfixed64_roundtrip() {
2777        let values: &[i64] = &[0, 1, -1, 127, -128, i64::MAX, i64::MIN];
2778        for &v in values {
2779            let mut buf = Vec::new();
2780            encode_sfixed64(v, &mut buf);
2781            assert_eq!(buf.len(), 8);
2782            let decoded = decode_sfixed64(&mut buf.as_slice()).unwrap();
2783            assert_eq!(v, decoded);
2784        }
2785    }
2786
2787    #[test]
2788    fn test_sfixed64_negative_encoding() {
2789        let mut buf = Vec::new();
2790        encode_sfixed64(-1, &mut buf);
2791        assert_eq!(buf, &[0xFF; 8]);
2792    }
2793
2794    #[test]
2795    fn test_fixed64_decode_truncated() {
2796        let result = decode_fixed64(&mut &[0x01; 7][..]);
2797        assert!(result.is_err());
2798    }
2799
2800    // -----------------------------------------------------------------------
2801    // Decode from empty buffer
2802    // -----------------------------------------------------------------------
2803
2804    #[test]
2805    fn test_decode_empty_buffer() {
2806        let empty: &[u8] = &[];
2807        // Fixed-width types
2808        assert!(decode_float(&mut &empty[..]).is_err());
2809        assert!(decode_double(&mut &empty[..]).is_err());
2810        assert!(decode_fixed32(&mut &empty[..]).is_err());
2811        assert!(decode_fixed64(&mut &empty[..]).is_err());
2812        assert!(decode_sfixed32(&mut &empty[..]).is_err());
2813        assert!(decode_sfixed64(&mut &empty[..]).is_err());
2814        // Varint types
2815        assert!(decode_int32(&mut &empty[..]).is_err());
2816        assert!(decode_int64(&mut &empty[..]).is_err());
2817        assert!(decode_uint32(&mut &empty[..]).is_err());
2818        assert!(decode_uint64(&mut &empty[..]).is_err());
2819        assert!(decode_sint32(&mut &empty[..]).is_err());
2820        assert!(decode_sint64(&mut &empty[..]).is_err());
2821        assert!(decode_bool(&mut &empty[..]).is_err());
2822    }
2823
2824    // -----------------------------------------------------------------------
2825    // Encoded size constants
2826    // -----------------------------------------------------------------------
2827
2828    #[test]
2829    fn test_encoded_size_constants() {
2830        assert_eq!(FIXED32_ENCODED_LEN, 4);
2831        assert_eq!(FIXED64_ENCODED_LEN, 8);
2832        assert_eq!(BOOL_ENCODED_LEN, 1);
2833    }
2834
2835    // -----------------------------------------------------------------------
2836    // int32 tests
2837    // -----------------------------------------------------------------------
2838
2839    #[test]
2840    fn test_int32_roundtrip() {
2841        let values: &[i32] = &[0, 1, -1, 127, -128, i32::MAX, i32::MIN, 300, -300];
2842        for &v in values {
2843            let mut buf = Vec::new();
2844            encode_int32(v, &mut buf);
2845            let decoded = decode_int32(&mut buf.as_slice()).unwrap();
2846            assert_eq!(v, decoded, "int32 roundtrip failed for {v}");
2847        }
2848    }
2849
2850    #[test]
2851    fn test_int32_negative_is_ten_bytes() {
2852        // Negative int32 values sign-extend to 64 bits → 10-byte varint.
2853        let mut buf = Vec::new();
2854        encode_int32(-1, &mut buf);
2855        assert_eq!(buf.len(), 10, "negative int32 should encode to 10 bytes");
2856        assert_eq!(int32_encoded_len(-1), 10);
2857    }
2858
2859    #[test]
2860    fn test_int32_positive_size() {
2861        assert_eq!(int32_encoded_len(0), 1);
2862        assert_eq!(int32_encoded_len(127), 1);
2863        assert_eq!(int32_encoded_len(128), 2);
2864        assert_eq!(int32_encoded_len(i32::MAX), 5);
2865    }
2866
2867    // -----------------------------------------------------------------------
2868    // int64 tests
2869    // -----------------------------------------------------------------------
2870
2871    #[test]
2872    fn test_int64_roundtrip() {
2873        let values: &[i64] = &[0, 1, -1, 127, -128, i64::MAX, i64::MIN, 300, -300];
2874        for &v in values {
2875            let mut buf = Vec::new();
2876            encode_int64(v, &mut buf);
2877            let decoded = decode_int64(&mut buf.as_slice()).unwrap();
2878            assert_eq!(v, decoded, "int64 roundtrip failed for {v}");
2879        }
2880    }
2881
2882    #[test]
2883    fn test_int64_negative_is_ten_bytes() {
2884        let mut buf = Vec::new();
2885        encode_int64(-1, &mut buf);
2886        assert_eq!(buf.len(), 10);
2887        assert_eq!(int64_encoded_len(-1), 10);
2888    }
2889
2890    // -----------------------------------------------------------------------
2891    // uint32 tests
2892    // -----------------------------------------------------------------------
2893
2894    #[test]
2895    fn test_uint32_roundtrip() {
2896        let values: &[u32] = &[0, 1, 127, 128, 255, 300, u32::MAX];
2897        for &v in values {
2898            let mut buf = Vec::new();
2899            encode_uint32(v, &mut buf);
2900            let decoded = decode_uint32(&mut buf.as_slice()).unwrap();
2901            assert_eq!(v, decoded, "uint32 roundtrip failed for {v}");
2902        }
2903    }
2904
2905    #[test]
2906    fn test_uint32_encoded_len() {
2907        assert_eq!(uint32_encoded_len(0), 1);
2908        assert_eq!(uint32_encoded_len(127), 1);
2909        assert_eq!(uint32_encoded_len(128), 2);
2910        assert_eq!(uint32_encoded_len(u32::MAX), 5);
2911    }
2912
2913    // -----------------------------------------------------------------------
2914    // uint64 tests
2915    // -----------------------------------------------------------------------
2916
2917    #[test]
2918    fn test_uint64_roundtrip() {
2919        let values: &[u64] = &[0, 1, 127, 128, u32::MAX as u64, u64::MAX];
2920        for &v in values {
2921            let mut buf = Vec::new();
2922            encode_uint64(v, &mut buf);
2923            let decoded = decode_uint64(&mut buf.as_slice()).unwrap();
2924            assert_eq!(v, decoded, "uint64 roundtrip failed for {v}");
2925        }
2926    }
2927
2928    #[test]
2929    fn test_uint64_encoded_len() {
2930        assert_eq!(uint64_encoded_len(0), 1);
2931        assert_eq!(uint64_encoded_len(u64::MAX), 10);
2932    }
2933
2934    // -----------------------------------------------------------------------
2935    // sint32 tests
2936    // -----------------------------------------------------------------------
2937
2938    #[test]
2939    fn test_sint32_roundtrip() {
2940        let values: &[i32] = &[0, -1, 1, -2, 2, i32::MAX, i32::MIN, -300, 300];
2941        for &v in values {
2942            let mut buf = Vec::new();
2943            encode_sint32(v, &mut buf);
2944            let decoded = decode_sint32(&mut buf.as_slice()).unwrap();
2945            assert_eq!(v, decoded, "sint32 roundtrip failed for {v}");
2946        }
2947    }
2948
2949    #[test]
2950    fn test_sint32_negative_is_compact() {
2951        // -1 zigzag-encodes to 1: should fit in 1 byte, unlike int32.
2952        let mut buf = Vec::new();
2953        encode_sint32(-1, &mut buf);
2954        assert_eq!(buf.len(), 1);
2955        assert_eq!(sint32_encoded_len(-1), 1);
2956
2957        // i32::MIN zigzag-encodes to u32::MAX (5 bytes).
2958        assert_eq!(sint32_encoded_len(i32::MIN), 5);
2959    }
2960
2961    // -----------------------------------------------------------------------
2962    // sint64 tests
2963    // -----------------------------------------------------------------------
2964
2965    #[test]
2966    fn test_sint64_roundtrip() {
2967        let values: &[i64] = &[0, -1, 1, -2, 2, i64::MAX, i64::MIN, -300, 300];
2968        for &v in values {
2969            let mut buf = Vec::new();
2970            encode_sint64(v, &mut buf);
2971            let decoded = decode_sint64(&mut buf.as_slice()).unwrap();
2972            assert_eq!(v, decoded, "sint64 roundtrip failed for {v}");
2973        }
2974    }
2975
2976    #[test]
2977    fn test_sint64_negative_is_compact() {
2978        let mut buf = Vec::new();
2979        encode_sint64(-1, &mut buf);
2980        assert_eq!(buf.len(), 1);
2981        assert_eq!(sint64_encoded_len(-1), 1);
2982    }
2983
2984    // -----------------------------------------------------------------------
2985    // bool tests
2986    // -----------------------------------------------------------------------
2987
2988    #[test]
2989    fn test_bool_roundtrip() {
2990        for v in [true, false] {
2991            let mut buf = Vec::new();
2992            encode_bool(v, &mut buf);
2993            assert_eq!(buf.len(), 1, "bool should encode to exactly 1 byte");
2994            let decoded = decode_bool(&mut buf.as_slice()).unwrap();
2995            assert_eq!(v, decoded, "bool roundtrip failed for {v}");
2996        }
2997    }
2998
2999    #[test]
3000    fn test_bool_wire_values() {
3001        let mut buf = Vec::new();
3002        encode_bool(true, &mut buf);
3003        assert_eq!(buf, &[0x01]);
3004
3005        buf.clear();
3006        encode_bool(false, &mut buf);
3007        assert_eq!(buf, &[0x00]);
3008    }
3009
3010    #[test]
3011    fn test_bool_nonzero_decodes_as_true() {
3012        // Spec: any non-zero varint decodes as true.
3013        for byte in [0x02u8, 0x7F, 0xFF] {
3014            // Encode a raw varint whose low byte is `byte` (with continuation
3015            // bit clear so it's a 1-byte varint).
3016            let raw = byte & 0x7F;
3017            let decoded = decode_bool(&mut &[raw][..]).unwrap();
3018            assert!(decoded, "0x{raw:02X} should decode as true");
3019        }
3020    }
3021
3022    #[test]
3023    fn test_bool_multibyte_varint_decodes_as_true() {
3024        // [0x80, 0x01] is a two-byte varint encoding of 128, which is non-zero
3025        // and must decode as true. Conforming encoders always write 0x00/0x01,
3026        // but the decoder must accept any non-zero varint per the spec.
3027        let decoded = decode_bool(&mut &[0x80u8, 0x01][..]).unwrap();
3028        assert!(decoded);
3029    }
3030
3031    #[test]
3032    fn test_packed_scalar_decoders_match_plain() {
3033        // Every `decode_*_packed` must agree with its plain counterpart on
3034        // the same wire bytes — same value, same truncation/zigzag/bool
3035        // conversion, same buffer advance.
3036        let raw_values: &[u64] = &[
3037            0,
3038            1,
3039            127,
3040            128,
3041            300,
3042            u64::from(u32::MAX),
3043            u64::from(u32::MAX) + 1,
3044            u64::MAX,
3045        ];
3046        for &raw in raw_values {
3047            let mut buf = Vec::new();
3048            encode_varint(raw, &mut buf);
3049            assert_eq!(
3050                decode_int32(&mut buf.as_slice()),
3051                decode_int32_packed(&mut buf.as_slice()),
3052                "int32 parity failed for raw {raw}"
3053            );
3054            assert_eq!(
3055                decode_int64(&mut buf.as_slice()),
3056                decode_int64_packed(&mut buf.as_slice()),
3057                "int64 parity failed for raw {raw}"
3058            );
3059            assert_eq!(
3060                decode_uint32(&mut buf.as_slice()),
3061                decode_uint32_packed(&mut buf.as_slice()),
3062                "uint32 parity failed for raw {raw}"
3063            );
3064            assert_eq!(
3065                decode_uint64(&mut buf.as_slice()),
3066                decode_uint64_packed(&mut buf.as_slice()),
3067                "uint64 parity failed for raw {raw}"
3068            );
3069            assert_eq!(
3070                decode_sint32(&mut buf.as_slice()),
3071                decode_sint32_packed(&mut buf.as_slice()),
3072                "sint32 parity failed for raw {raw}"
3073            );
3074            assert_eq!(
3075                decode_sint64(&mut buf.as_slice()),
3076                decode_sint64_packed(&mut buf.as_slice()),
3077                "sint64 parity failed for raw {raw}"
3078            );
3079            assert_eq!(
3080                decode_bool(&mut buf.as_slice()),
3081                decode_bool_packed(&mut buf.as_slice()),
3082                "bool parity failed for raw {raw}"
3083            );
3084        }
3085    }
3086
3087    // -----------------------------------------------------------------------
3088    // Varint-type encoded length helpers
3089    // -----------------------------------------------------------------------
3090
3091    #[test]
3092    fn test_varint_encoded_len_consistency() {
3093        // For each encode function, the encoded byte count must match the
3094        // corresponding *_encoded_len helper.
3095        let i32_cases: &[i32] = &[0, 1, -1, 127, 128, i32::MAX, i32::MIN];
3096        for &v in i32_cases {
3097            let mut buf = Vec::new();
3098            encode_int32(v, &mut buf);
3099            assert_eq!(
3100                buf.len(),
3101                int32_encoded_len(v),
3102                "int32_encoded_len mismatch for {v}"
3103            );
3104        }
3105
3106        let i64_cases: &[i64] = &[0, 1, -1, i64::MAX, i64::MIN];
3107        for &v in i64_cases {
3108            let mut buf = Vec::new();
3109            encode_int64(v, &mut buf);
3110            assert_eq!(
3111                buf.len(),
3112                int64_encoded_len(v),
3113                "int64_encoded_len mismatch for {v}"
3114            );
3115        }
3116
3117        let u32_cases: &[u32] = &[0, 1, 127, 128, u32::MAX];
3118        for &v in u32_cases {
3119            let mut buf = Vec::new();
3120            encode_uint32(v, &mut buf);
3121            assert_eq!(
3122                buf.len(),
3123                uint32_encoded_len(v),
3124                "uint32_encoded_len mismatch for {v}"
3125            );
3126        }
3127
3128        let u64_cases: &[u64] = &[0, 1, 127, 128, u64::MAX];
3129        for &v in u64_cases {
3130            let mut buf = Vec::new();
3131            encode_uint64(v, &mut buf);
3132            assert_eq!(
3133                buf.len(),
3134                uint64_encoded_len(v),
3135                "uint64_encoded_len mismatch for {v}"
3136            );
3137        }
3138
3139        let sint32_cases: &[i32] = &[0, -1, 1, i32::MAX, i32::MIN];
3140        for &v in sint32_cases {
3141            let mut buf = Vec::new();
3142            encode_sint32(v, &mut buf);
3143            assert_eq!(
3144                buf.len(),
3145                sint32_encoded_len(v),
3146                "sint32_encoded_len mismatch for {v}"
3147            );
3148        }
3149
3150        let sint64_cases: &[i64] = &[0, -1, 1, i64::MAX, i64::MIN];
3151        for &v in sint64_cases {
3152            let mut buf = Vec::new();
3153            encode_sint64(v, &mut buf);
3154            assert_eq!(
3155                buf.len(),
3156                sint64_encoded_len(v),
3157                "sint64_encoded_len mismatch for {v}"
3158            );
3159        }
3160    }
3161
3162    // -----------------------------------------------------------------------
3163    // string tests
3164    // -----------------------------------------------------------------------
3165
3166    #[test]
3167    fn test_string_roundtrip() {
3168        for s in ["", "hello", "héllo", "世界", "a".repeat(128).as_str()] {
3169            let mut buf = Vec::new();
3170            encode_string(s, &mut buf);
3171            assert_eq!(
3172                buf.len(),
3173                string_encoded_len(s),
3174                "string_encoded_len mismatch"
3175            );
3176            let decoded = decode_string(&mut buf.as_slice()).unwrap();
3177            assert_eq!(s, decoded);
3178        }
3179    }
3180
3181    #[test]
3182    fn test_string_empty() {
3183        let mut buf = Vec::new();
3184        encode_string("", &mut buf);
3185        // Empty string: varint 0 (1 byte), no payload.
3186        assert_eq!(buf, &[0x00]);
3187        assert_eq!(string_encoded_len(""), 1);
3188        let decoded = decode_string(&mut buf.as_slice()).unwrap();
3189        assert_eq!(decoded, "");
3190    }
3191
3192    #[test]
3193    fn test_decode_string_to_roundtrip() {
3194        // `decode_string_to::<S>` must decode identically to `decode_string`
3195        // for any `ProtoString` type; `String` exercises the identity path.
3196        for s in ["", "hello", "héllo", "世界", "a".repeat(128).as_str()] {
3197            let mut buf = Vec::new();
3198            encode_string(s, &mut buf);
3199            let decoded: String = decode_string_to(&mut buf.as_slice()).unwrap();
3200            assert_eq!(s, decoded);
3201        }
3202    }
3203
3204    #[test]
3205    fn test_decode_string_to_propagates_errors() {
3206        // Invalid UTF-8 surfaces before the `From<String>` conversion.
3207        let bad: &[u8] = &[0x02, 0xFF, 0xFE];
3208        assert_eq!(
3209            decode_string_to::<String>(&mut &bad[..]),
3210            Err(DecodeError::InvalidUtf8)
3211        );
3212        // Truncated payload is reported as EOF.
3213        let short: &[u8] = &[0x04, 0x61, 0x62];
3214        assert_eq!(
3215            decode_string_to::<String>(&mut &short[..]),
3216            Err(DecodeError::UnexpectedEof)
3217        );
3218    }
3219
3220    #[test]
3221    fn test_string_invalid_utf8() {
3222        // Length prefix = 2, payload = two invalid UTF-8 bytes.
3223        let buf: &[u8] = &[0x02, 0xFF, 0xFE];
3224        assert_eq!(decode_string(&mut &buf[..]), Err(DecodeError::InvalidUtf8));
3225    }
3226
3227    #[test]
3228    fn test_string_truncated() {
3229        // Length prefix says 4 bytes but buffer only has 2.
3230        let buf: &[u8] = &[0x04, 0x61, 0x62];
3231        assert_eq!(
3232            decode_string(&mut &buf[..]),
3233            Err(DecodeError::UnexpectedEof)
3234        );
3235    }
3236
3237    // -----------------------------------------------------------------------
3238    // bytes tests
3239    // -----------------------------------------------------------------------
3240
3241    #[test]
3242    fn test_bytes_roundtrip() {
3243        for b in [&[][..], &[0x00, 0xFF, 0x80], &[0u8; 128]] {
3244            let mut buf = Vec::new();
3245            encode_bytes(b, &mut buf);
3246            assert_eq!(
3247                buf.len(),
3248                bytes_encoded_len(b),
3249                "bytes_encoded_len mismatch"
3250            );
3251            let decoded = decode_bytes(&mut buf.as_slice()).unwrap();
3252            assert_eq!(b, decoded.as_slice());
3253        }
3254    }
3255
3256    #[test]
3257    fn test_bytes_empty() {
3258        let mut buf = Vec::new();
3259        encode_bytes(&[], &mut buf);
3260        assert_eq!(buf, &[0x00]);
3261        assert_eq!(bytes_encoded_len(&[]), 1);
3262        let decoded = decode_bytes(&mut buf.as_slice()).unwrap();
3263        assert!(decoded.is_empty());
3264    }
3265
3266    #[test]
3267    fn test_bytes_truncated() {
3268        // Length prefix says 5 bytes but buffer only has 2.
3269        let buf: &[u8] = &[0x05, 0xAA, 0xBB];
3270        assert_eq!(decode_bytes(&mut &buf[..]), Err(DecodeError::UnexpectedEof));
3271    }
3272
3273    #[test]
3274    fn decode_bytes_to_keeps_borrowed_payload_by_default() {
3275        let mut wire = Vec::new();
3276        encode_bytes(b"borrowed", &mut wire);
3277        let mut input = Bytes::from(wire);
3278
3279        let decoded = decode_bytes_to::<PayloadOwnership>(&mut input).unwrap();
3280
3281        assert_eq!(decoded.bytes, b"borrowed");
3282        assert!(!decoded.was_owned);
3283        assert!(input.is_empty());
3284    }
3285
3286    #[test]
3287    fn decode_bytes_to_can_share_owned_payload_for_custom_type() {
3288        let mut wire = Vec::new();
3289        encode_bytes(b"shared", &mut wire);
3290        encode_bytes(b"tail", &mut wire);
3291        let expected_remaining = wire[1 + b"shared".len()..].to_vec();
3292        let mut input = Bytes::from(wire);
3293        let payload_ptr = input.as_ptr() as usize + 1;
3294
3295        let decoded = decode_bytes_to::<SharedBytes>(&mut input).unwrap();
3296
3297        assert_eq!(&decoded.0[..], b"shared");
3298        assert_eq!(decoded.0.as_ptr() as usize, payload_ptr);
3299        assert_eq!(input.as_ref(), expected_remaining.as_slice());
3300
3301        // An input without Bytes-backed storage still decodes correctly; it
3302        // just cannot share the source allocation.
3303        let mut slice_wire = Vec::new();
3304        encode_bytes(b"copied", &mut slice_wire);
3305        let mut slice = slice_wire.as_slice();
3306        let copied = decode_bytes_to::<SharedBytes>(&mut slice).unwrap();
3307        assert_eq!(&copied.0[..], b"copied");
3308        assert!(slice.is_empty());
3309    }
3310
3311    #[test]
3312    fn decode_bytes_to_uses_owned_preference_for_bytes() {
3313        let mut wire = Vec::new();
3314        encode_bytes(b"shared", &mut wire);
3315        let mut input = Bytes::from(wire);
3316        let payload_ptr = input.as_ptr() as usize + 1;
3317
3318        let decoded = decode_bytes_to::<Bytes>(&mut input).unwrap();
3319
3320        assert_eq!(&decoded[..], b"shared");
3321        assert_eq!(decoded.as_ptr() as usize, payload_ptr);
3322        assert!(input.is_empty());
3323
3324        let mut empty = Bytes::from_static(&[0]);
3325        let decoded = decode_bytes_to::<Bytes>(&mut empty).unwrap();
3326        assert!(decoded.is_empty());
3327        assert!(empty.is_empty());
3328    }
3329
3330    #[test]
3331    fn decode_bytes_to_owned_preference_rejects_truncated_payload() {
3332        let mut input: &[u8] = &[0x04, 0xAA, 0xBB];
3333        assert!(matches!(
3334            decode_bytes_to::<SharedBytes>(&mut input),
3335            Err(DecodeError::UnexpectedEof)
3336        ));
3337    }
3338
3339    #[test]
3340    fn decode_bytes_to_owned_preference_reads_chained_input() {
3341        let mut wire = Vec::new();
3342        encode_bytes(b"first", &mut wire);
3343        encode_bytes(b"straddles", &mut wire);
3344        let split = 1 + b"first".len() + 4;
3345        let head = Bytes::copy_from_slice(&wire[..split]);
3346        let tail = Bytes::copy_from_slice(&wire[split..]);
3347        let first_ptr = head.as_ptr() as usize + 1;
3348        let mut input = head.chain(tail);
3349
3350        // A field inside one chunk shares that chunk.
3351        let first = decode_bytes_to::<SharedBytes>(&mut input).unwrap();
3352        assert_eq!(&first.0[..], b"first");
3353        assert_eq!(first.0.as_ptr() as usize, first_ptr);
3354
3355        // A field that spans two chunks is copied into one `Bytes`.
3356        let second = decode_bytes_to::<SharedBytes>(&mut input).unwrap();
3357        assert_eq!(&second.0[..], b"straddles");
3358        assert!(!input.has_remaining());
3359    }
3360
3361    #[test]
3362    fn custom_bytes_map_value_shares_the_input() {
3363        use crate::map_codec::{merge_entry, Int32, ProtoBytesMap};
3364
3365        // One length-prefixed map entry: key 1, value "value".
3366        let entry = [&[0x08, 0x01, 0x12, 0x05][..], b"value"].concat();
3367        let mut wire = Vec::new();
3368        encode_bytes(&entry, &mut wire);
3369        let mut input = Bytes::from(wire);
3370        let input_range = input.as_ptr() as usize..input.as_ptr() as usize + input.len();
3371        let limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
3372        let ctx = crate::DecodeContext::new(crate::RECURSION_LIMIT, &limit);
3373
3374        let mut map = std::collections::HashMap::<i32, SharedBytes>::new();
3375        merge_entry::<Int32, ProtoBytesMap<SharedBytes>, _>(&mut map, &mut input, ctx).unwrap();
3376
3377        let value = &map[&1];
3378        assert_eq!(&value.0[..], b"value");
3379        assert!(input_range.contains(&(value.0.as_ptr() as usize)));
3380    }
3381
3382    #[test]
3383    fn empty_bytes_field_at_the_end_of_the_input_does_not_retain_it() {
3384        // One field of length zero, which is also the end of the input.
3385        let whole = Bytes::from(vec![0u8]);
3386
3387        let mut input = whole.clone();
3388        let custom = decode_bytes_to::<SharedBytes>(&mut input).unwrap();
3389        drop(input);
3390        assert!(custom.0.is_empty());
3391        assert!(whole.is_unique(), "the empty value holds the input");
3392
3393        let mut input = whole.clone();
3394        let builtin = decode_bytes_to_bytes(&mut input).unwrap();
3395        drop(input);
3396        assert!(builtin.is_empty());
3397        assert!(whole.is_unique(), "the empty value holds the input");
3398    }
3399
3400    #[test]
3401    fn test_decode_bytes_to_bytes_zero_copy_from_bytes() {
3402        let mut enc = Vec::new();
3403        encode_bytes(b"\xDE\xAD\xBE\xEF", &mut enc);
3404        let mut buf = Bytes::from(enc);
3405        let payload_ptr = buf.as_ptr() as usize + 1;
3406        let out = decode_bytes_to_bytes(&mut buf).unwrap();
3407        assert_eq!(&out[..], b"\xDE\xAD\xBE\xEF");
3408        // copy_to_bytes on a Bytes input is split_to: the result aliases the
3409        // source buffer rather than allocating a copy.
3410        assert_eq!(out.as_ptr() as usize, payload_ptr);
3411        assert!(buf.is_empty());
3412    }
3413
3414    #[test]
3415    fn test_decode_bytes_to_bytes_from_slice() {
3416        let mut enc = Vec::new();
3417        encode_bytes(b"hello", &mut enc);
3418        let out = decode_bytes_to_bytes(&mut enc.as_slice()).unwrap();
3419        assert_eq!(&out[..], b"hello");
3420    }
3421
3422    #[test]
3423    fn test_decode_bytes_to_bytes_empty() {
3424        let mut buf = Bytes::from_static(&[0x00]);
3425        let out = decode_bytes_to_bytes(&mut buf).unwrap();
3426        assert!(out.is_empty());
3427        assert!(buf.is_empty());
3428    }
3429
3430    #[test]
3431    fn test_decode_bytes_to_bytes_truncated() {
3432        let buf: &[u8] = &[0x05, 0xAA, 0xBB];
3433        assert_eq!(
3434            decode_bytes_to_bytes(&mut &buf[..]),
3435            Err(DecodeError::UnexpectedEof)
3436        );
3437    }
3438
3439    // -----------------------------------------------------------------------
3440    // merge_string tests
3441    // -----------------------------------------------------------------------
3442
3443    #[test]
3444    fn merge_string_reuses_allocation() {
3445        // Pre-allocate a string with known capacity.
3446        let mut value = String::with_capacity(64);
3447        value.push_str("old content");
3448        let ptr_before = value.as_ptr();
3449
3450        let mut buf = Vec::new();
3451        encode_string("hello", &mut buf);
3452        merge_string(&mut value, &mut buf.as_slice()).unwrap();
3453
3454        assert_eq!(value, "hello");
3455        // The allocation should be reused (same base pointer) since
3456        // "hello" (5 bytes) fits within the 64-byte capacity.
3457        assert_eq!(value.as_ptr(), ptr_before);
3458    }
3459
3460    #[test]
3461    fn merge_string_empty() {
3462        let mut value = String::from("existing");
3463        let mut buf = Vec::new();
3464        encode_string("", &mut buf);
3465        merge_string(&mut value, &mut buf.as_slice()).unwrap();
3466        assert_eq!(value, "");
3467    }
3468
3469    #[test]
3470    fn merge_string_invalid_utf8() {
3471        let mut value = String::from("valid");
3472        let buf: &[u8] = &[0x02, 0xFF, 0xFE];
3473        let result = merge_string(&mut value, &mut &buf[..]);
3474        assert_eq!(result, Err(DecodeError::InvalidUtf8));
3475        // Value should be left in a valid (empty) state.
3476        assert!(value.is_empty());
3477    }
3478
3479    #[test]
3480    fn merge_string_truncated() {
3481        let mut value = String::from("existing");
3482        let buf: &[u8] = &[0x04, 0x61, 0x62];
3483        let result = merge_string(&mut value, &mut &buf[..]);
3484        assert_eq!(result, Err(DecodeError::UnexpectedEof));
3485        // Value should be preserved on UnexpectedEof (error returned before
3486        // any mutation).
3487        assert_eq!(value, "existing");
3488    }
3489
3490    #[test]
3491    fn merge_string_roundtrip() {
3492        for s in ["", "hello", "héllo", "世界", &"a".repeat(128)] {
3493            let mut buf = Vec::new();
3494            encode_string(s, &mut buf);
3495            let mut value = String::new();
3496            merge_string(&mut value, &mut buf.as_slice()).unwrap();
3497            assert_eq!(s, value);
3498        }
3499    }
3500
3501    // -----------------------------------------------------------------------
3502    // merge_bytes tests
3503    // -----------------------------------------------------------------------
3504
3505    #[test]
3506    fn merge_bytes_reuses_allocation() {
3507        let mut value = Vec::with_capacity(64);
3508        value.extend_from_slice(b"old content");
3509        let ptr_before = value.as_ptr();
3510
3511        let mut buf = Vec::new();
3512        encode_bytes(&[0xDE, 0xAD], &mut buf);
3513        merge_bytes(&mut value, &mut buf.as_slice()).unwrap();
3514
3515        assert_eq!(value, &[0xDE, 0xAD]);
3516        assert_eq!(value.as_ptr(), ptr_before);
3517    }
3518
3519    #[test]
3520    fn merge_bytes_empty() {
3521        let mut value = vec![1, 2, 3];
3522        let mut buf = Vec::new();
3523        encode_bytes(&[], &mut buf);
3524        merge_bytes(&mut value, &mut buf.as_slice()).unwrap();
3525        assert!(value.is_empty());
3526    }
3527
3528    #[test]
3529    fn merge_bytes_truncated() {
3530        let mut value = vec![0xAA];
3531        let buf: &[u8] = &[0x05, 0xAA, 0xBB];
3532        let result = merge_bytes(&mut value, &mut &buf[..]);
3533        assert_eq!(result, Err(DecodeError::UnexpectedEof));
3534        // Value should be preserved on UnexpectedEof.
3535        assert_eq!(value, &[0xAA]);
3536    }
3537
3538    #[test]
3539    fn merge_bytes_roundtrip() {
3540        for b in [&[][..], &[0x00, 0xFF, 0x80], &[0u8; 128]] {
3541            let mut buf = Vec::new();
3542            encode_bytes(b, &mut buf);
3543            let mut value = Vec::new();
3544            merge_bytes(&mut value, &mut buf.as_slice()).unwrap();
3545            assert_eq!(b, value.as_slice());
3546        }
3547    }
3548
3549    // -----------------------------------------------------------------------
3550    // copy_into_spare: chunked, panicking, and over-reporting sources
3551    // -----------------------------------------------------------------------
3552
3553    // A nested module so CI's Miri job can select these by name alongside the
3554    // size_cache tests (`-- size_cache copy_into_spare`).
3555    mod copy_into_spare {
3556        use super::*;
3557
3558        /// A `Buf` over fixed chunks that can misbehave on demand: `chunk()`
3559        /// panics once `panic_after` bytes have been consumed, `advance()`
3560        /// panics once it would push the consumed count past
3561        /// `panic_in_advance_after`, and `remaining()` reports `over_report`
3562        /// bytes more than the chunks actually hold.
3563        struct ChunkedBuf {
3564            chunks: Vec<Vec<u8>>,
3565            pos: usize,
3566            consumed: usize,
3567            panic_after: usize,
3568            panic_in_advance_after: usize,
3569            over_report: usize,
3570        }
3571
3572        impl ChunkedBuf {
3573            fn new(chunks: &[&[u8]]) -> Self {
3574                Self {
3575                    chunks: chunks.iter().map(|c| c.to_vec()).collect(),
3576                    pos: 0,
3577                    consumed: 0,
3578                    panic_after: usize::MAX,
3579                    panic_in_advance_after: usize::MAX,
3580                    over_report: 0,
3581                }
3582            }
3583        }
3584
3585        impl Buf for ChunkedBuf {
3586            fn remaining(&self) -> usize {
3587                self.chunks.iter().map(Vec::len).sum::<usize>() - self.pos + self.over_report
3588            }
3589
3590            fn chunk(&self) -> &[u8] {
3591                assert!(
3592                    self.consumed < self.panic_after,
3593                    "chunk() called after {} bytes",
3594                    self.consumed
3595                );
3596                self.chunks.first().map_or(&[], |c| &c[self.pos..])
3597            }
3598
3599            fn advance(&mut self, cnt: usize) {
3600                assert!(
3601                    self.consumed + cnt <= self.panic_in_advance_after,
3602                    "advance({cnt}) called after {} bytes",
3603                    self.consumed
3604                );
3605                self.pos += cnt;
3606                self.consumed += cnt;
3607                while self.chunks.first().is_some_and(|c| c.len() <= self.pos) {
3608                    self.pos -= self.chunks.remove(0).len();
3609                }
3610            }
3611        }
3612
3613        /// `wire` split into a one-byte length prefix and two payload chunks.
3614        fn split(wire: &[u8]) -> ChunkedBuf {
3615            ChunkedBuf::new(&[&wire[..1], &wire[1..4], &wire[4..]])
3616        }
3617
3618        #[cfg(feature = "std")]
3619        fn unwinds<R>(f: impl FnOnce() -> R) -> bool {
3620            std::panic::catch_unwind(std::panic::AssertUnwindSafe(f)).is_err()
3621        }
3622
3623        #[test]
3624        fn appends_across_chunks() {
3625            let mut buf = ChunkedBuf::new(&[b"ab", b"cde", b"f"]);
3626            let mut dst = vec![0x10, 0x11];
3627            copy_into_spare(&mut buf, &mut dst, 5);
3628            assert_eq!(dst, [0x10, 0x11, b'a', b'b', b'c', b'd', b'e']);
3629            assert_eq!(buf.chunk(), b"f");
3630            assert_eq!(buf.remaining(), 1);
3631        }
3632
3633        #[test]
3634        fn chunked_source_decodes_and_merges() {
3635            let payload = b"h\xC3\xA9llo!";
3636            let mut wire = Vec::new();
3637            encode_bytes(payload, &mut wire);
3638
3639            assert_eq!(decode_bytes(&mut split(&wire)).unwrap(), payload);
3640            assert_eq!(decode_string(&mut split(&wire)).unwrap(), "héllo!");
3641            let mut bytes = vec![0xAA; 3];
3642            merge_bytes(&mut bytes, &mut split(&wire)).unwrap();
3643            assert_eq!(bytes, payload);
3644            let mut string = String::from("previous");
3645            merge_string(&mut string, &mut split(&wire)).unwrap();
3646            assert_eq!(string, "héllo!");
3647        }
3648
3649        #[test]
3650        fn chunked_source_invalid_utf8_is_rejected_after_copy() {
3651            // Non-contiguous, so validation runs on the owned copy rather
3652            // than against the source chunk.
3653            let mut wire = Vec::new();
3654            encode_bytes(b"ab\xFF\xFEcd", &mut wire);
3655
3656            assert_eq!(
3657                decode_string(&mut split(&wire)),
3658                Err(DecodeError::InvalidUtf8)
3659            );
3660            let mut string = String::from("previous");
3661            assert_eq!(
3662                merge_string(&mut string, &mut split(&wire)),
3663                Err(DecodeError::InvalidUtf8)
3664            );
3665            assert!(string.is_empty());
3666        }
3667
3668        #[cfg(feature = "std")]
3669        #[test]
3670        fn merge_bytes_unwind_mid_copy_leaves_value_empty() {
3671            let mut buf = ChunkedBuf::new(&[b"\x06ab", b"cd", b"ef"]);
3672            buf.panic_after = 5; // after the length prefix + "abcd"
3673            let mut value = Vec::with_capacity(16);
3674            value.extend_from_slice(b"previous content");
3675            assert!(unwinds(|| merge_bytes(&mut value, &mut buf)));
3676            assert!(value.is_empty());
3677            assert!(value.capacity() >= 16);
3678        }
3679
3680        #[cfg(feature = "std")]
3681        #[test]
3682        fn merge_string_unwind_mid_copy_leaves_value_empty() {
3683            let mut buf = ChunkedBuf::new(&[b"\x06ab", b"cd", b"ef"]);
3684            buf.panic_after = 5;
3685            let mut value = String::from("previous content");
3686            assert!(unwinds(|| merge_string(&mut value, &mut buf)));
3687            assert!(value.is_empty());
3688        }
3689
3690        #[cfg(feature = "std")]
3691        #[test]
3692        fn unwind_in_advance_leaves_value_empty() {
3693            // `advance()` unwinds after "abcd" have already been copied into
3694            // spare capacity but before that progress is recorded — the
3695            // widest window of written-but-unpublished bytes.
3696            let mut buf = ChunkedBuf::new(&[b"\x06ab", b"cd", b"ef"]);
3697            buf.panic_in_advance_after = 4;
3698            let mut value = vec![0xAA; 8];
3699            assert!(unwinds(|| merge_bytes(&mut value, &mut buf)));
3700            assert!(value.is_empty());
3701        }
3702
3703        #[cfg(feature = "std")]
3704        #[test]
3705        fn decode_unwind_mid_copy_drops_partial_vec() {
3706            // The destination is a local `Vec` whose spare capacity is
3707            // partially written when the unwind drops it; under Miri this
3708            // checks that the drop touches nothing uninitialised.
3709            let mut buf = ChunkedBuf::new(&[b"\x06ab", b"cd", b"ef"]);
3710            buf.panic_after = 5;
3711            assert!(unwinds(|| decode_bytes(&mut buf)));
3712            let mut buf = ChunkedBuf::new(&[b"\x06ab", b"cd", b"ef"]);
3713            buf.panic_after = 5;
3714            assert!(unwinds(|| decode_string(&mut buf)));
3715        }
3716
3717        #[cfg(feature = "std")]
3718        #[test]
3719        fn over_reporting_buf_panics_without_publishing_length() {
3720            // `remaining()` promises 6 bytes but the chunks hold only 4 after
3721            // the length prefix, so `chunk()` runs dry mid-copy.
3722            let mut buf = ChunkedBuf::new(&[b"\x06ab", b"cd"]);
3723            buf.over_report = 2;
3724            let mut value = vec![0xAA; 8];
3725            let r = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
3726                merge_bytes(&mut value, &mut buf)
3727            }));
3728            let msg = r.unwrap_err();
3729            let msg = msg.downcast_ref::<String>().map_or("", String::as_str);
3730            assert!(msg.contains("2 bytes still to read"), "{msg}");
3731            assert!(value.is_empty());
3732        }
3733    }
3734
3735    // -----------------------------------------------------------------------
3736    // borrow_str / borrow_bytes tests
3737    // -----------------------------------------------------------------------
3738
3739    #[test]
3740    fn borrow_str_valid_borrows_from_source() {
3741        // Encode "hello" and verify the borrowed slice points into the same bytes.
3742        let mut encoded = Vec::new();
3743        encode_string("hello", &mut encoded);
3744        let source: &[u8] = &encoded;
3745        let mut cur: &[u8] = source;
3746        let s = borrow_str(&mut cur).unwrap();
3747        assert_eq!(s, "hello");
3748        // Verify zero-copy: the returned &str must be a sub-slice of the input buffer.
3749        assert!(core::ptr::eq(s.as_bytes().as_ptr(), source[1..].as_ptr()));
3750        // Cursor should be advanced past the string payload.
3751        assert!(cur.is_empty());
3752    }
3753
3754    #[test]
3755    fn borrow_str_empty_string() {
3756        let mut encoded = Vec::new();
3757        encode_string("", &mut encoded);
3758        let mut cur: &[u8] = &encoded;
3759        let s = borrow_str(&mut cur).unwrap();
3760        assert_eq!(s, "");
3761        assert!(cur.is_empty());
3762    }
3763
3764    #[test]
3765    fn borrow_str_advances_cursor() {
3766        // Two strings back-to-back; each borrow_str call should advance past its own payload.
3767        let mut encoded = Vec::new();
3768        encode_string("ab", &mut encoded);
3769        encode_string("cd", &mut encoded);
3770        let mut cur: &[u8] = &encoded;
3771        assert_eq!(borrow_str(&mut cur).unwrap(), "ab");
3772        assert_eq!(borrow_str(&mut cur).unwrap(), "cd");
3773        assert!(cur.is_empty());
3774    }
3775
3776    #[test]
3777    fn borrow_str_invalid_utf8_returns_error() {
3778        // Length prefix 2, then two invalid UTF-8 bytes.
3779        let buf: &[u8] = &[0x02, 0xFF, 0xFE];
3780        let mut cur: &[u8] = buf;
3781        assert_eq!(borrow_str(&mut cur), Err(DecodeError::InvalidUtf8));
3782        // Cursor is advanced past the bytes even on error.
3783        assert!(cur.is_empty());
3784    }
3785
3786    #[test]
3787    fn borrow_str_truncated_returns_eof() {
3788        let buf: &[u8] = &[0x04, 0x61, 0x62]; // length 4, only 2 bytes
3789        let mut cur: &[u8] = buf;
3790        assert_eq!(borrow_str(&mut cur), Err(DecodeError::UnexpectedEof));
3791    }
3792
3793    #[test]
3794    fn borrow_bytes_valid_borrows_from_source() {
3795        let mut encoded = Vec::new();
3796        encode_bytes(&[0xDE, 0xAD, 0xBE, 0xEF], &mut encoded);
3797        let source: &[u8] = &encoded;
3798        let mut cur: &[u8] = source;
3799        let b = borrow_bytes(&mut cur).unwrap();
3800        assert_eq!(b, &[0xDE, 0xAD, 0xBE, 0xEF]);
3801        // Verify zero-copy: the returned &[u8] must be a sub-slice of the input buffer.
3802        assert!(core::ptr::eq(b.as_ptr(), source[1..].as_ptr()));
3803        assert!(cur.is_empty());
3804    }
3805
3806    #[test]
3807    fn borrow_bytes_empty() {
3808        let mut encoded = Vec::new();
3809        encode_bytes(&[], &mut encoded);
3810        let mut cur: &[u8] = &encoded;
3811        let b = borrow_bytes(&mut cur).unwrap();
3812        assert!(b.is_empty());
3813        assert!(cur.is_empty());
3814    }
3815
3816    #[test]
3817    fn borrow_bytes_advances_cursor() {
3818        let mut encoded = Vec::new();
3819        encode_bytes(&[1, 2], &mut encoded);
3820        encode_bytes(&[3, 4, 5], &mut encoded);
3821        let mut cur: &[u8] = &encoded;
3822        assert_eq!(borrow_bytes(&mut cur).unwrap(), &[1, 2]);
3823        assert_eq!(borrow_bytes(&mut cur).unwrap(), &[3, 4, 5]);
3824        assert!(cur.is_empty());
3825    }
3826
3827    #[test]
3828    fn borrow_bytes_truncated_returns_eof() {
3829        let buf: &[u8] = &[0x05, 0xAA, 0xBB]; // length 5, only 2 bytes
3830        let mut cur: &[u8] = buf;
3831        assert_eq!(borrow_bytes(&mut cur), Err(DecodeError::UnexpectedEof));
3832    }
3833
3834    // -----------------------------------------------------------------------
3835    // borrow_group tests
3836    // -----------------------------------------------------------------------
3837
3838    /// Helper: build a byte buffer with the given tag+value pairs followed
3839    /// by an EndGroup tag for `group_field_number`.
3840    fn build_group_bytes(
3841        fields: &[(u32, crate::encoding::WireType, &[u8])],
3842        group_field_number: u32,
3843    ) -> Vec<u8> {
3844        use crate::encoding::Tag;
3845        let mut buf = Vec::new();
3846        for &(fnum, wt, data) in fields {
3847            Tag::new(fnum, wt).encode(&mut buf);
3848            buf.extend_from_slice(data);
3849        }
3850        Tag::new(group_field_number, crate::encoding::WireType::EndGroup).encode(&mut buf);
3851        buf
3852    }
3853
3854    #[test]
3855    fn borrow_group_empty() {
3856        // Group with no fields: just EndGroup(1).
3857        let data = build_group_bytes(&[], 1);
3858        let mut cur: &[u8] = &data;
3859        let body = borrow_group(&mut cur, 1, crate::RECURSION_LIMIT).unwrap();
3860        assert!(body.is_empty());
3861        assert!(cur.is_empty());
3862    }
3863
3864    #[test]
3865    fn borrow_group_one_varint_field() {
3866        // Group with one varint field (field 2 = 150).
3867        let mut varint_buf = Vec::new();
3868        crate::encoding::encode_varint(150, &mut varint_buf);
3869        let data = build_group_bytes(&[(2, crate::encoding::WireType::Varint, &varint_buf)], 1);
3870        let mut cur: &[u8] = &data;
3871        let body = borrow_group(&mut cur, 1, crate::RECURSION_LIMIT).unwrap();
3872
3873        // Body should contain the tag for field 2 + the varint 150.
3874        let expected_body_len = data.len() - crate::encoding::varint_len(((1u64) << 3) | 4);
3875        assert_eq!(body.len(), expected_body_len);
3876        assert!(cur.is_empty());
3877
3878        // Verify the body can be decoded as field 2 = 150.
3879        let mut body_cur = body;
3880        let tag = crate::encoding::Tag::decode(&mut body_cur).unwrap();
3881        assert_eq!(tag.field_number(), 2);
3882        assert_eq!(crate::encoding::decode_varint(&mut body_cur).unwrap(), 150);
3883        assert!(body_cur.is_empty());
3884    }
3885
3886    #[test]
3887    fn borrow_group_nested_group() {
3888        // Outer group (field 1) containing an inner group (field 3) with a
3889        // varint field (field 4 = 42), then EndGroup(3), then EndGroup(1).
3890        use crate::encoding::{Tag, WireType};
3891        let mut data = Vec::new();
3892        // Inner group: StartGroup(3), varint field 4 = 42, EndGroup(3)
3893        Tag::new(3, WireType::StartGroup).encode(&mut data);
3894        Tag::new(4, WireType::Varint).encode(&mut data);
3895        crate::encoding::encode_varint(42, &mut data);
3896        Tag::new(3, WireType::EndGroup).encode(&mut data);
3897        // Outer EndGroup(1)
3898        Tag::new(1, WireType::EndGroup).encode(&mut data);
3899
3900        let mut cur: &[u8] = &data;
3901        let body = borrow_group(&mut cur, 1, crate::RECURSION_LIMIT).unwrap();
3902        assert!(cur.is_empty());
3903
3904        // Body should contain the entire inner group (StartGroup through
3905        // EndGroup for field 3).
3906        assert!(!body.is_empty());
3907
3908        // Verify inner group can be parsed from the body.
3909        let mut body_cur = body;
3910        let inner_tag = crate::encoding::Tag::decode(&mut body_cur).unwrap();
3911        assert_eq!(inner_tag.field_number(), 3);
3912        assert_eq!(inner_tag.wire_type(), WireType::StartGroup);
3913        let inner_body = borrow_group(&mut body_cur, 3, crate::RECURSION_LIMIT).unwrap();
3914        assert!(body_cur.is_empty());
3915
3916        // Inner body: field 4 = 42
3917        let mut inner_cur = inner_body;
3918        let f4_tag = crate::encoding::Tag::decode(&mut inner_cur).unwrap();
3919        assert_eq!(f4_tag.field_number(), 4);
3920        assert_eq!(crate::encoding::decode_varint(&mut inner_cur).unwrap(), 42);
3921        assert!(inner_cur.is_empty());
3922    }
3923
3924    #[test]
3925    fn borrow_group_mismatched_end() {
3926        // EndGroup with wrong field number.
3927        use crate::encoding::{Tag, WireType};
3928        let mut data = Vec::new();
3929        Tag::new(99, WireType::EndGroup).encode(&mut data);
3930
3931        let mut cur: &[u8] = &data;
3932        assert_eq!(
3933            borrow_group(&mut cur, 1, crate::RECURSION_LIMIT),
3934            Err(DecodeError::InvalidEndGroup(99))
3935        );
3936    }
3937
3938    #[test]
3939    fn borrow_group_truncated() {
3940        // Buffer ends without EndGroup.
3941        use crate::encoding::{Tag, WireType};
3942        let mut data = Vec::new();
3943        Tag::new(2, WireType::Varint).encode(&mut data);
3944        crate::encoding::encode_varint(42, &mut data);
3945        // No EndGroup tag.
3946
3947        let mut cur: &[u8] = &data;
3948        assert_eq!(
3949            borrow_group(&mut cur, 1, crate::RECURSION_LIMIT),
3950            Err(DecodeError::UnexpectedEof)
3951        );
3952    }
3953
3954    #[test]
3955    fn borrow_group_empty_buffer() {
3956        let mut cur: &[u8] = &[];
3957        assert_eq!(
3958            borrow_group(&mut cur, 1, crate::RECURSION_LIMIT),
3959            Err(DecodeError::UnexpectedEof)
3960        );
3961    }
3962
3963    #[test]
3964    fn borrow_group_trailing_data_preserved() {
3965        // Group followed by extra data that should remain in the buffer.
3966        use crate::encoding::{Tag, WireType};
3967        let mut data = Vec::new();
3968        Tag::new(1, WireType::EndGroup).encode(&mut data);
3969        data.extend_from_slice(&[0xDE, 0xAD]); // trailing bytes
3970
3971        let mut cur: &[u8] = &data;
3972        let body = borrow_group(&mut cur, 1, crate::RECURSION_LIMIT).unwrap();
3973        assert!(body.is_empty());
3974        assert_eq!(cur, &[0xDE, 0xAD]);
3975    }
3976
3977    #[test]
3978    fn borrow_group_nested_start_group_respects_depth_limit() {
3979        // Group body contains a nested StartGroup(2)..EndGroup(2). With
3980        // depth=0, scanning past the nested group must fail with
3981        // RecursionLimitExceeded (it requires one level of depth budget).
3982        use crate::encoding::{Tag, WireType};
3983        let mut data = Vec::new();
3984        Tag::new(2, WireType::StartGroup).encode(&mut data);
3985        Tag::new(2, WireType::EndGroup).encode(&mut data);
3986        Tag::new(1, WireType::EndGroup).encode(&mut data);
3987
3988        let mut cur: &[u8] = &data;
3989        assert_eq!(
3990            borrow_group(&mut cur, 1, 0),
3991            Err(DecodeError::RecursionLimitExceeded)
3992        );
3993
3994        // With depth=1, the nested group (one level deep) is skippable.
3995        let mut cur: &[u8] = &data;
3996        let body = borrow_group(&mut cur, 1, 1).unwrap();
3997        assert!(!body.is_empty());
3998        assert!(cur.is_empty());
3999    }
4000
4001    // --- 32-bit specific tests ---
4002    // These exercise the `MessageTooLarge` error path in decode functions where
4003    // a varint length prefix exceeds `usize::MAX`. On 64-bit targets, `usize`
4004    // is as wide as `u64` so `usize::try_from(u64)` never fails; the error is
4005    // only reachable on 32-bit (or narrower) targets.
4006
4007    /// Varint encoding of 0x1_0000_0000 (u32::MAX + 1) — exceeds 32-bit usize.
4008    #[cfg(target_pointer_width = "32")]
4009    const OVERSIZED_VARINT: &[u8] = &[0x80, 0x80, 0x80, 0x80, 0x10];
4010
4011    #[test]
4012    #[cfg(target_pointer_width = "32")]
4013    fn decode_string_rejects_oversized_length_on_32bit() {
4014        let mut buf = OVERSIZED_VARINT;
4015        assert_eq!(decode_string(&mut buf), Err(DecodeError::MessageTooLarge));
4016    }
4017
4018    #[test]
4019    #[cfg(target_pointer_width = "32")]
4020    fn decode_bytes_rejects_oversized_length_on_32bit() {
4021        let mut buf = OVERSIZED_VARINT;
4022        assert_eq!(decode_bytes(&mut buf), Err(DecodeError::MessageTooLarge));
4023    }
4024
4025    #[test]
4026    #[cfg(target_pointer_width = "32")]
4027    fn merge_string_rejects_oversized_length_on_32bit() {
4028        let mut value = String::new();
4029        let mut buf = OVERSIZED_VARINT;
4030        assert_eq!(
4031            merge_string(&mut value, &mut buf),
4032            Err(DecodeError::MessageTooLarge)
4033        );
4034    }
4035
4036    #[test]
4037    #[cfg(target_pointer_width = "32")]
4038    fn merge_bytes_rejects_oversized_length_on_32bit() {
4039        let mut value = Vec::new();
4040        let mut buf = OVERSIZED_VARINT;
4041        assert_eq!(
4042            merge_bytes(&mut value, &mut buf),
4043            Err(DecodeError::MessageTooLarge)
4044        );
4045    }
4046
4047    #[test]
4048    #[cfg(target_pointer_width = "32")]
4049    fn borrow_str_rejects_oversized_length_on_32bit() {
4050        let mut buf: &[u8] = OVERSIZED_VARINT;
4051        assert_eq!(borrow_str(&mut buf), Err(DecodeError::MessageTooLarge));
4052    }
4053
4054    #[test]
4055    #[cfg(target_pointer_width = "32")]
4056    fn borrow_bytes_rejects_oversized_length_on_32bit() {
4057        let mut buf: &[u8] = OVERSIZED_VARINT;
4058        assert_eq!(borrow_bytes(&mut buf), Err(DecodeError::MessageTooLarge));
4059    }
4060
4061    // -----------------------------------------------------------------------
4062    // bulk packed fixed-width extender tests
4063    // -----------------------------------------------------------------------
4064
4065    /// Differential harness: the bulk extender must agree with the
4066    /// per-element decoder on every payload, valid or not.
4067    fn check_bulk_double(payload: &[u8]) {
4068        let mut bulk = Vec::new();
4069        let bulk_res = extend_packed_double(payload, &mut bulk);
4070        let mut elems = Vec::new();
4071        let mut cur = payload;
4072        let elem_res = loop {
4073            if cur.is_empty() {
4074                break Ok(());
4075            }
4076            match decode_double(&mut cur) {
4077                Ok(v) => elems.push(v),
4078                Err(e) => break Err(e),
4079            }
4080        };
4081        let bulk_ok = bulk_res.is_ok();
4082        assert_eq!(
4083            bulk_res.err(),
4084            elem_res.err(),
4085            "accept/reject and error-variant parity"
4086        );
4087        if bulk_ok {
4088            assert_eq!(bulk.len(), elems.len());
4089            for (a, b) in bulk.iter().zip(&elems) {
4090                assert_eq!(a.to_bits(), b.to_bits(), "bit-exact element parity");
4091            }
4092        }
4093    }
4094
4095    #[test]
4096    fn test_extend_packed_double_matches_per_element() {
4097        let mut payload = Vec::new();
4098        for v in [
4099            0.0f64,
4100            -0.0,
4101            1.0,
4102            -1.5,
4103            f64::NAN,
4104            f64::INFINITY,
4105            f64::MIN_POSITIVE,
4106            1.0e308,
4107        ] {
4108            encode_double(v, &mut payload);
4109        }
4110        check_bulk_double(&payload);
4111        check_bulk_double(&[]);
4112        // Misaligned payloads: every truncation of a valid payload.
4113        for cut in 1..payload.len() {
4114            check_bulk_double(&payload[..cut]);
4115        }
4116    }
4117
4118    #[test]
4119    fn test_extend_packed_double_error_leaves_out_unmodified() {
4120        let mut out = vec![42.0f64];
4121        let misaligned = [0u8; 9];
4122        assert!(extend_packed_double(&misaligned, &mut out).is_err());
4123        assert_eq!(out, vec![42.0], "failed decode must not partially extend");
4124    }
4125
4126    #[test]
4127    fn test_extend_packed_double_appends() {
4128        let mut payload = Vec::new();
4129        encode_double(2.5, &mut payload);
4130        let mut out = vec![1.0f64];
4131        extend_packed_double(&payload, &mut out).unwrap();
4132        assert_eq!(
4133            out,
4134            vec![1.0, 2.5],
4135            "extender appends after existing elements"
4136        );
4137    }
4138
4139    #[test]
4140    fn test_extend_packed_fixed32_family_roundtrip() {
4141        let mut p32 = Vec::new();
4142        for v in [0u32, 1, 0xDEAD_BEEF, u32::MAX] {
4143            encode_fixed32(v, &mut p32);
4144        }
4145        let mut out_u32 = Vec::new();
4146        extend_packed_fixed32(&p32, &mut out_u32).unwrap();
4147        assert_eq!(out_u32, vec![0, 1, 0xDEAD_BEEF, u32::MAX]);
4148
4149        let mut out_i32 = Vec::new();
4150        extend_packed_sfixed32(&p32, &mut out_i32).unwrap();
4151        assert_eq!(out_i32, vec![0, 1, 0xDEAD_BEEFu32 as i32, -1]);
4152
4153        let mut out_f32 = Vec::new();
4154        extend_packed_float(&p32, &mut out_f32).unwrap();
4155        assert_eq!(out_f32.len(), 4);
4156        assert!(extend_packed_float(&p32[..5], &mut Vec::new()).is_err());
4157    }
4158
4159    #[test]
4160    fn test_extend_packed_fixed64_family_roundtrip() {
4161        let mut p64 = Vec::new();
4162        for v in [0u64, 1, u64::MAX] {
4163            encode_fixed64(v, &mut p64);
4164        }
4165        let mut out_u64 = Vec::new();
4166        extend_packed_fixed64(&p64, &mut out_u64).unwrap();
4167        assert_eq!(out_u64, vec![0, 1, u64::MAX]);
4168
4169        let mut out_i64 = Vec::new();
4170        extend_packed_sfixed64(&p64, &mut out_i64).unwrap();
4171        assert_eq!(out_i64, vec![0, 1, -1]);
4172        assert!(extend_packed_sfixed64(&p64[..23], &mut Vec::new()).is_err());
4173    }
4174
4175    // -----------------------------------------------------------------------
4176    // bulk packed varint extender tests
4177    // -----------------------------------------------------------------------
4178
4179    fn per_element_u32(payload: &[u8]) -> Result<Vec<u32>, DecodeError> {
4180        let mut out = Vec::new();
4181        let mut cur = payload;
4182        while !cur.is_empty() {
4183            out.push(decode_uint32(&mut cur)?);
4184        }
4185        Ok(out)
4186    }
4187
4188    fn check_bulk_u32(payload: &[u8]) {
4189        let mut bulk = Vec::new();
4190        let bulk_res =
4191            extend_packed_uint32(payload, &mut bulk, crate::encoding::count_varints(payload));
4192        let elem_res = per_element_u32(payload);
4193        assert_eq!(
4194            bulk_res.err(),
4195            elem_res.as_ref().err().cloned(),
4196            "accept/reject and error-variant parity for {payload:?}"
4197        );
4198        if let Ok(elems) = elem_res {
4199            assert_eq!(bulk, elems, "element parity for {payload:?}");
4200        }
4201    }
4202
4203    #[test]
4204    fn test_extend_packed_uint32_matches_per_element() {
4205        let mut payload = Vec::new();
4206        for v in [0u32, 1, 127, 128, 16383, 16384, 65535, u32::MAX] {
4207            encode_uint32(v, &mut payload);
4208        }
4209        check_bulk_u32(&payload);
4210        check_bulk_u32(&[]);
4211        for cut in 1..payload.len() {
4212            check_bulk_u32(&payload[..cut]);
4213        }
4214        // Overlong but terminated encodings parity (e.g. 0 as [0x80, 0x00]).
4215        check_bulk_u32(&[0x80, 0x00, 0x81, 0x00]);
4216        // 10-byte and 11-byte elements (VarintTooLong parity).
4217        check_bulk_u32(&[0xFF; 9].iter().copied().chain([0x01]).collect::<Vec<_>>());
4218        check_bulk_u32(&[0xFF; 10].iter().copied().chain([0x01]).collect::<Vec<_>>());
4219        // All-continuation payload (unterminated tail -> per-element fallback).
4220        check_bulk_u32(&[0xFF; 4]);
4221    }
4222
4223    #[test]
4224    fn test_extend_packed_varint_family_conversions() {
4225        // int64 sign-extension: -1 encodes as 10 bytes.
4226        let mut p = Vec::new();
4227        encode_int64(-1, &mut p);
4228        encode_int64(5, &mut p);
4229        let mut out_i64 = Vec::new();
4230        extend_packed_int64(&p, &mut out_i64, p.len()).unwrap();
4231        assert_eq!(out_i64, vec![-1, 5]);
4232
4233        // int32 truncation through the same wire bytes.
4234        let mut out_i32 = Vec::new();
4235        extend_packed_int32(&p, &mut out_i32, p.len()).unwrap();
4236        assert_eq!(out_i32, vec![-1, 5]);
4237
4238        // sint32/sint64 zigzag.
4239        let mut pz = Vec::new();
4240        encode_sint32(-2, &mut pz);
4241        encode_sint64(i64::MIN, &mut pz);
4242        let mut out_s32 = Vec::new();
4243        extend_packed_sint32(&pz, &mut out_s32, pz.len()).unwrap();
4244        let mut cur: &[u8] = &pz;
4245        let want_s32 = vec![
4246            decode_sint32(&mut cur).unwrap(),
4247            decode_sint32(&mut cur).unwrap(),
4248        ];
4249        assert_eq!(out_s32, want_s32);
4250        let mut out_s64 = Vec::new();
4251        extend_packed_sint64(&pz, &mut out_s64, pz.len()).unwrap();
4252        assert_eq!(out_s64[1], i64::MIN);
4253
4254        // bool: nonzero (incl. overlong) is true.
4255        let mut out_b = Vec::new();
4256        extend_packed_bool(&[0x00, 0x01, 0x80, 0x01], &mut out_b, 4).unwrap();
4257        assert_eq!(out_b, vec![false, true, true]);
4258
4259        // uint64 max round-trip.
4260        let mut pm = Vec::new();
4261        encode_uint64(u64::MAX, &mut pm);
4262        let mut out_u64 = Vec::new();
4263        extend_packed_uint64(&pm, &mut out_u64, pm.len()).unwrap();
4264        assert_eq!(out_u64, vec![u64::MAX]);
4265    }
4266}
4267
4268#[cfg(test)]
4269mod decode_hook_tests;