@owlmeans/api 0.1.18-rc.5 → 0.1.18-rc.50

package/src/utils/body.ts

@@ -0,0 +1,70 @@
+import qs from 'qs'
+import { RouteMethod } from '@owlmeans/route'
+import { FORM_CONTENT_TYPE } from './consts.local.js'
+import { JSON_CONTENT_TYPE } from './consts.js'
+import type { BodyUtils, RequestBody } from './body/types.js'
+
+export const createBodyUtils = (): BodyUtils => {
+  const contentTypeOf = (headers?: Record<string, unknown>): string | undefined => {
+    const value = Object.entries(headers ?? {}).find(([key]) => key.toLowerCase() === 'content-type')?.[1]
+    if (value == null || value === '') {
+      return undefined
+    }
+    return Array.isArray(value) ? value.join(', ') : `${value}`
+  }
+
+  const isJsonContentType = (type?: string): boolean =>
+    type != null && /^application\/(?:[^\s;]+\+)?json\s*(?:;|$)/i.test(type.trim())
+
+  /** A JSON value no serializer quotes for us: a string, a number or a boolean. */
+  const isScalar = (value: unknown): value is string | number | boolean =>
+    typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+
+  /** Does the entrypoint's body schema declare a string? */
+  const stringContract = (schema?: object): boolean => {
+    const type = (schema as { type?: unknown } | undefined)?.type
+    return (Array.isArray(type) ? type : [type]).includes('string')
+  }
+
+  const parse = (text: string): { json: true, value: unknown } | { json: false } => {
+    try {
+      return { json: true, value: JSON.parse(text) }
+    } catch {
+      return { json: false }
+    }
+  }
+
+  const jsonScalarBody = (body: string | number | boolean, schema?: object): string => {
+    if (typeof body !== 'string') {
+      return JSON.stringify(body)
+    }
+    const parsed = parse(body)
+    const serialized = parsed.json && (!stringContract(schema) || typeof parsed.value === 'string')
+
+    return serialized ? body : JSON.stringify(body)
+  }
+
+  const requestBodyOf = (
+    body: unknown, headers: Record<string, unknown> | undefined, method?: RouteMethod, schema?: object
+  ): RequestBody => {
+    const type = contentTypeOf(headers)
+    if (body != null && type?.includes(FORM_CONTENT_TYPE) === true) {
+      return { data: qs.stringify(body), verbatim: false }
+    }
+    if (!isScalar(body)) {
+      return { data: body, verbatim: false }
+    }
+    if (type == null && method === RouteMethod.POST) {
+      return { data: jsonScalarBody(body, schema), contentType: JSON_CONTENT_TYPE, verbatim: true }
+    }
+    if (isJsonContentType(type)) {
+      return { data: jsonScalarBody(body, schema), verbatim: true }
+    }
+
+    return { data: body, verbatim: false }
+  }
+
+  return { contentTypeOf, isJsonContentType, jsonScalarBody, requestBodyOf }
+}
+
+export const bodyUtils = createBodyUtils()

package/src/utils/consts.local.ts

@@ -0,0 +1 @@
+export const FORM_CONTENT_TYPE = 'application/x-www-form-urlencoded'

package/src/utils/consts.ts

@@ -0,0 +1 @@
+export const JSON_CONTENT_TYPE = 'application/json'

package/src/utils/index.ts

@@ -1,2 +1,3 @@
 
-export * from './handler.js'
+export type * from './response/types.js'
+export * from './response.js'

package/src/utils/response/types.ts

@@ -0,0 +1,15 @@
+import type { AbstractResponse } from '@owlmeans/entrypoint'
+import type { AxiosResponse } from 'axios'
+import type { ApiClientError } from '../../errors.js'
+
+/** Turns an axios answer into the entrypoint reply: a resolved value or a typed failure. */
+export interface ResponseUtils {
+  /** Resolves `reply` with a 2xx answer's value, or rejects it with the failure of any other status. */
+  processResponse: (response: AxiosResponse, reply: AbstractResponse<any>) => void
+  /**
+   * The typed error of a bare status: `ServerCrashedError` (500), `ServerAuthError` (401),
+   * `ApiClientError('forbidden[:<id>]')` (403), `ApiStatusError` (`api:client:status:<n>[:<id>]`)
+   * for every other one.
+   */
+  statusError: (status: number, incidentId?: string) => ApiClientError
+}

