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

package/tests/handlers.spec.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from 'bun:test'
+import type { EntrypointProtocolDeclaration } from '@owlmeans/entrypoint'
+import { handlers } from '../src/protocol.js'
+import { HandlerMisconfiguredError } from '../src/errors.js'
+import { addLogPlugin, memoryPlugin, removeLogPlugin } from '@owlmeans/log'
+
+/**
+ * A protocol-bound implementation is run with the smallest binding context the transport needs —
+ * same pattern as `@owlmeans/server-auth-token`'s own `handlers.spec.ts`.
+ */
+const invoke = async (handler: any, context: any, req: any = {}): Promise<any> => {
+  const res: any = { resolve: (value: unknown) => { res.value = value }, reject: (e: Error) => { res.error = e } }
+  await handler.bind({ ref: { ctx: context } })(req, res)
+  if (res.error != null) throw res.error
+
+  return res.value
+}
+
+const protocolFor = (alias: string): EntrypointProtocolDeclaration =>
+  ({ alias } as unknown as EntrypointProtocolDeclaration)
+
+const context = { alias: 'test-context' } as any
+const api = handlers<any>()
+
+describe('@owlmeans/server-api — handlers() wrap-once tolerance', () => {
+  test('a plain function is wrapped once and called with the context', async () => {
+    const protocol = protocolFor('api.thing.plain')
+    const handler = api.request(protocol, async (_req: any, ctx: any) => ({ ok: true, ctx }))
+
+    const result = await invoke(handler, context, {})
+    expect(result).toEqual({ ok: true, ctx: context })
+  })
+
+  test('a handler already bound to the SAME protocol is returned unchanged by body/params/request and still answers', async () => {
+    for (const method of ['body', 'params', 'request'] as const) {
+      const protocol = protocolFor(`api.thing.${method}`)
+      const bound = api.request(protocol, async () => ({ from: method }))
+
+      const wrapped = (api as any)[method](protocol, bound)
+      expect(wrapped).toBe(bound)
+
+      const result = await invoke(wrapped, context, {})
+      expect(result).toEqual({ from: method })
+    }
+  })
+
+  test('a handler bound to a DIFFERENT protocol answers with HandlerMisconfiguredError', async () => {
+    const protocolA = protocolFor('api.thing.mismatch-a')
+    const protocolB = protocolFor('api.thing.mismatch-b')
+    const boundToA = api.request(protocolA, async () => ({ from: 'a' }))
+
+    const wrapped = api.request(protocolB, boundToA as any)
+    expect(wrapped).not.toBe(boundToA)
+    await expect(invoke(wrapped, context, {})).rejects.toThrow(HandlerMisconfiguredError)
+  })
+
+  test('a value that is neither a function nor a bound handler answers with HandlerMisconfiguredError', async () => {
+    const protocol = protocolFor('api.thing.not-a-function')
+    const wrapped = api.request(protocol, { not: 'a function' } as any)
+
+    await expect(invoke(wrapped, context, {})).rejects.toThrow(HandlerMisconfiguredError)
+  })
+
+  test('the double-wrap warning fires once per alias, not once per call', async () => {
+    const protocol = protocolFor('api.thing.warn-once')
+    const bound = api.request(protocol, async () => 'ok')
+
+    const memory = memoryPlugin('handlers-warn')
+    addLogPlugin(memory)
+    try {
+      // Each call is a deliberate double wrap — the exact shape `tsc` rejects at the real call
+      // site (TS2345) — so it is exercised here through `any`, the same way `body`/`params`
+      // are reached dynamically above.
+      (api as any).request(protocol, bound);
+      (api as any).body(protocol, bound);
+      (api as any).params(protocol, bound)
+    } finally {
+      removeLogPlugin('handlers-warn')
+    }
+
+    expect(memory.records.filter(record => record.level === 'warn').length).toBe(1)
+  })
+})

package/tests/json-body.spec.ts

