http/route_spec.ts

Apply named middleware specs to a Hono app.

Apply route specs to a Hono app.

For each spec: resolves auth to guards via the provided resolver, adds input validation middleware (for routes with non-null input schemas), runs the optional authorization phase to resolve the acting actor + build the request context, wraps handler with DEV-only output and error validation, wraps with error catch layer (catches ThrownJsonrpcError and generic errors), and registers the route.

Per-route middleware order: params → query → pre-validation auth guards (401) → input validation (400) → authorization phase → post-authorization auth guards (403) → handler. The 401 check runs before any body parsing so unauthenticated callers never see route-shape information from parse failures. Input validation runs before the authorization phase (validate first, authorize after) so the authorization phase reads c.var.validated_input.acting as a typed Zod field instead of pre-parsing the raw body. Role / credential-type denials still surface 403 last; trade-off is that authenticated-but-unauthorized callers can distinguish 400 (validation) from 403 (authorization), a defense-in-depth concession deemed acceptable because the route surface is public via spec/codegen JSON.

Each handler receives a RouteContext with: - db: transaction-scoped when RouteSpec.transaction is true; pool-level otherwise - pending_effects: eager fire-and-forget pool-write queue - post_commit_effects: deferred-thunk queue (push via emit_after_commit)

Also enforces registry-time invariant 2 from the auth-shape design: auth.actor !== 'none' ⟺ input or query declares acting?: ActingActor. REST is bi-located (GETs declare acting on query, mutations on input), so the check passes both slots; the action-dispatcher registries (compile_action_registry) share the same helper with input only — ActionSpec has no query shape.

Resolves a RouteAuth to middleware guard handlers.

Injected into apply_route_specs to decouple route registration from auth-specific middleware. See fuz_auth_guard_resolver in auth/auth_guard_resolver.ts for the standard implementation.

Two-phase auth guard set returned by AuthGuardResolver.

pre_validation runs before input validation — 401 checks live here so unauthenticated callers never see route-shape information from input parsing failures. post_authorization runs after the authorization phase has populated RequestContext — role / keeper checks live here because they read c.var.request_context.role_grants.

Per-route authorization phase. Runs after pre-validation auth guards AND input validation; resolves the acting actor (when auth.actor !== 'none') by reading c.var.validated_input.acting and sets the request context on the Hono context. Per-route order in apply_route_specs: params → query → pre-validation auth (401) → input validation (400) → authorization phase → post-authorization auth (403) → handler.

Returns a Response to short-circuit (resolution failure → 400 / 500), or void to continue. The http framework stays auth-agnostic — fuz_app provides the implementation via create_fuz_authorization_handler in auth/request_context.ts.

Get validated input from the Hono context.

Call after the input validation middleware has run. Pass the route's input Zod schema to infer the typed shape directly:

Or pass an explicit type argument when the schema isn't in scope:

Get validated URL path params from the Hono context.

Call after the params validation middleware has run. Pass the route's params schema to infer the typed shape, or supply an explicit type argument. See get_route_input for the two call shapes.

Get validated URL query params from the Hono context.

Call after the query validation middleware has run. Pass the route's query schema to infer the typed shape, or supply an explicit type argument. See get_route_input for the two call shapes.

Prepend a prefix to all route spec paths.

Per-request deps provided by the framework to route handlers.

Audit writes and other rollback-resilient fire-and-forget calls run through AppDeps.audit.emit(ctx, input) (see auth/audit_emitter.ts), which captures the pool inside its closure — handlers can never accidentally write audits against the request transaction.

Routes whose body manages its own transaction (signup, bootstrap) declare transaction: false on the spec, which makes route.db the pool — they reach for it directly.

Route handler function — receives the Hono context and a RouteContext with per-request deps (db, pending_effects).

TypeScript allows fewer params, so handlers that don't need route can use (c) => ... without changes.

HTTP methods supported by route specs.

A single route definition — the unit of the surface map.

input and output schemas align with SAES ActionSpec naming. Use z.null() for routes with no request body (GET, DELETE without body).