@owlmeans/api 0.1.18-rc.4 → 0.1.18-rc.41

package/src/utils/handler.ts

@@ -1,9 +1,14 @@
 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 {
+  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, ServerAuthError, ServerCrashedError } from '../errors.js'
+import { ApiClientError, ApiStatusError, ServerAuthError, ServerCrashedError } from '../errors.js'
+import { isIncidentBody } from '../status/index.js'
+import type { ResponseStatusCarrier } from '../status/index.js'
 
 export const processResponse = (response: AxiosResponse, reply: AbstractResponse<any>) => {
   switch (response.status) {
@@ -20,34 +25,75 @@ export const processResponse = (response: AxiosResponse, reply: AbstractResponse
     default:
 
       console.error(response.status, response.statusText)
-      console.error(response.config.url, response.headers)
+      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
-      }
+      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)
+    ?? (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 {
+      console.error(`Server returned an unrecognizable text error: ${response.status} ${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.
+ */
+export 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) => {
   if (response.data != null && response.data != '') {
     reply.resolve(response.data, outcome)

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, httpStatusOf, incidentIdOf,
+  INCIDENT_ID_HEADER,
+  DENIAL_KIND_HEADER, ACCESS_DENIED_KIND,
+} from '../src/index.js'
+import { processResponse, statusError } from '../src/utils/handler.js'
+import * as status 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 },
+  }
+  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(status.isAccessDenied(denied)).toBe(true)
+    expect(status.isAccessDenied(respond(403, INCIDENT).error)).toBe(false)
+    expect(status.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(httpStatusOf(error)).toBe(428)
+    expect(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(incidentIdOf(respond(409, 'x', headers).error)).toBe(INCIDENT)
+    expect(incidentIdOf(respond(402, INCIDENT).error)).toBe(INCIDENT)
+    expect(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(httpStatusOf(crashed)).toBe(500)
+
+    const auth = respond(401, INCIDENT).error
+    expect(auth).toBeInstanceOf(ServerAuthError)
+    expect(auth!.message).toBe(`api:client:auth:${INCIDENT}`)
+    expect(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(httpStatusOf(forbidden)).toBe(403)
+  })
+
+  test('without an incident id the markers stay as before', () => {
+    expect(statusError(500).message).toBe('api:client:crashed:error')
+    expect(statusError(403).message).toBe('api:client:forbidden')
+    expect(incidentIdOf(statusError(500))).toBeNull()
+    expect(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(httpStatusOf(html)).toBe(502)
+    expect(incidentIdOf(html)).toBeNull()
+
+    const json = respond(400, { statusCode: 400, error: 'Bad Request', message: 'body/x' }).error
+    expect(json).toBeInstanceOf(ApiStatusError)
+    expect(httpStatusOf(json)).toBe(400)
+  })
+
+  test('no class declares a static httpStatus, so a rethrow upstream stays 500', () => {
+    for (const error of [statusError(428), statusError(500), statusError(401), 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(httpStatusOf(error)).toBe(428)
+    expect(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(httpStatusOf(error)).toBe(code)
+      expect(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(httpStatusOf(error)).toBe(404)
+    expect(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(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(httpStatusOf(back)).toBe(code)
+      expect(incidentIdOf(back)).toBe(INCIDENT)
+    }
+  })
+
+  test('a legacy bare-status marker still reads', () => {
+    expect(httpStatusOf(new ApiClientError('404'))).toBe(404)
+  })
+})
+
+describe('./status', () => {
+  test('a declared static 428 answers without any marker; an undeclared 5xx does not', () => {
+    expect(status.httpStatusOf(new ConsentRequired())).toBe(428)
+    expect(status.httpStatusOf(new Unavailable())).toBeNull()
+    expect(status.httpStatusOf(new Error('plain'))).toBeNull()
+    expect(status.httpStatusOf(null)).toBeNull()
+  })
+
+  test('reads a marker from a plain error message or a type', () => {
+    expect(status.httpStatusOf(new Error(`${status.API_STATUS_MARKER}428:${INCIDENT}`))).toBe(428)
+    expect(status.httpStatusOf({ type: 'api:client:auth:error' })).toBe(401)
+    expect(status.incidentIdOf(new Error(`api:client:crashed:${INCIDENT}`))).toBe(INCIDENT)
+  })
+
+  test('isIncidentBody accepts a bare incident UUID only', () => {
+    expect(status.isIncidentBody(INCIDENT)).toBe(true)
+    expect(status.isIncidentBody(`${INCIDENT}\n`)).toBe(true)
+    expect(status.isIncidentBody('Unauthorized')).toBe(false)
+    expect(status.isIncidentBody(`ApiError|||api:x|||${INCIDENT}`)).toBe(false)
+    expect(status.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/**/*"]
 }