Skip to content

Edge gateway (WASM)

This tutorial builds an authenticating API gateway as a WebAssembly component written in Rust, and puts two internal Deno services behind it. It is for developers who want to see a WASM service use the runtime's host interfaces (std:host/kv, call, queue, sdk, log) and how environments, access: internal and allowed callers lock backends down so that only the gateway can reach them.

WASM Deno

What you build

Three services:

Service Runtime Reachable from Does
edge-gateway WASM component (Rust) the public listener Checks every request, forwards it in-process, audits the decision
edge-notes Deno, Form A only the gateway Per-subject notes in std:sql
edge-audit Deno, Form B only the gateway Stores audit events, ships the ones the gateway could not, serves recent events

Before any backend sees a request, the gateway checks, in this order:

  1. Path, method and query shape, and the route (400, 404, 405).
  2. A rate limit per client address, before any token work (429 with Retry-After).
  3. An HS256 bearer token: algorithm pinned, key picked by kid, signature checked in constant time, exp, nbf, iat, a lifetime of at most 900 s, aud, optional iss (401).
  4. The scope for the route and method (403).
  5. A rate limit per token subject (429).
  6. The body: application/json, at most 64 KiB, well-formed (400, 413, 415).

Then it forwards the request with std:host/call, answers the client, and finally ships an audit event to the operator's audit API with the operator SDK (std:host/sdk) and hands it to edge-audit (std:host/queue). The SDK also answers GET /v1/platform, which shows an SDK update reaching the running gateway without a redeploy.

Why WASM here. A gateway runs on every request and holds the signing keys, so it should be the most predictable and most locked-down piece in the path. Each request gets a fresh component instance (possibly pre-instantiated by the warm pool), so no request can see another's memory. The component imports only the capabilities it needs: WASI environment and clocks plus std:host/{log,kv,queue,call,sdk}; it has no filesystem preopens and its sockets are denied. There is no JIT warm-up and no garbage collector. The backends are ordinary Deno services: quick to write, never exposed. See Execution for how both runtimes run tasks.

Architecture

flowchart LR
  C["Client"] -- "HTTPS, Bearer JWT" --> GW
  subgraph edge["environment: edge"]
    GW["edge-gateway (WASM, public)"]
  end
  subgraph backend["environment: edge-backend, access: internal"]
    N["edge-notes (Deno)"]
    A["edge-audit (Deno)"]
  end
  GW --- KV[("std:host/kv: rate-limit counters")]
  GW -- "std:host/call" --> N
  GW -- "std:host/call GET /recent" --> A
  GW -- "std:host/queue: audit event" --> A
  GW -- "std:host/sdk invoke" --> SDK["Operator SDK acme (runtime service)"]
  A -- "std:sdk audit.ship: retries" --> SDK
  SDK -- "binding acme" --> OP["Operator audit API"]
  N --- NS[("std:sql: notes")]
  A --- AS[("std:sql: audit")]

The backends have access: internal, so the public listener answers 404 for them. They live in another environment than the gateway and list it in call.allowed_callers, so the runtime admits calls and enqueues from the gateway only. On top of that, both backends refuse anything whose ctx.trigger is not call (or queue). That is why they can trust the x-gw-sub header the gateway sets after it verified the token.

