# `Kettlecorn.ETF`
[🔗](https://github.com/mjrusso/kettlecorn/blob/v0.1.0/host/lib/kettlecorn/etf.ex#L1)

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.

# `decode_error`

```elixir
@type decode_error() :: :badarg | :too_deep | :too_large | {:unsupported, atom()}
```

# `decode`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
