0165. Every server request runs one pipeline, compiled per operation, with templates an app can replace
- Status: Accepted (Mik, 18 Nov 2026)
- Date: 2026-11-18
- Decided by: Mik asked for it on 18 Nov 2026 ("base middleware … Auth, Caching, Validation, Responses, Logging, Rate Limiting, Error Handling, and anything along these lines … allow custom handlebars or template files to allow users to modify the base interactions", and "Security and performance at the top most of our minds at all times"). The design is the integrator's, approved by Mik on 18 Nov 2026 with the answers recorded at the end.
- Planning item: none (after version 1, with decisions 0163 and 0164)
Context
The server companion (decision 0163) and domains (decision 0164) generate a server. A real server also needs what every team otherwise writes by hand: who the caller is, what they may do, limits, validation, caching, one error shape, logs and traces.
IDX-Studios/work-stable-api has all of these, as packages added over time (auth, cache, caching, rate-limiting, logging, pub-sub, elysia-server). Reading them shows what a base must get right, and what assembling by hand lets through:
- Two of each. There are two cache packages, and three rate limiters (an Express one, an Elysia one, and stores for memory and Redis).
- The order is by convention. Each plugin's comments say what it must be mounted after. Nothing checks it.
- The caller's address is trusted from a header. The limiter's key is the first
X-Forwarded-Forentry. That is right behind Cloud Run and spoofable anywhere else. - A request header raises the log level (
x-log-level), for any caller. - Errors have two shapes and two statuses for the same mistake (400 and 422 for a validation error).
- Good ideas worth keeping: token invalidations checked on every request, a claim store that makes event handlers run once, a tiered cache with tags, log obfuscation, and correlation ids carried into every log line.
Frameworks that solve this with a chain of middleware functions pay for the chain on every request, and leave the order and the omissions to the author. Most entries in the OWASP API Security Top 10 (2023) are omissions: no object-level check, no limit, too many fields in an answer.
Mik's rule for this work is security and performance first. So the base is not a library of middleware to remember to add. It is one pipeline, in one order, that the build writes out for each operation.
Decision
1. One pipeline, one order, written out per operation
Every request to a domain operation, a server loader or an action passes the same steps in the same order. The order is fixed by the framework, because each step's safety depends on the ones before it.
| # | Step | What it does | Why here |
|---|---|---|---|
| 1 | Limits | Refuses a body, header set or address over its limit; starts the request's deadline | Before any work is spent on the request |
| 2 | Trace | Reads or makes the trace context (traceparent) and the request id | Every later log line and error carries it |
| 3 | Origin | CORS, the Origin and Sec-Fetch-Site check for cookies, security headers | Refuses another site's request before it is counted or read |
| 4 | First limit | Rate limit by network address, from the trusted proxy setting | Stops floods before the cost of checking a token |
| 5 | Caller | Works out who is calling: a bearer token, a session cookie, a service key, or nobody | Everything after needs the caller |
| 6 | Caller's limit | Rate limit by caller and operation (limit: in the domain file) | Fair per account, not per office network |
| 7 | Input | Parses and validates path, query and body with the generated validator | Nothing unvalidated reaches a rule or a method |
| 8 | Allow | Runs the operation's allow: rules with the caller and the validated input | Object-level checks need the input (self(userId)) |
| 9 | Once | For a command with an Idempotency-Key: returns the stored answer, or claims the key | After the caller is allowed, so nobody can claim another's key |
| 10 | Read cache | For a query whose store rules keep its answer: answers from the cache, by its derived key | After allow, so a cached answer is never served to someone not allowed |
| 11 | Method | The app's own code | The only step the author writes |
| 12 | Answer | Writes only the fields the shape names, through a generated writer; sets status and headers | A field not in the shape cannot leave, whatever the method returned |
| 13 | After | Stores the answer, refreshes what the command changes:, publishes the command's events, writes the audit entry | Only after the method succeeded |
| 14 | Errors | Turns any failure into the one error shape; never a stack or a database message | One place, so no path leaks |
| 15 | Record | One structured log line, the metrics and the span, with secrets removed | Last, so it records what happened |
Compiled, not chained. The build writes each operation's pipeline as one straight function (TypeScript for the JavaScript targets, Rust for Axum) holding only the steps that operation uses. A public query with no cache has no caller step, no idempotency and no cache code in it at all. There is no list of middleware walked per request, no per-request closures, and nothing looked up by name at run time.
Refused when built, not when called. The pipeline's shape is known to the build, so these are build errors: an operation with no allow:; an answer that depends on the caller, kept without the caller in its key (the build adds the caller itself when an allow: rule reads it, and refuses when it cannot tell); a limit: by caller on a public operation; a command that publishes events with no outbox configured; a rule that reads input the operation does not have.
2. The steps
Caller (authentication).
- Bearer tokens (JWT from any OpenID Connect issuer: Firebase, Auth0, Clerk, Cognito, our own):
- Only the algorithms the project lists are accepted, and never
none. - Issuer, audience, expiry and not-before are always checked.
- Signing keys are fetched from the issuer's JWKS, cached and refreshed in the background. A token signed with an unknown key causes at most one refresh per minute, so a flood of bad tokens cannot make the server hammer the issuer.
- Only the algorithms the project lists are accepted, and never
- Sessions: an opaque random id in a
__Host-cookie (HttpOnly,Secure,SameSite=Lax), with the session in the store. It is rotated on sign-in and has idle and absolute lifetimes. - Service keys for server-to-server calls: stored hashed and compared in constant time.
- Revocation, as work-stable-api's invalidations do: a signed-out or disabled account's tokens are refused within seconds, from a small in-memory list fed by the store.
- A verified token's result is kept in memory for a few seconds under a hash of the token, so a burst from one client verifies its signature once.
Allow (authorisation). Rules are named in the domain file and written once, typed (self(userId), role(admin), owner(of: application)). They are deny by default. A rule that needs a record (ownership) declares the loader for it, so the pipeline loads it once and hands the same record to the method. The audit entry names the rule that allowed or refused.
Limits.
- Size and time: body size (1 MB by default, per operation), header size and count, address length, JSON depth, list lengths (from the shapes), and a deadline per request that cancels the method's work (
AbortSignal, or a dropped future in Rust). - Rate limits: a sliding window counter per key, in memory by default and in the shared store when there is more than one instance. Answers carry
Retry-Afterand the IETFRateLimitfields. - The caller's address: comes from
server: proxies:(how many proxies are in front, or which platform). Without that setting, forwarded headers are ignored, so they cannot be spoofed. - Outbound calls from server code go through a client with a timeout, a retry budget and a refusal of private addresses, which stops server-side request forgery.
Input (validation). Validators are generated from the shapes. Unknown fields are refused by default. Text is length-limited by its shape, numbers are range-checked, and id, email, url and time are checked by generated code with no regular expression that can backtrack. One mistake has one status: a body that cannot be parsed is 400, and one that fails validation is 422, with each field's path and reason.
Answer and Errors (responses).
- Success writes the shape through a generated writer. That writer is the security filter, and it is also faster than
JSON.stringifyon an unknown object. - Errors are
application/problem+json(RFC 9457):type,title,status,code(the stable name fromfails:),traceId, anderrorsfor fields. - In production, an unexpected error says only that something failed and gives its trace id. The cause goes to the log.
- Lists use
page of, with a cursor. - Queries get an
ETagand answer304. - Compression is done by the target (Brotli or gzip, by size and type), and is off for answers that mix a secret with caller-chosen text.
Caching.
- One tiered cache, as work-stable-api's: memory first, then the shared store.
- It is keyed by keys derived from the models (decision 0164). A command's
changes:refreshes the API answer, the kept page and the browser's copy together. - The caller is part of the key whenever the answer depends on the caller.
- Concurrent misses for one key run the method once.
- An entry can be served stale while it refreshes, and while the method is failing (
stale:, section 3).
Record (logging, metrics, traces).
- One JSON line per request, written off the request's path, with the trace id, caller id, operation, status, duration and sizes. Bodies are not logged.
- Fields a shape marks
secretorpersonalare removed or masked wherever they appear, and theAuthorizationandCookieheaders always are. - Traces follow W3C Trace Context and export to OpenTelemetry. Metrics per operation: count, errors, and duration as a histogram.
- The log level changes by configuration, or by a header only when the caller passes an
allow:rule the project names. It never changes for anyone who merely asks.
Also in the base, because every server needs them:
| Piece | What it gives |
|---|---|
| Configuration and secrets | A typed serverEnvironment() checked when the server starts (a missing or malformed value stops the start, naming it); secrets from the environment, files, or a provider (Google Secret Manager, Cloudflare secrets), never logged |
| Health | /_duolith/health (alive) and /_duolith/ready (stores and services reachable), outside the pipeline's limits and logs |
| Audit | An append-only entry for each command: who, what, which rule allowed it, and the trace id |
| Events | A command's publishes: goes through an outbox written in the same transaction, and handlers run once (the claim store) |
| Webhooks in | An operation marked signed by: verifies the sender's signature over the raw body before parsing, in constant time, and refuses old timestamps |
| Shutdown | Stops accepting, finishes what is running, flushes logs and the outbox |
| Switches | Typed feature switches read from configuration, so an operation can be turned off without a deploy |
3. Stores, and one pattern of rules for them
Sessions, rate-limit counters, the cache's second tier, idempotency claims, revocations and the outbox all need shared state. They go through one store seam (a seam is allowed at provider adapters), with adapters for memory (one instance, development), Redis, Cloudflare (KV and Durable Objects), Firestore and Postgres.
What is stored, for how long, and what happens when a store fails is decided by store rules. There is one pattern, with fallbacks and overrides, and the rules are defined on the models and domains, not on key strings (Mik, 18 Nov 2026). A key is never typed: it is derived from the model's identity or the query's input (decision 0164), and a rule written on a model follows that model into every place it is stored.
The same few settings are written at four levels, each inheriting from the one above:
| Level | Where it is written | Example |
|---|---|---|
| The framework | Built in, readable with duolith stores explain | sessions refuse when their store is down |
| The app | duolith.yaml, by kind of state | cache: { use: [memory, redis], keep: 5m } |
| The domain | The domain file's stores: | everything in billing kept 30s |
| The model, query or field | On the shape, operation or field itself | UserSkill kept 1h; note is personal |
# duolith.yaml: which stores exist, and the app's defaults by kind of state
server:
stores:
redis: { url: env(REDIS_URL) }
everything: { use: redis }
cache: { use: [memory, redis], keep: 5m, ifDown: skip }
limits: { ifDown: memory }
sessions: { keep: 30d, ifDown: refuse }
# domains/skills.domain.yaml: rules on the models themselves
shapes:
UserSkill:
identity: [userId, id]
keep: 1h
stale: { while: 60s, onError: 1h }
note?: text(..500), personal
queries:
searchSkills:
keep: 1d # this query's answers, overriding the app's 5m
- Kinds of state:
cache,sessions,limits,once,revocations,outbox, andpages(the server companion's kept pages). - What a rule sets:
use: one store, or tiers of them.keep: how long an entry is kept.stale: whether an entry may be served past its time.ifDown: what to do when the store does not answer.refusefails the request,skipgoes on without it, and a store's name falls back to it.deadline: how long to wait for the store beforeifDownapplies.- Field marks:
secret(never stored, never logged),personal(stored encrypted, masked in logs),hashed.
- The nearest rule wins, setting by setting. A field beats its model, a model or query beats its domain, the domain beats the app, and the app beats the framework. A rule sets only what it names and inherits the rest, so one word on a model changes one thing.
- A rule follows its model.
UserSkill'skeep: 1happlies to the API's cached answers, the kept pages that show it and the seed the browser gets. An answer made of several models takes the shortestkeepamong them. A field markedsecretis left out of every one of those and of every log line, with nothing more to write. - The defaults are safe ones.
- State that decides who the caller is or what they may do (
sessions,revocations,once) refuses when its store is down. cacheandpagesskip.limitsfalls back to memory.
- State that decides who the caller is or what they may do (
- Rules are checked when built. These are errors:
- a rule on a model with no
identity:that needs one; - a fallback that would weaken a security kind (
sessionswithifDown: skip) withoutunsafe: trueand a reason beside it; - a kind that needs a shared store on a target with more than one instance and resolves to memory only;
- a
personalfield cached where no encryption key is configured.
- a rule on a model with no
- Resolved once. The build works the rules out for every model, query and field and writes the result into each operation's compiled pipeline, so nothing is matched at run time.
duolith build --reportlists each one's resolved rule and the level it came from.
4. Templates an app can replace
Everything the build generates for the server comes from template files that ship with the framework: Handlebars for TypeScript, and the same for Rust. They cover each pipeline step's code, the error body, the response envelope, the client, the generated OpenAPI, the Dockerfile and the server's entry. Customising goes from light to heavy:
- Settings in
duolith.yaml(server: errors:,limits:,cors:,log:), which cover most needs. - Typed hooks:
onRequest,onCaller,onError,onRecord, written as ordinary functions. The build places them into the compiled pipeline at fixed points. - Templates:
duolith templates eject <name>copies one template into the project'stemplates/folder, and the build uses it instead of ours. A project like work-stable-api keeps its{ errors: [{ error }] }body by ejecting one small template, not by forking the generator.
Templates change what the generated code looks like. They cannot quietly remove what makes it safe:
- Every build runs the security conformance suite against its own generated server. Unallowed calls must be refused. Fields outside the shape must never be written. Oversized bodies must be refused. Errors must carry no stack, and secrets must be absent from logs. A replaced template that breaks one fails the build with the rule's name.
- Templates are logic-less. They can place and shape what the generator gives them. They cannot run code at build time, read files or reach the network.
- Replaced templates are visible. The build report lists each one with the version of ours it was copied from, and
duolith upgradeshows what changed in ours since, so a security fix to a template is not silently missed.
5. Performance is measured, and the build enforces it
- The pipeline adds no chain and no allocation per step. The steps an operation does not use cost nothing, because they are not in its code.
- Validators and writers are generated. Keys, sessions and tokens are verified once and remembered briefly. Logs are written off the request path. Cache misses are shared.
pnpm benchgains a server benchmark for each target: requests per second and tail latency for a public query, an authenticated query, a cached query and a validated command. Each is compared with the bare target answering a fixed body, so the number reported is what the pipeline itself costs. CI fails when that cost grows past a budget set from the first measurement. No figure is promised before it is measured.
Stages
- The compiled pipeline with limits, trace, input, answer, errors and record, plus the conformance suite and the benchmark. This is the least a generated server may ship with.
- Caller (bearer tokens, sessions, service keys, revocation), allow rules and audit.
- Rate limits, the store seam with all five stores together (memory, Redis, Cloudflare, Firestore and Postgres; Mik, 18 Nov 2026), store rules, caching and idempotency. One conformance suite runs against every store.
- Templates and
templates eject; hooks. - The outbox and events, inbound webhooks, switches.
Each is built for Bun, Node, Cloudflare Workers and Axum together, with the same conformance suite run against all four.
Alternatives considered
| Option | Why not |
|---|---|
| A library of middleware the author mounts (Express, Elysia plugins, Tower layers by hand) | The order and the omissions are the author's, which is where the security holes come from; a chain is walked on every request |
| Depend on existing packages for each (helmet, express-rate-limit, passport, pino, a schema library) | A dependency tree in every server, each with its own configuration and release cycle, and none of them for Rust or Workers alike |
| Let templates replace anything with no check | One edited template could drop the allow step for every operation, silently |
| Lock the templates of security steps | Mik asked for the base interactions to be modifiable; a check on the output keeps them open and safe |
| Make every step optional by configuration | A switched-off step is an omission with a config line; steps are absent only when the operation provably does not need them |
| Our own error shape by default | RFC 9457 is what clients and tools already read; an existing shape is one ejected template |
Consequences
- An app's server has authentication, authorisation, limits, validation, one error shape, caching, logging and tracing from its first build, and the author wrote none of it.
- The pipeline, its order and its build errors are new language surface: spec entries, diagnostic codes, reference pages and conformance fixtures; glossary words (pipeline, caller, rule, store, outbox).
packages/domains(and the Rust crate) hold the small run-time parts the generated code calls (the stores' seam, token verification, the writer's helpers). Their size is in the build report.- Cryptography uses the platform's own (
crypto.subtle;ringoraws-lcin Rust), never ours. - The conformance suite becomes part of every server build. It must stay fast (it runs in-process against the generated handler, with no network).
- work-stable-api's seven packages are covered by this base; moving it is its own repository's change, domain by domain (decision 0164).
Mik's answers (18 Nov 2026)
- The default error body is RFC 9457 problem details.
- Every template is replaceable, the security steps' included; the build's security suite runs on the result.
- Stores follow one pattern of rules (section 3), written on the models and domains, with keys derived from them: framework, app, domain, then model, query or field.
- All five stores (memory, Redis, Cloudflare, Firestore, Postgres) are built in the same stage.