Validating guest data

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

A 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")|)
apple

from_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}}]
} =
  catalog

Validating 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
end

The 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})
end

MyApp.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)}
end
Kettlecorn.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.