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

package/src/utils/payload.ts

@@ -1,72 +1,54 @@
 import { EntrypointOutcome } from '@owlmeans/entrypoint'
 import type { AbstractResponse, AbstractRequest } from '@owlmeans/entrypoint'
 import type { Request, Response } from '../types.js'
-import { ACCEPTED, CREATED, OK, SERVER_ERROR } from '@owlmeans/api'
-import type { AnySchemaObject } from 'ajv'
+import { ACCEPTED, CREATED, OK } from '@owlmeans/api'
+import { httpErrorHelper } from './error.js'
+import type { PayloadHelper } from './payload/types.js'
 
-export const provideRequest = (alias: string, req: Request, provision?: boolean): AbstractRequest => {
-  provision = provision ?? false
-  return {
-    alias,
-    auth: (req as any)._auth ?? undefined,
-    params: req.params as Record<string, string | number | undefined | null>,
-    body: req.body as Record<string, any>,
-    headers: req.headers,
-    query: req.query as Record<string, string | number | undefined | null>,
-    path: req.url,
-    original: provision ? req : undefined
-  }
-}
-
-/**
- * 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}
- */
-export const executeResponse = <T>(response: AbstractResponse<T>, reply: Response, throwOnError?: boolean): boolean => {
-  if (response.error != null) {
-    if (throwOnError ?? false) {
-      throw response.error
+export const createPayloadHelper = (): PayloadHelper => {
+  const provideRequest = (alias: string, req: Request, provision?: boolean): AbstractRequest => {
+    provision = provision ?? false
+    return {
+      alias,
+      auth: (req as any)._auth ?? undefined,
+      // Resolved once by `authorize` and carried by reference, exactly like `_auth`, so a handler
+      // reached through any path sees the same entity the guard admitted.
+      entity: (req as any)._entity ?? undefined,
+      params: req.params as Record<string, string | number | undefined | null>,
+      body: req.body as Record<string, any>,
+      headers: req.headers,
+      query: req.query as Record<string, string | number | undefined | null>,
+      path: req.url,
+      original: provision ? req : undefined
     }
-    reply.code(SERVER_ERROR).send(response.error.message)
-    return true
-  } else if (response.outcome != null) {
-    switch (response.outcome) {
-      case EntrypointOutcome.Accepted:
-        reply.code(ACCEPTED).send(response.value)
-        break
-      case EntrypointOutcome.Created:
-        reply.code(CREATED).send(response.value)
-        break
-      case EntrypointOutcome.Ok:
-      default:
-        reply.code(OK).send(response.value)
-    }
-    return true
   }
 
-  return false
-}
-
-
-export const fixFormatDates = (schema: AnySchemaObject) => {
-  if (schema.type === 'object') {
-    if (schema.format === 'date-time') {
-      schema.type = 'string'
-      schema.format = 'date-time'
-      if (schema.required != null) {
-        delete schema.required
+  const executeResponse = <T>(response: AbstractResponse<T>, reply: Response, throwOnError?: boolean): boolean => {
+    if (response.error != null) {
+      if (throwOnError ?? false) {
+        throw response.error
+      }
+      httpErrorHelper.handleError(response.error, reply)
+      return true
+    } else if (response.outcome != null) {
+      switch (response.outcome) {
+        case EntrypointOutcome.Accepted:
+          reply.code(ACCEPTED).send(response.value)
+          break
+        case EntrypointOutcome.Created:
+          reply.code(CREATED).send(response.value)
+          break
+        case EntrypointOutcome.Ok:
+        default:
+          reply.code(OK).send(response.value)
       }
-    } else if (schema.properties != null) {
-      schema.properties = Object.fromEntries(
-        Object.entries(schema.properties).map(([key, value]) => [key, fixFormatDates(value as AnySchemaObject)])
-      )
+      return true
     }
+
+    return false
   }
 
-  return schema
+  return { provideRequest, executeResponse }
 }
+
+export const payloadHelper = createPayloadHelper()

package/src/utils/schema.ts

@@ -0,0 +1,23 @@
+import type { AnySchemaObject } from 'ajv'
+
+/**
+ * A request schema Fastify can serve: a `date-time` object becomes a `date-time` string (and loses
+ * its `required` list), recursively through object properties. Mutates and returns `schema`.
+ */
+export const fixFormatDates = (schema: AnySchemaObject): AnySchemaObject => {
+  if (schema.type === 'object') {
+    if (schema.format === 'date-time') {
+      schema.type = 'string'
+      schema.format = 'date-time'
+      if (schema.required != null) {
+        delete schema.required
+      }
+    } else if (schema.properties != null) {
+      schema.properties = Object.fromEntries(
+        Object.entries(schema.properties).map(([key, value]) => [key, fixFormatDates(value as AnySchemaObject)])
+      )
+    }
+  }
+
+  return schema
+}

package/src/utils/server.ts

@@ -1,29 +1,27 @@
-import { AppType } from '@owlmeans/context'
+import { AppType, assertContext } from '@owlmeans/context'
 import type { FastifyReply, FastifyRequest } from 'fastify'
-import { assertContext } from '@owlmeans/context'
 import type { FixerService, ServerEntrypoint } from '@owlmeans/server-entrypoint'
-import type { CommonEntrypoint } from '@owlmeans/entrypoint'
-import type { GateService } from '@owlmeans/entrypoint'
-import { provideResponse } from '@owlmeans/entrypoint'
-import type { ServerContext, ServerConfig } from '@owlmeans/server-context'
+import { type CommonEntrypoint, type GateService, provideResponse } from '@owlmeans/entrypoint'
 import { ResilientError } from '@owlmeans/error'
 import { OK } from '@owlmeans/api'
-import { handleError } from './error.js'
-import { executeResponse, provideRequest } from './payload.js'
+import { logger } from '@owlmeans/log'
+import { httpErrorHelper } from './error.js'
+import { payloadHelper } from './payload.js'
 import { authorize } from './guards.js'
 import { RouteProtocols } from '@owlmeans/route'
+import type { ServerConfig2, ServerContext2 } from './types.local.js'
 
-type Config = ServerConfig
-type Context = ServerContext<Config>
 
-export const canServeModule = (context: Context, module: CommonEntrypoint): module is ServerEntrypoint<unknown> => {
+export const canServeModule = (context: ServerContext2, module: CommonEntrypoint): module is ServerEntrypoint<unknown> => {
   if (module.route.route.type !== AppType.Backend) {
     return false
   }
   if (module.route.route.service != null && module.route.route.service !== context.cfg.service) {
     return false
   }
-  if (module.route.route.protocol === RouteProtocols.SOCKET) {
+  // HTTP serves only its own protocol. Custom transports are handled by their owning packages.
+  if (module.route.route.protocol != null
+    && module.route.route.protocol !== RouteProtocols.WEB) {
     return false
   }
 
@@ -33,20 +31,20 @@ export const canServeModule = (context: Context, module: CommonEntrypoint): modu
 export const createServerHandler = (module: ServerEntrypoint<FastifyRequest>, location: string) =>
   async (req: FastifyRequest, reply: FastifyReply) => {
     // We passed context using fastify request object
-    let context = assertContext<Config, Context>((req as any)._ctx, location)
+    let context = assertContext<ServerConfig2, ServerContext2>((req as any)._ctx, location)
     try {
       const authorized = await authorize(context, module, req, reply)
       context = authorized[0]
       module = authorized[1]
 
       const response = provideResponse(reply)
-      const request = provideRequest(module.alias, req, true)
+      const request = payloadHelper.provideRequest(module.alias, req, true)
 
       const gates = module.getGates()
       for (const [srv, params] of gates) {
         const gate: GateService = context.service(srv)
         await gate.assert(request, response, params)
-        executeResponse(response, reply, true)
+        payloadHelper.executeResponse(response, reply, true)
       }
 
       await module.handle(request, response)
@@ -57,20 +55,17 @@ export const createServerHandler = (module: ServerEntrypoint<FastifyRequest>, lo
       // synchronously right after `reply.send()`. Track the emitted state
       // explicitly instead, and only fall back to a default response when
       // neither `executeResponse` nor the handler itself (hijack) replied.
-      const responded = executeResponse(response, reply, true)
+      const responded = payloadHelper.executeResponse(response, reply, true)
       if (!responded && !reply.sent) {
-        console.warn(`SENDS DEFAULT RESPONSE: ${module.alias}`)
+        logger('http').warn(`SENDS DEFAULT RESPONSE: ${module.alias}`)
         reply.code(OK).send(response.value)
       }
     } catch (error) {
-      console.error(`Error in ${module.alias} (${location})`)
-      console.error(JSON.stringify(error, null, 2))
-      console.error(error)
       if (module.fixer != null) {
         const fixer: FixerService = context.service(module.fixer)
         fixer.handle(reply, ResilientError.ensure(error as Error))
         return
       }
-      handleError(error as Error, reply)
+      httpErrorHelper.handleError(error as Error, reply, httpErrorHelper.errorExposure(context.cfg))
     }
   }

package/src/utils/types.local.ts

@@ -0,0 +1,12 @@
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import type { Config as ApiConfig } from '../types.js'
+
+export type Config = ServerConfig
+
+export interface Context<C extends Config = Config> extends ServerContext<C> { }
+
+export type Severity = 'debug' | 'info' | 'warn' | 'error'
+
+export type ServerConfig2 = ApiConfig
+
+export type ServerContext2 = ServerContext<ServerConfig2>

package/src/utils/types.ts

@@ -0,0 +1,18 @@
+/**
+ * What an error class may declare about the HTTP status it is answered with.
+ *
+ * Structural on purpose: the classes that declare it live in packages that must not depend on an
+ * HTTP server (`@owlmeans/payment`, a product's contract package), so they write a plain
+ * `public static httpStatus = 409` and nothing imports this type.
+ */
+export interface HttpStatusDeclaration {
+  httpStatus?: unknown
+  /** Explicit opt-in for a declared 5xx response. Client-error declarations need no opt-in. */
+  allowServerErrorStatus?: unknown
+}
+
+export interface SerializedHttpError {
+  status: number
+  body: string
+  incidentId: string
+}

package/tests/error-status.spec.ts

@@ -0,0 +1,349 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import Fastify from 'fastify'
+import type { FastifyInstance } from 'fastify'
+import { AuthForbidden, AuthorizationError, AuthUnknown } from '@owlmeans/auth'
+import { ResilientError, SEPARATOR } from '@owlmeans/error'
+import { provideResponse } from '@owlmeans/entrypoint'
+import { httpErrorHelper } from '../src/utils/error.js'
+import { INCIDENT_ID_HEADER } from '../src/utils/consts.js'
+import { payloadHelper } from '../src/utils/payload.js'
+import { AccessError, AuthFailedError } from '../src/errors.js'
+import { DENIAL_KIND_HEADER, ACCESS_DENIED_KIND, apiStatusHelper } from '@owlmeans/api'
+import {
+  MigrationError, MisshapedRecord, RecordExists, RecordUpdateFailed, UnknownRecordError,
+  UnsupportedArgumentError, UnsupportedMethodError,
+} from '@owlmeans/resource'
+
+class OutOfCredit extends ResilientError {
+  public static override typeName = 'ServerApiSpecOutOfCredit'
+  public static httpStatus = 402
+
+  constructor(message: string = 'error') {
+    super(OutOfCredit.typeName, `out-of-credit:${message}`)
+  }
+}
+
+/** Inherits 402 without redeclaring it. */
+class OutOfCreditForStory extends OutOfCredit {
+  public static override typeName = 'ServerApiSpecOutOfCreditForStory'
+
+  constructor() {
+    super('story')
+    this.type = OutOfCreditForStory.typeName
+  }
+}
+
+/** Redeclares its parent's status to a conflict. */
+class Busy extends OutOfCredit {
+  public static override typeName = 'ServerApiSpecBusy'
+  public static override httpStatus = 409
+
+  constructor() {
+    super('busy')
+    this.type = Busy.typeName
+  }
+}
+
+/** An auth refusal that also declares a status: the auth mapping still wins. */
+class DeclaringForbidden extends AuthForbidden {
+  public static override typeName = 'ServerApiSpecDeclaringForbidden'
+  public static httpStatus = 402
+
+  constructor() {
+    super('declaring')
+    this.type = DeclaringForbidden.typeName
+  }
+}
+
+class TemporarilyUnavailable extends ResilientError {
+  public static override typeName = 'ServerApiSpecTemporarilyUnavailable'
+  public static httpStatus = 503
+  public static allowServerErrorStatus = true
+
+  constructor() {
+    super(TemporarilyUnavailable.typeName, 'temporarily-unavailable')
+  }
+}
+
+class Throttled extends ResilientError {
+  public static override typeName = 'ServerApiSpecThrottled'
+  public static httpStatus = 429
+  public readonly retryAfter = 17.2
+
+  constructor() {
+    super(Throttled.typeName, 'throttled')
+  }
+}
+
+const declaring = (typeName: string, httpStatus: unknown) => {
+  class Declaring extends ResilientError {
+    public static override typeName = typeName
+    public static httpStatus = httpStatus
+
+    constructor(message: string = 'error') {
+      super(typeName, message)
+    }
+  }
+  return Declaring
+}
+
+/**
+ * A duplicate module copy of the error family — what a process loading `@owlmeans/error` through
+ * several `node_modules` paths holds: the same registered names, none of the imported classes.
+ */
+class ForeignResilientError extends Error {
+  public static typeName = 'ResilientError'
+  public type: string
+
+  constructor(type: string, message: string) {
+    super(message)
+    this.type = type
+  }
+}
+
+class ForeignAuthFailedError extends ForeignResilientError {
+  public static override typeName = 'AuthFailedError'
+
+  constructor() {
+    super(ForeignAuthFailedError.typeName, 'api:auth:error')
+  }
+}
+
+class ForeignAuthorizationError extends ForeignResilientError {
+  public static override typeName = 'AuthorizationError'
+
+  constructor(message: string = 'error') {
+    super(ForeignAuthorizationError.typeName, `auth:authorization:${message}`)
+  }
+}
+
+class ForeignAuthForbidden extends ForeignAuthorizationError {
+  public static override typeName = 'ForbiddenAuthorizationError'
+
+  constructor(message: string = 'error') {
+    super(`forbidden:${message}`)
+    this.type = ForeignAuthForbidden.typeName
+  }
+}
+
+/** A subclass whose own name embeds nothing of its parent's, like `EntitlementRefusal`. */
+class ForeignEntitlementRefusal extends ForeignAuthForbidden {
+  public static override typeName = 'EntitlementRefusal'
+
+  constructor() {
+    super('entitlement')
+    this.type = ForeignEntitlementRefusal.typeName
+  }
+}
+
+/** A declared refusal no registry of this process knows. */
+class ForeignOutOfCredit extends ForeignResilientError {
+  public static override typeName = 'ServerApiSpecForeignOutOfCredit'
+  public static httpStatus = 402
+
+  constructor() {
+    super(ForeignOutOfCredit.typeName, 'out-of-credit:foreign')
+  }
+}
+
+const typed = (type: string) => Object.assign(new Error('typed'), { type })
+
+ResilientError.registerErrorClass(OutOfCredit)
+ResilientError.registerErrorClass(OutOfCreditForStory)
+ResilientError.registerErrorClass(Busy)
+ResilientError.registerErrorClass(DeclaringForbidden)
+
+let server: FastifyInstance
+let thrown: unknown
+
+beforeAll(async () => {
+  server = Fastify()
+  server.get('/handle', async (_req, reply) => {
+    httpErrorHelper.handleError(thrown as Error, reply)
+    return reply
+  })
+  server.get('/handle-development', async (_req, reply) => {
+    httpErrorHelper.handleError(thrown as Error, reply, 'development')
+    return reply
+  })
+  server.get('/execute', async (_req, reply) => {
+    const response = provideResponse(reply)
+    response.reject(thrown as Error)
+    payloadHelper.executeResponse(response, reply)
+    return reply
+  })
+  await server.ready()
+})
+
+afterAll(async () => {
+  await server.close()
+})
+
+const answer = async (error: unknown, path: string = '/handle') => {
+  thrown = error
+  const reply = await server.inject({ method: 'GET', url: path })
+  return {
+    status: reply.statusCode,
+    body: reply.body,
+    incidentId: reply.headers[INCIDENT_ID_HEADER.toLowerCase()] as string,
+    retryAfter: reply.headers['retry-after'],
+    denialKind: reply.headers[DENIAL_KIND_HEADER.toLowerCase()],
+  }
+}
+
+describe('@owlmeans/server-api — production error exposure', () => {
+  test('returns only an incident id in production and correlates it with the header', async () => {
+    const response = await answer(new Error('private-marker'))
+    expect(response.body).toBe(response.incidentId)
+    expect(response.body).not.toContain('private-marker')
+    expect(response.body).not.toContain(SEPARATOR)
+    expect(response.body).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/)
+  })
+
+  test('includes stacks only under explicit development exposure and safely serializes SyntaxError', async () => {
+    const development = await answer(new Error('development-marker'), '/handle-development')
+    const [type, message, stack, incidentId] = development.body.split(SEPARATOR, 4)
+    expect(type).toBe(ResilientError.typeName)
+    expect(message).toBe('development-marker')
+    expect(stack).toContain('development-marker')
+    expect(incidentId).toBe(development.incidentId)
+
+    const syntax = await answer(new SyntaxError('bad wiring'))
+    expect(syntax.status).toBe(500)
+    expect(syntax.body).toBe(syntax.incidentId)
+    expect(syntax.body).not.toContain('bad wiring')
+
+    expect(httpErrorHelper.errorExposure()).toBe('production')
+    expect(httpErrorHelper.errorExposure({ http: { errors: { exposure: 'development' } } })).toBe('development')
+  })
+})
+
+describe('@owlmeans/server-api — handleError status', () => {
+  test('keeps the auth mappings: forbidden 403, unauthenticated 401', async () => {
+    expect((await answer(new AuthForbidden('x'))).status).toBe(403)
+    expect((await answer(new AccessError())).status).toBe(403)
+    expect((await answer(new AuthorizationError('x'))).status).toBe(401)
+    expect((await answer(new AuthFailedError())).status).toBe(401)
+    expect((await answer(new DeclaringForbidden())).status).toBe(403)
+    expect((await answer(new AuthForbidden('permission'))).denialKind).toBe(ACCESS_DENIED_KIND)
+    expect((await answer(new AccessError())).denialKind).toBe(ACCESS_DENIED_KIND)
+    expect((await answer(new DeclaringForbidden())).denialKind).toBeUndefined()
+    expect((await answer(new ForeignEntitlementRefusal())).denialKind).toBeUndefined()
+  })
+
+  test('honours a 4xx a class declares — inherited, redeclared, or after a marshal hop', async () => {
+    const refused = await answer(new OutOfCredit('create'))
+    expect(refused.status).toBe(402)
+    expect(refused.body).toBe(refused.incidentId)
+
+    expect((await answer(new OutOfCreditForStory())).status).toBe(402)
+    expect((await answer(new Busy())).status).toBe(409)
+    expect((await answer(ResilientError.marshal(new Busy()))).status).toBe(409)
+    expect((await answer(new ForeignOutOfCredit())).status).toBe(402)
+  })
+
+  test('answers 500 for no declaration, or one outside the client-error range', async () => {
+    expect((await answer(new ResilientError('Plain', 'plain'))).status).toBe(500)
+    expect((await answer(new Error('boom'))).status).toBe(500)
+    for (const status of [500, 503, 200, 302, 399, 600, 402.5, '402', null]) {
+      const Declaring = declaring(`ServerApiSpecDeclaring${String(status)}`, status)
+      expect((await answer(new Declaring())).status).toBe(500)
+    }
+    for (const type of ['AuthFailedErrorX', 'NotAuthorizationError', 'Forbidden', 'ResilientError']) {
+      expect((await answer(typed(type))).status).toBe(500)
+      expect((await answer(new ForeignResilientError(type, 'near-miss'))).status).toBe(500)
+    }
+  })
+
+  test('an unknown authentication method or identity answers 400, as thrown and after a marshal hop', async () => {
+    expect((await answer(new AuthUnknown('email-otp'))).status).toBe(400)
+    expect((await answer(ResilientError.marshal(new AuthUnknown('entity')))).status).toBe(400)
+    expect((await answer(new AuthUnknown(), '/execute')).status).toBe(400)
+  })
+
+  test('honours an explicitly exposed 5xx without opening arbitrary server statuses', async () => {
+    expect((await answer(new TemporarilyUnavailable())).status).toBe(503)
+    const Unexposed = declaring('ServerApiSpecUnexposed503', 503)
+    expect((await answer(new Unexposed())).status).toBe(500)
+  })
+
+  test('emits Retry-After for a throttled response', async () => {
+    const response = await answer(new Throttled())
+    expect(response.status).toBe(429)
+    expect(response.retryAfter).toBe('18')
+  })
+
+  test('executeResponse answers a rejected response with the same status', async () => {
+    expect((await answer(new OutOfCredit('create'), '/execute')).status).toBe(402)
+    expect((await answer(new AuthForbidden('x'), '/execute')).status).toBe(403)
+    expect((await answer(new ResilientError('Plain', 'plain'), '/execute')).status).toBe(500)
+  })
+})
+
+describe('@owlmeans/server-api — auth status across a rebuild and duplicate module copies', () => {
+  test('an AuthFailedError answers 401 as thrown and after a marshal round trip', async () => {
+    expect((await answer(new AuthFailedError())).status).toBe(401)
+    expect((await answer(ResilientError.marshal(new AuthFailedError()))).status).toBe(401)
+    expect(httpErrorHelper.errorStatus(ResilientError.ensure(ResilientError.marshal(new AuthFailedError())))).toBe(401)
+    expect((await answer(new AuthFailedError(), '/execute')).status).toBe(401)
+  })
+
+  test('a class from another module copy answers by its registered type name', async () => {
+    // The rebuild alone loses it — the regression this resolution exists for.
+    expect(httpErrorHelper.errorStatus(ResilientError.ensure(new ForeignAuthFailedError()))).toBe(500)
+    expect((await answer(new ForeignAuthFailedError())).status).toBe(401)
+    expect((await answer(new ForeignAuthorizationError())).status).toBe(401)
+    expect((await answer(new ForeignAuthForbidden())).status).toBe(403)
+    expect((await answer(new ForeignAuthForbidden(), '/execute')).status).toBe(403)
+  })
+
+  test('the family is read off the instance type or the constructor chain, 403 before 401', async () => {
+    expect((await answer(typed('AuthFailedError'))).status).toBe(401)
+    expect((await answer(typed('ForbiddenAuthorizationError'))).status).toBe(403)
+    expect((await answer(typed('AccessAuthFailedError'))).status).toBe(403)
+    // Its own type names nothing of the family; only the chain does.
+    expect((await answer(new ForeignEntitlementRefusal())).status).toBe(403)
+  })
+})
+
+describe('@owlmeans/server-api — storage refusals of @owlmeans/resource', () => {
+  test('an absent record answers 404 and a taken id or key 409 — as thrown and after a marshal hop', async () => {
+    expect((await answer(new UnknownRecordError('shelf/3'))).status).toBe(404)
+    expect((await answer(new RecordExists('id-present'))).status).toBe(409)
+    expect((await answer(ResilientError.marshal(new UnknownRecordError('shelf/3')))).status).toBe(404)
+    expect((await answer(ResilientError.marshal(new RecordExists('isbn')))).status).toBe(409)
+    expect((await answer(new UnknownRecordError('shelf/3'), '/execute')).status).toBe(404)
+  })
+
+  test('a storage fault still answers 500', async () => {
+    for (const fault of [
+      new MisshapedRecord('x'), new RecordUpdateFailed('x'), new UnsupportedArgumentError('ttl'),
+      new UnsupportedMethodError('watch'), new MigrationError('x'),
+    ]) {
+      expect([fault.type, (await answer(fault)).status]).toEqual([fault.type, 500])
+    }
+  })
+
+  test('a development body rebuilds into the same class, and the status the client stamps agrees with it', async () => {
+    for (const [error, status] of [
+      [new UnknownRecordError('shelf/3'), 404], [new RecordExists('isbn'), 409],
+    ] as const) {
+      const response = await answer(error, '/handle-development')
+      expect(response.status).toBe(status)
+      // What `@owlmeans/api` does with a non-2xx body carrying the separator.
+      const rebuilt = Object.assign(ResilientError.ensure(response.body, true), { responseStatus: response.status })
+      expect(rebuilt.constructor).toBe(error.constructor)
+      expect(rebuilt.message).toBe(error.message)
+      expect(apiStatusHelper.httpStatusOf(rebuilt)).toBe(status)
+    }
+    const rebuilt = ResilientError.ensure((await answer(new UnknownRecordError('shelf/3'), '/handle-development')).body, true)
+    expect((rebuilt as UnknownRecordError).id).toBe('shelf/3')
+  })
+
+  test('a production body is the incident id alone, under the declared status', async () => {
+    const response = await answer(new UnknownRecordError('shelf/3'))
+    expect(response.status).toBe(404)
+    expect(response.body).toBe(response.incidentId)
+    expect(response.body).not.toContain('shelf')
+  })
+})