@owlmeans/server-api 0.1.18-rc.6 → 0.1.18

package/src/utils/error/types.ts

@@ -0,0 +1,52 @@
+import type { FastifyReply } from 'fastify'
+import type { Config, HttpErrorExposure } from '../../types.js'
+import type { SerializedHttpError } from '../types.js'
+
+/** How the HTTP boundary answers a thrown error: its status, its wire body, its headers and its log entry. */
+export interface HttpErrorHelper {
+  /**
+   * The HTTP status an error's class declares, or `null` when it declares none that may be honoured.
+   *
+   * Read through the constructor chain — a static property is inherited, so a subclass answers what
+   * its nearest declaring ancestor says, and redeclares to change it. An integer 4xx is honoured
+   * directly. A 5xx is honoured only with `allowServerErrorStatus = true`, so a domain class must
+   * explicitly opt in to exposing a precise availability response. The read is structural, so a
+   * class from a duplicate module copy declares exactly what the imported one does.
+   */
+  declaredErrorStatus: (error: unknown) => number | null
+  /**
+   * The HTTP status an error is answered with, read off the error exactly as given.
+   *
+   * Two families reach here and both must be recognised. `AuthFailedError` / `AccessError` are this
+   * package's own, raised by the request pipeline itself. `AuthorizationError` / `AuthForbidden`
+   * come from `@owlmeans/auth` and are what the guards and gates actually throw — an unrecognised
+   * one answers 500, which reports a refused request as a crashed server: the client cannot tell
+   * "sign in again" from "the service is broken", and a consumer watching statuses concludes the
+   * application fell over. A family member is recognised by class OR by registered type name, so a
+   * class from a duplicate module copy answers the same status.
+   *
+   * **Order matters.** `AuthForbidden extends AuthorizationError`, so the 403 branch has to be
+   * tested first or every refusal of a permission is reported as a failure to authenticate. Both
+   * auth branches come before a class's own declaration, so an auth refusal can never be restated
+   * as something else. Everything that is neither an auth error nor a class declaring an allowed
+   * {@link HttpErrorHelper.declaredErrorStatus} answers 500.
+   */
+  errorStatus: (error: unknown) => number
+  /** Invalid or absent configuration always resolves to the production-safe policy. */
+  errorExposure: (config?: Pick<Config, 'http'>) => HttpErrorExposure
+  /** One central wire shape for every server error. */
+  serializeError: (error: Error, exposure?: HttpErrorExposure) => SerializedHttpError
+  /** Apply safe response metadata carried by an error without coupling its package to Fastify. */
+  applyErrorHeaders: (error: unknown, reply: FastifyReply) => void
+  /**
+   * Answer a thrown error: a status, and the marshalled `ResilientError` as the body.
+   *
+   * The status is resolved in two steps. The error AS THROWN comes first: it is the one object whose
+   * class is certainly the class that was raised, while `ResilientError.ensure` rebuilds through the
+   * registry of whichever `@owlmeans/error` copy this module loaded — under duplicate module copies
+   * that turns a perfectly recognisable auth refusal into a plain `ResilientError` answering 500.
+   * Only when the thrown error answers 500 is the ENSURED error asked, because the rebuild is what
+   * gives a status to a marshalled error that crossed a hop as a plain `Error`.
+   */
+  handleError: (error: Error, reply: FastifyReply, exposure?: HttpErrorExposure) => void
+}

package/src/utils/error.ts

@@ -1,18 +1,162 @@
-import { FORBIDDEN_ERROR, SERVER_ERROR, UNAUTHORIZED_ERROR } from '@owlmeans/api'
+import {
+  FORBIDDEN_ERROR, SERVER_ERROR, UNAUTHORIZED_ERROR, DENIAL_KIND_HEADER, ACCESS_DENIED_KIND,
+} from '@owlmeans/api'
 import type { FastifyReply } from 'fastify'
 import { AccessError, AuthFailedError } from '../errors.js'