package/src/utils/response.ts

@@ -0,0 +1,117 @@
+import { type AbstractResponse, EntrypointOutcome } from '@owlmeans/entrypoint'
+import type { AxiosResponse } from 'axios'
+import {
+  ACCEPTED, CREATED, FINISHED, FORBIDDEN_ERROR, INCIDENT_ID_HEADER, DENIAL_KIND_HEADER,
+  ACCESS_DENIED_KIND, OK, SERVER_ERROR, UNAUTHORIZED_ERROR,
+} from '../consts.js'
+import { ResilientError } from '@owlmeans/error'
+import { ApiClientError, ApiStatusError, ServerAuthError, ServerCrashedError } from '../errors.js'
+import { apiStatusHelper } from '../status/helper.js'
+import type { ResponseStatusCarrier } from '../status/types.js'
+import { logger } from '@owlmeans/log'
+import type { ResponseUtils } from './response/types.js'
+
+export const createResponseUtils = (): ResponseUtils => {
+  const log = logger('api')
+
+  const processResponse = (response: AxiosResponse, reply: AbstractResponse<any>): void => {
+    switch (response.status) {
+      case OK:
+        reply.resolve(response.data, EntrypointOutcome.Ok)
+        return
+      case ACCEPTED:
+        reply.resolve(response.data, EntrypointOutcome.Accepted)
+        return
+      case CREATED:
+        return processEmptyResponse(response, reply, EntrypointOutcome.Created)
+      case FINISHED:
+        return processEmptyResponse(response, reply, EntrypointOutcome.Finished)
+      default:
+        // A refusal is ordinary traffic (401, 403, 409, 428): debug, and never the headers.
+        log.debug('Request answered with a failure', {
+          status: response.status, statusText: response.statusText, url: response.config?.url,
+          incidentId: headerOf(response.headers, INCIDENT_ID_HEADER),
+        })
+
+        reply.reject(failureOf(response))
+    }
+  }
+
+  /**
+   * The error a non-2xx answer rejects with — always carrying the HTTP status and, when the server
+   * sent one, its incident id.
+   *
+   * A development body is the marshaled `ResilientError`: it is rebuilt into its own class and
+   * stamped with `responseStatus`. Anything else — the bare incident id of a production body, a
+   * proxy's HTML, a framework's JSON — becomes the status error of {@link statusError}.
+   */
+  const failureOf = (response: AxiosResponse): Error => {
+    const incidentId = headerOf(response.headers, INCIDENT_ID_HEADER)
+      ?? (apiStatusHelper.isIncidentBody(response.data) ? response.data.trim() : undefined)
+    const denialKind = response.status === FORBIDDEN_ERROR
+      && headerOf(response.headers, DENIAL_KIND_HEADER) === ACCESS_DENIED_KIND
+      ? ACCESS_DENIED_KIND : undefined
+
+    if (typeof response.data === 'string' && response.data.includes(ResilientError.separator)) {
+      try {
+        const error = ResilientError.ensure(response.data, true)
+        error.incidentId ??= incidentId
+        Object.assign(error, {
+          responseStatus: response.status, denialKind,
+        } satisfies ResponseStatusCarrier)
+
+        return error
+      } catch {
+        log.warn('Server returned an unrecognizable text error', { status: response.status, body: response.data })
+      }
+    }
+
+    return Object.assign(statusError(response.status, incidentId), { denialKind })
+  }
+
+  /**
+   * The typed error of a bare status: `ServerCrashedError` (500), `ServerAuthError` (401),
+   * `ApiClientError('forbidden[:<id>]')` (403), `ApiStatusError` (`api:client:status:<n>[:<id>]`)
+   * for every other one.
+   */
+  const statusError = (status: number, incidentId?: string): ApiClientError => {
+    const error = status === SERVER_ERROR ? new ServerCrashedError(incidentId)
+      : status === UNAUTHORIZED_ERROR ? new ServerAuthError(incidentId)
+        : status === FORBIDDEN_ERROR ? new ApiClientError(incidentId != null ? `forbidden:${incidentId}` : 'forbidden')
+          : new ApiStatusError(status, incidentId)
+    if (incidentId != null) {
+      error.incidentId = incidentId
+    }
+
+    return Object.assign(error, { responseStatus: status } satisfies ResponseStatusCarrier)
+  }
+
+  /** One response header, from an `AxiosHeaders` instance or a plain header object alike. */
+  const headerOf = (headers: unknown, name: string): string | undefined => {
+    if (headers == null || typeof headers !== 'object') {
+      return undefined
+    }
+    const get = (headers as { get?: unknown }).get
+    const viaGet = typeof get === 'function' ? get.call(headers, name) : undefined
+    const value = viaGet ?? Object.entries(headers).find(([key]) => key.toLowerCase() === name.toLowerCase())?.[1]
+    const first = Array.isArray(value) ? value[0] : value
+
+    return typeof first === 'string' && first.trim() !== '' ? first.trim() : undefined
+  }
+
+  const processEmptyResponse = (response: AxiosResponse, reply: AbstractResponse<any>, outcome: EntrypointOutcome): void => {
+    if (response.data != null && response.data != '') {
+      reply.resolve(response.data, outcome)
+      return
+    }
+    if (response.headers.toJSON != null && typeof response.headers.toJSON === 'function') {
+      reply.resolve(response.headers.toJSON(), outcome)
+      return
+    }
+    reply.resolve(response.headers, outcome)
+  }
+
+  return { processResponse, statusError }
+}
+
+export const responseUtils = createResponseUtils()

