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
@type vm() :: GenServer.server()
Functions
@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.
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.
Casts request to a GenServer registered as target in the guest.
Returns :ok without confirming delivery.
@spec close_stdin(vm()) :: :ok
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.
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:timeoutand 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 is5000.: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.
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.
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.
@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}.
Like start_link/1 but not linked to the caller.
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 withKettlecorn.acknowledge/2after handling them. Standard output captured byKettlecorn.eval/3appears in its result; writes to stderr arrive as console events. The default value isnil.:boot_timeout(pos_integer/0) - Milliseconds to wait for the VM to boot. The default value is30000.:output_limit(non_neg_integer/0) - Bytes of guest console output buffered fortake_output/1. Output beyond the cap is not buffered; owner delivery is subject to the pending event budgets. The default value is1048576.: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. SeeKettlecorn.ETF. The default value is67108864.: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 is1024.:max_pending_events(pos_integer/0) - Maximum unacknowledged owner events. Overflow stops the VM with:event_queue_full. The default value is1024.:max_pending_event_bytes(pos_integer/0) - Estimated retained-byte budget for unacknowledged owner events. UseKettlecorn.acknowledge/2after handling them. The default value is67108864.:stop_with(pid/0) - The VM stops when this process exits.run/2uses 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).
@spec stop(vm()) :: :ok
Stops the VM and its launcher process.
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.
Writes data to the guest's standard input.