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