Writing Deno services¶
This guide is the handler contract and platform API of the Deno executor: project layout, the handler shapes, the
request and response contract, the sandbox and its limits, warm reuse, and how to test and debug. The built-in storage
and messaging modules (std:kv, std:sql, ...) have their own guide, KV, SQL, blobs and other
sub-services; npm packages, frameworks and import rules are in the Deno runtime
language page. For exact signatures, see the guest API reference.
Deno A Deno service is a module whose default export handles requests. The node compiles it on first use, then runs every task in a V8 isolate that has the Web platform APIs, the runtime modules and nothing else: no file system, no sockets, no subprocesses.
How your code runs¶
- You upload source (
21ci pushorPOST /v1/services/{id}/versions). The node validates it right away: it parses every file and checks every import. Nothing is fetched yet. - The first task that needs the version builds it: TypeScript is transpiled (no type-check),
npm:/jsr:/https:dependencies are fetched and pinned inrt.lock, and everything is bundled with a V8 code cache. - Each task gets a fresh isolate from a pre-built snapshot, loads your bundle and calls your handler. Your module's top-level code runs once per task, so module variables never carry state from one request to the next (unless warm reuse is on, and even then only as a cache).
The mechanism is described in Execution; this page is about writing the code.
Project layout¶
The smallest service is one file. Larger services are a directory with an entry module and an optional rt.json.
| What you push | Sent as | Limits |
|---|---|---|
main.ts, main.js, x.mjs |
the file (application/typescript / text/javascript) |
≤ 1 MB |
a directory with rt.json |
JSON bundle {"entry", "files", "imports"} |
≤ 10 MB, ≤ 1,000 files, ≤ 1 MB per file |
a directory without rt.json |
one file as is; several as a bundle with the entry guessed from main.ts, main.js, index.ts, index.js, mod.ts |
same |
x.zip, x.tar |
the archive (optional rt.json inside) |
same |
rt.json names the entry module and an import map. Both fields are optional:
21ci push bundles the .ts .tsx .mts .js .jsx .mjs .json files below the directory and leaves out dot files,
node_modules and rt.json itself. See 21ci push for every option.
Start from a template¶
21ci init scaffolds a project from the runtime's samples:
| Template | Contents |
|---|---|
deno (default) |
main.ts from sample/deno/hello: a Form A handler that echoes the request and ctx |
deno-kv |
main.ts from sample/deno/kv-counter: std:kv get, an atomic counter with a TTL, delete, list |
wasm-rust, wasm-js |
WASM components, see Writing WASM services |
$ 21ci init my-fn --template deno-kv
Created my-fn (template deno-kv)
README.md
main.ts
Next: cd my-fn && 21ci push . --service my-fn --create
A layout that scales¶
The complete apps in sample/apps/ (in the runtime repository) all use the same structure, and it is worth copying:
my-service/
├── src/ what you push: 21ci push src --service my-service
│ ├── main.ts the handler: routing, std:* calls, nothing else
│ ├── validate.ts pure functions: parsing, validation, business rules
│ ├── http.ts small helpers (json(), error(), readJson())
│ └── rt.json only if you need an import map or another entry
├── test/
│ └── validate.test.ts
└── smoke.sh deploys src/ to a node and checks the main flows
Only main.ts imports std:* modules. Everything else is plain TypeScript that runs anywhere, which is what makes it
testable without a node. Push src/, not the project root: the node validates every file of an
upload, including files nothing imports, so a test file with a node:test import in the upload fails the deploy
with 422.
Handlers¶
The entry module's export default is either a function (Form A) or an object (Form B).
Form A: a function¶
The simplest shape. It receives a standard Web Request and a ctx object and returns a Response:
// Form A (val.town compatible): `export default function (req, ctx)`.
//
// By default the Deno executor runs every request in a fresh isolate: module top-level code
// runs once per TASK (not once per process), there is no warm state between requests.
// With `deno.reuse_isolates` (on in the `min_latency` profile) a cleanly finished isolate may
// serve later requests of the same service version, so module state is a cache at best.
interface Ctx {
taskId: string;
service: { id: string; slug: string; version: number };
trigger: "http" | "interval" | "cron" | "queue" | "call";
invoker?: string; // from x-rt-invoker, internal listener only
deadline: number; // epoch ms
waitUntil(p: Promise<unknown>): void;
}
// Looks like a process-wide counter, but it is re-created for every task: always 1 (DNO-01),
// unless isolate reuse is on (then it counts the requests this isolate served, DNO-17).
let hitsInThisTask = 0;
export default async function (req: Request, ctx: Ctx): Promise<Response> {
hitsInThisTask++;
// The runtime strips `/s/{slug}`: for GET /s/hello/x?name=Ada the handler sees /x?name=Ada.
const url = new URL(req.url);
const name = url.searchParams.get("name") ?? "World";
return Response.json({
message: `Hello, ${name}!`,
method: req.method,
path: url.pathname,
basePath: req.headers.get("x-rt-base-path"), // "/s/hello"
service: ctx.service, // { id, slug, version }
trigger: ctx.trigger, // "http"
taskId: ctx.taskId,
hitsInThisTask, // 1 without isolate reuse: no warm state between requests
});
}
A Form A handler also receives schedule fires and queue batches, as synthetic POST requests (see the table below).
Form B: an object¶
Export an object with any of fetch, scheduled and queue (at least one):
export default {
async fetch(req: Request, ctx: Ctx): Promise<Response> {
return Response.json({ trigger: ctx.trigger });
},
async scheduled(event: ScheduledEvent, ctx: Ctx): Promise<void> {
console.log("fired", event.scheduleId, event.payload);
},
async queue(batch: QueueBatch, ctx: Ctx): Promise<void> {
for (const msg of batch.messages) console.log(msg.id, msg.attempt, msg.body);
},
};
Which function the runtime calls depends on the trigger:
| Trigger | Called | Without that function |
|---|---|---|
http, call |
fetch(req, ctx) (Form A: the function) |
500 guest_error, logged as module has no default handler |
interval, cron |
scheduled(event, ctx) |
fetch receives POST http://localhost/__rt/scheduled with JSON {scheduleId, scheduledTime, payload}; the status is only logged |
queue |
queue(batch, ctx) |
fetch receives POST http://localhost/__rt/queue with JSON {messages: [{id, body, attempt}]}; 2xx acks the whole batch, anything else retries it |
The synthetic requests carry content-type: application/json and x-rt-trigger (interval, cron or queue).
Check the trigger, not the path
Anyone who can reach your service can also send POST /__rt/queue over HTTP. In a Form A handler, decide by
ctx.trigger (or the x-rt-trigger header, which clients cannot set), not by the path alone. Form B avoids
the question: scheduled and queue are only ever called by the runtime.
A real queue handler from sample/deno/scheduled-queue acks or retries each message on its own:
// Delivery is at-least-once: make the work idempotent. A message that is neither acked nor
// retried counts as acked when the handler returns normally, so errors are handled per message.
async queue(batch: QueueBatch, ctx: Ctx): Promise<void> {
console.log(`[queue] ${batch.messages.length} message(s) task=${ctx.taskId}`);
for (const msg of batch.messages) {
const job = msg.body as Job;
try {
if (typeof job?.failUntilAttempt === "number" && msg.attempt < job.failUntilAttempt) {
await record("queue-retry", { id: msg.id, text: job.text }, msg.attempt);
// Without arguments the runtime applies exponential backoff (2 s × 2^attempt, ±20 %) and
// moves the message to the DLQ after queue.max_attempts (5).
msg.retry({ delaySeconds: 1 });
continue;
}
await record("queue-done", { id: msg.id, text: job?.text ?? msg.body }, msg.attempt);
msg.ack();
} catch (e) {
console.error(e);
msg.retry();
}
}
},
Queue rules in short: a message you neither ack() nor retry() is acked when the handler returns normally; a
throw fails the task and the whole batch comes back. Without a delay, retries back off 2 s × 2^(attempt-1)
(±20 %), and after queue.max_attempts (5 by default) the message moves to the dead-letter queue. Delivery is
at-least-once and unordered, so make the work idempotent. Calling ack() first turns a later retry() of the same
message into a no-op. Schedules and queues have their own guides: Schedules and
Calls and queues.
The ctx object and types¶
The runtime ships no types package. Declare the shapes you use in your own code:
export interface Ctx {
taskId: string; // same as the x-rt-task-id response header
service: { id: string; slug: string; version: number };
trigger: "http" | "interval" | "cron" | "queue" | "call";
invoker?: string; // x-rt-invoker, internal listener only
client?: { ip: string }; // http trigger only: the client address
deadline: number; // epoch ms when the wall limit runs out
waitUntil(p: Promise<unknown>): void;
}
export interface ScheduledEvent { scheduleId: string; scheduledTime: number; payload: unknown }
export interface QueueMessage {
id: string;
body: unknown; // parsed JSON, or a string if it is not JSON
attempt: number; // 1 on the first delivery
ack(): void;
retry(o?: { delaySeconds?: number }): void;
}
export interface QueueBatch { messages: QueueMessage[] }
The guest API reference also has ambient declarations for the std:*
modules, so a TypeScript-aware editor can check your calls. The build itself never type-checks.
ctx.waitUntil(promise) keeps the task alive after the response has been sent, for work the client does not need to
wait for. It is bounded by the wall limit, and a rejected promise is logged as an error:
if (url.pathname === "/background") {
const target = url.searchParams.get("target") ?? "hello";
// The child task keeps running after this response is sent; waitUntil keeps the isolate
// alive for it (bounded by the wall-time limit).
ctx.waitUntil(
call(target, new Request("http://svc/background-task", { method: "POST", body: JSON.stringify({ from: ctx.service.slug }) }))
.then(async (r) => console.log(`[background] ${target} -> ${r.status}`, await r.text()))
.catch((e) => console.error("[background] failed", e)),
);
return Response.json({ message: "call scheduled", target, taskId: ctx.taskId }, { status: 202 });
}
Requests and responses¶
What the handler sees¶
- URL.
req.urlishttp://localhost/<rest>?<query>. ForGET /s/hello/x?name=Adathe handler seeshttp://localhost/x?name=Ada. The stripped prefix is in thex-rt-base-pathheader (/s/hello); on a custom domain there is no prefix and no header. Build absolute links fromx-rt-base-pathif you serve HTML. - Headers added by the runtime:
x-rt-trigger(http,call, …),x-rt-task-id,x-rt-base-path,x-rt-client-ip,traceparent(the caller's, or a new one), andx-rt-invokeron the internal listener only. - Headers removed: every
x-rt-*header the client sent (a client cannot spoof them,x-rt-keyincluded), theHostheader and hop-by-hop headers. Authorizationreaches you unchanged, so you can check your own tokens (an admin bearer,Basic …), with one exception: anAuthorization: Bearer rtk_…(a tenant API key, a runtime credential) is always removed, and so is the root token that passed the access check of anaccess: keyservice. Clients of anaccess: keyservice that also need to send your own token put the invoke key inx-rt-keyinstead.- Client address.
ctx.client.ipand thex-rt-client-ipheader hold the address the node resolved: the TCP peer, or, behind a proxy listed iningress.trusted_proxies, the firstX-Forwarded-Forhop, counted from the right, that is not a trusted proxy. A client-sentx-rt-client-ipis removed first. Both are set for thehttptrigger only: schedules, queues and calls have no client address, and neither do requests on the internal Unix socket. - Body.
req.bodyis aReadableStreamthat you can read while the client is still sending. Reading pastlimits.max_body_bytes(10 MB by default) fails with an error whose message isrequest_too_large. A request whoseContent-Lengthis already too large never reaches you: the client gets413 too_large.
What the handler returns¶
Return a Response. Anything else (undefined, a plain object, a string) is a TypeError and the client gets
500 guest_error.
- A streamed body is sent as you produce it: the client gets the first chunk right away. Chunks must be
Uint8Array. - A response body may be up to 100 MB (
max_response_stream_bytes). Past that the body is cut off with an error. - Several
Set-Cookieheaders are kept as separate headers. - The runtime adds
x-rt-task-id,x-rt-versionandserver-timingto your response.
A streamed response:
export default function (): Response {
const enc = new TextEncoder();
const body = new ReadableStream<Uint8Array>({
async start(controller) {
for (let i = 1; i <= 3; i++) {
controller.enqueue(enc.encode(`chunk ${i}\n`));
await new Promise((r) => setTimeout(r, 100));
}
controller.close();
},
});
return new Response(body, { headers: { "content-type": "text/plain" } });
}
Runtime modules¶
Seven built-in modules give your code storage and platform access. Import them by name; they are part of the runtime and
never bundled, and every function returns a promise, except std:sqlite, which is synchronous. Failures throw an Error whose message and code are a stable
code such as kv_value_too_large, never a path or a driver message. Your data is per service: two services never see
each other's KV keys, tables or blobs.
import { kv } from "std:kv";
import { sql } from "std:sql";
import { Database } from "std:sqlite"; // also "bun:sqlite"
import { blob } from "std:blob";
import { enqueue } from "std:queue";
import { call } from "std:services";
import { acme } from "std:sdk"; // an operator SDK
| Module | What it gives you | Guide |
|---|---|---|
std:kv |
Small values by key, TTL, list by prefix, and kv.incr, an atomic counter |
KV |
std:sql |
A private SQLite database: execute, batch, interactive transaction; rows come back as arrays |
SQL |
std:sqlite (bun:sqlite) |
The same database with bun:sqlite's synchronous API: a few µs per short statement, 100 ms per statement at most | Synchronous SQL |
std:blob |
Objects up to 100 MB, streamed in both directions (blob.put(key, req.body)) |
Blobs |
std:queue |
enqueue(slug, body, { delaySeconds, dedupId }) to a service the handler may call (same tenant by default), consumed by a queue handler |
Queues |
std:services |
services.fetch(slug, request) runs another service of the same tenant in-process (call is the same); services.call and services.bind make typed RPC calls to its rpc methods |
Service calls, Typed RPC |
std:sdk |
The operator's SDKs: import { acme } from "std:sdk", await acme.method(arg); the SDK runs in the runtime |
Use operator SDKs |
std:platform |
platform.fetch(binding, request): operator bindings, for operator SDK services only |
Operator SDKs and bindings |
std:log |
log.info(message, fields?) and log.with(fields): records with structured fields, shown by 21ci logs |
Structured logs |
std:secrets |
secrets.get(NAME) and secrets.require(...NAMES): secret values only, never a plain env var |
Secrets |
std:lock |
lock(key, fn, { waitMs, leaseMs }) and lock.try(key, fn, opts): a named mutex per service |
Locks |
std:schedule |
schedule.after, schedule.at, schedule.cancel, schedule.list: one-off tasks of the service |
Schedules |
import acme from "sdk:acme" is the same operator SDK as a default export; an SDK that is not published on the node
is rejected at deploy with 422. Neither form puts SDK code in your service. See Use operator SDKs.
A taste of the style, a counter in KV and a row in SQL:
import { kv } from "std:kv";
import { sql } from "std:sql";
export default async function (): Promise<Response> {
const hits = await kv.incr("hits"); // atomic, no lost updates
const r = await sql.execute("SELECT datetime('now')"); // rows are arrays: r.rows[0][0]
return Response.json({ hits, now: r.rows[0][0] });
}
Limits, consistency, error codes, schema migrations, transactions and a Rust (WASM) version of every example are in KV, SQL, blobs and other sub-services. How the data is stored is in Storage.
Environment variables and secrets¶
Env variables and secrets both appear in Deno.env, a read-only subset of Deno's API:
| Call | Result |
|---|---|
Deno.env.get(name) |
the value, or undefined |
Deno.env.has(name) |
boolean |
Deno.env.toObject() |
every variable and secret as an object |
Deno.env.set(), Deno.env.delete() |
throw a TypeError |
if (url.pathname === "/") {
const vars: Record<string, string> = {};
for (const name of PUBLIC_VARS) {
const v = Deno.env.get(name);
if (v !== undefined) vars[name] = v;
}
return Response.json({ environment: Deno.env.get("ENVIRONMENT") ?? "unset", vars });
}
if (url.pathname === "/secrets") {
// Report presence only. A secret is as readable as env inside the guest, so never log or return it.
const configured: Record<string, boolean> = {};
for (const name of SECRET_NAMES) configured[name] = Deno.env.get(name) !== undefined;
return Response.json({ configured });
}
Env values are readable through the API; secrets are write-only and encrypted at rest. Inside the guest both are
plain strings, so never log or return a secret. Names match [A-Z_][A-Z0-9_]*, the RT_ prefix is reserved, a
service has at most 100 env variables and 100 secrets, and a value is at most 32 KB. Changes apply to the next
task, without a redeploy.
To read only secrets, import std:secrets. get returns the value or null; require returns every value or
throws one error that names every missing secret:
import { secrets } from "std:secrets";
const { STRIPE_KEY, DB_URL } = secrets.require("STRIPE_KEY", "DB_URL");
// missing: error.code === "secret_missing", error.missing === ["DB_URL"],
// and the message says to run `21ci secret set <service> DB_URL`
The accessor cannot be dumped: it has no enumerable keys and JSON.stringify(secrets) is undefined.
# PUT replaces the whole env map
curl -sS -X PUT -H "Authorization: Bearer $RT_KEY" -H 'Content-Type: application/json' \
-d '{"GREETING":"hi","LOG_LEVEL":"debug"}' "$RT_API/v1/services/$SVC/env"
curl -sS -X PUT -H "Authorization: Bearer $RT_KEY" -H 'Content-Type: application/json' \
-d "{\"value\":\"$STRIPE_KEY\"}" "$RT_API/v1/services/$SVC/secrets/STRIPE_API_KEY"
If the node cannot load the env when your code reads it, the read throws env_unavailable instead of pretending the
variable is unset.
Dependencies¶
Imports resolve at build time, never at run time. The runtime serves only what is in the bundle.
| Import | Resolved |
|---|---|
./x.ts, ../lib/y.js |
files of your upload |
std:* |
built into the runtime |
sdk:<name>, std:sdk |
an operator SDK: a generated shim of its contract, never its code |
npm:pkg@range, jsr:@scope/pkg@range |
fetched at build from the node's CDN (build.npm_cdn, https://esm.sh by default), pinned in rt.lock |
https://host/... |
only if the host is in build.allowed_hosts |
a bare name such as zod |
only through the rt.json import map |
anything else (file:, node:, an unknown rt: or sdk:) |
422 validation_failed at deploy |
At run time the module loader serves only what is in the bundle. Static imports and dynamic imports with a literal
specifier (await import("./big.ts")) are bundled; a computed specifier works only for a module that is already in the
bundle, otherwise it fails with module_not_in_bundle. A package that needs the file system, sockets or child
processes does not work; use std:sql, std:blob and fetch instead. The import rules, the bundling model, framework recipes (Hono, itty-router, tRPC, Oak, drizzle-orm) and a
checklist for "does my npm package work?" are in the Deno runtime page. Keep bundles small:
Optimize your service explains what a large bundle costs.
When the build fails¶
Problems with your own files show up at deploy: 422 validation_failed with details.diagnostics listing file, line,
column and message (21ci push prints them). Problems found while building (a dependency that does not resolve, a
fetch that fails, a timeout) show up on first use:
- requests get
502withx-rt-reason: build_failed; - the version's
build_stateisfailedwith a reason:syntax,resolve,fetch,lock_mismatch,timeout,oom,too_largeorinternal; - if the failed version was live and an older version is ready, the node rolls back to it (
deploy.auto_rollback, on by default; off in thedevconfig).
21ci versions hello # build state of each version
21ci versions hello 3 # one version, with its failure reason and message
21ci build-logs hello 3 # the whole build log
21ci rebuild hello 3 # retry a failed version after fixing the cause
Use 21ci push --wait (an eager build) in CI, so a broken dependency fails the deploy instead of the first request.
See Deploy and roll back.
Web APIs¶
Available as globals: fetch, Request, Response, Headers, FormData, URL, URLSearchParams, URLPattern,
streams (ReadableStream, WritableStream, TransformStream, TextEncoderStream, TextDecoderStream,
CompressionStream, DecompressionStream, …), TextEncoder, TextDecoder, Blob, File, FileReader, atob,
btoa, timers, AbortController, AbortSignal, events (Event, EventTarget, CustomEvent, …),
structuredClone, MessageChannel, crypto (WebCrypto), console, performance and WebAssembly.
Removed: Worker, SharedWorker, SharedArrayBuffer, Atomics.wait / waitAsync / notify, ShadowRealm
and caches. WebSocket is an outbound client only; accept sockets with
std:sockets. Of Deno only Deno.env is left: Deno.readFile, Deno.connect, Deno.Command and the
rest do not exist.
WebAssembly modules work, but every wasm memory counts against your memory limit and shared memories are refused.
The full list is in the guest API reference.
Outbound fetch¶
fetch goes through the node's egress guard. Only the public internet is reachable: loopback, private and link-local
ranges and cloud metadata addresses are denied, and so are ports 25, 465 and 587 (mail). A service can narrow it
further with its egress block: a non-empty allowed_hosts turns into an allowlist, denied_hosts blocks hosts
(exact names or dot-suffixes). Redirects are followed (up to 5) and re-checked at every hop; an https to http
redirect is refused unless the operator allows it.
A refused or failed fetch rejects with a TypeError whose message is a code:
| Code | Meaning |
|---|---|
egress_denied |
the address, port, scheme or host is not allowed |
egress_limit |
too many fetches in this task (50 for HTTP, 200 for schedules and queues) |
egress_too_large |
the response is over the size cap |
egress_quota |
the tenant's daily egress quota is used up |
egress_timeout |
connect timeout, or the task's wall deadline |
egress_dns |
the name did not resolve |
egress_upstream |
connection, TLS or protocol failure |
egress_insecure_redirect |
an https URL redirected to http |
try {
const res = await fetch("https://api.example.com/rates");
if (!res.ok) return new Response(`upstream ${res.status}`, { status: 502 });
return Response.json(await res.json());
} catch (e) {
console.warn("fetch failed:", (e as Error).message); // e.g. "egress_timeout"
return new Response("upstream unavailable", { status: 503 });
}
At most 6 fetches run at once per task; further ones wait for a free slot. Request bodies are buffered before sending; response bodies stream.
The frozen clock¶
Date.now(), new Date() and performance.now() advance only at I/O and timer boundaries (an await on a fetch,
a storage call or a timer), never during synchronous code. A busy loop measures zero elapsed time:
const t0 = performance.now();
for (let i = 0; i < 1e8; i++) {} // burns CPU
console.log(performance.now() - t0); // 0
await new Promise((r) => setTimeout(r, 10));
console.log(performance.now() - t0); // >= 10
This takes away the high-resolution timer that timing side-channel attacks need. Timestamps are still correct for
everything practical (createdAt, TTLs, logs); just do not use the clock to measure CPU time. See
Security.
Warm reuse¶
By default every task starts from a clean isolate. With deno.reuse_isolates on (the default only in the
min_latency profile) an isolate that finished cleanly is kept and serves later requests of the same service version
on the same scheduler thread. Top-level code then runs once per isolate and module variables survive between requests.
Turn it on for one service with 21ci service update hello --reuse-isolates true, or
PATCH /v1/services/{id} with {"deno": {"reuse_isolates": true}}.
A kept isolate is a cache, not a home for state. It is dropped after any error, a CPU or memory kill, a leftover timer or pending promise, an env or secret change your code read, 1,000 requests, an idle period, memory pressure or a new version, and consecutive requests may land on different isolates. Write code that is correct both ways:
- Keep state in
std:kv,std:sql/std:sqliteorstd:blob, never in module variables. - Use module scope only for things that are safe to recompute: compiled regexes, parsed config, a "schema is ready" flag that falls back to a cheap check.
- Finish everything you start: await your promises (or hand them to
ctx.waitUntil) and clear your timers. An isolate with leftovers is not reused. - Read
Deno.envinside the handler, not once at the top level, if you want to be explicit about it. Either way a changed variable reaches the next task.
What reuse saves, what it costs and a longer list of reuse-safe patterns are in Optimize your service. The SQL sample shows the schema-once pattern: the flag saves a query while an isolate is reused, and without reuse the check is one cheap read:
// Schema once: a read checks for the schema and only a database without it pays for the write
// batch, so GETs never write. The flag only helps while an isolate is reused; without that, the
// check is one cheap read per request. Two first requests racing both create: IF NOT EXISTS makes
// that harmless, and the batch is one transaction, so the index (created last) proves both exist.
let schemaReady = false;
async function ensureSchema() {
if (schemaReady) return;
const found = await sql.execute(
"SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = 'todos_done'",
) as SqlResult;
if (found.rows.length === 0) await createSchema();
schemaReady = true;
}
Limits¶
Defaults depend on the trigger, not on the profile. A service can change its limits within the maximums of its plan
(PATCH /v1/services/{id} with a limits block); an explicit wall_ms or cpu_ms then applies to every trigger.
| Limit | HTTP and calls | Schedules | Queue |
|---|---|---|---|
| Wall time | 30 s (a call: at most the caller's remaining time) | 300 s | 300 s |
| CPU time | 1,000 ms | 10,000 ms | 10,000 ms |
Memory (heap, ArrayBuffers, wasm memories) |
128 MB | 128 MB | 128 MB |
| Request body | 10 MB | 1 MB per message | |
| Response body (streamed) | 100 MB | ||
| Outbound fetches (total / at once) | 50 / 6 | 200 / 6 | 200 / 6 |
| Log lines per task | 1,000 | 1,000 | 1,000 |
The plan's limits_max caps these defaults too: the free plan allows at most 30 s wall and 1,000 ms CPU, so on
free scheduled and queue tasks also get 30 s and 1 s. The full table, including plan maximums and storage quotas,
is in Limits.
Errors and logs¶
What the client sees when something goes wrong:
| Outcome | Status | x-rt-reason |
|---|---|---|
Your handler threw, rejected, or returned something that is not a Response |
500 | guest_error |
| CPU limit | 502 | cpu_limit |
| Memory limit | 502 | oom |
| Wall limit | 504 | timeout |
| The version failed to build | 502 | build_failed |
The body of these responses is generic: the message and stack of an exception go to the service logs, never to the client. If you want the client to see a reason, catch the error and return your own response.
console.debug, log/info, warn and error write log records at the matching level, tagged with the task id.
A task keeps up to 1,000 lines (later ones are dropped and counted); a message is cut at 10,000 characters.
SDK errors carry the code in .code. Some errors from the platform itself (fetch, the request body,
env_unavailable, the sql.transaction time cap) put the code only in .message, so read both:
try {
await kv.set(key, value);
} catch (e) {
const code = (e as { code?: string }).code ?? (e as Error).message;
if (code === "storage_quota") return new Response("storage full", { status: 507 });
throw e; // 500 guest_error, stack in the logs
}
Every code is listed in Error reasons.
Structured logs¶
std:log writes a record with fields. 21ci logs prints the fields after the message; --json and the API return
them as fields. Plain console.* lines keep working and have no fields.
import { log } from "std:log";
const orders = log.with({ route: "/orders" });
orders.info("order placed", { orderId: 42, total: 19.5 });
A fields object has at most 32 top-level keys and 8 KB of JSON. Anything else (an array, a BigInt inside, a larger
object) throws validation_failed and writes nothing.
Testing¶
The samples test at two levels.
Unit tests for pure modules. Keep parsing, validation and business rules in modules that do not import std:*,
and test them with deno test or Node's test runner (Node 22.18 or later runs .ts files directly):
// Run: node --test test/*.test.ts or deno test
import { test } from "node:test";
import assert from "node:assert/strict";
import { validateEventCreate } from "../src/validate.ts";
test("capacity must be a positive integer", () => {
const r = validateEventCreate({ title: "Meetup", starts_at: "2030-01-01T10:00:00Z", capacity: 0 }, 0);
assert.equal(r.ok, false);
});
node: imports are fine in tests as long as the test files stay out of the directory you push. If a function needs
storage, pass it in as a parameter (an object with get and set) so the test can hand it a Map.
Smoke tests against a node. Each app in sample/apps/ has a smoke.sh that deploys the service under its own
*-smoke slug with an eager build, then checks the main flows over HTTP with curl and jq:
SLUG="${SLUG:-events-smoke}"
ADMIN="adm_$(rand_hex 16)"
AUTH="Authorization: Bearer $ADMIN"
STARTS="$(jq -nr 'now + 2 * 86400 | strftime("%Y-%m-%dT%H:%M:%SZ")')"
RUN="$(rand_hex 4)" # unique contacts per run
THROTTLE=15 # registrations per minute per address; the run sends 10 before the throttle step
NOTIFY="$SLUG-notify"
step "deploy $SLUG and its notifier $NOTIFY"
deploy "$HERE/notify" "$NOTIFY"
deploy "$HERE/src" "$SLUG"
set_secret "$SLUG" ADMIN_TOKEN "$ADMIN"
set_env "$SLUG" "{\"THROTTLE_PER_MINUTE\": \"$THROTTLE\", \"NOTIFY_SERVICE\": \"$NOTIFY\"}"
step "admin: create"
EVENT_JSON="$(jq -nc --arg s "$STARTS" '{title: "Smoke meetup", description: "Talks\nand tea", location: "Tashkent", starts_at: $s, capacity: 2}')"
inv "$SLUG" POST /events "$EVENT_JSON"
expect_code 401 "create without the admin token"
inv "$SLUG" POST /events '{"title": "x", "starts_at": "2026-11-20T18:00:00", "capacity": 2}' "$AUTH"
expect_code 400 "starts_at without an offset is rejected"
inv "$SLUG" POST /events "$EVENT_JSON" "$AUTH"
Run them against a local node (Install) or a staging node. With 21ci the same loop
is short:
21ci push . --service my-fn-smoke --create --wait
21ci invoke my-fn-smoke '/healthz' --fail
21ci invoke my-fn-smoke /orders -d '{"sku":"a1"}' --fail
Debugging¶
- Find the task. Every response carries
x-rt-task-id.21ci logs <svc> --task task_…shows exactly that task's log lines, including the stack of an exception. - Follow live.
21ci logs <svc> -f --level infostreams new records as they arrive. - Tell platform errors from yours. A response with
x-rt-reasoncame from the runtime (guest_error,timeout,queue_timeout, …); responses your handler returns never have it. - See where the time went.
server-timingsplits a request intoqueue(waiting for a slot),wait_runtime(waiting for the build),initandexec.21ci stats <svc>shows the percentiles. - Builds.
21ci versions <svc> <n>shows a version's build state and failure;21ci build-logs <svc> <n>shows the whole build log. - Log the context.
console.log(ctx.taskId, ctx.trigger, ctx.service.version)makes schedule and queue runs easy to tell apart.
See also¶
- KV, SQL, blobs and other sub-services: the
std:*modules in depth, with Deno and WASM examples. - Deno runtime: imports, npm packages, frameworks and which packages work.
- Guest API reference: every function of the
std:*modules with parameters, results and error codes. - Calls and queues and Schedules: service-to-service calls, queue consumers and interval or cron handlers.
- Optimize your service: cold starts, reuse, bundle size, batching and limits.
- Tutorials: complete services built step by step.