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