@owlmeans/server-api 0.1.18-rc.5 → 0.1.18-rc.51

package/src/protocol.ts

@@ -0,0 +1,149 @@
+import { assertContext, type BasicConfig, type BasicContext } from '@owlmeans/context'
+import { EntrypointOutcome, type BodyOf, type EntrypointProtocolDeclaration, type HandlerRequest, type OpenRequest, type ParamsOf, type RequestOf, type ResponseOf, type AbstractRequest } from '@owlmeans/entrypoint'
+import type { BoundEntrypointHandler } from '@owlmeans/server-entrypoint'
+import { HandlerMisconfiguredError } from './errors.js'
+import { logger } from '@owlmeans/log'
+import type { AnyBoundHandler, BodyProtocol, ContextCarrier, HandlerResponse, MaybePromise, ParamsProtocol } from './types.local.js'
+
+
+const contextFor = <Context extends BasicContext<BasicConfig>>(
+  request: AbstractRequest,
+  fallback: Context,
+): Context => {
+  const original = request.original
+  if (original != null && typeof original === 'object' && '_ctx' in original) {
+    return (original as ContextCarrier<Context>)._ctx ?? fallback
+  }
+
+  return fallback
+}
+
+const bind = <Protocol extends EntrypointProtocolDeclaration, Context extends BasicContext<BasicConfig>>(
+  protocol: Protocol,
+  execute: (request: HandlerRequest<RequestOf<Protocol>>, context: Context) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>,
+): BoundEntrypointHandler<Protocol> => ({
+  protocol,
+  bind: ref => async (request, response) => {
+    const fallback = assertContext<BasicConfig, Context>(ref.ref?.ctx, protocol.alias)
+
+    try {
+      const typedRequest = (request as HandlerRequest<OpenRequest>) as HandlerRequest<RequestOf<Protocol>>
+      const value = await execute(
+        typedRequest,
+        contextFor(request, fallback),
+      )
+      response.resolve(value as ResponseOf<Protocol>, EntrypointOutcome.Ok)
+    } catch (error) {
+      response.reject(error as Error)
+    }
+
+    return response.value
+  },
+})
+
+/**
+ * `value` is shaped like a `BoundEntrypointHandler` — never a plain function, which also carries
+ * its own `.bind` and would otherwise pass a `typeof value.bind === 'function'` check alone.
+ */
+const isBoundHandler = (value: unknown): value is AnyBoundHandler =>
+  typeof value === 'object' && value != null
+  && typeof (value as { bind?: unknown }).bind === 'function'
+  && (value as { protocol?: unknown }).protocol != null
+
+const warnedAliases = new Set<string>()
+
+/**
+ * What `body`/`params`/`request` do with something that is not the plain callback they declare —
+ * the shape a handler module wraps its own export in when it is bound TWICE. `null` means the
+ * second argument really is a callback and the caller should wrap it as usual.
+ *
+ * A handler bound to THIS protocol is returned unchanged, with a one-time warning: the module
+ * already produced a working `BoundEntrypointHandler`, and re-wrapping it here would only wrap it
+ * again — returning it as-is is what makes `bind(protocol, api.body(protocol, alreadyBound))`
+ * behave exactly like `bind(protocol, alreadyBound)`, which is what a wrap-once file looks like at
+ * this call site. Anything else — a handler bound to a DIFFERENT protocol, or a value that is
+ * neither a function nor a bound handler at all — answers every request on this route with
+ * {@link HandlerMisconfiguredError} instead of throwing `TypeError: handler is not a function`
+ * out of the request pipeline's own `try`, where the type name and the alias it happened on are
+ * both lost.
+ */
+const toleratedHandler = <Protocol extends EntrypointProtocolDeclaration>(
+  protocol: Protocol, handler: unknown
+): BoundEntrypointHandler<Protocol> | null => {
+  if (typeof handler === 'function') return null
+
+  if (isBoundHandler(handler)) {
+    if (handler.protocol.alias === protocol.alias) {
+      if (!warnedAliases.has(protocol.alias)) {
+        warnedAliases.add(protocol.alias)
+        logger('server-api').warn(
+          `${protocol.alias}: handler is already bound — pass it to bind() directly; `
+          + 'wrapping it again here is a type error (TS2345 "BoundEntrypointHandler<…> is not '
+          + 'assignable"), tolerated at runtime for a project generated before the wrap-once rule.'
+        )
+      }
+
+      return handler as unknown as BoundEntrypointHandler<Protocol>
+    }
+
+    return bind<Protocol, BasicContext<BasicConfig>>(protocol, () => {
+      throw new HandlerMisconfiguredError(
+        `${protocol.alias}: handler is bound to a different protocol ('${handler.protocol.alias}')`
+      )
+    })
+  }
+
+  return bind<Protocol, BasicContext<BasicConfig>>(protocol, () => {
+    throw new HandlerMisconfiguredError(`${protocol.alias}: handler is not a function`)
+  })
+}
+
+/**
+ * Make server handlers that infer request sections and response values from their protocol.
+ * The protocol is passed once; application callbacks never name request or reply generics.
+ */
+export const handlers = <Context extends BasicContext<BasicConfig>>() => ({
+  body: <Protocol extends EntrypointProtocolDeclaration>(
+    protocol: Protocol,
+    handler: Protocol extends BodyProtocol<Protocol> ? (
+        payload: BodyOf<Protocol>,
+        context: Context,
+        request: HandlerRequest<RequestOf<Protocol>>,
+      ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>
+      : never,
+  ): BoundEntrypointHandler<Protocol> => toleratedHandler(protocol, handler) ?? bind<Protocol, Context>(protocol, (request, context) =>
+    (handler as (
+      payload: BodyOf<Protocol>, context: Context, request: HandlerRequest<RequestOf<Protocol>>,
+    ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>)(request.body as BodyOf<Protocol>, context, request)),
+
+  params: <Protocol extends EntrypointProtocolDeclaration>(
+    protocol: Protocol,
+    handler: Protocol extends ParamsProtocol<Protocol> ? (
+        payload: ParamsOf<Protocol>,
+        context: Context,
+        request: HandlerRequest<RequestOf<Protocol>>,
+      ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>
+      : never,
+  ): BoundEntrypointHandler<Protocol> => toleratedHandler(protocol, handler) ?? bind<Protocol, Context>(protocol, (request, context) =>
+    (handler as (
+      payload: ParamsOf<Protocol>, context: Context, request: HandlerRequest<RequestOf<Protocol>>,
+    ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>)(request.params as ParamsOf<Protocol>, context, request)),
+
+  request: <Protocol extends EntrypointProtocolDeclaration>(
+    protocol: Protocol,
+    handler: (
+      request: HandlerRequest<RequestOf<Protocol>>,
+      context: Context,
+    ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>,
+  ): BoundEntrypointHandler<Protocol> => toleratedHandler(protocol, handler) ?? bind<Protocol, Context>(protocol, handler),
+})
+
+/** Access a Fastify-specific upload through an explicit boundary helper, never `request.original`. */
+export const uploadedFile = async (
+  request: HandlerRequest<{ body: object }>,
+): Promise<import('@fastify/multipart').MultipartFile | undefined> => {
+  const original = (request as AbstractRequest).original
+  if (original == null || typeof original !== 'object' || !('file' in original)) return undefined
+
+  return (original as import('fastify').FastifyRequest).file()
+}

package/src/server.ts

@@ -1,13 +1,16 @@
-import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import type { ServerContext } from '@owlmeans/server-context'
 import type { ApiServer, ApiServerAppend } from './types.js'
-import { Layer, assertContext, createService } from '@owlmeans/context'
-import { canServeModule, executeResponse, provideRequest } from './utils/index.js'
+import { assertContext, createService } from '@owlmeans/context'
+import { canServeModule, payloadHelper, createServerHandler, fixFormatDates } from './utils/index.js'
 import { DEFAULT_ALIAS, CLOSED_HOST, PORT, OPENED_HOST } from './consts.js'
 import type { ServerEntrypoint } from '@owlmeans/server-entrypoint'
 import { RouteMethod } from '@owlmeans/route'
-import { createServerHandler, fixFormatDates } from './utils/index.js'
 import { provideResponse } from '@owlmeans/entrypoint'
 import { TOKEN_UPDATE } from '@owlmeans/auth-common'
+import { INCIDENT_ID_HEADER } from './utils/consts.js'
+import { DENIAL_KIND_HEADER } from '@owlmeans/api'
+import { logger } from '@owlmeans/log'
+import { fastifyLogger } from './utils/log.js'
 
 import Fastify from 'fastify'
 import type { FastifyRequest } from 'fastify'
@@ -20,6 +23,8 @@ import Multipart from '@fastify/multipart'
 import formatsPlugin from 'ajv-formats'
 import Ajv from 'ajv'
 import ajvErrors from "ajv-errors"
+import { bodyLimit } from './consts.local.js'
+import type { Config, Context } from './types.local.js'
 
 
 const ajv = new Ajv({
@@ -32,32 +37,25 @@ const ajv = new Ajv({
 formatsPlugin(ajv)
 ajvErrors(ajv, { singleError: true })
 
-type Config = ServerConfig
-type Context = ServerContext<Config>
 
-const bodyLimit = 1024 * 1024 * 20
+const http = logger('http')
+
+/**
+ * Fastify logging through `@owlmeans/log`. Fastify's own request/response lines are dropped by the
+ * adapter: a request is a debug record written once from `onResponse` (below), and a failed one is
+ * classified by `handleError`, so an info-level process is not flooded with every call it serves.
+ */
+const createFastify = () => Fastify({
+  loggerInstance: fastifyLogger(http),
+  bodyLimit,
+})
 
 export const createApiServer = (alias: string): ApiServer => {
   const location = `service:${alias}`
   const _assertContext = (context: Context | undefined): Context => assertContext<Config, Context>(context, location)
 
   const service = createService<ApiServer>(alias, {
-    server: Fastify({
-      logger: true,
-      bodyLimit,
-      /*{
-       transport: {
-         target: 'pino-pretty',
-         options: {
-           singleLine: true,
-           translateTime: 'HH:MM:ss Z',
-           ignore: 'pid,hostname',
-         },
-       },
-     }*/
-    }),
-
-    layers: [Layer.System],
+    server: createFastify(),
 
     listen: async () => {
       const context = _assertContext(service.ctx as Context)
@@ -67,7 +65,7 @@ export const createApiServer = (alias: string): ApiServer => {
       const port = config?.internalPort ?? config?.port ?? PORT
       const host = config.opened === true ? OPENED_HOST : CLOSED_HOST
       await service.server.listen({ port, host })
-      console.info(`${location}: server listening on ${host}${port != null ? `:${port}` : ''}`)
+      logger('server').info(`${location}: server listening on ${host}${port != null ? `:${port}` : ''}`, undefined, { event: 'server.listening' })
 
       process.on('SIGTERM', () => {
         service.server.close().then(() => {
@@ -78,7 +76,7 @@ export const createApiServer = (alias: string): ApiServer => {
   }, service => async () => {
     if (service.server.server.listening) {
       await service.server.close()
-      service.server = Fastify({ logger: true, bodyLimit })
+      service.server = createFastify()
     }
 
     const context = _assertContext(service.ctx as Context)
@@ -86,6 +84,16 @@ export const createApiServer = (alias: string): ApiServer => {
     const server = service.server
     // @TODO We should ensure some way that Resilient Error is thrown and go to the flow
     server.setValidatorCompiler(opts => ajv.compile(opts.schema))
+    server.addHook('onResponse', (request, reply, done) => {
+      if (http.enabled('debug')) {
+        // The path only: a query string can carry a token.
+        http.debug('request', {
+          method: request.method, path: request.url.split('?')[0], status: reply.statusCode,
+          ms: Math.round(reply.elapsedTime),
+        })
+      }
+      done()
+    })
     // @TODO It's quite unsafe and should be properly configured
     await server.register(cors, {
       origin: '*',
@@ -101,7 +109,7 @@ export const createApiServer = (alias: string): ApiServer => {
         ...Object.values(RouteMethod).map(method => method.toUpperCase()),
         'HEAD', 'OPTIONS'
       ],
-      exposedHeaders: [TOKEN_UPDATE]
+      exposedHeaders: [TOKEN_UPDATE, INCIDENT_ID_HEADER, DENIAL_KIND_HEADER]
     })
 
     await server.register(Multipart, {
@@ -133,59 +141,53 @@ export const createApiServer = (alias: string): ApiServer => {
           return context
         }
 
-        // await module.route.resolve(context as any)
-        await module.resolve()
-        // Actually intermediate module can be created without handler by elevate function
-        if (module.route.match(request) && module.handle != null) {
+        // An intermediate route can be created without a handler by the binding layer.
+        if (module.route.match(request, module.mount()) && module.handle != null) {
           const response = provideResponse(reply)
-          const currentRequest = provideRequest(module.alias, request, true)
+          const currentRequest = payloadHelper.provideRequest(module.alias, request, true)
           currentRequest.original._ctx = context
           const result: Context = await module.handle(currentRequest, response)
           if (result != null) {
             context = result
           }
-          responded = executeResponse(response, reply, true) || responded
+          responded = payloadHelper.executeResponse(response, reply, true) || responded
         }
         return context
       }, Promise.resolve(context))
     })
 
-    await Promise.all(
-      context.entrypoints<ServerEntrypoint<FastifyRequest>>()
-        .filter(module => canServeModule(context, module) && !module.route.isIntermediate())
-        .map(async module => {
-          // await module.route.resolve(context as any)
-          await module.resolve()
-          const method = module.route.route.method ?? RouteMethod.GET
-          if (module.handle == null) {
-            return
-          }
-          server.route({
-            url: module.getPath(), method,
-            schema: {
-              consumes: [
-                'application/json',
-                'application/x-www-form-urlencoded',
-                'multipart/form-data',
-              ],
-              querystring: fixFormatDates(module.filter?.query ?? {}),
-              ...(
-                [
-                  RouteMethod.POST,
-                  RouteMethod.PATCH,
-                  RouteMethod.PUT
-                ].includes(method)
-                  ? { body: fixFormatDates(module.filter?.body ?? {}) }
-                  : {}
-              ),
-              params: fixFormatDates(module.filter?.params ?? {}),
-              response: module.filter?.response,
-              headers: fixFormatDates(module.filter?.headers ?? {})
-            },
-            handler: createServerHandler(module, location)
-          })
+    context.entrypoints<ServerEntrypoint<FastifyRequest>>()
+      .filter(module => canServeModule(context, module) && !module.route.isIntermediate())
+      .forEach(module => {
+        const method = module.route.route.method ?? RouteMethod.GET
+        if (module.handle == null) {
+          return
+        }
+        server.route({
+          url: module.mount(), method,
+          schema: {
+            consumes: [
+              'application/json',
+              'application/x-www-form-urlencoded',
+              'multipart/form-data',
+            ],
+            querystring: fixFormatDates(module.filter?.query ?? {}),
+            ...(
+              [
+                RouteMethod.POST,
+                RouteMethod.PATCH,
+                RouteMethod.PUT
+              ].includes(method)
+                ? { body: fixFormatDates(module.filter?.body ?? {}) }
+                : {}
+            ),
+            params: fixFormatDates(module.filter?.params ?? {}),
+            response: module.filter?.response,
+            headers: fixFormatDates(module.filter?.headers ?? {})
+          },
+          handler: createServerHandler(module, location)
         })
-    )
+      })
 
     service.initialized = true
   })
@@ -207,5 +209,3 @@ export const appendApiServer = <C extends Config, T extends ServerContext<C>>(
 
   return context
 }
-
-

package/src/types.local.ts

@@ -0,0 +1,44 @@
+import type { EntrypointProtocolDeclaration, OpenValue, RequestOf } from '@owlmeans/entrypoint'
+import type { BoundEntrypointHandler } from '@owlmeans/server-entrypoint'
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+
+/**
+ * True for a response the declaration left with no compile-time contract: `typed<any>()` (an
+ * `[any] extends [X]` conditional does not produce `any`'s usual both-branches union once the
+ * checked type is wrapped in a tuple, so it resolves to a single branch like any other type) and
+ * a response inferred as bare `typed()` with nothing to infer from, which resolves to `undefined`
+ * with no shape to validate a handler's return against — the same signal a zero-argument
+ * `contract()` produces for a genuinely response-less route. Neither means "this handler must
+ * return void": it means the declaration did not constrain the response, so the handler is free to
+ * return whatever its route actually sends.
+ */
+export type IsUntypedResponse<T> = 0 extends (1 & T) ? true : [T] extends [undefined] ? true : false
+
+/**
+ * The type a bound handler is allowed to return for a given protocol response.
+ *
+ * A concretely typed or schema-backed `Response` is returned unchanged — the handler must produce
+ * exactly that shape. An untyped one (see `IsUntypedResponse` above) relaxes to `any`: the
+ * declaration made no promise about the response, so nothing here should force a handler bound to
+ * it into returning `void`.
+ */
+export type HandlerResponse<Response> = IsUntypedResponse<Response> extends true ? any : Response
+
+export type MaybePromise<Value> = Value | Promise<Value>
+
+export type BodyProtocol<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { body: OpenValue }
+  ? Protocol : never
+
+export type ParamsProtocol<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { params: object }
+  ? Protocol : never
+
+export type Config = ServerConfig
+
+export type Context = ServerContext<Config>
+
+export interface ContextCarrier<Context> {
+  _ctx?: Context
+}
+
+/** Structural, not `instanceof`: a `BoundEntrypointHandler` crosses no class boundary a runtime check could use. */
+export type AnyBoundHandler = BoundEntrypointHandler<EntrypointProtocolDeclaration>

package/src/types.ts

@@ -1,14 +1,13 @@
 
-import type { InitializedService, Layer } from '@owlmeans/context'
+import type { InitializedService } from '@owlmeans/context'
 import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
 import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'
 import '@fastify/middie/types/index.d.ts'
+import type { MultipartFile } from '@fastify/multipart'
 
 export interface ApiServer extends InitializedService {
   server: FastifyInstance
 
-  layers: [Layer.System]
-
   listen: () => Promise<void>
 }
 
@@ -20,7 +19,42 @@ export interface ApiServerAppend {
   getApiServer: () => ApiServer
 }
 
-export interface Config extends ServerConfig { }
+export type HttpErrorExposure = 'production' | 'development'
+
+export interface HttpErrorsConfig {
+  /** Production is the safe default; development is the only mode that exposes stacks. */
+  exposure?: HttpErrorExposure
+}
+
+export interface HttpConfig {
+  errors?: HttpErrorsConfig
+}
+
+export interface Config extends ServerConfig {
+  http?: HttpConfig
+}
 
 export interface Context<C extends Config = Config> extends ServerContext<C>,
   ApiServerAppend { }
+
+export interface UploadedFile extends MultipartFile { }
+
+export interface ApiPortHoldOptions {
+  /**
+   * The one path answered 200 while the hold is in place — the app's health endpoint, so
+   * whatever supervises the process keeps a conventional liveness answer through the boot.
+   * Everything else answers 503 with the same body. Absent, everything is 503.
+   */
+  okPath?: string
+  /** Body of every answer, evaluated per request so a changing boot phase is reported live. */
+  payload?: () => unknown
+}
+
+export interface ApiPortHold {
+  /**
+   * Free the port for the real server. Awaits the actual close — `listen()` follows immediately,
+   * and a predecessor still bound makes it throw — and force-closes keep-alive sockets, so a
+   * supervisor's own poller cannot hold the release open.
+   */
+  release: () => Promise<void>
+}

package/src/utils/consts.local.ts

@@ -0,0 +1,7 @@
+export const CLIENT_ERROR_FIRST = 400
+
+export const CLIENT_ERROR_LAST = 499
+
+export const SERVER_ERROR_FIRST = 500
+
+export const SERVER_ERROR_LAST = 599

package/src/utils/consts.ts

@@ -0,0 +1 @@
+export const INCIDENT_ID_HEADER = 'X-Incident-ID'

package/src/utils/context/types.ts

@@ -0,0 +1,13 @@
+import type { Config, Context } from '../../types.js'
+
+/** Carries the serving context on one raw request. */
+export interface RequestContextHelper {
+  /** Stores the context on the request. */
+  populateContext: <C extends Config, T extends Context<C>>(context: T) => void
+  /**
+   * The context stored on the request, else `ctx`.
+   *
+   * @throws {SyntaxError} when neither is there
+   */
+  extractContext: <C extends Config, T extends Context<C>>(ctx?: T, location?: string) => T
+}

package/src/utils/context.ts

@@ -1,9 +1,14 @@
 import { assertContext } from '@owlmeans/context'
 import type { Config, Context, Request } from '../types.js'
 import { DEFAULT_ALIAS } from '../consts.js'
+import type { RequestContextHelper } from './context/types.js'
 
-export const populateContext = <C extends Config, T extends Context<C>>(req: Request, context: T): void =>
-  void ((req as any)._ctx = context)
+export const makeRequestContextHelper = (req: Request): RequestContextHelper => {
+  const populateContext = <C extends Config, T extends Context<C>>(context: T): void =>
+    void ((req as any)._ctx = context)
 
-export const extractContext = <C extends Config, T extends Context<C>>(req: Request, ctx?: T, location?: string): T =>
-  assertContext<C, T>((req as any)._ctx ?? ctx, location ?? DEFAULT_ALIAS)
+  const extractContext = <C extends Config, T extends Context<C>>(ctx?: T, location?: string): T =>
+    assertContext<C, T>((req as any)._ctx ?? ctx, location ?? DEFAULT_ALIAS)
+
+  return { populateContext, extractContext }
+}

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
+}