Macaw.Layers.Limits (macaw_layers v0.5.0)

Copy Markdown View Source

Sanity limits on a document read from elsewhere (spec/01 §5).

LimitDefaultBounds
bytes8_000_000the encoded document's size
depth64how deeply objects and arrays nest; the document itself is depth 1
items100_000the 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

Types

A limit's name.

t()

The limits a reader applies, one positive integer per name.

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

name()

@type name() :: :bytes | :depth | :items

A limit's name.

t()

@type t() :: %{required(name()) => pos_integer()}

The limits a reader applies, one positive integer per name.

Functions

defaults()

@spec defaults() :: t()

The system's sanity values.

new(given)

@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!(given)

@spec new!(keyword() | map()) :: t()

new/1, or an ArgumentError naming every fault: a host's limits written in code.

structure(term, limits)

@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.