A strict decoder for terms produced by the (untrusted) guest VM.
:erlang.binary_to_term/2 with [:safe] is unsuitable for guest data:
- it decodes pids, ports and references into live host terms: a guest pid with the host's node name can identify a host process;
- it decodes local funs referencing host modules;
- it fails on any atom the host doesn't know.
This decoder only produces plain data. Atoms are returned when they already
exist on the host and as {:unknown_atom, name} tuples otherwise, so a
guest can never grow the host's atom table. Pids become Kettlecorn.Pid
handles for addressing the guest. Ports and references become
Kettlecorn.Opaque placeholders with no usable identity. Funs are rejected.
A map whose :__struct__ is an atom would be a struct of that module on
the host, and protocols dispatch on it: a guest could send a
%File.Stream{} with a path of its choice, and host code enumerating it
would read that file. Such maps decode as Kettlecorn.Struct, which holds
the module and the other fields as data.
Nesting depth and element counts are bounded. The :max_bytes budget
(default 64 MiB) charges retained binary data in full and estimates the
heap space for each decoded node; exceeding it returns :too_large.
Input slices are copied so decoded binaries cannot retain unrelated data.
PID handle copies and retained UTF-8 conversions of Latin-1 atom names
are charged separately.
For compressed terms, the budget counts the inflated data, and terms larger
than :max_bytes are rejected. A list of empty lists, for instance, takes 16 bytes
of heap per byte of input on a 64-bit host.
Summary
Functions
Decodes binary. Option :max_bytes sets the budget for retained binary
data and estimated heap space (default 64 MiB). Option :vm binds PID handles
to their originating VM; the default produces unbound handles.
Types
@type decode_error() :: :badarg | :too_deep | :too_large | {:unsupported, atom()}
Functions
@spec decode(binary(), keyword()) :: {:ok, term()} | {:error, decode_error()}
Decodes binary. Option :max_bytes sets the budget for retained binary
data and estimated heap space (default 64 MiB). Option :vm binds PID handles
to their originating VM; the default produces unbound handles.