json only.Expand description
JSON parse options for protobuf JSON deserialization.
The protobuf JSON spec says parsers should reject unknown fields by default but may provide an option to ignore them. This module exposes that option, matching the per-call semantics of C++ and Java reference implementations.
The options here are runtime ones: unknown enum values
(JsonParseOptions::ignore_unknown_enum_values), unregistered
extension keys (JsonParseOptions::strict_extension_keys) and
google.protobuf.Any @type values without a /
(JsonParseOptions::strict_any_type_urls). Unknown
field names are not governed here: generated deserializers ignore them
unless the code was generated with
buffa_build::Config::deny_unknown_json_fields (or its path-scoped
deny_unknown_json_fields_in).
§Two mutually exclusive APIs: scoped (std) vs global (no_std)
Serde’s Deserialize trait has no context parameter, so runtime options
must be passed through ambient state. The available mechanism differs
between std and no_std builds — each build exposes exactly one:
| Build | Mechanism | API | Scoping |
|---|---|---|---|
std | Thread-local | with_json_parse_options | Per-closure, nestable, per-thread |
no_std | AtomicPtr to leaked Box | set_global_json_parse_options | Process-wide, set-once |
The two APIs do not interact. set_global_json_parse_options is only
compiled in no_std builds; with_json_parse_options only in std.
§std: scoped per-closure options
use buffa::json::{JsonParseOptions, with_json_parse_options};
let opts = JsonParseOptions::new().ignore_unknown_enum_values(true);
let msg = with_json_parse_options(&opts, || {
serde_json::from_str::<MyMessage>(json_str)
});
// Options revert to defaults here. Concurrent threads are independent.§no_std: global set-once options
use buffa::json::{JsonParseOptions, set_global_json_parse_options};
// Call ONCE during startup (e.g. in your init function).
set_global_json_parse_options(
&JsonParseOptions::new().ignore_unknown_enum_values(true)
);
// All subsequent JSON deserialization uses these options.
let msg: MyMessage = serde_json::from_str(json_str)?;The global setter is idempotent for identical options — calling it
multiple times with the same configuration is a no-op, so initialization
from multiple modules is safe as long as they agree. Calling it with
different options after the first call triggers a debug_assert! (panic
in debug builds; the second call is silently ignored in release). Treat the
first successful call as locking in behaviour for the process lifetime.
§What ignore_unknown_enum_values changes for each kind of field
The option covers enum values that the enum does not declare. With the
option set, a generated message type handles such a value as the table
says, in std and no_std builds alike unless a cell names the build:
| Field | Unknown name | Undeclared number, closed enum |
|---|---|---|
implicit presence, or required | default value (0 for an open enum) | parse error |
explicit presence (the Rust type is Option) | left unset | left unset |
repeated or map | element or entry dropped | element or entry dropped |
oneof member, open enum | member set, with value 0 (std); parse error (no_std) | does not apply |
oneof member, closed enum | parse error | parse error |
| extension | parse error | kept |
An undeclared number is an integer in the i32 range that the enum does
not declare. An open enum keeps one as
EnumValue::Unknown in every kind of field.
With the option off, each cell is a parse error, and an extension still
keeps the number.
A value that cannot be an enum value is a parse error in every kind of
field, with the option on or off. Such a value is a bool, an object, an
array, a number written with a fraction or an exponent (such as 1.0), or
an integer outside the i32 range. A null element of a repeated closed
enum field, or a null value in a closed enum map, is a parse error in both
modes. For open enums, it is read as the enum’s default value.
The option applies to generated message types. JSON parsing of a
DynamicMessage in buffa-descriptor does not read the option, and an
unknown enum name is a parse error there.
Structs§
- Json
Parse Options - Options controlling protobuf JSON parsing behavior.
Functions§
- with_
json_ parse_ options std - Run a closure with the given parse options active.