@@ -0,0 +1,72 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { AppType } from '@owlmeans/context'
+import { contract, protocol, schema, typed } from '@owlmeans/entrypoint'
+import { backend, route, RouteMethod } from '@owlmeans/route'
+import { config, makeServerContext } from '@owlmeans/server-context'
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import { bind } from '@owlmeans/server-entrypoint'
+import type { FastifyInstance } from 'fastify'
+import { handlers } from '../src/protocol.js'
+import { appendApiServer } from '../src/server.js'
+
+interface Echo { value: unknown, type: string }
+
+const echoOf = <T>(alias: string, body: ReturnType<typeof schema<T>>) => protocol(
+  route(`server-api-test:${alias}`, `/echo/${alias}`, backend(null, RouteMethod.POST)),
+  contract(body, typed<Echo>()),
+)
+
+const text = echoOf('text', schema<string>({ type: 'string' }))
+const count = echoOf('count', schema<number>({ type: 'number' }))
+const flag = echoOf('flag', schema<boolean>({ type: 'boolean' }))
+const record = echoOf('record', schema<{ a: number }>({ type: 'object', properties: { a: { type: 'number' } }, required: ['a'] }))
+
+/**
+ * A scalar JSON body through the package's own server — `appendApiServer`, its Fastify instance,
+ * its body validation and a protocol-bound handler — exactly as `@owlmeans/api` now sends it:
+ * JSON text. The client half of the round trip is `@owlmeans/api`'s `body.spec.ts`.
+ */
+describe('@owlmeans/server-api — a scalar JSON body', () => {
+  let server: FastifyInstance
+  let context: ServerContext<ServerConfig>
+
+  beforeAll(async () => {
+    const service = 'server-api-tests'
+    context = makeServerContext(config<ServerConfig>(service, {
+      services: { [service]: { service, type: AppType.Backend, host: '127.0.0.1', default: true } },
+    } as Partial<ServerConfig>)) as ServerContext<ServerConfig>
+    const served = appendApiServer(context)
+    const api = handlers<ServerContext<ServerConfig>>()
+    for (const echo of [text, count, flag, record]) {
+      context.registerEntrypoint(bind(echo, api.request(echo, async request => ({ value: request.body, type: typeof request.body }))))
+    }
+    context.configure()
+    await context.init()
+    server = served.getApiServer().server
+    await server.ready()
+  })
+
+  afterAll(async () => { await server?.close() })
+
+  const post = async (alias: string, payload: string, type: string = 'application/json') =>
+    await server.inject({ method: 'POST', url: `/echo/${alias}`, headers: { 'content-type': type }, payload })
+
+  const echoed = async (alias: string, payload: string): Promise<Echo> => (await post(alias, payload)).json<Echo>()
+
+  test('a JSON string, number or boolean reaches the handler as that value', async () => {
+    expect(await echoed('text', '"abc"')).toEqual({ value: 'abc', type: 'string' })
+    expect(await echoed('text', '""')).toEqual({ value: '', type: 'string' })
+    expect(await echoed('text', '"123"')).toEqual({ value: '123', type: 'string' })
+    expect(await echoed('count', '42')).toEqual({ value: 42, type: 'number' })
+    expect(await echoed('flag', 'false')).toEqual({ value: false, type: 'boolean' })
+  })
+
+  test('an object body is unchanged', async () => {
+    expect(await echoed('record', '{"a":1}')).toEqual({ value: { a: 1 }, type: 'object' })
+  })
+
+  test('an unquoted string or an empty JSON body is refused with 400 — what the client no longer sends', async () => {
+    expect((await post('text', 'abc')).statusCode).toBe(400)
+    expect((await post('text', '')).statusCode).toBe(400)
+  })
+})

package/tests/log-adapter.spec.ts

