buffa/message.rs
1// Modified by ReallyMe Technologies Limited.
2//! The core [`Message`] trait and [`DecodeOptions`] builder.
3//!
4//! Every generated message type implements [`Message`], which provides
5//! encode/decode/merge methods and a two-pass serialization model
6//! (`compute_size` populates a [`SizeCache`](crate::SizeCache), `write_to`
7//! consumes it) that avoids the exponential-time problem affecting naïve
8//! length-delimited encoders.
9
10use crate::encode_sink::EncodeSink;
11use bytes::Buf;
12
13use crate::error::{DecodeError, EncodeError};
14use crate::message_field::DefaultInstance;
15
16/// Default recursion depth limit for decoding nested messages.
17///
18/// Protobuf implementations are required to enforce a recursion limit to
19/// prevent stack overflow from deeply nested messages in untrusted input.
20/// This value (100) matches the limit used by the official protobuf
21/// implementations and the protobuf conformance suite.
22///
23/// Pass this constant as the depth when constructing a [`DecodeContext`] for
24/// a top-level [`Message::merge`] call. The provided convenience methods
25/// ([`Message::decode`], [`Message::decode_from_slice`],
26/// [`Message::merge_from_slice`]) use this limit automatically.
27pub const RECURSION_LIMIT: u32 = 100;
28
29/// Default limit on unknown fields decoded per top-level decode: 1,000,000.
30///
31/// Bounds the number of [`UnknownField`](crate::UnknownField) values the
32/// decoder will materialize in a single top-level decode, independent of
33/// the input size. Without this bound, wire data can force allocation far
34/// in excess of its own size: every 2-byte unknown varint field
35/// materialises a ~40-byte `UnknownField`, a ~20× amplification, so a
36/// 64 MiB payload of unknown fields would otherwise force over 1 GiB of
37/// heap. The count limit caps that overhead at roughly `limit × 40` bytes
38/// (~40 MB at the default); unknown length-delimited *payload* bytes are
39/// not counted against the limit because they are already bounded by the
40/// input size, which [`DecodeOptions::with_max_message_size`] governs.
41///
42/// The `limit × 40` figure prices a *flat* unknown field, and nesting costs
43/// more than that. Each unknown group allocates its own `Vec` of children,
44/// and `Vec`'s minimum non-zero capacity is four elements — so a group
45/// holding a single child occupies ~160 bytes of that `Vec` plus its own
46/// ~40-byte slot, roughly 200 bytes charged as one. A payload of many
47/// shallow groups therefore reaches about five times the flat ceiling,
48/// ~200 MB at the default rather than ~40 MB. Still bounded and still
49/// proportional to the limit, but worth knowing when choosing one: the
50/// count bounds *slots*, and a slot is not a fixed number of bytes.
51///
52/// A million unknown fields is far more than any realistic
53/// forward-compatibility scenario needs. Raise the limit with
54/// [`DecodeOptions::with_unknown_field_limit`] if you decode trusted
55/// messages that legitimately carry more (e.g. a proxy forwarding messages
56/// with a huge unpacked repeated field from a much newer schema).
57pub const DEFAULT_UNKNOWN_FIELD_LIMIT: usize = 1_000_000;
58
59/// Default element-memory budget: 32 MiB per top-level decode.
60///
61/// Bounds the memory a single decode may materialize in the elements of
62/// length-delimited containers — repeated message, string and bytes fields, and
63/// map entries — independent of the input size. These amplify the same way unknown fields do, and further: an
64/// empty repeated message element is 2 wire bytes and materializes
65/// `size_of::<T>()` in the `Vec` it lands in, measured at 256 bytes for a
66/// message of a few `Vec`/`String` fields — a 128x ratio, so 4 MiB of such
67/// elements would otherwise force ~512 MiB. Empty `bytes` and `string`
68/// elements amplify 16x and 12x by the same route.
69///
70/// A map entry is charged for both halves, key and value: an omitted message
71/// value still materializes in the map, and a few bytes of key buy a distinct
72/// slot, so `map<string, Message>` amplifies exactly as a repeated message does.
73///
74/// Only the element footprint is counted. The *contents* of a string or bytes
75/// element are not, being already bounded by the input size that
76/// [`DecodeOptions::with_max_message_size`] governs, and packed scalars are not
77/// charged by the generated or view decoders: their worst case there is a
78/// 1-byte varint becoming a 4-byte `i32`, which is not an amplification vector,
79/// and bounding it would reject legitimate columnar payloads that carry
80/// millions of elements by design. The reflective `DynamicMessage` decoder is
81/// the exception — it stores each element as a `Value`, so the same varint
82/// costs `size_of::<Value>()` and is charged accordingly. A columnar payload
83/// decoded reflectively may therefore need this limit raised.
84///
85/// The textproto parser defaults to this same constant, raised through
86/// [`TextDecoder::with_element_memory_limit`](crate::text::TextDecoder::with_element_memory_limit).
87/// `buffa_descriptor`'s reflective JSON parser defaults to it too, raised
88/// through `buffa_descriptor::DynamicMessageSeed::with_element_memory_limit`.
89///
90/// 32 MiB of elements is far more than a realistic message carries, and sits
91/// alongside what [`DEFAULT_UNKNOWN_FIELD_LIMIT`] already permits (~38 MiB of
92/// `UnknownField`). Raise it with
93/// [`DecodeOptions::with_element_memory_limit`] for trusted inputs that
94/// legitimately decode into more. Note `Vec` grows by doubling, so peak
95/// resident memory can reach roughly twice the budget; this bounds what is
96/// materialized, not what the allocator reserves.
97pub const DEFAULT_ELEMENT_MEMORY_LIMIT: usize = 32 * 1024 * 1024;
98
99/// Per-decode limits threaded through every merge call.
100///
101/// Carries the remaining recursion depth and a shared unknown-field
102/// allowance. The context is `Copy` — passing it to a callee hands over the
103/// current depth by value, while the unknown-field allowance lives in a
104/// [`Cell`](core::cell::Cell) owned by the top-level decode entry point, so
105/// every field decoded under one entry point draws from the same
106/// allowance.
107///
108/// It also records where the message being decoded ends in the buffer the
109/// context is passed with. The default [`Message::merge_to_limit`] (and so
110/// [`Message::merge`]) records it; [`Message::merge_length_delimited`], map
111/// entries and
112/// [`decode_string_to_ctx`](crate::types::decode_string_to_ctx) /
113/// [`decode_bytes_to_ctx`](crate::types::decode_bytes_to_ctx) reject a declared
114/// length that runs past it, before decoding what it covers.
115/// [`DecodeContext::new`] records no end, so the whole buffer is allowed.
116///
117/// Because the end belongs to one buffer, hand-written code that decodes a
118/// *different* buffer with a context it was given (a copy of the message, a
119/// decompressed payload) must record that buffer's end first, with
120/// [`with_message_end`](Self::with_message_end) — `0` when the message runs to
121/// the end of that buffer — or start it with the default implementations of
122/// [`Message::merge`] or [`Message::merge_to_limit`], which do so. Otherwise a valid nested field
123/// near the end of that buffer can be rejected with
124/// [`DecodeError::UnexpectedEof`].
125///
126/// Constructed automatically by the [`Message`] convenience methods
127/// ([`decode`](Message::decode), [`decode_from_slice`](Message::decode_from_slice),
128/// [`merge_from_slice`](Message::merge_from_slice)) and by [`DecodeOptions`].
129/// Construct one manually only when calling [`Message::merge`] or the other
130/// depth-threading methods directly — and construct a **fresh limit cell
131/// per top-level decode**. Reusing one cell across decode calls makes the
132/// limit cumulative: each call drains it further until every decode fails
133/// with [`DecodeError::UnknownFieldLimitExceeded`].
134///
135/// ```rust
136/// # use buffa::__doctest_fixtures::Person;
137/// use core::cell::Cell;
138/// use buffa::{DecodeContext, Message, DEFAULT_UNKNOWN_FIELD_LIMIT, RECURSION_LIMIT};
139///
140/// # fn example(mut bytes: &[u8]) -> Result<(), buffa::DecodeError> {
141/// let limit = Cell::new(DEFAULT_UNKNOWN_FIELD_LIMIT);
142/// let mut msg = Person::default();
143/// msg.merge(&mut bytes, DecodeContext::new(RECURSION_LIMIT, &limit))?;
144/// # Ok(())
145/// # }
146/// ```
147#[derive(Clone, Copy, Debug)]
148pub struct DecodeContext<'a> {
149 depth: u32,
150 unknown_fields_remaining: &'a core::cell::Cell<usize>,
151 reject_unknown_fields: bool,
152 element_memory_remaining: Option<&'a core::cell::Cell<usize>>,
153 /// `buf.remaining()` at the end of the innermost enclosing
154 /// length-delimited message; 0 when the message runs to the end of the
155 /// buffer.
156 message_end: usize,
157}
158
159impl<'a> DecodeContext<'a> {
160 /// Create a context with `depth` remaining recursion levels and the
161 /// remaining unknown-field allowance stored in `unknown_field_limit`.
162 #[must_use]
163 pub fn new(depth: u32, unknown_field_limit: &'a core::cell::Cell<usize>) -> Self {
164 Self {
165 depth,
166 unknown_fields_remaining: unknown_field_limit,
167 reject_unknown_fields: unknown_field_limit.get() == 0,
168 element_memory_remaining: None,
169 message_end: 0,
170 }
171 }
172
173 /// The number of bytes of the buffer that follow the innermost enclosing
174 /// length-delimited message, or 0 when it runs to the end of the buffer.
175 #[inline]
176 pub(crate) fn message_end(&self) -> usize {
177 self.message_end
178 }
179
180 /// Record that the message being decoded ends when the buffer this
181 /// context is passed with has `message_end` bytes left, so a field,
182 /// sub-message or map entry of it that would reach further is rejected.
183 ///
184 /// `message_end` is a count of the bytes that *follow* the message, the
185 /// value `buf.remaining()` will have when the message ends: the same
186 /// `limit` that [`Message::merge_to_limit`] takes. It is not the
187 /// message's length or end offset. For a buffer that holds exactly the
188 /// message, pass `0`.
189 ///
190 /// The default [`Message::merge_to_limit`] calls this with its `limit`.
191 /// Call it yourself in a `merge_to_limit` override that calls
192 /// [`Message::merge_field`] directly, passing the `limit` (or `0` when the
193 /// override decodes a buffer holding exactly the message), and before
194 /// decoding a buffer other than the one the context came with.
195 #[inline]
196 #[must_use]
197 pub fn with_message_end(self, message_end: usize) -> Self {
198 Self {
199 message_end,
200 ..self
201 }
202 }
203
204 /// Check a declared length against the enclosing message: the bytes
205 /// `buf` holds before [`message_end`](Self::message_end), given its
206 /// `remaining` bytes.
207 ///
208 /// # Errors
209 ///
210 /// Returns [`DecodeError::UnexpectedEof`] if `len` runs past the end of
211 /// the enclosing message or of the buffer.
212 #[inline]
213 pub(crate) fn check_len(&self, remaining: usize, len: usize) -> Result<(), DecodeError> {
214 // A prefix may already have crossed the boundary. Saturation would
215 // turn that invalid state into a valid zero-length payload.
216 let available = remaining
217 .checked_sub(self.message_end)
218 .ok_or(DecodeError::UnexpectedEof)?;
219 if len > available {
220 return Err(DecodeError::UnexpectedEof);
221 }
222 Ok(())
223 }
224
225 /// Attach the shared element-memory budget in `element_memory_limit`.
226 ///
227 /// Without this the budget is absent and [`register_element_memory`] is a
228 /// no-op, which is what a [`DecodeContext::new`] built elsewhere — older
229 /// generated code, say — gets. buffa's own entry points attach it, so a
230 /// decode through [`DecodeOptions`] or the [`Message`] conveniences is
231 /// bounded by [`DEFAULT_ELEMENT_MEMORY_LIMIT`].
232 ///
233 /// Attach a **fresh cell per top-level decode**, for the same reason the
234 /// unknown-field allowance needs one: a reused cell drains across calls.
235 ///
236 /// [`register_element_memory`]: DecodeContext::register_element_memory
237 #[must_use]
238 pub fn with_element_memory(
239 mut self,
240 element_memory_limit: &'a core::cell::Cell<usize>,
241 ) -> Self {
242 self.element_memory_remaining = Some(element_memory_limit);
243 self
244 }
245
246 /// The remaining recursion depth.
247 #[must_use]
248 pub fn depth(&self) -> u32 {
249 self.depth
250 }
251
252 /// The number of additional unknown fields this decode may materialize.
253 #[must_use]
254 pub fn remaining_unknown_fields(&self) -> usize {
255 self.unknown_fields_remaining.get()
256 }
257
258 /// Whether this decode explicitly rejects all unknown wire fields.
259 /// Exhausting a positive storage budget does not change this policy.
260 #[must_use]
261 pub fn rejects_unknown_fields(&self) -> bool {
262 self.reject_unknown_fields
263 }
264
265 /// Check an unknown occurrence independently of its storage policy.
266 ///
267 /// # Errors
268 /// Returns `UnknownFieldLimitExceeded` when this decode started with a
269 /// zero allowance. Discarded fields do not consume a positive storage budget.
270 pub fn check_unknown_field(&self) -> Result<(), DecodeError> {
271 if self.reject_unknown_fields {
272 Err(DecodeError::UnknownFieldLimitExceeded)
273 } else {
274 Ok(())
275 }
276 }
277
278 // Deferred children replay the rejection policy separately from a storage
279 // allowance that may have reached zero before their bytes were recorded.
280 pub(crate) fn with_unknown_field_rejection(mut self, reject: bool) -> Self {
281 self.reject_unknown_fields = reject;
282 self
283 }
284
285 /// Consume one level of recursion depth.
286 ///
287 /// # Errors
288 ///
289 /// Returns [`DecodeError::RecursionLimitExceeded`] when the depth budget
290 /// is exhausted.
291 pub fn descend(self) -> Result<Self, DecodeError> {
292 let depth = self
293 .depth
294 .checked_sub(1)
295 .ok_or(DecodeError::RecursionLimitExceeded)?;
296 Ok(Self { depth, ..self })
297 }
298
299 /// Consume one slot of the shared unknown-field allowance.
300 ///
301 /// Call before materializing an unknown field. Discarded occurrences use
302 /// `check_unknown_field` instead, preserving the storage budget's meaning.
303 ///
304 /// # Errors
305 ///
306 /// Returns [`DecodeError::UnknownFieldLimitExceeded`] (leaving the
307 /// allowance unchanged) when no slots remain.
308 pub fn register_unknown_field(&self) -> Result<(), DecodeError> {
309 self.check_unknown_field()?;
310 let remaining = self
311 .unknown_fields_remaining
312 .get()
313 .checked_sub(1)
314 .ok_or(DecodeError::UnknownFieldLimitExceeded)?;
315 self.unknown_fields_remaining.set(remaining);
316 Ok(())
317 }
318
319 /// The element-memory budget left to this decode, or `None` when no budget
320 /// is attached.
321 #[must_use]
322 pub fn remaining_element_memory(&self) -> Option<usize> {
323 self.element_memory_remaining.map(core::cell::Cell::get)
324 }
325
326 /// Spend what is left of the element-memory budget, so that every later
327 /// nonzero charge on this context fails.
328 ///
329 /// A caller that drops a value after
330 /// [`ElementMemoryLimitExceeded`](DecodeError::ElementMemoryLimitExceeded)
331 /// and keeps decoding with the same context uses this to make the first
332 /// value that does not fit the last one it reads: a failed charge leaves
333 /// the budget unchanged, so a smaller value after it could otherwise
334 /// still be charged. The bound on the total does not depend on this
335 /// call; it comes from never refunding a charge.
336 pub(crate) fn exhaust_element_memory(&self) {
337 if let Some(cell) = self.element_memory_remaining {
338 cell.set(0);
339 }
340 }
341
342 /// Charge `bytes` against the shared element-memory budget.
343 ///
344 /// Call **before** materializing an element of a repeated
345 /// length-delimited field, passing that element's `size_of`. Those are the
346 /// fields where the wire is far cheaper than what it decodes into: an empty
347 /// message element is two bytes and costs `size_of::<T>()`, so a payload
348 /// well inside [`DecodeOptions::with_max_message_size`] can still expand by
349 /// two orders of magnitude. Packed scalars are not charged by the
350 /// generated or view decoders — there the worst case is a 1-byte varint
351 /// becoming a 4-byte `i32`, and bounding that would reject legitimate
352 /// columnar payloads. The reflective `DynamicMessage` decoder does charge
353 /// them: its store is a `Vec<Value>`, so a 1-byte varint becomes a whole
354 /// `Value` slot and the ratio is an order of magnitude worse.
355 ///
356 /// No-op when no budget is attached (see
357 /// [`with_element_memory`](DecodeContext::with_element_memory)).
358 ///
359 /// # Errors
360 ///
361 /// Returns [`DecodeError::ElementMemoryLimitExceeded`] (leaving the budget
362 /// unchanged) when `bytes` exceeds what remains.
363 pub fn register_element_memory(&self, bytes: usize) -> Result<(), DecodeError> {
364 let Some(cell) = self.element_memory_remaining else {
365 return Ok(());
366 };
367 let remaining = cell.get();
368 if bytes > remaining {
369 return Err(DecodeError::ElementMemoryLimitExceeded);
370 }
371 cell.set(remaining - bytes);
372 Ok(())
373 }
374}
375
376/// Maximum encoded size of a protobuf message: 2 GiB − 1 (`0x7FFF_FFFF`).
377///
378/// The protobuf specification limits any message — top-level or nested — to
379/// 2 GiB. buffa enforces this symmetrically:
380///
381/// - **Decode** rejects length-delimited payloads declared larger than this
382/// with [`DecodeError::MessageTooLarge`], matching protobuf C++ and Java.
383/// - **Encode** refuses to serialize a message whose encoded size would
384/// exceed it: the panicking entry points ([`Message::encode`] and friends)
385/// panic, the `try_*` twins ([`Message::try_encode`] and friends) return
386/// [`EncodeError::MessageTooLarge`]. Without this check a writer could
387/// produce bytes that no conforming decoder — including buffa's own —
388/// will read back.
389pub const MAX_MESSAGE_BYTES: u32 = 0x7FFF_FFFF;
390
391/// Saturate a `u64` size accumulator to `u32`.
392///
393/// Generated `compute_size` implementations accumulate in `u64` (which
394/// cannot overflow for any message that fits in memory) and saturate to
395/// `u32` once at each message node's return. A saturated value is
396/// necessarily greater than [`MAX_MESSAGE_BYTES`], so any over-limit
397/// message — whether from one huge field or from aggregation — surfaces at
398/// the encode entry points' size check; the byte-exact value is preserved
399/// for every message the wire format can actually represent.
400///
401/// Manual [`Message`] implementations should use the same pattern:
402/// accumulate the encoded size in a `u64` and `saturate_size` it at return.
403#[inline]
404#[must_use]
405pub fn saturate_size(size: u64) -> u32 {
406 u32::try_from(size).unwrap_or(u32::MAX)
407}
408
409/// Validate a computed encode size against [`MAX_MESSAGE_BYTES`].
410///
411/// The error-returning half of the encode-size funnel: the `try_encode*`
412/// methods (and generated inherent encode entry points, e.g. on lazy view
413/// types) validate their [`compute_size`](Message::compute_size) result
414/// through this before writing anything.
415///
416/// # Errors
417///
418/// Returns [`EncodeError::MessageTooLarge`] if `size` exceeds
419/// [`MAX_MESSAGE_BYTES`].
420#[inline]
421pub fn checked_encode_size(size: u32) -> Result<u32, EncodeError> {
422 if size > MAX_MESSAGE_BYTES {
423 Err(EncodeError::MessageTooLarge)
424 } else {
425 Ok(size)
426 }
427}
428
429/// Write `msg`, whose encoded size is `size` and whose nested sizes are
430/// recorded in `cache`, into `buf` through the shared pre-sized writer (see
431/// [`encode_sink`](crate::encode_sink)).
432#[inline]
433fn write_sized<M: Message>(
434 msg: &M,
435 size: u32,
436 cache: &mut crate::SizeCache,
437 buf: &mut impl EncodeSink,
438) {
439 crate::encode_sink::write_contiguous(
440 size as usize,
441 cache,
442 buf,
443 |cache, sink| msg.write_to(cache, sink),
444 |cache, sink| msg.write_to(cache, sink),
445 );
446}
447
448/// Debug-build two-pass coherence ledger: asserts `write_to` produced
449/// exactly the byte count `compute_size` declared.
450///
451/// Called by the provided encode entry points (through
452/// `encode_sink::write_contiguous` for a `BufMut`, and directly by
453/// `encode_to_vec` / `try_encode_to_vec` and their generated lazy-view
454/// counterparts) after the write pass; the `*_to_bytes` entry points reach
455/// it through those. The write pass is ground truth — leaf writers emit `len as u64` prefixes and
456/// full payloads — so any divergence indicates a size-pass bug (wrong
457/// presence check, traversal drift) in a generated or manual
458/// implementation. Free in release builds.
459#[doc(hidden)]
460#[inline]
461#[track_caller]
462pub fn debug_assert_two_pass(written: usize, declared: usize) {
463 debug_assert_eq!(
464 written, declared,
465 "write_to produced a different byte count than compute_size \
466 declared (two-pass traversal mismatch)"
467 );
468}
469
470/// Panic shim shared by every panicking encode entry point — the provided
471/// `Message` / `ViewEncode` methods, `SizeCachePool`, and generated
472/// lazy-view inherent methods all delegate to their `try_*` twin and route
473/// the `Err` here, so the panicking and fallible paths cannot diverge.
474///
475/// # Panics
476///
477/// Always — that is its entire job: one cold, out-of-line panic site with
478/// the canonical over-limit message.
479#[doc(hidden)]
480#[cold]
481#[inline(never)]
482pub fn encode_size_overflow() -> ! {
483 panic!(
484 "message encoded size exceeds the 2 GiB protobuf limit \
485 (the try_* variant of this method returns this as an error instead)"
486 )
487}
488
489/// The core trait implemented by all protobuf message types.
490///
491/// This trait is implemented by **generated code** — you write a `.proto` file,
492/// codegen emits the Rust struct and its `Message` impl. You should almost
493/// never implement this trait by hand.
494///
495/// # Manual implementation is discouraged
496///
497/// The only reason to implement `Message` yourself is when you need a
498/// custom in-memory representation that codegen cannot produce — for
499/// example, wrapping a `std::ops::Range<i64>` as a leaf message so the
500/// rest of your code uses the natural Rust type. If you just want a message
501/// type, **write a `.proto` file instead.**
502///
503/// Manual implementation is intentionally high-friction:
504/// - You must correctly implement the two-pass serialization contract
505/// (`compute_size` populates the [`SizeCache`](crate::SizeCache) in the
506/// same traversal order that `write_to` consumes it).
507/// - You must implement wire-format decoding in `merge_field`.
508/// - You must implement the [`DefaultInstance`] supertrait, which provides
509/// the lazily-initialized static default that [`MessageField`](crate::MessageField)
510/// dereferences to when unset.
511///
512/// If you still need to do this, see the [custom types section of the
513/// user guide](https://github.com/anthropics/buffa/blob/main/docs/guide.md#custom-type-implementations)
514/// for a complete worked example.
515///
516/// # Serialization model
517///
518/// Serialization is a two-pass process to avoid the exponential-time problem
519/// that affects prost with deeply nested messages:
520///
521/// 1. **`compute_size()`** — walks the message tree and records the encoded
522/// size of every length-delimited sub-message in a [`SizeCache`].
523/// 2. **`write_to()`** — walks the tree again, writing bytes and consuming
524/// cached sizes for length-prefixed sub-messages.
525///
526/// The provided [`encode`](Self::encode) method performs both passes with a
527/// fresh [`SizeCache`] — most callers use that and never touch the cache
528/// directly. `compute_size` / `write_to` take the cache explicitly so that
529/// manual `Message` implementations can thread it through nested-message
530/// recursion.
531///
532/// # Thread safety
533///
534/// `Message` requires `Send + Sync`. Generated structs contain no interior
535/// mutability — serialization state lives in the external [`SizeCache`], not
536/// in the message — so messages can be placed in an `Arc` and shared across
537/// threads freely. `merge` requires `&mut self`, so mutation is exclusive.
538///
539/// # Struct evolution policy
540///
541/// Generated message structs (and their [`MessageView`](crate::MessageView) /
542/// [`LazyMessageView`](crate::LazyMessageView) counterparts) may gain fields
543/// across releases — both when the source `.proto` schema evolves and when
544/// buffa adds internal bookkeeping such as `__buffa_unknown_fields` or the
545/// required-field presence bitmaps. **Exhaustive struct literals and
546/// exhaustive destructuring patterns are not covered by buffa's semver
547/// guarantees**: code that names every field will fail to compile when a field
548/// is added, and that breakage is not considered a breaking change.
549///
550/// The forward-compatible ways to construct a generated struct are:
551///
552/// - decode it from bytes;
553/// - struct-update syntax over the default: `Foo { x, y, ..Default::default() }`;
554/// - start from `Foo::default()` and assign fields (or call generated `with_*`
555/// setters when `generate_with_setters` is enabled).
556///
557/// The structs are deliberately *not* `#[non_exhaustive]`, so struct-update
558/// syntax remains available from downstream crates; this policy is a documented
559/// contract rather than a compiler-enforced one.
560///
561/// [`SizeCache`]: crate::SizeCache
562pub trait Message: DefaultInstance + Clone + PartialEq + Send + Sync {
563 /// Compute the encoded byte size of this message, recording nested
564 /// sub-message sizes in `cache` for `write_to` to consume.
565 ///
566 /// Most callers should use [`encode`](Self::encode) instead, which runs
567 /// both passes with a fresh cache. Manual `Message` implementations call
568 /// this recursively on nested message fields, wrapping each call in
569 /// [`SizeCache::reserve`] / [`SizeCache::set`] for length-delimited
570 /// fields — see the user guide's custom-types section for the pattern.
571 ///
572 /// # Size limit
573 ///
574 /// The protobuf specification limits messages to 2 GiB
575 /// ([`MAX_MESSAGE_BYTES`]). Generated implementations accumulate in
576 /// `u64` and saturate the return value via [`saturate_size`], so an
577 /// over-limit message yields a return greater than [`MAX_MESSAGE_BYTES`]
578 /// rather than a wrapped value; the provided encode methods check this
579 /// and refuse to produce over-limit output. Manual implementations must
580 /// follow the same pattern — if their arithmetic can wrap, over-limit
581 /// messages may encode corrupt bytes that bypass the check.
582 ///
583 /// [`SizeCache::reserve`]: crate::SizeCache::reserve
584 /// [`SizeCache::set`]: crate::SizeCache::set
585 fn compute_size(&self, cache: &mut crate::SizeCache) -> u32;
586
587 /// Write this message's encoded bytes to a buffer, consuming
588 /// nested-message sizes from `cache` (populated by a prior
589 /// `compute_size` call on the same cache).
590 ///
591 /// Most callers should use [`encode`](Self::encode) instead. This is a
592 /// low-level primitive: the 2 GiB size check ([`MAX_MESSAGE_BYTES`])
593 /// lives in the provided encode entry points, so callers driving
594 /// `compute_size` / `write_to` directly must validate the size
595 /// themselves (via [`checked_encode_size`]).
596 ///
597 /// An implementation must write exactly the number of bytes
598 /// `compute_size` returned. The provided encode methods write a
599 /// `BufMut` into space sized by `compute_size` and panic if `write_to`
600 /// writes more; in debug builds they also panic if it writes fewer.
601 fn write_to(&self, cache: &mut crate::SizeCache, buf: &mut impl EncodeSink);
602
603 /// Compute size, then write. This is the primary encoding API.
604 ///
605 /// The sink can be any [`BufMut`](bytes::BufMut) (contiguous output) or
606 /// a [`Rope`](crate::Rope), which captures large `bytes::Bytes` fields
607 /// as reference-counted segments for zero-copy handoff to networking
608 /// code — see [`encode_sink`](crate::encode_sink).
609 ///
610 /// # Panics
611 ///
612 /// Panics if the encoded size exceeds the 2 GiB protobuf limit
613 /// ([`MAX_MESSAGE_BYTES`]) — see [`try_encode`](Self::try_encode) for
614 /// the error-returning variant.
615 /// Also panics, when `buf` is a [`BufMut`](bytes::BufMut), if a manual
616 /// implementation's `write_to` produces more bytes than its
617 /// `compute_size` declared, and in debug builds if it produces a
618 /// different number.
619 #[inline]
620 fn encode(&self, buf: &mut impl EncodeSink) {
621 self.try_encode(buf)
622 .unwrap_or_else(|_| encode_size_overflow())
623 }
624
625 /// Encode, returning an error instead of panicking if the encoded size
626 /// exceeds the 2 GiB protobuf limit ([`MAX_MESSAGE_BYTES`]).
627 ///
628 /// On `Err`, nothing is written to `buf`.
629 ///
630 /// # Errors
631 ///
632 /// Returns [`EncodeError::MessageTooLarge`] if the encoded size exceeds
633 /// [`MAX_MESSAGE_BYTES`].
634 fn try_encode(&self, buf: &mut impl EncodeSink) -> Result<(), EncodeError> {
635 let mut cache = crate::SizeCache::new();
636 let size = checked_encode_size(self.compute_size(&mut cache))?;
637 write_sized(self, size, &mut cache, buf);
638 Ok(())
639 }
640
641 /// Encode using a caller-supplied [`SizeCache`](crate::SizeCache), for
642 /// reuse across many encodes in a hot loop. Clears the cache first.
643 ///
644 /// # Panics
645 ///
646 /// Panics if the encoded size exceeds the 2 GiB protobuf limit
647 /// ([`MAX_MESSAGE_BYTES`]) — see
648 /// [`try_encode_with_cache`](Self::try_encode_with_cache) for the
649 /// error-returning variant.
650 /// Also panics, when `buf` is a [`BufMut`](bytes::BufMut), if a manual
651 /// implementation's `write_to` produces more bytes than its
652 /// `compute_size` declared, and in debug builds if it produces a
653 /// different number.
654 #[inline]
655 fn encode_with_cache(&self, cache: &mut crate::SizeCache, buf: &mut impl EncodeSink) {
656 self.try_encode_with_cache(cache, buf)
657 .unwrap_or_else(|_| encode_size_overflow())
658 }
659
660 /// Encode with a caller-supplied [`SizeCache`](crate::SizeCache),
661 /// returning an error instead of panicking if the encoded size exceeds
662 /// the 2 GiB protobuf limit ([`MAX_MESSAGE_BYTES`]). Clears the cache
663 /// first.
664 ///
665 /// On `Err`, nothing is written to `buf`.
666 ///
667 /// # Errors
668 ///
669 /// Returns [`EncodeError::MessageTooLarge`] if the encoded size exceeds
670 /// [`MAX_MESSAGE_BYTES`].
671 fn try_encode_with_cache(
672 &self,
673 cache: &mut crate::SizeCache,
674 buf: &mut impl EncodeSink,
675 ) -> Result<(), EncodeError> {
676 cache.clear();
677 let size = checked_encode_size(self.compute_size(cache))?;
678 write_sized(self, size, cache, buf);
679 Ok(())
680 }
681
682 /// Encode this message into `buf` only if its encoded size fits within
683 /// `max_bytes`, using a single size pass that is then reused for the write.
684 ///
685 /// This avoids the double tree-walk that `try_encoded_len` + `encode`
686 /// would require: one `compute_size` pass populates the [`SizeCache`];
687 /// the budget check happens before `write_to` runs, so on `Err` nothing
688 /// is written to `buf`.
689 ///
690 /// Returns the encoded body length on success (excludes any length prefix
691 /// you add for framing) — useful for metrics or frame sizing. Note that
692 /// this return type is `u32`, unlike `try_encode`'s `()`. `max_bytes` is
693 /// also `u32` to match the encode-size domain; callers with a `usize`
694 /// budget can cast with `u32::try_from(budget).unwrap_or(u32::MAX)`.
695 ///
696 /// # Errors
697 ///
698 /// - [`EncodeError::MessageTooLarge`] if the encoded size exceeds the
699 /// 2 GiB protobuf limit ([`MAX_MESSAGE_BYTES`]).
700 /// `MessageTooLarge` takes precedence if both limits are exceeded.
701 /// - [`EncodeError::ExceedsBudget`] if the encoded size is within the
702 /// protobuf limit but exceeds `max_bytes`.
703 ///
704 /// [`SizeCache`]: crate::SizeCache
705 fn try_encode_bounded(
706 &self,
707 max_bytes: u32,
708 buf: &mut impl EncodeSink,
709 ) -> Result<u32, EncodeError> {
710 let mut cache = crate::SizeCache::new();
711 self.try_encode_bounded_with_cache(max_bytes, &mut cache, buf)
712 }
713
714 /// Like [`try_encode_bounded`](Self::try_encode_bounded) but reuses an
715 /// existing [`SizeCache`], clearing it first.
716 ///
717 /// Prefer [`SizeCachePool::try_encode_bounded`](crate::SizeCachePool::try_encode_bounded)
718 /// for hot-loop use — the pool amortizes the cache's spill allocation.
719 ///
720 /// # Errors
721 ///
722 /// Same as [`try_encode_bounded`](Self::try_encode_bounded).
723 ///
724 /// [`SizeCache`]: crate::SizeCache
725 fn try_encode_bounded_with_cache(
726 &self,
727 max_bytes: u32,
728 cache: &mut crate::SizeCache,
729 buf: &mut impl EncodeSink,
730 ) -> Result<u32, EncodeError> {
731 cache.clear();
732 let len = checked_encode_size(self.compute_size(cache))?;
733 if len > max_bytes {
734 return Err(EncodeError::ExceedsBudget { len, max_bytes });
735 }
736 write_sized(self, len, cache, buf);
737 Ok(len)
738 }
739
740 /// Compute the encoded byte size of this message.
741 ///
742 /// Walks the message tree, discarding the intermediate [`SizeCache`].
743 /// If you also intend to encode, prefer [`encode`](Self::encode) or
744 /// [`encode_to_vec`](Self::encode_to_vec) — they do a single size pass
745 /// and reuse the cache for the write.
746 ///
747 /// # Panics
748 ///
749 /// Panics if the encoded size exceeds the 2 GiB protobuf limit
750 /// ([`MAX_MESSAGE_BYTES`]) — see [`try_encoded_len`](Self::try_encoded_len)
751 /// for the error-returning variant.
752 ///
753 /// [`SizeCache`]: crate::SizeCache
754 #[inline]
755 #[must_use]
756 fn encoded_len(&self) -> u32 {
757 self.try_encoded_len()
758 .unwrap_or_else(|_| encode_size_overflow())
759 }
760
761 /// Compute the encoded byte size, returning an error instead of
762 /// panicking if it exceeds the 2 GiB protobuf limit
763 /// ([`MAX_MESSAGE_BYTES`]).
764 ///
765 /// # Errors
766 ///
767 /// Returns [`EncodeError::MessageTooLarge`] if the encoded size exceeds
768 /// [`MAX_MESSAGE_BYTES`].
769 fn try_encoded_len(&self) -> Result<u32, EncodeError> {
770 checked_encode_size(self.compute_size(&mut crate::SizeCache::new()))
771 }
772
773 /// Encode this message as a length-delimited byte sequence.
774 ///
775 /// # Panics
776 ///
777 /// Panics if the encoded size exceeds the 2 GiB protobuf limit
778 /// ([`MAX_MESSAGE_BYTES`]); the check runs before the length prefix is
779 /// written, so nothing reaches `buf` on failure. See
780 /// [`try_encode_length_delimited`](Self::try_encode_length_delimited)
781 /// for the error-returning variant.
782 /// Also panics, when `buf` is a [`BufMut`](bytes::BufMut), if a manual
783 /// implementation's `write_to` produces more bytes than its
784 /// `compute_size` declared, and in debug builds if it produces a
785 /// different number.
786 #[inline]
787 fn encode_length_delimited(&self, buf: &mut impl EncodeSink) {
788 self.try_encode_length_delimited(buf)
789 .unwrap_or_else(|_| encode_size_overflow())
790 }
791
792 /// Encode as a length-delimited byte sequence, returning an error
793 /// instead of panicking if the encoded size exceeds the 2 GiB protobuf
794 /// limit ([`MAX_MESSAGE_BYTES`]).
795 ///
796 /// On `Err`, nothing is written to `buf`.
797 ///
798 /// # Errors
799 ///
800 /// Returns [`EncodeError::MessageTooLarge`] if the encoded size exceeds
801 /// [`MAX_MESSAGE_BYTES`].
802 fn try_encode_length_delimited(&self, buf: &mut impl EncodeSink) -> Result<(), EncodeError> {
803 let mut cache = crate::SizeCache::new();
804 let len = checked_encode_size(self.compute_size(&mut cache))?;
805 crate::encoding::encode_varint(u64::from(len), buf);
806 write_sized(self, len, &mut cache, buf);
807 Ok(())
808 }
809
810 /// Encode this message to a new `Vec<u8>`.
811 ///
812 /// # Panics
813 ///
814 /// Panics if the encoded size exceeds the 2 GiB protobuf limit
815 /// ([`MAX_MESSAGE_BYTES`]) — see
816 /// [`try_encode_to_vec`](Self::try_encode_to_vec) for the
817 /// error-returning variant. Also panics if a manual
818 /// implementation's `write_to` produces more bytes than its
819 /// `compute_size` declared, and in debug builds if it produces a
820 /// different number.
821 // Direct body rather than delegating to try_encode_to_vec: LLVM does
822 // not fold the Result<Vec<u8>> niche away even under full inlining, so
823 // the delegating form re-checks the capacity sentinel and round-trips
824 // the Vec through a Result temp in every caller — measured +7.5% on
825 // dense-small-message encode (google_message1, quieted metal,
826 // layout-normalized). `encode_to_bytes` reuses this infallible body via
827 // `Bytes::from`. The unit- and scalar-returning entry points delegate —
828 // their Results stay in registers and fold cleanly.
829 #[inline]
830 #[must_use]
831 fn encode_to_vec(&self) -> alloc::vec::Vec<u8> {
832 let mut cache = crate::SizeCache::new();
833 let size = match checked_encode_size(self.compute_size(&mut cache)) {
834 Ok(size) => size as usize,
835 Err(_) => encode_size_overflow(),
836 };
837 let buf =
838 crate::encode_sink::write_to_new_vec(size, |sink| self.write_to(&mut cache, sink));
839 debug_assert_two_pass(buf.len(), size);
840 buf
841 }
842
843 /// Encode to a new `Vec<u8>`, returning an error instead of panicking
844 /// if the encoded size exceeds the 2 GiB protobuf limit
845 /// ([`MAX_MESSAGE_BYTES`]).
846 ///
847 /// # Errors
848 ///
849 /// Returns [`EncodeError::MessageTooLarge`] if the encoded size exceeds
850 /// [`MAX_MESSAGE_BYTES`].
851 ///
852 /// # Panics
853 ///
854 /// Panics if a manual implementation's `write_to` produces more
855 /// bytes than its `compute_size` declared, and in debug builds if it
856 /// produces a different number.
857 fn try_encode_to_vec(&self) -> Result<alloc::vec::Vec<u8>, EncodeError> {
858 let mut cache = crate::SizeCache::new();
859 let size = checked_encode_size(self.compute_size(&mut cache))? as usize;
860 let buf =
861 crate::encode_sink::write_to_new_vec(size, |sink| self.write_to(&mut cache, sink));
862 debug_assert_two_pass(buf.len(), size);
863 Ok(buf)
864 }
865
866 /// Encode this message to a new [`bytes::Bytes`].
867 ///
868 /// Useful when handing off to networking code (hyper, tonic, axum)
869 /// that expects `Bytes` frame or body payloads. Works in `no_std`.
870 ///
871 /// This is `Bytes::from(self.encode_to_vec())` — zero-copy and
872 /// allocation-free for the exactly-sized vector `encode_to_vec` returns —
873 /// and saves readers from having to know that `From<Vec<u8>> for Bytes`
874 /// is zero-copy. Because it is defined in terms of
875 /// [`encode_to_vec`](Self::encode_to_vec), an implementation that
876 /// overrides that method must not call this one from it.
877 ///
878 /// # Panics
879 ///
880 /// Panics if the encoded size exceeds the 2 GiB protobuf limit
881 /// ([`MAX_MESSAGE_BYTES`]) — see
882 /// [`try_encode_to_bytes`](Self::try_encode_to_bytes) for the
883 /// error-returning variant. Also panics if a manual
884 /// implementation's `write_to` produces more bytes than its
885 /// `compute_size` declared, and in debug builds if it produces a
886 /// different number.
887 // Encodes into an exactly-sized `Vec<u8>` and converts:
888 // `From<Vec<u8>> for Bytes` is zero-copy and allocation-free for it.
889 #[inline]
890 #[must_use]
891 fn encode_to_bytes(&self) -> bytes::Bytes {
892 bytes::Bytes::from(self.encode_to_vec())
893 }
894
895 /// Encode to a new [`bytes::Bytes`], returning an error instead of
896 /// panicking if the encoded size exceeds the 2 GiB protobuf limit
897 /// ([`MAX_MESSAGE_BYTES`]).
898 ///
899 /// # Errors
900 ///
901 /// Returns [`EncodeError::MessageTooLarge`] if the encoded size exceeds
902 /// [`MAX_MESSAGE_BYTES`].
903 ///
904 /// # Panics
905 ///
906 /// Panics if a manual implementation's `write_to` produces more
907 /// bytes than its `compute_size` declared, and in debug builds if it
908 /// produces a different number.
909 fn try_encode_to_bytes(&self) -> Result<bytes::Bytes, EncodeError> {
910 self.try_encode_to_vec().map(bytes::Bytes::from)
911 }
912
913 /// Decode a message from a buffer.
914 fn decode(buf: &mut impl Buf) -> Result<Self, DecodeError>
915 where
916 Self: Sized,
917 {
918 let limit = core::cell::Cell::new(DEFAULT_UNKNOWN_FIELD_LIMIT);
919 let elem_budget = core::cell::Cell::new(DEFAULT_ELEMENT_MEMORY_LIMIT);
920 let mut msg = Self::default();
921 msg.merge(
922 buf,
923 DecodeContext::new(RECURSION_LIMIT, &limit).with_element_memory(&elem_budget),
924 )?;
925 Ok(msg)
926 }
927
928 /// Decode a message from a byte slice.
929 ///
930 /// Convenience wrapper around [`decode`](Self::decode) that avoids the
931 /// `&mut bytes.as_slice()` incantation.
932 fn decode_from_slice(mut data: &[u8]) -> Result<Self, DecodeError>
933 where
934 Self: Sized,
935 {
936 // `mut data` creates a local mutable copy of the fat pointer so that
937 // `Buf::advance` can move the read cursor without affecting the caller.
938 Self::decode(&mut data)
939 }
940
941 /// Decode a length-delimited message from a buffer.
942 ///
943 /// This is a **top-level** entry point. It reads a varint length prefix,
944 /// then decodes using arithmetic bounds checking, calling
945 /// [`merge_to_limit`](Self::merge_to_limit) with a fresh
946 /// [`RECURSION_LIMIT`] budget. Any sub-messages inside are decoded via
947 /// [`merge_length_delimited`](Self::merge_length_delimited), which tracks
948 /// and decrements the budget.
949 ///
950 /// Do **not** call this method from within a
951 /// [`merge_to_limit`](Self::merge_to_limit) implementation to decode a
952 /// nested sub-message field; use
953 /// [`merge_length_delimited`](Self::merge_length_delimited) instead so
954 /// that the caller's depth budget is propagated correctly.
955 fn decode_length_delimited(buf: &mut impl Buf) -> Result<Self, DecodeError>
956 where
957 Self: Sized,
958 {
959 // Refuse messages larger than 2 GiB to prevent allocating attacker-
960 // controlled amounts of memory from a crafted length prefix.
961 let len_u64 = crate::encoding::decode_varint(buf)?;
962 if len_u64 > MAX_MESSAGE_BYTES as u64 {
963 return Err(DecodeError::MessageTooLarge);
964 }
965 // Safe on 32-bit: len_u64 <= 2 GiB - 1 < u32::MAX, so the cast never truncates.
966 let len = usize::try_from(len_u64).map_err(|_| DecodeError::MessageTooLarge)?;
967 if buf.remaining() < len {
968 return Err(DecodeError::UnexpectedEof);
969 }
970 // Arithmetic limit: decode `len` bytes from the buffer without
971 // wrapping it in `Take`. This keeps the buffer type `B` unchanged
972 // through every recursion level, avoiding E0275 for recursive
973 // message types like `google.protobuf.Struct ↔ Value`.
974 let limit = buf.remaining() - len;
975 let field_limit = core::cell::Cell::new(DEFAULT_UNKNOWN_FIELD_LIMIT);
976 let elem_budget = core::cell::Cell::new(DEFAULT_ELEMENT_MEMORY_LIMIT);
977 let mut msg = Self::default();
978 // Recorded here as well as by the default `merge_to_limit`, so an
979 // override that does not record it is still bounded by the frame.
980 msg.merge_to_limit(
981 buf,
982 DecodeContext::new(RECURSION_LIMIT, &field_limit)
983 .with_element_memory(&elem_budget)
984 .with_message_end(limit),
985 limit,
986 )?;
987 if buf.remaining() != limit {
988 let remaining = buf.remaining();
989 if remaining > limit {
990 buf.advance(remaining - limit);
991 } else {
992 return Err(DecodeError::UnexpectedEof);
993 }
994 }
995 Ok(msg)
996 }
997
998 /// Processes a single already-decoded tag and its associated field data
999 /// from `buf`.
1000 ///
1001 /// This is the per-field dispatch method generated for each message type.
1002 /// Both [`merge_to_limit`](Self::merge_to_limit) and
1003 /// [`merge_group`](Self::merge_group) call this in their respective loops.
1004 ///
1005 /// `ctx` carries the remaining nesting depth and the shared allocation
1006 /// budget.
1007 ///
1008 /// # Errors
1009 ///
1010 /// Returns a [`DecodeError`] if:
1011 /// - the buffer is truncated or malformed,
1012 /// - a wire-type mismatch is detected for a known field,
1013 /// - the recursion limit is exceeded, or
1014 /// - the allocation budget is exhausted.
1015 fn merge_field(
1016 &mut self,
1017 tag: crate::encoding::Tag,
1018 buf: &mut impl Buf,
1019 ctx: DecodeContext<'_>,
1020 ) -> Result<(), DecodeError>;
1021
1022 /// Merge fields from a buffer until `buf.remaining()` reaches `limit`.
1023 ///
1024 /// This is the core decode loop. [`merge`](Self::merge) delegates to this
1025 /// with `limit = 0` (read until exhausted).
1026 /// [`merge_length_delimited`](Self::merge_length_delimited) computes
1027 /// `limit` from the declared sub-message length and calls this directly.
1028 ///
1029 /// The caller must ensure `limit <= buf.remaining()`. The default
1030 /// implementations of [`merge`](Self::merge) and
1031 /// [`merge_length_delimited`](Self::merge_length_delimited) uphold this
1032 /// invariant.
1033 ///
1034 /// `ctx` carries the remaining nesting depth and the shared allocation
1035 /// budget. Each call to
1036 /// [`merge_length_delimited`](Self::merge_length_delimited) consumes one
1037 /// depth level before recursing; when the depth reaches zero the call
1038 /// returns [`DecodeError::RecursionLimitExceeded`]. The default
1039 /// implementation records `limit` in `ctx` as the end of the message
1040 /// ([`DecodeContext::with_message_end`]), so a sub-message, map entry, or
1041 /// custom string or bytes field of it whose declared length runs past
1042 /// `limit` is rejected before it is decoded. Other fields are checked only
1043 /// against the buffer, so a caller passing `limit > 0` must still check
1044 /// that `buf.remaining() == limit` afterwards, as
1045 /// [`merge_length_delimited`](Self::merge_length_delimited) does. An
1046 /// override should record `limit` the same way; `merge_length_delimited`
1047 /// and the length-delimited decode entry points also record it before
1048 /// calling this, so an override called from them is bounded either way.
1049 fn merge_to_limit(
1050 &mut self,
1051 buf: &mut impl Buf,
1052 ctx: DecodeContext<'_>,
1053 limit: usize,
1054 ) -> Result<(), DecodeError> {
1055 let ctx = ctx.with_message_end(limit);
1056 while buf.remaining() > limit {
1057 let tag = crate::encoding::Tag::decode(buf)?;
1058 self.merge_field(tag, buf, ctx)?;
1059 }
1060 Ok(())
1061 }
1062
1063 /// Merges a group-encoded message from `buf`, reading fields until an
1064 /// EndGroup tag with the given `field_number` is encountered.
1065 ///
1066 /// Proto2 groups use StartGroup/EndGroup wire types instead of
1067 /// length-delimited encoding. The opening StartGroup tag has already been
1068 /// consumed by the caller; this method reads the group body and the
1069 /// closing EndGroup tag.
1070 ///
1071 /// # Errors
1072 ///
1073 /// Returns a [`DecodeError`] if:
1074 /// - the buffer is truncated before the EndGroup tag,
1075 /// - an EndGroup tag is encountered with a mismatched field number,
1076 /// - a wire-type mismatch is detected for a known field, or
1077 /// - the recursion limit is exceeded.
1078 fn merge_group(
1079 &mut self,
1080 buf: &mut impl Buf,
1081 ctx: DecodeContext<'_>,
1082 field_number: u32,
1083 ) -> Result<(), DecodeError> {
1084 let ctx = ctx.descend()?;
1085 loop {
1086 if !buf.has_remaining() {
1087 return Err(DecodeError::UnexpectedEof);
1088 }
1089 let tag = crate::encoding::Tag::decode(buf)?;
1090 if tag.wire_type() == crate::encoding::WireType::EndGroup {
1091 return if tag.field_number() == field_number {
1092 Ok(())
1093 } else {
1094 Err(DecodeError::InvalidEndGroup(tag.field_number()))
1095 };
1096 }
1097 self.merge_field(tag, buf, ctx)?;
1098 }
1099 }
1100
1101 /// Merge fields from a buffer into this message.
1102 ///
1103 /// Fields that are already set will be overwritten for singular fields,
1104 /// or appended for repeated fields, following standard protobuf merge
1105 /// semantics.
1106 ///
1107 /// `ctx` carries the remaining nesting depth and the shared allocation
1108 /// budget. Each call to
1109 /// [`merge_length_delimited`](Self::merge_length_delimited) consumes one
1110 /// depth level before recursing; when the depth reaches zero the call
1111 /// returns [`DecodeError::RecursionLimitExceeded`]. Construct a fresh
1112 /// [`DecodeContext`] at the outermost call site, or use the convenience
1113 /// methods ([`decode`](Self::decode),
1114 /// [`merge_from_slice`](Self::merge_from_slice)) which do this
1115 /// automatically.
1116 fn merge(&mut self, buf: &mut impl Buf, ctx: DecodeContext<'_>) -> Result<(), DecodeError> {
1117 self.merge_to_limit(buf, ctx, 0)
1118 }
1119
1120 /// Merge fields from a byte slice into this message.
1121 ///
1122 /// Convenience wrapper around [`merge`](Self::merge) that avoids the
1123 /// `&mut bytes.as_slice()` incantation.
1124 fn merge_from_slice(&mut self, mut data: &[u8]) -> Result<(), DecodeError> {
1125 let limit = core::cell::Cell::new(DEFAULT_UNKNOWN_FIELD_LIMIT);
1126 let elem_budget = core::cell::Cell::new(DEFAULT_ELEMENT_MEMORY_LIMIT);
1127 self.merge(
1128 &mut data,
1129 DecodeContext::new(RECURSION_LIMIT, &limit).with_element_memory(&elem_budget),
1130 )
1131 }
1132
1133 /// Merge fields from a length-delimited sub-message payload into this message.
1134 ///
1135 /// Reads a varint length prefix, then calls [`merge_to_limit`](Self::merge_to_limit)
1136 /// with an arithmetic bound derived from the declared sub-message length.
1137 /// The buffer type `B` passes through unchanged at every recursion level,
1138 /// avoiding the `E0275` trait-solver recursion limit that occurs with
1139 /// `Take<&mut Take<&mut T>>` type growth.
1140 ///
1141 /// Used by generated code when decoding singular `MessageField<T>` fields
1142 /// — the sub-message is merged into the existing value rather than
1143 /// replaced, per protobuf merge semantics.
1144 ///
1145 /// `ctx` carries the remaining nesting depth and the shared allocation
1146 /// budget passed down from the enclosing
1147 /// [`merge_to_limit`](Self::merge_to_limit) call. This method consumes
1148 /// one depth level before calling the inner `merge_to_limit`; when the
1149 /// depth reaches zero it returns
1150 /// [`DecodeError::RecursionLimitExceeded`].
1151 ///
1152 /// Enforces the same 2 GiB safety limit as [`decode_length_delimited`](Self::decode_length_delimited).
1153 ///
1154 /// # Errors
1155 ///
1156 /// Returns an error if the buffer is too short or the declared length runs
1157 /// past the end of the message being decoded with `ctx` (both
1158 /// [`DecodeError::UnexpectedEof`]), if the declared length exceeds 2 GiB,
1159 /// if the recursion limit is reached, or if the inner `merge_to_limit`
1160 /// call fails.
1161 fn merge_length_delimited(
1162 &mut self,
1163 buf: &mut impl Buf,
1164 ctx: DecodeContext<'_>,
1165 ) -> Result<(), DecodeError> {
1166 let ctx = ctx.descend()?;
1167 let len_u64 = crate::encoding::decode_varint(buf)?;
1168 if len_u64 > MAX_MESSAGE_BYTES as u64 {
1169 return Err(DecodeError::MessageTooLarge);
1170 }
1171 let len = usize::try_from(len_u64).map_err(|_| DecodeError::MessageTooLarge)?;
1172 // The sub-message must also end within the message that holds it.
1173 ctx.check_len(buf.remaining(), len)?;
1174 // Arithmetic limit: the sub-message occupies `len` bytes, so the
1175 // decode loop should stop when `buf.remaining()` drops to
1176 // `remaining - len`. This avoids wrapping the buffer in `Take`,
1177 // which would grow the type at each recursion level and trigger
1178 // E0275 for recursive message types like `Struct ↔ Value`.
1179 let limit = buf.remaining() - len;
1180 // Recorded here as well as by the default `merge_to_limit`, so an
1181 // override that does not record it is still bounded by the sub-message.
1182 self.merge_to_limit(buf, ctx.with_message_end(limit), limit)?;
1183 if buf.remaining() != limit {
1184 let remaining = buf.remaining();
1185 if remaining > limit {
1186 // Sub-message consumed fewer bytes than declared; skip the rest.
1187 buf.advance(remaining - limit);
1188 } else {
1189 return Err(DecodeError::UnexpectedEof);
1190 }
1191 }
1192 Ok(())
1193 }
1194
1195 /// Clear all fields to their default values.
1196 fn clear(&mut self);
1197}
1198
1199/// Compile-time access to a generated message's protobuf identifiers.
1200///
1201/// Generic code that needs to *name* a message type — type-erased event
1202/// registries, structured logging, `Any` packing, schema lookups — can
1203/// bound on `T: MessageName` and read [`PACKAGE`], [`NAME`],
1204/// [`FULL_NAME`], or [`TYPE_URL`] without descriptor machinery or runtime
1205/// reflection. All four are `&'static str` literals computed at codegen
1206/// time, so there's no allocation or concatenation at runtime — unlike
1207/// `prost::Name`, whose `full_name()` and `type_url()` are runtime
1208/// `format!` calls.
1209///
1210/// Bring `buffa::MessageName` into scope to use `MyMessage::FULL_NAME`.
1211/// Without the trait in scope, use
1212/// `<MyMessage as buffa::MessageName>::FULL_NAME`.
1213///
1214/// Codegen implements `MessageName` for both the owned message type and
1215/// its zero-copy view type (`MyMessageView<'a>`), so the same generic
1216/// bound dispatches either. The trait has **no** [`Message`] supertrait —
1217/// it doesn't reach into the wire codec and a name-keyed registry should
1218/// be able to register a type without proving it can encode.
1219///
1220/// Hand-written [`Message`] implementations can opt in by also
1221/// implementing `MessageName`; it is a separate trait specifically so
1222/// that omitting it stays non-breaking. For messages that also implement
1223/// [`ExtensionSet`](crate::ExtensionSet), [`FULL_NAME`] is guaranteed
1224/// equal to [`ExtensionSet::PROTO_FQN`](crate::ExtensionSet::PROTO_FQN);
1225/// the inherent `MyMessage::TYPE_URL` const is equal to [`TYPE_URL`].
1226/// All derive from the same `proto_fqn` source in codegen.
1227///
1228/// Because the only items are associated `const`s, this trait is **not**
1229/// object-safe (`dyn MessageName` does not compile). Use it as a generic
1230/// bound (`fn foo<T: MessageName>()`), not a trait object.
1231///
1232/// ```
1233/// # use buffa::MessageName;
1234/// /// A name-keyed registry can register any `MessageName` type — owned
1235/// /// or view — without proving it can encode.
1236/// fn registry_key<T: MessageName>() -> &'static str {
1237/// T::FULL_NAME
1238/// }
1239/// # // No generated types in `buffa` itself; just check it monomorphises.
1240/// # struct Demo;
1241/// # impl MessageName for Demo {
1242/// # const PACKAGE: &'static str = "demo";
1243/// # const NAME: &'static str = "Demo";
1244/// # const FULL_NAME: &'static str = "demo.Demo";
1245/// # const TYPE_URL: &'static str = "type.googleapis.com/demo.Demo";
1246/// # }
1247/// assert_eq!(registry_key::<Demo>(), "demo.Demo");
1248/// ```
1249///
1250/// [`PACKAGE`]: Self::PACKAGE
1251/// [`NAME`]: Self::NAME
1252/// [`FULL_NAME`]: Self::FULL_NAME
1253/// [`TYPE_URL`]: Self::TYPE_URL
1254pub trait MessageName {
1255 /// The protobuf package the message is declared in.
1256 ///
1257 /// `"my.pkg"` for `package my.pkg;`. Empty string for the unnamed
1258 /// root package. Does not include a leading or trailing dot.
1259 const PACKAGE: &'static str;
1260
1261 /// The unqualified message name, with `.` between nesting levels.
1262 ///
1263 /// `"Foo"` for a top-level message; `"Outer.Inner"` for a message
1264 /// nested inside `Outer`. This is the "type name relative to the
1265 /// package" — what `prost::Name::NAME` calls the same thing — *not*
1266 /// `DescriptorProto.name`, which is only the leaf segment (`"Inner"`)
1267 /// for nested types.
1268 const NAME: &'static str;
1269
1270 /// The fully-qualified protobuf type name with no leading dot.
1271 ///
1272 /// `"my.pkg.Outer.Inner"` for a nested message in package `my.pkg`,
1273 /// or just `"Foo"` for a top-level message in the unnamed root
1274 /// package. Equal to `PACKAGE` + `"."` + `NAME` (with the joining
1275 /// dot omitted when `PACKAGE` is empty); shipped as its own const
1276 /// because consumers almost always want the joined form and the
1277 /// dotted string can't be re-split unambiguously
1278 /// (`foo.Bar.Baz` could be package `foo.Bar` + message `Baz`, or
1279 /// package `foo` + nested `Bar.Baz`).
1280 const FULL_NAME: &'static str;
1281
1282 /// The `google.protobuf.Any.type_url` form for this message.
1283 ///
1284 /// `"type.googleapis.com/" + FULL_NAME`. This is the value the
1285 /// runtime stores in [`Any::type_url`] when packing a message, and
1286 /// the one a generic `Any` registry should key on.
1287 ///
1288 /// [`Any::type_url`]: https://protobuf.dev/programming-guides/proto3/#any
1289 const TYPE_URL: &'static str;
1290}
1291
1292/// Options for configuring message decoding behavior.
1293///
1294/// Use this to set custom recursion depth limits or maximum message sizes
1295/// when decoding from untrusted input.
1296///
1297/// # Scope: the protobuf binary codec
1298///
1299/// Every limit here bounds the binary decoders — owned, view, and the
1300/// reflective `DynamicMessage` codec — and only those. Decoding the same
1301/// message from JSON goes through `serde_json` (or another `Deserializer`)
1302/// straight into the generated `Deserialize` impls, which never see a
1303/// `DecodeOptions`, so none of these limits apply to it. JSON input that must
1304/// be bounded needs a bound imposed by the caller, for example by capping the
1305/// input length before parsing.
1306///
1307/// One JSON path applies an element-memory limit of its own:
1308/// `buffa_descriptor`'s reflective parser (`DynamicMessage::from_json`)
1309/// charges the repeated elements and map entries it builds against a limit
1310/// that defaults to [`DEFAULT_ELEMENT_MEMORY_LIMIT`] and is changed with
1311/// `buffa_descriptor::DynamicMessageSeed::with_element_memory_limit`, not
1312/// here. The parser also charges that limit for the buffer it reads a
1313/// `google.protobuf.Any` payload into, until it has decoded the payload.
1314///
1315/// # Examples
1316///
1317/// ```no_run
1318/// # use buffa::__doctest_fixtures::Person;
1319/// use buffa::DecodeOptions;
1320///
1321/// # fn example(bytes: &[u8]) -> Result<(), buffa::DecodeError> {
1322/// // Restrict recursion depth to 50 and message size to 1 MiB:
1323/// let msg: Person = DecodeOptions::new()
1324/// .with_recursion_limit(50)
1325/// .with_max_message_size(1024 * 1024)
1326/// .decode_from_slice(bytes)?;
1327/// # Ok(())
1328/// # }
1329/// ```
1330#[derive(Debug, Clone)]
1331pub struct DecodeOptions {
1332 recursion_limit: u32,
1333 max_message_size: usize,
1334 unbounded_reader_size: bool,
1335 unknown_field_limit: usize,
1336 element_memory_limit: usize,
1337 clear_on_merge_error: bool,
1338}
1339
1340/// Default maximum message size: 2 GiB - 1 (matches the sub-message limit
1341/// in `merge_length_delimited` and the encode-side limit — see
1342/// [`MAX_MESSAGE_BYTES`]).
1343const DEFAULT_MAX_MESSAGE_SIZE: usize = MAX_MESSAGE_BYTES as usize;
1344
1345impl Default for DecodeOptions {
1346 fn default() -> Self {
1347 Self::new()
1348 }
1349}
1350
1351impl DecodeOptions {
1352 /// Create new decode options with defaults.
1353 ///
1354 /// Defaults:
1355 /// - `recursion_limit`: 100 (same as [`RECURSION_LIMIT`])
1356 /// - `max_message_size`: 2 GiB - 1
1357 /// - `unknown_field_limit`: 1,000,000 (same as [`DEFAULT_UNKNOWN_FIELD_LIMIT`])
1358 /// - `element_memory_limit`: 32 MiB (same as [`DEFAULT_ELEMENT_MEMORY_LIMIT`])
1359 pub fn new() -> Self {
1360 Self {
1361 recursion_limit: RECURSION_LIMIT,
1362 max_message_size: DEFAULT_MAX_MESSAGE_SIZE,
1363 unbounded_reader_size: false,
1364 unknown_field_limit: DEFAULT_UNKNOWN_FIELD_LIMIT,
1365 element_memory_limit: DEFAULT_ELEMENT_MEMORY_LIMIT,
1366 clear_on_merge_error: false,
1367 }
1368 }
1369
1370 /// Set the maximum recursion depth for nested messages.
1371 ///
1372 /// Each nested sub-message consumes one level of depth budget. When
1373 /// the budget reaches zero, decoding returns
1374 /// [`DecodeError::RecursionLimitExceeded`].
1375 ///
1376 /// Default: 100.
1377 #[must_use]
1378 pub fn with_recursion_limit(mut self, limit: u32) -> Self {
1379 self.recursion_limit = limit;
1380 self
1381 }
1382
1383 /// Set the maximum total message size in bytes.
1384 ///
1385 /// If the input buffer or length-delimited payload exceeds this size,
1386 /// decoding returns [`DecodeError::MessageTooLarge`].
1387 ///
1388 /// Values above the protobuf message-size limit (2 GiB - 1) are clamped to
1389 /// that limit. Debug builds assert on out-of-range values so accidental
1390 /// `usize::MAX` sentinels are caught during development. On `std` builds,
1391 /// use `without_reader_size_limit` when EOF-bounded `decode_reader` input
1392 /// intentionally has no byte cap.
1393 ///
1394 /// Calling this re-enables the reader byte cap, overriding any prior
1395 /// `without_reader_size_limit`.
1396 ///
1397 /// This is checked at the top-level decode entry point. Individual
1398 /// sub-messages are still bounded by the internal 2 GiB limit
1399 /// regardless of this setting.
1400 ///
1401 /// Default: 2 GiB - 1 (0x7FFF_FFFF).
1402 #[must_use]
1403 pub fn with_max_message_size(mut self, max_bytes: usize) -> Self {
1404 debug_assert!(
1405 max_bytes <= DEFAULT_MAX_MESSAGE_SIZE,
1406 "DecodeOptions::with_max_message_size clamps values above the protobuf 2 GiB limit; \
1407 on std builds, use DecodeOptions::without_reader_size_limit for intentionally \
1408 unbounded reader input — there is no unbounded slice/Buf path"
1409 );
1410 self.max_message_size = max_bytes.min(DEFAULT_MAX_MESSAGE_SIZE);
1411 self.unbounded_reader_size = false;
1412 self
1413 }
1414
1415 /// Remove the byte cap for EOF-bounded [`decode_reader`](Self::decode_reader)
1416 /// input.
1417 ///
1418 /// This is only used by the `std::io::Read` entry point that reads until
1419 /// EOF. Slice-, [`Buf`]-, and view-based entry points remain bounded by
1420 /// the configured [`with_max_message_size`](Self::with_max_message_size)
1421 /// (itself capped at the protobuf 2 GiB - 1 maximum), and length-delimited
1422 /// paths keep the same hard cap because their declared length is
1423 /// attacker-controlled.
1424 ///
1425 /// An unbounded reader can exhaust memory if the source does not end or is
1426 /// larger than available allocation capacity. Prefer
1427 /// [`with_max_message_size`](Self::with_max_message_size) for untrusted
1428 /// input.
1429 #[cfg(feature = "std")]
1430 #[must_use]
1431 pub fn without_reader_size_limit(mut self) -> Self {
1432 self.unbounded_reader_size = true;
1433 self
1434 }
1435
1436 /// Set the maximum number of unknown fields decoded per decode call.
1437 ///
1438 /// Preserved unknown fields consume this allowance. A zero allowance also
1439 /// rejects discarded unknown wire fields regardless of storage configuration.
1440 /// Positive limits retain their storage-budget semantics.
1441 ///
1442 /// Each preserved unknown field occupies a ~40-byte
1443 /// [`UnknownField`](crate::UnknownField) slot regardless of its wire
1444 /// size (a minimal field is 2 wire bytes — a ~20× amplification), so an
1445 /// input-size cap alone does not bound decoder memory; this limit does,
1446 /// at roughly `limit × 40` bytes of slot overhead. Unknown
1447 /// length-delimited *payload* bytes are not counted — they are bounded
1448 /// by the input size, which
1449 /// [`with_max_message_size`](Self::with_max_message_size) governs. When
1450 /// the limit is exceeded, decoding returns
1451 /// [`DecodeError::UnknownFieldLimitExceeded`].
1452 ///
1453 /// Zero-copy view decoding ([`decode_view`](Self::decode_view)) charges
1454 /// one slot per unknown field — including fields nested inside unknown
1455 /// groups — even though views store unknown fields as coalesced spans
1456 /// (~16 bytes per contiguous run): coalescing bounds view memory, while
1457 /// this limit bounds what converting the view to an owned message would
1458 /// materialize. Conversion replays under exactly the budget decoding
1459 /// charged, so a view that decodes within this limit always converts.
1460 ///
1461 /// Default: 1,000,000 ([`DEFAULT_UNKNOWN_FIELD_LIMIT`]).
1462 #[must_use]
1463 pub fn with_unknown_field_limit(mut self, count: usize) -> Self {
1464 self.unknown_field_limit = count;
1465 self
1466 }
1467
1468 /// Reject unknown wire fields independently of generated storage settings.
1469 /// Equivalent to a zero unknown-field allowance. Unknown closed-enum values
1470 /// are included; open-enum numbers remain valid values of known fields.
1471 /// Generated static messages retain extensions, MessageSet items and custom
1472 /// descriptor options as unknown fields, so they are rejected too. A dynamic
1473 /// message can recognize extensions registered in its descriptor pool.
1474 ///
1475 /// Deferred lazy children are checked only when materialized: constructing a
1476 /// lazy view alone does not establish rejection throughout its subtree.
1477 #[must_use]
1478 pub fn reject_unknown_fields(self) -> Self {
1479 self.with_unknown_field_limit(0)
1480 }
1481
1482 /// Set the memory this decode may materialize in the elements of
1483 /// length-delimited containers — repeated message, string and bytes fields,
1484 /// and map entries — shared across the whole decode tree rather than per
1485 /// field or per message.
1486 ///
1487 /// The lazy view family is the exception: there the budget is replayed
1488 /// per deferred subtree rather than shared, so a full traversal can
1489 /// spend it more than once. See
1490 /// [`decode_lazy_view`](Self::decode_lazy_view).
1491 ///
1492 /// This is not [`with_max_message_size`](Self::with_max_message_size) by
1493 /// another name: that bounds the bytes going *in*, this bounds what they
1494 /// expand *into*. They are not redundant, because the two are not
1495 /// proportional — an empty repeated message element is 2 wire bytes and
1496 /// `size_of::<T>()` of `Vec` footprint (measured at 256 bytes for a message
1497 /// of a few `Vec`/`String` fields), so a payload well inside any input
1498 /// bound can still materialize 128x its own size. Charging is by element
1499 /// footprint, so a budget means the same amount of memory whatever the
1500 /// element size — which a count limit could not offer.
1501 ///
1502 /// Packed scalar fields are not charged by the generated or view
1503 /// decoders, but are by the reflective `DynamicMessage` codec; see
1504 /// [`DEFAULT_ELEMENT_MEMORY_LIMIT`] for why, and for the `Vec`-doubling
1505 /// caveat on peak memory.
1506 ///
1507 /// Like every option on [`DecodeOptions`], this bounds the binary decoders
1508 /// only. The textproto parser applies the same default through its own
1509 /// knob,
1510 /// [`TextDecoder::with_element_memory_limit`](crate::text::TextDecoder::with_element_memory_limit).
1511 /// The same message decoded from JSON into a generated type is not
1512 /// charged against this budget, and the amplification it guards against
1513 /// is very nearly as large there — `{}` is three JSON bytes for the same
1514 /// element footprint. The reflective JSON parser in `buffa_descriptor`
1515 /// applies the same default, changed with
1516 /// `buffa_descriptor::DynamicMessageSeed::with_element_memory_limit`.
1517 ///
1518 /// Default: 32 MiB ([`DEFAULT_ELEMENT_MEMORY_LIMIT`]).
1519 #[must_use]
1520 pub fn with_element_memory_limit(mut self, bytes: usize) -> Self {
1521 self.element_memory_limit = bytes;
1522 self
1523 }
1524
1525 /// Returns the configured element-memory budget.
1526 #[must_use]
1527 pub fn element_memory_limit(&self) -> usize {
1528 self.element_memory_limit
1529 }
1530
1531 /// Returns the configured recursion depth limit.
1532 pub fn recursion_limit(&self) -> u32 {
1533 self.recursion_limit
1534 }
1535
1536 /// Returns the configured unknown-field limit.
1537 pub fn unknown_field_limit(&self) -> usize {
1538 self.unknown_field_limit
1539 }
1540
1541 /// Returns the configured maximum message size in bytes for bounded decode
1542 /// entry points.
1543 ///
1544 /// This returns the configured (clamped) value even when
1545 /// `without_reader_size_limit` is enabled for EOF-bounded reader input —
1546 /// the slice/`Buf`/view paths still honor it. Use
1547 /// `is_reader_size_unbounded` (std only) to inspect the reader flag.
1548 pub fn max_message_size(&self) -> usize {
1549 self.max_message_size
1550 }
1551
1552 /// Returns whether EOF-bounded reader input has no byte cap.
1553 #[cfg(feature = "std")]
1554 pub fn is_reader_size_unbounded(&self) -> bool {
1555 self.unbounded_reader_size
1556 }
1557
1558 /// Returns whether a failed merge clears the destination message.
1559 ///
1560 /// See [`Self::with_clear_on_merge_error`].
1561 #[must_use]
1562 pub fn clears_on_merge_error(&self) -> bool {
1563 self.clear_on_merge_error
1564 }
1565
1566 /// Decode a message from a buffer.
1567 pub fn decode<M: Message>(&self, buf: &mut impl Buf) -> Result<M, DecodeError> {
1568 if buf.remaining() > self.max_message_size {
1569 return Err(DecodeError::MessageTooLarge);
1570 }
1571 let limit = core::cell::Cell::new(self.unknown_field_limit);
1572 let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1573 let mut msg = M::default();
1574 msg.merge(
1575 buf,
1576 DecodeContext::new(self.recursion_limit, &limit).with_element_memory(&elem_budget),
1577 )?;
1578 Ok(msg)
1579 }
1580
1581 /// Decode a message from a byte slice.
1582 pub fn decode_from_slice<M: Message>(&self, data: &[u8]) -> Result<M, DecodeError> {
1583 if data.len() > self.max_message_size {
1584 return Err(DecodeError::MessageTooLarge);
1585 }
1586 self.decode_from_slice_unchecked_size(data)
1587 }
1588
1589 fn decode_from_slice_unchecked_size<M: Message>(&self, data: &[u8]) -> Result<M, DecodeError> {
1590 let limit = core::cell::Cell::new(self.unknown_field_limit);
1591 let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1592 let mut msg = M::default();
1593 msg.merge(
1594 &mut &*data,
1595 DecodeContext::new(self.recursion_limit, &limit).with_element_memory(&elem_budget),
1596 )?;
1597 Ok(msg)
1598 }
1599
1600 /// Decode a length-delimited message from a buffer.
1601 pub fn decode_length_delimited<M: Message>(
1602 &self,
1603 buf: &mut impl Buf,
1604 ) -> Result<M, DecodeError> {
1605 // Enforce the 2 GiB internal safety cap even if the user sets a
1606 // larger max_message_size, to prevent allocating attacker-controlled
1607 // amounts of memory from a crafted length prefix.
1608 let max = core::cmp::min(
1609 self.max_message_size as u64,
1610 DEFAULT_MAX_MESSAGE_SIZE as u64,
1611 );
1612 let len_u64 = crate::encoding::decode_varint(buf)?;
1613 if len_u64 > max {
1614 return Err(DecodeError::MessageTooLarge);
1615 }
1616 let len = usize::try_from(len_u64).map_err(|_| DecodeError::MessageTooLarge)?;
1617 if buf.remaining() < len {
1618 return Err(DecodeError::UnexpectedEof);
1619 }
1620 let limit = buf.remaining() - len;
1621 let field_limit = core::cell::Cell::new(self.unknown_field_limit);
1622 let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1623 let mut msg = M::default();
1624 // Recorded here as well as by the default `merge_to_limit`, so an
1625 // override that does not record it is still bounded by the frame.
1626 msg.merge_to_limit(
1627 buf,
1628 DecodeContext::new(self.recursion_limit, &field_limit)
1629 .with_element_memory(&elem_budget)
1630 .with_message_end(limit),
1631 limit,
1632 )?;
1633 if buf.remaining() != limit {
1634 let remaining = buf.remaining();
1635 if remaining > limit {
1636 buf.advance(remaining - limit);
1637 } else {
1638 return Err(DecodeError::UnexpectedEof);
1639 }
1640 }
1641 Ok(msg)
1642 }
1643
1644 /// Enable clearing the destination when a merge returns an error.
1645 ///
1646 /// Equivalent to [`Self::with_clear_on_merge_error`] with `true`. See that
1647 /// method for the cleanup and input-buffer guarantees.
1648 #[must_use]
1649 pub fn clear_on_merge_error(self) -> Self {
1650 self.with_clear_on_merge_error(true)
1651 }
1652
1653 /// Set whether a merge error clears the entire destination, including
1654 /// when the input exceeds the message size limit. Disabled by default.
1655 ///
1656 /// Use this when a failed merge must not leave old values or a partially
1657 /// merged message available to the caller. Passing `false` restores the
1658 /// normal partial-merge behavior, including on a cloned configuration.
1659 ///
1660 /// This option applies to [`Self::merge`] and [`Self::merge_from_slice`],
1661 /// which call [`Message::clear`], so memory is wiped only if the message's
1662 /// implementation wipes its fields. It also applies to
1663 /// `buffa_descriptor::reflect::DynamicMessage::merge_with_options`, which
1664 /// removes every set and unknown field without wiping memory. Backing
1665 /// storage may be retained.
1666 ///
1667 /// The typed decode methods on `DecodeOptions` do not apply this policy.
1668 /// `DynamicMessage::decode_with_options` delegates to its merge method,
1669 /// so it applies the policy to its temporary destination on error; it
1670 /// still returns no message and provides no memory-wiping guarantee.
1671 ///
1672 /// The caller's input is not wiped. A failed buffer merge may already
1673 /// have consumed bytes; clearing does not rewind that buffer.
1674 #[must_use]
1675 pub fn with_clear_on_merge_error(mut self, enabled: bool) -> Self {
1676 self.clear_on_merge_error = enabled;
1677 self
1678 }
1679
1680 /// Merge fields from a buffer into an existing message.
1681 ///
1682 /// On error the destination can contain old and partially merged fields,
1683 /// unless [`Self::clear_on_merge_error`] was requested. Buffer consumption
1684 /// is not rolled back on failure, regardless of the clearing policy.
1685 pub fn merge<M: Message>(&self, msg: &mut M, buf: &mut impl Buf) -> Result<(), DecodeError> {
1686 let result = if buf.remaining() > self.max_message_size {
1687 Err(DecodeError::MessageTooLarge)
1688 } else {
1689 let limit = core::cell::Cell::new(self.unknown_field_limit);
1690 let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1691 msg.merge(
1692 buf,
1693 DecodeContext::new(self.recursion_limit, &limit).with_element_memory(&elem_budget),
1694 )
1695 };
1696 if self.clear_on_merge_error && result.is_err() {
1697 msg.clear();
1698 }
1699 result
1700 }
1701
1702 /// Merge fields from a byte slice into an existing message.
1703 ///
1704 /// The destination follows the same failure policy as [`Self::merge`].
1705 pub fn merge_from_slice<M: Message>(
1706 &self,
1707 msg: &mut M,
1708 mut data: &[u8],
1709 ) -> Result<(), DecodeError> {
1710 self.merge(msg, &mut data)
1711 }
1712
1713 /// Decode a zero-copy view from a byte slice.
1714 ///
1715 /// Enforces `max_message_size` on the input, and passes the recursion
1716 /// limit, unknown-field limit, and element-memory budget to the view
1717 /// decoder (views charge the unknown-field limit per field, including
1718 /// fields nested in unknown groups — see
1719 /// [`with_unknown_field_limit`](Self::with_unknown_field_limit)).
1720 ///
1721 /// # Errors
1722 ///
1723 /// Returns [`DecodeError::MessageTooLarge`] for oversized input, or any
1724 /// error from the view decoder (malformed wire data,
1725 /// [`DecodeError::RecursionLimitExceeded`],
1726 /// [`DecodeError::UnknownFieldLimitExceeded`], or
1727 /// [`DecodeError::ElementMemoryLimitExceeded`]).
1728 pub fn decode_view<'a, V: crate::view::MessageView<'a>>(
1729 &self,
1730 buf: &'a [u8],
1731 ) -> Result<V, DecodeError> {
1732 if buf.len() > self.max_message_size {
1733 return Err(DecodeError::MessageTooLarge);
1734 }
1735 let limit = core::cell::Cell::new(self.unknown_field_limit);
1736 let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1737 V::decode_view_with_ctx(
1738 buf,
1739 DecodeContext::new(self.recursion_limit, &limit).with_element_memory(&elem_budget),
1740 )
1741 }
1742
1743 /// Decode a lazy view from a byte slice (see
1744 /// [`LazyMessageView`](crate::view::LazyMessageView)).
1745 ///
1746 /// The budgets remaining at each deferred field's position are recorded
1747 /// and charged when that field is accessed, so the configured limits
1748 /// flow through deferred decoding. Unlike
1749 /// [`decode_view`](Self::decode_view), the unknown-field and
1750 /// element-memory limits are not enforced globally across the message
1751 /// tree at decode time: each deferred subtree independently replays the
1752 /// budgets recorded at its position, so a full traversal can materialize
1753 /// records proportional to input size. Prefer `decode_view` for
1754 /// untrusted input if the global bound matters.
1755 ///
1756 /// # Errors
1757 ///
1758 /// Returns [`DecodeError::MessageTooLarge`] for oversized input, or any
1759 /// error from decoding the message's own fields — including
1760 /// [`DecodeError::RecursionLimitExceeded`],
1761 /// [`DecodeError::UnknownFieldLimitExceeded`], or
1762 /// [`DecodeError::ElementMemoryLimitExceeded`] when the configured limits
1763 /// are exhausted by them. Deferred sub-message bytes surface errors on
1764 /// access instead.
1765 pub fn decode_lazy_view<'a, L: crate::view::LazyMessageView<'a>>(
1766 &self,
1767 buf: &'a [u8],
1768 ) -> Result<L, DecodeError> {
1769 if buf.len() > self.max_message_size {
1770 return Err(DecodeError::MessageTooLarge);
1771 }
1772 let limit = core::cell::Cell::new(self.unknown_field_limit);
1773 let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1774 L::decode_lazy_with_ctx(
1775 buf,
1776 DecodeContext::new(self.recursion_limit, &limit).with_element_memory(&elem_budget),
1777 )
1778 }
1779
1780 /// Decode a message by reading all bytes from a [`std::io::Read`] source.
1781 ///
1782 /// Reads until EOF, enforces the configured reader size limit unless
1783 /// [`without_reader_size_limit`](Self::without_reader_size_limit) was
1784 /// selected, then decodes the buffered bytes. Returns `std::io::Error` to
1785 /// be compatible with `Read`-based error handling.
1786 #[cfg(feature = "std")]
1787 pub fn decode_reader<M: Message>(
1788 &self,
1789 reader: &mut impl std::io::Read,
1790 ) -> Result<M, std::io::Error> {
1791 let bytes = self.read_limited(reader)?;
1792 self.decode_from_slice_unchecked_size::<M>(&bytes)
1793 .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))
1794 }
1795
1796 /// Decode a length-delimited message from a [`std::io::Read`] source.
1797 ///
1798 /// Reads a varint length prefix, enforces `max_message_size`, reads
1799 /// exactly that many bytes, then decodes. Useful for reading sequential
1800 /// length-delimited messages from a file or stream.
1801 ///
1802 /// The declared length is treated as untrusted: the read buffer grows
1803 /// as bytes actually arrive rather than being allocated up front, so a
1804 /// source that declares a large length but never delivers the bytes
1805 /// cannot force a large allocation.
1806 #[cfg(feature = "std")]
1807 pub fn decode_length_delimited_reader<M: Message>(
1808 &self,
1809 reader: &mut impl std::io::Read,
1810 ) -> Result<M, std::io::Error> {
1811 use std::io::Read as _;
1812 let len = read_varint(reader)?;
1813 let max = core::cmp::min(
1814 self.max_message_size as u64,
1815 DEFAULT_MAX_MESSAGE_SIZE as u64,
1816 );
1817 if len > max {
1818 return Err(std::io::Error::new(
1819 std::io::ErrorKind::InvalidData,
1820 DecodeError::MessageTooLarge,
1821 ));
1822 }
1823 let len = usize::try_from(len).map_err(|_| {
1824 std::io::Error::new(
1825 std::io::ErrorKind::InvalidData,
1826 DecodeError::MessageTooLarge,
1827 )
1828 })?;
1829 // Pre-size only up to a small bound; `read_to_end` grows the buffer
1830 // geometrically as data is actually delivered, so peak allocation
1831 // tracks delivered bytes, not the wire-declared length.
1832 const INITIAL_CAPACITY_CAP: usize = 64 * 1024;
1833 let mut buf = alloc::vec::Vec::with_capacity(len.min(INITIAL_CAPACITY_CAP));
1834 reader.take(len as u64).read_to_end(&mut buf)?;
1835 if buf.len() < len {
1836 return Err(std::io::Error::new(
1837 std::io::ErrorKind::UnexpectedEof,
1838 DecodeError::UnexpectedEof,
1839 ));
1840 }
1841 self.decode_from_slice::<M>(&buf)
1842 .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))
1843 }
1844
1845 /// Read all bytes from a reader up to the configured reader limit.
1846 #[cfg(feature = "std")]
1847 fn read_limited(
1848 &self,
1849 reader: &mut impl std::io::Read,
1850 ) -> Result<alloc::vec::Vec<u8>, std::io::Error> {
1851 use std::io::Read as _;
1852 let mut buf = alloc::vec::Vec::new();
1853 if self.unbounded_reader_size {
1854 reader.read_to_end(&mut buf)?;
1855 return Ok(buf);
1856 }
1857 reader
1858 .take((self.max_message_size as u64).saturating_add(1))
1859 .read_to_end(&mut buf)?;
1860 if buf.len() > self.max_message_size {
1861 return Err(std::io::Error::new(
1862 std::io::ErrorKind::InvalidData,
1863 DecodeError::MessageTooLarge,
1864 ));
1865 }
1866 Ok(buf)
1867 }
1868}
1869
1870/// Read a varint from a `std::io::Read` source, one byte at a time.
1871///
1872/// Mirrors the validation in [`decode_varint_slow`](crate::encoding): a
1873/// 10th byte > `0x01` (overflow bits set, or continuation bit implying an
1874/// 11th byte) is rejected.
1875#[cfg(feature = "std")]
1876fn read_varint(reader: &mut impl std::io::Read) -> Result<u64, std::io::Error> {
1877 let mut value: u64 = 0;
1878 let mut shift: u32 = 0;
1879 loop {
1880 let mut byte = [0u8; 1];
1881 reader.read_exact(&mut byte)?;
1882 let b = byte[0];
1883 if shift < 63 {
1884 value |= ((b & 0x7F) as u64) << shift;
1885 if b < 0x80 {
1886 return Ok(value);
1887 }
1888 shift += 7;
1889 } else {
1890 // 10th byte: only bit 0 maps to bit 63 of the result. A byte
1891 // > 0x01 means either data overflow (bits 1-6 set) or an 11th
1892 // byte (continuation bit 0x80 set).
1893 if b > 0x01 {
1894 return Err(std::io::Error::new(
1895 std::io::ErrorKind::InvalidData,
1896 DecodeError::VarintTooLong,
1897 ));
1898 }
1899 value |= (b as u64) << 63;
1900 return Ok(value);
1901 }
1902 }
1903}
1904
1905#[cfg(test)]
1906mod tests {
1907 use super::*;
1908 use crate::encoding::encode_varint;
1909 use crate::error::DecodeError;
1910 use crate::message_field::DefaultInstance;
1911 use crate::SizeCache;
1912
1913 // Minimal hand-written Message for testing merge_length_delimited.
1914 #[derive(Clone, Debug, Default, PartialEq)]
1915 struct FlatMsg {
1916 value: i32,
1917 }
1918
1919 impl DefaultInstance for FlatMsg {
1920 fn default_instance() -> &'static Self {
1921 static INST: crate::__private::OnceBox<FlatMsg> = crate::__private::OnceBox::new();
1922 INST.get_or_init(|| alloc::boxed::Box::new(FlatMsg::default()))
1923 }
1924 }
1925
1926 impl Message for FlatMsg {
1927 fn compute_size(&self, _cache: &mut SizeCache) -> u32 {
1928 if self.value != 0 {
1929 1 + crate::types::int32_encoded_len(self.value) as u32
1930 } else {
1931 0
1932 }
1933 }
1934
1935 fn write_to(&self, _cache: &mut SizeCache, buf: &mut impl EncodeSink) {
1936 if self.value != 0 {
1937 crate::encoding::Tag::new(1, crate::encoding::WireType::Varint).encode(buf);
1938 crate::types::encode_int32(self.value, buf);
1939 }
1940 }
1941
1942 fn merge_field(
1943 &mut self,
1944 tag: crate::encoding::Tag,
1945 buf: &mut impl Buf,
1946 _ctx: DecodeContext<'_>,
1947 ) -> Result<(), DecodeError> {
1948 match tag.field_number() {
1949 1 => {
1950 self.value = crate::types::decode_int32(buf)?;
1951 }
1952 _ => {
1953 crate::encoding::skip_field(tag, buf)?;
1954 }
1955 }
1956 Ok(())
1957 }
1958
1959 fn clear(&mut self) {
1960 *self = Self::default();
1961 }
1962 }
1963
1964 /// A message whose `merge_to_limit` override does not record its limit,
1965 /// and whose `merge_field` reports the end its context carries.
1966 #[derive(Clone, Debug, Default, PartialEq)]
1967 struct OverrideMsg {
1968 seen_end: Option<usize>,
1969 }
1970
1971 impl DefaultInstance for OverrideMsg {
1972 fn default_instance() -> &'static Self {
1973 static INST: crate::__private::OnceBox<OverrideMsg> = crate::__private::OnceBox::new();
1974 INST.get_or_init(|| alloc::boxed::Box::new(OverrideMsg::default()))
1975 }
1976 }
1977
1978 impl Message for OverrideMsg {
1979 fn compute_size(&self, _cache: &mut SizeCache) -> u32 {
1980 0
1981 }
1982
1983 fn write_to(&self, _cache: &mut SizeCache, _buf: &mut impl EncodeSink) {}
1984
1985 fn merge_field(
1986 &mut self,
1987 tag: crate::encoding::Tag,
1988 buf: &mut impl Buf,
1989 ctx: DecodeContext<'_>,
1990 ) -> Result<(), DecodeError> {
1991 self.seen_end = Some(ctx.message_end());
1992 crate::encoding::skip_field(tag, buf)
1993 }
1994
1995 fn merge_to_limit(
1996 &mut self,
1997 buf: &mut impl Buf,
1998 ctx: DecodeContext<'_>,
1999 limit: usize,
2000 ) -> Result<(), DecodeError> {
2001 while buf.remaining() > limit {
2002 let tag = crate::encoding::Tag::decode(buf)?;
2003 self.merge_field(tag, buf, ctx)?;
2004 }
2005 Ok(())
2006 }
2007
2008 fn clear(&mut self) {
2009 *self = Self::default();
2010 }
2011 }
2012
2013 #[test]
2014 fn length_delimited_callers_record_the_end_for_an_override() {
2015 // A frame holding one varint field, then three bytes of a next frame.
2016 let stream = [2u8, 0x08, 0x01, 0xaa, 0xbb, 0xcc];
2017
2018 let mut input = &stream[..];
2019 let msg = OverrideMsg::decode_length_delimited(&mut input).unwrap();
2020 assert_eq!(msg.seen_end, Some(3));
2021
2022 let mut input = &stream[..];
2023 let msg: OverrideMsg = DecodeOptions::new()
2024 .decode_length_delimited(&mut input)
2025 .unwrap();
2026 assert_eq!(msg.seen_end, Some(3));
2027
2028 let limit = core::cell::Cell::new(DEFAULT_UNKNOWN_FIELD_LIMIT);
2029 let mut msg = OverrideMsg::default();
2030 msg.merge_length_delimited(
2031 &mut &stream[..],
2032 DecodeContext::new(RECURSION_LIMIT, &limit),
2033 )
2034 .unwrap();
2035 assert_eq!(msg.seen_end, Some(3));
2036 }
2037
2038 fn wire_bytes(msg: &FlatMsg) -> alloc::vec::Vec<u8> {
2039 let mut buf = alloc::vec::Vec::new();
2040 msg.encode_length_delimited(&mut buf);
2041 buf
2042 }
2043
2044 #[test]
2045 fn test_merge_length_delimited_basic() {
2046 let src = FlatMsg { value: 42 };
2047 let mut dst = FlatMsg::default();
2048 dst.merge_length_delimited(
2049 &mut wire_bytes(&src).as_slice(),
2050 crate::test_ctx(RECURSION_LIMIT),
2051 )
2052 .unwrap();
2053 assert_eq!(dst.value, 42);
2054 }
2055
2056 #[test]
2057 fn test_merge_length_delimited_merges_into_existing() {
2058 // Second merge overwrites (proto3 last-wins for scalar fields).
2059 let mut dst = FlatMsg::default();
2060 dst.merge_length_delimited(
2061 &mut wire_bytes(&FlatMsg { value: 1 }).as_slice(),
2062 crate::test_ctx(RECURSION_LIMIT),
2063 )
2064 .unwrap();
2065 assert_eq!(dst.value, 1);
2066 dst.merge_length_delimited(
2067 &mut wire_bytes(&FlatMsg { value: 2 }).as_slice(),
2068 crate::test_ctx(RECURSION_LIMIT),
2069 )
2070 .unwrap();
2071 assert_eq!(dst.value, 2);
2072 }
2073
2074 #[test]
2075 fn test_merge_length_delimited_truncated() {
2076 // Length prefix says 10 bytes but buffer contains only 2.
2077 let mut buf = alloc::vec::Vec::new();
2078 encode_varint(10, &mut buf);
2079 buf.extend_from_slice(&[0x01, 0x01]);
2080 let mut dst = FlatMsg::default();
2081 assert_eq!(
2082 dst.merge_length_delimited(&mut buf.as_slice(), crate::test_ctx(RECURSION_LIMIT)),
2083 Err(DecodeError::UnexpectedEof)
2084 );
2085 }
2086
2087 #[test]
2088 fn test_merge_length_delimited_oversized() {
2089 // Length prefix exceeds the 2 GiB safety limit.
2090 let mut buf = alloc::vec::Vec::new();
2091 encode_varint(0x8000_0000u64, &mut buf); // 2 GiB + 1
2092 let mut dst = FlatMsg::default();
2093 assert_eq!(
2094 dst.merge_length_delimited(&mut buf.as_slice(), crate::test_ctx(RECURSION_LIMIT)),
2095 Err(DecodeError::MessageTooLarge)
2096 );
2097 }
2098
2099 #[test]
2100 fn test_merge_length_delimited_recursion_limit() {
2101 // depth=1 means merge_length_delimited will decrement to 0, then any
2102 // nested call would return RecursionLimitExceeded. Passing depth=1
2103 // to merge_length_delimited itself is the boundary: it decrements to
2104 // 0 and calls merge with depth=0, which for FlatMsg (a leaf) succeeds.
2105 // Passing depth=0 directly must return RecursionLimitExceeded.
2106 let src = FlatMsg { value: 7 };
2107 let mut dst = FlatMsg::default();
2108 assert_eq!(
2109 dst.merge_length_delimited(&mut wire_bytes(&src).as_slice(), crate::test_ctx(0)),
2110 Err(DecodeError::RecursionLimitExceeded)
2111 );
2112 // depth=1 succeeds: exactly one level is consumed.
2113 dst.merge_length_delimited(&mut wire_bytes(&src).as_slice(), crate::test_ctx(1))
2114 .unwrap();
2115 assert_eq!(dst.value, 7);
2116 }
2117
2118 #[test]
2119 fn test_decode_from_slice_basic() {
2120 let src = FlatMsg { value: 42 };
2121 let bytes = src.encode_to_vec();
2122 let dst = FlatMsg::decode_from_slice(&bytes).unwrap();
2123 assert_eq!(dst.value, 42);
2124 }
2125
2126 #[test]
2127 fn test_encode_to_bytes_matches_encode_to_vec() {
2128 let src = FlatMsg { value: 42 };
2129 let vec = src.encode_to_vec();
2130 let bytes = src.encode_to_bytes();
2131 assert_eq!(vec.as_slice(), bytes.as_ref());
2132 // Round-trip through the Bytes variant.
2133 let dst = FlatMsg::decode_from_slice(&bytes).unwrap();
2134 assert_eq!(dst.value, 42);
2135 // Empty-message case: zero-length buffer is well-defined.
2136 assert!(FlatMsg::default().encode_to_bytes().is_empty());
2137 }
2138
2139 #[test]
2140 fn test_decode_from_slice_empty() {
2141 let dst = FlatMsg::decode_from_slice(&[]).unwrap();
2142 assert_eq!(dst.value, 0);
2143 }
2144
2145 #[test]
2146 fn test_decode_from_slice_invalid_returns_error() {
2147 // A lone 0xFF byte is not a valid varint tag.
2148 let result = FlatMsg::decode_from_slice(&[0xFF]);
2149 assert!(result.is_err());
2150 }
2151
2152 #[test]
2153 fn test_merge_from_slice_basic() {
2154 let src = FlatMsg { value: 7 };
2155 let bytes = src.encode_to_vec();
2156 let mut dst = FlatMsg::default();
2157 dst.merge_from_slice(&bytes).unwrap();
2158 assert_eq!(dst.value, 7);
2159 }
2160
2161 #[test]
2162 fn test_merge_from_slice_last_wins() {
2163 let src1 = FlatMsg { value: 1 };
2164 let src2 = FlatMsg { value: 2 };
2165 let mut dst = FlatMsg::default();
2166 dst.merge_from_slice(&src1.encode_to_vec()).unwrap();
2167 dst.merge_from_slice(&src2.encode_to_vec()).unwrap();
2168 // Proto3 last-wins semantics for scalar fields.
2169 assert_eq!(dst.value, 2);
2170 }
2171
2172 // ── DecodeOptions tests ──────────────────────────────────────────
2173
2174 #[test]
2175 fn test_decode_options_default_works() {
2176 let src = FlatMsg { value: 99 };
2177 let bytes = src.encode_to_vec();
2178 let msg: FlatMsg = DecodeOptions::new().decode_from_slice(&bytes).unwrap();
2179 assert_eq!(msg.value, 99);
2180 }
2181
2182 #[test]
2183 fn test_decode_options_max_message_size_rejects() {
2184 let src = FlatMsg { value: 42 };
2185 let bytes = src.encode_to_vec();
2186 // Set max size to 1 byte — smaller than the encoded message.
2187 let result: Result<FlatMsg, _> = DecodeOptions::new()
2188 .with_max_message_size(1)
2189 .decode_from_slice(&bytes);
2190 assert_eq!(result, Err(DecodeError::MessageTooLarge));
2191 }
2192
2193 #[test]
2194 fn test_decode_options_max_message_size_exact_boundary() {
2195 let src = FlatMsg { value: 42 };
2196 let bytes = src.encode_to_vec();
2197 // Exact size should succeed.
2198 let msg: FlatMsg = DecodeOptions::new()
2199 .with_max_message_size(bytes.len())
2200 .decode_from_slice(&bytes)
2201 .unwrap();
2202 assert_eq!(msg.value, 42);
2203 // One byte less should fail.
2204 let result: Result<FlatMsg, _> = DecodeOptions::new()
2205 .with_max_message_size(bytes.len() - 1)
2206 .decode_from_slice(&bytes);
2207 assert_eq!(result, Err(DecodeError::MessageTooLarge));
2208 }
2209
2210 #[test]
2211 fn test_decode_options_custom_recursion_limit() {
2212 // FlatMsg has no nested messages, so any recursion limit >= 0 works.
2213 // Just verify the API compiles and runs.
2214 let src = FlatMsg { value: 7 };
2215 let bytes = src.encode_to_vec();
2216 let msg: FlatMsg = DecodeOptions::new()
2217 .with_recursion_limit(1)
2218 .decode_from_slice(&bytes)
2219 .unwrap();
2220 assert_eq!(msg.value, 7);
2221 }
2222
2223 #[test]
2224 fn test_decode_options_merge() {
2225 let src = FlatMsg { value: 55 };
2226 let bytes = src.encode_to_vec();
2227 let mut msg = FlatMsg::default();
2228 DecodeOptions::new()
2229 .merge_from_slice(&mut msg, &bytes)
2230 .unwrap();
2231 assert_eq!(msg.value, 55);
2232 }
2233
2234 #[test]
2235 fn test_decode_options_merge_rejects_oversize() {
2236 let src = FlatMsg { value: 55 };
2237 let bytes = src.encode_to_vec();
2238 let mut msg = FlatMsg::default();
2239 let result = DecodeOptions::new()
2240 .with_max_message_size(1)
2241 .merge_from_slice(&mut msg, &bytes);
2242 assert_eq!(result, Err(DecodeError::MessageTooLarge));
2243 }
2244
2245 #[test]
2246 fn merge_error_clears_destination_only_when_requested() {
2247 let mut message = FlatMsg { value: 17 };
2248 let mut malformed = FlatMsg { value: 42 }.encode_to_vec();
2249 malformed.push(0); // illegal field number
2250 assert_eq!(
2251 DecodeOptions::new().merge_from_slice(&mut message, &malformed),
2252 Err(DecodeError::InvalidFieldNumber)
2253 );
2254 assert_eq!(message.value, 42);
2255 assert!(!DecodeOptions::new().clears_on_merge_error());
2256
2257 let options = DecodeOptions::new().clear_on_merge_error();
2258 assert!(options.clears_on_merge_error());
2259 assert_eq!(
2260 options.merge(&mut message, &mut malformed.as_slice()),
2261 Err(DecodeError::InvalidFieldNumber)
2262 );
2263 assert_eq!(message.value, 0);
2264
2265 let wire = FlatMsg { value: 27 }.encode_to_vec();
2266 options.merge_from_slice(&mut message, &wire).unwrap();
2267 assert_eq!(message.value, 27);
2268 assert_eq!(
2269 options
2270 .with_max_message_size(1)
2271 .merge_from_slice(&mut message, &wire),
2272 Err(DecodeError::MessageTooLarge)
2273 );
2274 assert_eq!(message.value, 0);
2275 }
2276
2277 #[test]
2278 fn clear_policy_can_be_disabled_on_a_cloned_configuration() {
2279 let enabled = DecodeOptions::new()
2280 .with_recursion_limit(7)
2281 .with_max_message_size(99)
2282 .with_unknown_field_limit(3)
2283 .with_element_memory_limit(64)
2284 .clear_on_merge_error();
2285 #[cfg(feature = "std")]
2286 let enabled = enabled.without_reader_size_limit();
2287 let disabled = enabled.clone().with_clear_on_merge_error(false);
2288 assert!(enabled.clears_on_merge_error());
2289 assert!(!disabled.clears_on_merge_error());
2290 assert_eq!(disabled.recursion_limit(), enabled.recursion_limit());
2291 assert_eq!(disabled.max_message_size(), enabled.max_message_size());
2292 assert_eq!(
2293 disabled.unknown_field_limit(),
2294 enabled.unknown_field_limit()
2295 );
2296 assert_eq!(
2297 disabled.element_memory_limit(),
2298 enabled.element_memory_limit()
2299 );
2300 #[cfg(feature = "std")]
2301 assert_eq!(
2302 disabled.is_reader_size_unbounded(),
2303 enabled.is_reader_size_unbounded()
2304 );
2305 assert!(disabled
2306 .clone()
2307 .with_clear_on_merge_error(true)
2308 .clears_on_merge_error());
2309
2310 let mut wire = FlatMsg { value: 42 }.encode_to_vec();
2311 wire.push(0);
2312 let mut message = FlatMsg { value: 17 };
2313 assert_eq!(
2314 disabled.merge_from_slice(&mut message, &wire),
2315 Err(DecodeError::InvalidFieldNumber)
2316 );
2317 assert_eq!(message.value, 42);
2318 assert_eq!(
2319 enabled.merge_from_slice(&mut message, &wire),
2320 Err(DecodeError::InvalidFieldNumber)
2321 );
2322 assert_eq!(message.value, 0);
2323 }
2324
2325 #[derive(Clone, Debug, Default, PartialEq)]
2326 struct ClearObserved {
2327 inner: FlatMsg,
2328 clear_calls: usize,
2329 }
2330 crate::impl_default_instance!(ClearObserved);
2331 impl Message for ClearObserved {
2332 fn compute_size(&self, cache: &mut SizeCache) -> u32 {
2333 self.inner.compute_size(cache)
2334 }
2335 fn write_to(&self, cache: &mut SizeCache, buf: &mut impl EncodeSink) {
2336 self.inner.write_to(cache, buf);
2337 }
2338 fn merge_field(
2339 &mut self,
2340 tag: crate::encoding::Tag,
2341 buf: &mut impl Buf,
2342 ctx: DecodeContext<'_>,
2343 ) -> Result<(), DecodeError> {
2344 self.inner.merge_field(tag, buf, ctx)
2345 }
2346 fn clear(&mut self) {
2347 self.inner.clear();
2348 self.clear_calls = self.clear_calls.checked_add(1).unwrap();
2349 }
2350 }
2351
2352 #[test]
2353 fn merge_cleanup_calls_the_message_hook_once_without_rewinding_input() {
2354 let valid = FlatMsg { value: 42 }.encode_to_vec();
2355 let mut malformed = valid.clone();
2356 malformed.extend_from_slice(&[0, 0x7f]);
2357 let input_before = malformed.clone();
2358 for clear in [false, true] {
2359 let options = DecodeOptions::new().with_clear_on_merge_error(clear);
2360 let mut message = ClearObserved::default();
2361 options.merge_from_slice(&mut message, &valid).unwrap();
2362 options.merge_from_slice(&mut message, &[]).unwrap();
2363 assert_eq!(message.clear_calls, 0, "success must not run cleanup");
2364 assert_eq!(message.inner.value, 42);
2365
2366 // Fragmented buffers retain the same consumed cursor when the
2367 // destination policy changes. The sentinel is outside the error.
2368 let (first, rest) = malformed.split_at(1);
2369 let mut input = first.chain(rest);
2370 assert_eq!(
2371 options.merge(&mut message, &mut input),
2372 Err(DecodeError::InvalidFieldNumber)
2373 );
2374 assert_eq!(input.chunk(), &[0x7f]);
2375 assert_eq!(message.clear_calls, usize::from(clear));
2376 assert_eq!(message.inner.value, if clear { 0 } else { 42 });
2377
2378 let mut message = ClearObserved::default();
2379 let mut input = valid.as_slice();
2380 assert_eq!(
2381 options
2382 .with_max_message_size(0)
2383 .merge(&mut message, &mut input),
2384 Err(DecodeError::MessageTooLarge)
2385 );
2386 assert_eq!(input, valid, "size rejection must not consume input");
2387 // This remains necessary even when the message is already empty:
2388 // its clear hook may erase retained allocation or external state.
2389 assert_eq!(message.clear_calls, usize::from(clear));
2390 }
2391 assert_eq!(malformed, input_before, "caller input bytes are not wiped");
2392 }
2393
2394 #[derive(Clone, Debug, Default, PartialEq)]
2395 struct MergeOverride(ClearObserved);
2396 crate::impl_default_instance!(MergeOverride);
2397 impl Message for MergeOverride {
2398 fn compute_size(&self, cache: &mut SizeCache) -> u32 {
2399 self.0.compute_size(cache)
2400 }
2401 fn write_to(&self, cache: &mut SizeCache, buf: &mut impl EncodeSink) {
2402 self.0.write_to(cache, buf);
2403 }
2404 fn merge_field(
2405 &mut self,
2406 tag: crate::encoding::Tag,
2407 buf: &mut impl Buf,
2408 ctx: DecodeContext<'_>,
2409 ) -> Result<(), DecodeError> {
2410 self.0.merge_field(tag, buf, ctx)
2411 }
2412 fn merge(
2413 &mut self,
2414 _buf: &mut impl Buf,
2415 _ctx: DecodeContext<'_>,
2416 ) -> Result<(), DecodeError> {
2417 // Hand-written implementations can reject empty input after
2418 // changing state, without entering the default field loop.
2419 self.0.inner.value = 42;
2420 Err(DecodeError::Custom("merge override rejected input"))
2421 }
2422 fn clear(&mut self) {
2423 self.0.clear();
2424 }
2425 }
2426
2427 #[test]
2428 fn empty_input_still_calls_an_overridden_merge_and_its_cleanup_hook() {
2429 for clear in [false, true] {
2430 let options = DecodeOptions::new()
2431 .with_max_message_size(0)
2432 .with_clear_on_merge_error(clear);
2433 for from_slice in [false, true] {
2434 let mut message = MergeOverride::default();
2435 let mut input = [].as_slice();
2436 let result = if from_slice {
2437 options.merge_from_slice(&mut message, input)
2438 } else {
2439 options.merge(&mut message, &mut input)
2440 };
2441 assert_eq!(
2442 result,
2443 Err(DecodeError::Custom("merge override rejected input"))
2444 );
2445 assert!(input.is_empty());
2446 assert_eq!(message.0.clear_calls, usize::from(clear));
2447 assert_eq!(message.0.inner.value, if clear { 0 } else { 42 });
2448 }
2449 }
2450 }
2451
2452 #[test]
2453 fn test_decode_options_length_delimited() {
2454 let src = FlatMsg { value: 42 };
2455 let mut ld_bytes = alloc::vec::Vec::new();
2456 src.encode_length_delimited(&mut ld_bytes);
2457 let msg: FlatMsg = DecodeOptions::new()
2458 .decode_length_delimited(&mut ld_bytes.as_slice())
2459 .unwrap();
2460 assert_eq!(msg.value, 42);
2461 }
2462
2463 #[test]
2464 fn test_decode_options_length_delimited_rejects_oversize() {
2465 let src = FlatMsg { value: 42 };
2466 let mut ld_bytes = alloc::vec::Vec::new();
2467 src.encode_length_delimited(&mut ld_bytes);
2468 let result: Result<FlatMsg, _> = DecodeOptions::new()
2469 .with_max_message_size(1)
2470 .decode_length_delimited(&mut ld_bytes.as_slice());
2471 assert_eq!(result, Err(DecodeError::MessageTooLarge));
2472 }
2473
2474 #[test]
2475 fn decode_options_getters_return_defaults() {
2476 let opts = DecodeOptions::new();
2477 assert_eq!(opts.recursion_limit(), RECURSION_LIMIT);
2478 assert_eq!(opts.max_message_size(), 0x7FFF_FFFF);
2479 assert_eq!(opts.unknown_field_limit(), DEFAULT_UNKNOWN_FIELD_LIMIT);
2480 }
2481
2482 #[test]
2483 fn decode_options_getters_return_custom_values() {
2484 let opts = DecodeOptions::new()
2485 .with_recursion_limit(42)
2486 .with_max_message_size(1024)
2487 .with_unknown_field_limit(2048);
2488 assert_eq!(opts.recursion_limit(), 42);
2489 assert_eq!(opts.max_message_size(), 1024);
2490 assert_eq!(opts.unknown_field_limit(), 2048);
2491 }
2492
2493 #[cfg(debug_assertions)]
2494 #[test]
2495 #[should_panic(expected = "protobuf 2 GiB limit")]
2496 fn decode_options_max_message_size_above_protobuf_limit_debug_asserts() {
2497 let _ = DecodeOptions::new().with_max_message_size(DEFAULT_MAX_MESSAGE_SIZE + 1);
2498 }
2499
2500 #[cfg(not(debug_assertions))]
2501 #[test]
2502 fn decode_options_max_message_size_above_protobuf_limit_saturates() {
2503 let opts = DecodeOptions::new().with_max_message_size(DEFAULT_MAX_MESSAGE_SIZE + 1);
2504 assert_eq!(opts.max_message_size(), DEFAULT_MAX_MESSAGE_SIZE);
2505 }
2506
2507 #[test]
2508 fn test_decode_options_default_impl() {
2509 // DecodeOptions::default() ≡ DecodeOptions::new().
2510 let opts = DecodeOptions::default();
2511 assert_eq!(opts.recursion_limit(), RECURSION_LIMIT);
2512 assert_eq!(opts.max_message_size(), 0x7FFF_FFFF);
2513 assert_eq!(opts.unknown_field_limit(), DEFAULT_UNKNOWN_FIELD_LIMIT);
2514 }
2515
2516 #[test]
2517 fn test_decode_options_decode_buf() {
2518 // The Buf-taking decode() variant (vs decode_from_slice).
2519 let src = FlatMsg { value: 123 };
2520 let bytes = src.encode_to_vec();
2521 let msg: FlatMsg = DecodeOptions::new().decode(&mut bytes.as_slice()).unwrap();
2522 assert_eq!(msg.value, 123);
2523 // Oversize check on the Buf variant.
2524 let result: Result<FlatMsg, _> = DecodeOptions::new()
2525 .with_max_message_size(1)
2526 .decode(&mut bytes.as_slice());
2527 assert_eq!(result, Err(DecodeError::MessageTooLarge));
2528 }
2529
2530 #[test]
2531 fn test_decode_options_merge_buf() {
2532 // The Buf-taking merge() variant (vs merge_from_slice).
2533 let src = FlatMsg { value: 77 };
2534 let bytes = src.encode_to_vec();
2535 let mut msg = FlatMsg::default();
2536 DecodeOptions::new()
2537 .merge(&mut msg, &mut bytes.as_slice())
2538 .unwrap();
2539 assert_eq!(msg.value, 77);
2540 // Oversize check.
2541 let mut msg = FlatMsg::default();
2542 let result = DecodeOptions::new()
2543 .with_max_message_size(1)
2544 .merge(&mut msg, &mut bytes.as_slice());
2545 assert_eq!(result, Err(DecodeError::MessageTooLarge));
2546 }
2547
2548 // ── Message trait default methods ─────────────────────────────────
2549
2550 #[test]
2551 fn test_message_encode_trait_default() {
2552 // Message::encode(buf) ≡ compute_size() then write_to(buf).
2553 let src = FlatMsg { value: 42 };
2554 let mut buf = alloc::vec::Vec::new();
2555 src.encode(&mut buf);
2556 assert_eq!(buf, src.encode_to_vec());
2557 }
2558
2559 #[test]
2560 fn test_message_decode_length_delimited_trait_default() {
2561 // The trait-level decode_length_delimited (distinct from
2562 // DecodeOptions::decode_length_delimited).
2563 let src = FlatMsg { value: 42 };
2564 let mut ld = alloc::vec::Vec::new();
2565 src.encode_length_delimited(&mut ld);
2566 let got = FlatMsg::decode_length_delimited(&mut ld.as_slice()).unwrap();
2567 assert_eq!(got.value, 42);
2568 }
2569
2570 #[test]
2571 fn test_message_decode_length_delimited_oversize() {
2572 // Length prefix > 2 GiB → MessageTooLarge.
2573 let mut buf = alloc::vec::Vec::new();
2574 encode_varint(0x8000_0000u64, &mut buf);
2575 let result = FlatMsg::decode_length_delimited(&mut buf.as_slice());
2576 assert_eq!(result, Err(DecodeError::MessageTooLarge));
2577 }
2578
2579 #[test]
2580 fn test_message_decode_length_delimited_truncated() {
2581 // Length prefix says 10 bytes, buffer has 2.
2582 let mut buf = alloc::vec::Vec::new();
2583 encode_varint(10, &mut buf);
2584 buf.push(0x08);
2585 buf.push(0x01);
2586 let result = FlatMsg::decode_length_delimited(&mut buf.as_slice());
2587 assert_eq!(result, Err(DecodeError::UnexpectedEof));
2588 }
2589
2590 #[test]
2591 fn test_message_decode_length_delimited_with_trailing() {
2592 // Buffer has two back-to-back length-delimited messages.
2593 // decode_length_delimited should consume exactly the first one
2594 // and leave the buffer positioned at the second.
2595 let a = FlatMsg { value: 1 };
2596 let b = FlatMsg { value: 2 };
2597 let mut buf = alloc::vec::Vec::new();
2598 a.encode_length_delimited(&mut buf);
2599 b.encode_length_delimited(&mut buf);
2600
2601 let mut cur = buf.as_slice();
2602 let first = FlatMsg::decode_length_delimited(&mut cur).unwrap();
2603 assert_eq!(first.value, 1);
2604 let second = FlatMsg::decode_length_delimited(&mut cur).unwrap();
2605 assert_eq!(second.value, 2);
2606 assert!(cur.is_empty());
2607 }
2608
2609 // ── merge_group tests ─────────────────────────────────────────────
2610
2611 /// Build a group body for FlatMsg (field 1 = value) terminated by
2612 /// EndGroup with the given field number.
2613 fn group_bytes(value: i32, group_field_number: u32) -> alloc::vec::Vec<u8> {
2614 use crate::encoding::{Tag, WireType};
2615 let mut buf = alloc::vec::Vec::new();
2616 if value != 0 {
2617 Tag::new(1, WireType::Varint).encode(&mut buf);
2618 crate::types::encode_int32(value, &mut buf);
2619 }
2620 Tag::new(group_field_number, WireType::EndGroup).encode(&mut buf);
2621 buf
2622 }
2623
2624 #[test]
2625 fn test_merge_group_basic() {
2626 let data = group_bytes(42, 5);
2627 let mut dst = FlatMsg::default();
2628 dst.merge_group(&mut data.as_slice(), crate::test_ctx(RECURSION_LIMIT), 5)
2629 .unwrap();
2630 assert_eq!(dst.value, 42);
2631 }
2632
2633 #[test]
2634 fn test_merge_group_empty() {
2635 // Group with no fields — just EndGroup.
2636 let data = group_bytes(0, 3);
2637 let mut dst = FlatMsg::default();
2638 dst.merge_group(&mut data.as_slice(), crate::test_ctx(RECURSION_LIMIT), 3)
2639 .unwrap();
2640 assert_eq!(dst.value, 0);
2641 }
2642
2643 #[test]
2644 fn test_merge_group_merges_into_existing() {
2645 let data1 = group_bytes(1, 5);
2646 let data2 = group_bytes(2, 5);
2647 let mut dst = FlatMsg::default();
2648 dst.merge_group(&mut data1.as_slice(), crate::test_ctx(RECURSION_LIMIT), 5)
2649 .unwrap();
2650 assert_eq!(dst.value, 1);
2651 dst.merge_group(&mut data2.as_slice(), crate::test_ctx(RECURSION_LIMIT), 5)
2652 .unwrap();
2653 assert_eq!(dst.value, 2);
2654 }
2655
2656 #[test]
2657 fn test_merge_group_recursion_limit_zero() {
2658 // depth=0 should immediately fail with RecursionLimitExceeded
2659 // because merge_group decrements before entering the loop.
2660 let data = group_bytes(42, 5);
2661 let mut dst = FlatMsg::default();
2662 assert_eq!(
2663 dst.merge_group(&mut data.as_slice(), crate::test_ctx(0), 5),
2664 Err(DecodeError::RecursionLimitExceeded)
2665 );
2666 }
2667
2668 #[test]
2669 fn test_merge_group_recursion_limit_one_succeeds() {
2670 // depth=1 succeeds: merge_group decrements to 0, but FlatMsg's
2671 // merge_field doesn't recurse further.
2672 let data = group_bytes(7, 5);
2673 let mut dst = FlatMsg::default();
2674 dst.merge_group(&mut data.as_slice(), crate::test_ctx(1), 5)
2675 .unwrap();
2676 assert_eq!(dst.value, 7);
2677 }
2678
2679 #[test]
2680 fn test_merge_group_mismatched_end() {
2681 // EndGroup with wrong field number.
2682 use crate::encoding::{Tag, WireType};
2683 let mut data = alloc::vec::Vec::new();
2684 Tag::new(99, WireType::EndGroup).encode(&mut data);
2685
2686 let mut dst = FlatMsg::default();
2687 assert_eq!(
2688 dst.merge_group(&mut data.as_slice(), crate::test_ctx(RECURSION_LIMIT), 5),
2689 Err(DecodeError::InvalidEndGroup(99))
2690 );
2691 }
2692
2693 #[test]
2694 fn test_merge_group_truncated() {
2695 // Buffer ends without EndGroup tag.
2696 use crate::encoding::{Tag, WireType};
2697 let mut data = alloc::vec::Vec::new();
2698 Tag::new(1, WireType::Varint).encode(&mut data);
2699 crate::types::encode_int32(42, &mut data);
2700 // No EndGroup.
2701
2702 let mut dst = FlatMsg::default();
2703 assert_eq!(
2704 dst.merge_group(&mut data.as_slice(), crate::test_ctx(RECURSION_LIMIT), 5),
2705 Err(DecodeError::UnexpectedEof)
2706 );
2707 }
2708
2709 #[test]
2710 fn test_merge_group_empty_buffer() {
2711 let mut dst = FlatMsg::default();
2712 assert_eq!(
2713 dst.merge_group(&mut [].as_slice(), crate::test_ctx(RECURSION_LIMIT), 5),
2714 Err(DecodeError::UnexpectedEof)
2715 );
2716 }
2717
2718 #[test]
2719 fn test_merge_group_unknown_fields_skipped() {
2720 // Group body contains an unknown field (field 99) which FlatMsg
2721 // routes to skip_field; the known field (field 1) should still
2722 // be decoded.
2723 use crate::encoding::{Tag, WireType};
2724 let mut data = alloc::vec::Vec::new();
2725 // Unknown varint field 99 = 0
2726 Tag::new(99, WireType::Varint).encode(&mut data);
2727 crate::encoding::encode_varint(0, &mut data);
2728 // Known field 1 = 99
2729 Tag::new(1, WireType::Varint).encode(&mut data);
2730 crate::types::encode_int32(99, &mut data);
2731 // EndGroup(5)
2732 Tag::new(5, WireType::EndGroup).encode(&mut data);
2733
2734 let mut dst = FlatMsg::default();
2735 dst.merge_group(&mut data.as_slice(), crate::test_ctx(RECURSION_LIMIT), 5)
2736 .unwrap();
2737 assert_eq!(dst.value, 99);
2738 }
2739
2740 #[test]
2741 fn test_merge_group_trailing_data_preserved() {
2742 // After the EndGroup tag, trailing data should remain in the buffer.
2743 let mut data = group_bytes(42, 5);
2744 data.extend_from_slice(&[0xDE, 0xAD]);
2745
2746 let mut cur = data.as_slice();
2747 let mut dst = FlatMsg::default();
2748 dst.merge_group(&mut cur, crate::test_ctx(RECURSION_LIMIT), 5)
2749 .unwrap();
2750 assert_eq!(dst.value, 42);
2751 assert_eq!(cur, &[0xDE, 0xAD]);
2752 }
2753
2754 // ── read_varint (std::io::Read) tests ──────────────────────────────
2755
2756 #[cfg(feature = "std")]
2757 mod read_varint_tests {
2758 use super::super::read_varint;
2759 use crate::encoding::encode_varint;
2760
2761 #[test]
2762 fn roundtrip_values() {
2763 let cases: &[u64] = &[0, 1, 127, 128, 300, 1 << 14, 1 << 35, 1 << 63, u64::MAX];
2764 for &v in cases {
2765 let mut buf = Vec::new();
2766 encode_varint(v, &mut buf);
2767 let got = read_varint(&mut buf.as_slice()).unwrap();
2768 assert_eq!(got, v, "roundtrip failed for {v}");
2769 }
2770 }
2771
2772 #[test]
2773 fn rejects_10th_byte_overflow() {
2774 // 9 continuation bytes + 10th byte with overflow bit (0x02).
2775 // Mirrors encoding::tests::test_varint_10th_byte_overflow_rejected.
2776 let mut bad: Vec<u8> = vec![0xFF; 9];
2777 bad.push(0x02);
2778 let err = read_varint(&mut bad.as_slice()).unwrap_err();
2779 assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
2780 }
2781
2782 #[test]
2783 fn rejects_11th_byte() {
2784 // 10 continuation bytes — implies an 11th byte is needed.
2785 let bad: &[u8] = &[0xFF; 10];
2786 let err = read_varint(&mut &bad[..]).unwrap_err();
2787 assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
2788 }
2789
2790 #[test]
2791 fn u64_max_roundtrips() {
2792 // u64::MAX requires 10 bytes with the 10th byte == 0x01.
2793 let mut buf = Vec::new();
2794 encode_varint(u64::MAX, &mut buf);
2795 assert_eq!(buf.len(), 10);
2796 assert_eq!(buf[9], 0x01);
2797 let got = read_varint(&mut buf.as_slice()).unwrap();
2798 assert_eq!(got, u64::MAX);
2799 }
2800
2801 #[test]
2802 fn eof_before_terminator_is_error() {
2803 // Single continuation byte with no follow-up.
2804 let bad: &[u8] = &[0x80];
2805 let err = read_varint(&mut &bad[..]).unwrap_err();
2806 assert_eq!(err.kind(), std::io::ErrorKind::UnexpectedEof);
2807 }
2808
2809 #[test]
2810 fn empty_input_is_error() {
2811 let err = read_varint(&mut &[][..]).unwrap_err();
2812 assert_eq!(err.kind(), std::io::ErrorKind::UnexpectedEof);
2813 }
2814 }
2815
2816 // ── Encode-side 2 GiB guard tests ──────────────────────────────────
2817
2818 use crate::test_doubles::{Mismatched, SizedMsg};
2819
2820 const OVER_LIMIT: u32 = MAX_MESSAGE_BYTES + 1;
2821
2822 #[test]
2823 fn saturate_size_is_exact_below_u32_max_and_saturates_above() {
2824 assert_eq!(saturate_size(0), 0);
2825 assert_eq!(saturate_size(MAX_MESSAGE_BYTES as u64), MAX_MESSAGE_BYTES);
2826 // 2–4 GiB window: exact (this is what makes the guard byte-precise).
2827 assert_eq!(saturate_size(0x8000_0000), 0x8000_0000u32);
2828 assert_eq!(saturate_size(u32::MAX as u64), u32::MAX);
2829 assert_eq!(saturate_size(u32::MAX as u64 + 1), u32::MAX);
2830 assert_eq!(saturate_size(u64::MAX), u32::MAX);
2831 }
2832
2833 #[test]
2834 fn encode_at_exactly_max_size_is_allowed() {
2835 // The guard is strictly-greater-than: a (fake) message of exactly
2836 // MAX_MESSAGE_BYTES passes. The pre-sized path and its ledger apply
2837 // only to `BufMut` sinks, and `NullSink` lets this no-op write_to
2838 // declare 2 GiB without allocating it.
2839 let msg = SizedMsg {
2840 reported_size: MAX_MESSAGE_BYTES,
2841 };
2842 let mut sink = crate::test_doubles::NullSink;
2843 msg.encode(&mut sink);
2844 assert!(msg.try_encode(&mut sink).is_ok());
2845 }
2846
2847 #[test]
2848 #[should_panic(expected = "2 GiB protobuf limit")]
2849 fn encode_over_limit_panics() {
2850 let msg = SizedMsg {
2851 reported_size: OVER_LIMIT,
2852 };
2853 let mut buf = alloc::vec::Vec::new();
2854 msg.encode(&mut buf);
2855 }
2856
2857 #[test]
2858 #[should_panic(expected = "2 GiB protobuf limit")]
2859 fn encoded_len_over_limit_panics() {
2860 let msg = SizedMsg {
2861 reported_size: OVER_LIMIT,
2862 };
2863 let _ = msg.encoded_len();
2864 }
2865
2866 #[test]
2867 #[should_panic(expected = "2 GiB protobuf limit")]
2868 fn encode_with_cache_over_limit_panics() {
2869 let msg = SizedMsg {
2870 reported_size: OVER_LIMIT,
2871 };
2872 let mut cache = SizeCache::new();
2873 let mut buf = alloc::vec::Vec::new();
2874 msg.encode_with_cache(&mut cache, &mut buf);
2875 }
2876
2877 #[test]
2878 #[should_panic(expected = "2 GiB protobuf limit")]
2879 fn encode_to_vec_over_limit_panics() {
2880 let msg = SizedMsg {
2881 reported_size: OVER_LIMIT,
2882 };
2883 let _ = msg.encode_to_vec();
2884 }
2885
2886 #[test]
2887 #[should_panic(expected = "2 GiB protobuf limit")]
2888 fn encode_to_bytes_over_limit_panics() {
2889 let msg = SizedMsg {
2890 reported_size: OVER_LIMIT,
2891 };
2892 let _ = msg.encode_to_bytes();
2893 }
2894
2895 #[test]
2896 #[should_panic(expected = "2 GiB protobuf limit")]
2897 fn encode_length_delimited_over_limit_panics() {
2898 let msg = SizedMsg {
2899 reported_size: OVER_LIMIT,
2900 };
2901 let mut buf = alloc::vec::Vec::new();
2902 msg.encode_length_delimited(&mut buf);
2903 }
2904
2905 #[test]
2906 fn try_encode_over_limit_errors_and_writes_nothing() {
2907 let msg = SizedMsg {
2908 reported_size: OVER_LIMIT,
2909 };
2910 let mut buf = alloc::vec::Vec::new();
2911 assert_eq!(msg.try_encode(&mut buf), Err(EncodeError::MessageTooLarge));
2912 assert!(buf.is_empty(), "no bytes may reach the buffer on Err");
2913 let mut cache = SizeCache::new();
2914 assert_eq!(
2915 msg.try_encode_with_cache(&mut cache, &mut buf),
2916 Err(EncodeError::MessageTooLarge)
2917 );
2918 assert!(buf.is_empty(), "no bytes may reach the buffer on Err");
2919 assert_eq!(
2920 msg.try_encode_length_delimited(&mut buf),
2921 Err(EncodeError::MessageTooLarge)
2922 );
2923 assert!(buf.is_empty(), "not even the length prefix");
2924 assert_eq!(msg.try_encode_to_vec(), Err(EncodeError::MessageTooLarge));
2925 assert_eq!(msg.try_encode_to_bytes(), Err(EncodeError::MessageTooLarge));
2926 assert_eq!(msg.try_encoded_len(), Err(EncodeError::MessageTooLarge));
2927 }
2928
2929 #[test]
2930 fn try_encode_matches_encode_for_normal_messages() {
2931 let msg = FlatMsg { value: 42 };
2932 let mut expected = alloc::vec::Vec::new();
2933 msg.encode(&mut expected);
2934 let mut actual = alloc::vec::Vec::new();
2935 msg.try_encode(&mut actual).unwrap();
2936 assert_eq!(actual, expected);
2937 let mut cache = SizeCache::new();
2938 let mut cached = alloc::vec::Vec::new();
2939 msg.try_encode_with_cache(&mut cache, &mut cached).unwrap();
2940 assert_eq!(cached, expected);
2941 assert_eq!(msg.try_encode_to_vec().unwrap(), expected);
2942 assert_eq!(msg.try_encode_to_bytes().unwrap(), expected);
2943 assert_eq!(msg.try_encoded_len().unwrap(), expected.len() as u32);
2944
2945 let mut ld_expected = alloc::vec::Vec::new();
2946 msg.encode_length_delimited(&mut ld_expected);
2947 let mut ld_actual = alloc::vec::Vec::new();
2948 msg.try_encode_length_delimited(&mut ld_actual).unwrap();
2949 assert_eq!(ld_actual, ld_expected);
2950 }
2951
2952 #[test]
2953 fn try_encode_bounded_within_budget_encodes_and_returns_len() {
2954 let msg = FlatMsg { value: 42 };
2955 let mut expected = alloc::vec::Vec::new();
2956 msg.encode(&mut expected);
2957 let budget = expected.len() as u32;
2958
2959 let mut buf = alloc::vec::Vec::new();
2960 let len = msg.try_encode_bounded(budget, &mut buf).unwrap();
2961 assert_eq!(buf, expected);
2962 assert_eq!(len, budget);
2963
2964 // with_cache variant agrees
2965 let mut cache = SizeCache::new();
2966 let mut buf2 = alloc::vec::Vec::new();
2967 let len2 = msg
2968 .try_encode_bounded_with_cache(budget, &mut cache, &mut buf2)
2969 .unwrap();
2970 assert_eq!(buf2, expected);
2971 assert_eq!(len2, budget);
2972 }
2973
2974 #[test]
2975 fn try_encode_bounded_at_exact_limit_succeeds() {
2976 let msg = FlatMsg { value: 42 };
2977 let exact = msg.encoded_len();
2978 let mut buf = alloc::vec::Vec::new();
2979 assert!(msg.try_encode_bounded(exact, &mut buf).is_ok());
2980 }
2981
2982 #[test]
2983 fn try_encode_bounded_over_budget_errors_and_writes_nothing() {
2984 let msg = FlatMsg { value: 42 };
2985 let len = msg.encoded_len();
2986 let budget = len - 1; // one byte under
2987
2988 let mut buf = alloc::vec::Vec::new();
2989 assert_eq!(
2990 msg.try_encode_bounded(budget, &mut buf),
2991 Err(EncodeError::ExceedsBudget {
2992 len,
2993 max_bytes: budget
2994 })
2995 );
2996 assert!(buf.is_empty(), "nothing written on budget exceeded");
2997 }
2998
2999 /// "Nothing written on `Err`" has to hold for a sink that already has
3000 /// bytes in it, which is how a caller framing several messages uses one
3001 /// buffer. Every other test starts from an empty `Vec`, so the append
3002 /// case — where a partial write would corrupt the *preceding* message
3003 /// rather than produce an obviously empty one — would go unnoticed.
3004 #[test]
3005 fn try_encode_bounded_over_budget_leaves_a_populated_buffer_untouched() {
3006 let msg = FlatMsg { value: 42 };
3007 let len = msg.encoded_len();
3008 let budget = len - 1;
3009
3010 let prefix = b"already framed".to_vec();
3011 let mut buf = prefix.clone();
3012 assert_eq!(
3013 msg.try_encode_bounded(budget, &mut buf),
3014 Err(EncodeError::ExceedsBudget {
3015 len,
3016 max_bytes: budget
3017 })
3018 );
3019 assert_eq!(buf, prefix, "the bytes already in the sink must survive");
3020 }
3021
3022 #[test]
3023 fn try_encode_bounded_zero_budget_with_empty_message_succeeds() {
3024 // A default FlatMsg with value=0 encodes to 0 bytes (all defaults
3025 // are elided in proto3), so budget=0 is exactly satisfied.
3026 let msg = FlatMsg { value: 0 };
3027 let mut buf = alloc::vec::Vec::new();
3028 let len = msg.try_encode_bounded(0, &mut buf).unwrap();
3029 assert_eq!(len, 0);
3030 assert!(buf.is_empty());
3031 }
3032
3033 #[test]
3034 fn try_encode_bounded_over_protobuf_limit_errors_as_too_large() {
3035 let msg = SizedMsg {
3036 reported_size: OVER_LIMIT,
3037 };
3038 let mut buf = alloc::vec::Vec::new();
3039 assert_eq!(
3040 msg.try_encode_bounded(u32::MAX, &mut buf),
3041 Err(EncodeError::MessageTooLarge)
3042 );
3043 assert!(buf.is_empty());
3044 }
3045
3046 #[test]
3047 fn pool_try_encode_bounded_within_budget_encodes_and_returns_len() {
3048 let msg = FlatMsg { value: 42 };
3049 let mut expected = alloc::vec::Vec::new();
3050 msg.encode(&mut expected);
3051 let budget = expected.len() as u32;
3052
3053 let mut pool = crate::SizeCachePool::sequential(64);
3054 let mut buf = alloc::vec::Vec::new();
3055 let len = pool.try_encode_bounded(&msg, budget, &mut buf).unwrap();
3056 assert_eq!(buf, expected);
3057 assert_eq!(len, budget);
3058 }
3059
3060 #[test]
3061 fn pool_try_encode_bounded_over_budget_errors_and_writes_nothing() {
3062 let msg = FlatMsg { value: 42 };
3063 let len = msg.encoded_len();
3064 let budget = len - 1;
3065
3066 let mut pool = crate::SizeCachePool::sequential(64);
3067 let mut buf = alloc::vec::Vec::new();
3068 assert_eq!(
3069 pool.try_encode_bounded(&msg, budget, &mut buf),
3070 Err(EncodeError::ExceedsBudget {
3071 len,
3072 max_bytes: budget
3073 })
3074 );
3075 assert!(buf.is_empty());
3076 // Pool buffer must be returned even on Err.
3077 assert_eq!(pool.try_encode_bounded(&msg, len, &mut buf).unwrap(), len);
3078 }
3079
3080 #[test]
3081 fn pool_try_encode_bounded_over_protobuf_limit_errors_as_too_large() {
3082 let msg = SizedMsg {
3083 reported_size: OVER_LIMIT,
3084 };
3085 let mut pool = crate::SizeCachePool::sequential(64);
3086 let mut buf = alloc::vec::Vec::new();
3087 assert_eq!(
3088 pool.try_encode_bounded(&msg, u32::MAX, &mut buf),
3089 Err(EncodeError::MessageTooLarge)
3090 );
3091 assert!(buf.is_empty());
3092 }
3093
3094 #[test]
3095 #[should_panic(expected = "2 GiB protobuf limit")]
3096 fn pool_encoded_len_over_limit_panics() {
3097 // SizeCachePool::encoded_len documents itself as the pooled
3098 // equivalent of Message::encoded_len — it must share the guard.
3099 let msg = SizedMsg {
3100 reported_size: OVER_LIMIT,
3101 };
3102 let mut pool = crate::SizeCachePool::sequential(1024);
3103 let _ = pool.encoded_len(&msg);
3104 }
3105
3106 #[cfg(debug_assertions)]
3107 #[test]
3108 #[should_panic(expected = "two-pass traversal mismatch")]
3109 fn encode_to_vec_ledger_catches_size_write_disagreement() {
3110 // An under-limit reported size with a no-op write_to: the guard
3111 // passes, then the debug ledger flags the two-pass divergence.
3112 let msg = SizedMsg { reported_size: 3 };
3113 let _ = msg.encode_to_vec();
3114 }
3115
3116 // ── DecodeOptions std::io::Read tests ─────────────────────────────
3117
3118 #[cfg(feature = "std")]
3119 mod reader_tests {
3120 use super::*;
3121
3122 #[test]
3123 fn decode_reader_basic() {
3124 let src = FlatMsg { value: 42 };
3125 let bytes = src.encode_to_vec();
3126 let msg: FlatMsg = DecodeOptions::new()
3127 .decode_reader(&mut bytes.as_slice())
3128 .unwrap();
3129 assert_eq!(msg.value, 42);
3130 }
3131
3132 #[test]
3133 fn decode_reader_rejects_oversize() {
3134 let src = FlatMsg { value: 42 };
3135 let bytes = src.encode_to_vec();
3136 let err = DecodeOptions::new()
3137 .with_max_message_size(1)
3138 .decode_reader::<FlatMsg>(&mut bytes.as_slice())
3139 .unwrap_err();
3140 assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
3141 }
3142
3143 #[test]
3144 fn decode_reader_exact_boundary() {
3145 // max_message_size == encoded length → success.
3146 let src = FlatMsg { value: 42 };
3147 let bytes = src.encode_to_vec();
3148 let msg: FlatMsg = DecodeOptions::new()
3149 .with_max_message_size(bytes.len())
3150 .decode_reader(&mut bytes.as_slice())
3151 .unwrap();
3152 assert_eq!(msg.value, 42);
3153 }
3154
3155 #[test]
3156 fn decode_options_reader_size_unbounded_getter_tracks_builder_order() {
3157 let opts = DecodeOptions::new();
3158 assert!(!opts.is_reader_size_unbounded());
3159
3160 let opts = opts.without_reader_size_limit();
3161 assert!(opts.is_reader_size_unbounded());
3162
3163 let opts = opts.with_max_message_size(1024);
3164 assert!(!opts.is_reader_size_unbounded());
3165 }
3166
3167 #[test]
3168 fn decode_reader_without_size_limit_does_not_overflow() {
3169 let src = FlatMsg { value: 42 };
3170 let bytes = src.encode_to_vec();
3171 let msg: FlatMsg = DecodeOptions::new()
3172 .without_reader_size_limit()
3173 .decode_reader(&mut bytes.as_slice())
3174 .unwrap();
3175 assert_eq!(msg.value, 42);
3176 }
3177
3178 #[test]
3179 fn decode_reader_with_max_message_size_after_without_limit_reenables_limit() {
3180 let src = FlatMsg { value: 42 };
3181 let bytes = src.encode_to_vec();
3182 let opts = DecodeOptions::new()
3183 .without_reader_size_limit()
3184 .with_max_message_size(1);
3185 assert!(!opts.is_reader_size_unbounded());
3186
3187 let err = opts
3188 .decode_reader::<FlatMsg>(&mut bytes.as_slice())
3189 .unwrap_err();
3190 assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
3191 }
3192
3193 #[test]
3194 fn decode_reader_without_size_limit_keeps_slice_limit() {
3195 let src = FlatMsg { value: 42 };
3196 let bytes = src.encode_to_vec();
3197 let opts = DecodeOptions::new()
3198 .with_max_message_size(1)
3199 .without_reader_size_limit();
3200 assert!(opts.is_reader_size_unbounded());
3201
3202 let slice_result: Result<FlatMsg, _> = opts.decode_from_slice(&bytes);
3203 assert_eq!(slice_result, Err(DecodeError::MessageTooLarge));
3204
3205 let msg: FlatMsg = opts.decode_reader(&mut bytes.as_slice()).unwrap();
3206 assert_eq!(msg.value, 42);
3207 }
3208
3209 #[test]
3210 fn decode_reader_propagates_read_error() {
3211 // A reader that errors immediately.
3212 struct ErrReader;
3213 impl std::io::Read for ErrReader {
3214 fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {
3215 Err(std::io::Error::new(std::io::ErrorKind::BrokenPipe, "gone"))
3216 }
3217 }
3218 let err = DecodeOptions::new()
3219 .decode_reader::<FlatMsg>(&mut ErrReader)
3220 .unwrap_err();
3221 assert_eq!(err.kind(), std::io::ErrorKind::BrokenPipe);
3222 }
3223
3224 #[test]
3225 fn decode_length_delimited_reader_basic() {
3226 let src = FlatMsg { value: 99 };
3227 let mut ld = Vec::new();
3228 src.encode_length_delimited(&mut ld);
3229 let msg: FlatMsg = DecodeOptions::new()
3230 .decode_length_delimited_reader(&mut ld.as_slice())
3231 .unwrap();
3232 assert_eq!(msg.value, 99);
3233 }
3234
3235 #[test]
3236 fn decode_length_delimited_reader_rejects_oversize_prefix() {
3237 // Length prefix claims more bytes than max_message_size allows.
3238 let src = FlatMsg { value: 99 };
3239 let mut ld = Vec::new();
3240 src.encode_length_delimited(&mut ld);
3241 let err = DecodeOptions::new()
3242 .with_max_message_size(1)
3243 .decode_length_delimited_reader::<FlatMsg>(&mut ld.as_slice())
3244 .unwrap_err();
3245 assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
3246 }
3247
3248 #[test]
3249 fn decode_length_delimited_reader_zero_length() {
3250 // A zero length prefix decodes to the default message and
3251 // consumes only the prefix byte.
3252 let stream = [0x00u8, 0xFF]; // len=0, then unrelated trailing byte
3253 let mut cursor = std::io::Cursor::new(stream);
3254 let msg: FlatMsg = DecodeOptions::new()
3255 .decode_length_delimited_reader(&mut cursor)
3256 .unwrap();
3257 assert_eq!(msg, FlatMsg::default());
3258 assert_eq!(cursor.position(), 1);
3259 }
3260
3261 #[test]
3262 fn decode_length_delimited_reader_truncated_reports_eof() {
3263 // Length prefix declares more bytes than the stream delivers.
3264 let src = FlatMsg { value: 99 };
3265 let mut ld = Vec::new();
3266 src.encode_length_delimited(&mut ld);
3267 ld.truncate(ld.len() - 1);
3268 let err = DecodeOptions::new()
3269 .decode_length_delimited_reader::<FlatMsg>(&mut ld.as_slice())
3270 .unwrap_err();
3271 assert_eq!(err.kind(), std::io::ErrorKind::UnexpectedEof);
3272 }
3273
3274 #[test]
3275 fn decode_length_delimited_reader_huge_claim_without_delivery() {
3276 // A 5-byte prefix declaring ~2 GiB followed by EOF must fail with
3277 // UnexpectedEof without allocating the declared length up front —
3278 // the buffer only grows as bytes are actually delivered. (This
3279 // test completes instantly; before the incremental-read fix it
3280 // zero-filled a ~2 GiB buffer first.)
3281 let mut stream = Vec::new();
3282 encode_varint(0x7FFF_FFF0, &mut stream); // just under the cap
3283 let err = DecodeOptions::new()
3284 .decode_length_delimited_reader::<FlatMsg>(&mut stream.as_slice())
3285 .unwrap_err();
3286 assert_eq!(err.kind(), std::io::ErrorKind::UnexpectedEof);
3287 }
3288
3289 #[test]
3290 fn decode_length_delimited_without_reader_size_limit_keeps_protobuf_cap() {
3291 let mut stream = Vec::new();
3292 encode_varint(0x8000_0000, &mut stream);
3293 let result: Result<FlatMsg, _> = DecodeOptions::new()
3294 .without_reader_size_limit()
3295 .decode_length_delimited(&mut stream.as_slice());
3296 assert_eq!(result, Err(DecodeError::MessageTooLarge));
3297 }
3298
3299 #[test]
3300 fn decode_length_delimited_reader_without_size_limit_keeps_protobuf_cap() {
3301 let mut stream = Vec::new();
3302 encode_varint(0x8000_0000, &mut stream);
3303 let err = DecodeOptions::new()
3304 .without_reader_size_limit()
3305 .decode_length_delimited_reader::<FlatMsg>(&mut stream.as_slice())
3306 .unwrap_err();
3307 assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
3308 }
3309
3310 #[test]
3311 fn decode_length_delimited_reader_sequential() {
3312 // Two messages in a stream — typical log-file use case.
3313 let a = FlatMsg { value: 10 };
3314 let b = FlatMsg { value: 20 };
3315 let mut stream = Vec::new();
3316 a.encode_length_delimited(&mut stream);
3317 b.encode_length_delimited(&mut stream);
3318
3319 let mut cursor = std::io::Cursor::new(stream);
3320 let first: FlatMsg = DecodeOptions::new()
3321 .decode_length_delimited_reader(&mut cursor)
3322 .unwrap();
3323 assert_eq!(first.value, 10);
3324 let second: FlatMsg = DecodeOptions::new()
3325 .decode_length_delimited_reader(&mut cursor)
3326 .unwrap();
3327 assert_eq!(second.value, 20);
3328 }
3329
3330 #[test]
3331 fn decode_length_delimited_reader_truncated_body() {
3332 // Length prefix says N bytes but reader EOFs early.
3333 let mut buf = Vec::new();
3334 crate::encoding::encode_varint(100, &mut buf);
3335 buf.push(0x08);
3336 let err = DecodeOptions::new()
3337 .decode_length_delimited_reader::<FlatMsg>(&mut buf.as_slice())
3338 .unwrap_err();
3339 assert_eq!(err.kind(), std::io::ErrorKind::UnexpectedEof);
3340 }
3341 }
3342
3343 // ── Contiguous sink routing ────────────────────────────────────────
3344 //
3345 // The `contiguous_sink_` prefix is the filter for the `Miri` CI step
3346 // that covers the pre-sized cursor; a renamed test silently leaves that
3347 // gate.
3348
3349 /// A `BufMut` with room receives a message through `advance_mut`, not
3350 /// through `put_*`, and one with less room is staged and appended once.
3351 /// The length prefix of `encode_length_delimited` goes through `put_*`.
3352 #[test]
3353 fn contiguous_sink_writes_in_place_when_there_is_room() {
3354 let msg = FlatMsg { value: 300 };
3355 let mut probe = crate::test_doubles::Probe::default();
3356 probe.inner.reserve(64);
3357 msg.encode(&mut probe);
3358 assert_eq!((probe.advance_mut_calls, probe.put_slice_calls), (1, 0));
3359 msg.encode_length_delimited(&mut probe);
3360 assert_eq!((probe.advance_mut_calls, probe.put_slice_calls), (2, 1));
3361
3362 let mut short = crate::test_doubles::Probe {
3363 chunk_limit: Some(2),
3364 ..Default::default()
3365 };
3366 msg.encode(&mut short);
3367 assert_eq!((short.advance_mut_calls, short.put_slice_calls), (0, 1));
3368 }
3369
3370 #[test]
3371 fn contiguous_sink_every_sink_receives_the_same_bytes() {
3372 let msg = FlatMsg { value: 300 };
3373 let expected = msg.encode_to_vec();
3374 assert_eq!(expected, [0x08, 0xAC, 0x02]);
3375
3376 // Appends after existing content.
3377 let mut prefixed = b"pre".to_vec();
3378 msg.encode(&mut prefixed);
3379 assert_eq!(&prefixed[..3], b"pre");
3380 assert_eq!(&prefixed[3..], &expected[..]);
3381
3382 let mut roomy = alloc::vec::Vec::with_capacity(64);
3383 msg.encode(&mut roomy);
3384 assert_eq!(roomy, expected);
3385
3386 let mut bytes_mut = bytes::BytesMut::new();
3387 msg.encode(&mut bytes_mut);
3388 assert_eq!(&bytes_mut[..], &expected[..]);
3389
3390 let mut storage = [0u8; 3];
3391 let mut slice: &mut [u8] = &mut storage;
3392 msg.encode(&mut slice);
3393 assert_eq!(storage, [0x08, 0xAC, 0x02]);
3394
3395 let mut rope = crate::Rope::new();
3396 msg.encode(&mut rope);
3397 assert_eq!(&rope.to_contiguous_bytes()[..], &expected[..]);
3398 }
3399
3400 #[test]
3401 fn contiguous_sink_framed_and_bounded_encodes_match() {
3402 let msg = FlatMsg { value: 300 };
3403
3404 let mut framed = alloc::vec::Vec::new();
3405 msg.encode_length_delimited(&mut framed);
3406 assert_eq!(framed, [3, 0x08, 0xAC, 0x02]);
3407
3408 let mut bounded = bytes::BytesMut::new();
3409 assert_eq!(msg.try_encode_bounded(3, &mut bounded), Ok(3));
3410 assert_eq!(&bounded[..], [0x08, 0xAC, 0x02]);
3411
3412 let mut cache = SizeCache::new();
3413 let mut cached = alloc::vec::Vec::new();
3414 msg.encode_with_cache(&mut cache, &mut cached);
3415 assert_eq!(cached, [0x08, 0xAC, 0x02]);
3416 }
3417
3418 #[test]
3419 #[should_panic(expected = "compute_size declared")]
3420 fn contiguous_sink_over_writing_panics() {
3421 let msg = Mismatched {
3422 declared: 1,
3423 written: 2,
3424 };
3425 msg.encode(&mut alloc::vec::Vec::new());
3426 }
3427
3428 #[cfg(debug_assertions)]
3429 #[test]
3430 #[should_panic(expected = "two-pass traversal mismatch")]
3431 fn contiguous_sink_under_writing_is_caught_in_debug_builds() {
3432 let msg = Mismatched {
3433 declared: 4,
3434 written: 2,
3435 };
3436 msg.encode(&mut alloc::vec::Vec::new());
3437 }
3438
3439 #[cfg(not(debug_assertions))]
3440 #[test]
3441 fn contiguous_sink_under_writing_appends_written_bytes() {
3442 let msg = Mismatched {
3443 declared: 4,
3444 written: 2,
3445 };
3446 let mut buf = alloc::vec::Vec::new();
3447 msg.encode(&mut buf);
3448 assert_eq!(buf, [0x55, 0x55]);
3449 }
3450}