Skip to main content

buffa/
extension.rs

1//! Typed access to protobuf extensions stored in unknown fields.
2//!
3//! Custom options — `(buf.validate.field)`, `(google.api.http)`, etc. — are
4//! declared with `extend google.protobuf.FieldOptions { ... }` and attached in
5//! proto source as `[(my.option) = {...}]`. Editions removed general-purpose
6//! message extensions but **custom options remain the sanctioned use of
7//! `extend`**: `descriptor.proto` still declares `extensions 1000 to max;` on
8//! every `*Options` message.
9//!
10//! On the wire, extension values are ordinary fields at their declared field
11//! numbers. When an extendee is decoded without the extension in its schema,
12//! those fields land in [`UnknownFields`] — already preserved. This module
13//! provides a typed extraction/injection path on top of that storage.
14//!
15//! # Usage
16//!
17//! Codegen emits a `pub const` for each `extend` declaration:
18//!
19//! ```ignore
20//! // Generated from: extend google.protobuf.FieldOptions { optional FieldRules field = 1159; }
21//! pub const FIELD: buffa::Extension<buffa::extension::codecs::MessageCodec<FieldRules>>
22//!     = buffa::Extension::new(1159, "google.protobuf.FieldOptions");
23//! ```
24//!
25//! The extendee (any message with unknown-field preservation) implements
26//! [`ExtensionSet`]:
27//!
28//! ```ignore
29//! use buffa::ExtensionSet;
30//! let rules: Option<FieldRules> = field.options.extension(&buf_validate::FIELD);
31//! opts.set_extension(&buf_validate::FIELD, my_rules);
32//! ```
33//!
34//! # Panics
35//!
36//! [`Extension::new`] and [`Extension::with_default`] panic if the extension
37//! field number is 0 or greater than `i32::MAX`.
38//!
39//! [`extension`], [`extension_or_default`], [`set_extension`],
40//! [`try_set_extension`], and [`clear_extension`] panic if the descriptor's
41//! [`extendee`](Extension::extendee) does not match the extendee message's
42//! [`PROTO_FQN`](ExtensionSet::PROTO_FQN). This catches bugs like
43//! `field_options.extension(&MESSAGE_LEVEL_OPTION)` at the first call site
44//! (matches protobuf-go, which panics, and protobuf-es, which throws).
45//! [`has_extension`] returns `false` gracefully on mismatch — "is this
46//! extension set here" when it can't extend here has a legitimate answer.
47//!
48//! # Defaults
49//!
50//! Proto2 `[default = ...]` values are surfaced by [`extension_or_default`],
51//! which returns the declared default when the extension is absent. Presence
52//! is still distinguishable via [`extension`] (returns `None`) or
53//! [`has_extension`].
54//!
55//! # JSON
56//!
57//! Extension fields serialize as `"[pkg.ext]"` keys in proto3 JSON. This
58//! requires a populated `TypeRegistry` — see the `type_registry` module
59//! (available under the `json` or `text` feature). Without a registry,
60//! extension bytes stay in `__buffa_unknown_fields` and are silently
61//! dropped from JSON output.
62//!
63//! # Presence semantics
64//!
65//! Extensions **always** have explicit field presence, regardless of proto3 or
66//! editions `IMPLICIT` file defaults (see protocolbuffers/protobuf#8234). This
67//! falls out naturally from unknown-field storage: `set_extension(&ext, 0)`
68//! pushes a record with value 0, so `has_extension` returns true. Singular
69//! `Output` is therefore `Option<T>`, not `T` with a sentinel.
70//!
71//! [`extension`]: ExtensionSet::extension
72//! [`set_extension`]: ExtensionSet::set_extension
73//! [`try_set_extension`]: ExtensionSet::try_set_extension
74//! [`clear_extension`]: ExtensionSet::clear_extension
75//! [`has_extension`]: ExtensionSet::has_extension
76//! [`extension_or_default`]: ExtensionSet::extension_or_default
77
78use core::marker::PhantomData;
79
80use crate::error::EncodeError;
81use crate::unknown_fields::UnknownFields;
82
83/// Typed extension descriptor.
84///
85/// Emitted by codegen as a `pub const` for each `extend` declaration. The
86/// type parameter `C` is an [`ExtensionCodec`] — a zero-sized codec struct
87/// that encodes the proto field type. Users don't name `C` directly; it flows
88/// through inference from the `const` to the [`ExtensionSet`] method call.
89///
90/// For proto2 extensions declared with `[default = ...]`, codegen stores a
91/// function pointer that lazily produces the default value. See
92/// [`Extension::with_default`] and [`ExtensionSet::extension_or_default`].
93#[derive(Debug)]
94pub struct Extension<C: ExtensionCodec> {
95    number: u32,
96    /// Fully-qualified proto name of the extendee (e.g.
97    /// `"google.protobuf.FieldOptions"`), no leading dot.
98    ///
99    /// Checked against [`ExtensionSet::PROTO_FQN`] by the accessors that the
100    /// module-level `# Panics` section lists — a mismatch panics.
101    /// `has_extension()` stays graceful (returns `false`), matching
102    /// protobuf-go and protobuf-es precedent.
103    extendee: &'static str,
104    default: Option<fn() -> C::Value>,
105    _codec: PhantomData<fn() -> C>,
106}
107
108impl<C: ExtensionCodec> Extension<C> {
109    /// Construct an extension descriptor for the given field number and
110    /// extendee message.
111    ///
112    /// `const fn` so that generated `pub const` items can use it.
113    ///
114    /// `extendee` is the fully-qualified proto type name (no leading dot) of
115    /// the message this extension extends — e.g. `"google.protobuf.FieldOptions"`.
116    /// Passing an extension with a mismatched extendee to an accessor that
117    /// reads, writes or clears it panics; the
118    /// [module documentation](crate::extension#panics) lists those accessors.
119    ///
120    /// # Panics
121    ///
122    /// Panics if `number` is 0 or greater than `i32::MAX`. In a `const` item
123    /// the panic is a compile error.
124    ///
125    /// The upper bound is `i32::MAX` because an extension of a message with
126    /// `option message_set_wire_format = true` can have a number up to that.
127    /// For any other extendee the largest valid number is
128    /// [`MAX_FIELD_NUMBER`](crate::encoding::MAX_FIELD_NUMBER): with a larger
129    /// one, `set_extension()` stores a field that encodes with a tag decoders
130    /// reject.
131    ///
132    /// # Examples
133    ///
134    /// ```
135    /// use buffa::extension::codecs::Int32;
136    /// use buffa::Extension;
137    ///
138    /// const WEIGHT: Extension<Int32> = Extension::new(50001, "my.pkg.Options");
139    /// assert_eq!(WEIGHT.number(), 50001);
140    /// ```
141    ///
142    /// A `const` with the number 0 does not compile:
143    ///
144    /// ```compile_fail,E0080
145    /// use buffa::extension::codecs::Int32;
146    /// use buffa::Extension;
147    ///
148    /// const ZERO: Extension<Int32> = Extension::new(0, "my.pkg.Options");
149    /// assert_eq!(ZERO.number(), 0);
150    /// ```
151    #[track_caller]
152    pub const fn new(number: u32, extendee: &'static str) -> Self {
153        assert_valid_extension_field_number(number);
154        Self {
155            number,
156            extendee,
157            default: None,
158            _codec: PhantomData,
159        }
160    }
161
162    /// Construct an extension descriptor with a proto2 `[default = ...]` value.
163    ///
164    /// The default is returned by [`ExtensionSet::extension_or_default`] when
165    /// the extension is absent. [`ExtensionSet::extension`] continues to return
166    /// `None` when absent — this is additive, not a semantic change.
167    ///
168    /// The function pointer is called lazily on each `extension_or_default`
169    /// call. For `Copy` scalars codegen emits a `const fn`; for `String` and
170    /// `bytes` a regular `fn` (allocates on each call — same cost as a
171    /// hand-written `.unwrap_or_else(|| "x".into())`).
172    ///
173    /// # Panics
174    ///
175    /// Panics if `number` is 0 or greater than `i32::MAX`, as
176    /// [`new`](Self::new) does.
177    #[track_caller]
178    pub const fn with_default(
179        number: u32,
180        extendee: &'static str,
181        default: fn() -> C::Value,
182    ) -> Self {
183        assert_valid_extension_field_number(number);
184        Self {
185            number,
186            extendee,
187            default: Some(default),
188            _codec: PhantomData,
189        }
190    }
191
192    /// The extension's field number on the extendee.
193    pub const fn number(&self) -> u32 {
194        self.number
195    }
196
197    /// The fully-qualified proto name of the extendee message.
198    pub const fn extendee(&self) -> &'static str {
199        self.extendee
200    }
201}
202
203/// Asserts the range that [`Extension::new`] documents, where the reason for
204/// the upper bound is given.
205///
206/// The implementation-reserved band (19000 to 19999) is not checked. It is a
207/// schema rule, which `DescriptorPool` applies when it loads a descriptor
208/// set; a number in the band encodes and decodes like any other.
209#[track_caller]
210const fn assert_valid_extension_field_number(number: u32) {
211    assert!(number != 0, "extension field number must not be 0");
212    assert!(
213        number <= crate::message_set::MAX_TYPE_ID,
214        "extension field number must be at most i32::MAX"
215    );
216}
217
218/// Asserts that `ext` actually extends `Self`. Called from `extension()`,
219/// `try_set_extension()`, and `clear_extension()`; the other accessors in the
220/// module-level `# Panics` list reach it through those. `has_extension()`
221/// does NOT call it — asking "is this extension set here" has a legitimate
222/// answer of `false` when it can't extend here, matching protobuf-go and
223/// protobuf-es.
224///
225/// `#[track_caller]` so the panic points at the user's call site, not here.
226#[track_caller]
227#[inline]
228fn assert_extendee<C: ExtensionCodec>(ext: &Extension<C>, expected: &'static str) {
229    assert_eq!(
230        ext.extendee, expected,
231        "extension at field {} extends `{}`, not `{}`",
232        ext.number, ext.extendee, expected
233    );
234}
235
236// Manual impls avoid a `C: Clone` / `C: Copy` bound that `#[derive]` would add.
237// `Option<fn() -> T>` is `Copy` for any `T` (fn pointers are always `Copy`),
238// so the struct remains `Copy` regardless of the codec's `Value` type.
239impl<C: ExtensionCodec> Clone for Extension<C> {
240    fn clone(&self) -> Self {
241        *self
242    }
243}
244impl<C: ExtensionCodec> Copy for Extension<C> {}
245
246/// One impl per proto field type. `Value` is what users pass to `set`;
247/// `Output` is what `get` returns (`Option<Value>` for singular,
248/// `Vec<Elem>` for repeated).
249pub trait ExtensionCodec {
250    /// The value type passed to [`ExtensionSet::set_extension`].
251    type Value;
252    /// The return type of [`ExtensionSet::extension`].
253    type Output;
254
255    /// Decode this extension's value from the extendee's unknown fields.
256    fn decode(number: u32, fields: &UnknownFields) -> Self::Output;
257
258    /// Encode `value` into the extendee's unknown fields.
259    ///
260    /// The caller is responsible for clearing any prior occurrences (see
261    /// [`ExtensionSet::set_extension`]). This is the one required encode
262    /// method — the fallible signature is required so that a codec whose
263    /// encode can fail (the message/group codecs, on an over-limit value)
264    /// cannot accidentally leave the fallible extension path panicking.
265    /// Infallible codecs (every scalar) simply end with `Ok(())`.
266    ///
267    /// Records pushed before an `Err` may remain in `fields`;
268    /// [`ExtensionSet::try_set_extension`] stages into a scratch set, so
269    /// the extendee itself is never affected by a failed set. Do not
270    /// implement this in terms of [`encode`](Self::encode) — that provided
271    /// wrapper calls back here.
272    ///
273    /// # Errors
274    ///
275    /// Returns [`EncodeError::MessageTooLarge`] if a message-typed value's
276    /// encoded size exceeds the 2 GiB protobuf limit
277    /// ([`MAX_MESSAGE_BYTES`](crate::MAX_MESSAGE_BYTES)).
278    fn try_encode(
279        number: u32,
280        value: Self::Value,
281        fields: &mut UnknownFields,
282    ) -> Result<(), EncodeError>;
283
284    /// Panicking wrapper over [`try_encode`](Self::try_encode).
285    ///
286    /// # Panics
287    ///
288    /// Panics if `try_encode` fails — i.e. a message-typed value's encoded
289    /// size exceeds the 2 GiB protobuf limit.
290    fn encode(number: u32, value: Self::Value, fields: &mut UnknownFields) {
291        Self::try_encode(number, value, fields)
292            .unwrap_or_else(|_| crate::message::encode_size_overflow())
293    }
294}
295
296/// Implemented by codegen on every message that preserves unknown fields.
297///
298/// The only required methods are the two `unknown_fields*` accessors; all
299/// extension operations are defaulted on top of them. The generated impl is
300/// therefore a two-line body.
301///
302/// Not object-safe (the default methods are generic over `C`). Extension
303/// access is always statically dispatched from a `const` descriptor.
304pub trait ExtensionSet {
305    /// Fully-qualified proto type name of this message (no leading dot),
306    /// e.g. `"google.protobuf.FieldOptions"`.
307    ///
308    /// Checked against [`Extension::extendee`] on every call of an accessor
309    /// that reads, writes or clears an extension; the
310    /// [module documentation](crate::extension#panics) lists them. A mismatch
311    /// panics: passing an extension for the wrong message is a bug in the
312    /// caller.
313    ///
314    /// Equal to [`MessageName::FULL_NAME`](crate::MessageName::FULL_NAME)
315    /// for generated messages — both come from the same `proto_fqn` in
316    /// codegen. Hand-written impls that implement both traits must keep the
317    /// two strings in sync; a mismatch surfaces as a runtime panic on
318    /// extension access rather than at compile time.
319    ///
320    /// If you only need the message's full name (no extension access), prefer
321    /// [`MessageName::FULL_NAME`](crate::MessageName::FULL_NAME): it
322    /// is a standalone trait that doesn't require the extension machinery or
323    /// the `unknown_fields=true` codegen option (which adds an
324    /// `__buffa_unknown_fields` storage field to the generated struct).
325    const PROTO_FQN: &'static str;
326
327    /// Immutable access to the extendee's unknown-field storage.
328    fn unknown_fields(&self) -> &UnknownFields;
329    /// Mutable access to the extendee's unknown-field storage.
330    fn unknown_fields_mut(&mut self) -> &mut UnknownFields;
331
332    /// Read an extension value.
333    ///
334    /// For singular extensions: `Option<T>` — `None` if absent, if the
335    /// stored wire data is malformed for this codec, or if the extension's
336    /// records together exhaust the decode budget.
337    ///
338    /// For repeated: `Vec<T>`, in wire order. A record that is malformed for
339    /// this codec is skipped.
340    ///
341    /// One decode budget covers every record of one extension. It is always
342    /// the crate default, whatever `DecodeOptions` decoded the carrier. For a
343    /// repeated message or group extension, each element's `size_of` is
344    /// charged to
345    /// [`DEFAULT_ELEMENT_MEMORY_LIMIT`](crate::DEFAULT_ELEMENT_MEMORY_LIMIT)
346    /// before the element is built, and the elements of the repeated and map
347    /// fields inside it are charged as it decodes. A charge is never
348    /// refunded, also for an element that is skipped, so the budget bounds
349    /// the element storage that one call builds. The contents of strings
350    /// and bytes are outside this budget.
351    ///
352    /// The getter stops at the first element that exceeds this budget and
353    /// returns the elements decoded before it. An element that fails for
354    /// another limit, the unknown-field allowance or the recursion limit, is
355    /// skipped like a malformed one, so only the element budget ends the
356    /// list.
357    ///
358    /// For a message or group extension each record is one element. To learn
359    /// whether elements are missing, compare the returned length with the
360    /// number of records in [`unknown_fields`](Self::unknown_fields) whose
361    /// `number` is [`ext.number()`](Extension::number).
362    ///
363    /// # Panics
364    ///
365    /// Panics if `ext.extendee()` does not match `Self::PROTO_FQN`.
366    #[track_caller]
367    fn extension<C: ExtensionCodec>(&self, ext: &Extension<C>) -> C::Output {
368        assert_extendee(ext, Self::PROTO_FQN);
369        C::decode(ext.number, self.unknown_fields())
370    }
371
372    /// Write an extension value, replacing any prior occurrences.
373    ///
374    /// # Panics
375    ///
376    /// Panics if `ext.extendee()` does not match `Self::PROTO_FQN`.
377    ///
378    /// Message-typed extension values are encoded to wire bytes on `set`,
379    /// so this also panics if the value's encoded size exceeds the 2 GiB
380    /// protobuf limit ([`MAX_MESSAGE_BYTES`](crate::MAX_MESSAGE_BYTES)) —
381    /// see [`try_set_extension`](Self::try_set_extension) for the
382    /// error-returning variant.
383    #[track_caller]
384    fn set_extension<C: ExtensionCodec>(&mut self, ext: &Extension<C>, value: C::Value) {
385        self.try_set_extension(ext, value)
386            .unwrap_or_else(|_| crate::message::encode_size_overflow())
387    }
388
389    /// Write an extension value, replacing any prior occurrences —
390    /// returning an error instead of panicking if a message-typed value's
391    /// encoded size exceeds the 2 GiB protobuf limit
392    /// ([`MAX_MESSAGE_BYTES`](crate::MAX_MESSAGE_BYTES)).
393    ///
394    /// On `Err`, the extendee's unknown fields are unchanged — prior
395    /// occurrences are retained.
396    ///
397    /// # Errors
398    ///
399    /// Returns [`EncodeError::MessageTooLarge`] if a message-typed value's
400    /// encoded size exceeds the limit. Scalar-typed extensions cannot fail.
401    ///
402    /// # Panics
403    ///
404    /// Panics if `ext.extendee()` does not match `Self::PROTO_FQN` —
405    /// passing an extension for the wrong message is a bug in the caller,
406    /// not a runtime condition.
407    #[track_caller]
408    fn try_set_extension<C: ExtensionCodec>(
409        &mut self,
410        ext: &Extension<C>,
411        value: C::Value,
412    ) -> Result<(), EncodeError> {
413        assert_extendee(ext, Self::PROTO_FQN);
414        // Stage into a scratch set first so `Err` leaves the extendee
415        // untouched (not even cleared).
416        let mut staged = UnknownFields::default();
417        C::try_encode(ext.number, value, &mut staged)?;
418        let fields = self.unknown_fields_mut();
419        fields.retain(|f| f.number != ext.number);
420        for f in staged {
421            fields.push(f);
422        }
423        Ok(())
424    }
425
426    /// Returns `true` if any record at the extension's field number is present.
427    ///
428    /// Does not check wire-type validity — this is a fast presence test, not
429    /// a decode. Also does not check extendee identity: asking "is this
430    /// extension set here" when it can't extend here has a legitimate answer
431    /// (`false`). This matches protobuf-go's `HasExtension` and protobuf-es's
432    /// `hasExtension`, both of which return `false` gracefully on mismatch.
433    fn has_extension<C: ExtensionCodec>(&self, ext: &Extension<C>) -> bool {
434        if ext.extendee != Self::PROTO_FQN {
435            return false;
436        }
437        self.unknown_fields().iter().any(|f| f.number == ext.number)
438    }
439
440    /// Remove all records at the extension's field number.
441    ///
442    /// # Panics
443    ///
444    /// Panics if `ext.extendee()` does not match `Self::PROTO_FQN`.
445    #[track_caller]
446    fn clear_extension<C: ExtensionCodec>(&mut self, ext: &Extension<C>) {
447        assert_extendee(ext, Self::PROTO_FQN);
448        self.unknown_fields_mut().retain(|f| f.number != ext.number);
449    }
450
451    /// Read a singular extension value, returning the proto2 `[default = ...]`
452    /// value if absent, or the type's `Default` if no proto default was declared.
453    ///
454    /// Only meaningful for singular codecs (`Output = Option<Value>`). For
455    /// repeated codecs use [`extension`](Self::extension) — there is no such
456    /// thing as a repeated default.
457    ///
458    /// Presence is still distinguishable via [`extension`](Self::extension)
459    /// (returns `None`) or [`has_extension`](Self::has_extension).
460    ///
461    /// # Panics
462    ///
463    /// Panics if `ext.extendee()` does not match `Self::PROTO_FQN`
464    /// (transitively, via the inner `extension()` call).
465    #[must_use]
466    #[track_caller]
467    fn extension_or_default<C>(&self, ext: &Extension<C>) -> C::Value
468    where
469        C: ExtensionCodec<Output = Option<<C as ExtensionCodec>::Value>>,
470        C::Value: Default,
471    {
472        self.extension(ext)
473            .or_else(|| ext.default.map(|f| f()))
474            .unwrap_or_default()
475    }
476}
477
478/// Codec types — one per proto field type.
479///
480/// These live in a submodule so they don't clutter the crate root. Generated
481/// consts mention the codec type (`Extension<codecs::MessageCodec<FieldRules>>`)
482/// but users never type it out — they just `opts.extension(&FIELD)` and
483/// inference handles the rest.
484pub mod codecs {
485    use core::marker::PhantomData;
486
487    use alloc::string::String;
488    use alloc::vec::Vec;
489    use bytes::Buf;
490
491    use crate::encoding::{decode_varint, encode_varint};
492    use crate::message::Message;
493    use crate::types::{
494        zigzag_decode_i32, zigzag_decode_i64, zigzag_encode_i32, zigzag_encode_i64,
495    };
496    use crate::unknown_fields::{UnknownField, UnknownFieldData, UnknownFields};
497
498    use super::ExtensionCodec;
499
500    /// Codecs that can appear as elements of [`Repeated`] / [`PackedRepeated`].
501    ///
502    /// Separated from [`ExtensionCodec`] because the singular decode semantics
503    /// differ by type: scalars use last-wins, but singular messages merge all
504    /// records. This trait provides the per-record primitives; each codec
505    /// assembles them into its own [`ExtensionCodec::decode`].
506    pub trait SingularCodec {
507        type Value;
508
509        /// Decode one value from one unknown-field record's data.
510        ///
511        /// Returns `None` on wire-type mismatch (and, for string/message,
512        /// on malformed payload).
513        fn decode_one(data: &UnknownFieldData) -> Option<Self::Value>;
514
515        /// Decode one value under a decode context shared with the other
516        /// records of the same field.
517        ///
518        /// Defaults to [`decode_one`](Self::decode_one), which is correct for
519        /// any codec whose per-record cost is fixed — every scalar, string,
520        /// and bytes codec. **A codec whose value can materialize an
521        /// unbounded subtree must override this**, or each record silently
522        /// gets its own full allowance of the crate-default limits.
523        ///
524        /// Such an override should also charge the value's `size_of` with
525        /// [`ctx.register_element_memory`](crate::DecodeContext::register_element_memory)
526        /// before it builds the value, as [`MessageCodec`] and [`GroupCodec`]
527        /// do. That charge bounds the `Vec` a repeated extension returns.
528        ///
529        /// For a repeated extension, a `None` returned while
530        /// [`ctx.remaining_element_memory()`](crate::DecodeContext::remaining_element_memory)
531        /// is `Some(0)` ends the whole list: the records after this one are
532        /// not read. With budget left, a `None` skips this record only. The
533        /// built-in message and group codecs end the list at the first
534        /// element that exceeds the element budget, including when a charge
535        /// inside the element's own decode fails. A failed charge leaves the
536        /// budget unchanged, so an override gets the same stop by spending
537        /// what is left before it returns `None`: it passes the value of
538        /// `remaining_element_memory()` to `register_element_memory`.
539        fn decode_one_ctx(
540            data: &UnknownFieldData,
541            _ctx: crate::DecodeContext<'_>,
542        ) -> Option<Self::Value> {
543            Self::decode_one(data)
544        }
545
546        /// Decode all values from a packed `LengthDelimited` payload.
547        ///
548        /// Non-packable types (string, bytes, message) **must leave `out`
549        /// unmodified**: `decode_repeated` falls through to this method when
550        /// [`decode_one`](Self::decode_one) returns `None` for a
551        /// `LengthDelimited` record, relying on the no-op to skip malformed
552        /// elements. A `LengthDelimited` record at their field number IS the
553        /// single value — there is no packed form.
554        fn decode_packed(bytes: &[u8], out: &mut Vec<Self::Value>);
555
556        /// Encode one value as a single unknown-field record.
557        ///
558        /// The one required encode method — same fallible-required contract
559        /// as [`ExtensionCodec::try_encode`]: infallible codecs (every
560        /// scalar) end with `Ok(...)`, and the message/group codecs surface
561        /// an over-limit value as an error. Do not implement this in terms
562        /// of [`encode_one`](Self::encode_one) — that provided wrapper
563        /// calls back here.
564        ///
565        /// # Errors
566        ///
567        /// Returns [`EncodeError::MessageTooLarge`](crate::EncodeError::MessageTooLarge)
568        /// if a message-typed value's encoded size exceeds the 2 GiB
569        /// protobuf limit ([`MAX_MESSAGE_BYTES`](crate::MAX_MESSAGE_BYTES)).
570        fn try_encode_one(value: &Self::Value) -> Result<UnknownFieldData, crate::EncodeError>;
571
572        /// Panicking wrapper over [`try_encode_one`](Self::try_encode_one).
573        ///
574        /// # Panics
575        ///
576        /// Panics if `try_encode_one` fails — i.e. a message-typed value's
577        /// encoded size exceeds the 2 GiB protobuf limit.
578        fn encode_one(value: &Self::Value) -> UnknownFieldData {
579            Self::try_encode_one(value).unwrap_or_else(|_| crate::message::encode_size_overflow())
580        }
581    }
582
583    /// Codecs whose elements can be concatenated into a packed wire form.
584    ///
585    /// Only varint-family and fixed-width scalars are packable. String, bytes,
586    /// and message use `LengthDelimited` for a single value, so there's no
587    /// distinct packed encoding.
588    pub trait PackableCodec: SingularCodec {
589        /// Write one value's wire payload (without tag) into `buf`.
590        fn encode_packed(value: &Self::Value, buf: &mut Vec<u8>);
591    }
592
593    // ─────────────────────────────────────────────────────────────────────
594    // Varint-family scalar codecs
595    // ─────────────────────────────────────────────────────────────────────
596
597    macro_rules! varint_codec {
598        ($name:ident, $ty:ty, |$d:ident| $decode:expr, |$e:ident| $encode:expr $(,)?) => {
599            #[doc = concat!("Codec for the `", stringify!($name), "` proto scalar type.")]
600            pub struct $name;
601
602            impl ExtensionCodec for $name {
603                type Value = $ty;
604                type Output = Option<$ty>;
605                fn decode(number: u32, fields: &UnknownFields) -> Option<$ty> {
606                    fields
607                        .iter()
608                        .rev()
609                        .filter(|f| f.number == number)
610                        .find_map(|f| Self::decode_one(&f.data))
611                }
612                fn try_encode(
613                    number: u32,
614                    value: $ty,
615                    fields: &mut UnknownFields,
616                ) -> Result<(), crate::EncodeError> {
617                    fields.push(UnknownField {
618                        number,
619                        data: Self::try_encode_one(&value)?,
620                    });
621                    Ok(())
622                }
623            }
624
625            impl SingularCodec for $name {
626                type Value = $ty;
627                fn decode_one(data: &UnknownFieldData) -> Option<$ty> {
628                    match *data {
629                        UnknownFieldData::Varint($d) => Some($decode),
630                        _ => None,
631                    }
632                }
633                fn decode_packed(bytes: &[u8], out: &mut Vec<$ty>) {
634                    let mut buf = bytes;
635                    // Deliberately the plain `decode_varint`, not the
636                    // force-inlined packed twin used by generated message
637                    // loops: extension decode runs off unknown-field
638                    // storage and is not hot enough to justify the
639                    // per-call-site code-size cost.
640                    while buf.has_remaining() {
641                        match decode_varint(&mut buf) {
642                            Ok($d) => out.push($decode),
643                            Err(_) => return,
644                        }
645                    }
646                }
647                fn try_encode_one($e: &$ty) -> Result<UnknownFieldData, crate::EncodeError> {
648                    let $e = *$e;
649                    Ok(UnknownFieldData::Varint($encode))
650                }
651            }
652
653            impl PackableCodec for $name {
654                fn encode_packed($e: &$ty, buf: &mut Vec<u8>) {
655                    let $e = *$e;
656                    encode_varint($encode, buf);
657                }
658            }
659        };
660    }
661
662    // `int32` negative values are sign-extended to 64 bits before varint
663    // encoding (matching protoc's behavior — a negative int32 is 10 bytes on
664    // the wire). `sint32` uses zigzag instead.
665    varint_codec!(Int32, i32, |v| v as i32, |v| v as i64 as u64);
666    varint_codec!(Int64, i64, |v| v as i64, |v| v as u64);
667    varint_codec!(Uint32, u32, |v| v as u32, |v| v as u64);
668    varint_codec!(Uint64, u64, |v| v, |v| v);
669    varint_codec!(
670        Sint32,
671        i32,
672        |v| zigzag_decode_i32(v as u32),
673        |v| zigzag_encode_i32(v) as u64
674    );
675    varint_codec!(
676        Sint64,
677        i64,
678        |v| zigzag_decode_i64(v),
679        |v| zigzag_encode_i64(v)
680    );
681    varint_codec!(Bool, bool, |v| v != 0, |v| v as u64);
682    /// Codec for proto `enum` extension fields.
683    ///
684    /// `Value = i32`; cast via `EnumValue::from_i32` at the call site.
685    /// A type-directed enum codec (emitting `Extension<MyEnum>`) is deferred.
686    pub struct EnumI32;
687    // EnumI32 is wire-identical to Int32 — delegate rather than re-expand.
688    impl ExtensionCodec for EnumI32 {
689        type Value = i32;
690        type Output = Option<i32>;
691        fn decode(number: u32, fields: &UnknownFields) -> Option<i32> {
692            Int32::decode(number, fields)
693        }
694        fn try_encode(
695            number: u32,
696            value: i32,
697            fields: &mut UnknownFields,
698        ) -> Result<(), crate::EncodeError> {
699            Int32::try_encode(number, value, fields)
700        }
701    }
702    impl SingularCodec for EnumI32 {
703        type Value = i32;
704        fn decode_one(data: &UnknownFieldData) -> Option<i32> {
705            Int32::decode_one(data)
706        }
707        fn decode_packed(bytes: &[u8], out: &mut Vec<i32>) {
708            Int32::decode_packed(bytes, out)
709        }
710        fn try_encode_one(value: &i32) -> Result<UnknownFieldData, crate::EncodeError> {
711            Int32::try_encode_one(value)
712        }
713    }
714    impl PackableCodec for EnumI32 {
715        fn encode_packed(value: &i32, buf: &mut Vec<u8>) {
716            Int32::encode_packed(value, buf)
717        }
718    }
719
720    // ─────────────────────────────────────────────────────────────────────
721    // Fixed-width scalar codecs
722    // ─────────────────────────────────────────────────────────────────────
723
724    macro_rules! fixed32_codec {
725        ($name:ident, $ty:ty, |$d:ident| $decode:expr, |$e:ident| $encode:expr $(,)?) => {
726            #[doc = concat!("Codec for the `", stringify!($name), "` proto scalar type.")]
727            pub struct $name;
728
729            impl ExtensionCodec for $name {
730                type Value = $ty;
731                type Output = Option<$ty>;
732                fn decode(number: u32, fields: &UnknownFields) -> Option<$ty> {
733                    fields
734                        .iter()
735                        .rev()
736                        .filter(|f| f.number == number)
737                        .find_map(|f| Self::decode_one(&f.data))
738                }
739                fn try_encode(
740                    number: u32,
741                    value: $ty,
742                    fields: &mut UnknownFields,
743                ) -> Result<(), crate::EncodeError> {
744                    fields.push(UnknownField {
745                        number,
746                        data: Self::try_encode_one(&value)?,
747                    });
748                    Ok(())
749                }
750            }
751
752            impl SingularCodec for $name {
753                type Value = $ty;
754                fn decode_one(data: &UnknownFieldData) -> Option<$ty> {
755                    match *data {
756                        UnknownFieldData::Fixed32($d) => Some($decode),
757                        _ => None,
758                    }
759                }
760                fn decode_packed(bytes: &[u8], out: &mut Vec<$ty>) {
761                    let mut buf = bytes;
762                    while buf.remaining() >= 4 {
763                        let $d = buf.get_u32_le();
764                        out.push($decode);
765                    }
766                }
767                fn try_encode_one($e: &$ty) -> Result<UnknownFieldData, crate::EncodeError> {
768                    let $e = *$e;
769                    Ok(UnknownFieldData::Fixed32($encode))
770                }
771            }
772
773            impl PackableCodec for $name {
774                fn encode_packed($e: &$ty, buf: &mut Vec<u8>) {
775                    use bytes::BufMut;
776                    let $e = *$e;
777                    buf.put_u32_le($encode);
778                }
779            }
780        };
781    }
782
783    macro_rules! fixed64_codec {
784        ($name:ident, $ty:ty, |$d:ident| $decode:expr, |$e:ident| $encode:expr $(,)?) => {
785            #[doc = concat!("Codec for the `", stringify!($name), "` proto scalar type.")]
786            pub struct $name;
787
788            impl ExtensionCodec for $name {
789                type Value = $ty;
790                type Output = Option<$ty>;
791                fn decode(number: u32, fields: &UnknownFields) -> Option<$ty> {
792                    fields
793                        .iter()
794                        .rev()
795                        .filter(|f| f.number == number)
796                        .find_map(|f| Self::decode_one(&f.data))
797                }
798                fn try_encode(
799                    number: u32,
800                    value: $ty,
801                    fields: &mut UnknownFields,
802                ) -> Result<(), crate::EncodeError> {
803                    fields.push(UnknownField {
804                        number,
805                        data: Self::try_encode_one(&value)?,
806                    });
807                    Ok(())
808                }
809            }
810
811            impl SingularCodec for $name {
812                type Value = $ty;
813                fn decode_one(data: &UnknownFieldData) -> Option<$ty> {
814                    match *data {
815                        UnknownFieldData::Fixed64($d) => Some($decode),
816                        _ => None,
817                    }
818                }
819                fn decode_packed(bytes: &[u8], out: &mut Vec<$ty>) {
820                    let mut buf = bytes;
821                    while buf.remaining() >= 8 {
822                        let $d = buf.get_u64_le();
823                        out.push($decode);
824                    }
825                }
826                fn try_encode_one($e: &$ty) -> Result<UnknownFieldData, crate::EncodeError> {
827                    let $e = *$e;
828                    Ok(UnknownFieldData::Fixed64($encode))
829                }
830            }
831
832            impl PackableCodec for $name {
833                fn encode_packed($e: &$ty, buf: &mut Vec<u8>) {
834                    use bytes::BufMut;
835                    let $e = *$e;
836                    buf.put_u64_le($encode);
837                }
838            }
839        };
840    }
841
842    fixed32_codec!(Fixed32, u32, |v| v, |v| v);
843    fixed32_codec!(Sfixed32, i32, |v| v as i32, |v| v as u32);
844    fixed32_codec!(Float, f32, |v| f32::from_bits(v), |v| v.to_bits());
845    fixed64_codec!(Fixed64, u64, |v| v, |v| v);
846    fixed64_codec!(Sfixed64, i64, |v| v as i64, |v| v as u64);
847    fixed64_codec!(Double, f64, |v| f64::from_bits(v), |v| v.to_bits());
848
849    // ─────────────────────────────────────────────────────────────────────
850    // String / bytes / message codecs (hand-written, not packable)
851    // ─────────────────────────────────────────────────────────────────────
852
853    /// Codec for the `string` proto type.
854    ///
855    /// Singular decode reads the last length-delimited record at the field
856    /// number and returns `None` when that record is not valid UTF-8, whatever
857    /// earlier records hold. Records with other wire types are ignored.
858    pub struct StringCodec;
859
860    impl ExtensionCodec for StringCodec {
861        type Value = String;
862        type Output = Option<String>;
863        fn decode(number: u32, fields: &UnknownFields) -> Option<String> {
864            fields
865                .iter()
866                .rev()
867                .filter(|f| f.number == number)
868                .find(|f| matches!(&f.data, UnknownFieldData::LengthDelimited(_)))
869                .and_then(|f| Self::decode_one(&f.data))
870        }
871        fn try_encode(
872            number: u32,
873            value: String,
874            fields: &mut UnknownFields,
875        ) -> Result<(), crate::EncodeError> {
876            fields.push(UnknownField {
877                number,
878                data: UnknownFieldData::LengthDelimited(value.into_bytes()),
879            });
880            Ok(())
881        }
882    }
883
884    impl SingularCodec for StringCodec {
885        type Value = String;
886        fn decode_one(data: &UnknownFieldData) -> Option<String> {
887            match data {
888                UnknownFieldData::LengthDelimited(bytes) => String::from_utf8(bytes.clone()).ok(),
889                _ => None,
890            }
891        }
892        fn decode_packed(_bytes: &[u8], _out: &mut Vec<String>) {}
893        fn try_encode_one(value: &String) -> Result<UnknownFieldData, crate::EncodeError> {
894            Ok(UnknownFieldData::LengthDelimited(
895                value.clone().into_bytes(),
896            ))
897        }
898    }
899
900    /// Codec for the `bytes` proto type.
901    pub struct BytesCodec;
902
903    impl ExtensionCodec for BytesCodec {
904        type Value = Vec<u8>;
905        type Output = Option<Vec<u8>>;
906        fn decode(number: u32, fields: &UnknownFields) -> Option<Vec<u8>> {
907            fields
908                .iter()
909                .rev()
910                .filter(|f| f.number == number)
911                .find_map(|f| Self::decode_one(&f.data))
912        }
913        fn try_encode(
914            number: u32,
915            value: Vec<u8>,
916            fields: &mut UnknownFields,
917        ) -> Result<(), crate::EncodeError> {
918            fields.push(UnknownField {
919                number,
920                data: UnknownFieldData::LengthDelimited(value),
921            });
922            Ok(())
923        }
924    }
925
926    impl SingularCodec for BytesCodec {
927        type Value = Vec<u8>;
928        fn decode_one(data: &UnknownFieldData) -> Option<Vec<u8>> {
929            match data {
930                UnknownFieldData::LengthDelimited(bytes) => Some(bytes.clone()),
931                _ => None,
932            }
933        }
934        fn decode_packed(_bytes: &[u8], _out: &mut Vec<Vec<u8>>) {}
935        fn try_encode_one(value: &Vec<u8>) -> Result<UnknownFieldData, crate::EncodeError> {
936            Ok(UnknownFieldData::LengthDelimited(value.clone()))
937        }
938    }
939
940    /// Codec for message-typed extension fields.
941    ///
942    /// Singular decode **merges all** `LengthDelimited` records at the field
943    /// number (proto spec: split messages merge). Any malformed record aborts
944    /// the merge and returns `None`.
945    pub struct MessageCodec<M>(PhantomData<fn() -> M>);
946
947    impl<M: Message + Default> ExtensionCodec for MessageCodec<M> {
948        type Value = M;
949        type Output = Option<M>;
950        fn decode(number: u32, fields: &UnknownFields) -> Option<M> {
951            let mut msg: Option<M> = None;
952            let (limit, elem) = extension_decode_cells();
953            let ctx = crate::DecodeContext::new(crate::RECURSION_LIMIT, &limit)
954                .with_element_memory(&elem);
955            for f in fields.iter().filter(|f| f.number == number) {
956                if let UnknownFieldData::LengthDelimited(bytes) = &f.data {
957                    let m = msg.get_or_insert_with(M::default);
958                    if m.merge(&mut &bytes[..], ctx).is_err() {
959                        return None;
960                    }
961                }
962            }
963            msg
964        }
965        fn try_encode(
966            number: u32,
967            value: M,
968            fields: &mut UnknownFields,
969        ) -> Result<(), crate::EncodeError> {
970            fields.push(UnknownField {
971                number,
972                data: UnknownFieldData::LengthDelimited(value.try_encode_to_vec()?),
973            });
974            Ok(())
975        }
976    }
977
978    impl<M: Message + Default> SingularCodec for MessageCodec<M> {
979        type Value = M;
980        fn decode_one(data: &UnknownFieldData) -> Option<M> {
981            match data {
982                UnknownFieldData::LengthDelimited(bytes) => {
983                    let mut m = M::default();
984                    m.merge_from_slice(bytes).ok()?;
985                    Some(m)
986                }
987                _ => None,
988            }
989        }
990        fn decode_one_ctx(data: &UnknownFieldData, ctx: crate::DecodeContext<'_>) -> Option<M> {
991            match data {
992                UnknownFieldData::LengthDelimited(bytes) => {
993                    decode_charged(ctx, |m: &mut M| m.merge(&mut &bytes[..], ctx))
994                }
995                _ => None,
996            }
997        }
998        fn decode_packed(_bytes: &[u8], _out: &mut Vec<M>) {}
999        fn try_encode_one(value: &M) -> Result<UnknownFieldData, crate::EncodeError> {
1000            Ok(UnknownFieldData::LengthDelimited(
1001                value.try_encode_to_vec()?,
1002            ))
1003        }
1004    }
1005
1006    /// Codec for group-encoded message extension fields (proto2 `group` syntax
1007    /// or editions `features.message_encoding = DELIMITED`).
1008    ///
1009    /// The wire data is [`UnknownFieldData::Group`] — the inner fields are
1010    /// already parsed into an [`UnknownFields`] sub-tree by the group decoder.
1011    /// Decode re-serializes the inner fields to a temporary buffer then merges
1012    /// into `M`; encode does the reverse via [`UnknownFields::decode_from_slice`].
1013    ///
1014    /// The round-trip through bytes is correct but not optimal. The alternative
1015    /// (a `Message::write_to_unknown_fields()` trait method) would be invasive
1016    /// for a rare-in-practice path: group-encoded extensions don't appear in
1017    /// real custom options.
1018    ///
1019    /// Singular decode **merges all** `Group` records at the field number
1020    /// (same as [`MessageCodec`]). Any malformed record aborts and returns
1021    /// `None`.
1022    pub struct GroupCodec<M>(PhantomData<fn() -> M>);
1023
1024    impl<M: Message + Default> ExtensionCodec for GroupCodec<M> {
1025        type Value = M;
1026        type Output = Option<M>;
1027        fn decode(number: u32, fields: &UnknownFields) -> Option<M> {
1028            let mut msg: Option<M> = None;
1029            let (limit, elem) = extension_decode_cells();
1030            let ctx = crate::DecodeContext::new(crate::RECURSION_LIMIT, &limit)
1031                .with_element_memory(&elem);
1032            for f in fields.iter().filter(|f| f.number == number) {
1033                if let UnknownFieldData::Group(inner) = &f.data {
1034                    let m = msg.get_or_insert_with(M::default);
1035                    let mut buf = Vec::with_capacity(inner.encoded_len());
1036                    inner.write_to(&mut buf);
1037                    if m.merge(&mut &buf[..], ctx).is_err() {
1038                        return None;
1039                    }
1040                }
1041            }
1042            msg
1043        }
1044        fn try_encode(
1045            number: u32,
1046            value: M,
1047            fields: &mut UnknownFields,
1048        ) -> Result<(), crate::EncodeError> {
1049            let bytes = value.try_encode_to_vec()?;
1050            // We just encoded `value` — re-decoding its bytes cannot fail
1051            // unless there's a bug in the Message encoder itself.
1052            let inner = UnknownFields::decode_from_slice(&bytes)
1053                .expect("BUG: re-decoding freshly-encoded message bytes failed");
1054            fields.push(UnknownField {
1055                number,
1056                data: UnknownFieldData::Group(inner),
1057            });
1058            Ok(())
1059        }
1060    }
1061
1062    impl<M: Message + Default> SingularCodec for GroupCodec<M> {
1063        type Value = M;
1064        fn decode_one(data: &UnknownFieldData) -> Option<M> {
1065            match data {
1066                UnknownFieldData::Group(inner) => {
1067                    let mut buf = Vec::with_capacity(inner.encoded_len());
1068                    inner.write_to(&mut buf);
1069                    let mut m = M::default();
1070                    m.merge_from_slice(&buf).ok()?;
1071                    Some(m)
1072                }
1073                _ => None,
1074            }
1075        }
1076        fn decode_one_ctx(data: &UnknownFieldData, ctx: crate::DecodeContext<'_>) -> Option<M> {
1077            match data {
1078                UnknownFieldData::Group(inner) => decode_charged(ctx, |m: &mut M| {
1079                    let mut buf = Vec::with_capacity(inner.encoded_len());
1080                    inner.write_to(&mut buf);
1081                    m.merge(&mut &buf[..], ctx)
1082                }),
1083                _ => None,
1084            }
1085        }
1086        // Groups are never packed — leave `out` unmodified (see
1087        // `SingularCodec::decode_packed` contract).
1088        fn decode_packed(_bytes: &[u8], _out: &mut Vec<M>) {}
1089        fn try_encode_one(value: &M) -> Result<UnknownFieldData, crate::EncodeError> {
1090            let bytes = value.try_encode_to_vec()?;
1091            // We just encoded `value` — re-decoding cannot fail.
1092            let inner = UnknownFields::decode_from_slice(&bytes)
1093                .expect("BUG: re-decoding freshly-encoded message bytes failed");
1094            Ok(UnknownFieldData::Group(inner))
1095        }
1096    }
1097
1098    // ─────────────────────────────────────────────────────────────────────
1099    // Repeated wrappers
1100    // ─────────────────────────────────────────────────────────────────────
1101
1102    /// Codec for `repeated T` extension fields, unpacked wire encoding.
1103    ///
1104    /// Decode accepts both packed and unpacked wire forms (proto spec
1105    /// requires this). Encode emits one record per element — this is the
1106    /// proto2 default for extensions and what `*Options` extendees expect.
1107    pub struct Repeated<C>(PhantomData<fn() -> C>);
1108
1109    impl<C: SingularCodec> ExtensionCodec for Repeated<C> {
1110        type Value = Vec<C::Value>;
1111        type Output = Vec<C::Value>;
1112        fn decode(number: u32, fields: &UnknownFields) -> Vec<C::Value> {
1113            decode_repeated::<C>(number, fields)
1114        }
1115        fn try_encode(
1116            number: u32,
1117            value: Vec<C::Value>,
1118            fields: &mut UnknownFields,
1119        ) -> Result<(), crate::EncodeError> {
1120            // Records already pushed stay in `fields` if a later element
1121            // errs — `try_set_extension`'s scratch staging is what keeps
1122            // the extendee itself untouched.
1123            for v in &value {
1124                fields.push(UnknownField {
1125                    number,
1126                    data: C::try_encode_one(v)?,
1127                });
1128            }
1129            Ok(())
1130        }
1131    }
1132
1133    /// Codec for `repeated T` extension fields, packed wire encoding.
1134    ///
1135    /// Decode accepts both packed and unpacked wire forms (identical to
1136    /// [`Repeated`]). Encode emits a single `LengthDelimited` record
1137    /// containing concatenated wire values. Only valid for packable scalar
1138    /// element types (varint / fixed families).
1139    ///
1140    /// Codegen picks this over [`Repeated`] when `field.options.packed ==
1141    /// Some(true)` or the resolved edition feature `repeated_field_encoding
1142    /// == PACKED`.
1143    pub struct PackedRepeated<C>(PhantomData<fn() -> C>);
1144
1145    impl<C: PackableCodec> ExtensionCodec for PackedRepeated<C> {
1146        type Value = Vec<C::Value>;
1147        type Output = Vec<C::Value>;
1148        fn decode(number: u32, fields: &UnknownFields) -> Vec<C::Value> {
1149            decode_repeated::<C>(number, fields)
1150        }
1151        fn try_encode(
1152            number: u32,
1153            value: Vec<C::Value>,
1154            fields: &mut UnknownFields,
1155        ) -> Result<(), crate::EncodeError> {
1156            if value.is_empty() {
1157                return Ok(());
1158            }
1159            let mut buf = Vec::new();
1160            for v in &value {
1161                C::encode_packed(v, &mut buf);
1162            }
1163            fields.push(UnknownField {
1164                number,
1165                data: UnknownFieldData::LengthDelimited(buf),
1166            });
1167            Ok(())
1168        }
1169    }
1170
1171    /// A decode context whose budgets are shared across every record of one
1172    /// extension field.
1173    ///
1174    /// `Message::merge_from_slice` mints fresh budget cells on each call, so
1175    /// merging N records one at a time gives each its own full allowance and
1176    /// turns the documented per-decode absolutes into per-record ones. An
1177    /// extension can carry arbitrarily many records, so that multiplies.
1178    /// Building the cells once and reusing the (`Copy`) context keeps the
1179    /// bound absolute.
1180    ///
1181    /// These are always the crate defaults: `ExtensionSet::extension` takes
1182    /// no context, so a `DecodeOptions` used to decode the carrier does not
1183    /// reach here.
1184    fn extension_decode_cells() -> (core::cell::Cell<usize>, core::cell::Cell<usize>) {
1185        (
1186            core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT),
1187            core::cell::Cell::new(crate::DEFAULT_ELEMENT_MEMORY_LIMIT),
1188        )
1189    }
1190
1191    /// Decodes one element of a repeated message or group extension: charges
1192    /// `size_of::<M>()` to the element-memory budget, then runs `merge` on a
1193    /// default `M`.
1194    ///
1195    /// The charges of an element that fails stay spent, as its unknown-field
1196    /// allowance does, so the budget bounds the element storage that one
1197    /// `extension()` call builds in total and not only what is live at once.
1198    /// When the failure is the element-memory budget itself, the rest of the
1199    /// budget is spent too. That does not add to the bound; it is how
1200    /// `decode_repeated_with_context` learns that it must stop, so the list
1201    /// ends at the first element that does not fit.
1202    fn decode_charged<M: Default>(
1203        ctx: crate::DecodeContext<'_>,
1204        merge: impl FnOnce(&mut M) -> Result<(), crate::DecodeError>,
1205    ) -> Option<M> {
1206        let decoded = ctx
1207            .register_element_memory(core::mem::size_of::<M>())
1208            .and_then(|()| {
1209                let mut m = M::default();
1210                merge(&mut m)?;
1211                Ok(m)
1212            });
1213        if matches!(decoded, Err(crate::DecodeError::ElementMemoryLimitExceeded)) {
1214            ctx.exhaust_element_memory();
1215        }
1216        decoded.ok()
1217    }
1218
1219    /// Decodes a repeated extension under the crate-default budgets.
1220    fn decode_repeated<C: SingularCodec>(number: u32, fields: &UnknownFields) -> Vec<C::Value> {
1221        // Every element stays live in the returned `Vec`, so one budget
1222        // covers all of them.
1223        let (limit, elem) = extension_decode_cells();
1224        let ctx =
1225            crate::DecodeContext::new(crate::RECURSION_LIMIT, &limit).with_element_memory(&elem);
1226        decode_repeated_with_context::<C>(number, fields, ctx)
1227    }
1228
1229    /// Shared repeated-decode logic: accepts both unpacked (one record per
1230    /// value) and packed (`LengthDelimited` of concatenated values).
1231    ///
1232    /// A record that `decode_one_ctx` rejects is skipped, and the loop goes on
1233    /// to the next record. The exception is an element-memory budget that is
1234    /// spent: the loop stops there and returns the elements decoded so far.
1235    /// [`MessageCodec`] and [`GroupCodec`] spend the whole budget when an
1236    /// element exceeds it, so a smaller element after it cannot be returned
1237    /// in its place.
1238    pub(super) fn decode_repeated_with_context<C: SingularCodec>(
1239        number: u32,
1240        fields: &UnknownFields,
1241        ctx: crate::DecodeContext<'_>,
1242    ) -> Vec<C::Value> {
1243        let mut out = Vec::new();
1244        for f in fields.iter().filter(|f| f.number == number) {
1245            if let Some(v) = C::decode_one_ctx(&f.data, ctx) {
1246                out.push(v);
1247            } else if ctx.remaining_element_memory() == Some(0) {
1248                break;
1249            } else if let UnknownFieldData::LengthDelimited(bytes) = &f.data {
1250                C::decode_packed(bytes, &mut out);
1251            }
1252        }
1253        out
1254    }
1255}
1256
1257// ─────────────────────────────────────────────────────────────────────────────
1258// Tests
1259// ─────────────────────────────────────────────────────────────────────────────
1260
1261#[cfg(test)]
1262mod tests {
1263    use super::codecs::*;
1264    use super::*;
1265    use crate::unknown_fields::{UnknownField, UnknownFieldData};
1266    use alloc::string::{String, ToString};
1267    use alloc::{vec, vec::Vec};
1268
1269    // Fake extendee — manually implements ExtensionSet over an UnknownFields.
1270    // All test `Extension<_>` consts use `CARRIER` as their extendee so the
1271    // identity check passes.
1272    const CARRIER: &str = "test.Carrier";
1273
1274    #[derive(Default)]
1275    struct Carrier {
1276        unknown: UnknownFields,
1277    }
1278    impl ExtensionSet for Carrier {
1279        const PROTO_FQN: &'static str = CARRIER;
1280        fn unknown_fields(&self) -> &UnknownFields {
1281            &self.unknown
1282        }
1283        fn unknown_fields_mut(&mut self) -> &mut UnknownFields {
1284            &mut self.unknown
1285        }
1286    }
1287
1288    fn varint(number: u32, v: u64) -> UnknownField {
1289        UnknownField {
1290            number,
1291            data: UnknownFieldData::Varint(v),
1292        }
1293    }
1294    fn fixed32(number: u32, v: u32) -> UnknownField {
1295        UnknownField {
1296            number,
1297            data: UnknownFieldData::Fixed32(v),
1298        }
1299    }
1300    fn fixed64(number: u32, v: u64) -> UnknownField {
1301        UnknownField {
1302            number,
1303            data: UnknownFieldData::Fixed64(v),
1304        }
1305    }
1306    fn ld(number: u32, data: Vec<u8>) -> UnknownField {
1307        UnknownField {
1308            number,
1309            data: UnknownFieldData::LengthDelimited(data),
1310        }
1311    }
1312    fn group(number: u32, inner: UnknownFields) -> UnknownField {
1313        UnknownField {
1314            number,
1315            data: UnknownFieldData::Group(inner),
1316        }
1317    }
1318
1319    // ── Extension<C> basics ─────────────────────────────────────────────────
1320
1321    #[test]
1322    fn extension_const_fn() {
1323        const EXT: Extension<Int32> = Extension::new(50001, CARRIER);
1324        assert_eq!(EXT.number(), 50001);
1325        assert_eq!(EXT.extendee(), CARRIER);
1326        let copy = EXT; // Copy
1327        assert_eq!(copy.number(), 50001);
1328    }
1329
1330    #[test]
1331    fn extension_with_default_const_fn() {
1332        // Naming a non-const fn in a const context is fine; only *calling*
1333        // it would not be. `with_default` just stores the pointer.
1334        const fn seven() -> i32 {
1335            7
1336        }
1337        const E: Extension<Int32> = Extension::with_default(1, CARRIER, seven);
1338        assert_eq!(E.number(), 1);
1339        assert_eq!(E.extendee(), CARRIER);
1340        let copy = E; // still Copy with the fn-pointer field
1341        assert_eq!(copy.number(), 1);
1342    }
1343
1344    #[test]
1345    fn extension_constructors_validate_field_numbers() {
1346        let valid_numbers = [
1347            1,
1348            crate::encoding::FIRST_RESERVED_FIELD_NUMBER,
1349            crate::encoding::LAST_RESERVED_FIELD_NUMBER,
1350            crate::encoding::MAX_FIELD_NUMBER,
1351            crate::encoding::MAX_FIELD_NUMBER + 1,
1352            i32::MAX as u32,
1353        ];
1354        for number in valid_numbers {
1355            assert_eq!(Extension::<Int32>::new(number, CARRIER).number(), number);
1356            assert_eq!(
1357                Extension::<Int32>::with_default(number, CARRIER, || 0).number(),
1358                number
1359            );
1360        }
1361
1362        let invalid_numbers = [0, i32::MAX as u32 + 1, u32::MAX];
1363        for number in invalid_numbers {
1364            assert!(
1365                std::panic::catch_unwind(|| Extension::<Int32>::new(number, CARRIER)).is_err(),
1366                "new accepted field number {number}"
1367            );
1368            assert!(
1369                std::panic::catch_unwind(|| {
1370                    Extension::<Int32>::with_default(number, CARRIER, || 0)
1371                })
1372                .is_err(),
1373                "with_default accepted field number {number}"
1374            );
1375        }
1376    }
1377
1378    #[test]
1379    #[should_panic(expected = "extension field number must not be 0")]
1380    fn extension_number_zero_panic_names_the_rule() {
1381        let _ = Extension::<Int32>::new(0, CARRIER);
1382    }
1383
1384    #[test]
1385    #[should_panic(expected = "extension field number must be at most i32::MAX")]
1386    fn extension_number_above_i32_max_panic_names_the_rule() {
1387        let _ = Extension::<Int32>::with_default(i32::MAX as u32 + 1, CARRIER, || 0);
1388    }
1389
1390    /// A MessageSet item is stored as a length-delimited unknown field whose
1391    /// number is the item's type ID, and a type ID can pass
1392    /// `MAX_FIELD_NUMBER`. A `const` extension with such a number compiles
1393    /// and reads the item.
1394    #[test]
1395    fn extension_number_above_max_field_number_reads_message_set_item() {
1396        const TYPE_ID: u32 = i32::MAX as u32;
1397        const E: Extension<BytesCodec> = Extension::new(TYPE_ID, CARRIER);
1398        const fn empty() -> Vec<u8> {
1399            Vec::new()
1400        }
1401        const D: Extension<BytesCodec> = Extension::with_default(TYPE_ID, CARRIER, empty);
1402        let mut c = Carrier::default();
1403        c.unknown.push(ld(TYPE_ID, vec![1, 2]));
1404        assert_eq!(c.extension(&E), Some(vec![1, 2]));
1405        assert_eq!(c.extension_or_default(&D), vec![1, 2]);
1406    }
1407
1408    // ── Extendee identity check ─────────────────────────────────────────────
1409
1410    // An extension declared for a different message. Using it on `Carrier`
1411    // is a bug in the caller — get/set/clear panic, has returns false.
1412    const WRONG: Extension<Int32> = Extension::new(1, "other.Message");
1413
1414    #[test]
1415    #[should_panic(expected = "extends `other.Message`, not `test.Carrier`")]
1416    fn extension_panics_on_extendee_mismatch() {
1417        let c = Carrier::default();
1418        let _ = c.extension(&WRONG);
1419    }
1420
1421    #[test]
1422    #[should_panic(expected = "extends `other.Message`, not `test.Carrier`")]
1423    fn set_extension_panics_on_extendee_mismatch() {
1424        let mut c = Carrier::default();
1425        c.set_extension(&WRONG, 42);
1426    }
1427
1428    #[test]
1429    #[should_panic(expected = "extends `other.Message`, not `test.Carrier`")]
1430    fn clear_extension_panics_on_extendee_mismatch() {
1431        let mut c = Carrier::default();
1432        c.clear_extension(&WRONG);
1433    }
1434
1435    #[test]
1436    #[should_panic(expected = "extends `other.Message`, not `test.Carrier`")]
1437    fn extension_or_default_panics_on_extendee_mismatch() {
1438        // Transitively via the inner extension() call.
1439        let c = Carrier::default();
1440        let _ = c.extension_or_default(&WRONG);
1441    }
1442
1443    #[test]
1444    fn has_extension_returns_false_on_extendee_mismatch() {
1445        // has_extension is graceful: matches protobuf-go's HasExtension
1446        // (extension.go:24-26) and protobuf-es's hasExtension
1447        // (extensions.ts:134), both of which return false rather than
1448        // panic/throw on mismatch.
1449        let mut c = Carrier::default();
1450        // Even with a record at the same field number.
1451        c.unknown.push(varint(1, 42));
1452        assert!(!c.has_extension(&WRONG));
1453        // Same number, matching extendee → true.
1454        const RIGHT: Extension<Int32> = Extension::new(1, CARRIER);
1455        assert!(c.has_extension(&RIGHT));
1456    }
1457
1458    // ── extension_or_default ────────────────────────────────────────────────
1459
1460    #[test]
1461    fn extension_or_default_returns_declared_default_when_absent() {
1462        const fn seven() -> i32 {
1463            7
1464        }
1465        const E: Extension<Int32> = Extension::with_default(1, CARRIER, seven);
1466        let c = Carrier::default();
1467        // extension() still returns None — presence is distinguishable.
1468        assert_eq!(c.extension(&E), None);
1469        assert!(!c.has_extension(&E));
1470        // extension_or_default() returns the declared default.
1471        assert_eq!(c.extension_or_default(&E), 7);
1472    }
1473
1474    #[test]
1475    fn extension_or_default_set_value_wins() {
1476        const fn seven() -> i32 {
1477            7
1478        }
1479        const E: Extension<Int32> = Extension::with_default(1, CARRIER, seven);
1480        let mut c = Carrier::default();
1481        c.set_extension(&E, 99);
1482        // Set value wins over the declared default.
1483        assert_eq!(c.extension_or_default(&E), 99);
1484        assert_eq!(c.extension(&E), Some(99));
1485    }
1486
1487    #[test]
1488    fn extension_or_default_falls_back_to_type_default() {
1489        // No [default] declared → type default (0 for i32).
1490        const E: Extension<Int32> = Extension::new(1, CARRIER);
1491        let c = Carrier::default();
1492        assert_eq!(c.extension_or_default(&E), 0);
1493        assert_eq!(c.extension(&E), None);
1494    }
1495
1496    #[test]
1497    fn extension_or_default_string_allocates_per_call() {
1498        // String default: non-const fn (allocates each call).
1499        fn hello() -> String {
1500            String::from("hello")
1501        }
1502        const E: Extension<StringCodec> = Extension::with_default(1, CARRIER, hello);
1503        let c = Carrier::default();
1504        assert_eq!(c.extension_or_default(&E), "hello");
1505        // Each call is a fresh allocation — the two strings are distinct.
1506        let a = c.extension_or_default(&E);
1507        let b = c.extension_or_default(&E);
1508        assert_eq!(a, b);
1509        assert_ne!(a.as_ptr(), b.as_ptr());
1510    }
1511
1512    #[test]
1513    fn extension_or_default_bytes() {
1514        fn blob() -> Vec<u8> {
1515            alloc::vec![0xDE, 0xAD]
1516        }
1517        const E: Extension<BytesCodec> = Extension::with_default(1, CARRIER, blob);
1518        let c = Carrier::default();
1519        assert_eq!(c.extension_or_default(&E), alloc::vec![0xDE, 0xAD]);
1520    }
1521
1522    #[test]
1523    fn extension_or_default_zero_is_present_not_default() {
1524        // Explicit presence: an explicitly-set 0 is returned, not the default.
1525        const fn seven() -> i32 {
1526            7
1527        }
1528        const E: Extension<Int32> = Extension::with_default(1, CARRIER, seven);
1529        let mut c = Carrier::default();
1530        c.set_extension(&E, 0);
1531        assert_eq!(c.extension_or_default(&E), 0);
1532    }
1533
1534    // ── Singular scalar: roundtrip, last-wins, wire-type mismatch ──────────
1535
1536    #[test]
1537    fn singular_scalar_roundtrip() {
1538        // One representative per wire family plus the zigzag cases.
1539        // Int32 sign-extend: -7 → `as i64 as u64` = 0xFFFF_FFFF_FFFF_FFF9.
1540        #[rustfmt::skip]
1541        let int32_cases: &[(i32, u64)] = &[
1542            (0,   0),
1543            (42,  42),
1544            (-7,  (-7_i64) as u64),
1545        ];
1546        for &(v, wire) in int32_cases {
1547            let mut c = Carrier::default();
1548            const E: Extension<Int32> = Extension::new(1, CARRIER);
1549            c.set_extension(&E, v);
1550            assert_eq!(
1551                c.unknown.iter().next().unwrap().data,
1552                UnknownFieldData::Varint(wire),
1553                "int32 {v}"
1554            );
1555            assert_eq!(c.extension(&E), Some(v), "int32 {v}");
1556        }
1557
1558        // Sint32 zigzag: -1 → 1, 1 → 2, -2 → 3.
1559        #[rustfmt::skip]
1560        let sint32_cases: &[(i32, u64)] = &[
1561            (0,  0),
1562            (-1, 1),
1563            (1,  2),
1564            (-2, 3),
1565        ];
1566        for &(v, wire) in sint32_cases {
1567            let mut c = Carrier::default();
1568            const E: Extension<Sint32> = Extension::new(1, CARRIER);
1569            c.set_extension(&E, v);
1570            assert_eq!(
1571                c.unknown.iter().next().unwrap().data,
1572                UnknownFieldData::Varint(wire),
1573                "sint32 {v}"
1574            );
1575            assert_eq!(c.extension(&E), Some(v), "sint32 {v}");
1576        }
1577
1578        // Sfixed32: bit-cast.
1579        let mut c = Carrier::default();
1580        const SF32: Extension<Sfixed32> = Extension::new(1, CARRIER);
1581        c.set_extension(&SF32, -1);
1582        assert_eq!(
1583            c.unknown.iter().next().unwrap().data,
1584            UnknownFieldData::Fixed32(u32::MAX)
1585        );
1586        assert_eq!(c.extension(&SF32), Some(-1));
1587
1588        // Bool: any nonzero varint decodes as true.
1589        const B: Extension<Bool> = Extension::new(1, CARRIER);
1590        let mut c = Carrier::default();
1591        c.unknown.push(varint(1, 7));
1592        assert_eq!(c.extension(&B), Some(true));
1593        let mut c = Carrier::default();
1594        c.set_extension(&B, true);
1595        assert_eq!(
1596            c.unknown.iter().next().unwrap().data,
1597            UnknownFieldData::Varint(1)
1598        );
1599
1600        // Float/Double: bit roundtrip.
1601        const F: Extension<Float> = Extension::new(1, CARRIER);
1602        let mut c = Carrier::default();
1603        c.set_extension(&F, 1.5_f32);
1604        assert_eq!(c.extension(&F), Some(1.5_f32));
1605        const D: Extension<Double> = Extension::new(2, CARRIER);
1606        c.set_extension(&D, -0.25_f64);
1607        assert_eq!(c.extension(&D), Some(-0.25_f64));
1608
1609        // Uint32: truncates high bits of oversized varint on decode.
1610        const U: Extension<Uint32> = Extension::new(1, CARRIER);
1611        let mut c = Carrier::default();
1612        c.unknown.push(varint(1, 0x1_0000_002A)); // top bit truncated
1613        assert_eq!(c.extension(&U), Some(0x0000_002A));
1614    }
1615
1616    #[test]
1617    fn singular_scalar_last_wins() {
1618        const E: Extension<Int32> = Extension::new(1, CARRIER);
1619        let mut c = Carrier::default();
1620        c.unknown.push(varint(1, 5));
1621        c.unknown.push(varint(1, 7));
1622        assert_eq!(c.extension(&E), Some(7));
1623    }
1624
1625    #[test]
1626    fn singular_scalar_wrong_wire_type_skipped() {
1627        const E: Extension<Int32> = Extension::new(1, CARRIER);
1628        let mut c = Carrier::default();
1629        c.unknown.push(varint(1, 5));
1630        c.unknown.push(ld(1, vec![0x00])); // wrong wire type, skipped
1631        assert_eq!(c.extension(&E), Some(5));
1632
1633        // Only wrong-type records → None.
1634        let mut c = Carrier::default();
1635        c.unknown.push(ld(1, vec![0x00]));
1636        assert_eq!(c.extension(&E), None);
1637    }
1638
1639    #[test]
1640    fn singular_absent_returns_none() {
1641        const E: Extension<Int32> = Extension::new(1, CARRIER);
1642        let c = Carrier::default();
1643        assert_eq!(c.extension(&E), None);
1644        // Other field numbers don't count.
1645        let mut c = Carrier::default();
1646        c.unknown.push(varint(2, 5));
1647        assert_eq!(c.extension(&E), None);
1648    }
1649
1650    // ── Explicit presence (#8234 invariant) ─────────────────────────────────
1651
1652    #[test]
1653    fn explicit_presence_with_zero_value() {
1654        // Extensions always have explicit presence: setting 0 makes it present.
1655        const E: Extension<Int32> = Extension::new(1, CARRIER);
1656        let mut c = Carrier::default();
1657        assert!(!c.has_extension(&E));
1658        c.set_extension(&E, 0);
1659        assert!(c.has_extension(&E));
1660        assert_eq!(c.extension(&E), Some(0));
1661    }
1662
1663    // ── set/clear/has ───────────────────────────────────────────────────────
1664
1665    #[test]
1666    fn set_clears_prior_occurrences() {
1667        const E: Extension<Int32> = Extension::new(1, CARRIER);
1668        let mut c = Carrier::default();
1669        c.set_extension(&E, 5);
1670        c.set_extension(&E, 7);
1671        // Exactly one record after second set.
1672        assert_eq!(c.unknown.iter().filter(|f| f.number == 1).count(), 1);
1673        assert_eq!(c.extension(&E), Some(7));
1674    }
1675
1676    #[test]
1677    fn set_preserves_other_fields() {
1678        const E: Extension<Int32> = Extension::new(1, CARRIER);
1679        let mut c = Carrier::default();
1680        c.unknown.push(varint(2, 99));
1681        c.set_extension(&E, 5);
1682        assert_eq!(c.unknown.len(), 2);
1683        // Field 2 survived.
1684        assert!(c.unknown.iter().any(|f| f.number == 2));
1685    }
1686
1687    #[test]
1688    fn clear_extension() {
1689        const E: Extension<Int32> = Extension::new(1, CARRIER);
1690        let mut c = Carrier::default();
1691        c.set_extension(&E, 5);
1692        c.unknown.push(varint(2, 99));
1693        c.clear_extension(&E);
1694        assert!(!c.has_extension(&E));
1695        assert_eq!(c.unknown.len(), 1); // field 2 survived
1696    }
1697
1698    // ── String / Bytes ──────────────────────────────────────────────────────
1699
1700    #[test]
1701    fn string_roundtrip() {
1702        const E: Extension<StringCodec> = Extension::new(1, CARRIER);
1703        let mut c = Carrier::default();
1704        c.set_extension(&E, "hello".to_string());
1705        assert_eq!(c.extension(&E), Some("hello".to_string()));
1706    }
1707
1708    #[test]
1709    fn string_invalid_utf8_is_none() {
1710        const E: Extension<StringCodec> = Extension::new(1, CARRIER);
1711        let mut c = Carrier::default();
1712        c.unknown.push(ld(1, vec![0xFF, 0xFE]));
1713        assert_eq!(c.extension(&E), None);
1714    }
1715
1716    #[test]
1717    fn string_invalid_last_record_is_none() {
1718        const E: Extension<StringCodec> = Extension::new(1, CARRIER);
1719        let invalid = [
1720            vec![0xFF],
1721            vec![0x80],
1722            vec![0xC0, 0xAF],
1723            vec![0xC2],
1724            vec![0xE2, 0x82],
1725            vec![0xED, 0xA0, 0x80],
1726            vec![0xF4, 0x90, 0x80, 0x80],
1727            vec![b'a', 0xFF],
1728        ];
1729        for bytes in invalid {
1730            let mut c = Carrier::default();
1731            c.unknown.push(ld(1, b"earlier".to_vec()));
1732            c.unknown.push(ld(1, bytes));
1733            assert_eq!(c.extension(&E), None, "{:?}", c.unknown);
1734        }
1735    }
1736
1737    #[test]
1738    fn string_last_record_wins_over_valid_or_invalid_prior_values() {
1739        const E: Extension<StringCodec> = Extension::new(1, CARRIER);
1740        for prior in [b"earlier".to_vec(), vec![0xFF]] {
1741            for latest in ["latest", "", "\0", "caf\u{e9} \u{1F600}"] {
1742                let mut c = Carrier::default();
1743                c.unknown.push(ld(1, prior.clone()));
1744                c.unknown.push(ld(1, latest.as_bytes().to_vec()));
1745                assert_eq!(c.extension(&E).as_deref(), Some(latest));
1746            }
1747        }
1748    }
1749
1750    #[test]
1751    fn string_last_record_ignores_other_numbers_and_wire_types() {
1752        const E: Extension<StringCodec> = Extension::new(1, CARRIER);
1753        for (latest, expected) in [
1754            (b"latest".to_vec(), Some("latest")),
1755            (Vec::new(), Some("")),
1756            (vec![0xFF], None),
1757        ] {
1758            let mut c = Carrier::default();
1759            c.unknown.push(ld(1, b"earlier".to_vec()));
1760            c.unknown.push(ld(1, latest));
1761            c.unknown.push(ld(2, b"other".to_vec()));
1762            c.unknown.push(varint(1, 42));
1763            c.unknown.push(fixed32(1, 42));
1764            c.unknown.push(fixed64(1, 42));
1765            c.unknown.push(group(1, UnknownFields::new()));
1766            assert_eq!(c.extension(&E).as_deref(), expected);
1767        }
1768    }
1769
1770    #[test]
1771    fn string_invalid_last_record_uses_declared_default() {
1772        const E: Extension<StringCodec> =
1773            Extension::with_default(1, CARRIER, || "fallback".to_string());
1774        let mut c = Carrier::default();
1775        c.unknown.push(ld(1, b"earlier".to_vec()));
1776        c.unknown.push(ld(1, vec![0xFF]));
1777        assert_eq!(c.extension_or_default(&E), "fallback");
1778    }
1779
1780    #[test]
1781    fn string_absent_or_wrong_wire_type_only_is_none() {
1782        const E: Extension<StringCodec> = Extension::new(1, CARRIER);
1783        let mut c = Carrier::default();
1784        assert_eq!(c.extension(&E), None);
1785        c.unknown.push(ld(2, b"other".to_vec()));
1786        c.unknown.push(varint(1, 42));
1787        c.unknown.push(fixed32(1, 42));
1788        c.unknown.push(fixed64(1, 42));
1789        assert_eq!(c.extension(&E), None);
1790    }
1791
1792    #[test]
1793    fn bytes_roundtrip() {
1794        const E: Extension<BytesCodec> = Extension::new(1, CARRIER);
1795        let mut c = Carrier::default();
1796        c.set_extension(&E, vec![0xDE, 0xAD, 0xBE, 0xEF]);
1797        assert_eq!(c.extension(&E), Some(vec![0xDE, 0xAD, 0xBE, 0xEF]));
1798    }
1799
1800    // ── Repeated scalar ─────────────────────────────────────────────────────
1801
1802    #[test]
1803    fn repeated_scalar_unpacked() {
1804        const E: Extension<Repeated<Int32>> = Extension::new(1, CARRIER);
1805        let mut c = Carrier::default();
1806        c.unknown.push(varint(1, 1));
1807        c.unknown.push(varint(1, 2));
1808        c.unknown.push(varint(1, 3));
1809        assert_eq!(c.extension(&E), vec![1, 2, 3]);
1810    }
1811
1812    #[test]
1813    fn repeated_scalar_packed() {
1814        // Packed varint payload for [1, 2, 300]: 0x01 0x02 0xAC 0x02
1815        const E: Extension<Repeated<Int32>> = Extension::new(1, CARRIER);
1816        let mut c = Carrier::default();
1817        c.unknown.push(ld(1, vec![0x01, 0x02, 0xAC, 0x02]));
1818        assert_eq!(c.extension(&E), vec![1, 2, 300]);
1819    }
1820
1821    #[test]
1822    fn repeated_scalar_mixed_packed_unpacked() {
1823        const E: Extension<Repeated<Int32>> = Extension::new(1, CARRIER);
1824        let mut c = Carrier::default();
1825        c.unknown.push(varint(1, 1));
1826        c.unknown.push(ld(1, vec![0x02, 0x03])); // packed [2, 3]
1827        c.unknown.push(varint(1, 4));
1828        assert_eq!(c.extension(&E), vec![1, 2, 3, 4]);
1829    }
1830
1831    #[test]
1832    fn repeated_scalar_fixed32_packed() {
1833        // Packed fixed32 payload for [1, 2]: 01 00 00 00 02 00 00 00
1834        const E: Extension<Repeated<Fixed32>> = Extension::new(1, CARRIER);
1835        let mut c = Carrier::default();
1836        c.unknown.push(ld(1, vec![1, 0, 0, 0, 2, 0, 0, 0]));
1837        assert_eq!(c.extension(&E), vec![1_u32, 2_u32]);
1838    }
1839
1840    #[test]
1841    fn repeated_scalar_wrong_wire_type_skipped() {
1842        const E: Extension<Repeated<Int32>> = Extension::new(1, CARRIER);
1843        let mut c = Carrier::default();
1844        c.unknown.push(varint(1, 1));
1845        c.unknown.push(fixed32(1, 0xDEAD)); // wrong, skipped
1846        c.unknown.push(varint(1, 2));
1847        assert_eq!(c.extension(&E), vec![1, 2]);
1848    }
1849
1850    #[test]
1851    fn repeated_scalar_set_roundtrip() {
1852        const E: Extension<Repeated<Sint32>> = Extension::new(1, CARRIER);
1853        let mut c = Carrier::default();
1854        c.set_extension(&E, vec![-1, 0, 1, -100]);
1855        assert_eq!(c.extension(&E), vec![-1, 0, 1, -100]);
1856        // One record per element.
1857        assert_eq!(c.unknown.len(), 4);
1858    }
1859
1860    #[test]
1861    fn repeated_string() {
1862        const E: Extension<Repeated<StringCodec>> = Extension::new(1, CARRIER);
1863        let mut c = Carrier::default();
1864        c.set_extension(&E, vec!["a".to_string(), "b".to_string()]);
1865        assert_eq!(c.extension(&E), vec!["a".to_string(), "b".to_string()]);
1866    }
1867
1868    #[test]
1869    fn repeated_string_malformed_element_skipped() {
1870        const E: Extension<Repeated<StringCodec>> = Extension::new(1, CARRIER);
1871        let mut c = Carrier::default();
1872        c.unknown.push(ld(1, b"ok".to_vec()));
1873        c.unknown.push(ld(1, vec![0xFF])); // invalid UTF-8, skipped
1874        c.unknown.push(ld(1, b"also ok".to_vec()));
1875        // StringCodec::decode_packed is a no-op, so the malformed element
1876        // contributes nothing.
1877        assert_eq!(
1878            c.extension(&E),
1879            vec!["ok".to_string(), "also ok".to_string()]
1880        );
1881    }
1882
1883    #[test]
1884    fn repeated_empty_set_not_present() {
1885        const E: Extension<Repeated<Int32>> = Extension::new(1, CARRIER);
1886        let mut c = Carrier::default();
1887        c.set_extension(&E, vec![]);
1888        assert!(!c.has_extension(&E));
1889        assert_eq!(c.extension(&E), Vec::<i32>::new());
1890    }
1891
1892    #[test]
1893    fn packed_repeated_set_twice_one_record() {
1894        const E: Extension<PackedRepeated<Int32>> = Extension::new(1, CARRIER);
1895        let mut c = Carrier::default();
1896        c.set_extension(&E, vec![1, 2]);
1897        c.set_extension(&E, vec![3, 4, 5]);
1898        assert_eq!(c.unknown.len(), 1);
1899        assert_eq!(c.extension(&E), vec![3, 4, 5]);
1900    }
1901
1902    // ── PackedRepeated ──────────────────────────────────────────────────────
1903
1904    #[test]
1905    fn packed_repeated_encode_one_record() {
1906        const E: Extension<PackedRepeated<Int32>> = Extension::new(1, CARRIER);
1907        let mut c = Carrier::default();
1908        c.set_extension(&E, vec![1, 2, 300]);
1909        // Exactly one record.
1910        assert_eq!(c.unknown.len(), 1);
1911        assert_eq!(
1912            c.unknown.iter().next().unwrap().data,
1913            UnknownFieldData::LengthDelimited(vec![0x01, 0x02, 0xAC, 0x02])
1914        );
1915        // And it roundtrips.
1916        assert_eq!(c.extension(&E), vec![1, 2, 300]);
1917    }
1918
1919    #[test]
1920    fn packed_repeated_decode_accepts_unpacked() {
1921        // PackedRepeated decode is identical to Repeated decode — accepts both.
1922        const E: Extension<PackedRepeated<Int32>> = Extension::new(1, CARRIER);
1923        let mut c = Carrier::default();
1924        c.unknown.push(varint(1, 1));
1925        c.unknown.push(varint(1, 2));
1926        assert_eq!(c.extension(&E), vec![1, 2]);
1927    }
1928
1929    #[test]
1930    fn packed_repeated_empty_not_present() {
1931        const E: Extension<PackedRepeated<Int32>> = Extension::new(1, CARRIER);
1932        let mut c = Carrier::default();
1933        c.set_extension(&E, vec![]);
1934        assert!(!c.has_extension(&E));
1935    }
1936
1937    #[test]
1938    fn packed_repeated_fixed64_roundtrip() {
1939        const E: Extension<PackedRepeated<Sfixed64>> = Extension::new(1, CARRIER);
1940        let mut c = Carrier::default();
1941        c.set_extension(&E, vec![-1_i64, 0, i64::MAX]);
1942        assert_eq!(c.unknown.len(), 1);
1943        assert_eq!(c.extension(&E), vec![-1_i64, 0, i64::MAX]);
1944    }
1945
1946    // ── MessageCodec ────────────────────────────────────────────────────────
1947
1948    // Minimal test message: two i32 fields (numbers 1 and 2). Unknown fields
1949    // are skipped, not preserved — see `BudgetMsg` below for a double that
1950    // preserves them and charges the decode budget for doing so.
1951    // Hand-written to avoid a codegen dependency in the runtime crate's tests.
1952    #[derive(Clone, Default, PartialEq, Debug)]
1953    struct TestMsg {
1954        a: i32,
1955        b: i32,
1956        unknown: UnknownFields,
1957    }
1958
1959    impl crate::DefaultInstance for TestMsg {
1960        fn default_instance() -> &'static Self {
1961            static INST: crate::__private::OnceBox<TestMsg> = crate::__private::OnceBox::new();
1962            INST.get_or_init(|| alloc::boxed::Box::new(TestMsg::default()))
1963        }
1964    }
1965
1966    impl crate::Message for TestMsg {
1967        fn compute_size(&self, _cache: &mut crate::SizeCache) -> u32 {
1968            let mut n = 0;
1969            if self.a != 0 {
1970                n += 1 + crate::encoding::varint_len(self.a as i64 as u64);
1971            }
1972            if self.b != 0 {
1973                n += 1 + crate::encoding::varint_len(self.b as i64 as u64);
1974            }
1975            n += self.unknown.encoded_len();
1976            n as u32
1977        }
1978        fn write_to(&self, _cache: &mut crate::SizeCache, buf: &mut impl crate::EncodeSink) {
1979            use crate::encoding::encode_varint;
1980            if self.a != 0 {
1981                encode_varint(1 << 3, buf);
1982                encode_varint(self.a as i64 as u64, buf);
1983            }
1984            if self.b != 0 {
1985                encode_varint(2 << 3, buf);
1986                encode_varint(self.b as i64 as u64, buf);
1987            }
1988            self.unknown.write_to(buf);
1989        }
1990        fn merge_field(
1991            &mut self,
1992            tag: crate::encoding::Tag,
1993            buf: &mut impl bytes::Buf,
1994            _ctx: crate::DecodeContext<'_>,
1995        ) -> Result<(), crate::DecodeError> {
1996            match tag.field_number() {
1997                1 => self.a = crate::types::decode_int32(buf)?,
1998                2 => self.b = crate::types::decode_int32(buf)?,
1999                _ => crate::encoding::skip_field(tag, buf)?,
2000            }
2001            Ok(())
2002        }
2003        fn clear(&mut self) {
2004            *self = Self::default();
2005        }
2006    }
2007
2008    #[test]
2009    fn message_single_record() {
2010        const E: Extension<MessageCodec<TestMsg>> = Extension::new(1, CARRIER);
2011        let mut c = Carrier::default();
2012        // Wire for TestMsg{a:5, b:0}: tag(1,varint)=0x08, value=0x05.
2013        c.unknown.push(ld(1, vec![0x08, 0x05]));
2014        let got = c.extension(&E).expect("decoded");
2015        assert_eq!(got.a, 5);
2016        assert_eq!(got.b, 0);
2017    }
2018
2019    #[test]
2020    fn message_split_records_merge() {
2021        // Proto spec: multiple records at the same field number merge.
2022        // Record 1 sets a=5, record 2 sets b=7 — result has both.
2023        const E: Extension<MessageCodec<TestMsg>> = Extension::new(1, CARRIER);
2024        let mut c = Carrier::default();
2025        c.unknown.push(ld(1, vec![0x08, 0x05])); // a=5
2026        c.unknown.push(ld(1, vec![0x10, 0x07])); // b=7
2027        let got = c.extension(&E).expect("decoded");
2028        assert_eq!(got.a, 5);
2029        assert_eq!(got.b, 7);
2030    }
2031
2032    #[test]
2033    fn message_absent_is_none() {
2034        const E: Extension<MessageCodec<TestMsg>> = Extension::new(1, CARRIER);
2035        let c = Carrier::default();
2036        assert!(c.extension(&E).is_none());
2037    }
2038
2039    #[test]
2040    fn message_malformed_is_none() {
2041        const E: Extension<MessageCodec<TestMsg>> = Extension::new(1, CARRIER);
2042        let mut c = Carrier::default();
2043        // Truncated varint: high bit set, no continuation.
2044        c.unknown.push(ld(1, vec![0x08, 0x80]));
2045        assert!(c.extension(&E).is_none());
2046    }
2047
2048    #[test]
2049    fn message_set_get_roundtrip() {
2050        const E: Extension<MessageCodec<TestMsg>> = Extension::new(1, CARRIER);
2051        let mut c = Carrier::default();
2052        c.set_extension(
2053            &E,
2054            TestMsg {
2055                a: 3,
2056                b: -1,
2057                unknown: UnknownFields::new(),
2058            },
2059        );
2060        let got = c.extension(&E).expect("decoded");
2061        assert_eq!(got.a, 3);
2062        assert_eq!(got.b, -1);
2063    }
2064
2065    // ── Budgets are shared across an extension's records ────────────────
2066
2067    /// A message that preserves unknown fields *through the decode context*,
2068    /// the way generated code does — so a budget can actually be exhausted.
2069    /// (`TestMsg` above skips them, so it never spends anything.)
2070    #[derive(Debug, Default, Clone, PartialEq)]
2071    struct BudgetMsg {
2072        unknown: UnknownFields,
2073    }
2074
2075    impl crate::DefaultInstance for BudgetMsg {
2076        fn default_instance() -> &'static Self {
2077            static INST: crate::__private::OnceBox<BudgetMsg> = crate::__private::OnceBox::new();
2078            INST.get_or_init(|| alloc::boxed::Box::new(BudgetMsg::default()))
2079        }
2080    }
2081
2082    impl crate::Message for BudgetMsg {
2083        fn compute_size(&self, _cache: &mut crate::SizeCache) -> u32 {
2084            self.unknown.encoded_len() as u32
2085        }
2086        fn write_to(&self, _cache: &mut crate::SizeCache, buf: &mut impl crate::EncodeSink) {
2087            self.unknown.write_to(buf);
2088        }
2089        fn merge_field(
2090            &mut self,
2091            tag: crate::encoding::Tag,
2092            buf: &mut impl bytes::Buf,
2093            ctx: crate::DecodeContext<'_>,
2094        ) -> Result<(), crate::DecodeError> {
2095            self.unknown
2096                .push(crate::encoding::decode_unknown_field(tag, buf, ctx)?);
2097            Ok(())
2098        }
2099        fn clear(&mut self) {
2100            *self = Self::default();
2101        }
2102    }
2103
2104    /// Wire bytes for a message carrying `n` unknown varint fields at field
2105    /// 9 (two bytes each: tag, value).
2106    fn unknowns_payload(n: usize) -> Vec<u8> {
2107        let mut v = Vec::with_capacity(n * 2);
2108        for _ in 0..n {
2109            v.push(9 << 3); // field 9, varint
2110            v.push(0x00);
2111        }
2112        v
2113    }
2114
2115    /// An extension's records share one decode budget rather than each
2116    /// getting a full one.
2117    ///
2118    /// The carrier's own decode sees only opaque records and charges one
2119    /// slot each, so an unshared budget here is invisible from outside.
2120    #[test]
2121    fn message_extension_records_share_one_budget() {
2122        const E: Extension<MessageCodec<BudgetMsg>> = Extension::new(1, CARRIER);
2123
2124        // Two records, each comfortably inside the per-record allowance but
2125        // together past it.
2126        let per_record = 2 * crate::DEFAULT_UNKNOWN_FIELD_LIMIT / 3;
2127        let mut c = Carrier::default();
2128        c.unknown.push(ld(1, unknowns_payload(per_record)));
2129        c.unknown.push(ld(1, unknowns_payload(per_record)));
2130
2131        assert!(
2132            c.extension(&E).is_none(),
2133            "two records totalling {} unknown fields must exhaust the shared \
2134             {} allowance",
2135            2 * per_record,
2136            crate::DEFAULT_UNKNOWN_FIELD_LIMIT
2137        );
2138
2139        // One record of the same size is still fine — a ceiling, not a wall.
2140        let mut ok = Carrier::default();
2141        ok.unknown.push(ld(1, unknowns_payload(per_record)));
2142        assert!(ok.extension(&E).is_some());
2143    }
2144
2145    /// The repeated form retains every element simultaneously, so it shares
2146    /// a budget for the same reason.
2147    #[test]
2148    fn repeated_message_extension_elements_share_one_budget() {
2149        const E: Extension<Repeated<MessageCodec<BudgetMsg>>> = Extension::new(1, CARRIER);
2150
2151        let per_record = 2 * crate::DEFAULT_UNKNOWN_FIELD_LIMIT / 3;
2152        let mut c = Carrier::default();
2153        c.unknown.push(ld(1, unknowns_payload(per_record)));
2154        c.unknown.push(ld(1, unknowns_payload(per_record)));
2155
2156        // `decode_one_ctx` returns `None` for the over-budget record, and
2157        // the repeated path drops it rather than aborting, so the observable
2158        // effect is a short list rather than an error.
2159        assert_eq!(
2160            c.extension(&E).len(),
2161            1,
2162            "the second element must not get a fresh allowance"
2163        );
2164    }
2165
2166    #[test]
2167    fn repeated_message_extension_charges_each_output_message() {
2168        let mut fields = UnknownFields::new();
2169        for _ in 0..3 {
2170            fields.push(ld(1, Vec::new()));
2171        }
2172        let unknown_limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
2173        let element_limit = core::cell::Cell::new(2 * core::mem::size_of::<TestMsg>());
2174        let ctx = crate::DecodeContext::new(crate::RECURSION_LIMIT, &unknown_limit)
2175            .with_element_memory(&element_limit);
2176
2177        let decoded = decode_repeated_with_context::<MessageCodec<TestMsg>>(1, &fields, ctx);
2178
2179        assert_eq!(decoded.len(), 2);
2180        assert_eq!(element_limit.get(), 0);
2181    }
2182
2183    #[test]
2184    fn repeated_group_extension_charges_each_output_message() {
2185        let mut fields = UnknownFields::new();
2186        for _ in 0..3 {
2187            fields.push(group(1, UnknownFields::new()));
2188        }
2189        let unknown_limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
2190        let element_limit = core::cell::Cell::new(2 * core::mem::size_of::<TestMsg>());
2191        let ctx = crate::DecodeContext::new(crate::RECURSION_LIMIT, &unknown_limit)
2192            .with_element_memory(&element_limit);
2193
2194        let decoded = decode_repeated_with_context::<GroupCodec<TestMsg>>(1, &fields, ctx);
2195
2196        assert_eq!(decoded.len(), 2);
2197        assert_eq!(element_limit.get(), 0);
2198    }
2199
2200    /// A malformed element is skipped and its `size_of` charge stays spent.
2201    #[test]
2202    fn repeated_message_extension_keeps_the_charge_of_a_malformed_element() {
2203        let mut fields = UnknownFields::new();
2204        fields.push(ld(1, vec![0x08, 0x80])); // truncated varint
2205        fields.push(ld(1, vec![0x08, 0x03])); // valid message
2206        let unknown_limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
2207        let element_limit = core::cell::Cell::new(2 * core::mem::size_of::<TestMsg>());
2208        let ctx = crate::DecodeContext::new(crate::RECURSION_LIMIT, &unknown_limit)
2209            .with_element_memory(&element_limit);
2210
2211        let decoded = decode_repeated_with_context::<MessageCodec<TestMsg>>(1, &fields, ctx);
2212
2213        assert_eq!(decoded.len(), 1);
2214        assert_eq!(decoded[0].a, 3);
2215        assert_eq!(element_limit.get(), 0);
2216    }
2217
2218    #[test]
2219    fn repeated_group_extension_keeps_the_charge_of_a_malformed_element() {
2220        let mut malformed = UnknownFields::new();
2221        malformed.push(varint(0, 1)); // field number zero is invalid
2222        let mut fields = UnknownFields::new();
2223        fields.push(group(1, malformed));
2224        fields.push(group(1, inner_a(3)));
2225        let unknown_limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
2226        let element_limit = core::cell::Cell::new(2 * core::mem::size_of::<TestMsg>());
2227        let ctx = crate::DecodeContext::new(crate::RECURSION_LIMIT, &unknown_limit)
2228            .with_element_memory(&element_limit);
2229
2230        let decoded = decode_repeated_with_context::<GroupCodec<TestMsg>>(1, &fields, ctx);
2231
2232        assert_eq!(decoded.len(), 1);
2233        assert_eq!(decoded[0].a, 3);
2234        assert_eq!(element_limit.get(), 0);
2235    }
2236
2237    /// A message that charges the element-memory budget from inside its own
2238    /// decode, as a generated message with a repeated field does: each
2239    /// varint at field 1 costs `ITEM_CHARGE`.
2240    #[derive(Debug, Default, Clone, PartialEq)]
2241    struct ListMsg {
2242        items: Vec<u64>,
2243    }
2244
2245    impl ListMsg {
2246        const ITEM_CHARGE: usize = 64;
2247    }
2248
2249    impl crate::DefaultInstance for ListMsg {
2250        fn default_instance() -> &'static Self {
2251            static INST: crate::__private::OnceBox<ListMsg> = crate::__private::OnceBox::new();
2252            INST.get_or_init(|| alloc::boxed::Box::new(ListMsg::default()))
2253        }
2254    }
2255
2256    impl crate::Message for ListMsg {
2257        fn compute_size(&self, _cache: &mut crate::SizeCache) -> u32 {
2258            0
2259        }
2260        fn write_to(&self, _cache: &mut crate::SizeCache, _buf: &mut impl crate::EncodeSink) {}
2261        fn merge_field(
2262            &mut self,
2263            tag: crate::encoding::Tag,
2264            buf: &mut impl bytes::Buf,
2265            ctx: crate::DecodeContext<'_>,
2266        ) -> Result<(), crate::DecodeError> {
2267            if tag.field_number() == 1 {
2268                ctx.register_element_memory(Self::ITEM_CHARGE)?;
2269                self.items.push(crate::encoding::decode_varint(buf)?);
2270                Ok(())
2271            } else {
2272                crate::encoding::skip_field(tag, buf)
2273            }
2274        }
2275        fn clear(&mut self) {
2276            self.items.clear();
2277        }
2278    }
2279
2280    /// The loop stops at an element that exhausts the element-memory budget
2281    /// from inside its own decode. The budget that element could not use
2282    /// would hold the smaller element after it, which is not returned: the
2283    /// result is the elements before the stop.
2284    #[test]
2285    fn repeated_message_extension_stops_at_an_element_that_exhausts_the_budget() {
2286        let element = core::mem::size_of::<ListMsg>();
2287        // What is left for the second element's item is less than the item
2288        // costs, and enough for the third element.
2289        assert!(element + ListMsg::ITEM_CHARGE / 2 < ListMsg::ITEM_CHARGE);
2290        let mut fields = UnknownFields::new();
2291        fields.push(ld(1, Vec::new()));
2292        fields.push(ld(1, vec![0x08, 0x01])); // one item, which does not fit
2293        fields.push(ld(1, Vec::new()));
2294        let unknown_limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
2295        let element_limit = core::cell::Cell::new(3 * element + ListMsg::ITEM_CHARGE / 2);
2296        let ctx = crate::DecodeContext::new(crate::RECURSION_LIMIT, &unknown_limit)
2297            .with_element_memory(&element_limit);
2298
2299        let decoded = decode_repeated_with_context::<MessageCodec<ListMsg>>(1, &fields, ctx);
2300
2301        assert_eq!(decoded, [ListMsg::default()]);
2302        assert_eq!(element_limit.get(), 0);
2303    }
2304
2305    /// A zero-sized message whose decode charges the element-memory budget:
2306    /// each varint at field 1 costs `ITEM_CHARGE`. Its `size_of` charge is 0,
2307    /// so it always fits a spent budget.
2308    #[derive(Debug, Default, Clone, PartialEq)]
2309    struct ZeroSizedMsg;
2310
2311    impl ZeroSizedMsg {
2312        const ITEM_CHARGE: usize = 64;
2313    }
2314
2315    impl crate::DefaultInstance for ZeroSizedMsg {
2316        fn default_instance() -> &'static Self {
2317            &Self
2318        }
2319    }
2320
2321    impl crate::Message for ZeroSizedMsg {
2322        fn compute_size(&self, _cache: &mut crate::SizeCache) -> u32 {
2323            0
2324        }
2325        fn write_to(&self, _cache: &mut crate::SizeCache, _buf: &mut impl crate::EncodeSink) {}
2326        fn merge_field(
2327            &mut self,
2328            tag: crate::encoding::Tag,
2329            buf: &mut impl bytes::Buf,
2330            ctx: crate::DecodeContext<'_>,
2331        ) -> Result<(), crate::DecodeError> {
2332            if tag.field_number() == 1 {
2333                ctx.register_element_memory(Self::ITEM_CHARGE)?;
2334            }
2335            crate::encoding::skip_field(tag, buf)
2336        }
2337        fn clear(&mut self) {}
2338    }
2339
2340    /// The loop itself stops once the budget is spent. An element of a
2341    /// zero-sized type would still fit a budget of 0, so it is the stop, not
2342    /// a failed charge, that keeps the record after the over-budget one out
2343    /// of the result.
2344    #[test]
2345    fn repeated_message_extension_reads_no_record_after_the_budget_is_spent() {
2346        let mut fields = UnknownFields::new();
2347        fields.push(ld(1, vec![0x08, 0x01])); // one item, which does not fit
2348        fields.push(ld(1, Vec::new()));
2349        let unknown_limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
2350        let element_limit = core::cell::Cell::new(ZeroSizedMsg::ITEM_CHARGE / 2);
2351        let ctx = crate::DecodeContext::new(crate::RECURSION_LIMIT, &unknown_limit)
2352            .with_element_memory(&element_limit);
2353
2354        let decoded = decode_repeated_with_context::<MessageCodec<ZeroSizedMsg>>(1, &fields, ctx);
2355
2356        assert_eq!(decoded, []);
2357        assert_eq!(element_limit.get(), 0);
2358    }
2359
2360    /// The way `decode_one_ctx` tells an override outside this crate to end
2361    /// the list: charging exactly what remains leaves the budget at 0.
2362    #[test]
2363    fn charging_the_remaining_element_memory_spends_the_budget() {
2364        let unknown_limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
2365        let element_limit = core::cell::Cell::new(40);
2366        let ctx = crate::DecodeContext::new(crate::RECURSION_LIMIT, &unknown_limit)
2367            .with_element_memory(&element_limit);
2368
2369        let rest = ctx.remaining_element_memory().unwrap();
2370        ctx.register_element_memory(rest).unwrap();
2371
2372        assert_eq!(ctx.remaining_element_memory(), Some(0));
2373    }
2374
2375    /// A malformed element does not stop the loop while the budget has room:
2376    /// it is skipped and the next record is read.
2377    #[test]
2378    fn repeated_message_extension_skips_malformed_elements_before_the_budget_is_spent() {
2379        let mut fields = UnknownFields::new();
2380        fields.push(ld(1, vec![0x08, 0x80])); // truncated varint
2381        fields.push(varint(1, 7)); // wrong wire type
2382        fields.push(ld(1, vec![0x08, 0x03]));
2383        let unknown_limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
2384        let element_limit = core::cell::Cell::new(4 * core::mem::size_of::<TestMsg>());
2385        let ctx = crate::DecodeContext::new(crate::RECURSION_LIMIT, &unknown_limit)
2386            .with_element_memory(&element_limit);
2387
2388        let decoded = decode_repeated_with_context::<MessageCodec<TestMsg>>(1, &fields, ctx);
2389
2390        assert_eq!(decoded.len(), 1);
2391        assert_eq!(decoded[0].a, 3);
2392    }
2393
2394    /// A message with a large inline footprint, so that a few hundred
2395    /// elements reach the default element-memory budget.
2396    #[derive(Clone, PartialEq)]
2397    struct WideMsg {
2398        pad: [u8; 64 * 1024],
2399    }
2400
2401    impl Default for WideMsg {
2402        fn default() -> Self {
2403            Self {
2404                pad: [0; 64 * 1024],
2405            }
2406        }
2407    }
2408
2409    impl crate::DefaultInstance for WideMsg {
2410        fn default_instance() -> &'static Self {
2411            static INST: crate::__private::OnceBox<WideMsg> = crate::__private::OnceBox::new();
2412            INST.get_or_init(|| alloc::boxed::Box::new(WideMsg::default()))
2413        }
2414    }
2415
2416    impl crate::Message for WideMsg {
2417        fn compute_size(&self, _cache: &mut crate::SizeCache) -> u32 {
2418            0
2419        }
2420        fn write_to(&self, _cache: &mut crate::SizeCache, _buf: &mut impl crate::EncodeSink) {}
2421        fn merge_field(
2422            &mut self,
2423            tag: crate::encoding::Tag,
2424            buf: &mut impl bytes::Buf,
2425            _ctx: crate::DecodeContext<'_>,
2426        ) -> Result<(), crate::DecodeError> {
2427            crate::encoding::skip_field(tag, buf)
2428        }
2429        fn clear(&mut self) {
2430            self.pad.fill(0);
2431        }
2432    }
2433
2434    /// `extension()` has no error channel, so a repeated message or group
2435    /// extension that outgrows the default budget comes back holding the
2436    /// elements that fit.
2437    #[test]
2438    fn extension_getter_stops_repeated_messages_at_default_budget() {
2439        const MESSAGES: Extension<Repeated<MessageCodec<WideMsg>>> = Extension::new(1, CARRIER);
2440        const GROUPS: Extension<Repeated<GroupCodec<WideMsg>>> = Extension::new(2, CARRIER);
2441        let fit = crate::DEFAULT_ELEMENT_MEMORY_LIMIT / core::mem::size_of::<WideMsg>();
2442        let mut c = Carrier::default();
2443        for _ in 0..fit + 3 {
2444            c.unknown.push(ld(1, Vec::new()));
2445            c.unknown.push(group(2, UnknownFields::new()));
2446        }
2447
2448        assert_eq!(c.extension(&MESSAGES).len(), fit);
2449        assert_eq!(c.extension(&GROUPS).len(), fit);
2450    }
2451
2452    /// Group-valued extensions share a budget for the same reason, in both
2453    /// the singular and repeated forms.
2454    ///
2455    /// Codegen emits `Repeated<GroupCodec<M>>` for a proto2 `repeated group`
2456    /// extension, so this is a real shape, not a hypothetical one — and it
2457    /// takes its own `decode_one_ctx` override to reach, because the
2458    /// defaulted one forwards to the budget-minting `decode_one`.
2459    #[test]
2460    fn group_extension_records_share_one_budget() {
2461        const SINGULAR: Extension<GroupCodec<BudgetMsg>> = Extension::new(1, CARRIER);
2462        const REPEATED: Extension<Repeated<GroupCodec<BudgetMsg>>> = Extension::new(1, CARRIER);
2463
2464        // A group record holds its payload as nested unknown fields rather
2465        // than raw bytes, so build it from `UnknownFields` directly.
2466        let per_record = 2 * crate::DEFAULT_UNKNOWN_FIELD_LIMIT / 3;
2467        let record = || {
2468            let mut inner = UnknownFields::new();
2469            for _ in 0..per_record {
2470                inner.push(varint(9, 0));
2471            }
2472            group(1, inner)
2473        };
2474
2475        let mut c = Carrier::default();
2476        c.unknown.push(record());
2477        c.unknown.push(record());
2478
2479        assert!(
2480            c.extension(&SINGULAR).is_none(),
2481            "two group records must share one allowance"
2482        );
2483        assert_eq!(
2484            c.extension(&REPEATED).len(),
2485            1,
2486            "the repeated group form must share it too"
2487        );
2488    }
2489
2490    // ── Over-limit message values (2 GiB encode guard) ──────────────────
2491
2492    use crate::test_doubles::SizedMsg;
2493
2494    fn huge_msg() -> SizedMsg {
2495        SizedMsg {
2496            reported_size: crate::MAX_MESSAGE_BYTES + 1,
2497        }
2498    }
2499
2500    #[test]
2501    fn try_set_extension_over_limit_errs_and_leaves_priors() {
2502        const E: Extension<MessageCodec<SizedMsg>> = Extension::new(1, CARRIER);
2503        let mut c = Carrier::default();
2504        c.unknown.push(ld(1, vec![0x08, 0x05])); // prior record at the number
2505        c.unknown.push(varint(7, 9)); // unrelated record
2506        assert_eq!(
2507            c.try_set_extension(&E, huge_msg()),
2508            Err(EncodeError::MessageTooLarge)
2509        );
2510        // On Err the extendee is untouched: the prior record at the
2511        // extension's number is retained, not cleared.
2512        assert_eq!(c.unknown.iter().count(), 2);
2513        assert!(c.unknown.iter().any(|f| f.number == 1));
2514    }
2515
2516    #[test]
2517    fn try_set_extension_scalar_replaces_priors() {
2518        const E: Extension<Int32> = Extension::new(3, CARRIER);
2519        let mut c = Carrier::default();
2520        c.unknown.push(varint(3, 1));
2521        c.unknown.push(varint(3, 2));
2522        c.try_set_extension(&E, 42).expect("scalars cannot fail");
2523        assert_eq!(c.extension(&E), Some(42));
2524        assert_eq!(c.unknown.iter().filter(|f| f.number == 3).count(), 1);
2525    }
2526
2527    #[test]
2528    #[should_panic(expected = "2 GiB protobuf limit")]
2529    fn set_extension_over_limit_panics() {
2530        const E: Extension<MessageCodec<SizedMsg>> = Extension::new(1, CARRIER);
2531        let mut c = Carrier::default();
2532        c.set_extension(&E, huge_msg());
2533    }
2534
2535    #[test]
2536    fn try_set_extension_repeated_message_over_limit_errs() {
2537        const E: Extension<Repeated<MessageCodec<SizedMsg>>> = Extension::new(2, CARRIER);
2538        let mut c = Carrier::default();
2539        assert_eq!(
2540            c.try_set_extension(&E, vec![huge_msg()]),
2541            Err(EncodeError::MessageTooLarge)
2542        );
2543        assert_eq!(c.unknown.iter().count(), 0);
2544    }
2545
2546    #[test]
2547    fn message_unknown_fields_survive_roundtrip() {
2548        // The extension message's *own* unknown fields survive get→set→get.
2549        const E: Extension<MessageCodec<TestMsg>> = Extension::new(1, CARRIER);
2550        let mut c = Carrier::default();
2551        // Wire for TestMsg with a=5 AND an unknown field 99 (tag=99<<3|0=0x318, varint 42).
2552        // 0x318 = 792 → varint: 0x98 0x06. Value 42 → 0x2A.
2553        c.unknown.push(ld(1, vec![0x08, 0x05, 0x98, 0x06, 0x2A]));
2554        let got = c.extension(&E).expect("decoded");
2555        assert_eq!(got.a, 5);
2556        // The unknown field was preserved inside TestMsg — actually wait,
2557        // our TestMsg::merge_field skips unknowns rather than storing them.
2558        // Redo this test with set→get instead.
2559        let mut inner_unk = UnknownFields::new();
2560        inner_unk.push(varint(99, 42));
2561        let msg = TestMsg {
2562            a: 5,
2563            b: 0,
2564            unknown: inner_unk,
2565        };
2566        let mut c = Carrier::default();
2567        c.set_extension(&E, msg);
2568        // Re-encode to bytes and decode — the unknown bytes are in the payload.
2569        use crate::Message;
2570        let mut roundtrip = TestMsg::default();
2571        if let UnknownFieldData::LengthDelimited(bytes) = &c.unknown.iter().next().unwrap().data {
2572            // Our TestMsg doesn't actually preserve unknowns on decode, so
2573            // verify the *wire* contains them instead.
2574            assert!(bytes.len() > 2, "payload includes unknown-field bytes");
2575            // Find the tag for field 99 in the encoded bytes.
2576            assert!(bytes.windows(3).any(|w| w == [0x98, 0x06, 0x2A]));
2577            // And decode of field 1 still works.
2578            roundtrip.merge_from_slice(bytes).unwrap();
2579            assert_eq!(roundtrip.a, 5);
2580        } else {
2581            panic!("expected LengthDelimited");
2582        }
2583    }
2584
2585    #[test]
2586    fn repeated_message() {
2587        const E: Extension<Repeated<MessageCodec<TestMsg>>> = Extension::new(1, CARRIER);
2588        let mut c = Carrier::default();
2589        c.unknown.push(ld(1, vec![0x08, 0x01])); // a=1
2590        c.unknown.push(ld(1, vec![0x08, 0x02])); // a=2
2591        let got = c.extension(&E);
2592        assert_eq!(got.len(), 2);
2593        assert_eq!(got[0].a, 1);
2594        assert_eq!(got[1].a, 2);
2595    }
2596
2597    #[test]
2598    fn repeated_message_malformed_element_skipped() {
2599        const E: Extension<Repeated<MessageCodec<TestMsg>>> = Extension::new(1, CARRIER);
2600        let mut c = Carrier::default();
2601        c.unknown.push(ld(1, vec![0x08, 0x01])); // a=1, ok
2602        c.unknown.push(ld(1, vec![0x08, 0x80])); // truncated, skipped
2603        c.unknown.push(ld(1, vec![0x08, 0x03])); // a=3, ok
2604        let got = c.extension(&E);
2605        assert_eq!(got.len(), 2);
2606        assert_eq!(got[0].a, 1);
2607        assert_eq!(got[1].a, 3);
2608    }
2609
2610    // ── GroupCodec ──────────────────────────────────────────────────────────
2611
2612    // Group-encoded message extensions (proto2 `group` syntax, editions
2613    // DELIMITED). Wire data is UnknownFieldData::Group(inner) instead of
2614    // LengthDelimited(bytes); inner is an already-parsed UnknownFields tree.
2615
2616    /// Build an `UnknownFields` containing field-1-varint-v — matches
2617    /// `TestMsg{a: v as i32}` when re-serialized and merged.
2618    fn inner_a(v: u64) -> UnknownFields {
2619        let mut inner = UnknownFields::new();
2620        inner.push(varint(1, v));
2621        inner
2622    }
2623
2624    #[test]
2625    fn group_single_record() {
2626        const E: Extension<GroupCodec<TestMsg>> = Extension::new(1, CARRIER);
2627        let mut c = Carrier::default();
2628        c.unknown.push(group(1, inner_a(5)));
2629        let got = c.extension(&E).expect("decoded");
2630        assert_eq!(got.a, 5);
2631        assert_eq!(got.b, 0);
2632    }
2633
2634    #[test]
2635    fn group_split_records_merge() {
2636        // Proto spec: multiple records at the same field number merge.
2637        // Record 1 sets a=5, record 2 sets b=7 — result has both.
2638        const E: Extension<GroupCodec<TestMsg>> = Extension::new(1, CARRIER);
2639        let mut c = Carrier::default();
2640        c.unknown.push(group(1, inner_a(5)));
2641        let mut inner_b = UnknownFields::new();
2642        inner_b.push(varint(2, 7));
2643        c.unknown.push(group(1, inner_b));
2644        let got = c.extension(&E).expect("decoded");
2645        assert_eq!(got.a, 5);
2646        assert_eq!(got.b, 7);
2647    }
2648
2649    #[test]
2650    fn group_absent_is_none() {
2651        const E: Extension<GroupCodec<TestMsg>> = Extension::new(1, CARRIER);
2652        let c = Carrier::default();
2653        assert!(c.extension(&E).is_none());
2654    }
2655
2656    #[test]
2657    fn group_wrong_wire_type_is_none() {
2658        // A LengthDelimited record at the same number does NOT match GroupCodec
2659        // — decode skips it (would merge if MessageCodec were used).
2660        const E: Extension<GroupCodec<TestMsg>> = Extension::new(1, CARRIER);
2661        let mut c = Carrier::default();
2662        c.unknown.push(ld(1, vec![0x08, 0x05]));
2663        assert!(c.extension(&E).is_none());
2664    }
2665
2666    #[test]
2667    fn group_set_get_roundtrip() {
2668        const E: Extension<GroupCodec<TestMsg>> = Extension::new(1, CARRIER);
2669        let mut c = Carrier::default();
2670        c.set_extension(
2671            &E,
2672            TestMsg {
2673                a: 3,
2674                b: -1,
2675                unknown: UnknownFields::new(),
2676            },
2677        );
2678        // Verify the encoded data is a Group variant.
2679        match &c.unknown.iter().next().unwrap().data {
2680            UnknownFieldData::Group(_) => {}
2681            other => panic!("expected Group, got {other:?}"),
2682        }
2683        let got = c.extension(&E).expect("decoded");
2684        assert_eq!(got.a, 3);
2685        assert_eq!(got.b, -1);
2686    }
2687
2688    #[test]
2689    fn group_set_empty_message() {
2690        // An empty message encodes to zero bytes → empty Group inner.
2691        // Still counts as present (explicit-presence semantics).
2692        const E: Extension<GroupCodec<TestMsg>> = Extension::new(1, CARRIER);
2693        let mut c = Carrier::default();
2694        c.set_extension(&E, TestMsg::default());
2695        assert!(c.has_extension(&E));
2696        let got = c.extension(&E).expect("decoded");
2697        assert_eq!(got, TestMsg::default());
2698    }
2699
2700    #[test]
2701    fn repeated_group() {
2702        const E: Extension<Repeated<GroupCodec<TestMsg>>> = Extension::new(1, CARRIER);
2703        let mut c = Carrier::default();
2704        c.unknown.push(group(1, inner_a(1)));
2705        c.unknown.push(group(1, inner_a(2)));
2706        let got = c.extension(&E);
2707        assert_eq!(got.len(), 2);
2708        assert_eq!(got[0].a, 1);
2709        assert_eq!(got[1].a, 2);
2710    }
2711
2712    #[test]
2713    fn repeated_group_set_get_roundtrip() {
2714        const E: Extension<Repeated<GroupCodec<TestMsg>>> = Extension::new(1, CARRIER);
2715        let mut c = Carrier::default();
2716        let msgs = vec![
2717            TestMsg {
2718                a: 10,
2719                b: 0,
2720                unknown: UnknownFields::new(),
2721            },
2722            TestMsg {
2723                a: 0,
2724                b: 20,
2725                unknown: UnknownFields::new(),
2726            },
2727        ];
2728        c.set_extension(&E, msgs.clone());
2729        // Two separate Group records.
2730        assert_eq!(c.unknown.len(), 2);
2731        for f in c.unknown.iter() {
2732            assert!(matches!(f.data, UnknownFieldData::Group(_)));
2733        }
2734        assert_eq!(c.extension(&E), msgs);
2735    }
2736
2737    // ── All remaining scalar types get a spot-check roundtrip ───────────────
2738
2739    #[test]
2740    fn scalar_roundtrip_table() {
2741        macro_rules! rt {
2742            ($codec:ty, $v:expr) => {{
2743                const E: Extension<$codec> = Extension::new(1, CARRIER);
2744                let mut c = Carrier::default();
2745                c.set_extension(&E, $v);
2746                assert_eq!(c.extension(&E), Some($v), stringify!($codec));
2747            }};
2748        }
2749        rt!(Int64, -1_i64);
2750        rt!(Uint64, u64::MAX);
2751        rt!(Sint64, i64::MIN);
2752        rt!(Fixed32, u32::MAX);
2753        rt!(Fixed64, u64::MAX);
2754        rt!(Sfixed64, -1_i64);
2755        rt!(EnumI32, 42);
2756    }
2757
2758    #[test]
2759    fn fixed64_packed_decode_partial_tail_ignored() {
2760        // 8 bytes = one value; 3 trailing bytes are ignored (not enough for a second).
2761        const E: Extension<Repeated<Fixed64>> = Extension::new(1, CARRIER);
2762        let mut c = Carrier::default();
2763        let mut payload = 42_u64.to_le_bytes().to_vec();
2764        payload.extend_from_slice(&[0x01, 0x02, 0x03]);
2765        c.unknown.push(ld(1, payload));
2766        assert_eq!(c.extension(&E), vec![42_u64]);
2767    }
2768
2769    #[test]
2770    fn varint_packed_decode_malformed_tail_stops() {
2771        // Good varint 1, then truncated varint (high bit, no continuation).
2772        const E: Extension<Repeated<Int32>> = Extension::new(1, CARRIER);
2773        let mut c = Carrier::default();
2774        c.unknown.push(ld(1, vec![0x01, 0x80]));
2775        assert_eq!(c.extension(&E), vec![1]);
2776    }
2777
2778    // Verify unused helper silenced by one use here.
2779    #[test]
2780    fn fixed64_wrong_wire_type() {
2781        const E: Extension<Fixed64> = Extension::new(1, CARRIER);
2782        let mut c = Carrier::default();
2783        c.unknown.push(fixed64(1, 0xDEADBEEF));
2784        assert_eq!(c.extension(&E), Some(0xDEADBEEF_u64));
2785        let mut c = Carrier::default();
2786        c.unknown.push(fixed32(1, 0)); // wrong wire type
2787        assert_eq!(c.extension(&E), None);
2788    }
2789}