@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { addLogPlugin, configureLog, memoryPlugin, resetLog } from '@owlmeans/log'
+import { fastifyLogUtils } from '../src/utils/log.js'
+
+const fastifyLogger = fastifyLogUtils.logger
+
+const memory = memoryPlugin('adapter')
+
+beforeEach(() => {
+  resetLog()
+  addLogPlugin(memory)
+  configureLog({ level: 'debug', console: 'native' })
+})
+afterEach(() => { memory.clear(); resetLog() })
+
+describe('@owlmeans/server-api — the Fastify logger adapter', () => {
+  test('lowers the listening line, keeps the rest', () => {
+    const log = fastifyLogger() as unknown as Record<string, (...args: unknown[]) => void>
+    log.info('Server listening at http://127.0.0.1:80')
+    log.info('something else')
+    log.warn({ a: 1 }, 'warned')
+    log.error({ err: new Error('boom') }, 'failed')
+
+    expect(memory.records.map(r => [r.level, r.message])).toEqual([
+      ['debug', 'Server listening at http://127.0.0.1:80'],
+      ['info', 'something else'],
+      ['warn', 'warned'],
+      ['error', 'failed'],
+    ])
+    expect(memory.records[3].error?.message).toBe('boom')
+  })
+
+  test('the controller writes no per-request pair and a missing route without its query', () => {
+    const controller = fastifyLogUtils.controller()
+    const request = { method: 'GET', url: '/x?token=abc' } as never
+    controller.incomingRequest(request, {} as never)
+    controller.requestCompleted(null, request, { statusCode: 200 } as never)
+    controller.routeNotFound(request, {} as never)
+
+    expect(memory.records.map(r => [r.level, r.message, r.data])).toEqual([
+      ['debug', 'Route not found', { method: 'GET', path: '/x' }],
+    ])
+  })
+
+  test('child loggers bind their fields and the level is the process level', () => {
+    const base = fastifyLogger()
+    const child = (base as unknown as { child: (b: object) => Record<string, (...a: unknown[]) => void> }).child({ reqId: 'r1' })
+    child.warn('hello')
+    expect(memory.records[0].data).toEqual({ reqId: 'r1' })
+    expect(base.level).toBe('debug')
+    configureLog({ level: 'warn' })
+    expect(base.level).toBe('warn')
+  })
+
+  test('at info level, debug lines are not written', () => {
+    configureLog({ level: 'info' })
+    const log = fastifyLogger() as unknown as Record<string, (...args: unknown[]) => void>
+    log.debug('quiet')
+    log.info('shown')
+    expect(memory.records.map(r => r.message)).toEqual(['shown'])
+  })
+})

package/tests/log-redaction.spec.ts

