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

Run untrusted Elixir and Erlang code on the server inside a WebAssembly sandbox.

Each VM runs OTP/BEAM with Popcorn's patches as a `wasm32-wasip3`
component in its own native launcher process with embedded Wasmtime. By default
the guest has no network, no OS processes, no native code loading and no access to the
host file system beyond a private copy of the runtime. Memory is capped
by default; CPU and wall-clock limits are opt-in. See `Kettlecorn.Sandbox`
for the limits and the opt-in network grants.

    {:ok, vm} = Kettlecorn.start_link(max_fuel: 50_000_000_000, max_lifetime: 30_000)
    {:ok,
     %{
       "value" => [{1, 1}, {2, 4}, {3, 9}],
       "inspected" => "[{1, 1}, {2, 4}, {3, 9}]"
     }} = Kettlecorn.eval(vm, "Enum.map(1..3, fn n -> {n, n * n} end)")

    {:ok, %{"output" => "hi\n", "value" => :ok}} = Kettlecorn.eval(vm, ~S|IO.puts("hi")|)

    {:error, %{"kind" => "timeout"}} =
      Kettlecorn.eval(vm, "Stream.repeatedly(fn -> 1 end) |> Stream.run()", timeout: 1_000)

    {:ok, %{"value" => 21}} = Kettlecorn.eval(vm, "X = 20. X + 1.", language: :erlang)
    Kettlecorn.stop(vm)

`max_fuel` bounds total execution in Wasmtime fuel units (roughly WebAssembly
instructions), and `max_lifetime: 30_000` caps elapsed time at 30 seconds.
Both limits include startup and apply across all evaluations in the VM.

`call/4` and `cast/3` reach GenServers in the guest (through the guest's
`Kettlecorn.Proxy`), and `send/4` delivers `{:wasm, payload}` to a
guest process. Messages the guest sends with
`Kettlecorn.Host.send/1` (see the [Guest API guide](guest-api.html))
arrive in the `:owner` process as
`{:kettlecorn, vm, {:message, term}}`, decoded by `Kettlecorn.ETF`. A
`Kettlecorn.Host.call/3` in the guest arrives as
`{:kettlecorn, vm, {:host_call, reply_to, name, args}}`; answer it with
`reply/3`. Owners call `acknowledge/2` after handling events to release their
delivery budget; exceeding that budget stops the VM.

Payloads sent to the guest must contain only atoms already loaded there;
its safe decoder rejects unknown atoms. Use strings for application data
whose labels are not part of the guest code.

Options are keyword lists with unique keys. Unknown keys and invalid
option values raise `ArgumentError`.

# `vm`

```elixir
@type vm() :: GenServer.server()
```

# `acknowledge`

```elixir
@spec acknowledge(vm(), pos_integer()) :: :ok
```

Acknowledges `count` owner events after handling them, releasing their delivery
budget. Only the VM's owner can acknowledge events. A count larger than the
number outstanding acknowledges all current events; the excess is ignored.
Event delivery preserves order.

# `call`

```elixir
@spec call(vm(), atom() | String.t(), term(), timeout()) ::
  {:ok, term()} | {:error, term()}
```

Calls a GenServer registered as `target` in the guest, like `GenServer.call/3`.

Returns `{:ok, reply}` or `{:error, reason}`. Common reasons are `:noproc`,
`:timeout`, `:request_queue_full`, `{:exit, inspected_reason}` and `{:vm_down, reason}`.
`:request_queue_full` means the VM's unanswered request limit was reached;
the request was not sent.
The guest can reject delivery with `:bad_payload` or `:bad_request`;
a malformed proxy reply returns `{:bad_reply, term}`.
After `timeout`, the host allows another 1000 milliseconds
for the guest's timeout reply.

# `cast`

```elixir
@spec cast(vm(), atom() | String.t(), term()) :: :ok
```

Casts `request` to a GenServer registered as `target` in the guest.
Returns `:ok` without confirming delivery.

# `close_stdin`

