Browse documentation

@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.

Shell
npm install @dads-framework/http zod

Save this as example.mts and run node --experimental-strip-types example.mts.

TypeScript
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

TypeScript
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:

TypeScript
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.

TypeScript
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. Same access requirement and error envelope; no handler deadline (streams own their lifetime); its hand-written openapi operation lands in the artifact marked x-raw-route: true. The bar for using it: the kit can't express what you need AND growing the kit was considered first — never import fastify in 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

TypeScript
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, and route-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/contract is 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 (the onResponse hook), request-log-sink (the seam @dads-framework/audit implements).
  • 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.

TypeScript
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.

TypeScript
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.