package/tests/body.spec.ts

@@ -0,0 +1,124 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { provideResponse, type AbstractRequest } from '@owlmeans/entrypoint'
+import { RouteMethod } from '@owlmeans/route'
+import { createApiService } from '../src/service.js'
+import { bodyUtils } from '../src/utils/body.js'
+
+const STRING = { type: 'string' }
+
+describe('what a request body becomes', () => {
+  test('a scalar on a POST without a content type is JSON text', () => {
+    expect(bodyUtils.requestBodyOf('abc', {}, RouteMethod.POST)).toEqual({ data: '"abc"', contentType: 'application/json', verbatim: true })
+    expect(bodyUtils.requestBodyOf('', {}, RouteMethod.POST).data).toBe('""')
+    expect(bodyUtils.requestBodyOf(5, {}, RouteMethod.POST).data).toBe('5')
+    expect(bodyUtils.requestBodyOf(0, {}, RouteMethod.POST).data).toBe('0')
+    expect(bodyUtils.requestBodyOf(true, {}, RouteMethod.POST).data).toBe('true')
+    expect(bodyUtils.requestBodyOf(false, {}, RouteMethod.POST).data).toBe('false')
+  })
+
+  test('a scalar under an explicit JSON content type is JSON text, on any method', () => {
+    expect(bodyUtils.requestBodyOf('abc', { 'Content-Type': 'application/json; charset=utf-8' }, RouteMethod.PUT))
+      .toEqual({ data: '"abc"', verbatim: true })
+    expect(bodyUtils.requestBodyOf(7, { 'content-type': 'application/merge-patch+json' }, RouteMethod.PATCH).data).toBe('7')
+  })
+
+  test('already-serialized JSON text is sent as it is', () => {
+    expect(bodyUtils.requestBodyOf('{"a":1}', {}, RouteMethod.POST).data).toBe('{"a":1}')
+    expect(bodyUtils.requestBodyOf('[1,2]', {}, RouteMethod.POST).data).toBe('[1,2]')
+    expect(bodyUtils.requestBodyOf('"abc"', {}, RouteMethod.POST).data).toBe('"abc"')
+    expect(bodyUtils.requestBodyOf('"abc"', {}, RouteMethod.POST, STRING).data).toBe('"abc"')
+  })
+
+  test('under a string body schema, JSON-looking text is the string the caller means', () => {
+    expect(bodyUtils.jsonScalarBody('123', STRING)).toBe('"123"')
+    expect(bodyUtils.jsonScalarBody('true', STRING)).toBe('"true"')
+    expect(bodyUtils.jsonScalarBody('null', { type: ['string', 'null'] })).toBe('"null"')
+    expect(bodyUtils.jsonScalarBody('{"a":1}', STRING)).toBe('"{\\"a\\":1}"')
+    expect(bodyUtils.jsonScalarBody('123', { type: 'number' })).toBe('123')
+  })
+
+  test('objects, arrays and everything outside JSON behave as before', () => {
+    const object = { a: 1 }
+    expect(bodyUtils.requestBodyOf(object, {}, RouteMethod.POST)).toEqual({ data: object, verbatim: false })
+    expect(bodyUtils.requestBodyOf([1], {}, RouteMethod.POST)).toEqual({ data: [1], verbatim: false })
+    expect(bodyUtils.requestBodyOf(undefined, {}, RouteMethod.POST)).toEqual({ data: undefined, verbatim: false })
+    expect(bodyUtils.requestBodyOf('abc', { 'content-type': 'text/plain' }, RouteMethod.POST)).toEqual({ data: 'abc', verbatim: false })
+    expect(bodyUtils.requestBodyOf('abc', {}, RouteMethod.PUT)).toEqual({ data: 'abc', verbatim: false })
+    expect(bodyUtils.requestBodyOf({ a: '1', b: ['x'] }, { 'content-type': 'application/x-www-form-urlencoded' }, RouteMethod.POST).data)
+      .toBe('a=1&b%5B0%5D=x')
+  })
+
+  test('the content-type header is read whatever its case', () => {
+    expect(bodyUtils.contentTypeOf({ 'CONTENT-TYPE': 'application/json' })).toBe('application/json')
+    expect(bodyUtils.contentTypeOf({ accept: 'application/json' })).toBeUndefined()
+    expect(bodyUtils.isJsonContentType('application/vnd.api+json')).toBe(true)
+    expect(bodyUtils.isJsonContentType('application/jsonp')).toBe(false)
+    expect(bodyUtils.isJsonContentType('text/plain')).toBe(false)
+  })
+})
+
+/**
+ * The real client over real HTTP: an echo server answers the bytes and the content type it
+ * received, so what a Fastify JSON parser would read is exactly what is asserted here.
+ */
+describe('the API client on the wire', () => {
+  let server: ReturnType<typeof Bun.serve>
+
+  beforeAll(() => {
+    server = Bun.serve({
+      port: 0,
+      fetch: async request => Response.json({ type: request.headers.get('content-type'), raw: await request.text() }),
+    })
+  })
+
+  afterAll(() => { server.stop(true) })
+
+  const send = async (
+    body: unknown, opts: { method?: RouteMethod, headers?: Record<string, string>, schema?: object } = {}
+  ): Promise<{ type: string | null, raw: string }> => {
+    const client = createApiService('test-client')
+    client.ctx = {
+      cfg: { service: 'api-tests', security: { unsecure: true }, services: {} },
+      entrypoint: () => ({
+        alias: 'echo',
+        route: { route: { method: opts.method ?? RouteMethod.POST } },
+        filter: opts.schema != null ? { body: opts.schema } : undefined,
+        path: () => '/echo',
+        address: () => ({ host: '127.0.0.1', port: server.port, secure: false }),
+      }),
+      hasService: () => false,
+    } as never
+    const reply = provideResponse<{ type: string | null, raw: string }>()
+    const request = { alias: 'echo', params: {}, query: {}, headers: opts.headers ?? {}, body, path: '/echo' } as AbstractRequest
+    await client.handler(request, reply)
+    if (reply.error != null) {
+      throw reply.error
+    }
+    return reply.value!
+  }
+
+  test('a bare string, number or boolean arrives as valid JSON of the same value', async () => {
+    for (const value of ['abc', '', 'a "quoted" word', 42, 0, true, false]) {
+      const received = await send(value)
+      expect(received.type).toStartWith('application/json')
+      expect(JSON.parse(received.raw)).toEqual(value)
+    }
+  })
+
+  test('a string contract carries JSON-looking text as a string', async () => {
+    expect(JSON.parse((await send('123', { schema: STRING })).raw)).toBe('123')
+  })
+
+  test('objects, arrays and serialized text arrive as before', async () => {
+    expect(await send({ a: 1 })).toEqual({ type: expect.stringContaining('application/json'), raw: '{"a":1}' })
+    expect((await send(['x'])).raw).toBe('["x"]')
+    expect((await send('{"a":1}')).raw).toBe('{"a":1}')
+    expect(await send('plain', { headers: { 'content-type': 'text/plain' } })).toEqual({ type: 'text/plain', raw: 'plain' })
+  })
+
+  test('the caller\'s headers are not rewritten', async () => {
+    const headers: Record<string, string> = {}
+    await send('abc', { headers })
+    expect(headers).toEqual({})
+  })
+})

