Skip to main content

buffa/json_helpers/
buffered.rs

1//! JSON values buffered with every object key read as data.
2//!
3//! Use this module wherever a `Deserialize` impl keeps untrusted input as a
4//! [`serde_json::Value`] before it decodes it:
5//!
6//! - In a hand-written visitor, read a [`BufferedValue`], as in
7//!   `let BufferedValue(value) = map.next_value()?;`. Read a
8//!   [`BufferedObject`] when the input must be an object.
9//! - On a field of a derived impl, name [`value`], [`opt_value`] or
10//!   [`object`] in `#[serde(deserialize_with = "...")]`.
11//!
12//! The `Deserialize` impl of `Value` itself must not read untrusted input.
13//! The same is true of the impls of types that hold a `Value`, such as
14//! `Map<String, Value>` and `Vec<Value>`. When any crate in the build enables
15//! the `raw_value` feature of `serde_json`, that impl reads an object whose
16//! first key is `$serde_json::private::RawValue` as the JSON text in the
17//! string under that key. The decoded value then differs from the one that a
18//! filter, a log or a signature check sees in the request text. Each such
19//! string is parsed with a new recursion limit, so nested strings build a
20//! value deeper than `serde_json` allows in one parse.
21//!
22//! The types in this module build the same `Value` and read every object key
23//! as data, at every depth. They set no depth limit of their own. The depth of
24//! what they build is the depth that the deserializer allows, which is 128
25//! for `serde_json` by default.
26//!
27//! `buffa` buffers through them where a proto3 JSON shape cannot be decoded in
28//! one pass. A `google.protobuf.Any` names its type in `@type`, which can
29//! follow the fields that it describes. An element of a repeated enum field
30//! that is an unknown enum name is dropped, not rejected, when
31//! [`ignore_unknown_enum_values`](crate::json::JsonParseOptions::ignore_unknown_enum_values)
32//! is set.
33//!
34//! # Fields of other types
35//!
36//! For a field that holds a `Value` in another container, write the function
37//! for `deserialize_with` from the types:
38//!
39//! ```
40//! use buffa::json_helpers::buffered::BufferedValue;
41//! use serde::{Deserialize, Deserializer};
42//! use serde_json::Value;
43//!
44//! fn values<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Vec<Value>, D::Error> {
45//!     let buffered = Vec::<BufferedValue>::deserialize(deserializer)?;
46//!     Ok(buffered.into_iter().map(Value::from).collect())
47//! }
48//!
49//! #[derive(Deserialize)]
50//! struct Batch {
51//!     #[serde(deserialize_with = "values")]
52//!     items: Vec<Value>,
53//! }
54//!
55//! let text = r#"{"items": [{"$serde_json::private::RawValue": "[1, 2]"}]}"#;
56//! let batch: Batch = serde_json::from_str(text)?;
57//! assert_eq!(batch.items[0]["$serde_json::private::RawValue"], "[1, 2]");
58//! # Ok::<(), serde_json::Error>(())
59//! ```
60//!
61//! # The `arbitrary_precision` feature of `serde_json`
62//!
63//! `buffa`'s JSON decoding does not support that feature. With it, a number
64//! that has a fraction or an exponent, or a whole number outside the `i64`
65//! and `u64` ranges, reaches a visitor as an object with the key
66//! `$serde_json::private::Number`. The numeric helpers, such as
67//! [`double`](super::double) and [`int64`](super::int64), reject that object,
68//! so an integer field also rejects `1.0` and `1e3`.
69//!
70//! The types in this module read that key as data, so the JSON text
71//! `{"$serde_json::private::Number": "1"}` stays an object in every build.
72//! With the feature on, the number `1.5` therefore buffers as an object with
73//! that key, where `Value` holds a number.
74
75use alloc::string::String;
76use alloc::vec::Vec;
77use core::cell::Cell;
78use core::fmt;
79
80use serde::de::{Deserialize, DeserializeSeed, Deserializer, Error, MapAccess, SeqAccess, Visitor};
81use serde_json::{Map, Number, Value};
82
83/// A [`serde_json::Value`], deserialized with every object key read as data.
84///
85/// The wrapper selects the `Deserialize` impl and carries no invariant: any
86/// `Value` can be wrapped. It accepts the input that `Value` accepts, and
87/// builds the same `Value` except in two cases:
88///
89/// - An object with the key `$serde_json::private::RawValue` stays an object.
90/// - In a build with `serde_json`'s `arbitrary_precision` feature, a number
91///   that has a fraction or an exponent, or that is outside the `i64` and
92///   `u64` ranges, buffers as an object and not as a number.
93///
94/// The [module documentation](self) explains both.
95///
96/// # Examples
97///
98/// ```
99/// use buffa::json_helpers::buffered::BufferedValue;
100///
101/// let text = r#"{"$serde_json::private::RawValue": "[1, 2]"}"#;
102/// let BufferedValue(value) = serde_json::from_str(text)?;
103/// assert_eq!(value["$serde_json::private::RawValue"], "[1, 2]");
104/// # Ok::<(), serde_json::Error>(())
105/// ```
106#[derive(Clone, Debug, PartialEq)]
107pub struct BufferedValue(pub Value);
108
109/// A JSON object, deserialized with every key read as data at every depth.
110///
111/// Use it instead of [`BufferedValue`] when the input must be a JSON object,
112/// such as a payload whose fields are looked up by name. It accepts the input
113/// that `serde_json::Map<String, Value>` accepts. From `serde_json`, that is
114/// only a JSON object, so `null` is an error.
115#[derive(Clone, Debug, PartialEq)]
116pub struct BufferedObject(pub Map<String, Value>);
117
118impl From<BufferedValue> for Value {
119    fn from(BufferedValue(value): BufferedValue) -> Self {
120        value
121    }
122}
123
124impl From<BufferedObject> for Map<String, Value> {
125    fn from(BufferedObject(object): BufferedObject) -> Self {
126        object
127    }
128}
129
130/// Deserializes a [`serde_json::Value`] as [`BufferedValue`] does.
131///
132/// Name it in `#[serde(deserialize_with = "...")]` on a field of type `Value`.
133/// The result differs from what `Value`'s own impl builds in the two cases
134/// that [`BufferedValue`] lists.
135///
136/// # Errors
137///
138/// Returns an error if `deserializer` fails, for example when `serde_json`
139/// finds input nested past its recursion limit. Returns an error if
140/// `deserializer` produces a value that a `Value` cannot hold, such as bytes.
141///
142/// # Examples
143///
144/// ```
145/// #[derive(serde::Deserialize)]
146/// struct Event {
147///     #[serde(deserialize_with = "buffa::json_helpers::buffered::value")]
148///     payload: serde_json::Value,
149/// }
150///
151/// let text = r#"{"payload": {"$serde_json::private::RawValue": "[1, 2]"}}"#;
152/// let event: Event = serde_json::from_str(text)?;
153/// assert_eq!(event.payload["$serde_json::private::RawValue"], "[1, 2]");
154/// # Ok::<(), serde_json::Error>(())
155/// ```
156pub fn value<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Value, D::Error> {
157    BufferedValue::deserialize(deserializer).map(Value::from)
158}
159
160/// Deserializes an `Option<serde_json::Value>` as [`BufferedValue`] does.
161///
162/// JSON `null` deserializes to `None`, and so does a missing field when the
163/// field has `#[serde(default)]`. Without `default`, serde rejects input that
164/// omits a field with `deserialize_with`.
165///
166/// # Errors
167///
168/// Returns the errors that [`value`] returns.
169///
170/// # Examples
171///
172/// ```
173/// #[derive(serde::Deserialize)]
174/// struct Event {
175///     #[serde(default, deserialize_with = "buffa::json_helpers::buffered::opt_value")]
176///     payload: Option<serde_json::Value>,
177/// }
178///
179/// let event: Event = serde_json::from_str("{}")?;
180/// assert_eq!(event.payload, None);
181/// # Ok::<(), serde_json::Error>(())
182/// ```
183pub fn opt_value<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Option<Value>, D::Error> {
184    Option::<BufferedValue>::deserialize(deserializer).map(|value| value.map(Value::from))
185}
186
187/// Deserializes a `serde_json::Map<String, Value>` as [`BufferedObject`] does.
188///
189/// Name it in `#[serde(deserialize_with = "...")]` on a field of type
190/// `Map<String, Value>`, including a field with `#[serde(flatten)]` that
191/// collects the keys that no other field names.
192///
193/// # Errors
194///
195/// Returns the errors that [`value`] returns. Returns an error if the input
196/// is not an object.
197pub fn object<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Map<String, Value>, D::Error> {
198    BufferedObject::deserialize(deserializer).map(Map::from)
199}
200
201impl<'de> Deserialize<'de> for BufferedValue {
202    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
203        d.deserialize_any(ValueVisitor).map(Self)
204    }
205}
206
207impl<'de> Deserialize<'de> for BufferedObject {
208    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
209        d.deserialize_map(ObjectVisitor).map(Self)
210    }
211}
212
213fn read_object<'de, A: MapAccess<'de>>(mut map: A) -> Result<Map<String, Value>, A::Error> {
214    let mut out = Map::new();
215    while let Some(key) = map.next_key::<String>()? {
216        let BufferedValue(value) = map.next_value()?;
217        out.insert(key, value);
218    }
219    Ok(out)
220}
221
222struct ObjectVisitor;
223
224impl<'de> Visitor<'de> for ObjectVisitor {
225    type Value = Map<String, Value>;
226
227    fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
228        f.write_str("a map")
229    }
230
231    fn visit_unit<E>(self) -> Result<Self::Value, E> {
232        Ok(Map::new())
233    }
234
235    fn visit_map<A: MapAccess<'de>>(self, map: A) -> Result<Self::Value, A::Error> {
236        read_object(map)
237    }
238}
239
240struct ValueVisitor;
241
242impl<'de> Visitor<'de> for ValueVisitor {
243    type Value = Value;
244
245    fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
246        f.write_str("any valid JSON value")
247    }
248
249    fn visit_bool<E>(self, v: bool) -> Result<Value, E> {
250        Ok(Value::Bool(v))
251    }
252
253    fn visit_i64<E>(self, v: i64) -> Result<Value, E> {
254        Ok(Value::Number(v.into()))
255    }
256
257    fn visit_i128<E: Error>(self, v: i128) -> Result<Value, E> {
258        Number::deserialize(serde::de::value::I128Deserializer::new(v)).map(Value::Number)
259    }
260
261    fn visit_u64<E>(self, v: u64) -> Result<Value, E> {
262        Ok(Value::Number(v.into()))
263    }
264
265    fn visit_u128<E: Error>(self, v: u128) -> Result<Value, E> {
266        Number::deserialize(serde::de::value::U128Deserializer::new(v)).map(Value::Number)
267    }
268
269    fn visit_f64<E>(self, v: f64) -> Result<Value, E> {
270        // A non-finite float has no JSON form; `serde_json` buffers it as
271        // `null`, and so does this.
272        Ok(Number::from_f64(v).map_or(Value::Null, Value::Number))
273    }
274
275    fn visit_str<E>(self, v: &str) -> Result<Value, E> {
276        Ok(Value::String(String::from(v)))
277    }
278
279    fn visit_string<E>(self, v: String) -> Result<Value, E> {
280        Ok(Value::String(v))
281    }
282
283    fn visit_none<E>(self) -> Result<Value, E> {
284        Ok(Value::Null)
285    }
286
287    fn visit_some<D: Deserializer<'de>>(self, d: D) -> Result<Value, D::Error> {
288        BufferedValue::deserialize(d).map(|BufferedValue(v)| v)
289    }
290
291    fn visit_unit<E>(self) -> Result<Value, E> {
292        Ok(Value::Null)
293    }
294
295    fn visit_seq<A: SeqAccess<'de>>(self, mut seq: A) -> Result<Value, A::Error> {
296        let mut out = Vec::new();
297        while let Some(BufferedValue(element)) = seq.next_element()? {
298            out.push(element);
299        }
300        Ok(Value::Array(out))
301    }
302
303    fn visit_map<A: MapAccess<'de>>(self, map: A) -> Result<Value, A::Error> {
304        read_object(map).map(Value::Object)
305    }
306}
307
308/// Buffers a JSON object as [`object`] does, and charges `remaining` for what
309/// it buffers.
310///
311/// At every depth, each object member subtracts `per_member` from `remaining`
312/// after it is read, and each array element subtracts `per_element`. A member
313/// whose name repeats an earlier one is charged again. A charge larger than
314/// `remaining` fails with `D::Error::custom(limit_msg)` and leaves `remaining`
315/// unchanged. The input after that value is not read, and what is buffered
316/// and not yet charged is at most one value for each level of nesting.
317///
318/// The function only subtracts. A caller that later drops the buffer reads
319/// `remaining` before and after the call, and adds the difference back
320/// itself.
321///
322/// `buffa-descriptor`'s reflective JSON parser calls this function to charge
323/// the buffer of a `google.protobuf.Any` payload to its element-memory limit.
324/// Like [`wkt`](super::wkt), it is not a supported entry point.
325#[doc(hidden)]
326pub fn charged_object<'de, D: Deserializer<'de>>(
327    deserializer: D,
328    remaining: &Cell<usize>,
329    per_member: usize,
330    per_element: usize,
331    limit_msg: &'static str,
332) -> Result<Map<String, Value>, D::Error> {
333    deserializer.deserialize_map(ChargingObjectVisitor(Budget {
334        remaining,
335        per_member,
336        per_element,
337        limit_msg,
338    }))
339}
340
341/// What [`charged_object`] charges: `per_member` bytes of `remaining` for
342/// each admitted object member and `per_element` for each admitted array
343/// element, and an error with the text `limit_msg` for a charge larger than
344/// `remaining`.
345#[derive(Clone, Copy)]
346struct Budget<'a> {
347    remaining: &'a Cell<usize>,
348    per_member: usize,
349    per_element: usize,
350    limit_msg: &'static str,
351}
352
353impl Budget<'_> {
354    fn charge<E: Error>(&self, bytes: usize) -> Result<(), E> {
355        let left = self.remaining.get();
356        if bytes > left {
357            return Err(E::custom(self.limit_msg));
358        }
359        self.remaining.set(left - bytes);
360        Ok(())
361    }
362}
363
364/// Buffers a value as [`BufferedValue`] does, charging the budget for each
365/// array element and object member inside it.
366#[derive(Clone, Copy)]
367struct ChargingValue<'a>(Budget<'a>);
368
369impl<'de> DeserializeSeed<'de> for ChargingValue<'_> {
370    type Value = Value;
371
372    fn deserialize<D: Deserializer<'de>>(self, d: D) -> Result<Value, D::Error> {
373        d.deserialize_any(ChargingValueVisitor(self.0))
374    }
375}
376
377/// Reads an object, charging `budget` for each member and buffering each
378/// value through [`ChargingValue`], so that nested values charge the same
379/// budget.
380///
381/// A member is charged after its value is read. The value's own contents were
382/// charged as they were built.
383fn read_charging_object<'de, A: MapAccess<'de>>(
384    mut map: A,
385    budget: Budget<'_>,
386) -> Result<Map<String, Value>, A::Error> {
387    let mut out = Map::new();
388    while let Some(key) = map.next_key::<String>()? {
389        let value = map.next_value_seed(ChargingValue(budget))?;
390        budget.charge(budget.per_member)?;
391        out.insert(key, value);
392    }
393    Ok(out)
394}
395
396struct ChargingObjectVisitor<'a>(Budget<'a>);
397
398impl<'de> Visitor<'de> for ChargingObjectVisitor<'_> {
399    type Value = Map<String, Value>;
400
401    fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
402        f.write_str("a map")
403    }
404
405    fn visit_unit<E>(self) -> Result<Self::Value, E> {
406        Ok(Map::new())
407    }
408
409    fn visit_map<A: MapAccess<'de>>(self, map: A) -> Result<Self::Value, A::Error> {
410        read_charging_object(map, self.0)
411    }
412}
413
414struct ChargingValueVisitor<'a>(Budget<'a>);
415
416impl<'de> Visitor<'de> for ChargingValueVisitor<'_> {
417    type Value = Value;
418
419    fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
420        f.write_str("any valid JSON value")
421    }
422
423    // A scalar has no children, and the container that admits it charges it.
424    // Each scalar method forwards to `ValueVisitor`, so the two build the
425    // same value for NaN and for wide integers.
426    fn visit_bool<E: Error>(self, v: bool) -> Result<Value, E> {
427        ValueVisitor.visit_bool(v)
428    }
429    fn visit_i64<E: Error>(self, v: i64) -> Result<Value, E> {
430        ValueVisitor.visit_i64(v)
431    }
432    fn visit_i128<E: Error>(self, v: i128) -> Result<Value, E> {
433        ValueVisitor.visit_i128(v)
434    }
435    fn visit_u64<E: Error>(self, v: u64) -> Result<Value, E> {
436        ValueVisitor.visit_u64(v)
437    }
438    fn visit_u128<E: Error>(self, v: u128) -> Result<Value, E> {
439        ValueVisitor.visit_u128(v)
440    }
441    fn visit_f64<E: Error>(self, v: f64) -> Result<Value, E> {
442        ValueVisitor.visit_f64(v)
443    }
444    fn visit_str<E: Error>(self, v: &str) -> Result<Value, E> {
445        ValueVisitor.visit_str(v)
446    }
447    fn visit_string<E: Error>(self, v: String) -> Result<Value, E> {
448        ValueVisitor.visit_string(v)
449    }
450    fn visit_none<E: Error>(self) -> Result<Value, E> {
451        ValueVisitor.visit_none()
452    }
453    fn visit_unit<E: Error>(self) -> Result<Value, E> {
454        ValueVisitor.visit_unit()
455    }
456
457    // The values inside a container go through the charging seed, so the
458    // whole subtree draws on the one budget.
459    fn visit_some<D: Deserializer<'de>>(self, d: D) -> Result<Value, D::Error> {
460        ChargingValue(self.0).deserialize(d)
461    }
462
463    fn visit_seq<A: SeqAccess<'de>>(self, mut seq: A) -> Result<Value, A::Error> {
464        let budget = self.0;
465        let mut out = Vec::new();
466        while let Some(element) = seq.next_element_seed(ChargingValue(budget))? {
467            budget.charge(budget.per_element)?;
468            out.push(element);
469        }
470        Ok(Value::Array(out))
471    }
472
473    fn visit_map<A: MapAccess<'de>>(self, map: A) -> Result<Value, A::Error> {
474        read_charging_object(map, self.0).map(Value::Object)
475    }
476}
477
478#[cfg(test)]
479mod tests {
480    use super::*;
481    use alloc::format;
482    use alloc::string::ToString;
483    use serde_json::json;
484
485    const RAW_VALUE_KEY: &str = "$serde_json::private::RawValue";
486
487    fn buffer(text: &str) -> serde_json::Result<Value> {
488        serde_json::from_str(text).map(|BufferedValue(v)| v)
489    }
490
491    fn depth(v: &Value) -> usize {
492        match v {
493            Value::Array(a) => 1 + a.iter().map(depth).max().unwrap_or(0),
494            Value::Object(o) => 1 + o.values().map(depth).max().unwrap_or(0),
495            Value::Null | Value::Bool(_) | Value::Number(_) | Value::String(_) => 0,
496        }
497    }
498
499    /// `levels` objects with the private key, each inside `arrays` arrays and
500    /// holding the next level as a JSON string.
501    fn nested_raw_values(levels: usize, arrays: usize) -> alloc::string::String {
502        let mut inner = "0".to_string();
503        for _ in 0..levels {
504            let object = json!({ RAW_VALUE_KEY: inner }).to_string();
505            inner = format!("{}{object}{}", "[".repeat(arrays), "]".repeat(arrays));
506        }
507        inner
508    }
509
510    /// The tests of the private key also pass against `serde_json::Value`'s
511    /// own `Deserialize` impl unless `serde_json` has `raw_value` on. It is a
512    /// dev-dependency feature of this crate, so a test build always has it.
513    #[test]
514    fn the_test_build_has_serde_json_raw_value_enabled() {
515        let text = json!({ RAW_VALUE_KEY: "[1]" }).to_string();
516        let value: Value = serde_json::from_str(&text).unwrap();
517        assert_eq!(value, json!([1]));
518    }
519
520    #[test]
521    fn ordinary_json_buffers_as_serde_json_does() {
522        for text in [
523            "null",
524            "true",
525            "0",
526            "-1",
527            "18446744073709551615",
528            "-9223372036854775808",
529            "1.5",
530            "1e400",
531            r#""a\"é\n""#,
532            "[]",
533            "{}",
534            r#"[1, [2, [3, {"a": [null]}]], "x"]"#,
535            r#"{"a": 1, "b": {"c": [true, false]}, "a": 2}"#,
536            r#"{"$serde_json::private::Number": "1"}"#,
537        ] {
538            let expected = serde_json::from_str::<Value>(text).map_err(|e| e.to_string());
539            let got = buffer(text).map_err(|e| e.to_string());
540            assert_eq!(got, expected, "{text}");
541        }
542    }
543
544    #[test]
545    fn the_raw_value_key_is_data_in_json_text() {
546        let text = json!({ RAW_VALUE_KEY: "[1]" }).to_string();
547        let mut expected = Map::new();
548        expected.insert(RAW_VALUE_KEY.to_string(), Value::String("[1]".to_string()));
549        assert_eq!(buffer(&text).unwrap(), Value::Object(expected.clone()));
550
551        let in_list = format!("[{text}]");
552        assert_eq!(
553            buffer(&in_list).unwrap(),
554            Value::Array(alloc::vec![Value::Object(expected.clone())])
555        );
556
557        let BufferedObject(object) = serde_json::from_str(&format!(r#"{{"f": {text}}}"#)).unwrap();
558        assert_eq!(object["f"], Value::Object(expected));
559    }
560
561    #[test]
562    fn the_raw_value_key_is_data_in_a_value_that_is_already_built() {
563        // A payload buffered once is decoded again from the `Value`, where
564        // `serde_json`'s own impl would parse the string.
565        let built = json!({ "f": [{ RAW_VALUE_KEY: "[1]" }] });
566        let BufferedValue(again) = BufferedValue::deserialize(built.clone()).unwrap();
567        assert_eq!(again, built);
568        let BufferedObject(object) = BufferedObject::deserialize(built.clone()).unwrap();
569        assert_eq!(Value::Object(object), built);
570    }
571
572    #[test]
573    fn nested_raw_value_strings_do_not_add_depth() {
574        // Parsed as JSON, this is 3 * 121 levels deep. As data it is 120
575        // arrays around one object.
576        let text = nested_raw_values(3, 120);
577        let value = buffer(&text).unwrap();
578        assert_eq!(depth(&value), 121);
579
580        let too_deep = nested_raw_values(1, 128);
581        let err = buffer(&too_deep).unwrap_err();
582        assert!(err.to_string().contains("recursion limit"), "{err}");
583    }
584
585    #[test]
586    fn an_object_buffer_accepts_what_a_serde_json_map_accepts() {
587        for text in ["{}", r#"{"a": [1]}"#, "null", "[]", "1", r#""x""#, "true"] {
588            let expected =
589                serde_json::from_str::<Map<String, Value>>(text).map_err(|e| e.to_string());
590            let got = serde_json::from_str(text)
591                .map(|BufferedObject(o)| o)
592                .map_err(|e| e.to_string());
593            assert_eq!(got, expected, "{text}");
594
595            // The same input as a `Value` that is already built.
596            let built: Value = serde_json::from_str(text).unwrap();
597            let expected =
598                Map::<String, Value>::deserialize(built.clone()).map_err(|e| e.to_string());
599            let got = BufferedObject::deserialize(built)
600                .map(|BufferedObject(o)| o)
601                .map_err(|e| e.to_string());
602            assert_eq!(got, expected, "{text}");
603        }
604        assert!(serde_json::from_str::<BufferedObject>("null").is_err());
605        assert!(BufferedObject::deserialize(Value::Null).is_err());
606    }
607
608    #[test]
609    fn the_field_functions_read_the_raw_value_key_as_data() {
610        #[derive(Debug, serde::Deserialize)]
611        struct Fields {
612            #[serde(deserialize_with = "value")]
613            required: Value,
614            #[serde(default, deserialize_with = "opt_value")]
615            optional: Option<Value>,
616            #[serde(deserialize_with = "object")]
617            named: Map<String, Value>,
618            #[serde(flatten, deserialize_with = "object")]
619            rest: Map<String, Value>,
620        }
621
622        let hidden = json!({ RAW_VALUE_KEY: "[1]" });
623        let built = json!({
624            "required": hidden,
625            "optional": hidden,
626            "named": { "a": hidden },
627            "other": hidden,
628        });
629        let from_text: Fields = serde_json::from_str(&built.to_string()).unwrap();
630        let from_value: Fields = serde_json::from_value(built).unwrap();
631        for fields in [from_text, from_value] {
632            assert_eq!(fields.required, hidden);
633            assert_eq!(fields.optional, Some(hidden.clone()));
634            assert_eq!(fields.named["a"], hidden);
635            assert_eq!(fields.rest["other"], hidden);
636        }
637
638        for text in [
639            r#"{"required": 1, "named": {}}"#,
640            r#"{"required": 1, "named": {}, "optional": null}"#,
641        ] {
642            let fields: Fields = serde_json::from_str(text).unwrap();
643            assert_eq!(fields.optional, None, "{text}");
644        }
645        let err = serde_json::from_str::<Fields>(r#"{"required": 1, "named": null}"#).unwrap_err();
646        assert!(err.to_string().contains("expected a map"), "{err}");
647    }
648
649    #[test]
650    fn a_field_with_a_field_function_and_no_default_is_required() {
651        #[derive(Debug, serde::Deserialize)]
652        struct Fields {
653            #[serde(deserialize_with = "opt_value")]
654            #[allow(dead_code)]
655            optional: Option<Value>,
656        }
657
658        let err = serde_json::from_str::<Fields>("{}").unwrap_err();
659        assert!(
660            err.to_string().contains("missing field `optional`"),
661            "{err}"
662        );
663    }
664
665    #[test]
666    fn a_buffer_converts_into_what_it_holds() {
667        let built = json!({ "a": [1] });
668        let buffered = BufferedValue::deserialize(built.clone()).unwrap();
669        assert_eq!(buffered, BufferedValue(built.clone()));
670        assert_eq!(Value::from(buffered), built);
671
672        let object = BufferedObject::deserialize(built.clone()).unwrap();
673        assert_eq!(Value::Object(object.into()), built);
674    }
675
676    #[test]
677    fn a_float_with_no_json_form_buffers_as_null() {
678        use serde::de::value::{Error, F64Deserializer};
679        for v in [f64::NAN, f64::INFINITY] {
680            let BufferedValue(value) =
681                BufferedValue::deserialize(F64Deserializer::<Error>::new(v)).unwrap();
682            assert_eq!(value, Value::Null);
683        }
684    }
685
686    #[test]
687    fn wide_integers_buffer_as_serde_json_does() {
688        use serde::de::value::{Error, I128Deserializer, U128Deserializer};
689        let small = BufferedValue::deserialize(I128Deserializer::<Error>::new(-5)).unwrap();
690        assert_eq!(small.0, json!(-5));
691        let small = BufferedValue::deserialize(U128Deserializer::<Error>::new(5)).unwrap();
692        assert_eq!(small.0, json!(5));
693        let wide = U128Deserializer::<Error>::new(u128::MAX);
694        assert_eq!(
695            BufferedValue::deserialize(wide).map(|v| v.0).ok(),
696            Value::deserialize(U128Deserializer::<Error>::new(u128::MAX)).ok(),
697        );
698    }
699
700    const CHARGED_OUT: &str = "charged out";
701
702    /// Buffers `text` through [`ChargingValue`] at `per_member` bytes for each
703    /// object member and `per_element` for each array element, and returns
704    /// the result with the bytes left of `limit`.
705    fn charge_at(
706        text: &str,
707        per_member: usize,
708        per_element: usize,
709        limit: usize,
710    ) -> (serde_json::Result<Value>, usize) {
711        let remaining = Cell::new(limit);
712        let budget = Budget {
713            remaining: &remaining,
714            per_member,
715            per_element,
716            limit_msg: CHARGED_OUT,
717        };
718        let result =
719            ChargingValue(budget).deserialize(&mut serde_json::Deserializer::from_str(text));
720        (result, remaining.get())
721    }
722
723    /// [`charge_at`] with one rate, `per_value`, for members and elements.
724    fn charge(text: &str, per_value: usize, limit: usize) -> (serde_json::Result<Value>, usize) {
725        charge_at(text, per_value, per_value, limit)
726    }
727
728    #[test]
729    fn a_charging_buffer_builds_what_a_plain_buffer_does() {
730        for text in [
731            "null",
732            "true",
733            "-1",
734            "1.5",
735            r#""x""#,
736            "[1,[2,[3,{}]]]",
737            r#"{"a":1,"b":{"c":[true,false]},"a":2}"#,
738            r#"{"$serde_json::private::RawValue":"[1]"}"#,
739            r#"{"$serde_json::private::Number":"1"}"#,
740        ] {
741            let got = charge(text, 1, usize::MAX).0.map_err(|e| e.to_string());
742            let expected = serde_json::from_str::<BufferedValue>(text)
743                .map(|BufferedValue(v)| v)
744                .map_err(|e| e.to_string());
745            assert_eq!(got, expected, "{text}");
746        }
747    }
748
749    #[test]
750    fn a_charging_buffer_reads_the_raw_value_key_as_data() {
751        let text = json!({ RAW_VALUE_KEY: "[1]" }).to_string();
752        let value = charge(&text, 1, usize::MAX).0.unwrap();
753        assert_eq!(value[RAW_VALUE_KEY], Value::String("[1]".to_string()));
754    }
755
756    /// Four values are admitted: the members `a` and `b`, and the two
757    /// elements of `b`'s array. Scalars at the top level cost nothing.
758    #[test]
759    fn each_array_element_and_object_member_is_charged_once() {
760        let text = r#"{"a":1,"b":[1,2]}"#;
761        let (value, left) = charge(text, 1, 10);
762        assert_eq!(value.unwrap(), json!({"a":1,"b":[1,2]}));
763        assert_eq!(left, 6);
764
765        // Each charge is `per_value` bytes.
766        assert_eq!(charge(text, 64, 1000).1, 1000 - 4 * 64);
767
768        assert_eq!(charge("7", 1, 0).0.unwrap(), json!(7));
769        assert_eq!(charge("[]", 1, 0).0.unwrap(), json!([]));
770        assert_eq!(charge("{}", 1, 0).0.unwrap(), json!({}));
771    }
772
773    /// A member and an element are charged at their own rates, at every
774    /// depth.
775    #[test]
776    fn members_and_elements_are_charged_at_their_own_rates() {
777        // Three members (`a`, `b`, `c`) and four elements: three in `a`'s
778        // array and one in `c`'s.
779        let text = r#"{"a":[1,{"b":2,"c":[3]},4]}"#;
780        let (value, left) = charge_at(text, 100, 1, 1000);
781        assert_eq!(value.unwrap(), json!({"a":[1,{"b":2,"c":[3]},4]}));
782        assert_eq!(left, 1000 - (3 * 100 + 4));
783
784        // One byte short of the last member's charge.
785        let (result, _) = charge_at(text, 100, 1, 303);
786        let err = result.unwrap_err();
787        assert!(err.to_string().starts_with(CHARGED_OUT), "{err}");
788    }
789
790    #[test]
791    fn a_charge_larger_than_what_is_left_fails_and_leaves_the_rest() {
792        let text = r#"{"a":1,"b":[1,2]}"#;
793        // Three values fit in 7 bytes at 2 bytes each. The fourth is refused,
794        // and the odd byte stays.
795        let (result, left) = charge(text, 2, 7);
796        let err = result.unwrap_err();
797        assert!(err.to_string().starts_with(CHARGED_OUT), "{err}");
798        assert_eq!(left, 1);
799
800        // The exact fit is accepted.
801        let (result, left) = charge(text, 2, 8);
802        assert!(result.is_ok());
803        assert_eq!(left, 0);
804    }
805
806    /// The failed charge ends the parse where it happens. The text after it is
807    /// not valid JSON, and the error is the budget's.
808    #[test]
809    fn a_failed_charge_stops_before_the_rest_of_the_input_is_read() {
810        let (result, left) = charge("[1,2,!", 1, 1);
811        let err = result.unwrap_err();
812        assert!(err.to_string().starts_with(CHARGED_OUT), "{err}");
813        assert_eq!(left, 0);
814
815        let (result, _) = charge(r#"{"a":[1,2],"b":!"#, 1, 2);
816        let err = result.unwrap_err();
817        assert!(err.to_string().starts_with(CHARGED_OUT), "{err}");
818    }
819
820    /// The object buffer charges its own members too, and it reads a `Value`
821    /// that is already built as it reads JSON text. A nested `Any` payload
822    /// reaches it in that form.
823    #[test]
824    fn an_object_buffer_charges_from_text_and_from_a_built_value() {
825        let text = r#"{"a":{"b":[1,2,3]},"c":null}"#;
826        let expected = json!({"a":{"b":[1,2,3]},"c":null});
827
828        // The members `a`, `b` and `c` at 10 bytes each, and three elements
829        // at 1 byte each.
830        let remaining = Cell::new(33);
831        let from_text = charged_object(
832            &mut serde_json::Deserializer::from_str(text),
833            &remaining,
834            10,
835            1,
836            CHARGED_OUT,
837        )
838        .unwrap();
839        assert_eq!(Value::Object(from_text), expected);
840        assert_eq!(remaining.get(), 0);
841
842        let remaining = Cell::new(33);
843        let from_value = charged_object(expected.clone(), &remaining, 10, 1, CHARGED_OUT).unwrap();
844        assert_eq!(Value::Object(from_value), expected);
845        assert_eq!(remaining.get(), 0);
846
847        let remaining = Cell::new(32);
848        let err = charged_object(expected, &remaining, 10, 1, CHARGED_OUT).unwrap_err();
849        assert!(err.to_string().starts_with(CHARGED_OUT), "{err}");
850    }
851
852    #[test]
853    fn a_charged_object_buffer_accepts_what_a_plain_one_accepts() {
854        let remaining = Cell::new(usize::MAX);
855        for text in ["{}", r#"{"a": [1]}"#, "null", "[]", "1", r#""x""#, "true"] {
856            let expected =
857                object(&mut serde_json::Deserializer::from_str(text)).map_err(|e| e.to_string());
858            let got = charged_object(
859                &mut serde_json::Deserializer::from_str(text),
860                &remaining,
861                1,
862                1,
863                CHARGED_OUT,
864            )
865            .map_err(|e| e.to_string());
866            assert_eq!(got, expected, "{text}");
867
868            // The same input as a `Value` that is already built.
869            let built: Value = serde_json::from_str(text).unwrap();
870            let expected = object(built.clone()).map_err(|e| e.to_string());
871            let got =
872                charged_object(built, &remaining, 1, 1, CHARGED_OUT).map_err(|e| e.to_string());
873            assert_eq!(got, expected, "{text}");
874        }
875    }
876}