Sanity limits on a document read from elsewhere (spec/01 §5).
| Limit | Default | Bounds |
|---|---|---|
bytes | 8_000_000 | the encoded document's size |
depth | 64 | how deeply objects and arrays nest; the document itself is depth 1 |
items | 100_000 | the entries any one object or array holds |
They bound what reading a document can be made to cost. A host may tighten every
limit: a host loading untrusted input knows its inputs and lowers the numbers at its
layer, and a limit it does not name keeps its default. A host may raise a limit only
by saying so, per limit: {:raise, max} for a host whose inputs are trusted and large
(a bundle import). A plain value above the default is a fault, so no limit is loosened
by mistake.
A fault is {path, {:limit, name, max, given}}, worded by Macaw.Layers.Fault.format/2.
The walk over a decoded term is the generic part of visualize's
Visualize.Chart.Limits.structure/2.
Summary
Functions
The system's sanity values.
The limits a reader applies, given over defaults/0: {:ok, limits}, or every fault
of given by its name. A plain value tightens a limit; {:raise, max} raises it above
its default.
new/1, or an ArgumentError naming every fault: a host's limits written in code.
Every depth and items fault of a decoded term, ordered by path.
Types
@type name() :: :bytes | :depth | :items
A limit's name.
@type t() :: %{required(name()) => pos_integer()}
The limits a reader applies, one positive integer per name.
Functions
@spec defaults() :: t()
The system's sanity values.
@spec new(keyword() | map()) :: {:ok, t()} | {:error, [Macaw.Layers.Fault.t(), ...]}
The limits a reader applies, given over defaults/0: {:ok, limits}, or every fault
of given by its name. A plain value tightens a limit; {:raise, max} raises it above
its default.
The faults: a name that is not a limit, :unknown_key; a value that is neither a
positive integer nor {:raise, max}, {:limit_value, default}; a plain value above the
default, {:limit_loosened, default} (a host can't loosen a sanity limit by mistake);
a raise that is not above it, {:limit_not_raised, default}; and given neither a
keyword list nor a map, {:type, :keyword} at [].
iex> {:ok, limits} = Macaw.Layers.Limits.new(items: 10)
iex> limits.items
10
iex> {:ok, limits} = Macaw.Layers.Limits.new(items: {:raise, 500_000})
iex> limits.items
500000
iex> Macaw.Layers.Limits.new(items: 500_000, pages: 3)
{:error, [{[:items], {:limit_loosened, 100000}}, {[:pages], :unknown_key}]}
new/1, or an ArgumentError naming every fault: a host's limits written in code.
@spec structure(term(), t()) :: [Macaw.Layers.Fault.t()]
Every depth and items fault of a decoded term, ordered by path.
The term itself is depth 1. A struct is a leaf. Past the depth limit a branch is reported once, at the first map or list beyond it, and not walked further. A map or list over the items limit is reported at its own path, with the number of entries it holds.