@mpen/routekit 0.1.0 → 0.1.2

package/src/router/middleware/request-id-ctx.test.ts

@@ -1,183 +0,0 @@
-#!/usr/bin/env -S bun test
-import { describe, expect, it } from 'bun:test'
-import { HttpMethod } from '@mpen/http'
-import { Router } from '../router'
-import { requestIdCtx } from './request-id-ctx'
-import type { RouterHeadersInit } from '../fetch-types'
-
-function makeRequest(headers?: RouterHeadersInit): Request {
-    const init: RequestInit = { method: HttpMethod.GET }
-    if (headers) init.headers = headers
-    return new Request('https://example.com/', init)
-}
-
-describe(requestIdCtx.name, () => {
-    it('uses the request id header when present', async () => {
-        const router = new Router()
-        router.useRequest(requestIdCtx())
-        router.add({
-            method: HttpMethod.GET,
-            path: '/',
-            handler: ({ requestId }) => {
-                expect(requestId).toBe('req-123')
-                return new Response(requestId)
-            },
-        })
-
-        const response = await router.fetch(makeRequest({ 'x-request-id': 'req-123' }))
-
-        expect(await response.text()).toBe('req-123')
-    })
-
-    it('uses the generate callback when missing a header', async () => {
-        const router = new Router()
-        const seenExtra: { prefix: string; hotReloadCounter: number; requestCounter: number }[] = []
-        const generated: string[] = []
-        const generate = (
-            _ctx: unknown,
-            extra: { prefix: string; hotReloadCounter: number; requestCounter: number },
-        ) => {
-            seenExtra.push(extra)
-            const value = `${extra.prefix}.${extra.hotReloadCounter}.${extra.requestCounter}`
-            generated.push(value)
-            return value
-        }
-        router.useRequest(requestIdCtx({ generate, prefix: 'custom' }))
-        router.add({
-            method: HttpMethod.GET,
-            path: '/',
-            handler: ({ requestId }) => {
-                expect(requestId).toBe(generated[generated.length - 1])
-                return new Response(requestId)
-            },
-        })
-
-        const first = await router.fetch(makeRequest())
-        const second = await router.fetch(makeRequest())
-
-        expect(await first.text()).toMatch(/^custom\.\d+\.\d+$/)
-        expect(await second.text()).toMatch(/^custom\.\d+\.\d+$/)
-        expect(seenExtra).toHaveLength(2)
-        expect(seenExtra[0]?.prefix).toBe('custom')
-        expect(seenExtra[1]?.prefix).toBe('custom')
-        expect(seenExtra[0]?.hotReloadCounter).toBe(seenExtra[1]?.hotReloadCounter)
-        expect(seenExtra[0]?.requestCounter).toBe(1)
-        expect(seenExtra[1]?.requestCounter).toBe(2)
-    })
-
-    it('respects header order when multiple names are provided', async () => {
-        const router = new Router()
-        router.useRequest(requestIdCtx({ readHeaderName: ['x-request-id', 'x-trace-id'] }))
-        router.add({
-            method: HttpMethod.GET,
-            path: '/',
-            handler: ({ requestId, request }) => {
-                const headerId =
-                    request.headers.get('x-request-id') ?? request.headers.get('x-trace-id')
-                expect(requestId).toBe(headerId)
-                return new Response(requestId)
-            },
-        })
-
-        const fallback = await router.fetch(makeRequest({ 'x-trace-id': 'trace-456' }))
-        const preferred = await router.fetch(
-            makeRequest({
-                'x-request-id': 'primary-789',
-                'x-trace-id': 'secondary-000',
-            }),
-        )
-
-        expect(await fallback.text()).toBe('trace-456')
-        expect(await preferred.text()).toBe('primary-789')
-    })
-
-    it('writes the request id into the response header when configured', async () => {
-        const router = new Router()
-        router.useRequest(
-            requestIdCtx({
-                generate: () => 'req-42',
-                writeHeaderName: 'x-request-id',
-            }),
-        )
-        router.add({
-            method: HttpMethod.GET,
-            path: '/',
-            handler: ({ requestId }) => {
-                expect(requestId).toBe('req-42')
-                return 'ok'
-            },
-        })
-
-        const response = await router.fetch(makeRequest())
-
-        expect(response.headers.get('x-request-id')).toBe('req-42')
-        expect(await response.text()).toBe('ok')
-    })
-
-    it('writes the request id into logical response headers', async () => {
-        const router = new Router()
-        router.useRequest(
-            requestIdCtx({
-                generate: () => 'req-logical',
-                writeHeaderName: 'x-request-id',
-            }),
-        )
-        router.add({
-            method: HttpMethod.GET,
-            path: '/',
-            handler: () => ({ ok: true }),
-        })
-
-        const response = await router.fetch(makeRequest())
-
-        expect(response.headers.get('x-request-id')).toBe('req-logical')
-        expect(await response.json()).toEqual({ ok: true })
-    })
-
-    it('uses the default generator format when no header is provided', async () => {
-        const router = new Router()
-        router.useRequest(requestIdCtx({ prefix: 'req' }))
-        router.add({
-            method: HttpMethod.GET,
-            path: '/',
-            handler: ({ requestId }) => {
-                return new Response(requestId)
-            },
-        })
-
-        const first = await router.fetch(makeRequest())
-        const second = await router.fetch(makeRequest())
-
-        const firstId = await first.text()
-        const secondId = await second.text()
-
-        expect(firstId).toBe('req.1')
-        expect(secondId).toBe('req.2')
-    })
-
-    it('does not declare a terminal response while decorating downstream output', () => {
-        const router = new Router().useRequest(requestIdCtx({ writeHeaderName: 'x-request-id' }))
-        router.add({ method: HttpMethod.GET, path: '/', handler: () => new Response() })
-
-        expect(router.getRoutes()[0]?.schema).toBeUndefined()
-    })
-
-    it('writes correlated ids on generated responses', async () => {
-        const router = new Router()
-            .useRequest(
-                requestIdCtx({
-                    generate: () => 'req-generated',
-                    writeHeaderName: 'x-request-id',
-                }),
-            )
-            .get('/exists', () => new Response('ok'))
-
-        const missing = await router.fetch(new Request('https://example.com/missing'))
-        const options = await router.fetch(
-            new Request('https://example.com/exists', { method: HttpMethod.OPTIONS }),
-        )
-
-        expect(missing.headers.get('x-request-id')).toBe('req-generated')
-        expect(options.headers.get('x-request-id')).toBe('req-generated')
-    })
-})

