Triggers¶
A trigger is whatever starts a task: http, interval, cron, queue, call, websocket and alarm. Every
trigger builds a task and hands it to the same admission and scheduler, so limits, logs and stats work the same
way for all of them. This page explains each trigger's semantics, how it reaches your handler, and how the
service owner and the operator switch triggers on and off.
| Trigger | Started by | Delivery | Handler entry point (Deno Form B) |
|---|---|---|---|
http |
A request on the public or internal listener | Once, response returned to the client | fetch(req, ctx) |
interval |
A schedule with every_seconds |
Never overlapping; missed ticks skipped | scheduled(event, ctx) |
cron |
A schedule with a cron expression and time zone | Never overlapping; missed ticks skipped | scheduled(event, ctx) |
queue |
Messages in the service's durable queue | At least once, in batches, with retries and a DLQ | queue(batch, ctx) |
call |
Another service calling call() or enqueueing |
Once, in process, response returned to the caller | fetch(req, ctx) |
websocket |
A message, close or error of a socket the service accepted | At least once, one at a time per object, in order | webSocketMessage / webSocketClose / webSocketError |
alarm |
A durable object's alarm coming due | At least once, with retries | alarm(info, ctx) of the durable class |
websocket and alarm are covered in WebSockets and durable objects; the WebSocket upgrade
itself is an http (or call) task.
Handlers that only speak HTTP (Deno Form A, every WASM component) still get every trigger; see how triggers reach your handler.
HTTP¶
Routes¶
A request reaches a service in one of three ways, checked in this order:
| Match | Example | Path the handler sees |
|---|---|---|
| A verified custom host mapped to the service | https://bot.example.com/webhook |
/webhook (unchanged) |
{slug}.{routing.base_domain}, when the operator set base_domain |
https://hello.fn.example.com/x |
/x (unchanged) |
The path prefix /s/{slug} |
http://127.0.0.1:8080/s/hello/x?y=1 |
/x?y=1, with x-rt-base-path: /s/hello |
With the path prefix, the runtime strips /s/{slug} so the same code works behind any of the three. If you build
absolute links, prefix them with x-rt-base-path when it is present. req.url in Deno is
http://localhost/<path>?<query>: the original Host is not passed on.
A request matches nothing, or matches a service with no live version or with triggers.http off: 404
not_found. Custom hosts are claimed per service (21ci host attach <svc> <host>, or
PUT /v1/services/{s}/hosts/{host}); a tenant's claim is
active once the node finds the DNS TXT record _rt-verify.<host> or the operator approves it. See
Custom domains.
Headers¶
| Direction | Added by the runtime | Removed by the runtime |
|---|---|---|
| Request to your handler | x-rt-task-id, x-rt-trigger: http, x-rt-base-path (path routes), x-rt-client-ip (public listener), traceparent (generated when absent), x-rt-invoker (internal listener only); WASM also gets x-rt-deadline (epoch ms) |
Every client-sent x-rt-* header (x-rt-key and x-rt-client-ip included), hop-by-hop headers, Host, and an Authorization: Bearer rtk_… (a tenant key) or the root token that passed access: key |
| Response to the client | x-rt-task-id, x-rt-version, server-timing: queue;dur=…, wait_runtime;dur=…, init;dur=…, exec;dur=… |
Nothing: your status, headers (including several Set-Cookie) and body pass through |
Because clients can never send x-rt-* headers through, your handler can trust every x-rt-* header it sees.
Any other Authorization header (your own bearer tokens, Basic …) reaches your handler unchanged, so a
service can check its own credentials.
Client address. x-rt-client-ip (and ctx.client.ip in Deno) is the address ingress resolved: the TCP
peer, or, when the peer is listed in ingress.trusted_proxies, the first X-Forwarded-For hop, counting from
the right, that is not a trusted proxy. It is the same address the ip_allow rule checks. It exists only for the http trigger on the
public listener: schedules, queue batches, calls and requests on the internal socket have none.
Access modes¶
A service's access decides who may invoke it over HTTP:
access |
Public listener | Internal listener |
|---|---|---|
public (default) |
Anyone | Yes |
key |
Authorization: Bearer rtk_… (or x-rt-key) of the same tenant with the invoke scope, or the root token; otherwise 401 unauthorized. 10 wrong keys per minute from one client, then 429 |
Yes, no key needed |
internal |
404 not_found, as if it did not exist |
Yes |
The invoke key never reaches your handler. If a client of an access: key service also needs to send the
service's own Authorization header, it passes the invoke key in x-rt-key instead.
access governs HTTP only. Calls between services have their own rules: service calls.
Ingress rules¶
On the public listener, after the access check, the service's ingress block can narrow traffic further:
{"ingress": {
"allowed_methods": ["GET", "POST"],
"allow_paths": ["/webhook", "/api/*"],
"ip_allow": ["203.0.113.0/24", "2001:db8::/32"],
"rate_limit": {"rps": 20, "burst": 40}
}}
| Rule | Refusal |
|---|---|
allowed_methods |
405 method_not_allowed |
allow_paths (exact match, or prefix with a trailing *, matched against the path the handler sees) |
403 forbidden |
ip_allow (IPv4 and IPv6 CIDRs; the client address is taken from X-Forwarded-For only behind ingress.trusted_proxies) |
403 forbidden |
rate_limit (per-service token bucket) |
429 rate_limited + Retry-After |
Empty lists and rps: 0 mean no rule. After the ingress rules come the tenant's plan quotas and admission; the
full order is on the Architecture page.
The internal listener¶
The internal listener (unix:/data/rt.sock by default) serves the same routes as the public one, for the
operator's own platform. It is trusted: no access check, no ingress rules, and it keeps an x-rt-invoker
header, which the handler reads as ctx.invoker (Deno) or as the request header (WASM). Use it to tell a
service which end user a platform call is for.
Only processes running as the node's own UID (or a UID listed in listeners.internal_allowed_uids) may connect;
others are disconnected before any response. A TCP internal listener cannot check the peer and needs the explicit
opt-in listeners.allow_tcp_internal = true (see [listeners]). The plan's
allowed_triggers and quotas still apply.
Schedules¶
A schedule fires a service on a timer, with a JSON payload (≤ 64 KB) that the handler receives as
event.payload.
| Kind | Body | Notes |
|---|---|---|
interval |
{"kind":"interval","every_seconds":300,"payload":{…}} |
At least the plan's min_schedule_seconds |
cron |
{"kind":"cron","cron":"0 9 * * MON-FRI","timezone":"Europe/Berlin","payload":{…}} |
5 fields, or 6 with a leading seconds field; IANA time zone, default UTC. Days of the week are numbered 1-7 with Sunday = 1 (so 1-5 is Sunday to Thursday): prefer names such as MON-FRI. The gap between two fires must also respect min_schedule_seconds |
How schedules behave:
- No overlap. While a run of a schedule is still going, its next tick is skipped (and counted in
rt_schedule_skipped_total). A slow job never piles up behind itself. - No backfill. Ticks missed while the node was down, or skipped, are not run later. Schedules are not at-least-once; if every run matters, have the schedule enqueue a message and do the work in the queue handler.
- Jitter. Each schedule fires up to
min(1 s, interval / 10)late, a fixed offset per schedule, so many schedules with the same period do not fire in the same millisecond. - Quotas. At most
max_schedulesper service (403 quota_exceeded); a period belowmin_schedule_secondsis422 schedule_too_frequent. Thefreeplan allows 3 per service, 60 s apart, and nocron.
Scheduled tasks get longer default limits than HTTP (300 s wall, 10 s CPU), capped by the plan maxima; see limits. More patterns: Schedules guide.
Queue¶
Every service has a durable queue (stored in queue.db, so it survives restarts). Delivery is
at least once and unordered: write handlers that tolerate a message twice.
Enqueue from the control API (scope queue:write), from guest code with enqueue() from std:queue (Deno)
or std:host/queue (WASM), or with the CLI:
| Aspect | Behavior |
|---|---|
| Message | JSON (or bytes from guest code), at most 1 MB |
| Delay | Optional, up to 7 days |
| Dedup | A second message with the same dedup_id within 24 hours is dropped |
| Batches | Up to queue.batch_size (10) messages per task |
| Visibility | A leased batch is invisible to other consumers for the task's wall limit + 10 s; if the task never finishes (crash, restart), the messages come back after that |
| Ack | Form B: messages you do not retry() are acked when the handler returns; a throw retries the batch. Form A and WASM: a 2xx response acks the batch, except the messages named in an x-rt-queue-retry response header (comma-separated ids, each optionally with ;delay=<seconds>); anything other than 2xx retries the whole batch |
| Retry | Backoff 2 s × 2^(attempt-1) (2 s, 4 s, 8 s, …) ±20 % jitter, up to queue.max_attempts (5) |
| Dead letters | After the last attempt the message moves to the service's DLQ: list, redrive (attempt reset to 1) or purge |
| Concurrency | At most queue.max_concurrency (4) queue tasks per service at once, within the service's own limit |
| Depth | At most the plan's max_queue_depth waiting messages per service, then 429 queue_full |
A queue is consumed only while its service has a live version and its queue trigger is allowed; otherwise
messages wait without using attempts. Patterns and the full API: Service calls and queues.
Service calls¶
A service can call another service of the same tenant by slug. The call runs in process: no HTTP hop, no
TCP connection, no TLS. The child is a separate task (trigger: call) of the target service with its own CPU
and memory limits, placed next to its parent when the runtimes match.
// Bindings generated with wit_bindgen::generate! from wit/rt-host.wit
use rt::host::call as rtcall;
let req = rtcall::Request {
method: "POST".into(),
path_with_query: "/charge".into(),
headers: vec![("content-type".into(), b"application/json".to_vec())],
body: br#"{"sku":"a"}"#.to_vec(),
};
match rtcall::call("billing", &req) {
Ok(res) => { /* res.status, res.headers, res.body */ }
Err(e) => { /* e.code: not_found, call_not_allowed, … */ }
}
Only the request's method, path, query, headers and body are used (the host part of the URL is ignored). The
callee sees x-rt-trigger: call and x-rt-base-path: /s/{its slug}; x-rt-* headers set by the caller are
dropped.
| Rule | Value |
|---|---|
| Depth | At most 15 nested calls; deeper is a 508 response with x-rt-reason: call_depth |
| Deadline | The child's wall limit is min(its own limit, the parent's remaining time) |
| Accounting | CPU and memory count to the child service; both count toward the tenant's concurrency |
| Failure | A child that fails or is killed comes back as a 5xx Response (x-rt-reason set); refusals are errors with a code |
Who may call whom¶
Every service has an environment label (default production) and a call.allowed_callers list. The same
list also governs enqueue() into another service's queue.
| Caller | Admitted when |
|---|---|
| The target itself | Always |
Same tenant, empty allowed_callers |
Both services are in the same project and environment |
| Same tenant, non-empty list | The list names the caller's slug, its svc_… id, or env:<caller's environment> |
| Another tenant | The caller's plan has allow_cross_tenant_calls and the list names the caller's svc_… id (slugs and env: entries never admit another tenant) |
A non-empty list names every admitted caller: add env:production to keep same-environment callers of a
production service. A slug entry admits whichever service holds that slug at call time; use ids where that
matters.
flowchart TD
S["call(slug) or enqueue(slug)"] --> F("Slug routable?")
F -->|yes| T("Same tenant, or the caller's plan allows cross-tenant calls?")
T -->|yes| SW("Target's triggers.call (or .queue) on, and its plan allows it?")
SW -->|yes| AC("Caller admitted by the target's call.allowed_callers?")
AC -->|yes| OK["Child task runs (enqueue: message stored)"]
F -.->|no| E1["not_found"]
T -.->|no| E2["cross_tenant_call"]
SW -.->|"switch off / plan forbids"| E3["forbidden / trigger_not_allowed"]
AC -.->|no| E5["call_not_allowed"]
The depth check (call_depth) runs before all of these for calls; an enqueue checks max_queue_depth
(queue_full) after them. Every check uses in-memory tables, so a refused call costs no task and no database
round trip.
How triggers reach your handler¶
| Trigger | Deno Form B (export default { fetch, scheduled, queue }) |
Deno Form A (export default function) and WASM components |
|---|---|---|
http, call |
fetch(req, ctx) |
The function / wasi:http/incoming-handler |
interval, cron |
scheduled(event, ctx) with {scheduleId, scheduledTime, payload} |
POST /__rt/scheduled, JSON {scheduleId, scheduledTime, payload}, header x-rt-trigger: interval or cron; the status is only logged |
queue |
queue(batch, ctx), each message with id, body, attempt, ack(), retry({delaySeconds?}) |
POST /__rt/queue, JSON {messages: [{id, body, attempt}]}; 2xx acks all but the ids listed in x-rt-queue-retry, anything else retries all |
A Form B module without the matching export falls back to fetch with the same synthetic request; one without
fetch answers HTTP and calls with 500 guest_error. ctx.trigger (Deno) or the x-rt-trigger header tells
you which trigger is running. Check the synthetic paths before your own routing so they cannot be mistaken for
user traffic:
export default async function (req: Request, ctx: { trigger: string }): Promise<Response> {
const { pathname } = new URL(req.url);
if ((ctx.trigger === "interval" || ctx.trigger === "cron") && pathname === "/__rt/scheduled") {
const { payload } = await req.json();
// … run the job …
return new Response("ok");
}
return new Response("hello");
}
The full handler contract is in the Deno guide and the WASM guide.
Turning triggers on and off¶
Two switches must both allow a trigger: the service owner's triggers block and the operator's plan.
| Trigger | triggers.<name>: false on the service |
Missing from the plan's allowed_triggers |
|---|---|---|
http |
404 not_found on every listener |
403 trigger_not_allowed on every listener |
interval, cron |
New schedules of that kind: 403 trigger_not_allowed; existing ones do not fire |
New schedules: 403 trigger_not_allowed; fires of existing ones are dropped |
queue |
Enqueue: 403 trigger_not_allowed (API) or forbidden (guest); queued messages wait |
Enqueue: 403 trigger_not_allowed / trigger_not_allowed; queued messages wait |
call |
call() fails with forbidden |
call() fails with trigger_not_allowed |
websocket |
Upgrades: 403 trigger_not_allowed |
Upgrades: 403 trigger_not_allowed |
PATCH replaces the whole triggers block, and a field you leave out is true. The plan side is described in
Tenants, plans and keys.
See also¶
- Service calls and queues and Schedules: patterns and recipes.
- Execution and isolation: the limits each trigger runs with.
- Error reasons and guest codes.
21ci schedule,21ci queue,21ci invoke.