package/tests/handler.spec.ts

@@ -0,0 +1,229 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { AxiosHeaders } from 'axios'
+import type { AxiosResponse } from 'axios'
+import type { AbstractResponse } from '@owlmeans/entrypoint'
+import { EntrypointOutcome } from '@owlmeans/entrypoint'
+import { ResilientError } from '@owlmeans/error'
+import { RecordExists, UnknownRecordError } from '@owlmeans/resource'
+import {
+  ApiClientError, ApiStatusError, ServerAuthError, ServerCrashedError, apiStatusHelper,
+  INCIDENT_ID_HEADER,
+  DENIAL_KIND_HEADER, ACCESS_DENIED_KIND,
+} from '../src/index.js'
+import { responseUtils } from '../src/utils/response.js'
+import * as statusModule from '../src/status/index.js'
+
+const INCIDENT = '6f1c1a52-8a0e-4f5e-9a7c-1f2d3e4c5b6a'
+
+class ConsentRequired extends ResilientError {
+  public static override typeName = 'ApiSpecConsentRequired'
+  public static httpStatus = 428
+
+  constructor(message: string = 'error') {
+    super(ConsentRequired.typeName, `spec:consent-required:${message}`)
+  }
+}
+ResilientError.registerErrorClass(ConsentRequired)
+
+class Unavailable extends ResilientError {
+  public static override typeName = 'ApiSpecUnavailable'
+  public static httpStatus = 503
+
+  constructor(message: string = 'error') {
+    super(Unavailable.typeName, message)
+  }
+}
+
+const respond = (
+  statusCode: number, data: unknown, headers: Record<string, string> | AxiosHeaders = {}
+): AbstractResponse<unknown> => {
+  const reply: AbstractResponse<unknown> = {
+    resolve: (value, outcome) => { reply.value = value; reply.outcome = outcome },
+    reject: error => { reply.error = error },
+  }
+  responseUtils.processResponse({
+    status: statusCode, statusText: '', data, headers, config: { url: '/spec' },
+  } as unknown as AxiosResponse, reply)
+
+  return reply
+}
+
+const quiet = console.error
+beforeAll(() => { console.error = () => {} })
+afterAll(() => { console.error = quiet })
+
+describe('2xx', () => {
+  test('resolve exactly as before', () => {
+    expect(respond(200, { ok: true })).toMatchObject({ value: { ok: true }, outcome: EntrypointOutcome.Ok })
+    expect(respond(202, 'queued')).toMatchObject({ value: 'queued', outcome: EntrypointOutcome.Accepted })
+    expect(respond(204, '', { 'x-a': '1' })).toMatchObject({ value: { 'x-a': '1' }, outcome: EntrypointOutcome.Finished })
+  })
+})
+
+describe('a production incident body keeps its status and incident id', () => {
+  test('only a labelled 403 is an auth/IAM denial', () => {
+    const denied = respond(403, INCIDENT, { [DENIAL_KIND_HEADER]: ACCESS_DENIED_KIND }).error
+    expect(statusModule.apiStatusHelper.isAccessDenied(denied)).toBe(true)
+    expect(statusModule.apiStatusHelper.isAccessDenied(respond(403, INCIDENT).error)).toBe(false)
+    expect(statusModule.apiStatusHelper.isAccessDenied(respond(401, INCIDENT, { [DENIAL_KIND_HEADER]: ACCESS_DENIED_KIND }).error)).toBe(false)
+  })
+  test('428 with the header becomes ApiStatusError', () => {
+    const { error } = respond(428, INCIDENT, { [INCIDENT_ID_HEADER.toLowerCase()]: INCIDENT })
+    expect(error).toBeInstanceOf(ApiStatusError)
+    expect(error!.message).toBe(`api:client:status:428:${INCIDENT}`)
+    expect(apiStatusHelper.httpStatusOf(error)).toBe(428)
+    expect(apiStatusHelper.incidentIdOf(error)).toBe(INCIDENT)
+    expect((error as ApiStatusError).status).toBe(428)
+  })
+
+  test('the header is read from AxiosHeaders too, and the body alone suffices', () => {
+    const headers = new AxiosHeaders({ [INCIDENT_ID_HEADER]: INCIDENT })
+    expect(apiStatusHelper.incidentIdOf(respond(409, 'x', headers).error)).toBe(INCIDENT)
+    expect(apiStatusHelper.incidentIdOf(respond(402, INCIDENT).error)).toBe(INCIDENT)
+    expect(apiStatusHelper.httpStatusOf(respond(402, INCIDENT).error)).toBe(402)
+  })
+
+  test('500, 401 and 403 keep their classes and markers', () => {
+    const crashed = respond(500, INCIDENT).error
+    expect(crashed).toBeInstanceOf(ServerCrashedError)
+    expect(crashed!.message).toBe(`api:client:crashed:${INCIDENT}`)
+    expect(apiStatusHelper.httpStatusOf(crashed)).toBe(500)
+
+    const auth = respond(401, INCIDENT).error
+    expect(auth).toBeInstanceOf(ServerAuthError)
+    expect(auth!.message).toBe(`api:client:auth:${INCIDENT}`)
+    expect(apiStatusHelper.httpStatusOf(auth)).toBe(401)
+
+    const forbidden = respond(403, INCIDENT).error
+    expect(forbidden).toBeInstanceOf(ApiClientError)
+    expect(forbidden).not.toBeInstanceOf(ApiStatusError)
+    expect(forbidden!.message).toBe(`api:client:forbidden:${INCIDENT}`)
+    expect(apiStatusHelper.httpStatusOf(forbidden)).toBe(403)
+  })
+
+  test('without an incident id the markers stay as before', () => {
+    expect(responseUtils.statusError(500).message).toBe('api:client:crashed:error')
+    expect(responseUtils.statusError(403).message).toBe('api:client:forbidden')
+    expect(apiStatusHelper.incidentIdOf(responseUtils.statusError(500))).toBeNull()
+    expect(responseUtils.statusError(418).message).toBe('api:client:status:418')
+  })
+
+  test('a proxy HTML page or framework JSON becomes a status error', () => {
+    const html = respond(502, '<html><body>Bad Gateway</body></html>').error
+    expect(html).toBeInstanceOf(ApiStatusError)
+    expect(apiStatusHelper.httpStatusOf(html)).toBe(502)
+    expect(apiStatusHelper.incidentIdOf(html)).toBeNull()
+
+    const json = respond(400, { statusCode: 400, error: 'Bad Request', message: 'body/x' }).error
+    expect(json).toBeInstanceOf(ApiStatusError)
+    expect(apiStatusHelper.httpStatusOf(json)).toBe(400)
+  })
+
+  test('no class declares a static httpStatus, so a rethrow upstream stays 500', () => {
+    for (const error of [responseUtils.statusError(428), responseUtils.statusError(500), responseUtils.statusError(401), responseUtils.statusError(403)]) {
+      expect((error.constructor as { httpStatus?: unknown }).httpStatus).toBeUndefined()
+    }
+  })
+})
+
+describe('a development body stays its typed class', () => {
+  test('rebuilt with responseStatus and incident id', () => {
+    const body = ResilientError.marshal(new ConsentRequired('2'), { includeStack: true, incidentId: INCIDENT }).message
+    const { error } = respond(428, body, { [INCIDENT_ID_HEADER]: INCIDENT })
+    expect(error).toBeInstanceOf(ConsentRequired)
+    expect(error!.message).toBe('spec:consent-required:2')
+    expect((error as { responseStatus?: number }).responseStatus).toBe(428)
+    expect(apiStatusHelper.httpStatusOf(error)).toBe(428)
+    expect(apiStatusHelper.incidentIdOf(error)).toBe(INCIDENT)
+  })
+
+  test('a typed api error keeps its marker fields', () => {
+    const body = ResilientError.marshal(new ApiStatusError(409, INCIDENT)).message
+    const error = respond(409, body).error as ApiStatusError
+    expect(error).toBeInstanceOf(ApiStatusError)
+    expect(error.status).toBe(409)
+    expect(error.incidentId).toBe(INCIDENT)
+  })
+
+  test('a storage refusal (404 absent record, 409 taken key) rebuilds into its own class', () => {
+    for (const [refusal, code] of [
+      [new UnknownRecordError('shelf/3'), 404], [new RecordExists('isbn'), 409],
+    ] as const) {
+      const body = ResilientError.marshal(refusal, { includeStack: true, incidentId: INCIDENT }).message
+      const { error } = respond(code, body, { [INCIDENT_ID_HEADER]: INCIDENT })
+      expect(error!.constructor).toBe(refusal.constructor)
+      expect(error!.message).toBe(refusal.message)
+      expect(apiStatusHelper.httpStatusOf(error)).toBe(code)
+      expect(apiStatusHelper.incidentIdOf(error)).toBe(INCIDENT)
+    }
+    const body = ResilientError.marshal(new UnknownRecordError('shelf/3')).message
+    expect((respond(404, body).error as UnknownRecordError).id).toBe('shelf/3')
+  })
+
+  test('a class this process never registered still answers the status the server sent', () => {
+    const body = `ApiSpecUnregisteredRefusal${ResilientError.separator}spec:unregistered:x`
+    const { error } = respond(404, body, { [INCIDENT_ID_HEADER]: INCIDENT })
+    expect(error).not.toBeInstanceOf(ServerCrashedError)
+    expect(apiStatusHelper.httpStatusOf(error)).toBe(404)
+    expect(apiStatusHelper.incidentIdOf(error)).toBe(INCIDENT)
+  })
+})
+
+describe('a production body of a storage refusal keeps the declared status', () => {
+  test('404 and 409 become status errors, not a crash', () => {
+    for (const code of [404, 409]) {
+      const { error } = respond(code, INCIDENT)
+      expect(error).toBeInstanceOf(ApiStatusError)
+      expect(error).not.toBeInstanceOf(ServerCrashedError)
+      expect(error!.message).toBe(`api:client:status:${code}:${INCIDENT}`)
+      expect(apiStatusHelper.httpStatusOf(error)).toBe(code)
+    }
+  })
+})
+
+describe('marshal round trips', () => {
+  const roundTrip = (error: Error): ResilientError => ResilientError.ensure(ResilientError.marshal(error))
+
+  test('keep status and incident id of every client error', () => {
+    const cases: Array<[ApiClientError, number]> = [
+      [new ApiStatusError(428, INCIDENT), 428],
+      [new ServerCrashedError(INCIDENT), 500],
+      [new ServerAuthError(INCIDENT), 401],
+      [new ApiClientError(`forbidden:${INCIDENT}`), 403],
+    ]
+    for (const [error, code] of cases) {
+      const back = roundTrip(error)
+      expect(back.constructor).toBe(error.constructor)
+      expect((back as ApiClientError).status).toBe(code)
+      expect(apiStatusHelper.httpStatusOf(back)).toBe(code)
+      expect(apiStatusHelper.incidentIdOf(back)).toBe(INCIDENT)
+    }
+  })
+
+  test('a legacy bare-status marker still reads', () => {
+    expect(apiStatusHelper.httpStatusOf(new ApiClientError('404'))).toBe(404)
+  })
+})
+
+describe('./status', () => {
+  test('a declared static 428 answers without any marker; an undeclared 5xx does not', () => {
+    expect(statusModule.apiStatusHelper.httpStatusOf(new ConsentRequired())).toBe(428)
+    expect(statusModule.apiStatusHelper.httpStatusOf(new Unavailable())).toBeNull()
+    expect(statusModule.apiStatusHelper.httpStatusOf(new Error('plain'))).toBeNull()
+    expect(statusModule.apiStatusHelper.httpStatusOf(null)).toBeNull()
+  })
+
+  test('reads a marker from a plain error message or a type', () => {
+    expect(statusModule.apiStatusHelper.httpStatusOf(new Error(`${statusModule.API_STATUS_MARKER}428:${INCIDENT}`))).toBe(428)
+    expect(statusModule.apiStatusHelper.httpStatusOf({ type: 'api:client:auth:error' })).toBe(401)
+    expect(statusModule.apiStatusHelper.incidentIdOf(new Error(`api:client:crashed:${INCIDENT}`))).toBe(INCIDENT)
+  })
+
+  test('isIncidentBody accepts a bare incident UUID only', () => {
+    expect(statusModule.apiStatusHelper.isIncidentBody(INCIDENT)).toBe(true)
+    expect(statusModule.apiStatusHelper.isIncidentBody(`${INCIDENT}\n`)).toBe(true)
+    expect(statusModule.apiStatusHelper.isIncidentBody('Unauthorized')).toBe(false)
+    expect(statusModule.apiStatusHelper.isIncidentBody(`ApiError|||api:x|||${INCIDENT}`)).toBe(false)
+    expect(statusModule.apiStatusHelper.isIncidentBody({ id: INCIDENT })).toBe(false)
+  })
+})

