Mix.install([{:kettlecorn, "~> 0.1.0"}])About this notebook
Validate guest structs before constructing host values. Start with one quote constructor, then extend it to nested containers and ISO dates. Read Working with guest VMs first for the host/guest boundary and returned values.
Requires Elixir 1.20 or later on x86_64 or ARM64 Linux or Apple silicon macOS. Run the cells in order.
{:ok, runtime} = Kettlecorn.Install.runtime()Validate a quote
A guest struct whose module atom exists on the host arrives as
Kettlecorn.Struct, holding its module and fields as data. Otherwise it stays
a map with __struct__: {:unknown_atom, name}. Rebuilding a host struct enables
that module's protocol implementations. Accept only known modules and validate
their fields before construction. Start with a single quote type:
defmodule MyApp.Quote do
@enforce_keys [:sku, :price]
defstruct [:sku, :price]
def new(sku, price) when is_binary(sku) and is_number(price) and price >= 0,
do: {:ok, %__MODULE__{sku: sku, price: price}}
def new(_sku, _price), do: {:error, :invalid_quote}
def from_guest(%Kettlecorn.Struct{module: __MODULE__, fields: %{sku: sku, price: price}}),
do: new(sku, price)
def from_guest(_other), do: {:error, :invalid_quote}
endA pricing plugin defines a module of the same name in the guest (in a cooked application, both sides would compile the same file) and returns quotes:
plugin = ~S"""
defmodule MyApp.Quote do
defstruct [:sku, :price]
end
defmodule Pricing do
def quote("apple"), do: {:ok, %MyApp.Quote{sku: "apple", price: 0.5}}
def quote("pear"), do: {:ok, %MyApp.Quote{sku: "pear", price: -1}}
def quote(sku), do: {:ok, URI.parse("https://example.com/" <> sku)}
end
"""
{:ok, pricing} =
Kettlecorn.start_link(
max_memory: 128 * 1024 * 1024,
max_fuel: 1_000_000_000_000,
max_lifetime: 600_000
)
{:ok, _} = Kettlecorn.eval(pricing, plugin)
{:ok, %{"value" => apple}} = Kettlecorn.eval(pricing, ~S|Pricing.quote("apple")|)
applefrom_guest/1 accepts the expected module and validates its fields:
{:ok, quote} = apple
{:ok, %MyApp.Quote{sku: "apple", price: 0.5}} = MyApp.Quote.from_guest(quote)A negative price is rejected by the same constructor:
{:ok, %{"value" => {:ok, quote}}} = Kettlecorn.eval(pricing, ~S|Pricing.quote("pear")|)
{:error, :invalid_quote} = MyApp.Quote.from_guest(quote)Convert nested values
A plugin can return quotes inside a larger result, such as a dated price list:
{:ok, %{"value" => catalog}} =
Kettlecorn.eval(pricing, ~S|%{"date" => ~D[2026-01-01], "quotes" => [Pricing.quote("apple")]}|)
%{
"date" => %Kettlecorn.Struct{module: Date},
"quotes" => [{:ok, %Kettlecorn.Struct{module: MyApp.Quote}}]
} =
catalogValidating only the outer map would leave its guest structs unconverted. Traverse
containers and apply a constructor to each accepted struct. The converter below
accepts quotes and ISO dates, rejects other Kettlecorn.Struct values, and
preserves ordinary maps, guest pid handles and
opaque handles as data. The preceding VM has a ten-minute lifetime; restart
the quote example if it expires.
defmodule MyApp.GuestData do
def cast(%Kettlecorn.Struct{module: MyApp.Quote, fields: %{sku: sku, price: price}}),
do: MyApp.Quote.new(sku, price)
# Date's calendar is a module whose callbacks run on the host; only accept ISO.
def cast(%Kettlecorn.Struct{
module: Date,
fields: %{calendar: Calendar.ISO, year: year, month: month, day: day}
})
when is_integer(year) and is_integer(month) and is_integer(day),
do: Date.new(year, month, day)
def cast(%Kettlecorn.Struct{module: Date}), do: {:error, :invalid_date}
def cast(%Kettlecorn.Struct{module: module}), do: {:error, {:unexpected_struct, module}}
def cast(%handle{} = value) when handle in [Kettlecorn.Pid, Kettlecorn.Opaque], do: {:ok, value}
def cast(list) when is_list(list), do: cast_list(list, [])
def cast(tuple) when is_tuple(tuple) do
with {:ok, list} <- cast_list(Tuple.to_list(tuple), []), do: {:ok, List.to_tuple(list)}
end
def cast(map) when is_map(map) do
with {:ok, pairs} <- cast_list(Map.to_list(map), []), do: {:ok, Map.new(pairs)}
end
def cast(other), do: {:ok, other}
defp cast_list([head | tail], acc) do
with {:ok, head} <- cast(head), do: cast_list(tail, [head | acc])
end
defp cast_list([], acc), do: {:ok, Enum.reverse(acc)}
defp cast_list(tail, acc) do
with {:ok, tail} <- cast(tail), do: {:ok, :lists.reverse(acc, tail)}
end
endThe nested result becomes a host date and a quote validated by its constructor:
{:ok, %{"date" => ~D[2026-01-01], "quotes" => [{:ok, %MyApp.Quote{sku: "apple", price: 0.5}}]}} =
MyApp.GuestData.cast(catalog)ISO dates are reconstructed from integer fields. Missing fields, wrong
types and other calendars are refused before calling Date.new/3:
{:ok, %{"value" => date}} = Kettlecorn.eval(pricing, "~D[2026-01-01]")
{:ok, ~D[2026-01-01]} = MyApp.GuestData.cast(date)
for fields <- [
%{calendar: Calendar.ISO},
%{calendar: Calendar.ISO, year: "2026", month: 1, day: 1},
%{calendar: MyApp.Calendar, year: 2026, month: 1, day: 1}
] do
{:error, :invalid_date} = MyApp.GuestData.cast(%Kettlecorn.Struct{module: Date, fields: fields})
endMyApp.Quote.new/2 rejects a quote with an invalid price. cast/1 rejects
structs the application doesn't accept:
for sku <- ["pear", "plum"] do
{:ok, %{"value" => value}} = Kettlecorn.eval(pricing, "Pricing.quote(#{inspect(sku)})")
{sku, MyApp.GuestData.cast(value)}
endKettlecorn.stop(pricing)struct!/2 checks keys but does not validate field values. Validate those
values before constructing host structs or running their protocol implementations.
Next steps
The Guest API guide documents messages and host calls. Use cases applies those APIs to services and plugins.