#[non_exhaustive]pub struct Limits {
pub max_depth: usize,
pub max_input_bytes: usize,
pub max_string_bytes: usize,
pub max_number_bytes: usize,
pub max_elements: usize,
pub max_memory: usize,
pub max_value_bytes: usize,
}Expand description
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 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 | 128 | nested arrays and objects; a scalar at the top is depth 0, [] is 1 |
max_input_bytes | 64 MiB | bytes of input (of each document, for a stream of documents) |
max_string_bytes | 16 MiB | source bytes between a string’s quotes, keys included |
max_number_bytes | 1 KiB | bytes of a number’s text |
max_elements | 1 Mi | values in the document: every scalar, array, and object counts one |
max_memory | 64 MiB | heap one read call holds for what it builds: a tree, or a typed value (see below) |
max_value_bytes | 64 MiB | bytes of input a 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
(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, Reader::read_value,
StreamReader::read_value), and to
typed reads (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
or 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 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());Fields (Non-exhaustive)§
This struct is marked as non-exhaustive
Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.max_depth: usizeThe deepest nesting of arrays and objects allowed. 0 allows only a
scalar document.
max_input_bytes: usizeThe longest input accepted, in bytes.
A StreamReader in
documents mode applies it to each
document instead: the bytes fed since the current document began (or,
between documents, since the last one ended), so a long-lived stream
of documents is never refused for its total. Outside that mode it
bounds all the input, as for a complete document.
max_string_bytes: usizeThe longest string or key accepted, in source bytes between the quotes (escape sequences count at their written length).
max_number_bytes: usizeThe longest number accepted, in bytes of its text.
max_elements: usizeThe most values a document may hold, counting every scalar, array, and object (keys are not counted separately).
max_memory: usizeThe most heap, in bytes, one read call may hold for the tree or the typed value it builds; see “What a tree costs” above.
max_value_bytes: usizeThe most input, in bytes, a StreamReader
holds for one value that a whole-value call
(read_raw,
read_value,
decode) is waiting on: such a call
keeps the value’s text, whitespace included, until the value ends.
Counted from the value’s first byte; a feed
that would take it past this is refused with
ErrorKind::InputTooLarge.
next_event holds no value and is
not affected. The other readers have the whole input already and do
not use it.
The default equals the default max_input_bytes. It matters when
max_input_bytes is raised for a long-lived stream: it still bounds
what one pending call can make the reader hold.
Implementations§
Source§impl Limits
impl Limits
Sourcepub const fn new() -> Self
pub const fn new() -> Self
The default budgets (see the table on Limits): generous for real
documents, and bounding what a hostile one can make a read hold (about
max_memory, see above) whatever its size or shape.
§Examples
use jsonx_lib::Limits;
assert_eq!(Limits::new().max_depth, 128);
assert_eq!(Limits::new(), Limits::default());Sourcepub const fn unlimited() -> Self
pub const fn unlimited() -> Self
No budgets at all: every limit is usize::MAX. For input you trust;
even then the parser cannot overflow the stack, because nothing in this
crate recurses on nesting depth.
§Examples
use jsonx_lib::{Limits, Parser};
let deep = format!("{}{}", "[".repeat(1000), "]".repeat(1000));
assert!(Parser::new().limits(Limits::unlimited()).parse(&deep).is_ok());Sourcepub const fn with_max_depth(self, depth: usize) -> Self
pub const fn with_max_depth(self, depth: usize) -> Self
Sourcepub const fn with_max_input_bytes(self, bytes: usize) -> Self
pub const fn with_max_input_bytes(self, bytes: usize) -> Self
Sets max_input_bytes.
§Examples
use jsonx_lib::{ErrorKind, Limits, Parser};
let p = Parser::new().limits(Limits::new().with_max_input_bytes(4));
assert!(p.parse("1234").is_ok());
assert_eq!(p.parse("12345").unwrap_err().kind(), ErrorKind::InputTooLarge);Sourcepub const fn with_max_string_bytes(self, bytes: usize) -> Self
pub const fn with_max_string_bytes(self, bytes: usize) -> Self
Sets max_string_bytes.
§Examples
use jsonx_lib::{ErrorKind, Limits, Parser};
let p = Parser::new().limits(Limits::new().with_max_string_bytes(2));
assert!(p.parse(r#"{"ab": "cd"}"#).is_ok());
assert_eq!(p.parse(r#"{"abc": 1}"#).unwrap_err().kind(), ErrorKind::StringTooLong);Sourcepub const fn with_max_number_bytes(self, bytes: usize) -> Self
pub const fn with_max_number_bytes(self, bytes: usize) -> Self
Sets max_number_bytes.
§Examples
use jsonx_lib::{ErrorKind, Limits, Parser};
let p = Parser::new().limits(Limits::new().with_max_number_bytes(3));
assert!(p.parse("-12").is_ok());
assert_eq!(p.parse("1e10").unwrap_err().kind(), ErrorKind::NumberTooLong);Sourcepub const fn with_max_elements(self, count: usize) -> Self
pub const fn with_max_elements(self, count: usize) -> Self
Sets max_elements.
§Examples
use jsonx_lib::{ErrorKind, Limits, Parser};
// The array itself is one value, so `[1, 2]` holds three.
let p = Parser::new().limits(Limits::new().with_max_elements(3));
assert!(p.parse("[1, 2]").is_ok());
assert_eq!(p.parse("[1, 2, 3]").unwrap_err().kind(), ErrorKind::TooManyElements);Sourcepub const fn with_max_memory(self, bytes: usize) -> Self
pub const fn with_max_memory(self, bytes: usize) -> Self
Sets max_memory.
§Examples
use jsonx_lib::{ErrorKind, Limits, Parser};
let p = Parser::new().limits(Limits::new().with_max_memory(4096));
assert!(p.parse("[1, 2, 3]").is_ok());
let big = format!("[{}0]", "0,".repeat(1000));
assert_eq!(p.parse(&big).unwrap_err().kind(), ErrorKind::MemoryLimitExceeded);Sourcepub const fn with_max_value_bytes(self, bytes: usize) -> Self
pub const fn with_max_value_bytes(self, bytes: usize) -> Self
Sets max_value_bytes.
§Examples
use jsonx_lib::{ErrorKind, Limits, Parser, Step};
let limits = Limits::new().with_max_input_bytes(usize::MAX).with_max_value_bytes(8);
let mut r = Parser::new().limits(limits).stream_reader();
r.feed(b"[1, ")?;
assert_eq!(r.read_value()?, Step::NeedInput);
let err = r.feed(b"2, 3, 4]").unwrap_err();
assert_eq!((err.kind(), err.offset()), (ErrorKind::InputTooLarge, 8));