Lua inside Kettlecorn

Copy Markdown View Source
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.