package/src/router/middleware/request-id-ctx.ts

@@ -1,135 +0,0 @@
-import type { AnyContext, HandlerContext, OneOrMany, RequestMiddleware } from '../types'
-
-declare global {
-    var _reloadCounter: number
-    var _globalRequestCounter: number
-}
-
-globalThis._reloadCounter = globalThis._reloadCounter == null ? 0 : globalThis._reloadCounter + 1
-globalThis._globalRequestCounter ??= 0
-
-interface ExtraContext {
-    prefix: string
-    /**
-     * Number of times this server has been hot-reloaded.
-     */
-    hotReloadCounter: number
-    /**
-     * Sequential request number for this middleware instance.
-     */
-    requestCounter: number
-    /**
-     * Sequential request number across request id middleware instances.
-     */
-    globalRequestCounter: number
-}
-
-/**
- * Options for [`requestIdCtx`]{@link requestIdCtx}.
- *
- * @example
- * ```ts
- * const options: RequestIdCtxOptions = {
- *     writeHeaderName: 'x-request-id',
- *     generate: () => crypto.randomUUID(),
- * }
- * ```
- *
- * @typeParam Ctx - Context available before request id generation.
- */
-export interface RequestIdCtxOptions<Ctx extends object = AnyContext> {
-    /**
-     * Prefix used by the default generator. Defaults to an empty string.
-     */
-    prefix?: string
-    /**
-     * Header(s) to check for a request id. Defaults to common request/trace headers.
-     * Set to `null` or an empty array to disable header reads.
-     */
-    readHeaderName?: OneOrMany<string> | null
-    /**
-     * Response header name to write the request id into.
-     */
-    writeHeaderName?: string
-    /**
-     * Custom request id generator used when no read header is present.
-     *
-     * @param ctx - Current request context.
-     * @param extra - Prefix and counter values maintained by this middleware.
-     * @returns Request identifier.
-     */
-    generate?: (ctx: HandlerContext<Ctx>, extra: ExtraContext) => string
-}
-
-export const isHMR = import.meta.hot !== undefined || process.execArgv.includes('--hot')
-
-function defaultRequestIdGenerator(_ctx: HandlerContext<AnyContext>, extra: ExtraContext): string {
-    let requestId = extra.requestCounter.toString(36)
-    if (isHMR) {
-        requestId = extra.hotReloadCounter.toString(36) + '.' + requestId
-    }
-    if (extra.prefix) requestId = `${extra.prefix}.${requestId}`
-    return requestId
-}
-
-/**
- * Attach a correlated request id to every final response and contextual logger record.
- *
- * @example
- * ```ts
- * router.useRequest(requestIdCtx({
- *   readHeaderName: ['x-request-id', 'x-trace-id'],
- *   writeHeaderName: 'x-request-id',
- *   generate: () => crypto.randomUUID(),
- * }))
- * ```
- *
- * @param options - Configuration for reading, generating, and writing request ids.
- * @returns Request-boundary middleware that populates `requestId` and logger context.
- * @typeParam Ctx - Context available before request id generation.
- */
-export function requestIdCtx<Ctx extends object = AnyContext>(
-    options: RequestIdCtxOptions<Ctx> = {},
-): RequestMiddleware<{ requestId: string }, Ctx> {
-    const prefix = options.prefix ?? ''
-    const headers =
-        options.readHeaderName === undefined
-            ? ['x-request-id', 'x-trace-id', 'traceparent']
-            : options.readHeaderName == null
-              ? []
-              : Array.isArray(options.readHeaderName)
-                ? options.readHeaderName
-                : [options.readHeaderName]
-    const writeHeaderName = options.writeHeaderName
-    const hotReloadCounter = globalThis._reloadCounter
-    let requestCounter = 0
-
-    return async (ctx, next) => {
-        let headerId: string | null = null
-
-        for (const name of headers) {
-            headerId = ctx.request.headers.get(name)
-            if (headerId !== null) break
-        }
-
-        const extra: ExtraContext = {
-            prefix,
-            hotReloadCounter,
-            requestCounter: ++requestCounter,
-            globalRequestCounter: ++globalThis._globalRequestCounter,
-        }
-        const requestId =
-            headerId ??
-            options.generate?.(ctx, extra) ??
-            defaultRequestIdGenerator(ctx, extra)
-
-        ctx.requestId = requestId
-        ctx.logger = ctx.logger.withContext({ 'request.id': requestId })
-
-        const response = await next()
-        if (writeHeaderName != null) {
-            response.headers.set(writeHeaderName, requestId)
-        }
-        return response
-    }
-}

