Kettlecorn (kettlecorn v0.1.0)

Copy Markdown View Source

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

Summary

Functions

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.

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

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

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

Evaluates Elixir or Erlang code in the guest.

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.

Evaluates code in a fresh VM and stops it afterward.

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

Like start_link/1 but not linked to the caller.

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

Stops the VM and its launcher process.

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

Writes data to the guest's standard input.

Types

vm()

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

Functions

acknowledge(vm, count \\ 1)

@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(vm, target, request, timeout \\ 5000)

@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(vm, target, request)

@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(vm)

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

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

eval(vm, code, opts \\ [])

@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 (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(vm, reply_to, result)

@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(code, opts \\ [])

@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(vm, target, payload, timeout \\ 5000)

@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(opts \\ [])

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

Like start_link/1 but not linked to the caller.

start_link(opts \\ [])

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

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 (pos_integer/0) - Milliseconds to wait for the VM to boot. The default value is 30000.

  • :output_limit (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 (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 (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 (pos_integer/0) - Maximum unacknowledged owner events. Overflow stops the VM with :event_queue_full. The default value is 1024.

  • :max_pending_event_bytes (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 (pid/0) - The VM stops when this process exits. run/2 uses it to keep its VM from outliving the caller.

  • :name (term/0) - GenServer name.

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

stop(vm)

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

Stops the VM and its launcher process.

take_output(vm)

@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(vm, data)

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

Writes data to the guest's standard input.