WebAssembly Runtime

The WASM runtime is an experimental extension. Configuration is stable, but runtime internals may change between releases.

Wippy registers WebAssembly modules alongside Lua code. Function entries join the function registry and run through function pools. Process entries register factories for persistent WASM actors: each PID owns one isolated module instance and bounded mailbox until it exits. Both use the runtime scheduler and security model.

Classification: conceptual overview. The Lua block contains independent call patterns and assumes the named WASM entries and their WIT contracts are already registered. See the Rust/WASM tutorial for a project with a compiled component.

Entry Kinds

Kind Description
function.wat Inline WebAssembly Text format function defined in YAML
function.wasm Precompiled WASM binary loaded from a filesystem entry
process.wasm Stateful WASM actor with one module instance per PID

How It Works

  1. WASM modules are declared as registry entries in _index.yaml
  2. At boot, function.wat and function.wasm entries are compiled, registered as functions, and placed into their configured function pools
  3. Lua calls those function entries through funcs.call()
  4. process.wasm entries register actor factories and are spawned under a process host; each PID keeps its module state across messages
  5. Function arguments and return values are mapped between Lua tables and WIT types
  6. Supported dispatcher-bridged operations, including clock polling and outgoing HTTP, yield so the scheduler can run other work

Component Model

Wippy supports the WebAssembly Component Model with WIT (WebAssembly Interface Types). Component modules map these types between the host and guest:

  • Records map to Lua tables with named fields
  • Lists map to Lua arrays
  • Results map to (value, error) return tuples
  • Primitives (s32, f64, string, etc.) map directly

Raw/core WASM modules are also supported with explicit WIT signatures.

Calling WASM from Lua

Call a WASM function by its registry ID through funcs.call():

local funcs = require("funcs")

-- No arguments
local result, err = funcs.call("myns:answer_wat")
if err then return nil, err end

-- With arguments
local computed, compute_err = funcs.call("myns:compute", 6, 7)
if compute_err then return nil, compute_err end

-- With complex data
local users = {
    {id = 1, name = "Alice", tags = {"admin"}, active = true},
    {id = 2, name = "Bob", tags = {"user"}, active = false},
}
local transformed, err = funcs.call("myns:transform_users", users)
if err then return nil, err end

Security

WASM executions inherit the caller's security context by default:

  • Actor identity is inherited
  • Scope is inherited
  • Request context is inherited

Host capabilities are opt-in through explicit imports. Each entry declares the host profiles it needs, such as funcs, wippy:actor, wasi1, wasi:cli, or wasi:filesystem, limiting the module's access surface. Enabling a profile does not bypass runtime security checks on operations such as process messaging, function calls, sockets, or outgoing HTTP.

A guest that imports funcs can call back into the registry. Each call is policy-checked as funcs.call against the target ID, so the reachable set is exactly what the inherited scope already permits. Socket dials are authorized the same way, by the network service, against the socket.* permissions.

See Also