package/src/router/middleware/request-logger-format.test.ts

@@ -1,16 +0,0 @@
-import { describe, test, expect } from 'bun:test'
-import { formatDurationMilliseconds } from './request-logger-format.ts'
-
-describe(formatDurationMilliseconds.name, () => {
-    test('formats durations correctly', () => {
-        expect(formatDurationMilliseconds(0.005)).toBe('0.01')
-        expect(formatDurationMilliseconds(0.05)).toBe('0.05')
-        expect(formatDurationMilliseconds(0.5)).toBe('0.50')
-        expect(formatDurationMilliseconds(5)).toBe('5.0')
-        expect(formatDurationMilliseconds(50)).toBe('50.0')
-        expect(formatDurationMilliseconds(500)).toBe('500')
-
-        expect(formatDurationMilliseconds(0.99)).toBe('0.99')
-        expect(formatDurationMilliseconds(0.996)).toBe('1.0')
-    })
-})

package/src/router/middleware/request-logger-format.ts

@@ -1,269 +0,0 @@
-import type { LogRecord, LogRecordTransform, TerminalLogRecordFormatter } from '@mpen/logger'
-
-export const ROUTEKIT_HTTP_SERVER_REQUEST_EVENT_NAME = 'http.server.request'
-
-const ROUTEKIT_REQUEST_CONTEXT_KEYS = ['http.request.method', 'url.path', 'request.id'] as const
-
-const REQUEST_ID_COLOR_KEYS = [
-    'cyanBright',
-    'magentaBright',
-    'greenBright',
-    'yellowBright',
-    'blueBright',
-    'redBright',
-    'cyan',
-    'magenta',
-] as const
-
-/**
- * Transform Routekit request activity records into production JSON access logs.
- *
- * Removes the fallback activity message from `http.server.request` records while preserving
- * normal application log messages written through the same contextual logger.
- *
- * @example
- * ```ts
- * import { JsonLogger } from '@mpen/logger'
- * import { transformRoutekitJsonLogRecord } from '@mpen/routekit/middleware'
- *
- * const logger = new JsonLogger({
- *     transformRecord: transformRoutekitJsonLogRecord,
- * })
- * ```
- *
- * @param record - Record emitted by a logger.
- * @returns The transformed record, or `undefined` to use the original record.
- */
-export const transformRoutekitJsonLogRecord: LogRecordTransform = (record) => {
-    if (!isRoutekitRequestEvent(record)) {
-        return undefined
-    }
-
-    return {
-        ...record,
-        data: stripActivityLifecycleMessage(record),
-    }
-}
-
-/**
- * Format Routekit request context for terminal logs.
- *
- * Renders compact request start/completion lines, color-correlated request identifiers, status
- * codes, elapsed time, and response sizes while leaving unrelated records to
- * [`TerminalLogger`]{@link import('@mpen/logger').TerminalLogger}'s default renderer.
- *
- * @example
- * ```ts
- * import { TerminalLogger } from '@mpen/logger'
- * import { formatRoutekitTerminalLogRecord } from '@mpen/routekit/middleware'
- *
- * const logger = new TerminalLogger({
- *     formatRecord: formatRoutekitTerminalLogRecord,
- * })
- * ```
- *
- * @param record - Record emitted by a logger.
- * @param terminal - Terminal formatting helpers.
- * @returns Formatted terminal output, or `undefined` to use the default renderer.
- */
-export const formatRoutekitTerminalLogRecord: TerminalLogRecordFormatter = (record, terminal) => {
-    if (!hasRoutekitRequestContext(record)) {
-        return undefined
-    }
-
-    const colors = terminal.colors
-    const context = record.context
-    const requestId = getStringContext(record, 'request.id')
-    const method = getStringContext(record, 'http.request.method')!
-    const path = getStringContext(record, 'url.path')!
-    const route = getStringContext(record, 'http.route')
-    const direction = getActivityDirection(record)
-    const parts = [
-        formatServiceName(getStringContext(record, 'service.name'), colors),
-        requestId == null ? undefined : formatRequestId(requestId, colors),
-        requestId == null ? undefined : formatDirection(direction, colors),
-        requestId == null ? formatDirection(direction, colors) : undefined,
-        colors.bold(colors.whiteBright(method)),
-        colors.white(path),
-        route == null || route === path ? undefined : colors.blackBright(`route=${route}`),
-        formatStatusCode(getNumberContext(context['http.response.status_code']), colors),
-        formatDuration(getNumberContext(context.duration_ms), colors),
-        formatBodySize(getNumberContext(context['http.response.body.size']), colors),
-    ].filter((part): part is string => part != null && part !== '')
-    const prefix = `${terminal.icon} ${colors.blackBright(terminal.time)} ${parts.join(' ')}`
-    const data = direction == null ? record.data : stripActivityLifecycleMessage(record)
-
-    if (data.length === 0) {
-        return prefix.trimEnd()
-    }
-
-    const message = terminal.formatData(data)
-
-    if (message === '') {
-        return prefix.trimEnd()
-    }
-
-    const [firstLine = '', ...remainingLines] = message.split('\n')
-
-    return [prefix + ' ' + firstLine, ...remainingLines.map((line) => '   ' + line)].join('\n')
-}
-
-function hasRoutekitRequestContext(record: LogRecord): boolean {
-    return ROUTEKIT_REQUEST_CONTEXT_KEYS.every((key) => record.context[key] != null)
-}
-
-function isRoutekitRequestEvent(record: LogRecord): boolean {
-    return record.context['event.name'] === ROUTEKIT_HTTP_SERVER_REQUEST_EVENT_NAME
-}
-
-function stripActivityLifecycleMessage(record: LogRecord): readonly unknown[] {
-    return record.metadata.activity == null ? record.data : record.data.slice(1)
-}
-
-function getActivityDirection(record: LogRecord): '\u2192' | '\u2190' | undefined {
-    switch (record.metadata.activity?.phase) {
-        case 'start':
-            return '\u2192'
-        case 'end':
-            return '\u2190'
-    }
-}
-
-function getStringContext(record: LogRecord, key: string): string | undefined {
-    const value = record.context[key]
-
-    return value == null ? undefined : String(value)
-}
-
-function getNumberContext(value: unknown): number | undefined {
-    if (typeof value !== 'number') {
-        return undefined
-    }
-
-    return Number.isFinite(value) ? value : undefined
-}
-
-function formatServiceName(
-    value: string | undefined,
-    colors: Parameters<TerminalLogRecordFormatter>[1]['colors'],
-): string | undefined {
-    if (value == null) {
-        return undefined
-    }
-
-    const text = `[${value}]`
-
-    return colors.bold(colors.blueBright(text))
-}
-
-function formatRequestId(
-    value: string,
-    colors: Parameters<TerminalLogRecordFormatter>[1]['colors'],
-): string {
-    const text = `[${value}]`
-    let hash = 0
-
-    for (const char of value) {
-        hash = (hash * 31 + char.codePointAt(0)!) >>> 0
-    }
-
-    const color = REQUEST_ID_COLOR_KEYS[hash % REQUEST_ID_COLOR_KEYS.length]!
-
-    return colors[color](text)
-}
-
-function formatDirection(
-    value: '\u2192' | '\u2190' | undefined,
-    colors: Parameters<TerminalLogRecordFormatter>[1]['colors'],
-): string | undefined {
-    return value == null ? undefined : colors.bold(colors.whiteBright(value))
-}
-
-function formatStatusCode(
-    value: number | undefined,
-    colors: Parameters<TerminalLogRecordFormatter>[1]['colors'],
-): string | undefined {
-    if (value == null) {
-        return undefined
-    }
-
-    const text = String(value)
-    const formatted =
-        value >= 500
-            ? colors.redBright(text)
-            : value >= 400
-              ? colors.yellowBright(text)
-              : value >= 300
-                ? colors.cyanBright(text)
-                : colors.greenBright(text)
-
-    return colors.bold(formatted)
-}
-
-function formatDuration(
-    value: number | undefined,
-    colors: Parameters<TerminalLogRecordFormatter>[1]['colors'],
-): string | undefined {
-    if (value == null) {
-        return undefined
-    }
-
-    const text = `${formatDurationMilliseconds(value)}ms`
-
-    if (value >= 1000) {
-        return colors.redBright(text)
-    }
-
-    return value >= 250 ? colors.yellowBright(text) : colors.greenBright(text)
-}
-
-/**
- * @internal
- */
-export function formatDurationMilliseconds(value: number): string {
-    const p2 = value.toFixed(2)
-    if (Number(p2) < 1) {
-        return p2
-    }
-
-    const p1 = value.toFixed(1)
-    if (Number(p1) < 100) {
-        return p1
-    }
-
-    return value.toFixed(0)
-}
-
-function formatBodySize(
-    value: number | undefined,
-    colors: Parameters<TerminalLogRecordFormatter>[1]['colors'],
-): string | undefined {
-    return value == null ? undefined : colors.cyan(formatByteSize(value))
-}
-
-function formatByteSize(value: number): string {
-    if (!Number.isFinite(value) || value < 0) {
-        return String(value)
-    }
-
-    if (value < 1024) {
-        return `${value} B`
-    }
-
-    const units = ['KiB', 'MiB', 'GiB'] as const
-    let amount = value
-    let unit = 'B'
-
-    for (const nextUnit of units) {
-        amount /= 1024
-        unit = nextUnit
-
-        if (amount < 1024 || nextUnit === units.at(-1)) {
-            break
-        }
-    }
-
-    const precision = amount >= 100 ? 0 : amount >= 10 ? 1 : 2
-
-    return `${amount.toFixed(precision)} ${unit}`
-}