Skip to main content

buffa/
json.rs

1//! JSON parse options for protobuf JSON deserialization.
2//!
3//! The protobuf JSON spec says parsers should reject unknown fields by default
4//! but **may provide an option** to ignore them. This module exposes that
5//! option, matching the per-call semantics of C++ and Java reference
6//! implementations.
7//!
8//! The options here are runtime ones: unknown enum *values*
9//! ([`JsonParseOptions::ignore_unknown_enum_values`]), unregistered
10//! extension keys ([`JsonParseOptions::strict_extension_keys`]) and
11//! `google.protobuf.Any` `@type` values without a `/`
12//! ([`JsonParseOptions::strict_any_type_urls`]). Unknown
13//! *field names* are not governed here: generated deserializers ignore them
14//! unless the code was generated with
15//! `buffa_build::Config::deny_unknown_json_fields` (or its path-scoped
16//! `deny_unknown_json_fields_in`).
17//!
18//! # Two mutually exclusive APIs: scoped (std) vs global (no_std)
19//!
20//! Serde's `Deserialize` trait has no context parameter, so runtime options
21//! must be passed through ambient state. The available mechanism differs
22//! between `std` and `no_std` builds — each build exposes exactly one:
23//!
24//! | Build | Mechanism | API | Scoping |
25//! |---|---|---|---|
26//! | `std` | Thread-local | `with_json_parse_options` | Per-closure, nestable, per-thread |
27//! | `no_std` | `AtomicPtr` to leaked `Box` | `set_global_json_parse_options` | Process-wide, set-once |
28//!
29//! The two APIs do not interact. `set_global_json_parse_options` is only
30//! compiled in `no_std` builds; `with_json_parse_options` only in `std`.
31//!
32//! ## `std`: scoped per-closure options
33//!
34//! ```ignore
35//! use buffa::json::{JsonParseOptions, with_json_parse_options};
36//!
37//! let opts = JsonParseOptions::new().ignore_unknown_enum_values(true);
38//! let msg = with_json_parse_options(&opts, || {
39//!     serde_json::from_str::<MyMessage>(json_str)
40//! });
41//! // Options revert to defaults here. Concurrent threads are independent.
42//! ```
43//!
44//! ## `no_std`: global set-once options
45//!
46//! ```ignore
47//! use buffa::json::{JsonParseOptions, set_global_json_parse_options};
48//!
49//! // Call ONCE during startup (e.g. in your init function).
50//! set_global_json_parse_options(
51//!     &JsonParseOptions::new().ignore_unknown_enum_values(true)
52//! );
53//!
54//! // All subsequent JSON deserialization uses these options.
55//! let msg: MyMessage = serde_json::from_str(json_str)?;
56//! ```
57//!
58//! The global setter is **idempotent for identical options** — calling it
59//! multiple times with the same configuration is a no-op, so initialization
60//! from multiple modules is safe as long as they agree. Calling it with
61//! *different* options after the first call triggers a `debug_assert!` (panic
62//! in debug builds; the second call is silently ignored in release). Treat the
63//! first successful call as locking in behaviour for the process lifetime.
64//!
65//! # What `ignore_unknown_enum_values` changes for each kind of field
66//!
67//! The option covers enum values that the enum does not declare. With the
68//! option set, a generated message type handles such a value as the table
69//! says, in `std` and `no_std` builds alike unless a cell names the build:
70//!
71//! | Field | Unknown name | Undeclared number, closed enum |
72//! |---|---|---|
73//! | implicit presence, or `required` | default value (0 for an open enum) | parse error |
74//! | explicit presence (the Rust type is `Option`) | left unset | left unset |
75//! | `repeated` or `map` | element or entry dropped | element or entry dropped |
76//! | `oneof` member, open enum | member set, with value 0 (`std`); parse error (`no_std`) | does not apply |
77//! | `oneof` member, closed enum | parse error | parse error |
78//! | extension | parse error | kept |
79//!
80//! An undeclared number is an integer in the `i32` range that the enum does
81//! not declare. An open enum keeps one as
82//! [`EnumValue::Unknown`](crate::EnumValue::Unknown) in every kind of field.
83//! With the option off, each cell is a parse error, and an extension still
84//! keeps the number.
85//!
86//! A value that cannot be an enum value is a parse error in every kind of
87//! field, with the option on or off. Such a value is a bool, an object, an
88//! array, a number written with a fraction or an exponent (such as `1.0`), or
89//! an integer outside the `i32` range. A `null` element of a repeated closed
90//! enum field, or a null value in a closed enum map, is a parse error in both
91//! modes. For open enums, it is read as the enum's default value.
92//!
93//! The option applies to generated message types. JSON parsing of a
94//! `DynamicMessage` in `buffa-descriptor` does not read the option, and an
95//! unknown enum name is a parse error there.
96
97/// Options controlling protobuf JSON parsing behavior.
98///
99/// Use [`JsonParseOptions::new`] plus builder methods to construct:
100///
101/// ```
102/// # use buffa::json::JsonParseOptions;
103/// let opts = JsonParseOptions::new().ignore_unknown_enum_values(true);
104/// # assert!(opts.ignore_unknown_enum_values);
105/// ```
106#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
107#[non_exhaustive]
108pub struct JsonParseOptions {
109    /// When `true`, an enum name that the enum does not declare is replaced
110    /// with the default value, left unset, or dropped, depending on the kind
111    /// of field. In an `optional`, `repeated` or `map` field of a closed
112    /// enum, a number in the `i32` range that the enum does not declare is
113    /// left unset or dropped too. A value that cannot be an enum value, such
114    /// as a bool or `1.5`, is a parse error with the option on or off. See
115    /// the [module docs](self) for each kind of field. Default: `false`.
116    pub ignore_unknown_enum_values: bool,
117    /// When `true`, `"[pkg.ext]"` JSON keys that are not in the extension
118    /// registry produce a parse error instead of being silently dropped.
119    ///
120    /// The default (`false`, lenient) matches the pre-extension-registry
121    /// behavior where all unknown keys were dropped by serde's derive.
122    /// protobuf-go (`protojson/decode.go:175`) and protobuf-es
123    /// (`from-json.ts:251`) both error on unregistered extension keys unless
124    /// their respective ignore-unknown flags are set; set `true` here to
125    /// match. The error pinpoints the missing registration.
126    ///
127    /// Extendee mismatch (key IS registered but extends a different message)
128    /// always errors regardless of this flag — that's a contract violation,
129    /// not a mere miss.
130    ///
131    /// This flag covers `"[pkg.ext]"` keys only, and only for messages that
132    /// preserve unknown fields. Ordinary unknown field names are governed by
133    /// the codegen option `buffa_build::Config::deny_unknown_json_fields`,
134    /// which also rejects `"[pkg.ext]"` keys on a message generated with
135    /// preservation off.
136    pub strict_extension_keys: bool,
137    /// When `true`, the `@type` of a `google.protobuf.Any` must be a type
138    /// URL: it must contain a `/`. A bare message full name such as
139    /// `"pkg.Message"` is a parse error.
140    ///
141    /// With the default (`false`), a bare full name is accepted when the
142    /// type registry has a JSON entry for a message of that name, and the
143    /// `Any` keeps it as its `type_url`. protobuf-go and Python read such a
144    /// name. C++ and Java reject it, and `any.proto` says that a type URL
145    /// contains at least one `/`. Set `true` to reject what C++ and Java
146    /// reject.
147    ///
148    /// A bare name without a JSON entry is a parse error with the option on
149    /// or off, and so is an `@type` that is empty or ends in `/`.
150    ///
151    /// The option covers parsing, and generated message types only.
152    /// Serialization writes the `type_url` an `Any` holds, and
153    /// `Any::type_name` and `Any::is_message` in `buffa-types` read a bare
154    /// name with the option on or off: test `type_url` for a `/` yourself
155    /// where that matters. JSON parsing of a `DynamicMessage` does not read
156    /// the option. Set `DynamicMessageSeed::strict_any_type_urls` in
157    /// `buffa-descriptor` for that.
158    pub strict_any_type_urls: bool,
159}
160
161impl JsonParseOptions {
162    /// Create new parse options with every flag at its default, `false`.
163    pub fn new() -> Self {
164        Self::default()
165    }
166
167    /// Set whether enum values that the enum does not declare are ignored
168    /// instead of producing a parse error. See the [module docs](self) for
169    /// what "ignored" means for each kind of field.
170    #[must_use]
171    pub fn ignore_unknown_enum_values(mut self, ignore: bool) -> Self {
172        self.ignore_unknown_enum_values = ignore;
173        self
174    }
175
176    /// Set whether unregistered `"[pkg.ext]"` JSON keys produce a parse error
177    /// (`true`) or are silently dropped (`false`, the default).
178    #[must_use]
179    pub fn strict_extension_keys(mut self, strict: bool) -> Self {
180        self.strict_extension_keys = strict;
181        self
182    }
183
184    /// Set whether the `@type` of a `google.protobuf.Any` must contain a `/`
185    /// (`true`), or may also be the bare full name of a registered message
186    /// (`false`, the default).
187    #[must_use]
188    pub fn strict_any_type_urls(mut self, strict: bool) -> Self {
189        self.strict_any_type_urls = strict;
190        self
191    }
192}
193
194// ─────────────────────────────────────────────────────────────────────────────
195// std: thread-local scoped options
196// ─────────────────────────────────────────────────────────────────────────────
197
198#[cfg(feature = "std")]
199mod std_impl {
200    use super::JsonParseOptions;
201    use std::cell::Cell;
202
203    thread_local! {
204        static OPTIONS: Cell<JsonParseOptions> = const {
205            Cell::new(JsonParseOptions {
206                ignore_unknown_enum_values: false,
207                strict_extension_keys: false,
208                strict_any_type_urls: false,
209            })
210        };
211    }
212
213    /// Run a closure with the given parse options active.
214    ///
215    /// The options affect JSON deserialization within the closure. This is
216    /// **thread-local** state — concurrent parses on different threads are
217    /// independent. The previous options are restored when the closure returns
218    /// (or panics), so scopes nest correctly.
219    ///
220    /// This function is only available with the `std` feature. In `no_std`
221    /// builds, use `set_global_json_parse_options` instead (see the module
222    /// documentation for the usage contract).
223    pub fn with_json_parse_options<T>(opts: &JsonParseOptions, f: impl FnOnce() -> T) -> T {
224        let prev = OPTIONS.with(|c| c.replace(*opts));
225        struct Guard(JsonParseOptions);
226        impl Drop for Guard {
227            fn drop(&mut self) {
228                OPTIONS.with(|c| c.set(self.0));
229            }
230        }
231        let _guard = Guard(prev);
232        f()
233    }
234
235    pub(crate) fn ignore_unknown_enum_values() -> bool {
236        OPTIONS.with(|c| c.get().ignore_unknown_enum_values)
237    }
238
239    pub(crate) fn strict_extension_keys() -> bool {
240        OPTIONS.with(|c| c.get().strict_extension_keys)
241    }
242
243    pub(crate) fn strict_any_type_urls() -> bool {
244        OPTIONS.with(|c| c.get().strict_any_type_urls)
245    }
246}
247
248#[cfg(feature = "std")]
249pub use std_impl::with_json_parse_options;
250
251// ─────────────────────────────────────────────────────────────────────────────
252// no_std: global once-cell options (set once, read lock-free)
253// ─────────────────────────────────────────────────────────────────────────────
254//
255// The module is always compiled so its tests run in std builds too, but
256// the public `set_global_json_parse_options` re-export is gated on `not(std)`.
257
258/// Global parse-options state for `no_std` builds.
259///
260/// Uses [`once_cell::race::OnceBox`] — an `AtomicPtr`-based set-once cell
261/// that's `no_std`-compatible and already a buffa dependency (for
262/// `DefaultInstance`). This stores the full struct on the heap, so future
263/// additions to `JsonParseOptions` (non-boolean fields, integers, strings,
264/// etc.) require no changes here.
265///
266/// [`once_cell::race::OnceBox`]: https://docs.rs/once_cell/latest/once_cell/race/struct.OnceBox.html
267#[cfg_attr(feature = "std", allow(dead_code))]
268mod global {
269    use super::JsonParseOptions;
270    use alloc::boxed::Box;
271    use once_cell::race::OnceBox;
272
273    static OPTS: OnceBox<JsonParseOptions> = OnceBox::new();
274
275    /// Defaults, used when `set_global_json_parse_options` has never been
276    /// called. Identical to `JsonParseOptions::default()` but `const`-eval.
277    static DEFAULT: JsonParseOptions = JsonParseOptions {
278        ignore_unknown_enum_values: false,
279        strict_extension_keys: false,
280        strict_any_type_urls: false,
281    };
282
283    /// Set the global JSON parse options.
284    ///
285    /// # Usage contract
286    ///
287    /// **Call this once during startup** (e.g. in your firmware init or
288    /// `main()`). After the first call, the options are locked in for the
289    /// process lifetime.
290    ///
291    /// Multiple calls with **identical** options are permitted and are no-ops —
292    /// this supports initialization from multiple modules that agree on
293    /// configuration. Multiple calls with **different** options are a bug:
294    /// - In debug builds: `debug_assert!` panics with a mismatch diagnostic.
295    /// - In release builds: the second call is silently ignored; the first
296    ///   call's options remain in effect.
297    ///
298    /// # Example
299    ///
300    /// ```ignore
301    /// use buffa::json::{JsonParseOptions, set_global_json_parse_options};
302    ///
303    /// fn init() {
304    ///     set_global_json_parse_options(
305    ///         &JsonParseOptions::new().ignore_unknown_enum_values(true)
306    ///     );
307    /// }
308    /// ```
309    pub fn set_global_json_parse_options(opts: &JsonParseOptions) {
310        if OPTS.set(Box::new(*opts)).is_err() {
311            // Already set. OnceBox::set returned our rejected Box (which it
312            // drops internally); the first caller's options remain in effect.
313            // Idempotent re-init with the same options is fine; mismatch is a bug.
314            let existing = OPTS.get().expect("set() returned Err ⇒ get() is Some");
315            debug_assert_eq!(
316                existing, opts,
317                "set_global_json_parse_options called with options that differ from the \
318                 first call. The first call's options remain in effect. \
319                 (existing: {existing:?}, new: {opts:?})"
320            );
321        }
322    }
323
324    /// Get the currently-active options (global or defaults if never set).
325    #[inline]
326    pub(crate) fn get() -> &'static JsonParseOptions {
327        OPTS.get().unwrap_or(&DEFAULT)
328    }
329
330    pub(crate) fn ignore_unknown_enum_values() -> bool {
331        get().ignore_unknown_enum_values
332    }
333
334    pub(crate) fn strict_extension_keys() -> bool {
335        get().strict_extension_keys
336    }
337
338    pub(crate) fn strict_any_type_urls() -> bool {
339        get().strict_any_type_urls
340    }
341}
342
343#[cfg(not(feature = "std"))]
344pub use global::set_global_json_parse_options;
345
346// ─────────────────────────────────────────────────────────────────────────────
347// Crate-internal read accessor (called from json_helpers.rs)
348// ─────────────────────────────────────────────────────────────────────────────
349
350/// Returns `true` if unknown enum string values should be silently accepted.
351///
352/// In `std` builds, reads the thread-local set by [`with_json_parse_options`].
353/// In `no_std` builds, reads the global atomic set by
354/// [`set_global_json_parse_options`]. The two mechanisms are mutually
355/// exclusive (different builds) and do not interact.
356pub(crate) fn ignore_unknown_enum_values() -> bool {
357    #[cfg(feature = "std")]
358    {
359        std_impl::ignore_unknown_enum_values()
360    }
361    #[cfg(not(feature = "std"))]
362    {
363        global::ignore_unknown_enum_values()
364    }
365}
366
367/// Returns `true` if unregistered `"[pkg.ext]"` JSON keys should produce a
368/// parse error instead of being silently dropped.
369pub(crate) fn strict_extension_keys() -> bool {
370    #[cfg(feature = "std")]
371    {
372        std_impl::strict_extension_keys()
373    }
374    #[cfg(not(feature = "std"))]
375    {
376        global::strict_extension_keys()
377    }
378}
379
380/// Returns `true` if a `google.protobuf.Any` `@type` without a `/` should
381/// produce a parse error.
382pub(crate) fn strict_any_type_urls() -> bool {
383    #[cfg(feature = "std")]
384    {
385        std_impl::strict_any_type_urls()
386    }
387    #[cfg(not(feature = "std"))]
388    {
389        global::strict_any_type_urls()
390    }
391}
392
393// ─────────────────────────────────────────────────────────────────────────────
394// Tests
395// ─────────────────────────────────────────────────────────────────────────────
396
397#[cfg(test)]
398mod tests {
399    use super::*;
400
401    // ── Thread-local (std) behaviour ───────────────────────────────────────
402    // These tests use the crate-internal `ignore_unknown_enum_values()` which
403    // in std reads ONLY the thread-local, so they don't need to coordinate
404    // with the global-atomic tests below.
405
406    #[test]
407    fn thread_local_default_does_not_ignore() {
408        assert!(!ignore_unknown_enum_values());
409    }
410
411    #[test]
412    fn thread_local_scope_enables_flag() {
413        let opts = JsonParseOptions {
414            ignore_unknown_enum_values: true,
415            ..Default::default()
416        };
417        with_json_parse_options(&opts, || {
418            assert!(ignore_unknown_enum_values());
419        });
420        // Restored after closure returns.
421        assert!(!ignore_unknown_enum_values());
422    }
423
424    #[test]
425    fn thread_local_scope_enables_strict_any_type_urls() {
426        assert!(!strict_any_type_urls());
427        let opts = JsonParseOptions::new().strict_any_type_urls(true);
428        with_json_parse_options(&opts, || {
429            assert!(strict_any_type_urls());
430            assert!(!ignore_unknown_enum_values());
431        });
432        assert!(!strict_any_type_urls());
433    }
434
435    #[test]
436    fn thread_local_nested_scopes_restore_correctly() {
437        let outer = JsonParseOptions {
438            ignore_unknown_enum_values: true,
439            ..Default::default()
440        };
441        let inner = JsonParseOptions {
442            ignore_unknown_enum_values: false,
443            ..Default::default()
444        };
445        with_json_parse_options(&outer, || {
446            assert!(ignore_unknown_enum_values());
447            with_json_parse_options(&inner, || {
448                assert!(!ignore_unknown_enum_values());
449            });
450            assert!(ignore_unknown_enum_values());
451        });
452    }
453
454    #[test]
455    fn thread_local_restored_on_panic() {
456        let opts = JsonParseOptions {
457            ignore_unknown_enum_values: true,
458            ..Default::default()
459        };
460        let result = std::panic::catch_unwind(|| {
461            with_json_parse_options(&opts, || {
462                assert!(ignore_unknown_enum_values());
463                panic!("boom");
464            });
465        });
466        assert!(result.is_err());
467        assert!(!ignore_unknown_enum_values());
468    }
469
470    // ── Global set-once behaviour (OnceBox) ─────────────────────────────────
471    // Single lifecycle test — the production contract is "set once", so we
472    // test that contract once. No reset-between-tests (OnceBox deliberately
473    // has no reset; that's the point of "once"). The phases run sequentially
474    // in one #[test] so ordering is guaranteed.
475    //
476    // In no_std builds, `global::set_global_json_parse_options` IS the public
477    // `set_global_json_parse_options` — this test verifies its contract.
478
479    #[test]
480    fn global_set_once_lifecycle() {
481        // Phase 1: never set → defaults.
482        assert!(
483            !global::ignore_unknown_enum_values(),
484            "unset global should return strict defaults"
485        );
486        assert_eq!(*global::get(), JsonParseOptions::default());
487
488        // Phase 2: first set wins, locks in.
489        let lenient = JsonParseOptions::new().ignore_unknown_enum_values(true);
490        global::set_global_json_parse_options(&lenient);
491        assert!(global::ignore_unknown_enum_values());
492
493        // Phase 3: idempotent re-init with identical options — no panic.
494        global::set_global_json_parse_options(&lenient);
495        global::set_global_json_parse_options(&lenient);
496        assert!(global::ignore_unknown_enum_values());
497
498        // Phase 4: mismatch → debug_assert.
499        //
500        // Run in a child thread so the panic is catchable (debug_assert panics
501        // without unwinding the current test); in release builds this phase
502        // asserts the first call's options remain in effect instead.
503        let strict = JsonParseOptions::new().ignore_unknown_enum_values(false);
504        let result = std::thread::spawn(move || {
505            global::set_global_json_parse_options(&strict);
506        })
507        .join();
508
509        #[cfg(debug_assertions)]
510        {
511            assert!(
512                result.is_err(),
513                "mismatch should debug_assert-panic in debug builds"
514            );
515            // Verify the panic message mentions the mismatch.
516            let msg = result.unwrap_err();
517            let msg_str = msg
518                .downcast_ref::<String>()
519                .map(String::as_str)
520                .or_else(|| msg.downcast_ref::<&str>().copied())
521                .unwrap_or("");
522            assert!(
523                msg_str.contains("differ from the first call"),
524                "expected mismatch diagnostic, got: {msg_str}"
525            );
526        }
527        #[cfg(not(debug_assertions))]
528        {
529            assert!(
530                result.is_ok(),
531                "release builds silently ignore mismatched second call"
532            );
533        }
534
535        // Either way: first call's options remain in effect.
536        assert!(
537            global::ignore_unknown_enum_values(),
538            "first call's lenient options should remain in effect after mismatch"
539        );
540    }
541}