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:
- Path, method and query shape, and the route (
400,404,405). - A rate limit per client address, before any token work (
429withRetry-After). - 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, optionaliss(401). - The scope for the route and method (
403). - A rate limit per token subject (
429). - 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), orbash,curlandjqforsample/scripts/*.sh.- Rust with the
wasm32-wasip2target (build.shadds the target withrustupwhen it is missing). Optional:wasm-tools, whichbuild.shuses to check the component's imports and export. opensslandjqformint-token.sh, which signs test tokens.- Optional, for audit shipping and
/v1/platform: the operator SDK fromsample/operator-sdk/, published and granted (21ci sdk publish acme 1.0.0 sample/operator-sdk/acme-sdk,21ci sdk grants set node acme --allow), itsacmebinding pointing at the mock API, and a tenant on a plan that binding allows. See Operator SDKs and bindings. Without it the trail stays inedge-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:
[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]
wasip2provides thewasi:httptypes and thewasi:http/incoming-handlerexport.wit-bindgengenerates Rust bindings for the runtime's own imports fromgateway/wit/rt-host.wit, a vendored copy of the runtime'swit/rt-host.wit(packagestd: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:
# 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 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:
//! 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¶
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¶
}
#[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.
};
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¶
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:
// 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¶
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:
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:
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¶
#[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:
/// 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::callruns 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 andcall.allowed_callers; a refusal comes back as an error (call_not_allowed,not_found, …), which the gateway turns into502 upstream_unavailable.- A backend
5xxbecomesupstream_errorwithout 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¶
),
_ => 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:
/// `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::invokecalls the operator SDK'saudit.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 anerrorwith a stable code (sdk_not_granted,sdk_unavailable, or the SDK's own, such asbinding_not_allowed).GET /v1/platformis answered the same way, from the SDK'sgetPlatformInfo: 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 anddedup_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:
// 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:
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:
// 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.
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_KEYSanswers503for 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_LIMITfor that. Requests withoutx-rt-client-ip(not over the public listener) skip that limit. - Body size.
GATEWAY_MAX_BODYis checked againstContent-Lengthand again while reading.
Ideas to extend it¶
- Add a route to another backend: a new
Target, a scope inrequired_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
GETanswers instd:host/kvwith 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¶
- WASM components: toolchains, the component contract,
std:host - WIT reference
- Calls and queues: environments and allowed callers
- Operator SDKs and bindings
21ci service