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