@owlmeans/api 0.1.18-rc.8 → 0.1.18

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