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}