Skip to main content

jsonx_lib/
limits.rs

1//! Budgets on what a document may cost to read.
2
3/// Budgets on the work and memory a document may cost.
4///
5/// Every budget is checked before the memory it guards is allocated (with
6/// the one exception noted under "What a tree costs"), so a hostile document
7/// is refused while it is still cheap to refuse. None of them
8/// is there to protect the stack: the parser, the writer, and every operation
9/// on [`Value`](crate::Value) use a bounded amount of stack whatever the
10/// nesting depth (explicit stacks on the heap; drop recurses at most a fixed
11/// 32 levels). The depth budget exists for the code that consumes the value,
12/// which may well be recursive.
13///
14/// | Budget | Default | Counts |
15/// |---|---:|---|
16/// | [`max_depth`](Self::max_depth) | 128 | nested arrays and objects; a scalar at the top is depth 0, `[]` is 1 |
17/// | [`max_input_bytes`](Self::max_input_bytes) | 64 MiB | bytes of input (of each document, for a stream of documents) |
18/// | [`max_string_bytes`](Self::max_string_bytes) | 16 MiB | source bytes between a string's quotes, keys included |
19/// | [`max_number_bytes`](Self::max_number_bytes) | 1 KiB | bytes of a number's text |
20/// | [`max_elements`](Self::max_elements) | 1 Mi | values in the document: every scalar, array, and object counts one |
21/// | [`max_memory`](Self::max_memory) | 64 MiB | heap one read call holds for what it builds: a tree, or a typed value (see below) |
22/// | [`max_value_bytes`](Self::max_value_bytes) | 64 MiB | bytes of input a [`StreamReader`](crate::StreamReader) holds for one value a whole-value call is waiting on |
23///
24/// The depth default matches `serde_json`'s recursion limit, so code moving
25/// from it sees the same behaviour. A string's budget is measured in source
26/// bytes, which is never less than its decoded length, so the check can run
27/// before the string is decoded.
28///
29/// **What a tree costs.** A parsed value holds, besides the borrowed input,
30/// `size_of::<Value>()` bytes for every value (32 on a 64-bit target), the
31/// same again for every object member's key (24 bytes for the key, so 56
32/// per member), and the decoded text of every string or key that had
33/// escapes. A compact document spends a few bytes of input per value, so the
34/// tree can be several times the input: under the defaults a hostile
35/// document can make one parse hold at most about [`max_memory`](Self::max_memory)
36/// (64 MiB), whatever its shape. That is the number to multiply by the
37/// parses that may run at once; a server taking many requests should lower
38/// it (and `max_input_bytes`) to what its messages need.
39///
40/// `max_memory` counts the buffers a parse asks for (the tree and the
41/// builder's working stacks, at their capacity), checked before a stack
42/// grows and before each array or object is allocated; a decoded string is
43/// counted once made, so a parse may hold one string budget beyond it. The
44/// allocator's own overhead is not counted. It applies wherever a tree is
45/// built ([`Parser::parse`](crate::Parser::parse), [`Reader::read_value`](crate::Reader::read_value),
46/// [`StreamReader::read_value`](crate::StreamReader::read_value)), and to
47/// typed reads ([`FromJson`](crate::FromJson) through `decode`, `from_str`,
48/// and the stream reader's `decode`). The count is per call: each
49/// top-level `parse`, `read_value`, or `decode` call starts it afresh, and
50/// every read nested inside that call (a `Value` field of a typed decode, a
51/// `decode` made by a `FromJson` impl) shares it. So the budget bounds what
52/// one call builds, which is what the caller then holds: reading a large
53/// array item by item with [`Reader::read_value`](crate::Reader::read_value)
54/// or [`Reader::decode`](crate::Reader::decode), dropping each item, is
55/// never refused for the total, however large, as in 0.2. The crate's own impls charge what
56/// they hold: owned strings at their capacity, vectors at their buffer's
57/// size as it doubles, boxes at their contents' size, and maps and sets at
58/// an estimate of about twice their entries' size (a B-tree's or hash
59/// table's spare room is not measured exactly); your own `FromJson` impls
60/// are charged for the crate types they read.
61///
62/// Separately, the reader's own state is bounded by the same number: under
63/// [`DuplicateKeys::Error`](crate::DuplicateKeys::Error) the duplicate check
64/// keeps about 56 bytes per key of the objects still open (and a stream
65/// reader a copy of each key), and a key past `max_memory` of that is
66/// refused. Reading events with no check keeps only a bit per open
67/// container. So one read call holds at most about `max_memory`
68/// for what it builds, plus as much again for the duplicate check's state
69/// in the worst case.
70///
71/// The struct is `#[non_exhaustive]`: start from [`Limits::default`] or
72/// [`Limits::unlimited`] and change the fields you care about, or chain the
73/// `with_*` methods.
74///
75/// # Examples
76///
77/// ```
78/// use jsonx_lib::{Limits, Parser, ErrorKind};
79///
80/// let strict = Parser::new().limits(Limits::default().with_max_depth(2));
81/// assert!(strict.parse("[[1]]").is_ok());
82/// let err = strict.parse("[[[1]]]").unwrap_err();
83/// assert_eq!(err.kind(), ErrorKind::DepthLimitExceeded);
84/// assert_eq!(err.offset(), 2);
85///
86/// let mut limits = Limits::default();
87/// limits.max_string_bytes = 4;
88/// assert!(Parser::new().limits(limits).parse(r#""abcde""#).is_err());
89/// ```
90#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
91#[non_exhaustive]
92pub struct Limits {
93    /// The deepest nesting of arrays and objects allowed. `0` allows only a
94    /// scalar document.
95    pub max_depth: usize,
96    /// The longest input accepted, in bytes.
97    ///
98    /// A [`StreamReader`](crate::StreamReader) in
99    /// [`documents`](crate::StreamReader::documents) mode applies it to each
100    /// document instead: the bytes fed since the current document began (or,
101    /// between documents, since the last one ended), so a long-lived stream
102    /// of documents is never refused for its total. Outside that mode it
103    /// bounds all the input, as for a complete document.
104    pub max_input_bytes: usize,
105    /// The longest string or key accepted, in source bytes between the quotes
106    /// (escape sequences count at their written length).
107    pub max_string_bytes: usize,
108    /// The longest number accepted, in bytes of its text.
109    pub max_number_bytes: usize,
110    /// The most values a document may hold, counting every scalar, array, and
111    /// object (keys are not counted separately).
112    pub max_elements: usize,
113    /// The most heap, in bytes, one read call may hold for the tree or the
114    /// typed value it builds; see "What a tree costs" above.
115    pub max_memory: usize,
116    /// The most input, in bytes, a [`StreamReader`](crate::StreamReader)
117    /// holds for one value that a whole-value call
118    /// ([`read_raw`](crate::StreamReader::read_raw),
119    /// [`read_value`](crate::StreamReader::read_value),
120    /// [`decode`](crate::StreamReader::decode)) is waiting on: such a call
121    /// keeps the value's text, whitespace included, until the value ends.
122    /// Counted from the value's first byte; a [`feed`](crate::StreamReader::feed)
123    /// that would take it past this is refused with
124    /// [`ErrorKind::InputTooLarge`](crate::ErrorKind::InputTooLarge).
125    /// [`next_event`](crate::StreamReader::next_event) holds no value and is
126    /// not affected. The other readers have the whole input already and do
127    /// not use it.
128    ///
129    /// The default equals the default `max_input_bytes`. It matters when
130    /// `max_input_bytes` is raised for a long-lived stream: it still bounds
131    /// what one pending call can make the reader hold.
132    pub max_value_bytes: usize,
133}
134
135impl Limits {
136    /// The default budgets (see the table on [`Limits`]): generous for real
137    /// documents, and bounding what a hostile one can make a read hold (about
138    /// `max_memory`, see above) whatever its size or shape.
139    ///
140    /// # Examples
141    ///
142    /// ```
143    /// use jsonx_lib::Limits;
144    ///
145    /// assert_eq!(Limits::new().max_depth, 128);
146    /// assert_eq!(Limits::new(), Limits::default());
147    /// ```
148    #[must_use]
149    pub const fn new() -> Self {
150        Self {
151            max_depth: 128,
152            max_input_bytes: 64 * 1024 * 1024,
153            max_string_bytes: 16 * 1024 * 1024,
154            max_number_bytes: 1024,
155            max_elements: 1024 * 1024,
156            max_memory: 64 * 1024 * 1024,
157            max_value_bytes: 64 * 1024 * 1024,
158        }
159    }
160
161    /// No budgets at all: every limit is `usize::MAX`. For input you trust;
162    /// even then the parser cannot overflow the stack, because nothing in this
163    /// crate recurses on nesting depth.
164    ///
165    /// # Examples
166    ///
167    /// ```
168    /// use jsonx_lib::{Limits, Parser};
169    ///
170    /// let deep = format!("{}{}", "[".repeat(1000), "]".repeat(1000));
171    /// assert!(Parser::new().limits(Limits::unlimited()).parse(&deep).is_ok());
172    /// ```
173    #[must_use]
174    pub const fn unlimited() -> Self {
175        Self {
176            max_depth: usize::MAX,
177            max_input_bytes: usize::MAX,
178            max_string_bytes: usize::MAX,
179            max_number_bytes: usize::MAX,
180            max_elements: usize::MAX,
181            max_memory: usize::MAX,
182            max_value_bytes: usize::MAX,
183        }
184    }
185
186    /// Sets [`max_depth`](Self::max_depth).
187    ///
188    /// # Examples
189    ///
190    /// ```
191    /// use jsonx_lib::Limits;
192    ///
193    /// assert_eq!(Limits::new().with_max_depth(8).max_depth, 8);
194    /// ```
195    #[must_use]
196    pub const fn with_max_depth(mut self, depth: usize) -> Self {
197        self.max_depth = depth;
198        self
199    }
200
201    /// Sets [`max_input_bytes`](Self::max_input_bytes).
202    ///
203    /// # Examples
204    ///
205    /// ```
206    /// use jsonx_lib::{ErrorKind, Limits, Parser};
207    ///
208    /// let p = Parser::new().limits(Limits::new().with_max_input_bytes(4));
209    /// assert!(p.parse("1234").is_ok());
210    /// assert_eq!(p.parse("12345").unwrap_err().kind(), ErrorKind::InputTooLarge);
211    /// ```
212    #[must_use]
213    pub const fn with_max_input_bytes(mut self, bytes: usize) -> Self {
214        self.max_input_bytes = bytes;
215        self
216    }
217
218    /// Sets [`max_string_bytes`](Self::max_string_bytes).
219    ///
220    /// # Examples
221    ///
222    /// ```
223    /// use jsonx_lib::{ErrorKind, Limits, Parser};
224    ///
225    /// let p = Parser::new().limits(Limits::new().with_max_string_bytes(2));
226    /// assert!(p.parse(r#"{"ab": "cd"}"#).is_ok());
227    /// assert_eq!(p.parse(r#"{"abc": 1}"#).unwrap_err().kind(), ErrorKind::StringTooLong);
228    /// ```
229    #[must_use]
230    pub const fn with_max_string_bytes(mut self, bytes: usize) -> Self {
231        self.max_string_bytes = bytes;
232        self
233    }
234
235    /// Sets [`max_number_bytes`](Self::max_number_bytes).
236    ///
237    /// # Examples
238    ///
239    /// ```
240    /// use jsonx_lib::{ErrorKind, Limits, Parser};
241    ///
242    /// let p = Parser::new().limits(Limits::new().with_max_number_bytes(3));
243    /// assert!(p.parse("-12").is_ok());
244    /// assert_eq!(p.parse("1e10").unwrap_err().kind(), ErrorKind::NumberTooLong);
245    /// ```
246    #[must_use]
247    pub const fn with_max_number_bytes(mut self, bytes: usize) -> Self {
248        self.max_number_bytes = bytes;
249        self
250    }
251
252    /// Sets [`max_elements`](Self::max_elements).
253    ///
254    /// # Examples
255    ///
256    /// ```
257    /// use jsonx_lib::{ErrorKind, Limits, Parser};
258    ///
259    /// // The array itself is one value, so `[1, 2]` holds three.
260    /// let p = Parser::new().limits(Limits::new().with_max_elements(3));
261    /// assert!(p.parse("[1, 2]").is_ok());
262    /// assert_eq!(p.parse("[1, 2, 3]").unwrap_err().kind(), ErrorKind::TooManyElements);
263    /// ```
264    #[must_use]
265    pub const fn with_max_elements(mut self, count: usize) -> Self {
266        self.max_elements = count;
267        self
268    }
269
270    /// Sets [`max_memory`](Self::max_memory).
271    ///
272    /// # Examples
273    ///
274    /// ```
275    /// use jsonx_lib::{ErrorKind, Limits, Parser};
276    ///
277    /// let p = Parser::new().limits(Limits::new().with_max_memory(4096));
278    /// assert!(p.parse("[1, 2, 3]").is_ok());
279    /// let big = format!("[{}0]", "0,".repeat(1000));
280    /// assert_eq!(p.parse(&big).unwrap_err().kind(), ErrorKind::MemoryLimitExceeded);
281    /// ```
282    #[must_use]
283    pub const fn with_max_memory(mut self, bytes: usize) -> Self {
284        self.max_memory = bytes;
285        self
286    }
287
288    /// Sets [`max_value_bytes`](Self::max_value_bytes).
289    ///
290    /// # Examples
291    ///
292    /// ```
293    /// use jsonx_lib::{ErrorKind, Limits, Parser, Step};
294    ///
295    /// let limits = Limits::new().with_max_input_bytes(usize::MAX).with_max_value_bytes(8);
296    /// let mut r = Parser::new().limits(limits).stream_reader();
297    /// r.feed(b"[1, ")?;
298    /// assert_eq!(r.read_value()?, Step::NeedInput);
299    /// let err = r.feed(b"2, 3, 4]").unwrap_err();
300    /// assert_eq!((err.kind(), err.offset()), (ErrorKind::InputTooLarge, 8));
301    /// # Ok::<(), jsonx_lib::Error>(())
302    /// ```
303    #[must_use]
304    pub const fn with_max_value_bytes(mut self, bytes: usize) -> Self {
305        self.max_value_bytes = bytes;
306        self
307    }
308}
309
310impl Default for Limits {
311    #[inline]
312    fn default() -> Self {
313        Self::new()
314    }
315}
316
317#[cfg(test)]
318mod tests {
319    use super::*;
320
321    #[test]
322    fn test_limits_default_matches_documented_table() {
323        let l = Limits::default();
324        assert_eq!(l.max_depth, 128);
325        assert_eq!(l.max_input_bytes, 64 << 20);
326        assert_eq!(l.max_string_bytes, 16 << 20);
327        assert_eq!(l.max_number_bytes, 1024);
328        assert_eq!(l.max_elements, 1 << 20);
329        assert_eq!(l.max_memory, 64 << 20);
330        assert_eq!(l.max_value_bytes, 64 << 20);
331    }
332
333    #[test]
334    fn test_limits_setters_chain() {
335        let l = Limits::unlimited()
336            .with_max_depth(1)
337            .with_max_input_bytes(2)
338            .with_max_string_bytes(3)
339            .with_max_number_bytes(4)
340            .with_max_elements(5)
341            .with_max_memory(6)
342            .with_max_value_bytes(7);
343        assert_eq!(
344            (
345                l.max_depth,
346                l.max_input_bytes,
347                l.max_string_bytes,
348                l.max_number_bytes,
349                l.max_elements,
350                l.max_memory,
351                l.max_value_bytes
352            ),
353            (1, 2, 3, 4, 5, 6, 7)
354        );
355    }
356}