std:host WIT package¶
WASM std:host@0.1.0 is the set of WIT interfaces the runtime provides to
WASM components, next to the standard WASI ones: logs, key/value storage, SQL, blobs, queues, service-to-service calls
and operator bindings. This page lists every interface, type, function and error code, and shows how to generate
bindings in Rust and JavaScript. For a walkthrough, read Writing WASM services; the Deno
counterparts are in the guest API reference.
At a glance¶
| Interface | Functions | Purpose |
|---|---|---|
log |
log |
write a log record at a level |
kv |
get, set, delete, list, incr |
per-service key/value store with TTL and atomic counters |
sql |
execute, batch |
per-service SQLite database |
blob |
get, head, put, delete, list |
per-service object storage |
queue |
enqueue |
send a message to a service's queue |
call |
call, call-rpc |
call another service in-process; typed RPC |
sdk |
invoke |
call an operator SDK (it runs in the runtime) |
rpc (export) |
handle |
serve RPC calls (world rpc-service) |
platform |
fetch |
call an operator binding without credentials (operator SDK services only) |
sockets |
accept, send, broadcast, close, close-all, list, get, set-tags, get-attachment, set-attachment, set-auto-response |
the service's WebSockets (guide) |
durable |
object, get, put, delete, list, delete-all, get-alarm, set-alarm, fetch |
the task's durable object: storage, alarm, requests to objects |
ws-client |
connect; connection.send, recv, close |
outbound WebSockets through the egress guard |
socket-handler (export) |
on-message, on-close, on-error, on-alarm |
socket events and alarms (world socket-service) |
The world guest imports every interface above, and secrets, lock and schedule (see the file below); the world
rpc-service adds the rpc export and the world socket-service the socket-handler export. A component may import any subset: wit-bindgen and jco only emit imports for the
interfaces your code uses or your world lists.
The full file¶
This is wit/rt-host.wit from the runtime repository. Copy it into your project's wit/ directory (or
wit/deps/rt-host/ for jco) to generate bindings.
// std:host — capabilities the runtime exposes to WASM guest components.
//
// A guest is a WASI P2 component whose world exports `wasi:http/incoming-handler`
// (wasi:http/proxy) and may import any of the interfaces below. Denied outright: wasi:filesystem
// (no preopens) and wasi:sockets (all addresses denied). Outbound HTTP is the standard
// `wasi:http/outgoing-handler`, routed through the host's SSRF guard.
//
// Scope: kv, sql, blob, log, queue (enqueue to a service of the same tenant), call (in-process
// call and RPC to a service of the same tenant; a component exporting `rpc`, world `rpc-service`,
// serves RPC) and platform (operator bindings). Blob and call bodies are buffered in this revision
// (streaming via wasi:io streams is a follow-up). All errors are stable `error { code, message }`
// records (SEC-26: never host paths or driver text), with the codes of the Deno SDK.
package std:host@0.1.0;
interface log {
enum level { debug, info, warn, error }
record error {
code: string,
message: string,
}
// Appends a record to the service's logs, tagged with the task id.
log: func(level: level, message: string);
// Appends a record with structured fields: `fields-json` is a JSON object (at most 32 top-level
// keys and 8 KiB). A refused object fails `validation_failed` and writes no record.
log-fields: func(level: level, message: string, fields-json: string) -> result<_, error>;
}
interface kv {
variant value {
// JSON text (UTF-8).
json(string),
bytes(list<u8>),
}
record set-options {
ttl-seconds: option<u64>,
}
record list-options {
prefix: list<u8>,
cursor: option<list<u8>>,
// <= 1000
limit: u32,
// Descending key order: the cursor pages downwards.
reverse: bool,
}
record list-page {
entries: list<tuple<list<u8>, value>>,
next-cursor: option<list<u8>>,
}
record error {
code: string,
message: string,
}
get: func(key: list<u8>) -> result<option<value>, error>;
set: func(key: list<u8>, value: value, opts: set-options) -> result<_, error>;
delete: func(key: list<u8>) -> result<bool, error>;
%list: func(opts: list-options) -> result<list-page, error>;
// Atomically adds `delta` to the integer counter at `key` and returns the new value. A missing
// (or expired) key starts at 0 and gets `opts.ttl-seconds`; an existing counter keeps its
// expiry. The counter is stored as JSON text (`get` returns `json("<n>")`). Errors:
// kv_not_integer (the value is not a JSON integer in the s64 range), kv_overflow (the result
// leaves s64), plus the `set` codes (validation_failed, kv_key_too_large, storage_quota).
incr: func(key: list<u8>, delta: s64, opts: set-options) -> result<s64, error>;
// Atomic compare-and-swap in one step: `next` is written (`none`: deleted) only when the current
// value equals `expected` (same bytes and tag; `none` = absent or expired). `opts.ttl-seconds`
// applies to `next`. Returns whether the swap happened. Errors: the `set` codes.
cas: func(key: list<u8>, expected: option<value>, next: option<value>, opts: set-options) -> result<bool, error>;
// Sets (`ttl-seconds` some) or clears (`none`) the expiry of a live key; false when absent.
expire: func(key: list<u8>, opts: set-options) -> result<bool, error>;
// Seconds left on a live key with an expiry (rounded up); none when absent or without expiry.
ttl: func(key: list<u8>) -> result<option<u64>, error>;
}
interface sql {
variant sql-value {
null,
integer(s64),
real(f64),
text(string),
blob(list<u8>),
}
record statement {
sql: string,
args: list<sql-value>,
}
record sql-result {
columns: list<string>,
rows: list<list<sql-value>>,
rows-affected: u64,
last-insert-rowid: option<s64>,
}
record error {
// sql_error | sql_timeout | sql_not_authorized | storage_quota
code: string,
message: string,
}
execute: func(stmt: statement) -> result<sql-result, error>;
// All statements in one transaction; `write = false` opens it read-only.
batch: func(stmts: list<statement>, write: bool) -> result<list<sql-result>, error>;
}
interface blob {
record meta {
key: string,
size: u64,
content-type: option<string>,
}
record list-page {
items: list<meta>,
next-cursor: option<string>,
}
record error {
code: string,
message: string,
}
get: func(key: string) -> result<option<tuple<meta, list<u8>>>, error>;
head: func(key: string) -> result<option<meta>, error>;
put: func(key: string, content-type: option<string>, data: list<u8>) -> result<meta, error>;
delete: func(key: string) -> result<bool, error>;
%list: func(prefix: string, cursor: option<string>, limit: u32) -> result<list-page, error>;
}
interface queue {
record send-options {
// Deliver no earlier than this many seconds from now (<= 7 days).
delay-seconds: option<u64>,
// The same id within 24 h is delivered once.
dedup-id: option<string>,
}
record error {
// not_found | forbidden | trigger_not_allowed | queue_full | rejected codes
code: string,
message: string,
}
// Enqueue `body` (<= 1 MB) for the service `slug` of the same tenant; returns the message id.
enqueue: func(slug: string, body: list<u8>, opts: send-options) -> result<string, error>;
}
interface call {
// Header values are bytes, as in `wasi:http/types` fields.
type headers = list<tuple<string, list<u8>>>;
record request {
method: string,
// Only the path and query reach the target (`/s/{slug}` is the target's own prefix).
path-with-query: string,
headers: headers,
body: list<u8>,
}
record response {
status: u16,
headers: headers,
// Buffered, at most `limits.max_response_buffered_bytes`.
body: list<u8>,
}
record error {
// not_found | cross_tenant_call | forbidden | call_not_allowed | trigger_not_allowed |
// call_failed | invalid_request | response_too_large | rejected codes
code: string,
message: string,
}
// In-process call to the service `slug` of the same tenant (no HTTP hop). The target's
// `call.allowed_callers` / environment and the plan's triggers decide; the child's wall limit
// is min(own, the caller's remaining time). A failing child is a 5xx `response`, not an error;
// past call depth 15 the response is `508` with `x-rt-reason: call_depth`.
call: func(slug: string, req: request) -> result<response, error>;
// RPC to the service `slug` over the same path (std:services `services.call`): runs the
// callee's method `method` (a dot-separated path of identifiers, `invoices.create`) with the
// JSON argument `args-json` and returns its JSON result. The argument and the result are at
// most 256 KiB each. Errors: the callee's own `{code, message}` (a Deno `ServiceError`, a WASM
// `rpc.handle` error), or the host's: validation_failed, method_not_found, response_too_large,
// invalid_response, call_depth, timeout, the `call` codes above.
call-rpc: func(slug: string, method: string, args-json: string) -> result<string, error>;
}
// Operator SDKs (std:sdk). No SDK code is in the component: each call is
// bound at run time to the SDK release the caller's grants select, and runs in the runtime.
interface sdk {
record error {
// The SDK's own code, or: sdk_not_found | sdk_unavailable (removed) | sdk_not_granted |
// sdk_version_unavailable | method_not_found | validation_failed | call_depth | timeout | ...
code: string,
message: string,
}
// Calls `method` (`invoices.create`) of the SDK `name` with the JSON argument `args-json`
// (at most 256 KiB) and returns its JSON result (at most 256 KiB).
invoke: func(name: string, method: string, args-json: string) -> result<string, error>;
}
// The callee side of an RPC, exported by a component that serves `call-rpc` / `services.call`
// (world `rpc-service`). A call to such a component runs `handle` instead of its HTTP handler.
interface rpc {
// Who called, as the runtime stamped it (never from the request).
record caller {
// svc_… id of the calling service.
service: string,
// Its slug, project id and environment: none when not visible from the callee's tenant.
slug: option<string>,
project: option<string>,
environment: option<string>,
// ten_… id of the calling tenant.
tenant: string,
// An operator SDK call (`sdk.invoke`): the calling tenant's plan.
plan: option<string>,
}
record error {
code: string,
message: string,
}
// `method` is the method name the caller asked for; `args-json` its JSON argument (`null` when
// none). Answers the JSON result (at most 256 KiB) or an error the caller receives as is
// (`method_not_found` for an unknown method, by convention).
handle: func(method: string, args-json: string, caller: option<caller>) -> result<string, error>;
}
interface platform {
use call.{request, response};
record error {
// invalid_request | response_too_large | unavailable (outside a task)
code: string,
message: string,
}
// Calls the operator binding `binding` (`[[binding]]` in the node config) without credentials:
// the node injects the binding's headers upstream; the guest never sees them. Only the request's
// method, path + query, headers (minus authorization, cookie, x-rt-*) and body are used.
// Never an error for a refusal: the binding's answer is a `response` with `x-rt-reason`:
// 403 binding_denied (method/path not allowed, `..` traversal), 403 binding_not_allowed (the
// tenant's plan), 404 binding_not_found, 429 rate_limited, 502 binding_upstream.
fetch: func(binding: string, req: request) -> result<response, error>;
}
// The imports a guest may use in addition to `wasi:http/proxy`.
interface secrets {
record error {
code: string,
message: string,
}
// The value of a secret of this service (never a plain env var); `none` when it is not set.
// Errors: validation_failed (not a secret name), unavailable / internal (the env is not readable).
get: func(name: string) -> result<option<string>, error>;
}
// Named mutexes of this service on this node (std:lock).
interface lock {
record error {
code: string,
message: string,
}
// A held lock. `release` gives it up; dropping it does too, and so does the end of the task: the
// host releases every lock a task still holds when the task ends, is killed or hits a limit.
resource lease {
release: func();
}
// Waits at most `wait-ms` (0 = do not wait) for `key` and holds it for at most `lease-ms`, after
// which the next waiter gets it. Errors: lock_timeout (not got in time), lock_limit (a cap),
// validation_failed (key 1-512 bytes, wait <= 300000 ms, lease 1-900000 ms).
acquire: func(key: string, wait-ms: u32, lease-ms: u32) -> result<lease, error>;
}
// One-off tasks of this service, created from code (std:schedule). The due
// schedule runs the guest's `scheduled` export with the id, the due time and the payload (at-least-once).
interface schedule {
record error {
code: string,
message: string,
}
record entry {
id: string,
run-at-ms: s64,
}
record page {
entries: list<entry>,
cursor: option<string>,
}
// Due `seconds` from now (at most 30 days). `payload-json` is the JSON text of the payload (at most
// 16 KiB). `id` (1 to 128 of a-z, A-Z, 0-9, . _ - :) replaces a pending schedule of that id; without
// one the host generates it. Errors: validation_failed, schedule_limit (1000 pending per service).
after: func(seconds: u64, payload-json: string, id: option<string>) -> result<entry, error>;
// Due at `at-ms` (Unix ms), at most 30 days from now.
at: func(at-ms: s64, payload-json: string, id: option<string>) -> result<entry, error>;
// Removes a pending schedule; false when there is none.
cancel: func(id: string) -> result<bool, error>;
// Pending schedules in id order, after `after`; `cursor` is set on a full page.
%list: func(after: option<string>, limit: u32) -> result<page, error>;
}
// WebSockets the node holds for this service (std:sockets, docs/handlers.md "WebSockets and durable objects").
// Every call is scoped to this service: another service's socket is `not_found`. A task that acts
// for an object (a socket event, an alarm, a request to a durable object) sends when its handler
// returned (after its storage writes committed); elsewhere a send leaves at once.
// Errors: not_found, invalid_request, too_large, limit_exceeded, slow_consumer, unavailable,
// not_upgradable.
interface sockets {
record error {
code: string,
message: string,
}
variant payload {
text(string),
binary(list<u8>),
}
record socket-info {
// ws_...
id: string,
object: string,
tags: list<string>,
protocol: option<string>,
created-at-ms: s64,
last-message-at-ms: option<s64>,
auto-response-at-ms: option<s64>,
buffered-amount: u64,
remote-ip: option<string>,
}
record accept-options {
// At most 10 tags of 1 to 256 bytes.
tags: list<string>,
// At most 16 KiB; read back with `get-attachment` in later events.
attachment: option<list<u8>>,
// The subprotocol to answer with (one the client offered).
protocol: option<string>,
}
record accepted {
id: string,
ticket: string,
}
// Accepts the WebSocket upgrade the task's request offered (an HTTP or call task only; `wasi:http`
// hides `Upgrade`, the runtime marks the offer with the request header `x-rt-websocket: 1`), for
// the task's object (`default` outside one). Answer the request with status 101: the runtime adds
// the ticket header and connects the client to the socket.
accept: func(opts: accept-options) -> result<accepted, error>;
send: func(id: string, data: payload) -> result<_, error>;
// To every socket of `object` (default: the task's object), with `tag` when set, except `except`.
// Returns how many sockets it reached.
broadcast: func(object: option<string>, tag: option<string>, data: payload, except: list<string>) -> result<u32, error>;
// Code 1000 or 3000-4999; reason at most 123 bytes.
close: func(id: string, code: u16, reason: string) -> result<_, error>;
close-all: func(object: option<string>, tag: option<string>, code: u16, reason: string) -> result<u32, error>;
// Sockets of `object` (default: the task's object, else every object), in id order after `cursor`.
%list: func(object: option<string>, tag: option<string>, limit: u32, cursor: option<string>) -> result<tuple<list<socket-info>, option<string>>, error>;
get: func(id: string) -> result<option<socket-info>, error>;
set-tags: func(id: string, tags: list<string>) -> result<_, error>;
get-attachment: func(id: string) -> result<option<list<u8>>, error>;
set-attachment: func(id: string, value: option<list<u8>>) -> result<_, error>;
// The object's automatic answer: a text message equal to the pair's first string is answered with
// the second by the runtime, without an event. `none` removes it.
set-auto-response: func(object: option<string>, pair: option<tuple<string, string>>) -> result<_, error>;
}
// Durable objects (std:durable): the task's object's storage and alarm,
// and requests to objects. Writes wait until the handler returned and commit in one transaction
// (before the task's socket sends); a handler that fails writes nothing. Values are bytes here
// (a Deno service stores structured clones). Errors: no_object (outside an object), validation_failed,
// kv_key_too_large (2 KiB), kv_value_too_large (1 MiB), limit_exceeded (1000 writes per task),
// storage_quota, not_durable, and the `call` codes.
interface durable {
use call.{request, response};
record error {
code: string,
message: string,
}
// The object this task acts for.
object: func() -> option<string>;
get: func(key: string) -> result<option<list<u8>>, error>;
put: func(key: string, value: list<u8>) -> result<_, error>;
// `true` when the key existed.
delete: func(key: string) -> result<bool, error>;
// Keys with `prefix`, then in `[start, end)`, at most `limit` (<= 1000), descending with `reverse`.
%list: func(prefix: string, start: option<string>, end: option<string>, limit: u32, reverse: bool) -> result<list<tuple<string, list<u8>>>, error>;
delete-all: func() -> result<_, error>;
// One alarm per object (Unix ms); it runs the `socket-handler.on-alarm` export, at least once.
get-alarm: func() -> result<option<s64>, error>;
set-alarm: func(at-ms: option<s64>) -> result<_, error>;
// A request to the object `object` of the durable service `service` (a slug; `none`: this one),
// in the object's turn: an object runs one request or event at a time.
fetch: func(service: option<string>, object: string, req: request) -> result<response, error>;
}
// Outbound WebSockets (`ws:` / `wss:`) through the host's egress guard: the same scheme, port, host
// and address rules as `wasi:http/outgoing-handler`; a connection counts as one of the task's fetches,
// received bytes count against the daily egress quota, and it closes when the task ends.
// Errors: egress_denied, egress_dns, egress_timeout, egress_upstream, egress_limit, egress_quota,
// validation_failed, invalid_state.
interface ws-client {
use sockets.{payload};
record error {
code: string,
message: string,
}
record close-frame {
code: u16,
reason: string,
}
variant event {
message(payload),
// The connection ended (1006 without a close frame).
closed(close-frame),
}
resource connection {
// The subprotocol the server chose.
protocol: func() -> option<string>;
send: func(data: payload) -> result<_, error>;
// The next message or the end of the connection; `none` when nothing came within `timeout-ms`.
recv: func(timeout-ms: u32) -> result<option<event>, error>;
// Code 1000 or 3000-4999.
close: func(code: u16, reason: string) -> result<_, error>;
}
connect: func(url: string, protocols: list<string>) -> result<connection, error>;
}
// Exported by a component that handles socket events and alarms (world `socket-service`). Each
// call is one task, one object at a time. An `err` (or a trap) fails the event: it is delivered
// again (at least once), then given up (a message's socket closes 1011).
interface socket-handler {
use sockets.{socket-info, payload};
record close-info {
code: u16,
reason: string,
was-clean: bool,
}
on-message: func(object: string, socket: socket-info, data: payload) -> result<_, string>;
on-close: func(object: string, socket: socket-info, info: close-info) -> result<_, string>;
on-error: func(object: string, socket: socket-info, code: string, message: string) -> result<_, string>;
on-alarm: func(object: string, scheduled-ms: s64, retry: u32) -> result<_, string>;
}
world guest {
import log;
import kv;
import sql;
import blob;
import queue;
import call;
import platform;
import secrets;
import lock;
import schedule;
import sdk;
import sockets;
import durable;
import ws-client;
}
// A guest that also serves RPC: everything `guest` imports, plus the `rpc` export.
world rpc-service {
include guest;
export rpc;
}
// A guest that handles WebSocket events and alarms: everything `guest` imports, plus the
// `socket-handler` export (required for a durable service).
world socket-service {
include guest;
export socket-handler;
}
// What the runtime binds: every import and every optional export.
world runtime-host {
include guest;
export rpc;
export socket-handler;
}
Conventions¶
- Errors. Every function except
log.logreturnsresult<T, error>. Each interface defines its ownrecord error { code: string, message: string }.codeis a stable string, the same codes the Deno SDK uses; it never contains host paths or driver text. Match oncode, showmessageonly in logs. unavailable. Code that runs outside a task (start-up code while the node pre-creates an instance) getsunavailablefrom every function, andlogdrops the line.- Bytes. KV keys and values, queue bodies and HTTP bodies are
list<u8>. Blob keys arestring. - Buffered bodies. In this version blob contents and the bodies of
callandplatformare passed as whole byte lists. Responses are capped atmax_response_buffered_bytes(10 MB by default). Streaming throughwasi:iois a planned follow-up. - Clock. Every
std:hostcall that had to wait is an I/O boundary: the frozenwasi:clockscatch up with real time when it returns. - Data scope. KV, SQL and blob data belong to the service; no other service can read them.
log¶
Appends a record to the service's logs, tagged with the task id. It counts against the task's 1,000 log lines (later
lines are dropped and counted); a message is cut at 10,000 characters. Lines written to wasi:cli/stdout and
stderr are logged too, as info and error.
kv¶
| Type | Definition |
|---|---|
value |
variant { json(string), bytes(list<u8>) }: JSON text, or raw bytes |
set-options |
{ ttl-seconds: option<u64> } |
list-options |
{ prefix: list<u8>, cursor: option<list<u8>>, limit: u32 } |
list-page |
{ entries: list<tuple<list<u8>, value>>, next-cursor: option<list<u8>> } |
| Function | Result |
|---|---|
get(key) |
option<value>: none when missing or expired |
set(key, value, opts) |
writes the value; with ttl-seconds the key expires after that many seconds |
delete(key) |
bool: whether the key existed |
list(opts) |
one page of entries in lexicographic key order; pass next-cursor back as cursor; limit is clamped to 1 to 1,000 |
incr(key, delta, opts) |
s64: the new value of the counter, see below |
incr adds delta (an s64, may be negative) to an integer counter atomically: the read and the write run in one
transaction on the service's single writer, so concurrent increments never lose an update. A missing or expired key
starts at 0 and gets opts.ttl-seconds; an existing counter keeps its expiry, which gives fixed windows. The counter
is stored as JSON text, so get returns json("<n>").
Limits: keys are non-empty and at most 2 KB, values at most 1 MB.
| Code | When |
|---|---|
validation_failed |
empty key |
kv_key_too_large |
key or list prefix over 2 KB |
kv_value_too_large |
value over 1 MB |
storage_quota |
the service's storage quota is used up |
kv_not_integer |
incr on a value that is not a JSON integer in the s64 range (the value is unchanged) |
kv_overflow |
incr whose result would leave the s64 range |
sql¶
| Type | Definition |
|---|---|
sql-value |
variant { null, integer(s64), real(f64), text(string), blob(list<u8>) } |
statement |
{ sql: string, args: list<sql-value> }, with ? placeholders |
sql-result |
{ columns: list<string>, rows: list<list<sql-value>>, rows-affected: u64, last-insert-rowid: option<s64> } |
| Function | Result |
|---|---|
execute(stmt) |
one sql-result. Read-only statements run on read connections, writes on the service's single writer |
batch(stmts, write) |
one result per statement, all in one transaction. write = false opens a read-only transaction: a statement that writes fails |
There is no interactive transaction in WIT; put statements that must commit together in one batch.
Limits: 1,000 ms per statement by default (storage.sql_budget_ms), at most 10,000 rows per statement and 10 MB of
result values per call, statement text up to 1 MB, up to 10,000 bound parameters. The authorizer refuses ATTACH,
load_extension, the runtime's _rt_* tables and pragmas that change durability, limits or file layout.
| Code | When |
|---|---|
sql_error |
syntax error, constraint violation, a write in a read-only batch |
sql_timeout |
a statement ran over its budget |
sql_not_authorized |
refused by the authorizer |
sql_result_too_large |
over 10,000 rows or 10 MB of results |
storage_quota |
the service's storage quota is used up |
blob¶
| Type | Definition |
|---|---|
meta |
{ key: string, size: u64, content-type: option<string> } |
list-page |
{ items: list<meta>, next-cursor: option<string> } |
| Function | Result |
|---|---|
get(key) |
option<tuple<meta, list<u8>>>: the whole object, read into guest memory |
head(key) |
option<meta> |
put(key, content-type, data) |
writes (or replaces) the object; returns its meta |
delete(key) |
bool: whether the object existed |
list(prefix, cursor, limit) |
one page of objects; limit is clamped to 1 to 1,000 |
Limits: keys are non-empty strings of at most 1 KB; an object is at most 100 MB, but get returns at most 10 MB and
everything you hold also counts against the instance's linear memory limit (128 MB by default).
| Code | When |
|---|---|
validation_failed |
empty key |
blob_key_too_large |
key or prefix over 1 KB |
blob_too_large |
get of an object larger than the buffered response limit |
storage_quota |
the object is over 100 MB, or the storage quota is used up |
queue¶
| Type | Definition |
|---|---|
send-options |
{ delay-seconds: option<u64>, dedup-id: option<string> } |
enqueue(slug, body, opts) -> result<string, error> puts body (at most 1 MB) on the queue of the service slug
in the same tenant, the calling service included, and returns the message id (msg_…). delay-seconds (at most
7 days) delays delivery; a second message with the same dedup-id within 24 hours is dropped.
The consumer receives body parsed as JSON, or as a string when it is not valid JSON, so send JSON bytes. The
target's queue trigger must be on, its plan must allow queues, and its call.allowed_callers (or, when that list
is empty, its environment) must admit the caller.
| Code | When |
|---|---|
not_found |
no service with that slug |
cross_tenant_call |
another tenant's service, and the plan does not allow cross-tenant calls |
forbidden |
the target's queue trigger is off |
trigger_not_allowed |
the target's plan does not allow queues |
call_not_allowed |
the target's caller rules do not admit the caller |
queue_full |
the target's queue is at the plan's max_queue_depth |
call_failed |
the message was refused (over 1 MB, delay over 7 days) or could not be stored |
For queue errors, message repeats the code.
call¶
| Type | Definition |
|---|---|
headers |
list<tuple<string, list<u8>>>: names and byte values, as in wasi:http fields |
request |
{ method: string, path-with-query: string, headers: headers, body: list<u8> } |
response |
{ status: u16, headers: headers, body: list<u8> } |
call(slug, req) -> result<response, error> runs the service slug of the same tenant in-process (no HTTP hop), as
a child task with trigger call. path-with-query must start with /; it is the target's own path, without any
/s/{slug} prefix. Your x-rt-* headers are not passed on.
- The child's wall limit is the smaller of its own and your remaining time.
- A child that fails is a
5xxresponsewithx-rt-reason, not anerror. - Past call depth 15 the result is a
508response withx-rt-reason: call_depth. - The response body is buffered, at most
max_response_buffered_bytes(10 MB).
| Code | When |
|---|---|
not_found |
no service with that slug |
cross_tenant_call |
another tenant's service, and the plan does not allow cross-tenant calls |
forbidden |
the target's call trigger is off |
call_not_allowed |
the target's call.allowed_callers (or environment) does not admit the caller |
trigger_not_allowed |
the target's plan does not allow calls |
invalid_request |
a method, path or header that is not valid HTTP |
response_too_large |
the response body is over the buffered limit |
call_failed |
the call could not be made |
scheduler codes (overloaded, …) |
the node refused to start the child task |
call-rpc(slug, method, args-json) -> result<string, error> is typed RPC over the same path (services.call in Deno):
it runs the callee's method method (a dotted path such as invoices.create) with the JSON argument and returns its
JSON result, each at most 256 KiB. Errors are the callee's own {code, message} or the host's: validation_failed,
method_not_found, response_too_large, invalid_response, call_depth, timeout and the codes above. The callee
may be a Deno service with an rpc export or a component exporting rpc.
sdk¶
Calls method of the operator SDK name with the JSON argument and returns its JSON result (each at most 256 KiB). The
SDK runs in the runtime, never in your component: the call is bound to the release your grants select, so an SDK
update reaches you without a redeploy. Errors: the SDK's own codes, or sdk_not_found, sdk_unavailable (removed),
sdk_not_granted, sdk_version_unavailable, method_not_found, validation_failed, call_depth, timeout. See
Use operator SDKs.
rpc (export)¶
record caller { service: string, slug: option<string>, project: option<string>, environment: option<string>,
tenant: string, plan: option<string> }
handle: func(method: string, args-json: string, caller: option<caller>) -> result<string, error>;
A component of world rpc-service exports rpc to serve RPC: a call to it for /__rt/rpc/<method> runs handle
instead of the HTTP handler, with the caller the runtime stamped, and the host answers the caller with the JSON result
or the {code, message} error (method_not_found for an unknown method, by convention). A component without the
export answers such a call method_not_found without running any code.
platform¶
use call.{request, response};
fetch: func(binding: string, req: request) -> result<response, error>;
Calls the operator binding binding ([[binding]] in the node configuration), from an operator SDK service only: a
tenant's component gets 403 binding_not_allowed. The node uses the request's method,
path, query, headers (minus authorization, cookie and x-rt-*) and body, sends it to the binding's base_url
with the operator's credentials, and returns the answer. The credentials never enter guest memory.
A refusal is a response with an x-rt-reason header, never an error:
| Status | x-rt-reason |
When |
|---|---|---|
| 403 | binding_denied |
method or path not allowed by the binding, or a .. segment |
| 403 | binding_not_allowed |
the tenant's plan may not use the binding |
| 404 | binding_not_found |
no binding with that name |
| 429 | rate_limited |
the binding's per-tenant rate limit |
| 502 | binding_upstream |
the upstream failed |
| Code | When |
|---|---|
invalid_request |
a method, path or header that is not valid HTTP |
response_too_large |
the response body is over the buffered limit |
unavailable |
called outside a task |
See Operator SDKs and bindings.
Linked WASI interfaces¶
Besides std:host, a component may import these packages, at any 0.2.x version:
| Package | What the node provides |
|---|---|
wasi:http |
the incoming-handler export is called per task; outgoing-handler sends requests through the egress guard |
wasi:io |
streams and polling (a blocking wait advances the frozen clock) |
wasi:clocks |
frozen monotonic and wall clocks, whole milliseconds |
wasi:random |
random numbers |
wasi:cli |
environment = the service's env and secrets; stdout → info logs, stderr → error logs; stdin empty; exit ends the task; terminal-* report no terminal |
wasi:filesystem |
linked with no preopened directories: nothing can be opened |
wasi:sockets |
linked with every address denied |
Any other import, a missing wasi:http/incoming-handler export, or the threads proposal makes the upload fail with
422 invalid_artifact.
Using it from Rust¶
Generate bindings with wit-bindgen and take the wasi:http side from the
wasip2 crate. Build for wasm32-wasip2.
wit_bindgen::generate!({
path: "wit", // directory with rt-host.wit
world: "guest",
});
use rt::host::{kv, log, queue};
fn remember(user: &str) -> Result<i64, kv::Error> {
let key = format!("visits/{user}");
let n = kv::incr(key.as_bytes(), 1, kv::SetOptions { ttl_seconds: None })?;
if n == 1 {
let opts = queue::SendOptions { delay_seconds: None, dedup_id: Some(format!("welcome:{user}")) };
if let Err(e) = queue::enqueue("mailer", br#"{"kind":"welcome"}"#, &opts) {
log::log(log::Level::Warn, &format!("enqueue: {}", e.code));
}
}
Ok(n)
}
How WIT types appear in Rust:
| WIT | Rust |
|---|---|
string |
&str as a parameter, String in results |
list<u8> |
&[u8] as a parameter, Vec<u8> in results |
option<T>, result<T, E> |
Option<T>, Result<T, E> |
s64, u64, u32, u16, f64, bool |
i64, u64, u32, u16, f64, bool |
record |
a struct with snake_case fields (kv::SetOptions { ttl_seconds }); passed by reference when it holds strings or lists |
variant, enum |
a Rust enum (kv::Value::Json(String), log::Level::Info) |
tuple<A, B> |
(A, B) |
The interfaces end up in the module rt::host. The edge gateway sample
(sample/apps/edge-gateway/gateway in the runtime repository) uses kv, call, queue, platform and log this
way.
Using it from JavaScript¶
With jco componentize, list the interfaces in your world and put
rt-host.wit under wit/deps/, next to the WASI packages your world refers to:
wit/
├── world.wit
└── deps/
├── rt-host/rt-host.wit
├── wasi-http/package.wit
├── wasi-io/package.wit
└── wasi-clocks/package.wit
package example:app;
world app {
import std:host/kv@0.1.0;
import std:host/sql@0.1.0;
import std:host/log@0.1.0;
export wasi:http/incoming-handler@0.2.10;
}
Each imported interface is an ES module named after it:
import { incr } from "std:host/kv@0.1.0";
import { execute } from "std:host/sql@0.1.0";
import { log } from "std:host/log@0.1.0";
const enc = new TextEncoder();
function countVisit(path) {
const n = incr(enc.encode(`visits:${path}`), 1n, {});
execute({ sql: "INSERT INTO visits (path) VALUES (?)", args: [{ tag: "text", val: path }] });
log("info", `visit ${n} of ${path}`);
return n;
}
How WIT types appear in JavaScript (jco's mapping):
| WIT | JavaScript |
|---|---|
string |
string |
list<u8> |
Uint8Array |
s64, u64 |
bigint |
u32, u16, f64 |
number |
option<T> |
T or undefined |
result<T, E> |
returns T; an err is thrown as an error whose payload is the { code, message } record |
record |
an object with camelCase fields ({ ttlSeconds }, { pathWithQuery }) |
variant |
{ tag, val } ({ tag: "json", val: "42" }) |
enum |
a string ("info") |
tuple<A, B> |
[A, B] |
Imported functions are synchronous. Build with jco componentize src/app.js --wit wit --world-name app --out app.wasm.
Checking a component¶
wasm-tools lists what a component imports and exports, which is what the node checks at deploy:
$ wasm-tools component wit app.wasm | grep -E '^\s*(import|export)'
import std:host/log@0.1.0;
import std:host/kv@0.1.0;
import wasi:io/poll@0.2.12;
import wasi:http/types@0.2.10;
...
export wasi:http/incoming-handler@0.2.10;
Versioning¶
The package version is std:host@0.1.0. A component imports specific functions, and the node links them when it
builds the version: a component that imports a function the node does not provide (built against a newer copy of
the file) passes the deploy check, but its build fails (21ci push --wait reports it; a lazy build answers the first
request with 502 build_failed). Keep your vendored copy in sync with the
node you deploy to; the edge gateway's build.sh warns when its copy differs from the runtime's.