forwarder

README

Shared spawn-forwarder

embedded/spawn-forwarder.wasm is the daemon-embedded WASM that drives every spawn-primitive connector whose manifest declares connector.forwarder = "builtin://spawn-forwarder". See ADR-0002 for the design.

Layout

forwarder/
  forwarder.go            embed wrapper (committed)
  src/main.go             WASM source of truth (committed)
  embedded/
    .gitkeep              committed; satisfies //go:embed
    spawn-forwarder.wasm  generated by `task build:forwarder` (gitignored)

The WASM is generated code, not committed. The embedded/.gitkeep guarantees the directory exists so //go:embed all:embedded matches at least one file on a fresh clone. The Taskfile entry below is the only path that writes the WASM file.

Regenerate

task build:forwarder

Or directly:

cd internal/sandbox/forwarder/src && \
  GOOS=wasip1 GOARCH=wasm go build -trimpath -ldflags="-s -w" \
    -o ../embedded/spawn-forwarder.wasm .

task build:cli, task test:go, and the CI / release workflows all depend on task build:forwarder, so a fresh clone that goes through Task always gets a freshly-built WASM. A go build that bypasses Task on a clean checkout compiles fine (the .gitkeep satisfies the embed) but forwarder.WASM is empty; the action executor surfaces a clear "this daemon was built without the forwarder WASM" error rather than handing zero bytes to Wazero.

What it does

The resulting ~3 MB WASM (native Go wasip1; smaller TinyGo build is a v3 follow-up) exposes a single WASI _start entrypoint. It reads {"op": "...", "args": {...}} from stdin, calls aileron_host.spawn_op, reads back exit code and stdout/stderr via the spawn_output_* host functions, and emits a JSON output envelope to stdout.

The forwarder carries no service-specific knowledge. All behavior is driven by the consuming connector's manifest.

Documentation

Overview

Package forwarder embeds the shared spawn-forwarder WASM into the Aileron daemon binary.

The forwarder is a manifest-driven adapter between the action layer's JSON envelope ({op, args}) and the runtime's aileron_host.spawn_op host function. Per ADR-0002's spawn-primitive section, every spawn-primitive connector that references `connector.forwarder = "builtin://spawn-forwarder"` is dispatched through this binary.

The forwarder source lives under src/. The compiled WASM lives under embedded/ and is regenerated by `task build:forwarder`. The embedded directory is gitignored except for a committed `.gitkeep` that guarantees the `go:embed` pattern always matches at least one file on a fresh clone. When the WASM has not been built (a fresh clone where `task build:forwarder` has not run, or a `go build` that bypassed the Taskfile), WASM is empty and callers surface a clear error instead of compiling an empty module.

Index

• Variables

Variables

var WASM []byte

WASM is the compiled forwarder bytes. Loaded into the Wazero runtime when a connector manifest declares `connector.forwarder = "builtin://spawn-forwarder"`.

The hash of these bytes contributes to a forwarder-connector's content hash (sha256(WASM || manifest.toml) per ADR-0002), so a daemon upgrade that ships new forwarder bytes invalidates the cached hashes of every shared-forwarder wrap on the host. The install pipeline re-stores the manifest under the new hash; manifest content is unchanged.

Empty when `task build:forwarder` has not populated embedded/spawn-forwarder.wasm. Callers check `len(WASM) > 0` before using and surface a clear "forwarder not built" error otherwise.