@mpen/routekit 0.1.0

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

@@ -0,0 +1,267 @@
+#!/usr/bin/env -S bun test
+import { describe, expect, it } from 'bun:test'
+import { HttpMethod, HttpStatus } from '@mpen/http'
+import { JsonLogger, MemoryLogger, TerminalLogger } from '@mpen/logger'
+import { Router } from '../router'
+import { response as routekitResponse } from '../response'
+import { requestIdCtx } from './request-id-ctx'
+import { requestLogger } from './request-logger'
+import {
+    formatRoutekitTerminalLogRecord,
+    transformRoutekitJsonLogRecord,
+} from './request-logger-format'
+
+describe(requestLogger.name, () => {
+    it('logs correlated start and completion activity records for matched requests', async () => {
+        const logger = new MemoryLogger()
+        const router = new Router()
+            .setLogger(logger)
+            .useRequest(requestIdCtx({ generate: () => 'req.1' }))
+            .useRequest(requestLogger({ trustedClientAddressHeader: 'x-forwarded-for' }))
+            .get('/users/:id', () => routekitResponse({ ok: true }))
+
+        const response = await router.fetch(
+            new Request('https://example.com/users/1', {
+                method: HttpMethod.GET,
+                headers: {
+                    'user-agent': 'routekit-test/1',
+                    'x-forwarded-for': '203.0.113.9, 10.0.0.1',
+                },
+            }),
+        )
+
+        expect(response.status).toBe(HttpStatus.OK)
+        expect(logger.logs).toHaveLength(2)
+        expect(logger.logs[0]).toEqual({
+            level: 'info',
+            data: ['request started'],
+            context: {
+                'client.address': '203.0.113.9',
+                'http.request.method': HttpMethod.GET,
+                'http.route': '/users/:id',
+                'request.id': 'req.1',
+                'url.path': '/users/1',
+                'user_agent.original': 'routekit-test/1',
+            },
+            metadata: { activity: { name: 'request', phase: 'start' } },
+        })
+        expect(logger.logs[1]?.level).toBe('info')
+        expect(logger.logs[1]?.data).toEqual(['request completed'])
+        expect(logger.logs[1]?.context).toMatchObject({
+            'event.name': 'http.server.request',
+            'http.request.method': HttpMethod.GET,
+            'http.response.body.size': 11,
+            'http.response.status_code': HttpStatus.OK,
+            'http.route': '/users/:id',
+            'request.id': 'req.1',
+            'url.path': '/users/1',
+            'user_agent.original': 'routekit-test/1',
+            'client.address': '203.0.113.9',
+        })
+        expect(logger.logs[1]?.metadata).toEqual({ activity: { name: 'request', phase: 'end' } })
+        expect(typeof logger.logs[1]?.context.duration_ms).toBe('number')
+    })
+
+    it('covers generated responses and reports server failures at error severity', async () => {
+        const logger = new MemoryLogger()
+        const router = new Router()
+            .setLogger(logger)
+            .useRequest(requestIdCtx({ generate: () => 'req.generated' }))
+            .useRequest(requestLogger())
+            .get('/boom', () => {
+                throw new Error('boom')
+            })
+
+        const missing = await router.fetch(new Request('https://example.com/missing'))
+        const failed = await router.fetch(new Request('https://example.com/boom'))
+
+        expect(missing.status).toBe(HttpStatus.NOT_FOUND)
+        expect(failed.status).toBe(HttpStatus.INTERNAL_SERVER_ERROR)
+
+        const completions = logger.logs.filter((record) => record.data[0] === 'request completed')
+        expect(completions).toHaveLength(2)
+        expect(completions[0]?.context['http.response.status_code']).toBe(HttpStatus.NOT_FOUND)
+        expect(completions[0]?.level).toBe('info')
+        expect(completions[1]?.context['http.response.status_code']).toBe(
+            HttpStatus.INTERNAL_SERVER_ERROR,
+        )
+        expect(completions[1]?.level).toBe('error')
+    })
+
+    it('does not record forwarded client addresses without an explicitly trusted header', async () => {
+        const logger = new MemoryLogger()
+        const router = new Router()
+            .setLogger(logger)
+            .useRequest(requestIdCtx({ generate: () => 'req.ignored' }))
+            .useRequest(requestLogger())
+            .get('/users', () => new Response(null))
+
+        await router.fetch(
+            new Request('https://example.com/users', {
+                headers: {
+                    'x-forwarded-for': '203.0.113.9',
+                },
+            }),
+        )
+
+        expect(logger.logs[0]?.context['client.address']).toBeUndefined()
+        expect(logger.logs[1]?.context['client.address']).toBeUndefined()
+    })
+
+    it('writes one named JSON access event without activity lifecycle details', async () => {
+        const lines: string[] = []
+        const logger = new JsonLogger({
+            transformRecord: transformRoutekitJsonLogRecord,
+            writeLine: (line) => lines.push(line),
+        })
+        const router = new Router()
+            .setLogger(logger)
+            .useRequest(requestIdCtx({ generate: () => 'req.json' }))
+            .useRequest(requestLogger())
+            .get('/users', () => routekitResponse({ ok: true }))
+
+        await router.fetch(new Request('https://example.com/users'))
+
+        expect(lines).toHaveLength(1)
+        const payload = JSON.parse(lines[0]!)
+        expect(payload['event.name']).toBe('http.server.request')
+        expect(payload.message).toBeUndefined()
+        expect(payload['activity.name']).toBeUndefined()
+        expect(payload['activity.phase']).toBeUndefined()
+        expect(payload['request.id']).toBe('req.json')
+        expect(payload['http.response.status_code']).toBe(HttpStatus.OK)
+    })
+})
+
+describe(formatRoutekitTerminalLogRecord.name, () => {
+    it('renders compact contextual activity start and completion output', () => {
+        const lines: string[] = []
+        const logger = new TerminalLogger({
+            color: false,
+            formatRecord: formatRoutekitTerminalLogRecord,
+            maxWidth: 200,
+            write: (line) => lines.push(line),
+        }).withContext({ 'service.name': 'api' })
+        const activity = logger.startActivity('request', {
+            'request.id': 'req.1',
+            'http.request.method': 'GET',
+            'url.path': '/users/1',
+            hidden: 'not-rendered',
+        })
+
+        activity.end({
+            context: { 'http.response.body.size': 1536, 'http.response.status_code': 200 },
+        })
+
+        const output = lines.join('')
+
+        expect(output).toContain('[api] [req.1] \u2192 GET /users/1')
+        expect(output).toContain('[api] [req.1] \u2190 GET /users/1 200')
+        expect(output).toContain('ms 1.50 KiB')
+        expect(output).not.toContain('request started')
+        expect(output).not.toContain('request completed')
+        expect(output).not.toContain('not-rendered')
+        expect(
+            output
+                .trimEnd()
+                .split('\n')
+                .every((line) => !line.endsWith(' ')),
+        ).toBe(true)
+    })
+
+    it('colors request correlations, completion status, and slow duration indicators', () => {
+        const lines: string[] = []
+        const logger = new TerminalLogger({
+            color: true,
+            formatRecord: formatRoutekitTerminalLogRecord,
+            maxWidth: 200,
+            write: (line) => lines.push(line),
+        }).withContext({ 'service.name': 'api' })
+        const fast = logger.startActivity('request', {
+            'request.id': '1',
+            'http.request.method': 'GET',
+            'url.path': '/fast',
+        })
+        const slow = logger.startActivity('request', {
+            'request.id': '2',
+            'http.request.method': 'POST',
+            'url.path': '/slow',
+        })
+
+        fast.end({ context: { 'http.response.status_code': 204, duration_ms: 1 } })
+        slow.end({ context: { 'http.response.status_code': 503, duration_ms: 1200 } })
+        logger
+            .withContext({
+                'request.id': '3',
+                'http.request.method': 'GET',
+                'url.path': '/manual-slow',
+                duration_ms: 1200,
+            })
+            .info('slow checkpoint')
+        logger
+            .withContext({
+                'request.id': '4',
+                'http.request.method': 'GET',
+                'url.path': '/manual-medium',
+                duration_ms: 300,
+            })
+            .info('medium checkpoint')
+
+        const output = lines.join('')
+
+        expect(output).toContain('\x1B[1m\x1B[94m[api]\x1B[39m\x1B[22m')
+        expect(output).toContain('\x1B[1m\x1B[97mGET\x1B[39m\x1B[22m')
+        expect(output).toContain('\x1B[1m\x1B[92m204\x1B[39m\x1B[22m')
+        expect(output).toContain('\x1B[1m\x1B[91m503\x1B[39m\x1B[22m')
+        expect(output).toContain('\x1B[91m1200ms\x1B[39m')
+        expect(output).toContain('\x1B[93m300ms\x1B[39m')
+        expect(output.match(/\x1B\[(?:9[1-6]|3[5-6])m\[[1234]\]/gu)).toHaveLength(6)
+    })
+
+    it('formats durations with precision based on elapsed time', () => {
+        const lines: string[] = []
+        const logger = new TerminalLogger({
+            color: false,
+            formatRecord: formatRoutekitTerminalLogRecord,
+            maxWidth: 200,
+            write: (line) => lines.push(line),
+        }).withContext({
+            'request.id': 'req.1',
+            'http.request.method': 'GET',
+            'url.path': '/timing',
+        })
+
+        logger.withContext({ duration_ms: 0.493 }).info('sub-ms')
+        logger.withContext({ duration_ms: 1.088 }).info('single-ms')
+        logger.withContext({ duration_ms: 16.726 }).info('double-ms')
+        logger.withContext({ duration_ms: 100 }).info('hundred-ms')
+        logger.withContext({ duration_ms: 1200.4 }).info('slow-ms')
+
+        const output = lines.join('')
+
+        expect(output).toContain('0.49ms')
+        expect(output).toContain('1.1ms')
+        expect(output).toContain('16.7ms')
+        expect(output).toContain('100ms')
+        expect(output).toContain('1200ms')
+    })
+
+    it('keeps ordinary request-context messages as messages', () => {
+        const lines: string[] = []
+        const logger = new TerminalLogger({
+            color: false,
+            formatRecord: formatRoutekitTerminalLogRecord,
+            maxWidth: 200,
+            write: (line) => lines.push(line),
+        }).withContext({
+            'request.id': 'req.1',
+            'http.request.method': 'POST',
+            'url.path': '/todos',
+        })
+
+        logger.info('request started')
+
+        expect(lines.join('')).toContain('[req.1] POST /todos request started')
+        expect(lines.join('')).not.toContain('\u2192')
+    })
+})

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

@@ -0,0 +1,131 @@
+import { LogLevel } from '@mpen/logger'
+import type { AnyContext, RequestMiddleware } from '../types'
+import { ROUTEKIT_HTTP_SERVER_REQUEST_EVENT_NAME } from './request-logger-format'
+
+/**
+ * Options for [`requestLogger`]{@link requestLogger}.
+ *
+ * @example
+ * ```ts
+ * const options: RequestLoggerOptions = {
+ *     completionLevel: response => response.status >= 500 ? LogLevel.ERROR : LogLevel.INFO,
+ * }
+ * ```
+ */
+export interface RequestLoggerOptions {
+    /**
+     * Activity label used for start and completion records.
+     * @defaultValue `'request'`
+     */
+    activityName?: string
+    /**
+     * Completion severity or a function selecting severity from the final response.
+     */
+    completionLevel?: LogLevel | ((response: Response) => LogLevel)
+    /**
+     * Header containing a trusted proxy-provided original client address.
+     *
+     * Only configure this when direct clients cannot provide or alter this header. For
+     * `x-forwarded-for`, the first comma-separated address is recorded as `client.address`.
+     *
+     * @example
+     * ```ts
+     * requestLogger({ trustedClientAddressHeader: 'x-forwarded-for' })
+     * ```
+     */
+    trustedClientAddressHeader?: string
+}
+
+function defaultCompletionLevel(response: Response): LogLevel {
+    return response.status >= 500 ? LogLevel.ERROR : LogLevel.INFO
+}
+
+const HTTP_SERVER_REQUEST_EVENT = {
+    'event.name': ROUTEKIT_HTTP_SERVER_REQUEST_EVENT_NAME,
+} as const
+
+function getResponseBodySize(response: Response): number | undefined {
+    if (response.body == null) {
+        return 0
+    }
+
+    const value = response.headers.get('content-length')
+    if (value == null || !/^\d+$/u.test(value)) {
+        return undefined
+    }
+
+    const size = Number(value)
+    return Number.isSafeInteger(size) ? size : undefined
+}
+
+function getClientAddress(
+    request: { headers: Headers },
+    trustedHeader: string | undefined,
+): string | undefined {
+    if (trustedHeader == null) {
+        return undefined
+    }
+
+    const value = request.headers.get(trustedHeader)?.trim()
+    if (!value) {
+        return undefined
+    }
+
+    return trustedHeader.toLowerCase() === 'x-forwarded-for'
+        ? value.split(',', 1)[0]?.trim()
+        : value
+}
+
+/**
+ * Log a timed request activity through the request's contextual logger.
+ *
+ * @example
+ * ```ts
+ * router.useRequest(requestIdCtx())
+ * router.useRequest(requestLogger())
+ * ```
+ *
+ * @param options - Request activity naming and severity options.
+ * @returns Request-boundary middleware that logs final status and duration.
+ * @typeParam Ctx - Context containing the correlated request identifier.
+ */
+export function requestLogger<
+    Ctx extends { requestId: string } & object = AnyContext & { requestId: string },
+>(options: RequestLoggerOptions = {}): RequestMiddleware<{}, Ctx> {
+    const activityName = options.activityName ?? 'request'
+
+    return async (ctx, next) => {
+        const clientAddress = getClientAddress(ctx.request, options.trustedClientAddressHeader)
+        const userAgent = ctx.request.headers.get('user-agent') ?? undefined
+        const activity = ctx.logger.startActivity(activityName, {
+            ...(clientAddress == null ? {} : { 'client.address': clientAddress }),
+            ...(userAgent == null ? {} : { 'user_agent.original': userAgent }),
+        })
+        ctx.logger = activity.logger
+
+        try {
+            const response = await next()
+            const bodySize = getResponseBodySize(response)
+            const level =
+                typeof options.completionLevel === 'function'
+                    ? options.completionLevel(response)
+                    : (options.completionLevel ?? defaultCompletionLevel(response))
+            activity.end({
+                context: {
+                    ...HTTP_SERVER_REQUEST_EVENT,
+                    'http.response.status_code': response.status,
+                    ...(bodySize == null ? {} : { 'http.response.body.size': bodySize }),
+                },
+                level,
+            })
+            return response
+        } catch (error) {
+            activity.end({
+                context: HTTP_SERVER_REQUEST_EVENT,
+                data: [error],
+                level: LogLevel.ERROR,
+            })
+            throw error
+        }
+    }
+}

package/src/router/middleware/start-time-ctx.ts

@@ -0,0 +1,5 @@
+import type { ContextMiddleware } from '../types'
+
+export const startTimeCtx = (): ContextMiddleware<{ startTime: number }> => (ctx) => {
+    ctx.startTime = Date.now()
+}