```elixir
@spec close_stdin(vm()) :: :ok
```

Signals the end of the guest's standard input.
Readers get `:eof` after consuming all queued bytes.

# `eval`

```elixir
@spec eval(vm(), String.t(), keyword()) :: {:ok, map()} | {:error, term()}
```

Evaluates Elixir or Erlang `code` in the guest.

Returns `{:ok, map}` with `"inspected"` (the formatted result), `"output"`
(captured standard output) and, for plain data of at most 1,000,000 terms, `"value"`.
On failure, returns `{:error, map}` with `"kind"` (`"error"`, `"exit"`,
`"throw"` or `"timeout"`), `"message"` and `"output"`.

Writes to stderr bypass evaluation capture and go to the VM's console output.
They are available through `take_output/1` and, when an `:owner` is configured,
`{:kettlecorn, vm, {:stderr, data}}` events.

The evaluator is a GenServer in the guest that `eval/3` reaches with
`call/4`, so it can also return `call/4`'s errors:

  * `{:error, {:vm_down, reason}}` - the whole VM died.
  * `{:error, :request_queue_full}` - the unanswered request limit was reached;
    the evaluation request was not sent.
  * `{:error, :timeout}` - the proxy received no evaluator reply by
    `:timeout` + 1000 milliseconds, or the host received no
    guest reply by `:timeout` + 2000 milliseconds. An evaluator
    that stops the code at `:timeout` and replies returns `"kind" => "timeout"`.
  * `{:error, :noproc}` - the evaluator isn't running (guest code can stop
    it or unregister its name).
  * `{:error, {:exit, inspected_reason}}` - the evaluator exited during
    the call.
  * `{:error, :bad_payload}` or `{:error, :bad_request}` - the guest
    rejected the request, for example because a binding contains an
    atom not loaded in the guest.
  * `{:error, {:bad_reply, term}}` - an answer of another shape (guest code
    can send one in the evaluator's place).

## Options

* `:timeout` (`t:timeout/0`) - Evaluation deadline in milliseconds, or `:infinity`. The default value is `5000`.

* `:binding` (map or list of variable/value pairs) - Variable names mapped to plain values. Names are converted to strings. The default value is `%{}`.

* `:language` - Language of the source code. The default value is `:elixir`.

Erlang `code` is either expressions, evaluated one after another like in
the Erlang shell (`"X = 20. X + 1."`; the last dot is optional), or a
module, starting with `-module(name).`, which is compiled and loaded and
returns `{:module, name}`. Bindings use Erlang variable names
(`binding: %{"N" => 21}`). Results and error messages use Erlang syntax.

The guest keeps up to 1,000,000 bytes of output, ending at a UTF-8 boundary;
`"output_truncated"` is `true` when there was more. Processes started by
the code keep running after success. On timeout, the evaluator
attempts to kill them through tracing, which guest code can disable. Use
VM limits to bound untrusted code.

# `reply`

```elixir
@spec reply(vm(), binary(), {:ok, term()} | {:error, String.t()}) :: :ok
```

Replies to a guest's `Kettlecorn.Host.call/3` using the `reply_to` from its
`{:host_call, reply_to, name, args}` event. `result` is `{:ok, value}` or
`{:error, binary_reason}`; the guest's call returns it.

Error reasons are binaries, so the guest can distinguish host errors from
its own `{:error, :timeout}`.

Returns `:ok` without confirming delivery. Replies containing atoms not
loaded in the guest are rejected, so the call can time out.

# `run`

```elixir
@spec run(String.t(), keyword()) :: {:ok, map()} | {:error, term()}
```

Evaluates `code` in a fresh VM and stops it afterward.

Accepts the options of both `start_link/1` and `eval/3`. Use this when
each piece of code must not see state left behind by others.

# `send`

```elixir
@spec send(vm(), atom() | String.t() | Kettlecorn.Pid.t(), term(), timeout()) ::
  :ok | {:error, :noproc | :bad_payload | :bad_request | :timeout | term()}
```

Sends `{:wasm, payload}` to a guest process: a registered name or a
`Kettlecorn.Pid` received from the guest.

Unlike `Kernel.send/2`, reports whether the target existed: `:ok`, or
`{:error, reason}` with `:noproc`, `:bad_payload`, `:bad_request`,
`:request_queue_full` (rejected before transmission),
`:timeout` (no answer within `timeout` plus 1000 milliseconds)
or `{:vm_down, reason}`. A handle from another VM returns `{:error, :wrong_vm}`.

# `start`

```elixir
@spec start(keyword()) :: {:ok, pid()} | {:error, term()}
```

Like `start_link/1` but not linked to the caller.

# `start_link`

```elixir
@spec start_link(keyword()) :: {:ok, pid()} | {:error, term()}
```

Starts a VM linked to the caller and waits until it has booted.

Resource limits and guest crashes can terminate the linked caller. Use `start/1`
with monitoring when the caller must survive VM failures; `:stop_with` ties an
unlinked VM to a worker's lifetime. See
[Managing VM lifetime](sandbox.html#managing-vm-lifetime).

Guest application failures return `{:error, :boot_failed}`. A VM that
exits during boot or exceeds `:boot_timeout` returns
`{:error, {:vm_down, reason}}`.

Accepts the options in `Kettlecorn.Sandbox`, plus:

* `:owner` - PID that receives `{:kettlecorn, vm_pid, event}` for console output (`{:stdout,
  data}`, `{:stderr, data}`), messages (`{:message, term}`) and host calls
  (`{:host_call, reply_to, name, args}`). Acknowledge events with
  `Kettlecorn.acknowledge/2` after handling them.
  Standard output captured by `Kettlecorn.eval/3` appears in its
  result; writes to stderr arrive as console events. The default value is `nil`.

* `:boot_timeout` (`t:pos_integer/0`) - Milliseconds to wait for the VM to boot. The default value is `30000`.

* `:output_limit` (`t:non_neg_integer/0`) - Bytes of guest console output buffered for `take_output/1`. Output beyond the cap is
  not buffered; owner delivery is subject to the pending event budgets. The default value is `1048576`.

* `:max_message_size` (`t:pos_integer/0`) - Longest guest frame in bytes. A longer frame kills the VM with `{:vm_down,
  {:frame_too_large, length}}`. Also sets the decoder's memory budget (retained
  binaries plus estimated heap space); messages exceeding that budget are
  dropped. See `Kettlecorn.ETF`. The default value is `67108864`.

* `:max_pending_requests` (`t:pos_integer/0`) - Maximum unanswered requests. Excess requests return `{:error, :request_queue_full}`
  before transmission. Caller exit releases a request without cancelling guest work. The default value is `1024`.

* `:max_pending_events` (`t:pos_integer/0`) - Maximum unacknowledged owner events. Overflow stops the VM with `:event_queue_full`. The default value is `1024`.

* `:max_pending_event_bytes` (`t:pos_integer/0`) - Estimated retained-byte budget for unacknowledged owner events. Use `Kettlecorn.acknowledge/2` after handling them. The default value is `67108864`.

* `:stop_with` (`t:pid/0`) - The VM stops when this process exits. `run/2` uses it to keep its VM from outliving
  the caller.

* `:name` (`t:term/0`) - GenServer name.

Raises `ArgumentError` for an unknown or invalid option, or a missing or
incompatible runtime (see `Kettlecorn.Sandbox.new/1`).

# `stop`

```elixir
@spec stop(vm()) :: :ok
```

Stops the VM and its launcher process.

# `take_output`

```elixir
@spec take_output(vm()) :: binary()
```

Returns and clears the guest console output buffered since the last call.

The buffer combines console stdout and stderr without stream labels. Standard
output captured in an `eval/3` result is excluded. Configure an `:owner` to
receive separate `:stdout` and `:stderr` events.

# `write_stdin`

```elixir
@spec write_stdin(vm(), iodata()) :: :ok
```

Writes `data` to the guest's standard input.

---

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