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