PSA/ee/docs/extension-system/runner_guest_abi.md

# Runner Guest ABI (EE)

This document specifies the ABI between the Runner (host) and Extension bundles (guest WebAssembly module).

Scope
- Execution: how the host calls your handler and how you return a response
- Memory/alloc conventions
- Host imports provided (logging, HTTP egress)
- Data formats and constraints

Overview
- The guest exports a linear memory and functions: alloc, handler, and optionally dealloc
- The host writes a normalized request JSON into guest memory and calls handler
- The guest writes a response JSON into guest memory and indicates its location via an out-pointer tuple

Guest exports
- memory: (export "memory") (required)
  - A standard linear memory the host can read/write
- alloc: (export "alloc") (required)
  - Signature: alloc(size: i32) -> i32
  - Returns a pointer to a region of guest memory at least size bytes
- dealloc: (export "dealloc") (optional)
  - Signature: dealloc(ptr: i32, size: i32) -> void
  - If exported, the host may call dealloc for input, output, and tuple buffers after use
- handler: (export "handler") (required)
  - Signature: handler(req_ptr: i32, req_len: i32, out_ptr: i32) -> i32
  - Arguments:
    - req_ptr/req_len: point to a UTF-8 JSON request payload provided by host (see Request JSON)
    - out_ptr: points to an 8-byte area in guest memory where the guest must write back a pair of little-endian i32 values: (resp_ptr, resp_len)
      - resp_ptr: pointer to the start of the response JSON bytes in guest memory
      - resp_len: length in bytes of the response JSON
  - Return value: 0 for success; non-zero indicates application-level error. Traps terminate execution.

Request JSON (host -> guest)
- Bytes at (req_ptr, req_len) are UTF-8 JSON with the shape:
{
  "context": {
    "request_id": string | null,
    "tenant_id": string,
    "extension_id": string,
    "version_id": string | null
  },
  "http": {
    "method": string,            // "GET", "POST", ...
    "path": string,              // "/route"
    "query": { [k: string]: string },
    "headers": { [k: string]: string },
    "body_b64": string | null    // base64-encoded body (if any)
  }
}

Response JSON (guest -> host)
- Guest allocates a buffer via alloc(len), writes UTF-8 JSON, then writes the tuple (resp_ptr, resp_len) at out_ptr
- JSON shape expected by host:
{
  "status": number,                      // e.g., 200
  "headers": { [k: string]: string },    // optional
  "body_b64": string | null              // base64-encoded body (optional)
}
- If the guest returns non-JSON bytes, the host will treat them as an opaque payload and base64-encode them with status 200 and no headers

Host imports (module "alga")
- alga.log_info(ptr: i32, len: i32) -> void
  - Reads UTF-8 string from guest memory and logs at info level
- alga.log_error(ptr: i32, len: i32) -> void
  - Reads UTF-8 string from guest memory and logs at error level
- alga.http.fetch(req_ptr: i32, req_len: i32, out_ptr: i32) -> i32
  - Asynchronous host function exposed synchronously in the ABI; returns 0 on success, non-zero on error (trap on severe errors)
  - Request JSON (at req_ptr/req_len):
    {
      "url": string,                      // required
      "method": string,                   // optional, default "GET"
      "headers": { [k: string]: string }, // optional
      "body_b64": string | null           // optional
    }
  - Allowlist enforcement: the host validates URL host against EXT_EGRESS_ALLOWLIST (comma-separated hostnames). Exact or subdomain match required. If denied, returns error.
  - On success, host writes response JSON to guest memory (alloc used) and stores (resp_ptr, resp_len) at out_ptr with shape:
    {
      "status": number,
      "headers": { [k: string]: string },
      "body_b64": string
    }
  - Notes: Size/time limits may be enforced by the host; avoid large payloads

Limits & timeouts
- Per-invocation limits may be applied by the host:
  - Timeout: context.limits.timeout_ms (default configured by host); exceeding deadline interrupts execution
  - Memory: context.limits.memory_mb (default configured by host); allocations beyond limit will fail
- Egress allowlist: EXT_EGRESS_ALLOWLIST environment variable on the Runner controls which hosts alga.http.fetch can access
- Request/response sizes: the host may enforce maximum sizes for inbound/outbound bodies; exceeding limits will error

Guest design guidance
- Keep handler stateless and idempotent where practical; rely on host-brokered I/O only
- Always check for missing/optional fields in request JSON
- Return normalized response JSON whenever possible (status, headers, body_b64)
- Use alga.http.fetch for outbound HTTP only to allowed domains
- Free memory when exporting dealloc; host will attempt to call it if present

Minimal pseudo-code
- Pseudocode guest outline:
export function alloc(sz: i32): i32 { /* ... */ }
export function dealloc(ptr: i32, sz: i32): void { /* ... */ }
export function handler(req_ptr: i32, req_len: i32, out_ptr: i32): i32 {
  const req = JSON.parse(loadString(req_ptr, req_len));
  const res = { status: 200, headers: { "content-type": "application/json" }, body_b64: b64encode(utf8("{\"ok\":true}")) };
  const buf = utf8(JSON.stringify(res));
  const resp_ptr = alloc(buf.length);
  storeBytes(resp_ptr, buf);
  storeI32(out_ptr + 0, resp_ptr);
  storeI32(out_ptr + 4, buf.length);
  return 0;
}

Error handling
- handler returns non-zero to signal application errors; the host maps this to a 500 execute_failed with the code
- Traps (e.g., out-of-bounds, allowlist denial, host errors) abort execution; the host returns 500 with an error message

Versioning
- This is the initial MVP ABI for the Runner (EE). Future revisions may add:
  - Structured error mapping
  - Built-in size/time limit introspection
  - Additional host imports (KV/doc storage, secrets)