-import { ResilientError } from '@owlmeans/error'
-
-export const handleError = (error: Error, reply: FastifyReply) => {
-  let code: number = SERVER_ERROR
-  if (error instanceof AuthFailedError) {
-    code = UNAUTHORIZED_ERROR
-  } else if (error instanceof AccessError) {
-    code = FORBIDDEN_ERROR
+import { AuthForbidden, AuthorizationError } from '@owlmeans/auth'
+import { isResilientError, ResilientError, SEPARATOR } from '@owlmeans/error'
+import { randomUUID } from 'node:crypto'
+import { fastifyLogUtils } from './log.js'
+import type { Config, HttpErrorExposure } from '../types.js'
+import { CLIENT_ERROR_FIRST, CLIENT_ERROR_LAST, SERVER_ERROR_FIRST, SERVER_ERROR_LAST } from './consts.local.js'
+import { INCIDENT_ID_HEADER } from './consts.js'
+import type { HttpStatusDeclaration, SerializedHttpError } from './types.js'
+import type { HttpErrorHelper } from './error/types.js'
+
+export const createHttpErrorHelper = (): HttpErrorHelper => {
+  const declaredErrorStatus = (error: unknown): number | null => {
+    if (error == null || typeof error !== 'object') {
+      return null
+    }
+    const declaration = error.constructor as HttpStatusDeclaration | undefined
+    const status = declaration?.httpStatus
+    if (typeof status !== 'number' || !Number.isInteger(status)) {
+      return null
+    }
+    if (status >= CLIENT_ERROR_FIRST && status <= CLIENT_ERROR_LAST) return status
+    if (status >= SERVER_ERROR_FIRST && status <= SERVER_ERROR_LAST
+      && declaration?.allowServerErrorStatus === true) return status
+
+    return null
+  }
+
+  /**
+   * The registered type names an error carries: its own `type`, and the static `typeName` of every
+   * class on its constructor chain.
+   *
+   * This is how a class is recognised when `instanceof` cannot see it. A process that loads a package
+   * twice — `bun --preserve-symlinks` over a linked workspace resolves one package through several
+   * `node_modules` paths — holds several copies of every error class, and an error built by one copy
+   * is not an instance of another. The registered names are the same in every copy. A subclass's
+   * `typeName` does not reliably embed its parent's (`EntitlementRefusal` extends `AuthForbidden`), so
+   * a family is recognised by walking the chain and matching names exactly, never by a substring.
+   */
+  const typeNamesOf = (error: object): Set<string> => {
+    const names = new Set<string>()
+    const type = (error as { type?: unknown }).type
+    if (typeof type === 'string') {
+      names.add(type)
+    }
+    let ctor: unknown = error.constructor
+    while (typeof ctor === 'function') {
+      const name = (ctor as { typeName?: unknown }).typeName
+      if (typeof name === 'string') {
+        names.add(name)
+      }
+      ctor = Object.getPrototypeOf(ctor)
+    }
+
+    return names
   }
-  if (!reply.sent) {
-    reply.code(code).send(
-      ResilientError.marshal(ResilientError.ensure(error as Error)).message
-    )
+
+  const isOfFamily = (names: Set<string>, family: string[]): boolean =>
+    family.some(typeName => names.has(typeName))
+
+  const errorStatus = (error: unknown): number => {
+    if (error == null || typeof error !== 'object') {
+      return SERVER_ERROR
+    }
+    const names = typeNamesOf(error)
+    if (error instanceof AuthForbidden || error instanceof AccessError
+      || isOfFamily(names, [AuthForbidden.typeName, AccessError.typeName])) {
+      // An established identity that lacks the permission. Re-authenticating changes nothing.
+      return FORBIDDEN_ERROR
+    }
+    if (error instanceof AuthorizationError || error instanceof AuthFailedError
+      || isOfFamily(names, [AuthorizationError.typeName, AuthFailedError.typeName])) {
+      // No usable credential — absent, expired, revoked, or naming a session this server no longer
+      // holds. The caller is told to sign in, not that signing in would not help.
+      return UNAUTHORIZED_ERROR
+    }
+
+    return declaredErrorStatus(error) ?? SERVER_ERROR
+  }
+
+  const errorExposure = (config?: Pick<Config, 'http'>): HttpErrorExposure =>
+    config?.http?.errors?.exposure === 'development' ? 'development' : 'production'
+
+  /**
+   * Preserve a typed/marshalled error when possible without asking `ensure` to convert a plain
+   * error. In particular, `ensure` deliberately rethrows SyntaxError; an HTTP boundary still has
+   * to serialize it safely and let the incident log retain the original object.
+   */
+  const normalizeForWire = (error: Error): Error => {
+    if (error instanceof SyntaxError || isResilientError(error)) {
+      return error
+    }
+    if (error.message.includes(SEPARATOR)) {
+      const ensured = ResilientError.ensure(error)
+      // The catch-all converter's legacy constructor shape shifts an ordinary error's fields.
+      // Only keep `ensure`'s result when a registered wire prefix actually rebuilt something.
+      if (ensured.type !== error.message || ensured.message !== error.stack) {
+        return ensured
+      }
+    }
+    return error
   }
+
+  const serializeError = (
+    error: Error, exposure: HttpErrorExposure = 'production'
+  ): SerializedHttpError => {
+    const normalized = normalizeForWire(error)
+    const thrown = errorStatus(error)
+    const status = thrown !== SERVER_ERROR ? thrown : errorStatus(normalized)
+    const incidentId = randomUUID()
+    // The server log owns every diagnostic. Production callers receive only its correlation key;
+    // development keeps the typed wire form so local clients can retain their usual error details.
+    Object.assign(error, { incidentId })
+    if (isResilientError(normalized)) normalized.incidentId = incidentId
+    const body = exposure === 'production'
+      ? incidentId
+      : ResilientError.marshal(normalized, { includeStack: true, incidentId }).message
+
+    return { status, body, incidentId }
+  }
+
+  const applyErrorHeaders = (error: unknown, reply: FastifyReply): void => {
+    if (error == null || typeof error !== 'object') {
+      return
+    }
+    const retryAfter = (error as { retryAfter?: unknown }).retryAfter
+    if (typeof retryAfter === 'number' && Number.isFinite(retryAfter) && retryAfter > 0) {
+      reply.header('Retry-After', String(Math.ceil(retryAfter)))
+    }
+    // Match exact registered types. EntitlementRefusal also extends AuthForbidden but is a plan
+    // decision, not a person's IAM permission denial.
+    const type = (error as { type?: unknown }).type
+    if (type === AuthForbidden.typeName || type === AccessError.typeName) {
+      reply.header(DENIAL_KIND_HEADER, ACCESS_DENIED_KIND)
+    }
+  }
+
+  const handleError = (
+    error: Error, reply: FastifyReply, exposure: HttpErrorExposure = 'production'
+  ): void => {
+    if (!reply.sent) {
+      const serialized = serializeError(error, exposure)
+      applyErrorHeaders(error, reply)
+      // The one record of a failed request: method, path and status — never what the caller sent.
+      fastifyLogUtils.failure(error, reply.request, serialized.status, serialized.incidentId)
+      reply.header(INCIDENT_ID_HEADER, serialized.incidentId)
+        .code(serialized.status)
+        .send(serialized.body)
+    }
+  }
+
+  return { declaredErrorStatus, errorStatus, errorExposure, serializeError, applyErrorHeaders, handleError }
 }
+
+export const httpErrorHelper = createHttpErrorHelper()
+
+/** @deprecated compat:factory-refactor — use `httpErrorHelper.errorStatus(…)` */
+export const errorStatus = (error: unknown): number => httpErrorHelper.errorStatus(error)

package/src/utils/guards.ts

@@ -1,15 +1,12 @@
-import { isContextWithoutIds, Layer } from '@owlmeans/context'
 import type { FastifyReply, FastifyRequest } from 'fastify'
 import type { ServerEntrypoint } from '@owlmeans/server-entrypoint'
-import type { GuardService } from '@owlmeans/entrypoint'
-import { provideResponse } from '@owlmeans/entrypoint'
-import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
-import { executeResponse, provideRequest } from './payload.js'
+import { type GuardService, provideResponse } from '@owlmeans/entrypoint'
+import { payloadHelper } from './payload.js'
 import { AuthFailedError } from '../errors.js'
 import type { Auth } from '@owlmeans/auth'
+import type { Config, Context } from './types.local.js'
+import { makeEntityScope } from '@owlmeans/auth-common'
 
-type Config = ServerConfig
-interface Context<C extends Config = Config> extends ServerContext<C> { }
 
 export const authorize = async <C extends Config, T extends Context<C>>(
   context: T, module: ServerEntrypoint<FastifyRequest>,
@@ -18,7 +15,7 @@ export const authorize = async <C extends Config, T extends Context<C>>(
   const guards = module.getGuards()
   if (guards.length > 0) {
     const response = provideResponse(reply)
-    const request = provideRequest(module.alias, req)
+    const request = payloadHelper.provideRequest(module.alias, req)
 
     let guard: GuardService | undefined = undefined
     for (const alias of guards) {
@@ -26,7 +23,7 @@ export const authorize = async <C extends Config, T extends Context<C>>(
       if (await _guard.match(request, response)) {
         guard = _guard
       }
-      executeResponse(response, reply, true)
+      payloadHelper.executeResponse(response, reply, true)
       if (guard != null) {
         break
       }
@@ -40,7 +37,7 @@ export const authorize = async <C extends Config, T extends Context<C>>(
     if (!await guard.handle<boolean>(request, authResponse)) {
       throw new AuthFailedError(guard.alias)
     }
-    executeResponse(authResponse, reply, true)
+    payloadHelper.executeResponse(authResponse, reply, true)
     // Guard that returns true and does not provide an error is an optional guard
     // if (authResponse.value == null) {
     //   throw SyntaxError(`Guard that returns true and does not provide an error, should provide authorization`)
@@ -50,22 +47,15 @@ export const authorize = async <C extends Config, T extends Context<C>>(
       (req as any)._auth = request.auth
     }
 
-    if (request.auth?.entityId != null) {
-      // @TODO Probably we need to downgrade context in this case
-      if (!isContextWithoutIds(context as any)) {
-        throw SyntaxError(`Context should be without ids during authorization ${context.cfg.layer}:${context.cfg.layerId}`)
-      }
-
-      if (isContextWithoutIds(context as any) && context.cfg.layer !== Layer.Service) {
-        context = await context.updateContext(undefined, Layer.Service)
-        await context.waitForInitialized()
-      }
-      context = await context.updateContext(request.auth.entityId, Layer.Entity)
-      await context.waitForInitialized()
-
-      // We elevate module to the context level if it was changed
-      module = context.entrypoint(module.alias)
-      await module.resolve()
+    // The token names the organization by slug; everything downstream — grants, records, minted
+    // infrastructure names — keys on the entity's stable id. Resolving here, once, is what keeps a
+    // rename from being a sweep of every handler: the id arrives on the request, and a slug that
+    // has since been retired still resolves to the entity that retired it.
+    const entity = await makeEntityScope(request).attachEntity(context)
+    if (entity != null) {
+      // Carried on the raw request the same way `_auth` is, so the request the handler is given
+      // later — a different object, built after this runs — sees the same resolution.
+      ;(req as any)._entity = entity
     }
   }
   // Update context in request object

package/src/utils/index.ts

@@ -1,7 +1,12 @@
 
 export * from './error.js'
+export * from './consts.js'
+export type * from './types.js'
+export type * from './error/types.js'
+export type * from './payload/types.js'
+export type * from './context/types.js'
 export * from './server.js'
 export * from './payload.js'
-export * from './server.js'
+export * from './schema.js'
 export * from './guards.js'
 export * from './context.js'

package/src/utils/log/consts.ts

@@ -0,0 +1,18 @@
+/**
+ * Keys of a Fastify log record that carry what a caller sent. They are dropped at every depth: a
+ * request body and its raw form (`rawBody`), multipart fields and file buffers, headers (with the
+ * authorization and cookie values), cookies and the parsed query string.
+ */
+export const UNSAFE_LOG_KEYS: ReadonlySet<string> = new Set([
+  'body', 'rawBody', 'payload', 'files', 'file', 'headers', 'rawHeaders', 'trailers', 'rawTrailers',
+  'query', 'querystring', 'cookies', 'cookie', 'authorization',
+])
+
+/** Deepest nesting `safeData` walks; anything below is one marker. */
+export const SAFE_DATA_DEPTH = 4
+
+/**
+ * The query string of a path or URL inside free text (a Fastify warning names `"/x?token=…"`): the
+ * path is kept (`$1`), the query is cut.
+ */
+export const QUERY_IN_TEXT = /(\/[^\s?"'`]*)\?[^\s"'`)]+/g

package/src/utils/log/types.ts

@@ -0,0 +1,43 @@
+import type { FastifyBaseLogger, LogController } from 'fastify'
+import type { Logger } from '@owlmeans/log'
+
+/** All a log record may say about a request: its method and its path — never the query string. */
+export interface RequestSummary {
+  method?: string
+  path?: string
+}
+
+/**
+ * How the API server's Fastify instance logs: through `@owlmeans/log`, and never with what a caller
+ * sent — a body, a raw body, multipart bytes, headers, cookies or a query string.
+ */
+export interface FastifyLogUtils {
+  /**
+   * A pino-shaped logger over `log` (scope `http` by default), handed to Fastify as its
+   * `loggerInstance`. Every record's data — Fastify's own and any plugin's — passes `safeData`.
+   */
+  logger: (log?: Logger, bindings?: Record<string, unknown>) => FastifyBaseLogger
+  /**
+   * The `logController` Fastify writes its own request lines through: no per-request pair (the
+   * server writes one debug record from `onResponse`), a request the default error handler answers
+   * is `failure`, a missing route is one debug line without its query.
+   */
+  controller: () => LogController
+  /**
+   * A copy of a record's data that is safe to write: a request becomes its `RequestSummary`, a reply
+   * its status, bytes their size, any other class instance its name; the keys that carry what a
+   * caller sent (`body`, `rawBody`, `headers`, `query`, `cookies`, files…) are dropped at every depth
+   * (a number or boolean under them stays: a count, a flag), and any string loses the query of a URL
+   * it names. An `Error` passes as it is (a copy, when its message names a URL with a query) — the
+   * log writes only its name, message, code and stack.
+   */
+  safeData: (data: unknown) => unknown
+  /** The method and the path, without the query string, of a Fastify or Node request. */
+  requestOf: (request: unknown) => RequestSummary
+  /**
+   * The one record of a failed request, by what its status means: 5xx `error` with the error,
+   * 403 `warn` `access.forbidden`, 401 `debug` `auth.refused`, any other 4xx `debug` with the error's
+   * code and message. Method, path and status only — never the request's content.
+   */
+  failure: (error: Error, request: unknown, status: number, incidentId?: string) => void
+}

package/src/utils/log.ts

@@ -0,0 +1,193 @@
+import { LogController } from 'fastify'
+import type { FastifyBaseLogger, FastifyReply, FastifyRequest } from 'fastify'
+import { FORBIDDEN_ERROR, SERVER_ERROR, UNAUTHORIZED_ERROR } from '@owlmeans/api'
+import { logger, type LogLevel, type Logger } from '@owlmeans/log'
+import type { Severity } from './types.local.js'
+import { QUERY_IN_TEXT, SAFE_DATA_DEPTH, UNSAFE_LOG_KEYS } from './log/consts.js'
+import type { FastifyLogUtils, RequestSummary } from './log/types.js'
+
+const pathOf = (url: string): string => url.split('?')[0]
+
+const withoutQueries = (text: string): string => text.replace(QUERY_IN_TEXT, '$1')
+
+/** The error itself, or — when its message names a URL with a query — a copy without the query. */
+const safeError = (error: Error): Error => {
+  const message = withoutQueries(error.message)
+  if (message === error.message) {
+    return error
+  }
+  const copy: Error = Object.assign(Object.create(Object.getPrototypeOf(error) as object) as Error, error)
+  copy.message = message
+  copy.stack = error.stack != null ? withoutQueries(error.stack) : undefined
+  return copy
+}
+
+const isPlain = (value: object): boolean => {
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+const levelName = (log: Logger): string => {
+  const order: LogLevel[] = ['debug', 'info', 'warn', 'error']
+  return order.find(level => log.enabled(level)) ?? 'silent'
+}
+
+export const createFastifyLogUtils = (): FastifyLogUtils => {
+  const http = logger('http')
+
+  const requestOf = (request: unknown): RequestSummary => {
+    const { method, url } = (request ?? {}) as { method?: unknown, url?: unknown }
+    return {
+      ...(typeof method === 'string' ? { method } : {}),
+      ...(typeof url === 'string' ? { path: pathOf(url) } : {}),
+    }
+  }
+
+  /** A class instance as a record may carry it: a request or reply by summary, anything else by name. */
+  const instanceOf = (value: object): unknown => {
+    const shape = value as { method?: unknown, url?: unknown, statusCode?: unknown }
+    if (typeof shape.method === 'string' && typeof shape.url === 'string') {
+      return requestOf(value)
+    }
+    if (typeof shape.statusCode === 'number') {
+      return { statusCode: shape.statusCode }
+    }
+    const name = value.constructor?.name ?? 'object'
+    if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+      return `[${name} ${value.byteLength} bytes]`
+    }
+    return `[${name}]`
+  }
+
+  const safe = (value: unknown, depth: number, seen: WeakSet<object>): unknown => {
+    if (typeof value === 'string') {
+      return withoutQueries(value)
+    }
+    if (value instanceof Error) {
+      return safeError(value)
+    }
+    if (value == null || typeof value !== 'object' || value instanceof Date) {
+      return value
+    }
+    if (seen.has(value)) {
+      return '[circular]'
+    }
+    if (!Array.isArray(value) && !isPlain(value)) {
+      return instanceOf(value)
+    }
+    if (depth >= SAFE_DATA_DEPTH) {
+      return '[…]'
+    }
+    seen.add(value)
+    if (Array.isArray(value)) {
+      return value.map(item => safe(item, depth + 1, seen))
+    }
+    const out: Record<string, unknown> = {}
+    for (const [key, item] of Object.entries(value)) {
+      // A count or a flag under such a key (`limits.files: 5`) says nothing a caller sent.
+      if (UNSAFE_LOG_KEYS.has(key) && typeof item !== 'number' && typeof item !== 'boolean') {
+        continue
+      }
+      out[key] = key === 'url' && typeof item === 'string' ? pathOf(item) : safe(item, depth + 1, seen)
+    }
+    return out
+  }
+
+  const safeData = (data: unknown): unknown => safe(data, 0, new WeakSet())
+
+  const failure: FastifyLogUtils['failure'] = (error, request, status, incidentId) => {
+    const where = { ...requestOf(request), status, ...(incidentId != null ? { incidentId } : {}) }
+    const safe = safeError(error)
+    if (status >= SERVER_ERROR) {
+      http.error('Request failed', { err: safe, ...where })
+    } else if (status === FORBIDDEN_ERROR) {
+      http.warn('Access forbidden', { type: (error as { type?: unknown }).type, message: safe.message, ...where },
+        { event: 'access.forbidden' })
+    } else if (status === UNAUTHORIZED_ERROR) {
+      http.debug('Authentication refused', { message: safe.message, ...where }, { event: 'auth.refused' })
+    } else {
+      const code = (error as { code?: unknown }).code
+      http.debug('Request refused', { ...(typeof code === 'string' ? { code } : {}), message: safe.message, ...where })
+    }
+  }
+
+  /**
+   * Fastify announces its listening address at info; the server writes `server.listening` itself.
+   * Its request lines no longer reach the adapter at all — `controller()` owns them.
+   */
+  const levelOf = (level: Severity, message: unknown): Severity =>
+    level === 'info' && typeof message === 'string' && message.startsWith('Server listening at') ? 'debug' : level
+
+  const fastifyLogger = (log: Logger = http, bindings?: Record<string, unknown>): FastifyBaseLogger => {
+    const call = (requested: Severity) => (first: unknown, second?: unknown): void => {
+      const [object, message] = typeof first === 'string' || first instanceof Error
+        ? [undefined, first] : [first, second]
+      const level = levelOf(requested, message)
+      if (!log.enabled(level)) {
+        return
+      }
+      const data = bindings != null && Object.keys(bindings).length > 0
+        ? { ...bindings, ...(object != null && typeof object === 'object' ? object : {}) } : object
+      const text = message == null ? '' : message instanceof Error ? safeError(message) : withoutQueries(String(message))
+      log[level](text, safeData(data))
+    }
+
+    const adapter = {
+      get level(): string { return levelName(log) },
+      set level(_value: string) { /* the level belongs to the process, not to this server */ },
+      fatal: call('error'), error: call('error'), warn: call('warn'),
+      info: call('info'), debug: call('debug'), trace: call('debug'),
+      silent: () => undefined,
+      // Fastify's second argument (pino options: its own `req`/`res` serializers) is ignored —
+      // `safeData` is this adapter's serializer.
+      child: (extra: Record<string, unknown>) => fastifyLogger(log, { ...bindings, ...extra }),
+    }
+    return adapter as unknown as FastifyBaseLogger
+  }
+
+  /**
+   * Fastify accepts a `logController` only as an instance of its own class, so this one member is a
+   * subclass; its methods use no `this`.
+   */
+  const controller = (): LogController => {
+    class SafeLogController extends LogController {
+      override incomingRequest (): void { /* `onResponse` writes the one record of a request */ }
+
+      override requestCompleted (error: Error | null | undefined, request: FastifyRequest, reply: FastifyReply): void {
+        if (error != null) {
+          http.error('Response failed', { err: error, ...requestOf(request), status: reply.statusCode })
+        }
+      }
+
+      override defaultErrorLog (error: Error, request: FastifyRequest, reply: FastifyReply): void {
+        failure(error, request, reply.statusCode)
+      }
+
+      override streamError (error: Error, request: FastifyRequest, reply: FastifyReply): void {
+        const where = { ...requestOf(request), status: reply.statusCode }
+        if ((error as { code?: unknown }).code === 'ERR_STREAM_PREMATURE_CLOSE') {
+          http.debug('Response stream closed prematurely', where)
+        } else {
+          http.warn('Response stream failed after its headers were sent', { err: error, ...where })
+        }
+      }
+
+      override routeNotFound (request: FastifyRequest): void {
+        http.debug('Route not found', requestOf(request))
+      }
+
+      override writeHeadError (error: Error, request: FastifyRequest, reply: FastifyReply): void {
+        http.warn('Response headers not written', { err: error, ...requestOf(request), status: reply.statusCode })
+      }
+
+      override serializerError (error: Error, request: FastifyRequest, _reply: FastifyReply, metadata: { statusCode: number }): void {
+        http.error('Response serializer failed', { err: error, ...requestOf(request), status: metadata.statusCode })
+      }
+    }
+    return new SafeLogController()
+  }
+
+  return { logger: fastifyLogger, controller, safeData, requestOf, failure }
+}
+
+export const fastifyLogUtils = createFastifyLogUtils()

package/src/utils/payload/types.ts

@@ -0,0 +1,18 @@
+import type { AbstractRequest, AbstractResponse } from '@owlmeans/entrypoint'
+import type { Request, Response } from '../../types.js'
+
+/** Moves an exchange between Fastify and the entrypoint shapes: the request in, the response out. */
+export interface PayloadHelper {
+  /** The entrypoint request of a Fastify request; `provision` keeps the original on it. */
+  provideRequest: (alias: string, req: Request, provision?: boolean) => AbstractRequest
+  /**
+   * Emits the response onto the fastify reply if the handler produced an
+   * error or an outcome. Returns `true` when something was actually sent so
+   * callers don't rely on `reply.sent`, which in fastify v5 only flips once
+   * the raw socket finishes writing (asynchronously) and therefore reads
+   * `false` synchronously right after `reply.send()`.
+   *
+   * @throws {Error}
+   */
+  executeResponse: <T>(response: AbstractResponse<T>, reply: Response, throwOnError?: boolean) => boolean
+}