Prerequisites

  • A running node and a tenant key in RT_KEY (see First run).
  • 21ci (see Install), or bash, curl and jq for sample/scripts/*.sh.
  • Rust with the wasm32-wasip2 target (build.sh adds the target with rustup when it is missing). Optional: wasm-tools, which build.sh uses to check the component's imports and export.
  • openssl and jq for mint-token.sh, which signs test tokens.
  • Optional, for audit shipping and /v1/platform: the operator SDK from sample/operator-sdk/, published and granted (21ci sdk publish acme 1.0.0 sample/operator-sdk/acme-sdk, 21ci sdk grants set node acme --allow), its acme binding pointing at the mock API, and a tenant on a plan that binding allows. See Operator SDKs and bindings. Without it the trail stays in edge-audit's own database.

Build the component

cd sample/apps/edge-gateway
gateway/build.sh --test     # unit tests on the host, then the release build

The crate builds two ways: as a cdylib for wasm32-wasip2, which rustc turns into a WebAssembly component, and as an rlib, so cargo test runs the pure modules (token, request, ratelimit, audit, config) on your machine:

gateway/Cargo.toml
[package]
name = "edge-gateway"
version = "1.0.0"
edition = "2021"
publish = false

# A cdylib built for `wasm32-wasip2` is a WebAssembly component (rustc runs wasm-component-ld).
# The rlib lets `cargo test` run the pure modules (token, request, ratelimit, audit, config) on the host.
[lib]
crate-type = ["cdylib", "rlib"]

[dependencies]
# wasi:http types and the `wasi:http/incoming-handler` export (world wasi:http/proxy).
wasip2 = "2"
# Bindings for the runtime's own imports, from the vendored wit/rt-host.wit (package std:host@0.1.0).
wit-bindgen = "0.62"
hmac = "0.12"
sha2 = "0.10"
base64 = "0.22"
serde_json = "1"

[profile.release]
opt-level = "s"
lto = true
strip = true
panic = "abort"
codegen-units = 1

# Standalone crate, not a member of the runtime workspace.
[workspace]
  • wasip2 provides the wasi:http types and the wasi:http/incoming-handler export.
  • wit-bindgen generates Rust bindings for the runtime's own imports from gateway/wit/rt-host.wit, a vendored copy of the runtime's wit/rt-host.wit (package std:host@0.1.0, see WIT reference).
  • The release profile optimizes for size and aborts on panic: a panic in a component is a trap, which the runtime reports as 500 guest_error.

build.sh warns when the vendored WIT drifts from the runtime's copy, runs the tests with --test, builds the release component and, with wasm-tools installed, checks that it exports wasi:http/incoming-handler@0.2.x and imports nothing the runtime does not link:

gateway/build.sh
# wit/rt-host.wit is a vendored copy of the runtime's ../../../../wit/rt-host.wit: warn if they drift.
UPSTREAM="../../../../wit/rt-host.wit"
if [[ -f "$UPSTREAM" ]] && ! cmp -s "$UPSTREAM" wit/rt-host.wit; then
  echo "warning: wit/rt-host.wit differs from $UPSTREAM; copy it over if the host interface changed" >&2
fi

if [[ "${1:-}" == "--test" ]]; then
  cargo test --target-dir target
fi

echo "Building edge-gateway -> WASI P2 component (wasm32-wasip2, release)..."
cargo build --release --target wasm32-wasip2 --target-dir target

OUT="target/wasm32-wasip2/release/edge_gateway.wasm"
[[ -f "$OUT" ]] || { echo "error: $OUT was not produced" >&2; exit 1; }
echo "Built $OUT ($(wc -c <"$OUT" | tr -d ' ') bytes)"

# The runtime links wasi:{io,clocks,random,cli,http,filesystem,sockets}/* and std:host/*; anything
# else, or a missing wasi:http/incoming-handler export, is `422 invalid_artifact` at deploy.
if command -v wasm-tools >/dev/null; then
  WIT="$(wasm-tools component wit "$OUT")"
  grep -Eq '^\s*export wasi:http/incoming-handler@0\.2\.' <<<"$WIT" \
    || { echo "error: component does not export wasi:http/incoming-handler@0.2.x" >&2; exit 1; }
  IMPORTS="$(grep -E '^\s*import ' <<<"$WIT" | sed -E 's/^ *import //; s/;$//')"
  BAD="$(grep -Ev '^(wasi:(io|clocks|random|cli|http|filesystem|sockets)/[a-z-]+@0\.2\.[0-9]+|std:host/[a-z]+@0\.1\.0)$' <<<"$IMPORTS" || true)"
  if [[ -n "$BAD" ]]; then
    echo "error: imports outside the runtime policy:" >&2
    sed 's/^/  /' <<<"$BAD" >&2
    exit 1
  fi
  echo "Imports (all linked by the runtime):"
  sed 's/^/  /' <<<"$IMPORTS"
else
  echo "note: install wasm-tools to check the component's imports and export"
fi

A component with other imports, or without that export, is refused at deploy with 422 invalid_artifact. The output is gateway/target/wasm32-wasip2/release/edge_gateway.wasm.

Deploy it

1. Create the services with their isolation, then push

Create the backends with access: internal, their own environment and the gateway as the only allowed caller before any code is uploaded, so they are never public, not even for a moment.

cd sample/apps/edge-gateway
21ci service create edge-notes --runtime deno --access internal --env edge-backend --allowed-caller edge-gateway
21ci service create edge-audit --runtime deno --access internal --env edge-backend --allowed-caller edge-gateway
21ci service create edge-gateway --runtime wasm --env edge

21ci push notes/main.ts --service edge-notes --wait
21ci push audit/src --service edge-audit --wait
21ci push gateway/target/wasm32-wasip2/release/edge_gateway.wasm --service edge-gateway --wait
cd sample/apps/edge-gateway
create() {  # JSON body of POST /v1/services
  curl -sS -X POST -H "Authorization: Bearer $RT_KEY" -H 'Content-Type: application/json' \
    -d "$1" "$RT_API/v1/services"
}
backend() {
  jq -nc --arg s "$1" '{slug: $s, runtime: "deno", environment: "edge-backend", access: "internal",
                        call: {allowed_callers: ["edge-gateway"]}}'
}
create "$(backend edge-notes)"
create "$(backend edge-audit)"
create '{"slug": "edge-gateway", "runtime": "wasm", "environment": "edge"}'

export RT_COMPILE=eager
../../scripts/deploy.sh notes/main.ts edge-notes
../../scripts/deploy.sh audit/src edge-audit
../../scripts/deploy.sh gateway/target/wasm32-wasip2/release/edge_gateway.wasm edge-gateway

Slug or id in allowed_callers

A slug entry admits whichever service holds that slug when the call is made. Where that matters, list the gateway's svc_… id instead. See Calls and queues.

2. Set the signing key and limits

KEY=$(openssl rand -hex 32)       # keep it: token issuers sign with it
printf %s "k1:$KEY" | 21ci secret set edge-gateway GATEWAY_KEYS
21ci env set edge-gateway GATEWAY_RATE_LIMIT=120 GATEWAY_IP_RATE_LIMIT=600 GATEWAY_RATE_WINDOW=60
21ci schedule add edge-audit --every 5m      # optional: retries shipping, prunes shipped events after 30 days

The component reads its settings from the WASI environment, where the runtime puts the service's env and secrets together:

Name Kind Default Meaning
GATEWAY_KEYS secret required kid:hex[,kid:hex], each key at least 32 bytes. Rotation: add k2, move issuers to it, remove k1
GATEWAY_AUDIENCE env edge-gateway Required aud
GATEWAY_ISSUER env unset Required iss when set
GATEWAY_MAX_TOKEN_TTL env 900 Maximum exp - iat in seconds
GATEWAY_RATE_LIMIT env 120 Requests per window per token subject; 0 turns it off
GATEWAY_IP_RATE_LIMIT env 600 Requests per window per client address (IPv6 per /64), checked before the token; 0 turns it off
GATEWAY_RATE_WINDOW env 60 Window in seconds, for both limits
GATEWAY_NOTES_SERVICE, GATEWAY_AUDIT_SERVICE env edge-notes, edge-audit Backend slugs
GATEWAY_AUDIT env mutations all, mutations (writes and every denial) or off
GATEWAY_SDK env acme Operator SDK the gateway ships each event with (audit.ship) and answers /v1/platform from; off leaves all shipping to edge-audit
GATEWAY_MAX_BODY env 65536 Request body limit in bytes

edge-audit reads AUDIT_SDK (default acme, off never ships) and AUDIT_RETENTION_DAYS (default 30, for shipped events). Keep the SDK equal on both services. To keep every event local, set GATEWAY_SDK=off and AUDIT_SDK=off.

Try it

mint-token.sh signs a short-lived token with the same key, for local use:

mint-token.sh
# Mint a short-lived HS256 JWT for the edge gateway (local use and the smoke test).
#
#   GATEWAY_KEY_HEX=<hex key> ./mint-token.sh <sub> "<scopes>" [ttl_seconds]
#   GATEWAY_KEY_HEX=$KEY ./mint-token.sh alice "notes:read notes:write" 300
#
# Env: GATEWAY_KEY_HEX   the key, as in GATEWAY_KEYS (kid:hex) on the gateway (required)
#      GATEWAY_KID       key id (default k1)
#      GATEWAY_AUDIENCE  aud claim (default edge-gateway)
#      GATEWAY_ISSUER    iss claim (optional)
#      MINT_NOW          issue time in unix seconds (default: now), e.g. to mint an expired token
#
# The key is passed to openssl on its command line, so other local users could see it in `ps`:
# use this on a development machine. Production clients mint tokens in their own code (any JWT
# library with HS256, or HMAC-SHA256 over "<b64url header>.<b64url payload>").
B=http://127.0.0.1:8080/s/edge-gateway
T=$(GATEWAY_KEY_HEX=$KEY ./mint-token.sh alice "notes:read notes:write")
curl -sS -X POST $B/v1/notes -H "Authorization: Bearer $T" -H 'Content-Type: application/json' -d '{"text": "hi"}'
curl -sS $B/v1/notes -H "Authorization: Bearer $T"
curl -sS http://127.0.0.1:8080/s/edge-notes/      # 404: the backend is not on the public listener

The bearer token reaches the component unchanged: the platform removes an Authorization header only when it carries one of its own tenant keys (Bearer rtk_…).

Method and path Scope Backend
GET /healthz none the gateway itself (503 when misconfigured)
GET /v1/notes?limit=&before= notes:read edge-notes: own notes, newest first
POST /v1/notes {text, tags?} notes:write 201 with Location
GET /v1/notes/{id} notes:read own note or 404
PUT /v1/notes/{id} {text, tags?} notes:write
DELETE /v1/notes/{id} notes:write
GET /v1/audit/recent?limit=&sub=&ip= audit:read edge-audit: events plus the shipping state

Gateway errors are {"error": {"code", "message"}} with the codes invalid_request, not_found, method_not_allowed, invalid_token (with WWW-Authenticate: Bearer), insufficient_scope, rate_limited (with Retry-After), unsupported_media_type, too_large, invalid_json, invalid_body (a body that cannot be read, or a missing JSON body), unexpected_body (a body on GET or DELETE), upstream_unavailable, upstream_error and gateway_misconfigured (503). Every answer carries x-request-id (the task id) and content-length, and the ratelimit-limit, ratelimit-remaining and ratelimit-reset headers once the client is known.

How the code works

The crate is split so that everything but the WASI glue is a plain Rust module with host-side unit tests:

gateway/src/lib.rs
//! Edge gateway: a WASI P2 HTTP component in front of internal services.
//!
//! Per request, in this order, before any backend sees anything:
//!   1. method and path validation, routing          (400 / 404 / 405)
//!   2. per-client-address rate limit in `std:host/kv` (429 + Retry-After), keyed on the platform's
//!      `x-rt-client-ip`, so a flood of bad tokens is cut before any token work
//!   3. `Authorization: Bearer <HS256 JWT>` checks    (401): signature in constant time, alg pinned,
//!      short lifetime, audience, optional issuer; keys from the `GATEWAY_KEYS` secret
//!   4. scope for the route and method                (403)
//!   5. per-subject rate limit in `std:host/kv`        (429 + Retry-After)
//!   6. body rules: JSON only, size cap, well-formed  (411 / 413 / 415 / 400)
//!   7. forward with `std:host/call` to a backend that accepts calls only from this gateway; the
//!      backend gets `x-gw-sub`, `x-gw-scopes`, `x-gw-request-id`, `x-gw-client-ip` and nothing
//!      the client invented
//!   8. after the response: the audit event to the operator's audit log through the operator SDK
//!      (`std:host/sdk`, `audit.ship`), then to the audit service with `std:host/queue` (dedup id = task id)
//!
//! Everything runs inside the component: a fresh instance per request is ready in microseconds
//! and is gone afterwards, so no request can see another's memory.

pub mod audit;
pub mod config;
pub mod ratelimit;
pub mod request;
pub mod token;

#[cfg(target_arch = "wasm32")]
mod component;

Bindings and the export

gateway/src/component.rs
use crate::{audit, config, ratelimit, request, token};

// `std` is also the Rust crate name, so the generated `std:host` module lives in its own scope.
mod bindings {
    wit_bindgen::generate!({
        path: "wit",
        world: "guest",
    });
}

use std::net::IpAddr;
use std::time::{SystemTime, UNIX_EPOCH};

use bindings::std::host::{call as rtcall, kv, log, queue, sdk};
use wasip2::exports::http::incoming_handler::Guest;
use wasip2::http::types::{
    Fields, IncomingBody, IncomingRequest, Method, OutgoingBody, OutgoingResponse, ResponseOutparam,
};
use wasip2::io::streams::StreamError;

use config::Config;
use request::{Headers, HttpMethod, Route, Target};

wit_bindgen::generate! turns the vendored WIT world guest into the rt::host::* modules. The wasip2 crate's export! macro makes Gateway the component's wasi:http/incoming-handler. The handler gets an IncomingRequest and a ResponseOutparam. The runtime adds x-rt-task-id to the request (the gateway uses it as the request id) and, for HTTP requests, x-rt-client-ip.

The pipeline

gateway/src/component.rs
}

#[allow(clippy::too_many_arguments)]
fn handle(
    cfg: &Config,
    req: &IncomingRequest,
    headers: &Headers,
    method: &str,
    path: &str,
    query: &str,
    request_id: &str,
    seen: &mut Seen,
) -> Reply {
    // 1. Shape of the request.
    if let Err(e) = request::validate_path(path).and_then(|_| request::validate_query(query)) {
        return Reply::error(400, "invalid", "invalid_request", e);
    }
    if path == "/healthz" {
        return Reply::json(200, "ok", serde_json::json!({ "ok": true }));
    }
    let Some(route) = request::match_route(path) else {
        return Reply::error(404, "invalid", "not_found", "no such route");
    };
    seen.route = Some(route.target.name());
    let Some(m) = HttpMethod::parse(method).filter(|m| request::method_allowed(route.target, *m)) else {
        return Reply::error(405, "invalid", "method_not_allowed", "method not allowed on this route");
    };

    let now = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_secs())
        .unwrap_or(0);

    // 2. How often from this address? Before the token is looked at, so a flood of bad tokens
    //    costs one counter increment per request and never reaches a backend.
    if let Some(ip) = seen.ip {
        let limit = rate_limit(cfg, cfg.ip_rate_limit, |w| ratelimit::ip_key(ip, w), now);
        if let Some(d) = limit.filter(|d| !d.allowed) {
            return too_many(d, "ip_rate_limited");
        }
    }

    // 3. Who is calling.
    let unauthorized = |reason: &str| {
        let mut r = Reply::error(401, "denied", "invalid_token", "a valid bearer token is required")
            .header("www-authenticate", "Bearer realm=\"edge\", error=\"invalid_token\"");
        r.reason = Some(reason.to_string());
        r
    };
    let token = match request::bearer(headers) {
        Ok(t) => t,
        Err(_) => return unauthorized("missing_token"),
    };
    let policy = token::Policy {
        keys: &cfg.keys,
        audience: &cfg.audience,
        issuer: cfg.issuer.as_deref(),
        max_ttl: cfg.max_ttl,
        leeway: cfg.leeway,
    };
    let claims = match token::verify(token, &policy, now) {
        Ok(c) => c,

The per-address limit runs before the token is even parsed, so a flood of forged tokens costs one counter increment per request. The address comes from x-rt-client-ip, which the platform sets to the client address it resolved (behind ingress.trusted_proxies); a client-sent value is removed first. Token errors map to one public code, invalid_token, while the precise reason (expired, bad_signature, …) goes to the log and the audit trail.

gateway/src/component.rs
    };
    seen.sub = Some(claims.sub.clone());

    // 4. May they do this?
    let scope = request::required_scope(route.target, m);
    if !claims.has_scope(scope) {
        return Reply::error(
            403,
            "denied",
            "insufficient_scope",
            &format!("this request needs the {scope} scope"),
        );
    }

    // 5. How often from this subject?
    let limit = rate_limit(cfg, cfg.rate_limit, |w| ratelimit::sub_key(&claims.sub, w), now);
    if let Some(d) = limit.filter(|d| !d.allowed) {
        return too_many(d, "rate_limited");
    }

    // 6. Body.
    let body = match read_body(req, headers, m, cfg.max_body) {
        Ok(b) => b,
        Err(r) => return with_limit(r, limit),
    };

    // 7. Forward (or answer from the operator SDK).
    if route.target == Target::Platform {
        return with_limit(platform_info(cfg), limit);
    }

Token verification

gateway/src/token.rs
pub fn verify(token: &str, p: &Policy, now: u64) -> Result<Claims, TokenError> {
    if token.len() > MAX_TOKEN {
        return Err(TokenError::Malformed);
    }
    let mut parts = token.split('.');
    let (h, pl, s) = match (parts.next(), parts.next(), parts.next(), parts.next()) {
        (Some(h), Some(pl), Some(s), None) => (h, pl, s),
        _ => return Err(TokenError::Malformed),
    };

    // 1. Header: algorithm and key only.
    let header = object(&b64(h, 512)?)?;
    if header.get("alg").and_then(Value::as_str) != Some("HS256") || header.contains_key("crit") {
        return Err(TokenError::UnsupportedAlg);
    }
    if let Some(typ) = header.get("typ") {
        if typ.as_str().map(|t| t.eq_ignore_ascii_case("JWT")) != Some(true) {
            return Err(TokenError::Malformed);
        }
    }
    let key = match header.get("kid") {
        Some(Value::String(kid)) => p.keys.iter().find(|k| k.kid == *kid),
        Some(_) => None,
        None if p.keys.len() == 1 => p.keys.first(),
        None => None,
    }
    .ok_or(TokenError::UnknownKey)?;

    // 2. Signature over "<header>.<payload>", compared in constant time by `verify_slice`.
    let sig = b64(s, 64)?;
    let mut mac = Hmac::<Sha256>::new_from_slice(&key.secret).map_err(|_| TokenError::UnknownKey)?;
    mac.update(h.as_bytes());
    mac.update(b".");
    mac.update(pl.as_bytes());
    mac.verify_slice(&sig).map_err(|_| TokenError::BadSignature)?;

The order matters. The header is parsed only to pick the algorithm and the key: anything but HS256 is refused, including none, and so is a crit header. The HMAC over <header>.<payload> is checked with verify_slice, which compares in constant time, before the payload is parsed at all. Only then are the claims trusted:

gateway/src/token.rs
    // 3. Claims, now authenticated.
    let c = object(&b64(pl, 2048)?)?;
    let num = |name: &str| c.get(name).and_then(Value::as_u64);
    let exp = num("exp").ok_or(TokenError::InvalidClaims)?;
    let iat = num("iat").ok_or(TokenError::InvalidClaims)?;
    if now > exp.saturating_add(p.leeway) {
        return Err(TokenError::Expired);
    }
    match c.get("nbf") {
        None => {}
        Some(v) => match v.as_u64() {
            Some(nbf) if nbf <= now.saturating_add(p.leeway) => {}
            Some(_) => return Err(TokenError::NotYetValid),
            None => return Err(TokenError::InvalidClaims),
        },
    }
    if iat > now.saturating_add(p.leeway) {
        return Err(TokenError::IssuedInFuture);
    }
    if exp <= iat || exp - iat > p.max_ttl {
        return Err(TokenError::LifetimeTooLong);
    }

WASM clocks are frozen at the start of the task, which is the right reference time for exp. The 30 s leeway covers clock skew between the token issuer and the node.

Exact rate limits with kv::incr

gateway/src/component.rs
    with_limit(r, limit)
}

/// Counts this request in the current window (`kv::incr`: atomic, so the limit is exact) and
/// decides on the new count. None when the limit is off or the store failed: availability over
/// strictness, a KV failure does not lock everyone out (it is logged).
fn rate_limit(
    cfg: &Config,
    limit: u64,
    key: impl FnOnce(ratelimit::Window) -> Vec<u8>,
    now: u64,
) -> Option<ratelimit::Decision> {
    if limit == 0 {
        return None;
    }
    let w = ratelimit::window(now, cfg.rate_window);
    // The TTL applies when the increment creates the key: each window's counter expires on its own.
    let opts = kv::SetOptions {
        ttl_seconds: Some(cfg.rate_window + 5),
    };
    match kv::incr(&key(w), 1, opts) {
        Ok(count) => Some(ratelimit::decide(u64::try_from(count).unwrap_or(0), limit, w)),
        Err(e) => {
            log::log(log::Level::Warn, &format!("rate limit store: {}", e.code));
            None
        }
    }
}

fn with_limit(r: Reply, limit: Option<ratelimit::Decision>) -> Reply {
    match limit {
        Some(d) => r
            .header("ratelimit-limit", d.limit.to_string())
            .header("ratelimit-remaining", d.remaining.to_string())
            .header("ratelimit-reset", d.reset_in.to_string()),
        None => r,
    }
}

fn too_many(d: ratelimit::Decision, reason: &str) -> Reply {
    let mut r = with_limit(
        Reply::error(429, "limited", "rate_limited", "too many requests").header("retry-after", d.reset_in.to_string()),
        Some(d),
    );

kv::incr adds 1 to the counter for the current window and returns the new value in one atomic step on the service's single SQLite writer, so concurrent requests never share a count and the limit is exact within a window. The TTL applies when the call creates the key, so every window's counter expires on its own. Keys are per subject or per address, and IPv6 clients count per /64:

gateway/src/ratelimit.rs
pub fn sub_key(sub: &str, w: Window) -> Vec<u8> {
    format!("rl/sub/{sub}/{}", w.start).into_bytes()
}

pub fn ip_key(ip: IpAddr, w: Window) -> Vec<u8> {
    format!("rl/ip/{}/{}", client_bucket(ip), w.start).into_bytes()
}

/// What a per-address limit counts: an IPv4 address, or the /64 of an IPv6 address (a subscriber
/// usually holds a whole /64, so counting single IPv6 addresses would be trivial to dodge). An
/// IPv4-mapped IPv6 address counts as its IPv4 address.
pub fn client_bucket(ip: IpAddr) -> String {
    match ip {
        IpAddr::V4(v4) => v4.to_string(),
        IpAddr::V6(v6) => match v6.to_ipv4_mapped() {
            Some(v4) => v4.to_string(),
            None => {
                let s = v6.segments();
                format!("{:x}:{:x}:{:x}:{:x}::/64", s[0], s[1], s[2], s[3])
            }
        },
    }
}

The interface, from the runtime's WIT:

wit/rt-host.wit
  }

  record error {
    code: string,
    message: string,
  }

A KV error lets the request through and logs a warning (availability over strictness). A fixed window still admits up to twice the limit across a window boundary, so keep the service's ingress.rate_limit as the global cap.

Forwarding with std:host/call

gateway/src/component.rs
#[allow(clippy::too_many_arguments)]
fn forward(
    cfg: &Config,
    route: &Route,
    m: HttpMethod,
    query: &str,
    headers: &Headers,
    body: Vec<u8>,
    claims: &token::Claims,
    request_id: &str,
    client_ip: Option<IpAddr>,
) -> Reply {
    let slug = match route.target {
        Target::Notes => &cfg.notes_service,
        Target::Audit | Target::Platform => &cfg.audit_service,
    };
    let mut fwd = request::filter(headers, request::FORWARD_REQUEST);
    fwd.push(("x-gw-sub".into(), claims.sub.clone().into_bytes()));
    fwd.push(("x-gw-scopes".into(), claims.scopes.join(" ").into_bytes()));
    fwd.push(("x-gw-request-id".into(), request_id.as_bytes().to_vec()));
    if let Some(ip) = client_ip {
        fwd.push(("x-gw-client-ip".into(), ip.to_string().into_bytes()));
    }
    let path_with_query = if query.is_empty() {
        route.rest.clone()
    } else {
        format!("{}?{query}", route.rest)
    };
    let call_req = rtcall::Request {
        method: m.as_str().into(),
        path_with_query,
        headers: fwd,
        body,
    };

    match rtcall::call(slug, &call_req) {
        Ok(res) => {
            let mut headers = request::filter(&res.headers, request::PASS_RESPONSE);
            if !headers.iter().any(|(k, _)| k == "cache-control") {
                headers.push(("cache-control".into(), b"no-store".to_vec()));
            }
            let outcome = if res.status >= 500 { "upstream_error" } else { "ok" };
            let mut r = Reply {
                status: res.status,
                headers,
                body: res.body,
                outcome,
                reason: None,
            };
            if res.status >= 500 {
                // Do not leak a backend's error page; keep its status.
                r = Reply::error(
                    res.status.clamp(502, 504),
                    "upstream_error",
                    "upstream_error",
                    "the backend failed",
                );
                r.reason = Some(format!("backend {}", res.status));
            }
            r
        }
        Err(e) => {
            // not_found, call_not_allowed (allowed_callers / environment), forbidden, call_failed …
            log::log(log::Level::Error, &format!("call {slug}: {} ({})", e.code, e.message));
            let mut r = Reply::error(
                502,
                "upstream_error",
                "upstream_unavailable",
                "the backend is not reachable",
            );
            r.reason = Some(e.code);
            r
        }
    }
}

The backend sees only an allowlist of client headers plus the gateway's own x-gw-* headers:

gateway/src/request.rs
/// Request headers a backend may see. Everything else (cookies, the client's Authorization,
/// spoofed x-gw-*, the platform's x-rt-*, hop-by-hop headers) stops at the gateway; the gateway
/// adds its own x-gw-* (the client address as `x-gw-client-ip`).
pub const FORWARD_REQUEST: &[&str] = &["content-type", "accept", "if-match", "if-none-match"];

/// Response headers passed back to the client.
pub const PASS_RESPONSE: &[&str] = &["content-type", "etag", "location", "cache-control", "retry-after"];
  • rtcall::call runs the backend in-process, with no HTTP hop. Only the method, path and query, headers and body are used. The runtime checks the target's environment and call.allowed_callers; a refusal comes back as an error (call_not_allowed, not_found, …), which the gateway turns into 502 upstream_unavailable.
  • A backend 5xx becomes upstream_error without the backend's body, so internal error pages never leak.
  • Call bodies are buffered (no streaming yet), which is fine for JSON within GATEWAY_MAX_BODY.

The audit trail: answer first, ship after

gateway/src/component.rs
            ),
            _ => None,
        };
        reply
            .headers
            .push(("x-request-id".into(), request_id.as_bytes().to_vec()));
        // The client has the whole response now (buffered, with content-length); the audit work
        // runs after it, while this instance is still held (bounded by the wall limit).
        send(out, reply);

send writes the whole buffered response with a content-length, so the client has it at once. Only then does deliver run:

gateway/src/component.rs
/// `GET /v1/platform`: the operator SDK's `getPlatformInfo`, answered by whichever SDK release the
/// gateway's grants select now (an SDK update reaches it without a redeploy). The SDK's refusal
/// (sdk_unavailable after a removal, sdk_not_granted, ...) is a 502 with that code.
fn platform_info(cfg: &Config) -> Reply {
    let Some(name) = cfg.sdk.as_deref() else {
        return Reply::error(404, "invalid", "not_found", "no operator SDK is configured (GATEWAY_SDK=off)");
    };
    match sdk::invoke(name, "getPlatformInfo", "null") {
        Ok(json) => match serde_json::from_str::<serde_json::Value>(&json) {
            Ok(v) => Reply::json(200, "ok", v).header("cache-control", "no-store"),
            Err(_) => Reply::error(502, "upstream_error", "invalid_response", "the SDK answered no JSON"),
        },
        Err(e) => {
            log::log(log::Level::Warn, &format!("sdk {name}: {} ({})", e.code, e.message));
            Reply::error(502, "upstream_error", &e.code, "the operator SDK is not available")
        }
    }
}

/// Runs after the response: ships the event to the operator's audit log through the SDK, then
/// enqueues it with the result to the audit service (the local trail; it retries what was not
/// shipped). The dedup id (the task id) makes a retried enqueue harmless. The request has been
/// answered already, so nothing here can fail it: failures are logged.
fn deliver(cfg: &Config, request_id: &str, event: serde_json::Value) {
    let shipped = cfg.sdk.as_deref().map(|name| ship(name, &event));
    if let Some(Err(e)) = &shipped {
        log::log(
            log::Level::Warn,
            &format!("audit shipping: {e} (the audit service retries)"),
        );
    }
    let message = audit::queue_message(event, shipped.as_ref());
    let opts = queue::SendOptions {
        delay_seconds: None,
        dedup_id: (request_id != "-").then(|| format!("gw:{request_id}")),
    };
    if let Err(e) = queue::enqueue(&cfg.audit_service, message.to_string().as_bytes(), &opts) {
        log::log(
            log::Level::Warn,
            &format!("audit enqueue to {}: {}", cfg.audit_service, e.code),
        );
    }
}

/// `audit.ship({"source", "events": [event]})` of the operator SDK. The SDK holds the operator
/// binding (credentials injected by the node, the gateway's tenant forwarded); no SDK code is in
/// this component.
fn ship(name: &str, event: &serde_json::Value) -> Result<(), String> {
    let args = String::from_utf8(audit::shipment(event)).unwrap_or_default();
    match sdk::invoke(name, "audit.ship", &args) {
        Ok(_) => Ok(()),
        Err(e) => Err(audit::ship_error(name, &e.code)),
    }
}
  • sdk::invoke calls the operator SDK's audit.ship. The SDK is a runtime service of the operator: no SDK code is in the component, and the SDK release that runs is the one the gateway's grants select now. The SDK reaches the operator API through its binding, which injects the credentials and forwards the gateway's tenant. A failure is an error with a stable code (sdk_not_granted, sdk_unavailable, or the SDK's own, such as binding_not_allowed).
  • GET /v1/platform is answered the same way, from the SDK's getPlatformInfo: when the operator publishes a new SDK release, the next request gets its answer, with no redeploy of the gateway.
  • The event then goes to edge-audit's queue with the shipping result and dedup_id: "gw:<task id>", so a retried enqueue is delivered once.
  • Nothing here can fail the request: it has been answered already. Failures are logged.

The runtime ends the response stream only when the handler returns, so the instance and its concurrency slot stay busy for the round trip to the operator API, bounded by the wall limit. To keep that outbound call off the hot path, set GATEWAY_SDK=off and let edge-audit ship every event in batches.

The SDK interface in the runtime's WIT:

wit/rt-host.wit
// 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 backends

edge-notes is a Form A handler that trusts x-gw-sub only because nothing but the gateway can call it, and checks that once more:

notes/main.ts
export default async function (req: Request, ctx: Ctx): Promise<Response> {
  // Defense in depth on top of access=internal and allowed_callers.
  if (ctx.trigger !== "call") return fail(404, "not_found", "not found");
  const owner = req.headers.get("x-gw-sub") ?? "";
  if (!SUBJECT.test(owner)) return fail(400, "no_subject", "missing x-gw-sub (call through the gateway)");

Every query is scoped by that owner (WHERE … AND owner = ?), so one subject can never read another's notes, even with a spoofed x-gw-sub header: the gateway drops client x-gw-* headers before it adds its own.

edge-audit is a Form B service with a queue consumer, a scheduled handler and a fetch for /recent. Delivery is at least once, so the event id (the gateway's task id) is the primary key and a redelivered event is stored once:

audit/src/main.ts
// What the gateway already shipped is stored as shipped, so it is never sent twice.
async function store(events: AuditEvent[]) {
  const now = Date.now();
  await sql.batch(events.map((e) => ({
    sql: `INSERT OR IGNORE INTO audit (id, at, sub, ip, method, path, route, status, outcome, reason, received_at, shipped_at)
          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
    args: [e.id, e.at, e.sub, e.ip, e.method, e.path, e.route, e.status, e.outcome, e.reason, now, e.shipped ? now : null],
  })), "write");
}

  // At-least-once delivery: the event id is the primary key, so a redelivery stores nothing new.
  async queue(batch: { messages: QueueMessage[] }, _ctx: Ctx): Promise<void> {
    await ensureSchema();
    const events: AuditEvent[] = [];
    for (const m of batch.messages) {
      const e = parseAuditEvent(m.body);
      if (e) events.push(e);
      else console.warn(`dropping malformed audit message ${m.id}`); // a retry cannot fix it
    }
    if (events.length) await store(events); // a throw here fails the task: the batch is redelivered
    // The gateway reports how its own attempt went; ship now only what it could not (or did not
    // try to) ship, together with anything still pending. Shipping failures are not delivery
    // failures: the events are stored and stay pending for the schedule.
    const attempt = lastGatewayAttempt(events);
    if (attempt) await kv.set("ship", attempt);
    if (events.some((e) => !e.shipped)) await ship();
  },

Events the gateway could not ship are shipped right away in one batch with sdk(AUDIT_SDK).audit.ship (std:sdk), and again by the optional schedule. An attempt that timed out after the operator API accepted it is shipped again, so the operator API should deduplicate by event id.

Test it

Unit tests. gateway/build.sh --test runs 21 Rust tests on the host: tokens (forgery, algorithm tricks, malformed input, time and audience checks, issuer, and a token produced by mint-token.sh), routing, path rules, the bearer header, client addresses and rate-limit keys, the audit event and shipping results, and configuration. audit/test/events.test.ts has 5 tests for event validation and the shipping state.

gateway/build.sh --test
(cd audit && node --test test/*.test.ts)     # Node >= 22.18, or: deno test

Smoke test. smoke.sh builds the component if it is missing and deploys edge-smoke-gateway, edge-smoke-notes and edge-smoke-audit with the same isolation. It checks that the backends are not public; forged, expired, long-lived, wrong-audience and alg=none tokens; scopes; per-subject isolation with a spoofed x-gw-sub; request validation; the per-subject limit (10 per minute); the per-address limit cutting forged tokens before any token check; the runtime refusing the gateway once it is removed from allowed_callers; the audit trail, filtered by subject and by address; and the operator SDK, which it publishes itself as acme_<run> with the operator token: GET /v1/platform answered by 1.0.0, then by 1.1.0 (with the integrations, its new behavior) right after 1.1.0 is published to stable, by 1.0.0 after a rollback, and 502 sdk_unavailable after removal, while the gateway keeps the same version throughout.

RT_API=http://127.0.0.1:8081 RT_INVOKE=http://127.0.0.1:8080 RT_KEY=rtk_… RT_ROOT_TOKEN=… ./smoke.sh
EXPECT_SHIPPED=1 ./smoke.sh        # with the acme binding and its mock API: events reached the operator API

Notes and limits

  • Fail closed. Missing or invalid GATEWAY_KEYS answers 503 for everything; nothing is forwarded unverified.
  • Fail open on the store. A KV error in either rate limiter lets the request through and logs a warning.
  • Shared addresses. Clients behind one NAT or proxy share a per-address budget; size GATEWAY_IP_RATE_LIMIT for that. Requests without x-rt-client-ip (not over the public listener) skip that limit.
  • Body size. GATEWAY_MAX_BODY is checked against Content-Length and again while reading.

Ideas to extend it

  • Add a route to another backend: a new Target, a scope in required_scope, and the backend's slug in the config.
  • Verify asymmetric tokens (RS256 or EdDSA) from your identity provider instead of shared HMAC keys.
  • Cache idempotent GET answers in std:host/kv with a short TTL, keyed by subject and path.
  • Write a second backend as a WASM component too, for a fully WASM request path.

Where the code lives

sample/apps/edge-gateway/ in the runtime repository: gateway/ (the Rust crate: src/, wit/rt-host.wit, Cargo.toml, build.sh), notes/main.ts, audit/ (src/, test/), mint-token.sh, smoke.sh and a README.

See also