Introspectable route spec system for Hono apps.
Routes are defined as data (method, path, auth, input/output schemas, handler), then applied to Hono. The attack surface is generated from the specs — always accurate, always complete.
Input/output schemas align with SAES ActionSpec conventions:
- input: Zod schema for the request body (z.null() for no body)
- output: Zod schema for the success response body
- z.strictObject() for inputs (reject unknown keys)
12 declarations
http/route_spec.ts view source
(app: Hono<BlankEnv, BlankSchema, "/">, specs: MiddlewareSpec[]): void Apply named middleware specs to a Hono app.
appthe Hono app
Hono<BlankEnv, BlankSchema, "/">specsmiddleware specs to apply
MiddlewareSpec[]void http/route_spec.ts view source
(app: Hono<BlankEnv, BlankSchema, "/">, specs: RouteSpec[], resolve_auth_guards: AuthGuardResolver, log: Logger, db: Db): void 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), wraps handler with DEV-only output and error validation, and registers the route.
Each handler receives a RouteContext with:
- db: transaction-scoped (for non-GET) or pool-level (for GET)
- background_db: always pool-level
- pending_effects: fire-and-forget effect queue
appthe Hono app
Hono<BlankEnv, BlankSchema, "/">specsroute specs to apply
RouteSpec[]resolve_auth_guardsmaps RouteAuth to middleware — use fuz_auth_guard_resolver from auth/route_guards.ts
logthe logger instance
Loggerdbdatabase instance for transaction wrapping and RouteContext
void http/route_spec.ts view source
AuthGuardResolver 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/route_guards.ts for the standard implementation.
http/route_spec.ts view source
<T>(c: Context<any, any, {}>): T Get validated input from the Hono context.
Call this in route handlers after the input validation middleware has run.
The type parameter should match the route's input schema.
cContext<any, any, {}>T the validated request body
http/route_spec.ts view source
<T>(c: Context<any, any, {}>): T Get validated URL path params from the Hono context.
Call this in route handlers after the params validation middleware has run.
The type parameter should match the route's params schema.
TODO
cContext<any, any, {}>T the validated path parameters
http/route_spec.ts view source
<T>(c: Context<any, any, {}>): T Get validated URL query params from the Hono context.
Call this in route handlers after the query validation middleware has run.
The type parameter should match the route's query schema.
cContext<any, any, {}>T the validated query parameters
http/route_spec.ts view source
(prefix: string, specs: RouteSpec[]): RouteSpec[] Prepend a prefix to all route spec paths.
prefixthe path prefix (e.g. /api/account)
stringspecsroute specs to prefix
RouteSpec[]RouteSpec[] new array of specs with prefixed paths
http/route_spec.ts view source
RouteAuth Auth requirement for a route — none, authenticated, a specific role, or keeper.
{type: 'none'} means the route is open to all clients — including non-browser
callers (CLI, API tokens, scripts). No session or auth middleware guards are applied.
http/route_spec.ts view source
RouteContext Per-request deps provided by the framework to route handlers.
db is transaction-scoped for mutation routes and pool-level for reads.
background_db is always pool-level — use it for fire-and-forget effects
that must outlive the transaction.
dbTransaction-scoped for mutations, pool-level for reads.
background_dbAlways pool-level — for fire-and-forget effects that outlive the transaction.
pending_effectsFire-and-forget side effects — push here for post-response flushing.
Array<Promise<void>>http/route_spec.ts view source
RouteHandler Route handler function — receives the Hono context and a RouteContext with per-request deps (db, background_db, pending_effects).
TypeScript allows fewer params, so handlers that don't need route
can use (c) => ... without changes.
http/route_spec.ts view source
RouteMethod HTTP methods supported by route specs.
http/route_spec.ts view source
RouteSpec 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).
methodpathstringauthAuth requirement for this route.
{type: 'none'} means the route is open to all clients including non-browser
callers (CLI, scripts) — no auth guards are applied.
handlerdescriptionstringparamsURL path parameter schema. Use z.strictObject() with string fields matching :param segments.
TODO
z.ZodObjectqueryURL query parameter schema. Use z.strictObject() with string fields.
z.ZodObjectinputRequest body schema. Use z.null() for routes with no body.
z.ZodTypeoutputSuccess response body schema.
z.ZodTyperate_limitRate limit key type — declares what this route's rate limiter is keyed on.
When set, 429 (RateLimitError) is auto-derived in derive_error_schemas. The actual RateLimiter instance is still wired imperatively in the handler — this field is metadata for surface introspection and policy invariants.
errorsHandler-specific error response schemas keyed by HTTP status code.
Middleware errors (auth 401/403, validation 400, rate limit 429) are
auto-derived from auth, input, and rate_limit. Declare handler-specific
errors here (e.g., 404 for not-found, 409 for conflicts).
Explicit entries override auto-derived ones for the same status code.
transactionWhether to wrap the handler in a database transaction.
When omitted, defaults are derived from the HTTP method:
- GET → false (read-only, no transaction)
- All others (POST, PUT, DELETE, PATCH) → true
Set explicitly to override the default (e.g., false for a POST
that manages its own transaction like signup).
boolean