Skip to main content

Limits

Struct Limits 

Source
#[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.

BudgetDefaultCounts
max_depth128nested arrays and objects; a scalar at the top is depth 0, [] is 1
max_input_bytes64 MiBbytes of input (of each document, for a stream of documents)
max_string_bytes16 MiBsource bytes between a string’s quotes, keys included
max_number_bytes1 KiBbytes of a number’s text
max_elements1 Mivalues in the document: every scalar, array, and object counts one
max_memory64 MiBheap one read call holds for what it builds: a tree, or a typed value (see below)
max_value_bytes64 MiBbytes 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
Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.
§max_depth: usize

The deepest nesting of arrays and objects allowed. 0 allows only a scalar document.

§max_input_bytes: usize

The 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: usize

The longest string or key accepted, in source bytes between the quotes (escape sequences count at their written length).

§max_number_bytes: usize

The longest number accepted, in bytes of its text.

§max_elements: usize

The most values a document may hold, counting every scalar, array, and object (keys are not counted separately).

§max_memory: usize

The 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: usize

The 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

Source

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());
Source

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());
Source

pub const fn with_max_depth(self, depth: usize) -> Self

Sets max_depth.

§Examples
use jsonx_lib::Limits;

assert_eq!(Limits::new().with_max_depth(8).max_depth, 8);
Source

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);
Source

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);
Source

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);
Source

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);
Source

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);
Source

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));

Trait Implementations§

Source§

impl Clone for Limits

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Copy for Limits

Source§

impl Debug for Limits

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for Limits

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl Eq for Limits

Source§

impl Hash for Limits

Source§

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher. Read more
1.3.0 · Source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
Source§

impl PartialEq for Limits

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for Limits

Auto Trait Implementations§

§

impl Forget for Limits

§

impl Freeze for Limits

§

impl Move for Limits

§

impl RefUnwindSafe for Limits

§

impl Send for Limits

§

impl Sync for Limits

§

impl Unpin for Limits

§

impl UnsafeUnpin for Limits

§

impl UnwindSafe for Limits

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.