@dads-framework/http — HTTP routes
On this page
Ship an endpoint with one declaration for the input schema, access policy, handler, response, and generated OpenAPI. Define the route in its domain, register it in the API, and test both allowed and denied requests. This package owns the Fastify integration.
Try it
In a Node.js 22+ project, install the packages.
npm install @dads-framework/http zod
Save this as example.mts and run node --experimental-strip-types example.mts.
import {
createHttpApp,
getRoute,
publicAccess,
registerRoutes,
routeGroup,
} from "@dads-framework/http";
import { z } from "zod";
const greeting = getRoute({
path: "/greeting",
summary: "Read a public greeting",
access: publicAccess(),
response: z.object({ message: z.string() }),
handler: () => ({ message: "Hello" }),
});
const app = await createHttpApp({
nodeEnv: "test",
trustedOrigins: [],
logger: false,
});
try {
registerRoutes(app, {
routes: routeGroup("Greetings", [greeting]),
subjects: { resolve: () => Promise.resolve(null) },
authorization: { check: () => Promise.resolve(false) },
});
const response = await app.inject({ method: "GET", url: "/greeting" });
console.log(response.statusCode, response.body);
} finally {
await app.close();
}
The injected request prints 200 {"data":{"message":"Hello"}}. It runs
through the HTTP app without opening a port.
In the generated app, route declarations live with the owning domain.
assembly/start-app.ts registers them with identity and authorization.
Notes routes · Starter HTTP wiring
Define a route — the verb IS the function
import { permissionToken } from "@dads-framework/access";
import { getRoute, requires, fromParam } from "@dads-framework/http";
import { z } from "zod";
// In a real route this comes from the owning domain's contract lib.
const organizationSchema = z.object({ id: z.uuid(), name: z.string() });
export const getOrganization = getRoute({
route: { method: "GET", template: "/organizations/:id" },
summary: "Get an organization",
access: requires(
permissionToken("organizations/organization", "view"),
fromParam("id"),
),
params: z.object({ id: z.uuid() }),
response: organizationSchema, // the DATA shape from the contract lib
handler: ({ params }) => ({ id: params.id, name: "Example Organization" }),
});
One function per verb, each carrying its own compile rules:
| Verb | Rules the compiler enforces |
|---|---|
getRoute |
A single read: no body key, no ARRAY responses (collections are listRoute); always 200 |
listRoute |
THE collection verb: query must extend paginationQuerySchema, handler returns { items, total }, the kit builds { data, meta } — pagination is compile-enforced |
postRoute |
201 by default (status: 200 for command-style posts) |
postNoContentRoute |
A guarded POST that reports and learns nothing back: no response schema, handler returns nothing, 204 |
patchRoute / putRoute |
body is REQUIRED; no query/meta/status; always 200 |
deleteRoute |
THE no-content shape — no response schema, handler returns nothing, 204; optional request body when path params alone are not enough |
Handlers may be sync or async — the return type is X | Promise<X> and the
kit awaits either, so you only write async when you await inside (and
forgetting it there is a compile error, not a runtime bug).
Groups — the only door to registration
Verbs return blueprints; registerRoutes accepts only grouped routes,
so forgetting the group is a compile error:
export function createOrganizationsRoutes(deps: Deps): HttpRoute[] {
return routeGroup("Organizations", [
listRoute({ ... }),
getRoute({ ... }),
]);
}
The tag is stamped once per group (it is not a route field). Groups compose
— a domain owning two tags returns [...groupA, ...groupB].
Capabilities — named fields, never middleware
Cross-cutting behavior is declared data resolved through a three-rung
ladder — route field > group capabilities > app default
(registerRoutes({ capabilities })) — so "what applies to this route" is
answerable by reading at most three named places. There are no middleware
arrays and never will be; true universals live in the kit pipeline itself.
routeGroup("Auth", { rateLimit: { perMinute: 30 } }, [
postRoute({ ..., capabilities: { rateLimit: { perMinute: 5 } } }), // route wins
getRoute({ ... }), // inherits the group's 30/min
]);
First shipped capability: rateLimit (per-caller fixed window, per
replica; 429 + retry-after once spent, budget consumed only AFTER access
so denied callers learn nothing). machineCredential: "<name>" (route or
group only; the app rung throws) makes the route resolve its caller only
through registerRoutes({ machineCredentials })[name] instead of sessions;
a missing resolver or a public route throws HttpWiringError at registration.
Capabilities grow by need — each lands with an engine and tests in the kit.
The kit does the rest: parses params/query/body (bad input → 400 with
field issues), runs your handler, parses the return through response
(drift → loud 500), and wraps it in the { data } envelope. You never
touch statuses, envelopes, or serialization.
The compiler is the reviewer. These do not compile: a route without
access; a GET with a body; a PATCH without one; a params schema that
doesn't cover the path's :params; a handler return that doesn't satisfy
response; touching subject as non-null on a public route.
The access vocabulary — all of it
| Constructor | Meaning | Handler's subject |
|---|---|---|
requires(token, fromParam("id")) |
Relationship check on the resource; denied → 404 (existence never leaks), anon 401 | SubjectRef |
… fromBody("organizationId") / fromQuery("workspaceId") / fromFixed("app") |
Same check; id from body field, query param, or a compile-time constant (singleton platform) | SubjectRef |
requireSession() |
Authenticated caller; the mutation/query owns authorization (lists/creates) | SubjectRef |
publicAccess() |
Explicitly unauthenticated (health, auth) | SubjectRef | null |
Variants
- Streams (SSE, downloads, multipart):
defineRawRoute({ ..., method, openapi, handler: ({ request, reply }) => ... })— the ONE escape hatch. Sameaccessrequirement and error envelope; no handler deadline (streams own their lifetime); its hand-writtenopenapioperation lands in the artifact markedx-raw-route: true. The bar for using it: the kit can't express what you need AND growing the kit was considered first — never importfastifyin a domain.
Errors
Throw typed DomainErrors from domain code (notFound, conflict,
validation, forbidden from @dads-framework/errors); the kit maps kinds to
statuses in one place. Kit-produced failures: request validation → 400,
response drift / wiring bugs → masked 500 (logged loud), handler past its
deadline → 503 HANDLER_TIMEOUT. Unknown errors are always masked — no
internals in bodies, correlation id included.
Process discipline (defaults you can raise, never disable)
createHttpApp sets: body limit 1 MiB, request/connection/keep-alive
timeouts, trustProxy as a hop count (trustedProxyHops, default 0 — never
trust-all XFF; CloudFront + ALB is 2 so request.ip is the viewer),
request-id correlation (inbound x-request-id honored, always
echoed), credential-redacting pino, CORS for trusted origins. Every typed
route runs under a hard handler deadline — a hung handler answers 503 and
frees its socket; its orphaned promise drains into the log.
Given a requestLog lookup and an apiRelease stamp, createHttpApp also
captures one request_log row per answer from an onResponse hook — routes,
404s, the 426 gate, 429s, error-handler responses, and protocol mounts alike.
Nothing per route: it is a pipeline universal, successful reads are skipped,
and capture can never change a response. What is stored, and for how long:
observability.
Testing
import { buildTestApp, dataBodyOf } from "@dads-framework/http/testing";
import { FakeAuthorization } from "@dads-framework/access/testing";
import { routeGroup } from "@dads-framework/http";
const id = "ca498064-95f7-4334-8d66-12703cd044a9";
const authorization = new FakeAuthorization();
authorization.seed({
resource: { type: "organizations/organization", id },
subject: { type: "user", id: "u1" },
relation: "view",
});
const app = await buildTestApp({
routes: routeGroup("Organizations", [getOrganization]),
authorization,
});
const res = await app.inject({
method: "GET",
url: `/organizations/${id}`,
headers: { "x-test-subject": "u1" },
});
console.log(dataBodyOf(res, organizationSchema).id); // ca498064-95f7-4334-8d66-12703cd044a9
await app.close();
buildTestApp never opens a port (listen does not exist on it — pinned
by a type test). Default subject = x-test-subject header; default
authorization denies everything until you pass a seeded FakeAuthorization.
Parse bodies with dataBodyOf/listBodyOf/errorBodyOf (or bodyOf for
an arbitrary schema) — res.json() is any and defeats the type walls.
Folder story
lib/route/— authoring: one file per verb,route-group,access,capabilities,define-raw-route,sse-route, androute-definition(parse → handler → parse).lib/create-http-app.ts— builds the Fastify instance (logger, CORS, timeouts, request-id, trustedProxyHops).lib/request-pipeline/—register-routes(enforce → run under deadline → envelope),enforce-access,with-deadline,error-handler,envelope,rate-limit,request-id.lib/openapi/— the generated document. The kit knows how to convert a route table, never which domains exist: nothing here imports a domain contract lib (@dads-framework/contractis the kit's own vocabulary). The parity golden test that pins the generated document against the committed artifact needs real domain schemas, so it lives with the composition root that already knows them.lib/request-log/— the captured row:request-record(pure builder plus the header allowlist),request-outcome(what the pipeline learned and the response no longer shows),capture-request-record(theonResponsehook),request-log-sink(the seam@dads-framework/auditimplements).lib/http-errors.ts— typed failures this library produces while running a route.src/testing/—buildTestApp+ typed inject-response helpers.
Protocol mounts — someone else's wire spec
A surface that implements another party's protocol (Better Auth's
/api/auth/*, the remote MCP endpoint) is not a route: it is a fetch-style
handler mounted whole. Import the bridge from @dads-framework/http/protocol-mounts in the API composition root.
mountFetchHandler is the one bridge for that — every content type arrives as
raw bytes, the request crosses to a WHATWG Request whose clones never share
a stream (to-web-request.ts, the Node 22 undici clone trap), and the
handler's Response is copied back status, headers and body. Register it with
a literal prefix so the protocol-mount boundary wall can read it; an
extraSetCookies hook appends cookies to one answer, which is how an
API can clear an authorization-consistency cookie on sign-out.
await app.register(mountFetchHandler(auth), { prefix: "/api/auth" });
Liveness and readiness
Use createHealthRoutes(checks) to expose separate checks for processes and
traffic routers. /health confirms the process responds. /ready evaluates
the application's readiness probes. Register the routes during API composition
and supply probes for dependencies required to serve traffic.
Save this as example.mts and run node --experimental-strip-types example.mts.
import { createHealthRoutes } from "@dads-framework/http/health";
import { buildTestApp } from "@dads-framework/http/testing";
const app = await buildTestApp({
routes: createHealthRoutes({
pingDatabase: () => Promise.reject(new Error("Database unavailable")),
pingCriticalServices: () => Promise.resolve(),
}),
});
try {
const live = await app.inject({ method: "GET", url: "/health" });
const ready = await app.inject({ method: "GET", url: "/ready" });
console.log(live.statusCode, ready.statusCode);
} finally {
await app.close();
}
The simulated outage prints 200 503. Liveness still succeeds. Replace
the example probes with your application’s dependency checks when
registering the routes in your HTTP app.
In the generated app, assembly/start-app.ts registers probes for the
database, job queue, and file store. Starter health wiring
Compose authorization for lists
Use requires, requiresVisible, or requiresScoped from
@dads-framework/http with an access permission token. Pass the app's
accessModel as registerRoutes's accessModel option for visibility and
scoped routes. Registration refuses an omitted model or a missing list
resource definition. Record routes use requiresScoped with scope bindings. Tests can pass the same
model and a fake lookup port to buildTestApp.
Set currentTraceId and requestTrace on createHttpApp to correlate request records and annotate the active request span. The observer receives the request ID and the audit actor kind.
Feature state previews
When a host configures featureState.preview, the resolver receives the
preview ID, authenticated subject, effective subject, and feature-state
context. By default the context comes from a request header. The host verifies the effective identity and context before
returning a preview. Set featureState.contextFromRequest to derive context
from matched route parameters instead of the caller’s header. Preview responses
are private and non-cacheable. A resolver may return a scopeKey for its feature
evaluator to match against
the context being evaluated.
What it refuses to do
Readiness reports the results of probes supplied by the application.
Application code supplies identity, access policies, and business handlers. The HTTP kit enforces the declared route boundary and owns transport.
A public POST that only appends internal telemetry can declare
resourcePolicy: { kind: "resource-free", purpose: "append-only-telemetry" }.
Use status 200 and a bounded body schema. Return an acknowledgement of the
report. The telemetry entries remain internal to the application.
mountFetchHandler implements the shared FetchHandler protocol boundary.
Its transport conformance runs over a real Fastify socket and against the
contract package's independent in-memory Fetch host. The shared proof covers
GET and POST beneath a prefix. Fastify-specific hooks and limits have their own
tests.
A subject resolver can read the matched route's decoded params when its
session policy depends on a route parameter. Validate those values before
using them to select a policy.