# Lua inside Kettlecorn

```elixir
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](https://lua.hexdocs.pm/Lua.html) is an interpreter implemented in
Elixir. Its [playground](https://deflua.com) introduces the language and API.
The same interpreter runs in the guest BEAM, isolated from the host by
Wasmtime. See [sandbox and resource limits](../guides/sandbox.md) 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.

```elixir
{: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.

```elixir
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.

```elixir
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:

```elixir
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:

```elixir
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.

```elixir
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](use-cases.livemd#give-the-guest-controlled-access).

## Stop the VM

```elixir
:ok = GenServer.stop(local)
:ok = Kettlecorn.stop(vm)
```

For packaging and deployment, the repository's
[Lua example app](https://github.com/mjrusso/kettlecorn/tree/main/examples/apps/lua)
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.