package/tests/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json"
+  ],
+  "compilerOptions": {
+    "types": ["bun"],
+    "rootDir": "../",
+    "noEmit": true
+  },
+  "include": ["./**/*", "../src/**/*"]
+}

package/tsconfig.json

@@ -6,5 +6,5 @@
     "rootDir": "./src/",
     "outDir": "./build/"
   },
-  "exclude": ["./dist/**/*", "./build/**/*", "./*.ts"]
+  "exclude": ["./dist/**/*", "./build/**/*", "./*.ts", "./tests/**/*"]
 }

package/src/utils/handler.ts

@@ -1,61 +0,0 @@
-import type { AbstractResponse } from '@owlmeans/entrypoint'
-import { EntrypointOutcome } from '@owlmeans/entrypoint'
-import type { AxiosResponse } from 'axios'
-import { ACCEPTED, CREATED, FINISHED, FORBIDDEN_ERROR, OK, SERVER_ERROR, UNAUTHORIZED_ERROR } from '../consts.js'
-import { ResilientError } from '@owlmeans/error'
-import { ApiClientError, ServerAuthError, ServerCrashedError } from '../errors.js'
-
-export const processResponse = (response: AxiosResponse, reply: AbstractResponse<any>) => {
-  switch (response.status) {
-    case OK:
-      reply.resolve(response.data, EntrypointOutcome.Ok)
-      return
-    case ACCEPTED:
-      reply.resolve(response.data, EntrypointOutcome.Accepted)
-      return
-    case CREATED:
-      return processEmptyResponse(response, reply, EntrypointOutcome.Created)
-    case FINISHED:
-      return processEmptyResponse(response, reply, EntrypointOutcome.Finished)
-    default:
-
-      console.error(response.status, response.statusText)
-      console.error(response.config.url, response.headers)
-      console.error(response.data)
-
-      try {
-        if (typeof response.data === 'string') {
-          reply.reject(ResilientError.ensure(response.data, true))
-          return
-        }
-      } catch {
-        console.error(`Server returned an unrecognizable text error: ${response.status} ${response.data}`)
-      }
-      switch (response.status) {
-        case SERVER_ERROR:
-          reply.reject(new ServerCrashedError())
-          return
-        case UNAUTHORIZED_ERROR:
-          reply.reject(new ServerAuthError())
-          return
-        case FORBIDDEN_ERROR:
-          reply.reject(new ApiClientError('forbidden'))
-          return
-        default:
-          reply.reject(new ApiClientError(`${response.status}`))
-          return
-      }
-  }
-}
-
-const processEmptyResponse = (response: AxiosResponse, reply: AbstractResponse<any>, outcome: EntrypointOutcome) => {
-  if (response.data != null && response.data != '') {
-    reply.resolve(response.data, outcome)
-    return
-  }
-  if (response.headers.toJSON != null && typeof response.headers.toJSON === 'function') {
-    reply.resolve(response.headers.toJSON(), outcome)
-    return
-  }
-  reply.resolve(response.headers, outcome)
-}