pipework 0.251.0 → 0.252.1

package/src/request/http/server.ts

@@ -0,0 +1,916 @@
+import { randomUUID } from 'node:crypto'
+import { Readable } from 'node:stream'
+import Fastify, { type FastifyInstance, type FastifyRequest, type FastifyReply } from 'fastify'
+import fastifyCors from '@fastify/cors'
+import fastifyHelmet from '@fastify/helmet'
+import fastifyRateLimit from '@fastify/rate-limit'
+import fastifyMultipart from '@fastify/multipart'
+import type { Manifold } from '../../core/pipework.js'
+import type { Handler, HttpMethod } from '../di/types.js'
+import type { CorsConfig, ServerConfig, RouteRegistration, HandlerResponse, InjectOptions, InjectResponse } from './types.js'
+import { runInContext } from '../context/store.js'
+import { createRequestContext } from '../context/index.js'
+import { executeInTransaction } from '../context/run-in-transaction.js'
+import { resolveAndExecute, parseRouteInputs, resolveHandlerDatabases, buildCheckpoint, type ResolveOptions } from '../di/resolve.js'
+import { createRateLimitClasses } from './rate-limit-classes.js'
+import { buildContext, type ContextOptions } from './middleware.js'
+import { closeTrace } from '../../trace/entry/close-trace.js'
+import { recordErrorStep } from './error-step.js'
+import type { Flow } from '../context/index.js'
+import type { ErrorResponse } from './types.js'
+import { buildErrorResponse, buildInternalErrorResponse, buildClientErrorResponse, sendError } from './response.js'
+import { isPipeworkError } from '../../core/errors/index.js'
+import { checkUploadHeaders, uploadBodyLimit, startUpload, settleUpload, isUploadRefusal, newUploadTrack, type UploadTrack, MULTIPART_FIELD_LIMIT } from './upload.js'
+import type { BinaryUpload, MultipartUpload, UploadConfig, UploadRefusal, RouteRefusal, RouteRefusedHook, HandlerMeta } from '../di/types.js'
+import { __flowStep } from '../../trace/runtime/flow-step.js'
+import { isFileResponse, fileResponseProblem, contentDisposition, primeStream, type FileResponse } from './file.js'
+import type { FileConfig } from '../di/types.js'
+import { toJsonSchema } from '../../data/schema/json-schema.js'
+import { generateOpenAPI } from '../openapi/generate.js'
+import { getBaseLogger, setLoggingConfig } from '../../core/logging/index.js'
+import { settleTraceWrites } from '../../trace/runtime/pending-writes.js'
+import { setupDrain } from '../../core/lifecycle/drain.js'
+import { registerHealthRoutes } from '../../core/lifecycle/health.js'
+import { validateSessionVarName } from '../../auth/tenant/index.js'
+import type { Rbac } from '../../auth/rbac/types.js'
+import { ForbiddenError } from '../../core/errors/index.js'
+import { withTenantSetting } from '../../auth/tenant/in-tenant.js'
+import type { Resource } from '../fixture/types.js'
+import { resourceToHandlers } from '../fixture/to-handlers.js'
+
+/** Fastify server wrapper with route registration, handler auto-wiring, and inject() for testing. */
+export interface PipeworkServer {
+  route(method: HttpMethod, path: string, handler: Handler<Record<string, unknown>, unknown>): void
+  registerHandlers(handlers: Handler<Record<string, unknown>, unknown>[]): void
+  registerResource(resource: Resource<unknown>): void
+  ready(): Promise<void>
+  inject(opts: InjectOptions): Promise<InjectResponse>
+  listen(): Promise<string>
+  close(): Promise<void>
+  /**
+   * Stops the listener at once and drains in-flight requests, leaving the pools open. When `force` aborts, the
+   * remaining sockets are destroyed and this returns without waiting for their handlers.
+   */
+  stop(force?: AbortSignal): Promise<void>
+}
+
+/** Creates a PipeworkServer — wraps Fastify with auto request IDs, CORS, rate limiting, and transaction-per-request. */
+export function createServer(instance: Manifold, config: ServerConfig = {}): PipeworkServer {
+  if (instance.config.environment === 'production') {
+    validateProductionConfig(config)
+  }
+
+  const fastifyOpts: Record<string, unknown> = {
+    trustProxy: Array.isArray(config.trustProxy) ? [...config.trustProxy] : (config.trustProxy ?? false),
+    genReqId: () => randomUUID(),
+    requestIdHeader: false,
+  }
+
+  if (config.bodyLimit !== undefined) {
+    fastifyOpts['bodyLimit'] = config.bodyLimit
+  }
+
+  if (config.logger === false) {
+    fastifyOpts['logger'] = false
+  } else {
+    fastifyOpts['loggerInstance'] = config.logger ?? getBaseLogger()
+  }
+
+  const app = Fastify(fastifyOpts)
+
+  // Fastify's own refusals (content type, bad JSON, body too large) answer in
+  // Pipework's error shape, never through a route's declared response schema.
+  // The Flow of a request that got one, for the internal-error hook.
+  const requestFlows = new WeakMap<object, Flow>()
+  const refusedRequests = new WeakSet<object>()
+
+  // Tells `onInternalError` about an error answered with a 5xx, in the request's
+  // Flow (no transaction is open: the request's has rolled back). Awaited; a
+  // failure is logged and the response is unchanged.
+  async function reportInternalError(req: FastifyRequest, error: unknown, handler: Handler<Record<string, unknown>, unknown> | null = null): Promise<void> {
+    const hook = config.onInternalError
+    if (hook === undefined) return
+    try {
+      const route = (req.routeOptions as { url?: string } | undefined)?.url ?? req.url.split('?')[0]!
+      const ctx = requestFlows.get(req) ?? createRequestContext({
+        instance,
+        requestId: String(req.id),
+        metadata: { method: req.method, path: req.url, startedAt: Date.now(), traceId: String(req.id), sessionId: null },
+      })
+      const inputs = parseRouteInputs(handler?.meta ?? null, req.query, req.params)
+      await runInContext(ctx, () => hook({
+        error,
+        params: inputs.params,
+        query: inputs.query,
+        method: req.method,
+        route,
+        requestId: String(req.id),
+        tenantId: ctx.tenant,
+        userId: ctx.user ?? ((ctx.auth as Record<string, unknown> | null)?.['userId'] ?? null) as string | null,
+        traceId: ctx.trace?.id ?? null,
+      }))
+    } catch (hookError) {
+      req.log.error(hookError, 'onInternalError failed')
+    }
+  }
+
+  // Runs a route's `onRefused` hook for a 4xx about to be sent, in the request's
+  // Flow (a minimal one where the request never got its own), as a trace step.
+  // What it returns is merged into `response.error` except pipework's own keys;
+  // a throw is logged and the response is left as it was.
+  async function runRefusedHook(
+    req: FastifyRequest,
+    meta: HandlerMeta | null,
+    ctx: Flow | undefined,
+    status: number,
+    response: ErrorResponse,
+  ): Promise<void> {
+    const hook = meta?.onRefused
+    if (meta === null || hook === undefined || hook === null) return
+    if (refusedRequests.has(req)) return
+    refusedRequests.add(req)
+    try {
+      const flow = ctx ?? createRequestContext({
+        instance,
+        requestId: String(req.id),
+        metadata: { method: req.method, path: req.url, startedAt: Date.now(), traceId: String(req.id), sessionId: null },
+      })
+      const inputs = parseRouteInputs(meta, req.query, req.params)
+      const refusal: RouteRefusal = {
+        status,
+        code: response.error.code,
+        message: response.error.message,
+        fields: response.error.fields ?? null,
+        retryAfterSeconds: status === 429 ? response.error.retryAfterSeconds ?? null : null,
+        auth: ctx?.auth ?? null,
+        params: inputs.params,
+        query: inputs.query,
+        request: {
+          headers: req.headers as Record<string, string | undefined>,
+          ip: req.ip,
+          ips: [...(req.ips ?? [req.ip])],
+        },
+        requestId: String(req.id),
+      }
+      const extra: unknown = await runInContext(flow, () => refusedStep(hook, refusal))
+      if (typeof extra !== 'object' || extra === null || Array.isArray(extra)) return
+      const target = response.error as unknown as Record<string, unknown>
+      for (const [key, value] of Object.entries(extra as Record<string, unknown>)) {
+        if (REFUSAL_OWN_KEYS.has(key)) {
+          req.log.warn({ key, requestId: String(req.id) }, 'onRefused hook returned a key pipework owns; dropped')
+          continue
+        }
+        Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true })
+      }
+    } catch (hookError) {
+      req.log.error({ err: hookError, requestId: String(req.id) }, 'onRefused hook threw')
+    }
+  }
+
+  app.setErrorHandler(async (error, req, reply) => {
+    const status = (error as { statusCode?: unknown }).statusCode
+    const open = requestFlows.get(req)
+    const routeOf = (): string => (req.routeOptions as { url?: string } | undefined)?.url ?? req.url.split('?')[0]!
+    const record = async (code: string, httpStatus: number, refused?: () => Promise<void>): Promise<void> => {
+      if (open === undefined) {
+        await refused?.()
+        return
+      }
+      recordErrorStep(open, { method: req.method, route: routeOf(), status: httpStatus, code, error })
+      try {
+        await refused?.()
+      } finally {
+        void closeTrace(instance, open.trace, 'error')
+      }
+    }
+    if (typeof status === 'number' && status >= 400 && status < 500) {
+      const response = buildClientErrorResponse(status, error, reply.getHeader('retry-after'))
+      const owner = (req.routeOptions as { config?: { pipeworkHandler?: Handler<Record<string, unknown>, unknown> } } | undefined)?.config?.pipeworkHandler
+      await record(response.error.code, status, () => runRefusedHook(req, owner?.meta ?? null, open, status, response))
+      return sendError(reply, status, response)
+    }
+    req.log.error(error, 'Unhandled error')
+    await record('INTERNAL_ERROR', 500)
+    await reportInternalError(req, error)
+    return sendError(reply, 500, buildInternalErrorResponse(error, config.exposeErrorDetails))
+  })
+
+  // Validation is handled by Pipework's DI layer (parse + ValidationError).
+  // Pass-through compiler lets us attach JSON Schema for OpenAPI without AJV double-validating.
+  app.setValidatorCompiler(() => (data) => ({ value: data }))
+
+  // CORS is closed unless granted: a route's own `.cors()` replaces the server's
+  // `cors` for that route, and a route with neither grants nothing. The plugin
+  // loads only if some grant exists, which is known once routes are registered.
+  // A preflight names no route of its own, so each path that has a grant gets
+  // one OPTIONS route carrying the grant per method; Fastify does the matching.
+  const corsPaths = new Map<string, { byMethod: Record<string, CorsConfig | false> }>()
+  let grantCount = 0
+  const serverGrant: CorsConfig | null = config.cors !== undefined && config.cors !== false ? config.cors : null
+  const corsPlugin = async (scope: FastifyInstance): Promise<void> => {
+    if (serverGrant === null && grantCount === 0) return
+    await scope.register(fastifyCors, {
+      delegator: (req: FastifyRequest, cb: (err: Error | null, options?: Record<string, unknown>) => void) => {
+        let grant: CorsConfig | null
+        const requested = req.headers['access-control-request-method']
+        const routeConfig = req.routeOptions.config as { cors?: CorsConfig | false; corsByMethod?: Record<string, CorsConfig | false> } | undefined
+        if (req.method === 'OPTIONS' && typeof requested === 'string') {
+          const g = routeConfig?.corsByMethod?.[requested.toUpperCase()]
+          grant = g === undefined || g === false ? null : g
+        } else {
+          const own = routeConfig?.cors
+          grant = own === undefined ? serverGrant : own === false ? null : own
+        }
+        cb(null, grant === null ? { origin: false } : (grant as Record<string, unknown>))
+      },
+    } as never)
+    for (const [path, entry] of corsPaths) {
+      if (!Object.values(entry.byMethod).some((g) => g !== false)) continue
+      scope.options(path, { config: { corsByMethod: entry.byMethod } }, (_req, reply) => reply.status(204).send())
+    }
+  }
+  ;(corsPlugin as unknown as Record<symbol, boolean>)[Symbol.for('skip-override')] = true
+  void app.register(corsPlugin)
+
+  if (config.security !== false) {
+    void app.register(fastifyHelmet, (config.security ?? {}) as Record<string, unknown>)
+  }
+
+  if (config.rateLimit !== false) {
+    void app.register(fastifyRateLimit, (config.rateLimit ?? {}) as Record<string, unknown>)
+  }
+
+  if (config.logging) {
+    setLoggingConfig(config.logging)
+  }
+
+  app.decorateRequest('rawBody', undefined)
+  app.decorateRequest('pipeworkTraceId', null)
+
+  app.addHook('onSend', (_req, reply, payload, done) => {
+    void reply.header('x-request-id', _req.id)
+    const traceId = (_req as FastifyRequest & { pipeworkTraceId: string | null }).pipeworkTraceId
+    if (traceId !== null) void reply.header('x-pipework-trace-id', traceId)
+    done(null, payload)
+  })
+
+  const routes: RouteRegistration[] = []
+
+  const authConfig = config.auth
+  const strategies = authConfig
+    ? ('strategies' in authConfig ? authConfig.strategies : [authConfig.strategy])
+    : []
+  const enrichers = authConfig && 'enrichers' in authConfig ? (authConfig.enrichers ?? []) : []
+  const tenantResolver = authConfig && 'tenantResolver' in authConfig ? authConfig.tenantResolver : undefined
+
+  const tenantConfig = config.tenant ?? null
+  if (tenantConfig?.sessionVars) {
+    for (const name of Object.keys(tenantConfig.sessionVars)) {
+      validateSessionVarName(name)
+    }
+  }
+
+  const contextOptions: ContextOptions = {
+    instance,
+    strategies,
+    enrichers,
+    tenantResolver,
+    tenantConfig,
+    authOptional: authConfig?.optional ?? false,
+    logging: config.logging ?? null,
+  }
+
+  const gracefulShutdownMs = config.gracefulShutdownMs ?? 10000
+  const drain = setupDrain(app)
+
+  if (config.health !== false) {
+    // Registered on the app itself: probes are never rate limited.
+    registerHealthRoutes(app, instance, config.healthChecks ?? [], {
+      health: config.healthPath ?? '/health',
+      ready: config.readyPath ?? '/ready',
+    })
+  }
+
+  const rbacInstance = config.rbac ?? null
+  const rateLimitClasses = config.rateLimits === undefined ? null : createRateLimitClasses(instance, config.rateLimits)
+
+  const txDatabases: readonly string[] | null = config.transactionPerRequest !== undefined && config.transactionPerRequest !== false
+    ? (config.transactionPerRequest === true
+        ? [...instance.config.databases().keys()]
+        : config.transactionPerRequest)
+    : null
+  const txTimeoutMs = config.transactionTimeoutMs ?? 5000
+
+  if (tenantConfig?.sessionVars !== undefined && txDatabases === null) {
+    throw new Error(
+      '[pipework] Tenant session variables require transactionPerRequest.\n\n' +
+      '  Your server config has tenant.sessionVars configured, but transactionPerRequest\n' +
+      '  is not enabled. Session variables are propagated via SET LOCAL inside a\n' +
+      '  transaction — without transactionPerRequest, they are silently skipped.\n\n' +
+      '  Fix: Add transactionPerRequest: true (or a list of database names) to your\n' +
+      '  createServer() config.\n',
+    )
+  }
+
+  function route(
+    method: HttpMethod,
+    path: string,
+    handler: Handler<Record<string, unknown>, unknown>,
+  ): void {
+    routes.push({ method, path, handler })
+    rateLimitClasses?.checkRoute(method, path, handler.meta)
+
+    const fastifyMethod = method.toLowerCase() as 'get' | 'post' | 'put' | 'patch' | 'delete'
+
+    const schema: Record<string, unknown> = {}
+    if (handler.meta.inputSchema) {
+      schema['body'] = toJsonSchema(handler.meta.inputSchema)
+    }
+    if (handler.meta.outputSchemas.size > 0) {
+      const response: Record<string, unknown> = {}
+      for (const [status, outputSchema] of handler.meta.outputSchemas) {
+        response[String(status)] = toJsonSchema(outputSchema)
+      }
+      schema['response'] = response
+    }
+    if (handler.meta.querySchema) {
+      schema['querystring'] = toJsonSchema(handler.meta.querySchema)
+    }
+    if (handler.meta.paramsSchema) {
+      schema['params'] = toJsonSchema(handler.meta.paramsSchema)
+    }
+    const opts: Record<string, unknown> = Object.keys(schema).length > 0 ? { schema } : {}
+
+    const ownCors = handler.meta.cors ?? undefined
+    const entry = corsPaths.get(path) ?? { byMethod: {} }
+    const effective = ownCors === undefined ? (serverGrant ?? false) : ownCors
+    entry.byMethod[method] = effective
+    corsPaths.set(path, entry)
+    if (ownCors !== undefined) {
+      grantCount++
+      opts['config'] = { ...(opts['config'] as object | undefined), cors: ownCors }
+      if (instance.config.environment === 'production') {
+        const problem = credentialedWildcard(ownCors)
+        if (problem !== null) throw new Error(`[pipework] ${method} ${path}: ${problem}`)
+      }
+    }
+
+    if (handler.meta.onRefused) {
+      opts['config'] = { ...(opts['config'] as object | undefined), pipeworkHandler: handler }
+    }
+
+    const upload = handler.meta.upload ?? null
+    if (upload !== null) {
+      opts['bodyLimit'] = uploadBodyLimit(upload)
+    } else if (handler.meta.route?.bodyLimit !== undefined) {
+      opts['bodyLimit'] = handler.meta.route.bodyLimit
+    }
+
+    const screen = handler.meta.route?.screen
+    if (screen !== undefined) {
+      // Runs before the body is parsed, so a route can refuse on headers alone
+      // (its own status + named reason) before the body limit turns it into 413.
+      opts['onRequest'] = async (req: FastifyRequest, reply: FastifyReply) => {
+        const raw = req.headers['content-length']
+        const declared = raw === undefined || raw === '' ? NaN : Number(raw)
+        let refusal
+        try {
+          // The screen runs inside its own minimal request context so `pipe.system()`
+          // works. No auth chain and no transaction: the screen is pre-parse and
+          // pre-auth, and its reads are committed-only, outside request atomicity.
+          const screenCtx = createRequestContext({
+            instance,
+            requestId: String(req.id),
+            metadata: { method: req.method, path: req.url, startedAt: Date.now(), traceId: String(req.id), sessionId: null },
+          })
+          refusal = await runInContext(screenCtx, () => screen({
+            method: req.method,
+            url: req.url,
+            headers: req.headers as Record<string, string | undefined>,
+            contentLength: Number.isFinite(declared) ? declared : null,
+            params: parseRouteInputs(handler.meta, req.query, req.params).params,
+          }))
+        } catch (error) {
+          req.log.error(error, 'Route screen threw')
+          await reportInternalError(req, error, handler)
+          return sendError(reply, 500, {
+            error: 'ScreenFailed',
+            message:
+              `[pipework] The pre-parse screen for ${method} ${path} threw: ${error instanceof Error ? error.message : String(error)}\n\n` +
+              '  A screen must inspect headers and either return a refusal\n' +
+              '  ({ status, reason }) or return nothing. Fix the screen, or catch\n' +
+              '  inside it and return the refusal you want the caller to see.\n',
+          })
+        }
+        if (refusal !== undefined && refusal !== null) {
+          return sendError(reply, refusal.status, { ...refusal.body, reason: refusal.reason })
+        }
+        return undefined
+      }
+    }
+
+    if (upload !== null && upload.kind === 'multipart') {
+      // After the screen: a body that is not multipart/form-data is a protocol
+      // error, refused from the headers before anything is read.
+      const headerCheck = async (req: FastifyRequest, reply: FastifyReply) => {
+        const refusal = checkUploadHeaders(upload, req.headers)
+        if (refusal === null) return undefined
+        void reply.header('connection', 'close')
+        const response = buildErrorResponse(refusal)
+        await runRefusedHook(req, handler.meta, undefined, refusal.httpStatus, response)
+        return sendError(reply, refusal.httpStatus, response)
+      }
+      const existing = opts['onRequest'] as ((req: FastifyRequest, reply: FastifyReply) => Promise<unknown>) | undefined
+      opts['onRequest'] = existing === undefined ? [headerCheck] : [existing, headerCheck]
+    }
+
+    if (handler.meta.wantsRawBody) {
+      opts['preParsing'] = async (req: FastifyRequest, _reply: FastifyReply, payload: AsyncIterable<Buffer>) => {
+        const chunks: Buffer[] = []
+        for await (const chunk of payload) chunks.push(chunk)
+        const raw = Buffer.concat(chunks)
+        ;(req as FastifyRequest & { rawBody: Buffer }).rawBody = raw
+        return Readable.from(raw)
+      }
+    }
+
+    const routeHandler = async (req: FastifyRequest, reply: FastifyReply) => {
+      let ctx: Flow | undefined
+      let uploaded: BinaryUpload | MultipartUpload | undefined
+      const track = newUploadTrack()
+      // Ends the upload stream and closes the connection if the body was left unread.
+      const finishUpload = (failed: boolean): void => {
+        if (settleUpload(uploaded?.stream) || (failed && upload !== null)) void reply.header('connection', 'close')
+      }
+      try {
+        ctx = await buildContext(req, contextOptions, handler.meta.authRequirement)
+        ;(req as FastifyRequest & { pipeworkTraceId: string | null }).pipeworkTraceId = ctx.trace?.id ?? null
+        requestFlows.set(req, ctx)
+
+        if (rateLimitClasses !== null) await rateLimitClasses.check(req, ctx, handler.meta, { method, url: path })
+
+        if (handler.meta.permission && rbacInstance) {
+          await enforceHandlerPermission(instance, ctx, handler.meta, rbacInstance)
+        }
+
+        const requestObj: import('./types.js').HttpRequest = {
+          headers: req.headers as Record<string, string | undefined>,
+          ip: req.ip,
+          ips: [...(req.ips ?? [req.ip])],
+        }
+        const rawBodyBuffer = handler.meta.wantsRawBody
+          ? (req as FastifyRequest & { rawBody: Buffer }).rawBody
+          : undefined
+        if (rawBodyBuffer !== undefined) {
+          (requestObj as { rawBody: Buffer }).rawBody = rawBodyBuffer
+        }
+
+        if (upload !== null) {
+          uploaded = await startUpload(req, upload, track)
+        }
+
+        const httpOptions: ResolveOptions = {
+          request: requestObj,
+          response: {
+            header: (name: string, value: string | readonly string[]) => { void reply.header(name, typeof value === 'string' ? value : [...value]) },
+            onFinish: (cb) => watchResponse(reply, cb, req.log),
+          },
+          ...(rawBodyBuffer !== undefined ? { rawBody: rawBodyBuffer } : {}),
+          ...(uploaded !== undefined ? { upload: uploaded } : {}),
+        }
+
+        // Fastify hands a missing body over as null; the input sees undefined.
+        // A body that is literally JSON null names a content-type and stays null.
+        const body = req.body === null && req.headers['content-type'] === undefined ? undefined : req.body
+
+        let result: unknown
+        if (handler.meta.jobTransaction === 'manual') {
+          // The route owns its commit boundaries: no request-wide transaction
+          // is opened, and every checkpoint commits on its own. Between them
+          // the handler holds no connection, which is the point — a lease can
+          // be written and committed, a network call made, and the outcome
+          // written again, all under the request's own tenant with RLS
+          // enforced. What it costs is stated on `.transaction('manual')`.
+          const checkpoint = buildCheckpoint(
+            handler,
+            ctx,
+            resolveHandlerDatabases(handler, instance),
+            tenantConfig,
+            txTimeoutMs,
+          )
+          result = await runInContext(ctx, () =>
+            resolveAndExecute(handler, body, req.query, req.params, { ...httpOptions, checkpoint }),
+          )
+        } else if (txDatabases !== null && txDatabases.length > 0) {
+          result = await executeInTransaction(
+            ctx,
+            txDatabases,
+            tenantConfig,
+            txTimeoutMs,
+            () => resolveAndExecute(handler, body, req.query, req.params, httpOptions),
+          )
+        } else {
+          result = await runInContext(ctx, () => resolveAndExecute(handler, body, req.query, req.params, httpOptions))
+        }
+
+        finishUpload(false)
+        void closeTrace(instance, ctx.trace, 'closed')
+        return await sendResult(reply, req, result, handler.meta.file ?? null, `${method} ${path}`)
+      } catch (error) {
+        finishUpload(true)
+        // Records the error step, runs `refused` (the route's onRefused hook) while the
+        // trace is still open, then closes the trace.
+        const failWith = async (status: number, code: string, refused?: () => Promise<void>): Promise<void> => {
+          recordErrorStep(ctx, { method, route: path, status, code, error })
+          try {
+            await refused?.()
+          } finally {
+            if (ctx !== undefined) void closeTrace(instance, ctx.trace, 'error')
+          }
+        }
+
+        if (error instanceof FileResponseError) {
+          await failWith(500, 'FILE_RESPONSE_INVALID')
+          req.log.error({ route: `${method} ${path}`, requestId: String(req.id), err: error }, 'File response refused')
+          await reportInternalError(req, error, handler)
+          return sendError(reply, 500, { error: { code: 'FILE_RESPONSE_INVALID', message: error.message } })
+        }
+
+        if (isPipeworkError(error)) {
+          const response = buildErrorResponse(error)
+          const isClient = error.httpStatus >= 400 && error.httpStatus < 500
+          await failWith(error.httpStatus, error.code, async () => {
+            if (upload !== null && ctx !== undefined && isUploadRefusal(error)) {
+              const message = await notifyRefusal(req, ctx, handler, upload, track, error)
+              if (message !== undefined) response.error.message = message
+            }
+            if (isClient) await runRefusedHook(req, handler.meta, ctx, error.httpStatus, response)
+          })
+          const retryAfter = response.error.retryAfterSeconds
+          if (retryAfter !== undefined) void reply.header('Retry-After', String(retryAfter))
+          if (error.httpStatus >= 500) await reportInternalError(req, error, handler)
+          return sendError(reply, error.httpStatus, response)
+        }
+
+        // A malformed multipart body surfaces as a Fastify client error (4xx).
+        const clientStatus = upload !== null ? (error as { statusCode?: unknown } | null)?.statusCode : undefined
+        if (typeof clientStatus === 'number' && clientStatus >= 400 && clientStatus < 500) {
+          const response = buildClientErrorResponse(clientStatus, error)
+          await failWith(clientStatus, response.error.code, () => runRefusedHook(req, handler.meta, ctx, clientStatus, response))
+          return sendError(reply, clientStatus, response)
+        }
+
+        await failWith(500, 'INTERNAL_ERROR')
+        req.log.error(error, 'Unhandled error in route handler')
+        await reportInternalError(req, error, handler)
+        return sendError(reply, 500, buildInternalErrorResponse(error, config.exposeErrorDetails))
+      }
+    }
+
+    // Its own plugin scope, so the route loads after @fastify/rate-limit and
+    // gets its limit (a route added to `app` directly would be registered
+    // before the plugin's onRoute hook exists). An upload's body parsers
+    // replace the JSON parser for this route only, so no other route's
+    // parsing changes.
+    void app.register(async (scope) => {
+      if (upload !== null) {
+        scope.removeAllContentTypeParsers()
+        if (upload.kind === 'binary') {
+          scope.addContentTypeParser('*', (_req, payload, done) => { done(null, payload) })
+        } else {
+          await scope.register(fastifyMultipart, {
+            throwFileSizeLimit: false,
+            limits: { fileSize: upload.maxBytes + 1024, fieldSize: MULTIPART_FIELD_LIMIT, files: 1, fields: 100 },
+          })
+        }
+      }
+      if (handler.meta.ignoresBody === true && upload === null) {
+        scope.removeAllContentTypeParsers()
+        scope.addContentTypeParser('*', (req, payload, done) => {
+          const declared = Number(req.headers['content-length'])
+          if (Number.isFinite(declared) && declared > IGNORED_BODY_LIMIT) {
+            done(Object.assign(new Error('Request body is too large'), { statusCode: 413 }))
+            return
+          }
+          payload.resume()
+          done(null, undefined)
+        })
+      }
+      scope[fastifyMethod](path, opts, routeHandler)
+    })
+  }
+
+  // Tells the route's `onRefuse` hook about a file pipework refused, in the
+  // request's context. Returns the hook's replacement message, if it gave one.
+  async function notifyRefusal(
+    req: FastifyRequest,
+    ctx: Flow,
+    handler: Handler<Record<string, unknown>, unknown>,
+    upload: UploadConfig,
+    track: UploadTrack,
+    error: { httpStatus: number; code: string },
+  ): Promise<string | undefined> {
+    if (upload.onRefuse === undefined) return undefined
+    const declaredLength = Number(req.headers['content-length'])
+    const inputs = parseRouteInputs(handler.meta, req.query, req.params)
+    const refusal: UploadRefusal = {
+      status: error.httpStatus as 413 | 415,
+      code: error.code,
+      detectedType: track.detectedType,
+      declaredType: track.declaredType,
+      extension: track.extension,
+      filename: track.filename,
+      declaredLength: req.headers['content-length'] !== undefined && Number.isFinite(declaredLength) ? declaredLength : null,
+      bytesRead: track.bytesRead,
+      accepted: upload.mediaTypes,
+      auth: ctx.auth,
+      requestId: ctx.requestId,
+      params: inputs.params,
+      query: inputs.query,
+    }
+    const hook = upload.onRefuse
+    try {
+      const message = await runInContext(ctx, async () => hook(refusal))
+      return typeof message === 'string' && message !== '' ? message : undefined
+    } catch (hookError) {
+      req.log.error({ err: hookError, requestId: ctx.requestId }, 'Upload onRefuse hook threw')
+      return undefined
+    }
+  }
+
+  function registerHandlers(handlers: Handler<Record<string, unknown>, unknown>[]): void {
+    for (const handler of handlers) {
+      if (handler.meta.route) {
+        route(handler.meta.route.method, handler.meta.route.path, handler)
+      }
+    }
+  }
+
+  function registerResourceFn(resource: Resource<unknown>): void {
+    registerHandlers(resourceToHandlers(resource))
+  }
+
+  if (config.openapi) {
+    const openApiPath = config.openApiPath ?? '/openapi.json'
+    const openApiInfo = config.openapi
+    // Registered on the app itself: the document is not rate limited.
+    app.get(openApiPath, async (_req, reply) => {
+      return reply.send(generateOpenAPI(openApiInfo, routes, { rateLimited: config.rateLimit !== false || config.rateLimits !== undefined }))
+    })
+  }
+
+  async function listen(): Promise<string> {
+    const address = await app.listen({
+      port: config.port ?? 3000,
+      host: config.host ?? '0.0.0.0',
+    })
+
+    if (config.managed !== true) {
+      setupGracefulShutdown(app, instance, drain, gracefulShutdownMs)
+    }
+
+    return address
+  }
+
+  async function close(): Promise<void> {
+    await app.close()
+    await settleTraceWrites()
+    await instance.pool.closeAll()
+  }
+
+  async function stop(force?: AbortSignal): Promise<void> {
+    const node = app.server
+    const destroy = (): void => { node.closeAllConnections() }
+    if (node.listening) node.close()
+    if (force?.aborted === true) destroy()
+    else force?.addEventListener('abort', destroy, { once: true })
+    try {
+      await app.close()
+    } finally {
+      force?.removeEventListener('abort', destroy)
+    }
+    if (force?.aborted !== true) await settleTraceWrites()
+  }
+
+  async function ready(): Promise<void> {
+    await app.ready()
+  }
+
+  async function inject(opts: InjectOptions): Promise<InjectResponse> {
+    const response = await app.inject({
+      method: opts.method as 'GET',
+      url: opts.url,
+      headers: opts.headers as Record<string, string>,
+      payload: opts.payload as string,
+      query: opts.query as Record<string, string>,
+      ...(opts.remoteAddress !== undefined ? { remoteAddress: opts.remoteAddress } : {}),
+    })
+    const r = response as unknown as { statusCode: number; headers: Record<string, string | number | string[] | undefined>; body: string; rawPayload: Buffer; json(): unknown }
+    return { statusCode: r.statusCode, headers: r.headers, body: r.body, rawPayload: r.rawPayload, json: () => r.json() }
+  }
+
+  return { route, registerHandlers, registerResource: registerResourceFn, ready, inject, listen, close, stop }
+}
+
+const REFUSAL_OWN_KEYS: ReadonlySet<string> = new Set(['code', 'message', 'fields', 'details', 'retryAfterSeconds'])
+
+const refusedStep = __flowStep(
+  { ref: 'pipework/http:on-refused' },
+  async (hook: RouteRefusedHook, refusal: RouteRefusal) => hook(refusal),
+)
+
+function setupGracefulShutdown(
+  app: FastifyInstance,
+  instance: Manifold,
+  drain: ReturnType<typeof setupDrain>,
+  timeoutMs: number,
+): void {
+  const shutdown = async (signal: string) => {
+    app.log.info({ signal }, 'Graceful shutdown initiated')
+
+    const timer = setTimeout(() => {
+      process.exit(1)
+    }, timeoutMs)
+
+    let exitCode = 0
+    try {
+      await drain.waitForDrain(timeoutMs - 1000)
+      await app.close()
+      await settleTraceWrites()
+      await instance.pool.closeAll()
+    } catch {
+      exitCode = 1
+    } finally {
+      clearTimeout(timer)
+      process.exit(exitCode)
+    }
+  }
+
+  process.once('SIGTERM', () => { void shutdown('SIGTERM') })
+  process.once('SIGINT', () => { void shutdown('SIGINT') })
+}
+
+// Runs `cb` once with how the response ended. `finish` fires when the last byte
+// is handed to the socket; `close` without `finish` means the connection died first.
+function watchResponse(
+  reply: FastifyReply,
+  cb: (outcome: 'sent' | 'aborted') => void | Promise<void>,
+  log: { error(obj: unknown, msg?: string): void },
+): void {
+  const raw = reply.raw
+  let called = false
+  const settle = (outcome: 'sent' | 'aborted'): void => {
+    if (called) return
+    called = true
+    raw.removeListener('finish', onFinish)
+    raw.removeListener('close', onClose)
+    void (async () => {
+      try {
+        await cb(outcome)
+      } catch (err) {
+        log.error(err, 'HttpResponse.onFinish callback threw')
+      }
+    })()
+  }
+  const onFinish = (): void => settle('sent')
+  const onClose = (): void => settle(raw.writableFinished ? 'sent' : 'aborted')
+  if (raw.writableFinished) return settle('sent')
+  if (raw.destroyed) return settle('aborted')
+  raw.once('finish', onFinish)
+  raw.once('close', onClose)
+}
+
+/** A file response the route cannot send; becomes a 500 naming the reason. */
+class FileResponseError extends Error {}
+
+async function sendFile(reply: FastifyReply, req: FastifyRequest, file: FileResponse, declared: FileConfig | null, route: string): Promise<unknown> {
+  const problem = fileResponseProblem(declared, file)
+  if (problem !== null) {
+    if (!Buffer.isBuffer(file.body)) file.body.destroy()
+    throw new FileResponseError(`[pipework] ${route}: ${problem}`)
+  }
+
+  let body: Buffer | Readable
+  let length: number | undefined
+  if (Buffer.isBuffer(file.body)) {
+    body = file.body
+    length = file.body.length
+  } else {
+    body = await primeStream(file.body, file.length)
+    length = file.length
+    const raw = reply.raw
+    body.on('error', (err) => {
+      // Headers are out: the only honest signal left is a dead connection.
+      req.log.error({ route, requestId: String(req.id), err }, 'File stream failed while sending')
+      raw.destroy()
+    })
+    raw.once('close', () => { if (!(body as Readable).destroyed) (body as Readable).destroy() })
+  }
+
+  void reply.status(declared?.status ?? 200)
+  void reply.header('content-type', file.mediaType)
+  void reply.header('content-disposition', contentDisposition(file.disposition, file.filename))
+  void reply.header('x-content-type-options', 'nosniff')
+  if (length !== undefined) void reply.header('content-length', String(length))
+  return reply.send(body)
+}
+
+/** The largest declared body a route that ignores its body drains. */
+const IGNORED_BODY_LIMIT = 64 * 1024
+
+function isStatusResponse(value: unknown): value is HandlerResponse {
+  return value !== null && typeof value === 'object' && 'status' in value && typeof (value as Record<string, unknown>)['status'] === 'number'
+}
+
+async function sendResult(reply: FastifyReply, req: FastifyRequest, result: unknown, fileConfig: FileConfig | null, route: string): Promise<unknown> {
+  if (isFileResponse(result)) return sendFile(reply, req, result, fileConfig, route)
+  if (fileConfig !== null) {
+    const other = isStatusResponse(result) && result.status !== fileConfig.status
+    if (!other) {
+      throw new FileResponseError(`[pipework] ${route} is declared with .file() and must return http.file({ body, mediaType, filename? }) at status ${fileConfig.status}; it returned ${result === null ? 'null' : typeof result}. Only a { status } answer at another status may stand in for the file.`)
+    }
+  }
+  if (isStatusResponse(result)) {
+    const response = result as HandlerResponse
+    if (response.body !== undefined) {
+      return reply.status(response.status).send(response.body)
+    }
+    return reply.status(response.status).send()
+  }
+  return reply.status(200).send(result)
+}
+
+function credentialedWildcard(grant: CorsConfig | false): string | null {
+  if (grant === false || grant.credentials !== true) return null
+  const origin = grant.origin
+  if (origin === true || origin === '*' || (Array.isArray(origin) && origin.includes('*'))) {
+    return 'a grant with credentials: true must name its origins; origin: true or "*" lets any site read credentialed responses.\n' +
+      '  Fix: List the exact origins, or drop credentials.'
+  }
+  return null
+}
+
+function validateProductionConfig(config: ServerConfig): void {
+  const problems: string[] = []
+
+  if (config.cors !== undefined && config.cors !== false) {
+    const problem = credentialedWildcard(config.cors)
+    if (problem !== null) problems.push(`CORS: ${problem}`)
+  }
+
+  if (config.rateLimit === undefined && config.rateLimits === undefined) {
+    problems.push(
+      'Rate limiting: Not configured. Production APIs should have rate limiting.\n' +
+      '  Fix: Set rateLimit: { max: 100, timeWindow: "1 minute" }, set rateLimits: { classes: {...} }, or set rateLimit: false to explicitly opt out.',
+    )
+  }
+
+  if (config.auth !== undefined && config.tenant === undefined) {
+    problems.push(
+      'Tenant isolation: Auth is configured but no tenant config is set.\n' +
+      '  Fix: Set tenant: { mode: "schema" | "rls" | "header", ... } to enforce tenant isolation,\n' +
+      '  or acknowledge this by setting tenant: null in your server config.',
+    )
+  }
+
+  if (problems.length > 0) {
+    throw new Error(
+      `[pipework] Production server configuration is missing security settings:\n\n${problems.map((p, i) => `  ${i + 1}. ${p}`).join('\n\n')}\n\n` +
+      '  Pipework refuses to start a production server with insecure defaults.\n' +
+      '  Set each option explicitly to confirm your security posture.\n',
+    )
+  }
+}
+
+async function enforceHandlerPermission(
+  instance: Manifold,
+  ctx: import('../context/types.js').Flow,
+  meta: import('../di/types.js').HandlerMeta,
+  rbac: Rbac,
+): Promise<void> {
+  const permission = meta.permission!
+
+  if (ctx.auth === null || typeof ctx.auth !== 'object') {
+    throw new ForbiddenError(`Missing permission: ${permission.resource}:${permission.action}`)
+  }
+
+  const auth = ctx.auth as Record<string, unknown>
+  const userId = typeof auth['userId'] === 'string' ? auth['userId'] : null
+  const tenantId = ctx.tenant
+  const authVersion = typeof auth['authVersion'] === 'number' ? auth['authVersion'] : 1
+
+  if (userId === null || tenantId === null) {
+    throw new ForbiddenError(`Missing permission: ${permission.resource}:${permission.action}`)
+  }
+
+  const dbName = meta.databases[0] ?? [...instance.config.databases().keys()][0]
+  if (dbName === undefined) {
+    throw new ForbiddenError(`Missing permission: ${permission.resource}:${permission.action}`)
+  }
+
+  const permissionSet = await withTenantSetting(instance, dbName, tenantId, db => rbac.resolve(db, userId, tenantId, authVersion))
+  const granted = rbac.check(permissionSet, permission.resource, permission.action, permission.scope)
+  if (!granted) {
+    throw new ForbiddenError(`Missing permission: ${permission.resource}:${permission.action}`)
+  }
+}