Mix.install([{:kettlecorn, "~> 0.1.0"}, {:lua, "1.0.2"}])About this notebook
Run the same Lua order transformation on the host BEAM and inside a Kettlecorn guest, retain state between calls, and expose one host operation.
Lua is an interpreter implemented in Elixir. Its playground introduces the language and API. The same interpreter runs in the guest BEAM, isolated from the host by Wasmtime. See sandbox and resource limits for the available memory, time, and execution limits.
Run the cells in order on x86_64 or ARM64 Linux or Apple silicon macOS. The host must use the runtime's OTP major release and exact Elixir version because it compiles Lua's BEAM files.
{:ok, runtime} = Kettlecorn.Install.runtime()Copy Lua into the guest
Mix.install installs Lua on the host. code_paths copies its compiled
modules into the guest at startup; the guest does not fetch dependencies.
Lua 1.0.2 has no additional production Hex dependencies or native code.
manifest = Kettlecorn.Runtime.load!(Kettlecorn.Runtime.dir()).manifest
guest_otp = manifest.otp |> String.split(".") |> hd()
unless System.version() == manifest.elixir and System.otp_release() == guest_otp do
raise "Compile Lua with Elixir #{manifest.elixir} and OTP #{guest_otp}; " <>
"this runtime uses Elixir #{System.version()} and OTP #{System.otp_release()}"
end
lua_limits = [max_instructions: 100_000, max_call_depth: 100, max_string_bytes: 1_000_000]
lua_ebin = :lua |> :code.lib_dir(:ebin) |> List.to_string()
{:ok, vm} =
Kettlecorn.start_link(
code_paths: [lua_ebin],
apps: [:lua],
owner: self(),
max_memory: 256 * 1024 * 1024,
max_lifetime: 600_000,
max_fuel: 1_000_000_000_000
)The guest has a ten-minute lifetime; restart it if it expires while reading. Lua's limits count its own instructions; Kettlecorn's fuel counts Wasm execution across the whole VM, including boot.
Transform orders
The output contains an ID, total in cents, route, and running count. It omits the email and original items. Prices and totals use integer cents.
script = ~S"""
processed = 0
function transform(event)
local total = 0
for _, item in ipairs(event.items) do
total = total + item.unit_price_cents * item.quantity
end
local route = "standard"
if total >= 10000 then
route = "priority"
end
processed = processed + 1
return event.id, total, route, processed
end
"""
events = [
%{
"id" => "order-1",
"email" => "ada@example.test",
"items" => [
%{"unit_price_cents" => 2500, "quantity" => 2},
%{"unit_price_cents" => 1500, "quantity" => 1}
]
},
%{
"id" => "order-2",
"email" => "grace@example.test",
"items" => [%{"unit_price_cents" => 12500, "quantity" => 1}]
}
]Define one worker to load the script once and reuse its Lua state on both sides:
worker = ~S"""
defmodule LuaComparison do
use GenServer
def init({script, limits}) do
{[], lua} = Lua.eval!(Lua.new(limits), script)
{:ok, lua}
end
def handle_call({:transform, event}, _from, lua) do
{event, lua} = Lua.encode!(lua, event)
{result, lua} = Lua.call_function!(lua, [:transform], [event])
{:reply, result, lua}
end
end
"""
Code.compile_string(worker)
{:ok, local} = GenServer.start(LuaComparison, {script, lua_limits})
{:ok, _} = Kettlecorn.eval(vm, worker)
{:ok, %{"value" => :ok}} =
Kettlecorn.eval(
vm,
"{:ok, _pid} = GenServer.start(LuaComparison, {script, limits}, name: :lua_comparison); :ok",
binding: %{script: script, limits: lua_limits}
)Both workers should produce the same results, including the running count:
expected = [["order-1", 6500, "standard", 1], ["order-2", 12500, "priority", 2]]
^expected = Enum.map(events, &GenServer.call(local, {:transform, &1}))
^expected =
Enum.map(events, fn event ->
{:ok, result} = Kettlecorn.call(vm, :lua_comparison, {:transform, event})
result
end)Both GenServers retain Lua state. Reusing the guest also retains its other processes, modules, and files. Give unrelated tenants separate VMs; a new evaluation process does not reset the guest.
Lua.call_function!/3 takes encoded Lua values. Lua.encode!/2 converts the
event's maps and lists to tables before calling the loaded function. Its
results here are strings and integers, which need no further decoding.
Compile the worker before sending Lua's option atoms in binding: the
guest's payload decoder accepts only atoms already loaded there.
Expose one host operation
On the host, an exposed Lua function can call Elixir directly. In the guest,
it can request a host operation through Kettlecorn.Host.call/3. The host
checks the request before replying. This example permits one customer lookup
without granting network access.
discounts = %{"customer-1" => 10}
local_lua =
Lua.new(lua_limits)
|> Lua.set!([:discount], fn [customer] -> [Map.fetch!(discounts, customer)] end)
{[10], _lua} = Lua.eval!(local_lua, ~S|return discount("customer-1")|)
task =
Task.async(fn ->
Kettlecorn.eval(vm, ~S"""
lua = Lua.new(max_instructions: 100_000)
lua = Lua.set!(lua, [:discount], fn [customer] ->
{:ok, discount} = Kettlecorn.Host.call("discount", %{"customer" => customer})
[discount]
end)
{result, _lua} = Lua.eval!(lua, ~S|return discount("customer-1")|)
result
""")
end)
receive do
{:kettlecorn, ^vm, {:host_call, reply_to, "discount", %{"customer" => customer}}} ->
reply =
case Map.fetch(discounts, customer) do
{:ok, discount} -> {:ok, discount}
:error -> {:error, "unknown customer"}
end
Kettlecorn.reply(vm, reply_to, reply)
Kettlecorn.acknowledge(vm)
after
5_000 -> raise "guest did not request the discount"
end
{:ok, %{"value" => [10]}} = Task.await(task, 10_000)The host process must reject unsupported operations and consume guest events; see controlled host access.
Stop the VM
:ok = GenServer.stop(local)
:ok = Kettlecorn.stop(vm)For packaging and deployment, the repository's
Lua example app
keeps the script in priv/ and cooks Lua with the application. This notebook
loads Lua directly through code_paths; Lua is not part of Kettlecorn's
default runtime.