@@ -0,0 +1,181 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test'
+import { AppType } from '@owlmeans/context'
+import { addLogPlugin, configureLog, logStateHelper, memoryPlugin, resetLog } from '@owlmeans/log'
+import type { LogRecord, NativeConsole } from '@owlmeans/log'
+import { contract, protocol, schema, typed } from '@owlmeans/entrypoint'
+import { backend, route, RouteMethod } from '@owlmeans/route'
+import { config, makeServerContext } from '@owlmeans/server-context'
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import { bind } from '@owlmeans/server-entrypoint'
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'
+import { handlers } from '../src/protocol.js'
+import { appendApiServer } from '../src/server.js'
+import { fastifyLogUtils } from '../src/utils/log.js'
+
+/** What a caller sent; none of it may reach a log record or a written line. */
+const MARKER = 'pii-marker-7f3a'
+const SECRETS = ['auth-secret-91c2', 'cookie-secret-44d0', 'query-secret-0b5e']
+
+interface Inquiry { email: string, message: string }
+
+const inquiry = protocol(
+  route('server-api-test:inquiry', '/inquiry', backend(null, RouteMethod.POST)),
+  contract(schema<Inquiry>({
+    type: 'object',
+    properties: { email: { type: 'string', format: 'email' }, message: { type: 'string', maxLength: 10 } },
+    required: ['email', 'message'],
+  }), typed<{ ok: boolean }>()),
+)
+
+const memory = memoryPlugin('redaction')
+const written: string[] = []
+const saved: Partial<NativeConsole> = {}
+
+/** Every record as a plugin receives it, plus the error's own text: the sink writes no more than that. */
+const recorded = (records: LogRecord[]): string => JSON.stringify(records.map(record => ({
+  ...record, error: record.error != null ? { message: record.error.message, stack: record.error.stack } : undefined,
+})))
+
+const leaks = (): string[] => {
+  const everything = `${recorded(memory.records)}\n${written.join('\n')}`
+  return [MARKER, ...SECRETS].filter(secret => everything.includes(secret))
+}
+
+beforeEach(() => {
+  memory.clear()
+  written.length = 0
+  addLogPlugin(memory)
+  configureLog({ level: 'debug', console: 'native' })
+  // The sink itself: read what it writes, through the captured natives it writes with.
+  const native = logStateHelper.nativeConsole()
+  for (const method of ['debug', 'info', 'warn', 'error'] as const) {
+    saved[method] = native[method]
+    native[method] = (...args: unknown[]) => { written.push(args.map(String).join(' ')) }
+  }
+})
+
+afterEach(() => {
+  Object.assign(logStateHelper.nativeConsole(), saved)
+  resetLog()
+})
+
+describe('@owlmeans/server-api — a request never reaches the log', () => {
+  let server: FastifyInstance
+
+  beforeAll(async () => {
+    const service = 'server-api-redaction'
+    const context = makeServerContext(config<ServerConfig>(service, {
+      services: { [service]: { service, type: AppType.Backend, host: '127.0.0.1', default: true } },
+    } as Partial<ServerConfig>)) as ServerContext<ServerConfig>
+    const served = appendApiServer(context)
+    const api = handlers<ServerContext<ServerConfig>>()
+    context.registerEntrypoint(bind(inquiry, api.request(inquiry, async () => ({ ok: true }))))
+    context.configure()
+    await context.init()
+    server = served.getApiServer().server
+    await server.ready()
+  })
+
+  afterAll(async () => { await server?.close() })
+
+  const headers = {
+    authorization: `Bearer ${SECRETS[0]}`, cookie: `session=${SECRETS[1]}`,
+  }
+
+  test('a JSON body the schema refuses: method, path, status, code and message only', async () => {
+    const response = await server.inject({
+      method: 'POST', url: `/inquiry?token=${SECRETS[2]}`,
+      headers: { ...headers, 'content-type': 'application/json' },
+      payload: JSON.stringify({ email: `${MARKER}@`, message: `${MARKER} wrote this` }),
+    })
+
+    expect(response.statusCode).toBe(400)
+    expect(leaks()).toEqual([])
+    const refused = memory.records.find(record => record.message === 'Request refused')
+    expect(refused).toMatchObject({
+      level: 'debug', scope: 'http',
+      data: { method: 'POST', path: '/inquiry', status: 400, code: 'FST_ERR_VALIDATION' },
+    })
+    expect(Object.keys(refused!.data as object).sort()).toEqual(['code', 'message', 'method', 'path', 'status'])
+    // Nothing about a refused request is written at info.
+    expect(memory.records.filter(record => record.level !== 'debug')).toEqual([])
+  })
+
+  test('a multipart body the schema refuses: no field, no file byte', async () => {
+    const boundary = 'owlmeansboundary'
+    const payload = [
+      `--${boundary}`, 'Content-Disposition: form-data; name="email"', '', `${MARKER}@`,
+      `--${boundary}`, 'Content-Disposition: form-data; name="message"', '', `${MARKER} wrote this`,
+      `--${boundary}`, 'Content-Disposition: form-data; name="file"; filename="note.txt"', 'Content-Type: text/plain', '',
+      `${MARKER} file bytes`, `--${boundary}--`, '',
+    ].join('\r\n')
+    const response = await server.inject({
+      method: 'POST', url: '/inquiry', payload,
+      headers: { ...headers, 'content-type': `multipart/form-data; boundary=${boundary}` },
+    })
+
+    expect(response.statusCode).toBe(400)
+    expect(leaks()).toEqual([])
+    expect(memory.records.some(record => record.message === 'Request refused')).toBe(true)
+  })
+
+  test('an unparsable body and a missing route: no body, no query', async () => {
+    const broken = await server.inject({
+      method: 'POST', url: `/inquiry?token=${SECRETS[2]}`,
+      headers: { ...headers, 'content-type': 'application/json' }, payload: `{"email":"${MARKER}`,
+    })
+    const missing = await server.inject({ method: 'GET', url: `/nowhere?token=${SECRETS[2]}`, headers })
+
+    expect(broken.statusCode).toBe(400)
+    expect(missing.statusCode).toBe(404)
+    expect(leaks()).toEqual([])
+    expect(memory.records.find(record => record.message === 'Route not found')?.data)
+      .toEqual({ method: 'GET', path: '/nowhere' })
+  })
+})
+
+describe('@owlmeans/server-api — what the Fastify log adapter writes', () => {
+  const request = {
+    method: 'POST', url: `/inquiry?token=${SECRETS[2]}`, id: 'req-1',
+    headers: { ...{ authorization: `Bearer ${SECRETS[0]}`, cookie: `session=${SECRETS[1]}` }, 'x-note': MARKER },
+    body: { email: `${MARKER}@example.com` }, rawBody: `{"email":"${MARKER}@example.com"}`,
+    query: { token: SECRETS[2] },
+  }
+  const reply = { statusCode: 500, request, header: () => reply }
+
+  test('a request becomes its method and path, a reply its status, bytes their size', () => {
+    const fastifyRequest = Object.assign(Object.create({ kind: 'request' }) as object, request)
+    const fastifyReply = Object.assign(Object.create({ kind: 'reply' }) as object, reply)
+    const log = fastifyLogUtils.logger() as unknown as Record<string, (...args: unknown[]) => void>
+    log.error({ req: fastifyRequest, res: fastifyReply, err: new Error('boom') }, 'failed')
+    log.info({ busboyOptions: { headers: request.headers, limits: { files: 5 } } }, 'parsing')
+    log.warn({ body: request.body, rawBody: request.rawBody, file: new TextEncoder().encode(MARKER) }, 'dumped')
+    log.warn({ upload: new TextEncoder().encode(MARKER), url: request.url }, `Reply was already sent in "${request.url}"`)
+
+    expect(leaks()).toEqual([])
+    expect(memory.records.map(record => record.data)).toEqual([
+      { req: { method: 'POST', path: '/inquiry' }, res: { statusCode: 500 } },
+      { busboyOptions: { limits: { files: 5 } } },
+      {},
+      { upload: `[Uint8Array ${MARKER.length} bytes]`, url: '/inquiry' },
+    ])
+    expect(memory.records[3].message).toBe('Reply was already sent in "/inquiry"')
+  })
+
+  test('the controller logs a request the default error handler answers by its status alone', () => {
+    const controller = fastifyLogUtils.controller()
+    const asRequest = request as unknown as FastifyRequest
+    controller.defaultErrorLog(new Error('fault'), asRequest, { ...reply, statusCode: 500 } as unknown as FastifyReply)
+    controller.defaultErrorLog(new Error('denied'), asRequest, { ...reply, statusCode: 403 } as unknown as FastifyReply)
+    controller.incomingRequest(asRequest, reply as unknown as FastifyReply)
+    controller.requestCompleted(null, asRequest, reply as unknown as FastifyReply)
+
+    expect(leaks()).toEqual([])
+    expect(memory.records.map(record => [record.level, record.message, record.data])).toEqual([
+      ['error', 'Request failed', { method: 'POST', path: '/inquiry', status: 500 }],
+      ['warn', 'Access forbidden', { message: 'denied', method: 'POST', path: '/inquiry', status: 403 }],
+    ])
+    expect(memory.records[0].error?.message).toBe('fault')
+    expect(memory.records[1].event).toBe('access.forbidden')
+  })
+})

package/tests/tsconfig.json

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

package/tsconfig.json

@@ -10,6 +10,7 @@
   "exclude": [
     "./dist/**/*",
     "./build/**/*",
+    "./tests/**/*",
     "./*.ts"
   ]
 }