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