Skip to main content

proto_rs/
codec.rs

1//! Dynamic Protocol Buffers wire codec.
2//!
3//! # Design boundaries
4//!
5//! The codec operates on descriptors produced by the schema module.
6//! It never relies on generated Rust structs or generated field accessors.
7//! Values are stored in an allocation-backed runtime representation.
8//! All byte processing uses `core` and `alloc` only.
9//! No stream, file, socket, clock, or operating-system API is required.
10//! The caller owns framing and transport concerns.
11//! The caller also chooses which descriptor describes each payload.
12//!
13//! # Wire keys
14//!
15//! Every protobuf occurrence starts with an unsigned varint key.
16//! The upper bits contain the positive field number.
17//! The lower three bits contain the wire type.
18//! Field number zero is always rejected.
19//! Field numbers above 536,870,911 are always rejected.
20//! Tags that need more than five bytes are rejected.
21//! This prevents a wide integer from truncating into a plausible field tag.
22//! Reserved schema field numbers are rejected by the schema parser.
23//!
24//! # Wire types
25//!
26//! Wire type zero carries varints.
27//! It represents signed integers, unsigned integers, booleans, and enums.
28//! Negative `int32` and `int64` values use ten-byte two's-complement varints.
29//! `sint32` and `sint64` use zig-zag transformation before varint encoding.
30//! Wire type one carries fixed-width little-endian 64-bit values.
31//! It represents `fixed64`, `sfixed64`, and `double`.
32//! Wire type two carries a varint length followed by bytes.
33//! It represents strings, bytes, messages, packed fields, and map entries.
34//! Wire type five carries fixed-width little-endian 32-bit values.
35//! It represents `fixed32`, `sfixed32`, and `float`.
36//! Wire types three and four carry unknown groups and Edition `DELIMITED`
37//! message fields; matching terminators and nesting are validated.
38//! A decoder never guesses a different type after a wire-type mismatch.
39//!
40//! # Dynamic values
41//!
42//! [`Value`] mirrors the protobuf scalar type families.
43//! Signed fixed and zig-zag values share the signed integer variants.
44//! Unsigned and fixed unsigned values share the unsigned variants.
45//! Enums retain their numeric value, including unknown enum numbers.
46//! Strings normally validate UTF-8; Edition fields selecting validation `NONE`
47//! use [`Value::RawString`] to preserve arbitrary payload bytes losslessly.
48//! Embedded messages recursively contain another [`Message`].
49//! Repeated values retain encounter order.
50//! Maps retain deterministic insertion order in a vector.
51//! Map duplicate keys are replaced using last-key-wins semantics.
52//! The dynamic representation does not borrow from the input payload.
53//! A successfully decoded message therefore owns all of its data.
54//!
55//! # Singular field semantics
56//!
57//! Repeating a singular scalar field applies protobuf's last-wins rule.
58//! Repeating a singular string or bytes field also applies last-wins.
59//! Repeating a singular enum applies last-wins without rejecting unknown values.
60//! Repeating the same oneof member applies its normal scalar or message rule.
61//! Encountering a different oneof member removes the previously selected one.
62//! Singular embedded-message occurrences are merged instead of replaced.
63//! Recursive singular messages merge recursively.
64//! Repeated fields inside merged messages are concatenated.
65//! Maps inside merged messages apply last-key-wins for each key.
66//! Unknown fields inside merged messages are appended to the audit data.
67//! These rules match the official Protocol Buffers conformance test suite.
68//!
69//! # Repeated and packed fields
70//!
71//! A decoder accepts packed and unpacked encodings for packable primitives.
72//! Multiple packed segments append values rather than replacing them.
73//! Packed lengths are checked with overflow-safe arithmetic.
74//! Fixed-width packed segments must contain complete values.
75//! A truncated packed value is reported as a parse error.
76//! Proto3 packable fields serialize packed unless explicitly disabled.
77//! Proto2 packable fields serialize unpacked unless explicitly enabled.
78//! Empty repeated fields produce no wire occurrence.
79//! Strings, bytes, messages, and maps are never packed.
80//!
81//! # Maps
82//!
83//! Maps use protobuf's synthetic entry-message wire representation.
84//! Entry field one is the key.
85//! Entry field two is the value.
86//! Missing keys receive the scalar key type's protobuf default.
87//! Missing values receive the value type's protobuf default.
88//! Unknown entry fields are skipped within the entry boundary.
89//! Entry decoding may not read beyond its declared length.
90//! Duplicate keys retain the last decoded value.
91//! The audit trail still identifies that a duplicate key occurred.
92//! Valid map keys are enforced by the schema parser.
93//! Nested maps are rejected by the schema parser and default-value logic.
94//!
95//! # Unknown data
96//!
97//! Unknown values preserve their original encoded value bytes.
98//! Their stored bytes exclude the key because number and wire type are explicit.
99//! Encoding reconstructs the key and appends the untouched value bytes.
100//! This makes ordinary decode/encode cycles forward-compatible.
101//! Unknown varints retain non-canonical but valid encodings.
102//! Unknown fixed-width values retain their exact bit patterns.
103//! Unknown length-delimited values retain their exact length and payload bytes.
104//! An unknown length-delimited value may represent a future nested message.
105//! For that reason its audit tag is [`AuditTag::UnknownMessage`].
106//! Other unknown wire occurrences use [`AuditTag::UnknownField`].
107//! Encoding options can filter these two categories independently.
108//!
109//! # Application-added fields
110//!
111//! A field absent from the descriptor cannot be encoded from a name alone.
112//! Its field number, wire type, and encoded value are not inferable.
113//! [`AddedField`] supplies that missing wire metadata explicitly.
114//! [`Message::add_field`] records the addition in the audit trail.
115//! Added values are raw by design and do not pretend to be schema-validated.
116//! Invalid field numbers and invalid wire types are rejected during encoding.
117//! Named values inserted directly into `Message::fields` are also detected.
118//! Such name-only additions can be dropped and audited.
119//! Forwarding a name-only addition returns an actionable encoding error.
120//! Callers that need forwarding should use [`Message::add_field`].
121//!
122//! # Audit trail
123//!
124//! [`AuditRecord`] describes every decoded wire occurrence.
125//! It stores the source tag, optional schema name, number, and wire type.
126//! It also stores the complete original field bytes including the key.
127//! [`AuditTag::SchemaField`] identifies a normal descriptor-known occurrence.
128//! [`AuditTag::UnknownField`] identifies unknown non-length-delimited data.
129//! [`AuditTag::UnknownMessage`] identifies unknown length-delimited data.
130//! [`AuditTag::AddedField`] identifies application-supplied raw data.
131//! [`AuditTag::DuplicateDiscarded`] identifies a displaced earlier value.
132//! [`AuditTag::DuplicateLastWins`] identifies the later retained value.
133//! [`AuditTag::DuplicateMerged`] identifies a merged message occurrence.
134//! Audit records are metadata and do not affect semantic message equality.
135//! Encoding returns the relevant records through [`EncodeOutput`].
136//! Applications can persist, inspect, count, or reject records by tag.
137//!
138//! # Forwarding policy
139//!
140//! [`EncodeOptions`] makes forwarding decisions explicit and local.
141//! `forward_unknown_fields` governs unknown scalar and fixed-width data.
142//! `forward_unknown_messages` governs unknown length-delimited data.
143//! `forward_added_fields` governs application-added raw fields.
144//! [`DuplicatePolicy::LastOnly`] emits only the retained singular value.
145//! [`DuplicatePolicy::PreserveAll`] re-emits displaced raw occurrences.
146//! [`FieldOrder::Declaration`] follows descriptor declaration order.
147//! [`FieldOrder::FieldNumber`] stably orders all emitted wire occurrences.
148//! [`MapOrder::Key`] provides stable protobuf-key ordering within maps.
149//! [`FloatEncoding::Normalize`] removes NaN-payload and signed-zero variance.
150//! `max_output_bytes` rejects an encoded root or embedded message above budget.
151//! The ordinary [`encode`] function uses conservative compatibility defaults.
152//! Those defaults forward unknown and added raw fields.
153//! Those defaults emit only the last singular scalar occurrence.
154//! Nested-message encoding receives the same options as its parent.
155//! Filtering never mutates the in-memory message or its audit trail.
156//!
157//! # Proto3 presence
158//!
159//! Implicit-presence proto3 scalar defaults are omitted during serialization.
160//! This includes zero numbers, false, empty strings, empty bytes, and enum zero.
161//! Explicit `optional` fields retain presence even when holding a default value.
162//! Oneof members retain presence even when holding a default value.
163//! Message fields always have explicit presence.
164//! Proto2 optional and required fields always have explicit presence.
165//! Presence metadata is computed after user-defined type resolution.
166//! This avoids mistaking an unresolved enum name for a message field.
167//!
168//! # Parse errors and limits
169//!
170//! Every read checks the available input before slicing.
171//! Every length addition uses checked arithmetic where overflow is possible.
172//! Varints longer than ten bytes are rejected.
173//! A tenth varint byte may contain at most the low bit.
174//! Strings with invalid UTF-8 are rejected.
175//! Known fields with incompatible wire types are rejected.
176//! Unknown group wire types are rejected rather than partially consumed.
177//! Required proto2 fields are checked after the complete message is decoded.
178//! Required fields are also checked before encoding.
179//! Errors carry the byte offset at which the problem became observable.
180//! [`DecodeOptions`] bounds size, depth, occurrences, collections, and auditing.
181//! It can reject non-minimal varints, ambiguous duplicates, unknown fields,
182//! noncanonical boolean values, and enum values absent from the descriptor.
183//! Every wire length is checked before conversion to the target's `usize`.
184//! [`decode`] uses compatibility policies and a conventional depth limit.
185//! Security boundaries should use [`decode_with_options`] with local budgets.
186//!
187//! # Sanitizing untrusted input
188//!
189//! Wire validity and application acceptance are deliberately separate layers.
190//! [`decode`] accepts protobuf-compatible alternate representations.
191//! It preserves unknown data so old and new schema versions can interoperate.
192//! That behavior is appropriate for ordinary message forwarding.
193//! A trust boundary can instead call [`decode_with_options`].
194//! Each strict policy is independent and can be adopted incrementally.
195//! Limits are checked before retaining the affected value or audit bytes.
196//! An error never returns a partially decoded public [`Message`].
197//! The caller can therefore treat success as acceptance by every chosen rule.
198//! Sanitization still cannot replace domain-specific authorization checks.
199//! Field values may be wire-valid while violating application invariants.
200//! Callers should validate identities, ranges, lengths, and relationships too.
201//!
202//! # Decode size budgets
203//!
204//! `max_message_bytes` applies to the root and every embedded message.
205//! The root check occurs before its first field is decoded.
206//! Embedded-message length is checked before recursive decoding begins.
207//! `max_length_delimited_bytes` applies to each string and bytes value.
208//! It also applies to embedded messages, packed fields, and map entries.
209//! Wire lengths are decoded as `u64` and converted with [`usize::try_from`].
210//! A length that cannot fit the current target is rejected without truncation.
211//! `max_recursion_depth` counts embedded-message edges below the root.
212//! A limit of zero permits the root but rejects its first embedded message.
213//! The compatibility default follows the conventional depth limit of 100.
214//! Applications with smaller stacks should select a smaller explicit limit.
215//! These checks are important on constrained 32-bit and embedded targets.
216//!
217//! # Decode collection budgets
218//!
219//! `max_field_occurrences` is shared across the complete decoded message tree.
220//! It includes known fields, unknown fields, and synthetic map-entry fields.
221//! This bounds floods made from many tiny tags even when values are discarded.
222//! `max_repeated_values` applies independently to each repeated field.
223//! Both packed elements and unpacked occurrences count toward the same limit.
224//! Multiple packed segments continue accumulating against that shared bound.
225//! `max_map_entries` bounds the distinct keys retained by each map field.
226//! Duplicate keys do not increase retained size under last-key-wins behavior.
227//! They still consume the global occurrence budget and can be rejected.
228//! Limits use checked counters so counter overflow itself becomes an error.
229//! The defaults remain permissive except for recursion depth.
230//! Gateways should choose budgets from their actual protocol expectations.
231//!
232//! # Strict varint form
233//!
234//! `require_minimal_varints` covers keys, lengths, and scalar varint values.
235//! Redundant continuation bytes are rejected even when the value would fit.
236//! Field keys must still fit the protobuf five-byte and field-number bounds.
237//! Strict 32-bit fields additionally reject lossy truncation from a `u64`.
238//! This catches five-byte negative `int32` values that require ten bytes.
239//! It also catches `uint32` and `sint32` inputs above their numeric width.
240//! Known values are normally normalized by decode followed by encode.
241//! Unknown values retain raw bytes unless strict decoding or dropping is used.
242//! Strict form is useful before signatures, policy checks, or parser handoff.
243//! It does not make the complete protobuf serialization canonical.
244//!
245//! # Unknown and duplicate policies
246//!
247//! [`UnknownFieldPolicy::Preserve`] retains normal compatibility behavior.
248//! [`UnknownFieldPolicy::Drop`] omits the value but still creates audit evidence.
249//! [`UnknownFieldPolicy::Reject`] fails at the first unknown field occurrence.
250//! Length-delimited unknown data cannot be reliably classified without schema.
251//! It might contain bytes, text, packed scalars, or an embedded message.
252//! Dropping unknown data is therefore the strongest generic sanitization.
253//! [`DuplicateInputPolicy::Allow`] applies protobuf merge and last-wins rules.
254//! [`DuplicateInputPolicy::Reject`] rejects singular scalar repetitions.
255//! It also rejects oneof conflicts, duplicate map keys, and duplicate entry data.
256//! Repeated field occurrences are intentional and are never duplicates.
257//! Strict duplicate rejection can prevent cross-parser interpretation variance.
258//!
259//! # Scalar-domain policies
260//!
261//! Protobuf normally interprets every nonzero boolean varint as true.
262//! [`BooleanValuePolicy::RejectNonCanonical`] accepts only zero and one.
263//! Open protobuf enums normally preserve numbers absent from the descriptor.
264//! [`EnumValuePolicy::RejectUnknown`] restricts values to declared members.
265//! That enum rule is an application sanitization choice, not proto3 default.
266//! Signed and unsigned integer values otherwise follow protobuf cast semantics.
267//! UTF-8 validation is unconditional for every descriptor-known string.
268//! Bytes fields remain opaque and require application-level content checks.
269//! Fixed-width floats retain all IEEE bit patterns during ordinary decoding.
270//!
271//! # Bounded auditing
272//!
273//! Full auditing copies each complete source occurrence for later inspection.
274//! Nested data can appear in its own audit and in its containing field record.
275//! `max_audit_bytes` bounds the cumulative bytes copied during one decode.
276//! [`AuditMode::MetadataOnly`] retains provenance without copying source bytes.
277//! Metadata-only records still identify names, numbers, wire types, and tags.
278//! They can prove that unknown or duplicate data was observed and removed.
279//! They cannot later reproduce a displaced raw occurrence byte-for-byte.
280//! Encoding with [`DuplicatePolicy::PreserveAll`] therefore rejects such input.
281//! Unknown values preserved in [`Message::unknown_fields`] remain independent.
282//! Dropping unknown fields plus metadata-only audit minimizes payload copying.
283//! Applications can persist or aggregate metadata after successful decoding.
284//!
285//! # Encoder normalization
286//!
287//! [`FieldOrder::FieldNumber`] stably sorts all complete wire occurrences.
288//! Equal-number occurrences retain order for repeated-field correctness.
289//! [`MapOrder::Key`] orders signed, unsigned, boolean, and string map keys.
290//! Map values remain attached to their corresponding keys during sorting.
291//! [`FloatEncoding::Normalize`] maps every NaN width to one quiet NaN pattern.
292//! It also converts negative zero to positive zero before writing fixed bits.
293//! Finite nonzero floating-point values retain their original IEEE value.
294//! `max_output_bytes` rejects each completed root or embedded serialization.
295//! The output limit is a final size guard rather than a streaming allocator.
296//! Callers should also bound programmatically constructed collection sizes.
297//! Unknown and application-added data can be filtered before size validation.
298//! Numeric field ordering and map ordering improve local reproducibility.
299//! Protobuf explicitly does not define a universal canonical byte encoding.
300//!
301//! # Determinism
302//!
303//! Descriptor fields serialize in declaration order.
304//! Dynamic named fields use a `BTreeMap` for stable inspection order.
305//! Repeated values serialize in their retained order.
306//! Map values serialize in their retained insertion order.
307//! Unknown fields serialize after schema-known fields.
308//! Application-added raw fields serialize after received unknown fields.
309//! Protobuf does not require a unique byte representation for a message.
310//! Determinism here is therefore an implementation property, not canonicality.
311//! Decoders must continue accepting semantically equivalent field orders.
312//!
313//! # Conformance
314//!
315//! The repository contains a host-only official conformance test adapter.
316//! The adapter uses this dynamic API rather than generated Rust messages.
317//! Proto3 binary required and recommended cases are exercised.
318//! Basic proto2 binary cases are exercised with known MessageSet exclusions.
319//! Protobuf JSON requests use the descriptor-driven JSON module.
320//! Text-format and JSPB requests are explicitly skipped by the adapter.
321//! `CONFORMANCE.md` records every ignored or unsupported family.
322//! The vendored runner pins the upstream protobuf revision used for results.
323//! None of the host-only conformance machinery is linked into this library.
324
325use crate::{
326    Cardinality, EnumType, Error, Field, FieldPresence, FieldType, MessageDescriptor,
327    MessageEncoding, Result, Schema, Utf8Validation,
328    constants::{
329        CANONICAL_F32_NAN_BITS, CANONICAL_F64_NAN_BITS, DEFAULT_RECURSION_LIMIT,
330        FIELD_NUMBER_SHIFT, FIXED32_SIZE, FIXED64_SIZE, HARDENED_MAX_AUDIT_BYTES,
331        HARDENED_MAX_FIELD_OCCURRENCES, HARDENED_MAX_LENGTH_DELIMITED_BYTES,
332        HARDENED_MAX_MAP_ENTRIES, HARDENED_MAX_MESSAGE_BYTES, HARDENED_MAX_REPEATED_VALUES,
333        I32_SIGN_SHIFT, I64_SIGN_SHIFT, MAP_KEY_FIELD_NUMBER, MAP_VALUE_FIELD_NUMBER,
334        MAX_FIELD_KEY_BYTES, MAX_FIELD_NUMBER, MAX_TENTH_VARINT_BYTE, MAX_VARINT_BYTES,
335        MIN_FIELD_NUMBER, VARINT_BITS_PER_BYTE, VARINT_CONTINUATION_BIT, VARINT_DATA_MASK,
336        WIRE_TYPE_END_GROUP, WIRE_TYPE_FIXED32, WIRE_TYPE_FIXED64, WIRE_TYPE_LENGTH_DELIMITED,
337        WIRE_TYPE_MASK, WIRE_TYPE_START_GROUP, WIRE_TYPE_VARINT, is_supported_wire_type, make_key,
338    },
339};
340use alloc::{
341    collections::{BTreeMap, BTreeSet},
342    string::{String, ToString},
343    vec::Vec,
344};
345use core::{cmp::Ordering, ops::Range};
346/// Runtime representation of any supported protobuf field value.
347#[derive(Clone, Debug, PartialEq)]
348pub enum Value {
349    /// IEEE-754 double-precision value.
350    Double(f64),
351    /// IEEE-754 single-precision value.
352    Float(f32),
353    /// Signed 32-bit integer, including `sint32` and `sfixed32` values.
354    Int32(i32),
355    /// Signed 64-bit integer, including `sint64` and `sfixed64` values.
356    Int64(i64),
357    /// Unsigned 32-bit integer, including `fixed32` values.
358    Uint32(u32),
359    /// Unsigned 64-bit integer, including `fixed64` values.
360    Uint64(u64),
361    /// Boolean value.
362    Bool(bool),
363    /// UTF-8 string value.
364    String(String),
365    /// String payload retained without UTF-8 validation under Editions.
366    RawString(Vec<u8>),
367    /// Opaque byte-string value.
368    Bytes(Vec<u8>),
369    /// Numeric enum value, including values unknown to the schema.
370    Enum(i32),
371    /// Descriptor-driven embedded message.
372    Message(Message),
373    /// Ordered occurrences of a repeated field.
374    Repeated(Vec<Value>),
375    /// Protobuf map entries in deterministic insertion order.
376    Map(Vec<(Value, Value)>),
377}
378/// Schema-external wire occurrence retained during decoding.
379#[derive(Clone, Debug, PartialEq)]
380pub struct UnknownField {
381    /// Positive protobuf field number decoded from the wire key.
382    pub number: u32,
383    /// Protobuf binary wire-type identifier.
384    pub wire_type: u8,
385    /// Exact encoded value bytes excluding the field key.
386    pub encoded_value: Vec<u8>,
387}
388/// A raw field supplied by the application without a schema declaration.
389///
390/// `encoded_value` contains the bytes after the field key, exactly like
391/// [`UnknownField::encoded_value`]. Keeping the wire metadata makes forwarding
392/// possible even though the registry has no descriptor for the field.
393#[derive(Clone, Debug, PartialEq)]
394pub struct AddedField {
395    /// Application-facing name used to identify the added field.
396    pub name: String,
397    /// Positive protobuf field number to write into the wire key.
398    pub number: u32,
399    /// Protobuf binary wire-type identifier.
400    pub wire_type: u8,
401    /// Pre-encoded value bytes excluding the field key.
402    pub encoded_value: Vec<u8>,
403}
404
405/// Identifies why an occurrence exists and how decoding treated it.
406#[derive(Clone, Copy, Debug, Eq, PartialEq)]
407pub enum AuditTag {
408    /// The occurrence was declared by the parsed schema.
409    SchemaField,
410    /// The field number was absent from the schema.
411    UnknownField,
412    /// An unknown length-delimited occurrence may contain a nested message.
413    UnknownMessage,
414    /// The application added a raw field absent from the schema.
415    AddedField,
416    /// A later singular occurrence displaced this one under last-wins rules.
417    DuplicateDiscarded,
418    /// This occurrence won because it was the last singular value or map key.
419    DuplicateLastWins,
420    /// A repeated singular message occurrence was merged as protobuf requires.
421    DuplicateMerged,
422}
423
424/// Controls whether unknown wire occurrences are retained after decoding.
425#[derive(Clone, Copy, Debug, Eq, PartialEq)]
426pub enum UnknownFieldPolicy {
427    /// Retain unknown values for forward-compatible reserialization.
428    Preserve,
429    /// Remove unknown values while retaining their audit metadata.
430    Drop,
431    /// Reject a message as soon as an unknown field number is encountered.
432    Reject,
433}
434
435/// Controls how duplicate singular fields and duplicate map keys are handled.
436#[derive(Clone, Copy, Debug, Eq, PartialEq)]
437pub enum DuplicateInputPolicy {
438    /// Apply protobuf merge and last-wins rules while recording audit tags.
439    Allow,
440    /// Reject duplicate singular fields, oneof conflicts, and map keys.
441    Reject,
442}
443
444/// Controls retention of original field bytes in decode audit records.
445#[derive(Clone, Copy, Debug, Eq, PartialEq)]
446pub enum AuditMode {
447    /// Retain complete original field bytes subject to the audit-byte limit.
448    Full,
449    /// Retain tags and field metadata without copying original field bytes.
450    MetadataOnly,
451}
452
453/// Controls interpretation of boolean varints other than zero and one.
454#[derive(Clone, Copy, Debug, Eq, PartialEq)]
455pub enum BooleanValuePolicy {
456    /// Decode zero as false and every nonzero value as true.
457    CoerceNonzero,
458    /// Reject boolean varints whose numeric value is greater than one.
459    RejectNonCanonical,
460}
461
462/// Controls whether enum numbers absent from the descriptor are accepted.
463#[derive(Clone, Copy, Debug, Eq, PartialEq)]
464pub enum EnumValuePolicy {
465    /// Preserve every signed 32-bit enum number, including unknown values.
466    Preserve,
467    /// Reject enum numbers not declared by the resolved enum descriptor.
468    RejectUnknown,
469}
470
471/// Resource and normalization policies applied while decoding wire data.
472#[derive(Clone, Copy, Debug, Eq, PartialEq)]
473pub struct DecodeOptions {
474    /// Maximum size of each decoded root or embedded message.
475    pub max_message_bytes: usize,
476    /// Maximum embedded-message nesting below the root message.
477    pub max_recursion_depth: usize,
478    /// Maximum total field occurrences across the complete message tree.
479    pub max_field_occurrences: usize,
480    /// Maximum payload size of one length-delimited value.
481    pub max_length_delimited_bytes: usize,
482    /// Maximum retained values in any one repeated field.
483    pub max_repeated_values: usize,
484    /// Maximum retained entries in any one map field.
485    pub max_map_entries: usize,
486    /// Maximum cumulative original bytes copied into audit records.
487    pub max_audit_bytes: usize,
488    /// Unknown-field retention or rejection policy.
489    pub unknown_fields: UnknownFieldPolicy,
490    /// Duplicate singular-field and map-key policy.
491    pub duplicates: DuplicateInputPolicy,
492    /// Whether audit records retain complete original field bytes.
493    pub audit_mode: AuditMode,
494    /// Whether keys, lengths, and scalar varints must use minimal encoding.
495    pub require_minimal_varints: bool,
496    /// Boolean value-domain policy.
497    pub booleans: BooleanValuePolicy,
498    /// Enum value-domain policy.
499    pub enum_values: EnumValuePolicy,
500}
501
502impl Default for DecodeOptions {
503    /// Preserves protobuf-compatible behavior with a conventional depth limit.
504    fn default() -> Self {
505        Self {
506            max_message_bytes: usize::MAX,
507            max_recursion_depth: DEFAULT_RECURSION_LIMIT,
508            max_field_occurrences: usize::MAX,
509            max_length_delimited_bytes: usize::MAX,
510            max_repeated_values: usize::MAX,
511            max_map_entries: usize::MAX,
512            max_audit_bytes: usize::MAX,
513            unknown_fields: UnknownFieldPolicy::Preserve,
514            duplicates: DuplicateInputPolicy::Allow,
515            audit_mode: AuditMode::Full,
516            require_minimal_varints: false,
517            booleans: BooleanValuePolicy::CoerceNonzero,
518            enum_values: EnumValuePolicy::Preserve,
519        }
520    }
521}
522
523impl DecodeOptions {
524    /// Returns finite, strict defaults suitable for decoding hostile traffic.
525    pub const fn hardened() -> Self {
526        Self {
527            max_message_bytes: HARDENED_MAX_MESSAGE_BYTES,
528            max_recursion_depth: DEFAULT_RECURSION_LIMIT,
529            max_field_occurrences: HARDENED_MAX_FIELD_OCCURRENCES,
530            max_length_delimited_bytes: HARDENED_MAX_LENGTH_DELIMITED_BYTES,
531            max_repeated_values: HARDENED_MAX_REPEATED_VALUES,
532            max_map_entries: HARDENED_MAX_MAP_ENTRIES,
533            max_audit_bytes: HARDENED_MAX_AUDIT_BYTES,
534            unknown_fields: UnknownFieldPolicy::Reject,
535            duplicates: DuplicateInputPolicy::Reject,
536            audit_mode: AuditMode::MetadataOnly,
537            require_minimal_varints: true,
538            booleans: BooleanValuePolicy::RejectNonCanonical,
539            enum_values: EnumValuePolicy::RejectUnknown,
540        }
541    }
542}
543
544/// Immutable evidence for one decoded or programmatically added occurrence.
545#[derive(Clone, Debug, Eq, PartialEq)]
546pub struct AuditRecord {
547    /// Classification describing the occurrence's provenance and treatment.
548    pub tag: AuditTag,
549    /// Descriptor or application field name, when one is available.
550    pub field_name: Option<String>,
551    /// Numeric protobuf field tag, or zero for name-only additions.
552    pub field_number: u32,
553    /// Protobuf binary wire-type identifier.
554    pub wire_type: u8,
555    /// Complete original field bytes, including the encoded field key.
556    pub encoded_field: Vec<u8>,
557}
558
559/// Controls whether displaced singular occurrences are re-emitted.
560#[derive(Clone, Copy, Debug, Eq, PartialEq)]
561pub enum DuplicatePolicy {
562    /// Emit only the value retained by protobuf's last-wins policy.
563    LastOnly,
564    /// Re-emit displaced raw occurrences before the retained value.
565    PreserveAll,
566}
567
568/// Controls the order of serialized protobuf field occurrences.
569#[derive(Clone, Copy, Debug, Eq, PartialEq)]
570pub enum FieldOrder {
571    /// Emit known fields in schema declaration order, then forwarded fields.
572    Declaration,
573    /// Stably sort every emitted occurrence by its numeric protobuf field ID.
574    ///
575    /// Repeated occurrences with the same field number retain their original
576    /// relative order, preserving repeated-field and duplicate semantics.
577    FieldNumber,
578}
579
580/// Controls serialization order for entries within each map field.
581#[derive(Clone, Copy, Debug, Eq, PartialEq)]
582pub enum MapOrder {
583    /// Preserve the map entry order retained by the dynamic message.
584    Preserve,
585    /// Sort entries by their protobuf key value before serialization.
586    Key,
587}
588
589/// Controls normalization of floating-point bit patterns during encoding.
590#[derive(Clone, Copy, Debug, Eq, PartialEq)]
591pub enum FloatEncoding {
592    /// Preserve finite values, signed zero, and NaN payload bits exactly.
593    Preserve,
594    /// Convert negative zero to positive zero and every NaN to one quiet NaN.
595    Normalize,
596}
597
598/// Serialization controls for schema-external, duplicate, and ordered data.
599#[derive(Clone, Copy, Debug, Eq, PartialEq)]
600pub struct EncodeOptions {
601    /// Whether unknown scalar and fixed-width occurrences are emitted.
602    pub forward_unknown_fields: bool,
603    /// Whether unknown length-delimited occurrences are emitted.
604    pub forward_unknown_messages: bool,
605    /// Whether raw application-added occurrences are emitted.
606    pub forward_added_fields: bool,
607    /// Policy controlling displaced duplicate singular occurrences.
608    pub duplicates: DuplicatePolicy,
609    /// Ordering policy applied to every emitted wire occurrence.
610    pub field_order: FieldOrder,
611    /// Ordering policy applied within each dynamically represented map.
612    pub map_order: MapOrder,
613    /// Floating-point bit-pattern normalization policy.
614    pub floats: FloatEncoding,
615    /// Maximum total serialized size of each root or embedded message.
616    pub max_output_bytes: usize,
617}
618
619impl Default for EncodeOptions {
620    /// Enables forwarding of schema-external data and keeps only retained
621    /// singular values, matching protobuf's normal compatibility behavior.
622    fn default() -> Self {
623        Self {
624            forward_unknown_fields: true,
625            forward_unknown_messages: true,
626            forward_added_fields: true,
627            duplicates: DuplicatePolicy::LastOnly,
628            field_order: FieldOrder::Declaration,
629            map_order: MapOrder::Preserve,
630            floats: FloatEncoding::Preserve,
631            max_output_bytes: usize::MAX,
632        }
633    }
634}
635
636/// Encoded bytes accompanied by the complete audit trail used to produce them.
637#[derive(Clone, Debug, PartialEq)]
638pub struct EncodeOutput {
639    /// Serialized protobuf binary message.
640    pub bytes: Vec<u8>,
641    /// Audit records considered while producing the serialized bytes.
642    pub audit: Vec<AuditRecord>,
643}
644
645/// Allocation-backed dynamic protobuf message and its audit metadata.
646#[derive(Clone, Debug, Default)]
647pub struct Message {
648    /// Descriptor-named semantic field values.
649    pub fields: BTreeMap<String, Value>,
650    /// Wire occurrences whose field numbers are absent from the descriptor.
651    pub unknown_fields: Vec<UnknownField>,
652    /// Raw schema-external fields supplied by the application.
653    pub added_fields: Vec<AddedField>,
654    /// Provenance and duplicate-handling records for wire occurrences.
655    pub audit: Vec<AuditRecord>,
656}
657impl PartialEq for Message {
658    /// Compares semantic fields while deliberately excluding audit metadata.
659    fn eq(&self, other: &Self) -> bool {
660        self.fields == other.fields
661            && self.unknown_fields == other.unknown_fields
662            && self.added_fields == other.added_fields
663    }
664}
665impl Message {
666    /// Creates an empty dynamic message with no fields or audit records.
667    pub fn new() -> Self {
668        Self::default()
669    }
670    /// Inserts or replaces a descriptor-named value.
671    ///
672    /// Returns the previous value when the name was already present.
673    pub fn insert(&mut self, n: impl Into<String>, v: Value) -> Option<Value> {
674        self.fields.insert(n.into(), v)
675    }
676    /// Returns the dynamic value stored under a descriptor field name.
677    pub fn get(&self, n: &str) -> Option<&Value> {
678        self.fields.get(n)
679    }
680
681    /// Adds a schema-external raw field and records its provenance immediately.
682    pub fn add_field(&mut self, field: AddedField) {
683        let mut encoded_field = Vec::new();
684        vi(make_key(field.number, field.wire_type), &mut encoded_field);
685        encoded_field.extend_from_slice(&field.encoded_value);
686        self.audit.push(AuditRecord {
687            tag: AuditTag::AddedField,
688            field_name: Some(field.name.clone()),
689            field_number: field.number,
690            wire_type: field.wire_type,
691            encoded_field,
692        });
693        self.added_fields.push(field);
694    }
695}
696/// Appends an unsigned integer using protobuf's base-128 varint encoding.
697fn vi(mut n: u64, o: &mut Vec<u8>) {
698    while n > u64::from(VARINT_DATA_MASK) {
699        o.push(n as u8 | VARINT_CONTINUATION_BIT);
700        n >>= VARINT_BITS_PER_BYTE
701    }
702    o.push(n as u8)
703}
704/// Reads one unsigned protobuf varint and advances the input cursor.
705///
706/// Returns an error for truncation, values wider than 64 bits, or varints
707/// longer than the protobuf ten-byte limit.
708fn rv(b: &[u8], p: &mut usize) -> Result<u64> {
709    read_varint(b, p, false)
710}
711
712/// Returns the shortest legal byte length for an unsigned varint value.
713fn minimal_varint_length(mut value: u64) -> usize {
714    let mut length = 1;
715    while value > u64::from(VARINT_DATA_MASK) {
716        value >>= VARINT_BITS_PER_BYTE;
717        length += 1;
718    }
719    length
720}
721
722/// Reads a varint and optionally rejects a longer-than-minimal representation.
723fn read_varint(b: &[u8], p: &mut usize, require_minimal: bool) -> Result<u64> {
724    let s = *p;
725    let mut n = 0;
726    for byte_index in 0..MAX_VARINT_BYTES {
727        let shift = byte_index * VARINT_BITS_PER_BYTE;
728        let x = *b.get(*p).ok_or_else(|| Error::new(s, "truncated varint"))?;
729        *p += 1;
730        if byte_index + 1 == MAX_VARINT_BYTES && x > MAX_TENTH_VARINT_BYTE {
731            return Err(Error::new(s, "varint overflow"));
732        }
733        n |= u64::from(x & VARINT_DATA_MASK) << shift;
734        if x & VARINT_CONTINUATION_BIT == 0 {
735            let encoded_length = p
736                .checked_sub(s)
737                .ok_or_else(|| Error::new(s, "varint cursor moved backwards"))?;
738            if require_minimal && encoded_length != minimal_varint_length(n) {
739                return Err(Error::new(s, "non-minimal varint encoding"));
740            }
741            return Ok(n);
742        }
743    }
744    Err(Error::new(s, "varint overflow"))
745}
746/// Decodes and validates a protobuf field key at the current input cursor.
747///
748/// The returned pair contains the positive field number and its wire type.
749fn read_key(b: &[u8], p: &mut usize) -> Result<(u32, u8)> {
750    read_key_with_policy(b, p, false)
751}
752
753/// Decodes a field key under the selected minimal-varint policy.
754fn read_key_with_policy(b: &[u8], p: &mut usize, require_minimal: bool) -> Result<(u32, u8)> {
755    let start = *p;
756    let key = read_varint(b, p, require_minimal)?;
757    let encoded_size = p
758        .checked_sub(start)
759        .ok_or_else(|| Error::new(start, "field cursor moved backwards"))?;
760    if encoded_size > MAX_FIELD_KEY_BYTES || key > u64::from(u32::MAX) {
761        return Err(Error::new(start, "field tag exceeds 32 bits"));
762    }
763    let number = (key >> FIELD_NUMBER_SHIFT) as u32;
764    if !(MIN_FIELD_NUMBER..=MAX_FIELD_NUMBER).contains(&number) {
765        return Err(Error::new(start, "invalid field number in tag"));
766    }
767    Ok((number, (key & WIRE_TYPE_MASK) as u8))
768}
769/// Returns the protobuf binary wire type required by a resolved field type.
770fn wire(t: &FieldType) -> u8 {
771    match t {
772        FieldType::Double | FieldType::Fixed64 | FieldType::Sfixed64 => WIRE_TYPE_FIXED64,
773        FieldType::String | FieldType::Bytes | FieldType::Message(_) | FieldType::Map(..) => {
774            WIRE_TYPE_LENGTH_DELIMITED
775        }
776        FieldType::Float | FieldType::Fixed32 | FieldType::Sfixed32 => WIRE_TYPE_FIXED32,
777        _ => WIRE_TYPE_VARINT,
778    }
779}
780/// Encodes one non-map, non-repeated value without writing its field key.
781///
782/// Nested messages inherit the caller's forwarding options. An error is
783/// returned when the dynamic value does not match the descriptor field type.
784fn scalar(
785    t: &FieldType,
786    v: &Value,
787    s: &Schema,
788    options: &EncodeOptions,
789    o: &mut Vec<u8>,
790) -> Result<()> {
791    match (t, v) {
792        (FieldType::Double, Value::Double(x)) => {
793            let value = normalized_f64(*x, options.floats);
794            o.extend(value.to_le_bytes());
795        }
796        (FieldType::Float, Value::Float(x)) => {
797            let value = normalized_f32(*x, options.floats);
798            o.extend(value.to_le_bytes());
799        }
800        (FieldType::Int32, Value::Int32(x)) => vi(*x as i64 as u64, o),
801        (FieldType::Int64, Value::Int64(x)) => vi(*x as u64, o),
802        (FieldType::Uint32, Value::Uint32(x)) => vi(*x as u64, o),
803        (FieldType::Uint64, Value::Uint64(x)) => vi(*x, o),
804        (FieldType::Sint32, Value::Int32(x)) => {
805            vi(((*x << 1) ^ (*x >> I32_SIGN_SHIFT)) as u32 as u64, o)
806        }
807        (FieldType::Sint64, Value::Int64(x)) => vi(((*x << 1) ^ (*x >> I64_SIGN_SHIFT)) as u64, o),
808        (FieldType::Fixed32, Value::Uint32(x)) => o.extend(x.to_le_bytes()),
809        (FieldType::Fixed64, Value::Uint64(x)) => o.extend(x.to_le_bytes()),
810        (FieldType::Sfixed32, Value::Int32(x)) => o.extend(x.to_le_bytes()),
811        (FieldType::Sfixed64, Value::Int64(x)) => o.extend(x.to_le_bytes()),
812        (FieldType::Bool, Value::Bool(x)) => vi(*x as u64, o),
813        (FieldType::Enum(name), Value::Enum(x)) => {
814            if s.enums.get(name).is_some_and(|enumeration| {
815                enumeration.features.enum_type == EnumType::Closed
816                    && !enumeration
817                        .values
818                        .iter()
819                        .any(|candidate| candidate.number == *x)
820            }) {
821                return Err(Error::new(0, "unknown value for closed enum"));
822            }
823            vi(*x as i64 as u64, o);
824        }
825        (FieldType::String, Value::String(x)) => {
826            ensure_output_growth(
827                o.len(),
828                minimal_varint_length(x.len() as u64),
829                x.len(),
830                options.max_output_bytes,
831            )?;
832            vi(x.len() as u64, o);
833            o.extend(x.as_bytes())
834        }
835        (FieldType::Bytes, Value::Bytes(x)) => {
836            ensure_output_growth(
837                o.len(),
838                minimal_varint_length(x.len() as u64),
839                x.len(),
840                options.max_output_bytes,
841            )?;
842            vi(x.len() as u64, o);
843            o.extend(x)
844        }
845        (FieldType::Message(n), Value::Message(x)) => {
846            let d = s
847                .message(n)
848                .ok_or_else(|| Error::new(0, "unknown message type"))?;
849            let b = encode_inner(s, d, x, options)?.bytes;
850            ensure_output_growth(
851                o.len(),
852                minimal_varint_length(b.len() as u64),
853                b.len(),
854                options.max_output_bytes,
855            )?;
856            vi(b.len() as u64, o);
857            o.extend(b)
858        }
859        _ => return Err(Error::new(0, "value does not match field type")),
860    }
861    Ok(())
862}
863
864/// Rejects an append before it can grow an output buffer beyond its budget.
865fn ensure_output_growth(
866    current: usize,
867    overhead: usize,
868    payload: usize,
869    limit: usize,
870) -> Result<()> {
871    let required = current
872        .checked_add(overhead)
873        .and_then(|value| value.checked_add(payload))
874        .ok_or_else(|| Error::new(0, "encoded message size overflow"))?;
875    if required > limit {
876        return Err(Error::new(
877            0,
878            "encoded message exceeds configured size limit",
879        ));
880    }
881    Ok(())
882}
883
884/// Applies the selected normalization policy to one 32-bit float.
885fn normalized_f32(value: f32, policy: FloatEncoding) -> f32 {
886    if policy == FloatEncoding::Normalize {
887        if value.is_nan() {
888            f32::from_bits(CANONICAL_F32_NAN_BITS)
889        } else if value == 0.0 {
890            0.0
891        } else {
892            value
893        }
894    } else {
895        value
896    }
897}
898
899/// Applies the selected normalization policy to one 64-bit float.
900fn normalized_f64(value: f64, policy: FloatEncoding) -> f64 {
901    if policy == FloatEncoding::Normalize {
902        if value.is_nan() {
903            f64::from_bits(CANONICAL_F64_NAN_BITS)
904        } else if value == 0.0 {
905            0.0
906        } else {
907            value
908        }
909    } else {
910        value
911    }
912}
913
914/// Compares two valid dynamic map keys according to their protobuf key type.
915fn compare_map_keys(kind: &FieldType, left: &Value, right: &Value) -> Ordering {
916    match (kind, left, right) {
917        (
918            FieldType::Int32 | FieldType::Sint32 | FieldType::Sfixed32,
919            Value::Int32(left),
920            Value::Int32(right),
921        ) => left.cmp(right),
922        (
923            FieldType::Int64 | FieldType::Sint64 | FieldType::Sfixed64,
924            Value::Int64(left),
925            Value::Int64(right),
926        ) => left.cmp(right),
927        (FieldType::Uint32 | FieldType::Fixed32, Value::Uint32(left), Value::Uint32(right)) => {
928            left.cmp(right)
929        }
930        (FieldType::Uint64 | FieldType::Fixed64, Value::Uint64(left), Value::Uint64(right)) => {
931            left.cmp(right)
932        }
933        (FieldType::Bool, Value::Bool(left), Value::Bool(right)) => left.cmp(right),
934        (FieldType::String, Value::String(left), Value::String(right)) => left.cmp(right),
935        (FieldType::String, Value::RawString(left), Value::RawString(right)) => left.cmp(right),
936        _ => Ordering::Equal,
937    }
938}
939/// Serializes a dynamic message using the default forwarding policy.
940///
941/// # Errors
942///
943/// Returns an error for missing required fields, unknown referenced message
944/// types, invalid added-field metadata, or values incompatible with the schema.
945pub fn encode(s: &Schema, d: &MessageDescriptor, m: &Message) -> Result<Vec<u8>> {
946    Ok(encode_with_options(s, d, m, &EncodeOptions::default())?.bytes)
947}
948
949/// Serializes a message while applying explicit forwarding policies.
950///
951/// The returned audit vector includes existing decode records and any
952/// schema-absent named fields discovered during serialization.
953///
954/// # Errors
955///
956/// Returns the same validation errors as [`encode`]. Forwarding a named field
957/// with no descriptor also fails because its wire metadata cannot be inferred.
958pub fn encode_with_options(
959    s: &Schema,
960    d: &MessageDescriptor,
961    m: &Message,
962    options: &EncodeOptions,
963) -> Result<EncodeOutput> {
964    encode_inner(s, d, m, options)
965}
966
967/// Validates descriptor-level invariants that the open dynamic model cannot
968/// express in its Rust types alone.
969fn validate_message_shape(s: &Schema, d: &MessageDescriptor, m: &Message) -> Result<()> {
970    let mut selected_oneofs = BTreeSet::new();
971    for field in s.fields_for(d) {
972        let Some(value) = m.get(&field.name) else {
973            continue;
974        };
975        if let Some(oneof) = &field.oneof
976            && !selected_oneofs.insert(oneof.as_str())
977        {
978            return Err(Error::new(0, "multiple values supplied for oneof"));
979        }
980        match (&field.kind, field.cardinality, value) {
981            (FieldType::Map(_, _), _, Value::Map(entries)) => {
982                for (index, (key, _)) in entries.iter().enumerate() {
983                    if entries[..index].iter().any(|(previous, _)| previous == key) {
984                        return Err(Error::new(0, "dynamic map contains duplicate keys"));
985                    }
986                }
987            }
988            (FieldType::Map(_, _), _, _) => {
989                return Err(Error::new(0, "map field requires Value::Map"));
990            }
991            (_, Cardinality::Repeated, Value::Repeated(_)) => {}
992            (_, Cardinality::Repeated, _) => {
993                return Err(Error::new(0, "repeated field requires Value::Repeated"));
994            }
995            (_, _, Value::Repeated(_)) => {
996                return Err(Error::new(
997                    0,
998                    "singular field cannot contain Value::Repeated",
999                ));
1000            }
1001            _ => {}
1002        }
1003    }
1004    Ok(())
1005}
1006
1007/// Requires a public raw-field buffer to contain exactly one complete value.
1008fn validate_raw_field(number: u32, wire_type: u8, encoded_value: &[u8]) -> Result<()> {
1009    if !(MIN_FIELD_NUMBER..=MAX_FIELD_NUMBER).contains(&number)
1010        || !is_supported_wire_type(wire_type)
1011    {
1012        return Err(Error::new(0, "raw field has invalid wire metadata"));
1013    }
1014    let mut cursor = 0;
1015    skip(number, wire_type, encoded_value, &mut cursor)?;
1016    if cursor != encoded_value.len() {
1017        return Err(Error::new(cursor, "raw field contains trailing wire data"));
1018    }
1019    Ok(())
1020}
1021
1022/// Validates a complete audit occurrence before duplicate replay.
1023fn validate_encoded_occurrence(record: &AuditRecord) -> Result<()> {
1024    let mut cursor = 0;
1025    let (number, wire_type) = read_key(&record.encoded_field, &mut cursor)?;
1026    if number != record.field_number || wire_type != record.wire_type {
1027        return Err(Error::new(
1028            0,
1029            "audit wire metadata does not match encoded field",
1030        ));
1031    }
1032    skip(number, wire_type, &record.encoded_field, &mut cursor)?;
1033    if cursor != record.encoded_field.len() {
1034        return Err(Error::new(
1035            cursor,
1036            "audit field contains trailing wire data",
1037        ));
1038    }
1039    Ok(())
1040}
1041
1042/// Implements recursive serialization shared by the public encoding APIs.
1043fn encode_inner(
1044    s: &Schema,
1045    d: &MessageDescriptor,
1046    m: &Message,
1047    options: &EncodeOptions,
1048) -> Result<EncodeOutput> {
1049    validate_message_shape(s, d, m)?;
1050    let mut o = Vec::new();
1051    let mut audit = m.audit.clone();
1052    if options.duplicates == DuplicatePolicy::PreserveAll {
1053        for record in &m.audit {
1054            if record.tag == AuditTag::DuplicateDiscarded {
1055                if record.encoded_field.is_empty() {
1056                    return Err(Error::new(
1057                        0,
1058                        "cannot preserve duplicate without retained audit bytes",
1059                    ));
1060                }
1061                validate_encoded_occurrence(record)?;
1062                ensure_output_growth(
1063                    o.len(),
1064                    0,
1065                    record.encoded_field.len(),
1066                    options.max_output_bytes,
1067                )?;
1068                o.extend_from_slice(&record.encoded_field);
1069            }
1070        }
1071    }
1072    for f in s.fields_for(d) {
1073        if let Some(v) = m.get(&f.name) {
1074            if let FieldType::Map(key_type, value_type) = &f.kind {
1075                let Value::Map(entries) = v else {
1076                    return Err(Error::new(0, "map field requires Value::Map"));
1077                };
1078                let mut ordered_entries: Vec<_> = entries.iter().collect();
1079                if options.map_order == MapOrder::Key {
1080                    ordered_entries
1081                        .sort_by(|left, right| compare_map_keys(key_type, &left.0, &right.0));
1082                }
1083                for (key, value) in ordered_entries {
1084                    let mut entry = Vec::new();
1085                    vi(make_key(MAP_KEY_FIELD_NUMBER, wire(key_type)), &mut entry);
1086                    scalar(key_type, key, s, options, &mut entry)?;
1087                    vi(
1088                        make_key(MAP_VALUE_FIELD_NUMBER, wire(value_type)),
1089                        &mut entry,
1090                    );
1091                    scalar(value_type, value, s, options, &mut entry)?;
1092                    ensure_output_growth(
1093                        o.len(),
1094                        minimal_varint_length(make_key(f.number, WIRE_TYPE_LENGTH_DELIMITED))
1095                            + minimal_varint_length(entry.len() as u64),
1096                        entry.len(),
1097                        options.max_output_bytes,
1098                    )?;
1099                    vi(make_key(f.number, WIRE_TYPE_LENGTH_DELIMITED), &mut o);
1100                    vi(entry.len() as u64, &mut o);
1101                    o.extend(entry);
1102                }
1103                continue;
1104            }
1105            if !f.explicit_presence && is_default(v) {
1106                continue;
1107            }
1108            let xs = if let Value::Repeated(x) = v {
1109                x.as_slice()
1110            } else {
1111                core::slice::from_ref(v)
1112            };
1113            if xs.is_empty() {
1114                continue;
1115            }
1116            let pack = matches!(v, Value::Repeated(_)) && f.packed.unwrap_or(false);
1117            if pack {
1118                let mut z = Vec::new();
1119                for x in xs {
1120                    scalar(&f.kind, x, s, options, &mut z)?
1121                }
1122                ensure_output_growth(
1123                    o.len(),
1124                    minimal_varint_length(make_key(f.number, WIRE_TYPE_LENGTH_DELIMITED))
1125                        + minimal_varint_length(z.len() as u64),
1126                    z.len(),
1127                    options.max_output_bytes,
1128                )?;
1129                vi(make_key(f.number, WIRE_TYPE_LENGTH_DELIMITED), &mut o);
1130                vi(z.len() as u64, &mut o);
1131                o.extend(z)
1132            } else {
1133                for x in xs {
1134                    if matches!(f.kind, FieldType::Message(_))
1135                        && f.features.message_encoding == MessageEncoding::Delimited
1136                    {
1137                        let (FieldType::Message(name), Value::Message(message)) = (&f.kind, x)
1138                        else {
1139                            return Err(Error::new(0, "value does not match message field type"));
1140                        };
1141                        let nested = s
1142                            .message(name)
1143                            .ok_or_else(|| Error::new(0, "unknown message type"))?;
1144                        vi(make_key(f.number, WIRE_TYPE_START_GROUP), &mut o);
1145                        o.extend(encode_inner(s, nested, message, options)?.bytes);
1146                        vi(make_key(f.number, WIRE_TYPE_END_GROUP), &mut o);
1147                    } else {
1148                        vi(make_key(f.number, wire(&f.kind)), &mut o);
1149                        if let (FieldType::String, Value::RawString(bytes)) = (&f.kind, x) {
1150                            if f.features.utf8_validation != Utf8Validation::None {
1151                                return Err(Error::new(
1152                                    0,
1153                                    "raw string requires utf8_validation = NONE",
1154                                ));
1155                            }
1156                            ensure_output_growth(
1157                                o.len(),
1158                                minimal_varint_length(bytes.len() as u64),
1159                                bytes.len(),
1160                                options.max_output_bytes,
1161                            )?;
1162                            vi(bytes.len() as u64, &mut o);
1163                            o.extend(bytes);
1164                        } else {
1165                            scalar(&f.kind, x, s, options, &mut o)?
1166                        }
1167                    }
1168                }
1169            }
1170        } else if f.cardinality == Cardinality::Required
1171            || f.features.field_presence == FieldPresence::LegacyRequired
1172        {
1173            return Err(Error::new(0, "missing required field"));
1174        }
1175    }
1176    for u in &m.unknown_fields {
1177        let forward = if matches!(
1178            u.wire_type,
1179            WIRE_TYPE_LENGTH_DELIMITED | WIRE_TYPE_START_GROUP
1180        ) {
1181            options.forward_unknown_messages
1182        } else {
1183            options.forward_unknown_fields
1184        };
1185        if forward {
1186            validate_raw_field(u.number, u.wire_type, &u.encoded_value)?;
1187            ensure_output_growth(
1188                o.len(),
1189                minimal_varint_length(make_key(u.number, u.wire_type)),
1190                u.encoded_value.len(),
1191                options.max_output_bytes,
1192            )?;
1193            vi(make_key(u.number, u.wire_type), &mut o);
1194            o.extend_from_slice(&u.encoded_value)
1195        }
1196    }
1197    if options.forward_added_fields {
1198        for field in &m.added_fields {
1199            validate_raw_field(field.number, field.wire_type, &field.encoded_value)?;
1200            ensure_output_growth(
1201                o.len(),
1202                minimal_varint_length(make_key(field.number, field.wire_type)),
1203                field.encoded_value.len(),
1204                options.max_output_bytes,
1205            )?;
1206            vi(make_key(field.number, field.wire_type), &mut o);
1207            o.extend_from_slice(&field.encoded_value);
1208        }
1209    }
1210    for name in m.fields.keys() {
1211        if !s.fields_for(d).any(|field| field.name == *name) {
1212            audit.push(AuditRecord {
1213                tag: AuditTag::AddedField,
1214                field_name: Some(name.clone()),
1215                field_number: 0,
1216                wire_type: 0,
1217                encoded_field: Vec::new(),
1218            });
1219            if options.forward_added_fields {
1220                return Err(Error::new(
1221                    0,
1222                    "schema-absent named field needs raw wire metadata via Message::add_field",
1223                ));
1224            }
1225        }
1226    }
1227    apply_field_order(&mut o, options.field_order)?;
1228    if o.len() > options.max_output_bytes {
1229        return Err(Error::new(
1230            0,
1231            "encoded message exceeds configured size limit",
1232        ));
1233    }
1234    Ok(EncodeOutput { bytes: o, audit })
1235}
1236
1237/// Applies the requested stable ordering to complete encoded occurrences.
1238///
1239/// Sorting happens after forwarding filters are applied, so known, unknown,
1240/// application-added, and preserved duplicate fields participate uniformly.
1241fn apply_field_order(bytes: &mut Vec<u8>, order: FieldOrder) -> Result<()> {
1242    if order == FieldOrder::Declaration {
1243        return Ok(());
1244    }
1245    let mut cursor = 0;
1246    let mut occurrences = Vec::new();
1247    while cursor < bytes.len() {
1248        let start = cursor;
1249        let (number, wire_type) = read_key(bytes, &mut cursor)?;
1250        skip(number, wire_type, bytes, &mut cursor)?;
1251        occurrences.push((number, audit_bytes(bytes, start, cursor)?));
1252    }
1253    occurrences.sort_by_key(|(number, _)| *number);
1254    bytes.clear();
1255    for (_, occurrence) in occurrences {
1256        bytes.extend_from_slice(&occurrence);
1257    }
1258    Ok(())
1259}
1260/// Reports whether a value is a protobuf implicit-presence default.
1261fn is_default(value: &Value) -> bool {
1262    match value {
1263        Value::Double(value) => *value == 0.0,
1264        Value::Float(value) => *value == 0.0,
1265        Value::Int32(value) | Value::Enum(value) => *value == 0,
1266        Value::Int64(value) => *value == 0,
1267        Value::Uint32(value) => *value == 0,
1268        Value::Uint64(value) => *value == 0,
1269        Value::Bool(value) => !*value,
1270        Value::String(value) => value.is_empty(),
1271        Value::RawString(value) => value.is_empty(),
1272        Value::Bytes(value) => value.is_empty(),
1273        Value::Repeated(value) => value.is_empty(),
1274        Value::Map(value) => value.is_empty(),
1275        Value::Message(_) => false,
1276    }
1277}
1278
1279/// Applies protobuf's recursive merge rules to singular message occurrences.
1280fn merge_message(existing: &mut Message, mut incoming: Message) {
1281    for (name, value) in incoming.fields {
1282        match (existing.fields.get_mut(&name), value) {
1283            (Some(Value::Message(old)), Value::Message(new)) => merge_message(old, new),
1284            (Some(Value::Repeated(old)), Value::Repeated(mut new)) => old.append(&mut new),
1285            (Some(Value::Map(old)), Value::Map(new)) => {
1286                for (key, value) in new {
1287                    if let Some(entry) = old.iter_mut().find(|(candidate, _)| candidate == &key) {
1288                        entry.1 = value;
1289                    } else {
1290                        old.push((key, value));
1291                    }
1292                }
1293            }
1294            (_, value) => {
1295                existing.fields.insert(name, value);
1296            }
1297        }
1298    }
1299    existing.unknown_fields.append(&mut incoming.unknown_fields);
1300    existing.added_fields.append(&mut incoming.added_fields);
1301    existing.audit.append(&mut incoming.audit);
1302}
1303/// Borrows exactly `n` input bytes and advances the cursor after bounds checks.
1304fn take<'a>(b: &'a [u8], p: &mut usize, n: usize) -> Result<&'a [u8]> {
1305    let end = p
1306        .checked_add(n)
1307        .ok_or_else(|| Error::new(*p, "field length overflow"))?;
1308    let x = b
1309        .get(*p..end)
1310        .ok_or_else(|| Error::new(*p, "truncated field"))?;
1311    *p = end;
1312    Ok(x)
1313}
1314/// Reads an exact fixed-width value into an array without panicking on conversion.
1315fn fixed_bytes<const SIZE: usize>(b: &[u8], p: &mut usize) -> Result<[u8; SIZE]> {
1316    let start = *p;
1317    take(b, p, SIZE)?
1318        .try_into()
1319        .map_err(|_| Error::new(start, "invalid fixed-width field"))
1320}
1321
1322/// Copies a validated input range for an audit record.
1323fn audit_bytes(b: &[u8], start: usize, end: usize) -> Result<Vec<u8>> {
1324    b.get(start..end)
1325        .map(<[u8]>::to_vec)
1326        .ok_or_else(|| Error::new(start, "invalid audit byte range"))
1327}
1328
1329/// Shared counters and policies for one recursive decode operation.
1330struct DecodeContext<'a> {
1331    /// Caller-selected limits and strictness policies.
1332    options: &'a DecodeOptions,
1333    /// Total wire occurrences observed across root and embedded messages.
1334    field_occurrences: usize,
1335    /// Total original wire bytes copied into full audit records.
1336    audit_bytes: usize,
1337}
1338
1339impl DecodeContext<'_> {
1340    /// Accounts for one field occurrence before decoding its value.
1341    fn count_field(&mut self, offset: usize) -> Result<()> {
1342        self.field_occurrences = self
1343            .field_occurrences
1344            .checked_add(1)
1345            .ok_or_else(|| Error::new(offset, "field occurrence counter overflow"))?;
1346        if self.field_occurrences > self.options.max_field_occurrences {
1347            return Err(Error::new(
1348                offset,
1349                "message exceeds configured field occurrence limit",
1350            ));
1351        }
1352        Ok(())
1353    }
1354
1355    /// Reads a scalar, key, or length varint under the configured strictness.
1356    fn varint(&self, bytes: &[u8], cursor: &mut usize) -> Result<u64> {
1357        read_varint(bytes, cursor, self.options.require_minimal_varints)
1358    }
1359
1360    /// Reads a checked platform-sized length and applies its payload limit.
1361    fn length(&self, bytes: &[u8], cursor: &mut usize) -> Result<usize> {
1362        let offset = *cursor;
1363        let length = usize::try_from(self.varint(bytes, cursor)?)
1364            .map_err(|_| Error::new(offset, "length does not fit this target"))?;
1365        if length > self.options.max_length_delimited_bytes {
1366            return Err(Error::new(
1367                offset,
1368                "length-delimited value exceeds configured size limit",
1369            ));
1370        }
1371        Ok(length)
1372    }
1373
1374    /// Creates an audit record while enforcing byte-retention limits.
1375    fn audit_record(
1376        &mut self,
1377        bytes: &[u8],
1378        range: Range<usize>,
1379        mut record: AuditRecord,
1380    ) -> Result<AuditRecord> {
1381        let encoded_field = if self.options.audit_mode == AuditMode::Full {
1382            let length = range
1383                .end
1384                .checked_sub(range.start)
1385                .ok_or_else(|| Error::new(range.start, "audit cursor moved backwards"))?;
1386            self.audit_bytes = self
1387                .audit_bytes
1388                .checked_add(length)
1389                .ok_or_else(|| Error::new(range.start, "audit byte counter overflow"))?;
1390            if self.audit_bytes > self.options.max_audit_bytes {
1391                return Err(Error::new(
1392                    range.start,
1393                    "message exceeds configured audit byte limit",
1394                ));
1395            }
1396            audit_bytes(bytes, range.start, range.end)?
1397        } else {
1398            Vec::new()
1399        };
1400        record.encoded_field = encoded_field;
1401        Ok(record)
1402    }
1403}
1404
1405/// Decodes one descriptor-known scalar or embedded-message value.
1406///
1407/// The function checks that the encountered wire type matches the schema and
1408/// advances `p` past the decoded value.
1409fn val(
1410    t: &FieldType,
1411    w: u8,
1412    b: &[u8],
1413    p: &mut usize,
1414    s: &Schema,
1415    context: &mut DecodeContext<'_>,
1416    depth: usize,
1417) -> Result<Value> {
1418    if w != wire(t) {
1419        return Err(Error::new(*p, "wrong wire type"));
1420    }
1421    Ok(match t {
1422        FieldType::Double => Value::Double(f64::from_le_bytes(fixed_bytes::<FIXED64_SIZE>(b, p)?)),
1423        FieldType::Float => Value::Float(f32::from_le_bytes(fixed_bytes::<FIXED32_SIZE>(b, p)?)),
1424        FieldType::Int32 => {
1425            let raw = context.varint(b, p)?;
1426            let value = raw as i32;
1427            require_canonical_32_bit_varint(raw, value as i64 as u64, *p, context)?;
1428            Value::Int32(value)
1429        }
1430        FieldType::Int64 => Value::Int64(context.varint(b, p)? as i64),
1431        FieldType::Uint32 => {
1432            let raw = context.varint(b, p)?;
1433            let value = raw as u32;
1434            require_canonical_32_bit_varint(raw, u64::from(value), *p, context)?;
1435            Value::Uint32(value)
1436        }
1437        FieldType::Uint64 => Value::Uint64(context.varint(b, p)?),
1438        FieldType::Sint32 => {
1439            let raw = context.varint(b, p)?;
1440            let n = raw as u32;
1441            require_canonical_32_bit_varint(raw, u64::from(n), *p, context)?;
1442            Value::Int32((n >> 1) as i32 ^ -((n & 1) as i32))
1443        }
1444        FieldType::Sint64 => {
1445            let n = context.varint(b, p)?;
1446            Value::Int64((n >> 1) as i64 ^ -((n & 1) as i64))
1447        }
1448        FieldType::Fixed32 => Value::Uint32(u32::from_le_bytes(fixed_bytes::<FIXED32_SIZE>(b, p)?)),
1449        FieldType::Fixed64 => Value::Uint64(u64::from_le_bytes(fixed_bytes::<FIXED64_SIZE>(b, p)?)),
1450        FieldType::Sfixed32 => Value::Int32(i32::from_le_bytes(fixed_bytes::<FIXED32_SIZE>(b, p)?)),
1451        FieldType::Sfixed64 => Value::Int64(i64::from_le_bytes(fixed_bytes::<FIXED64_SIZE>(b, p)?)),
1452        FieldType::Bool => {
1453            let raw = context.varint(b, p)?;
1454            if raw > 1 && context.options.booleans == BooleanValuePolicy::RejectNonCanonical {
1455                return Err(Error::new(*p, "non-canonical boolean value"));
1456            }
1457            Value::Bool(raw != 0)
1458        }
1459        FieldType::Enum(name) => {
1460            let raw = context.varint(b, p)?;
1461            let value = raw as i32;
1462            require_canonical_32_bit_varint(raw, value as i64 as u64, *p, context)?;
1463            if context.options.enum_values == EnumValuePolicy::RejectUnknown
1464                && !s.enums.get(name).is_some_and(|enumeration| {
1465                    enumeration
1466                        .values
1467                        .iter()
1468                        .any(|candidate| candidate.number == value)
1469                })
1470            {
1471                return Err(Error::new(*p, "unknown enum value rejected by policy"));
1472            }
1473            Value::Enum(value)
1474        }
1475        FieldType::String => {
1476            let n = context.length(b, p)?;
1477            Value::String(
1478                core::str::from_utf8(take(b, p, n)?)
1479                    .map_err(|_| Error::new(*p, "invalid UTF-8"))?
1480                    .to_string(),
1481            )
1482        }
1483        FieldType::Bytes => {
1484            let n = context.length(b, p)?;
1485            Value::Bytes(take(b, p, n)?.to_vec())
1486        }
1487        FieldType::Message(n) => {
1488            let z = context.length(b, p)?;
1489            let q = take(b, p, z)?;
1490            Value::Message(decode_inner(
1491                s,
1492                s.message(n)
1493                    .ok_or_else(|| Error::new(*p, "unknown message type"))?,
1494                q,
1495                context,
1496                depth
1497                    .checked_add(1)
1498                    .ok_or_else(|| Error::new(*p, "recursion depth overflow"))?,
1499            )?)
1500        }
1501        FieldType::Map(..) => return Err(Error::new(*p, "map codec not yet supported")),
1502    })
1503}
1504
1505/// Locates a matching group terminator and returns its body without decoding it.
1506fn delimited_message_body<'a>(
1507    field_number: u32,
1508    bytes: &'a [u8],
1509    cursor: &mut usize,
1510) -> Result<&'a [u8]> {
1511    let body_start = *cursor;
1512    let mut scan = *cursor;
1513    loop {
1514        if scan == bytes.len() {
1515            return Err(Error::new(scan, "unterminated delimited message"));
1516        }
1517        let tag_start = scan;
1518        let (nested_number, nested_wire_type) = read_key(bytes, &mut scan)?;
1519        if nested_wire_type == WIRE_TYPE_END_GROUP {
1520            if nested_number != field_number {
1521                return Err(Error::new(scan, "mismatched delimited message terminator"));
1522            }
1523            *cursor = scan;
1524            return bytes
1525                .get(body_start..tag_start)
1526                .ok_or_else(|| Error::new(body_start, "invalid delimited message bounds"));
1527        }
1528        skip(nested_number, nested_wire_type, bytes, &mut scan)?;
1529    }
1530}
1531
1532/// Decodes one field while honoring its resolved message-encoding feature.
1533fn field_value(
1534    field: &Field,
1535    wire_type: u8,
1536    bytes: &[u8],
1537    cursor: &mut usize,
1538    schema: &Schema,
1539    context: &mut DecodeContext<'_>,
1540    depth: usize,
1541) -> Result<Value> {
1542    if matches!(field.kind, FieldType::String)
1543        && field.features.utf8_validation == Utf8Validation::None
1544    {
1545        if wire_type != WIRE_TYPE_LENGTH_DELIMITED {
1546            return Err(Error::new(*cursor, "string has wrong wire type"));
1547        }
1548        let length = context.length(bytes, cursor)?;
1549        return Ok(Value::RawString(take(bytes, cursor, length)?.to_vec()));
1550    }
1551    if field.features.message_encoding != MessageEncoding::Delimited
1552        || !matches!(field.kind, FieldType::Message(_))
1553    {
1554        return val(
1555            &field.kind,
1556            wire_type,
1557            bytes,
1558            cursor,
1559            schema,
1560            context,
1561            depth,
1562        );
1563    }
1564    let FieldType::Message(name) = &field.kind else {
1565        return Err(Error::new(
1566            *cursor,
1567            "DELIMITED message encoding requires a message field",
1568        ));
1569    };
1570    if wire_type != WIRE_TYPE_START_GROUP {
1571        return Err(Error::new(*cursor, "delimited message has wrong wire type"));
1572    }
1573    let body = delimited_message_body(field.number, bytes, cursor)?;
1574    let nested = schema
1575        .message(name)
1576        .ok_or_else(|| Error::new(*cursor, "unknown message type"))?;
1577    let nested_depth = depth
1578        .checked_add(1)
1579        .ok_or_else(|| Error::new(*cursor, "recursion depth overflow"))?;
1580    Ok(Value::Message(decode_inner(
1581        schema,
1582        nested,
1583        body,
1584        context,
1585        nested_depth,
1586    )?))
1587}
1588
1589/// Rejects lossy 64-to-32-bit varint truncation in strict decoding mode.
1590fn require_canonical_32_bit_varint(
1591    raw: u64,
1592    canonical: u64,
1593    offset: usize,
1594    context: &DecodeContext<'_>,
1595) -> Result<()> {
1596    if context.options.require_minimal_varints && raw != canonical {
1597        return Err(Error::new(offset, "non-canonical 32-bit varint value"));
1598    }
1599    Ok(())
1600}
1601
1602/// Constructs the protobuf default value for a map-entry component type.
1603fn default_value(t: &FieldType) -> Result<Value> {
1604    Ok(match t {
1605        FieldType::Double => Value::Double(0.0),
1606        FieldType::Float => Value::Float(0.0),
1607        FieldType::Int32 | FieldType::Sint32 | FieldType::Sfixed32 => Value::Int32(0),
1608        FieldType::Int64 | FieldType::Sint64 | FieldType::Sfixed64 => Value::Int64(0),
1609        FieldType::Uint32 | FieldType::Fixed32 => Value::Uint32(0),
1610        FieldType::Uint64 | FieldType::Fixed64 => Value::Uint64(0),
1611        FieldType::Bool => Value::Bool(false),
1612        FieldType::String => Value::String(String::new()),
1613        FieldType::Bytes => Value::Bytes(Vec::new()),
1614        FieldType::Enum(_) => Value::Enum(0),
1615        FieldType::Message(_) => Value::Message(Message::new()),
1616        FieldType::Map(..) => return Err(Error::new(0, "a map cannot be a map value")),
1617    })
1618}
1619
1620/// Decodes one length-delimited synthetic map-entry message.
1621///
1622/// Missing key or value components receive their protobuf defaults. Unknown
1623/// entry fields are skipped without escaping the declared entry boundary.
1624fn decode_map_entry(
1625    key_type: &FieldType,
1626    value_type: &FieldType,
1627    b: &[u8],
1628    p: &mut usize,
1629    s: &Schema,
1630    context: &mut DecodeContext<'_>,
1631    depth: usize,
1632) -> Result<(Value, Value)> {
1633    let length = context.length(b, p)?;
1634    let entry = take(b, p, length)?;
1635    let mut cursor = 0;
1636    let mut key = None;
1637    let mut value = None;
1638    while cursor < entry.len() {
1639        context.count_field(cursor)?;
1640        let tag = context.varint(entry, &mut cursor)?;
1641        match tag >> FIELD_NUMBER_SHIFT {
1642            field if field == u64::from(MAP_KEY_FIELD_NUMBER) => {
1643                if key.is_some() && context.options.duplicates == DuplicateInputPolicy::Reject {
1644                    return Err(Error::new(
1645                        cursor,
1646                        "duplicate map-entry key rejected by policy",
1647                    ));
1648                }
1649                key = Some(val(
1650                    key_type,
1651                    (tag & WIRE_TYPE_MASK) as u8,
1652                    entry,
1653                    &mut cursor,
1654                    s,
1655                    context,
1656                    depth,
1657                )?)
1658            }
1659            field if field == u64::from(MAP_VALUE_FIELD_NUMBER) => {
1660                if value.is_some() && context.options.duplicates == DuplicateInputPolicy::Reject {
1661                    return Err(Error::new(
1662                        cursor,
1663                        "duplicate map-entry value rejected by policy",
1664                    ));
1665                }
1666                value = Some(val(
1667                    value_type,
1668                    (tag & WIRE_TYPE_MASK) as u8,
1669                    entry,
1670                    &mut cursor,
1671                    s,
1672                    context,
1673                    depth,
1674                )?)
1675            }
1676            _ => {
1677                skip_decode(
1678                    tag as u32 >> FIELD_NUMBER_SHIFT,
1679                    (tag & WIRE_TYPE_MASK) as u8,
1680                    entry,
1681                    &mut cursor,
1682                    context,
1683                    depth,
1684                )?;
1685            }
1686        }
1687    }
1688    Ok((
1689        key.unwrap_or(default_value(key_type)?),
1690        value.unwrap_or(default_value(value_type)?),
1691    ))
1692}
1693/// Skips one unknown wire value and returns its exact encoded value bytes.
1694///
1695/// The returned bytes exclude the already-consumed field key. Groups include
1696/// their matching end tag so an unknown occurrence can be forwarded exactly.
1697fn skip(field_number: u32, w: u8, b: &[u8], p: &mut usize) -> Result<Vec<u8>> {
1698    let s = *p;
1699    match w {
1700        WIRE_TYPE_VARINT => {
1701            rv(b, p)?;
1702        }
1703        WIRE_TYPE_FIXED64 => {
1704            take(b, p, FIXED64_SIZE)?;
1705        }
1706        WIRE_TYPE_LENGTH_DELIMITED => {
1707            let offset = *p;
1708            let n = usize::try_from(rv(b, p)?)
1709                .map_err(|_| Error::new(offset, "length does not fit this target"))?;
1710            take(b, p, n)?;
1711        }
1712        WIRE_TYPE_FIXED32 => {
1713            take(b, p, FIXED32_SIZE)?;
1714        }
1715        WIRE_TYPE_START_GROUP => loop {
1716            if *p == b.len() {
1717                return Err(Error::new(*p, "unterminated group"));
1718            }
1719            let (nested_number, nested_wire_type) = read_key(b, p)?;
1720            if nested_wire_type == WIRE_TYPE_END_GROUP {
1721                if nested_number != field_number {
1722                    return Err(Error::new(*p, "mismatched end-group field number"));
1723                }
1724                break;
1725            }
1726            skip(nested_number, nested_wire_type, b, p)?;
1727        },
1728        WIRE_TYPE_END_GROUP => return Err(Error::new(*p, "unexpected end-group tag")),
1729        _ => return Err(Error::new(*p, "unsupported wire type")),
1730    }
1731    audit_bytes(b, s, *p)
1732}
1733
1734/// Skips one unknown value under decode length and varint policies.
1735fn skip_decode(
1736    field_number: u32,
1737    wire_type: u8,
1738    bytes: &[u8],
1739    cursor: &mut usize,
1740    context: &mut DecodeContext<'_>,
1741    depth: usize,
1742) -> Result<Vec<u8>> {
1743    let start = *cursor;
1744    match wire_type {
1745        WIRE_TYPE_VARINT => {
1746            context.varint(bytes, cursor)?;
1747        }
1748        WIRE_TYPE_FIXED64 => {
1749            take(bytes, cursor, FIXED64_SIZE)?;
1750        }
1751        WIRE_TYPE_LENGTH_DELIMITED => {
1752            let length = context.length(bytes, cursor)?;
1753            take(bytes, cursor, length)?;
1754        }
1755        WIRE_TYPE_FIXED32 => {
1756            take(bytes, cursor, FIXED32_SIZE)?;
1757        }
1758        WIRE_TYPE_START_GROUP => {
1759            let nested_depth = depth
1760                .checked_add(1)
1761                .ok_or_else(|| Error::new(*cursor, "recursion depth overflow"))?;
1762            if nested_depth > context.options.max_recursion_depth {
1763                return Err(Error::new(
1764                    *cursor,
1765                    "group exceeds configured recursion limit",
1766                ));
1767            }
1768            loop {
1769                if *cursor == bytes.len() {
1770                    return Err(Error::new(*cursor, "unterminated group"));
1771                }
1772                let field_start = *cursor;
1773                context.count_field(field_start)?;
1774                let (nested_number, nested_wire_type) =
1775                    read_key_with_policy(bytes, cursor, context.options.require_minimal_varints)?;
1776                if nested_wire_type == WIRE_TYPE_END_GROUP {
1777                    if nested_number != field_number {
1778                        return Err(Error::new(*cursor, "mismatched end-group field number"));
1779                    }
1780                    break;
1781                }
1782                skip_decode(
1783                    nested_number,
1784                    nested_wire_type,
1785                    bytes,
1786                    cursor,
1787                    context,
1788                    nested_depth,
1789                )?;
1790            }
1791        }
1792        WIRE_TYPE_END_GROUP => return Err(Error::new(*cursor, "unexpected end-group tag")),
1793        _ => return Err(Error::new(*cursor, "unsupported wire type")),
1794    }
1795    audit_bytes(bytes, start, *cursor)
1796}
1797/// Decodes protobuf binary bytes into a descriptor-driven dynamic message.
1798///
1799/// Unknown fields, duplicate occurrences, and schema-known occurrences are
1800/// retained in the message's audit data according to protobuf merge rules.
1801///
1802/// # Errors
1803///
1804/// Returns an error for malformed wire data, type mismatches, unsupported
1805/// group wire types, unresolved nested descriptors, or missing required fields.
1806pub fn decode(s: &Schema, d: &MessageDescriptor, b: &[u8]) -> Result<Message> {
1807    decode_with_options(s, d, b, &DecodeOptions::default())
1808}
1809
1810/// Decodes wire bytes while applying explicit resource and sanitization rules.
1811///
1812/// # Errors
1813///
1814/// Returns the same structural errors as [`decode`], plus errors selected by
1815/// resource limits, strict minimal-varint validation, unknown-field rejection,
1816/// or duplicate rejection.
1817pub fn decode_with_options(
1818    schema: &Schema,
1819    descriptor: &MessageDescriptor,
1820    bytes: &[u8],
1821    options: &DecodeOptions,
1822) -> Result<Message> {
1823    let mut context = DecodeContext {
1824        options,
1825        field_occurrences: 0,
1826        audit_bytes: 0,
1827    };
1828    decode_inner(schema, descriptor, bytes, &mut context, 0)
1829}
1830
1831/// Recursively decodes one descriptor-bounded message with shared counters.
1832fn decode_inner(
1833    s: &Schema,
1834    d: &MessageDescriptor,
1835    b: &[u8],
1836    context: &mut DecodeContext<'_>,
1837    depth: usize,
1838) -> Result<Message> {
1839    if depth > context.options.max_recursion_depth {
1840        return Err(Error::new(0, "message exceeds configured recursion limit"));
1841    }
1842    if b.len() > context.options.max_message_bytes {
1843        return Err(Error::new(0, "message exceeds configured input size limit"));
1844    }
1845    let (mut m, mut p) = (Message::new(), 0);
1846    while p < b.len() {
1847        let field_start = p;
1848        context.count_field(field_start)?;
1849        let (n, w) = read_key_with_policy(b, &mut p, context.options.require_minimal_varints)?;
1850        let Some(f) = s.field_by_number(d, n) else {
1851            let encoded_value = skip_decode(n, w, b, &mut p, context, depth)?;
1852            if context.options.unknown_fields == UnknownFieldPolicy::Reject {
1853                return Err(Error::new(field_start, "unknown field rejected by policy"));
1854            }
1855            if context.options.unknown_fields == UnknownFieldPolicy::Preserve {
1856                m.unknown_fields.push(UnknownField {
1857                    number: n,
1858                    wire_type: w,
1859                    encoded_value,
1860                });
1861            }
1862            let tag = if matches!(w, WIRE_TYPE_LENGTH_DELIMITED | WIRE_TYPE_START_GROUP) {
1863                AuditTag::UnknownMessage
1864            } else {
1865                AuditTag::UnknownField
1866            };
1867            let record = context.audit_record(
1868                b,
1869                field_start..p,
1870                AuditRecord {
1871                    tag,
1872                    field_name: None,
1873                    field_number: n,
1874                    wire_type: w,
1875                    encoded_field: Vec::new(),
1876                },
1877            )?;
1878            m.audit.push(record);
1879            continue;
1880        };
1881        if let FieldType::Map(key_type, value_type) = &f.kind {
1882            if w != WIRE_TYPE_LENGTH_DELIMITED {
1883                return Err(Error::new(p, "map field has wrong wire type"));
1884            }
1885            let (key, value) =
1886                decode_map_entry(key_type, value_type, b, &mut p, s, context, depth)?;
1887            let mut entries = match m.fields.remove(&f.name) {
1888                Some(Value::Map(entries)) => entries,
1889                _ => Vec::new(),
1890            };
1891            // The protobuf map wire format permits duplicate keys; the last
1892            // occurrence wins, matching generated protobuf implementations.
1893            let duplicate = entries.iter().any(|(candidate, _)| candidate == &key);
1894            if duplicate && context.options.duplicates == DuplicateInputPolicy::Reject {
1895                return Err(Error::new(
1896                    field_start,
1897                    "duplicate map key rejected by policy",
1898                ));
1899            }
1900            if let Some(existing) = entries.iter_mut().find(|(candidate, _)| candidate == &key) {
1901                existing.1 = value;
1902            } else {
1903                if entries.len() >= context.options.max_map_entries {
1904                    return Err(Error::new(
1905                        field_start,
1906                        "map exceeds configured entry limit",
1907                    ));
1908                }
1909                entries.push((key, value));
1910            }
1911            m.insert(f.name.clone(), Value::Map(entries));
1912            if duplicate
1913                && let Some(previous) = m.audit.iter_mut().rev().find(|record| {
1914                    record.field_name.as_deref() == Some(&f.name)
1915                        && matches!(
1916                            record.tag,
1917                            AuditTag::SchemaField | AuditTag::DuplicateLastWins
1918                        )
1919                })
1920            {
1921                previous.tag = AuditTag::DuplicateDiscarded;
1922            }
1923            let tag = if duplicate {
1924                AuditTag::DuplicateLastWins
1925            } else {
1926                AuditTag::SchemaField
1927            };
1928            let record = context.audit_record(
1929                b,
1930                field_start..p,
1931                AuditRecord {
1932                    tag,
1933                    field_name: Some(f.name.clone()),
1934                    field_number: n,
1935                    wire_type: w,
1936                    encoded_field: Vec::new(),
1937                },
1938            )?;
1939            m.audit.push(record);
1940            continue;
1941        }
1942        if let FieldType::Enum(name) = &f.kind
1943            && w == WIRE_TYPE_VARINT
1944            && s.enums
1945                .get(name)
1946                .is_some_and(|enumeration| enumeration.features.enum_type == EnumType::Closed)
1947        {
1948            let value_start = p;
1949            let raw = context.varint(b, &mut p)?;
1950            let value = raw as i32;
1951            require_canonical_32_bit_varint(raw, value as i64 as u64, p, context)?;
1952            let known = s.enums.get(name).is_some_and(|enumeration| {
1953                enumeration
1954                    .values
1955                    .iter()
1956                    .any(|candidate| candidate.number == value)
1957            });
1958            if !known {
1959                if context.options.unknown_fields == UnknownFieldPolicy::Reject {
1960                    return Err(Error::new(field_start, "closed enum value is unknown"));
1961                }
1962                if context.options.unknown_fields == UnknownFieldPolicy::Preserve {
1963                    m.unknown_fields.push(UnknownField {
1964                        number: f.number,
1965                        wire_type: w,
1966                        encoded_value: audit_bytes(b, value_start, p)?,
1967                    });
1968                }
1969                let record = context.audit_record(
1970                    b,
1971                    field_start..p,
1972                    AuditRecord {
1973                        tag: AuditTag::UnknownField,
1974                        field_name: Some(f.name.clone()),
1975                        field_number: n,
1976                        wire_type: w,
1977                        encoded_field: Vec::new(),
1978                    },
1979                )?;
1980                m.audit.push(record);
1981                continue;
1982            }
1983            p = value_start;
1984        }
1985        let repeated = f.cardinality == Cardinality::Repeated;
1986        let duplicate = !repeated
1987            && (m.fields.contains_key(&f.name)
1988                || f.oneof.as_ref().is_some_and(|group| {
1989                    d.fields.iter().any(|candidate| {
1990                        candidate.oneof.as_ref() == Some(group)
1991                            && m.fields.contains_key(&candidate.name)
1992                    })
1993                }));
1994        if duplicate && context.options.duplicates == DuplicateInputPolicy::Reject {
1995            return Err(Error::new(
1996                field_start,
1997                "duplicate singular field rejected by policy",
1998            ));
1999        }
2000        let mut xs = if repeated {
2001            match m.fields.remove(&f.name) {
2002                Some(Value::Repeated(x)) => x,
2003                _ => Vec::new(),
2004            }
2005        } else {
2006            Vec::new()
2007        };
2008        if repeated
2009            && w == WIRE_TYPE_LENGTH_DELIMITED
2010            && wire(&f.kind) != WIRE_TYPE_LENGTH_DELIMITED
2011        {
2012            let length = context.length(b, &mut p)?;
2013            let packed = take(b, &mut p, length)?;
2014            let mut packed_cursor = 0;
2015            while packed_cursor < packed.len() {
2016                if xs.len() >= context.options.max_repeated_values {
2017                    return Err(Error::new(
2018                        field_start,
2019                        "repeated field exceeds configured value limit",
2020                    ));
2021                }
2022                let value = val(
2023                    &f.kind,
2024                    wire(&f.kind),
2025                    packed,
2026                    &mut packed_cursor,
2027                    s,
2028                    context,
2029                    depth,
2030                )?;
2031                if let (FieldType::Enum(name), Value::Enum(number)) = (&f.kind, &value)
2032                    && s.enums.get(name).is_some_and(|enumeration| {
2033                        enumeration.features.enum_type == EnumType::Closed
2034                            && !enumeration
2035                                .values
2036                                .iter()
2037                                .any(|candidate| candidate.number == *number)
2038                    })
2039                {
2040                    if context.options.unknown_fields == UnknownFieldPolicy::Reject {
2041                        return Err(Error::new(field_start, "closed enum value is unknown"));
2042                    }
2043                    if context.options.unknown_fields == UnknownFieldPolicy::Preserve {
2044                        let mut encoded_value = Vec::new();
2045                        vi(*number as i64 as u64, &mut encoded_value);
2046                        m.unknown_fields.push(UnknownField {
2047                            number: f.number,
2048                            wire_type: WIRE_TYPE_VARINT,
2049                            encoded_value,
2050                        });
2051                    }
2052                } else {
2053                    xs.push(value);
2054                }
2055            }
2056            m.insert(f.name.clone(), Value::Repeated(xs));
2057            let record = context.audit_record(
2058                b,
2059                field_start..p,
2060                AuditRecord {
2061                    tag: AuditTag::SchemaField,
2062                    field_name: Some(f.name.clone()),
2063                    field_number: n,
2064                    wire_type: w,
2065                    encoded_field: Vec::new(),
2066                },
2067            )?;
2068            m.audit.push(record);
2069            continue;
2070        }
2071        let x = field_value(f, w, b, &mut p, s, context, depth)?;
2072        let mut merged = false;
2073        if repeated {
2074            if xs.len() >= context.options.max_repeated_values {
2075                return Err(Error::new(
2076                    field_start,
2077                    "repeated field exceeds configured value limit",
2078                ));
2079            }
2080            xs.push(x);
2081            m.insert(f.name.clone(), Value::Repeated(xs));
2082        } else {
2083            if let Some(g) = &f.oneof {
2084                for q in &d.fields {
2085                    if q.oneof.as_ref() == Some(g) && q.name != f.name {
2086                        m.fields.remove(&q.name);
2087                    }
2088                }
2089            }
2090            merged = duplicate && matches!(x, Value::Message(_));
2091            match x {
2092                Value::Message(incoming) => {
2093                    if let Some(Value::Message(existing)) = m.fields.get_mut(&f.name) {
2094                        merge_message(existing, incoming);
2095                    } else {
2096                        m.insert(f.name.clone(), Value::Message(incoming));
2097                    }
2098                }
2099                value => {
2100                    m.insert(f.name.clone(), value);
2101                }
2102            }
2103        }
2104        if duplicate
2105            && !merged
2106            && let Some(previous) = m.audit.iter_mut().rev().find(|record| {
2107                let same_field = record.field_name.as_deref() == Some(&f.name);
2108                let same_oneof = f.oneof.as_ref().is_some_and(|group| {
2109                    record.field_name.as_deref().is_some_and(|name| {
2110                        d.field_by_name(name).and_then(|field| field.oneof.as_ref()) == Some(group)
2111                    })
2112                });
2113                (same_field || same_oneof)
2114                    && matches!(
2115                        record.tag,
2116                        AuditTag::SchemaField | AuditTag::DuplicateLastWins
2117                    )
2118            })
2119        {
2120            previous.tag = AuditTag::DuplicateDiscarded;
2121        }
2122        let tag = if repeated || !duplicate {
2123            AuditTag::SchemaField
2124        } else if merged {
2125            AuditTag::DuplicateMerged
2126        } else {
2127            AuditTag::DuplicateLastWins
2128        };
2129        let record = context.audit_record(
2130            b,
2131            field_start..p,
2132            AuditRecord {
2133                tag,
2134                field_name: Some(f.name.clone()),
2135                field_number: n,
2136                wire_type: w,
2137                encoded_field: Vec::new(),
2138            },
2139        )?;
2140        m.audit.push(record);
2141    }
2142    for f in s.fields_for(d) {
2143        if (f.cardinality == Cardinality::Required
2144            || f.features.field_presence == FieldPresence::LegacyRequired)
2145            && !m.fields.contains_key(&f.name)
2146        {
2147            return Err(Error::new(0, "missing required field"));
2148        }
2149    }
2150    Ok(m)
2151}