request-scope-api 1.0.0

package/dist/esm/middleware.js

@@ -0,0 +1,193 @@
+/**
+ * RequestScope — Core middleware factory.
+ *
+ * Provides:
+ *   - requestscope(config) — Express middleware factory that validates config,
+ *     instantiates the appropriate storage adapter, creates AsyncQueue and
+ *     RetentionScheduler, and returns a request handler.
+ *   - errorHandler — 4-arity error middleware that attaches error data to
+ *     the request for capture by the finish handler.
+ *
+ * Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 2.2, 4.1, 4.2, 4.3, 5.1
+ */
+import { validateConfig, applyDefaults, buildSensitiveFieldSet } from './config';
+import { MongoAdapter } from './adapters/mongo.adapter';
+import { MySQLAdapter } from './adapters/mysql.adapter';
+import { PgAdapter } from './adapters/pg.adapter';
+import { AsyncQueue } from './queue';
+import { RetentionScheduler } from './retention';
+import { bufferRequestBody, wrapResponse, ERROR_DATA_SYMBOL } from './capture';
+import { createDashboardRouter } from './dashboard/router';
+// ---------------------------------------------------------------------------
+// Factory function
+// ---------------------------------------------------------------------------
+/**
+ * Creates and returns an Express middleware that captures HTTP requests.
+ *
+ * Validation and initialization:
+ *   1. Calls `validateConfig()`, `applyDefaults()`, and `buildSensitiveFieldSet()`
+ *      synchronously; throws on any validation error.
+ *   2. Instantiates the correct `StorageAdapter` based on `storage.type` (unless adapter is provided).
+ *   3. Calls `adapter.initialize()` asynchronously; logs errors to `stderr`
+ *      without throwing (middleware continues to function even if storage fails).
+ *   4. Creates `AsyncQueue` and `RetentionScheduler`; starts both.
+ *   5. Attaches queue `drain()` to `process.on('SIGTERM')` and
+ *      `process.on('SIGINT')` for graceful shutdown.
+ *
+ * Request handling:
+ *   - Checks `ignore` list; skips capture and calls `next()` if matched.
+ *   - Buffers request body via `bufferRequestBody()`.
+ *   - Wraps response via `wrapResponse()` to accumulate response chunks.
+ *   - On response finish, builds `RequestRecord` and enqueues it.
+ *
+ * @param config - RequestScope configuration object
+ * @param adapter - Optional storage adapter instance (for sharing with dashboard)
+ * @returns Express RequestHandler middleware
+ */
+export function requestscope(config, adapter) {
+    // 1. Validate and apply defaults synchronously
+    validateConfig(config);
+    applyDefaults(config);
+    const sensitiveFields = buildSensitiveFieldSet(config);
+    // 2. Instantiate the appropriate storage adapter (if not provided)
+    if (!adapter) {
+        switch (config.storage.type) {
+            case 'mongodb':
+                adapter = new MongoAdapter(config.storage);
+                break;
+            case 'mysql':
+                adapter = new MySQLAdapter(config.storage);
+                break;
+            case 'postgresql':
+                adapter = new PgAdapter(config.storage);
+                break;
+            default:
+                // This should never happen due to validateConfig, but TypeScript needs it
+                throw new Error(`Unsupported storage type: ${config.storage.type}`);
+        }
+    }
+    // 3. Initialize adapter asynchronously (log errors, don't throw)
+    void adapter.initialize().catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[RequestScope] Failed to initialize storage adapter: ${message}\n`);
+    });
+    // 4. Create and start AsyncQueue and RetentionScheduler
+    const queue = new AsyncQueue(adapter);
+    const retentionDays = config.retentionDays ?? 30;
+    const retentionScheduler = new RetentionScheduler(adapter, retentionDays);
+    retentionScheduler.start();
+    // 5. Attach graceful shutdown handlers
+    const shutdown = async () => {
+        retentionScheduler.stop();
+        await queue.drain(10000);
+        queue.destroy();
+    };
+    process.on('SIGTERM', () => {
+        void shutdown();
+    });
+    process.on('SIGINT', () => {
+        void shutdown();
+    });
+    // 6. Return the request handler middleware
+    return async (req, res, next) => {
+        // Check ignore list
+        const ignoreList = config.ignore ?? [];
+        const url = req.originalUrl || req.url || '/';
+        // Always ignore dashboard routes
+        if (url.startsWith('/requestscope')) {
+            next();
+            return;
+        }
+        if (ignoreList.some((pattern) => url === pattern || url.startsWith(pattern))) {
+            next();
+            return;
+        }
+        try {
+            // Buffer request body
+            const { body: requestBody, bodySize: requestBodySize, clientIp } = await bufferRequestBody(req);
+            // Wrap response to capture response data
+            wrapResponse(res, req, requestBody, requestBodySize, clientIp, sensitiveFields, (record) => queue.enqueue(record));
+        }
+        catch (err) {
+            // If capture fails, log and continue without disrupting the request
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[RequestScope] Capture error: ${message}\n`);
+        }
+        next();
+    };
+}
+// ---------------------------------------------------------------------------
+// Setup function
+// ---------------------------------------------------------------------------
+/**
+ * Sets up RequestScope middleware and automatically mounts the dashboard at /requestscope.
+ *
+ * This function:
+ *   1. Creates the storage adapter
+ *   2. Sets up the request capture middleware
+ *   3. Automatically mounts the dashboard at /requestscope
+ *
+ * @param app - Express application instance
+ * @param config - RequestScope configuration object
+ */
+export function setup(app, config) {
+    // Validate and apply defaults
+    validateConfig(config);
+    applyDefaults(config);
+    // Instantiate the appropriate storage adapter
+    let adapter;
+    switch (config.storage.type) {
+        case 'mongodb':
+            adapter = new MongoAdapter(config.storage);
+            break;
+        case 'mysql':
+            adapter = new MySQLAdapter(config.storage);
+            break;
+        case 'postgresql':
+            adapter = new PgAdapter(config.storage);
+            break;
+        default:
+            throw new Error(`Unsupported storage type: ${config.storage.type}`);
+    }
+    // Initialize adapter asynchronously
+    void adapter.initialize().catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[RequestScope] Failed to initialize storage adapter: ${message}\n`);
+    });
+    // Set adapter on app for dashboard API to use
+    app.set('requestscopeAdapter', adapter);
+    // Use the middleware with the shared adapter
+    app.use(requestscope(config, adapter));
+    // Mount dashboard at /requestscope
+    app.use('/requestscope', createDashboardRouter(config.dashboard, adapter));
+}
+// ---------------------------------------------------------------------------
+// Error middleware
+// ---------------------------------------------------------------------------
+/**
+ * 4-arity error middleware that attaches error data to the request.
+ *
+ * The error data (message, stack, statusCode) is attached via a Symbol-keyed
+ * property so the response finish handler can include it in the RequestRecord.
+ *
+ * Usage:
+ *   app.use(requestscope(config));
+ *   app.use(errorHandler);
+ *   // ... route handlers that may throw
+ *
+ * @param err - Error object
+ * @param req - Express Request
+ * @param res - Express Response
+ * @param next - Express NextFunction
+ */
+export function errorHandler(err, req, res, next) {
+    const errorData = {
+        message: err.message,
+        stack: err.stack || '',
+        statusCode: err.statusCode || 500,
+    };
+    req[ERROR_DATA_SYMBOL] = errorData;
+    // Pass error to next error handler in the chain
+    next(err);
+}
+//# sourceMappingURL=middleware.js.map

package/dist/esm/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/middleware.ts"],"names":[],"mappings":"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"}

package/dist/esm/queue.js

@@ -0,0 +1,110 @@
+/**
+ * AsyncQueue — In-process batch write queue.
+ *
+ * Decouples the hot-path enqueue (synchronous, ≤1 ms) from database writes,
+ * which happen asynchronously in configurable batches. Fault isolation is
+ * total: adapter failures are caught, logged to stderr, and discarded so
+ * they never propagate to the caller.
+ */
+export class AsyncQueue {
+    constructor(adapter, batchSize = 50, flushIntervalMs = 5000, maxCapacity = 10000) {
+        this.adapter = adapter;
+        this.batchSize = batchSize;
+        this.flushIntervalMs = flushIntervalMs;
+        this.maxCapacity = maxCapacity;
+        this.items = [];
+        this.flushTimer = null;
+        this.isFlushing = false;
+        // Start the periodic flush timer immediately on construction.
+        this.flushTimer = setInterval(() => {
+            void this.flush();
+        }, this.flushIntervalMs);
+        // Allow the Node.js process to exit even if this timer is still active.
+        if (this.flushTimer.unref) {
+            this.flushTimer.unref();
+        }
+    }
+    /**
+     * Synchronously adds a record to the queue.
+     *
+     * If the queue is at capacity, the record is discarded and a warning is
+     * written to stderr. If the queue has reached `batchSize` after this push,
+     * a flush is triggered immediately (fire-and-forget).
+     */
+    enqueue(record) {
+        if (this.items.length >= this.maxCapacity) {
+            process.stderr.write(`[RequestScope] Queue capacity exceeded (max ${this.maxCapacity}). ` +
+                `Record for ${record.method} ${record.url} discarded.\n`);
+            return;
+        }
+        this.items.push(record);
+        if (this.items.length >= this.batchSize) {
+            void this.flush();
+        }
+    }
+    /**
+     * Flushes up to `batchSize` items from the front of the queue.
+     *
+     * A guard (`isFlushing`) prevents concurrent flushes. The splice is
+     * performed atomically before the async adapter call so no records are
+     * lost even if the adapter rejects. On failure the batch is discarded
+     * and the error is written to stderr.
+     */
+    async flush() {
+        if (this.isFlushing || this.items.length === 0) {
+            return;
+        }
+        this.isFlushing = true;
+        // Atomically remove up to batchSize items from the front of the array.
+        const batch = this.items.splice(0, this.batchSize);
+        try {
+            await this.adapter.insert(batch);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[RequestScope] adapter.insert() failed — batch of ${batch.length} record(s) discarded. ` +
+                `Error: ${message}\n`);
+        }
+        finally {
+            this.isFlushing = false;
+        }
+    }
+    /**
+     * Flushes all remaining items in the queue, waiting at most `timeoutMs`
+     * milliseconds. Any items that could not be flushed before the timeout
+     * are logged to stderr.
+     *
+     * Used during graceful shutdown (SIGTERM / SIGINT).
+     */
+    async drain(timeoutMs = 10000) {
+        const deadline = Date.now() + timeoutMs;
+        while (this.items.length > 0) {
+            if (Date.now() >= deadline) {
+                const remaining = this.items.splice(0);
+                process.stderr.write(`[RequestScope] drain() timed out — ${remaining.length} record(s) could not be flushed:\n` +
+                    remaining
+                        .map((r) => `  ${r.method} ${r.url} @ ${r.timestamp}`)
+                        .join('\n') +
+                    '\n');
+                return;
+            }
+            // Wait for any in-progress flush to complete before starting the next.
+            if (this.isFlushing) {
+                await new Promise((resolve) => setTimeout(resolve, 10));
+                continue;
+            }
+            await this.flush();
+        }
+    }
+    /**
+     * Clears the periodic flush timer. Call this to allow the Node.js process
+     * to exit cleanly, or when the queue is no longer needed.
+     */
+    destroy() {
+        if (this.flushTimer !== null) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/esm/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../src/queue.ts"],"names":[],"mappings":"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"}

package/dist/esm/retention.js

@@ -0,0 +1,60 @@
+/**
+ * RetentionScheduler — automatically purges records older than the configured
+ * retention window by calling `adapter.deleteOlderThan()` once per day.
+ *
+ * Requirements: 7.1, 7.2, 7.4, 7.5
+ */
+const TWENTY_FOUR_HOURS_MS = 24 * 60 * 60 * 1000; // 86_400_000 ms
+export class RetentionScheduler {
+    constructor(adapter, retentionDays) {
+        this.adapter = adapter;
+        this.retentionDays = retentionDays;
+        this.intervalHandle = null;
+    }
+    /**
+     * Runs the retention job immediately, then schedules it to repeat every 24 h.
+     * Calling `start()` more than once has no additional effect until `stop()` is
+     * called first (the previous interval is replaced by the new one).
+     */
+    start() {
+        // Run an initial sweep right away so old records are not kept waiting up
+        // to 24 h after the server first starts.
+        void this.runOnce();
+        // Replace any previously-running interval.
+        if (this.intervalHandle !== null) {
+            clearInterval(this.intervalHandle);
+        }
+        this.intervalHandle = setInterval(() => {
+            void this.runOnce();
+        }, TWENTY_FOUR_HOURS_MS);
+    }
+    /**
+     * Stops the scheduled retention job.  Inflight `runOnce()` calls are allowed
+     * to complete naturally because they are fire-and-forget.
+     */
+    stop() {
+        if (this.intervalHandle !== null) {
+            clearInterval(this.intervalHandle);
+            this.intervalHandle = null;
+        }
+    }
+    /**
+     * Computes the cutoff date from `retentionDays` and asks the adapter to
+     * delete every record older than that date.  Any error is logged to `stderr`
+     * but never rethrown so the scheduler stays alive for the next tick.
+     */
+    async runOnce() {
+        const cutoff = new Date(Date.now() - this.retentionDays * 86400000);
+        try {
+            const deleted = await this.adapter.deleteOlderThan(cutoff);
+            if (deleted > 0) {
+                process.stderr.write(`[RequestScope] RetentionScheduler: deleted ${deleted} record(s) older than ${cutoff.toISOString()}\n`);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[RequestScope] RetentionScheduler error: ${message}\n`);
+        }
+    }
+}
+//# sourceMappingURL=retention.js.map

package/dist/esm/retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.js","sourceRoot":"","sources":["../../src/retention.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,oBAAoB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,gBAAgB;AAElE,MAAM,OAAO,kBAAkB;IAG7B,YACmB,OAAuB,EACvB,aAAqB;QADrB,YAAO,GAAP,OAAO,CAAgB;QACvB,kBAAa,GAAb,aAAa,CAAQ;QAJhC,mBAAc,GAA0C,IAAI,CAAC;IAKlE,CAAC;IAEJ;;;;OAIG;IACH,KAAK;QACH,yEAAyE;QACzE,yCAAyC;QACzC,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;QAEpB,2CAA2C;QAC3C,IAAI,IAAI,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;YACjC,aAAa,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACrC,CAAC;QAED,IAAI,CAAC,cAAc,GAAG,WAAW,CAAC,GAAG,EAAE;YACrC,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;QACtB,CAAC,EAAE,oBAAoB,CAAC,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,IAAI;QACF,IAAI,IAAI,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;YACjC,aAAa,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YACnC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC7B,CAAC;IACH,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,OAAO;QACnB,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,aAAa,GAAG,QAAU,CAAC,CAAC;QACtE,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;YAC3D,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;gBAChB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,8CAA8C,OAAO,yBAAyB,MAAM,CAAC,WAAW,EAAE,IAAI,CACvG,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,4CAA4C,OAAO,IAAI,CACxD,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

package/dist/esm/types.js

@@ -0,0 +1,8 @@
+/**
+ * RequestScope — All exported TypeScript interfaces.
+ *
+ * This file is the single source of truth for every public type in the library.
+ * All interfaces are written to compile under `strict: true` with zero errors.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/types/adapters/adapter.interface.d.ts

@@ -0,0 +1,7 @@
+/**
+ * StorageAdapter interface — the contract all storage adapters must implement.
+ *
+ * Adapters should import from this file so they stay decoupled from the
+ * top-level types module while still satisfying the shared contract.
+ */
+export type { StorageAdapter, RequestRecord, QueryFilters } from '../types';

package/dist/types/adapters/mongo.adapter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * MongoAdapter — MongoDB implementation of the StorageAdapter interface.
+ *
+ * Collection: `requestscope_records`
+ * `_id` is set to the record's UUID string for direct look-ups.
+ * A descending index on `timestamp` is created at initialization for sort
+ * performance and retention queries.
+ */
+import type { StorageAdapter, RequestRecord, QueryFilters, StorageConfig } from '../types';
+export declare class MongoAdapter implements StorageAdapter {
+    private readonly config;
+    private client;
+    private collection;
+    constructor(config: StorageConfig);
+    initialize(): Promise<void>;
+    insert(records: RequestRecord[]): Promise<void>;
+    query(filters: QueryFilters, pagination: {
+        page: number;
+        pageSize: number;
+    }): Promise<{
+        records: RequestRecord[];
+        total: number;
+    }>;
+    deleteOlderThan(date: Date): Promise<number>;
+}

package/dist/types/adapters/mysql.adapter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * MySQLAdapter — StorageAdapter implementation for MySQL using mysql2/promise.
+ *
+ * Compiles under `strict: true` with zero errors.
+ * Requirements: 1.6, 1.7, 6.1, 6.3, 6.5, 7.4
+ */
+import type { StorageAdapter, RequestRecord, QueryFilters } from '../types';
+import type { StorageConfig } from '../types';
+export declare class MySQLAdapter implements StorageAdapter {
+    private pool;
+    private readonly config;
+    constructor(config: StorageConfig);
+    initialize(): Promise<void>;
+    insert(records: RequestRecord[]): Promise<void>;
+    query(filters: QueryFilters, pagination: {
+        page: number;
+        pageSize: number;
+    }): Promise<{
+        records: RequestRecord[];
+        total: number;
+    }>;
+    deleteOlderThan(date: Date): Promise<number>;
+    private getPool;
+}

package/dist/types/adapters/pg.adapter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * PgAdapter — StorageAdapter implementation for PostgreSQL using pg.
+ *
+ * Compiles under `strict: true` with zero errors.
+ * Requirements: 1.6, 1.7, 6.1, 6.4, 6.5, 7.4
+ */
+import type { StorageAdapter, RequestRecord, QueryFilters, StorageConfig } from '../types';
+export declare class PgAdapter implements StorageAdapter {
+    private pool;
+    private readonly config;
+    constructor(config: StorageConfig);
+    initialize(): Promise<void>;
+    /**
+     * Batch-inserts records using unnest arrays for efficient multi-row inserts.
+     *
+     * INSERT INTO requestscope_records (col1, col2, ...)
+     * SELECT * FROM unnest($1::varchar[], $2::text[], ...)
+     */
+    insert(records: RequestRecord[]): Promise<void>;
+    query(filters: QueryFilters, pagination: {
+        page: number;
+        pageSize: number;
+    }): Promise<{
+        records: RequestRecord[];
+        total: number;
+    }>;
+    deleteOlderThan(date: Date): Promise<number>;
+    private getPool;
+}

package/dist/types/capture.d.ts

@@ -0,0 +1,88 @@
+/**
+ * RequestScope — Capture layer, request and response sides.
+ *
+ * Provides:
+ *   - parseClientIp(req)    — extract client IP from headers/socket
+ *   - bufferRequestBody(req) — consume request stream, buffer ≤50 KB,
+ *                              attempt JSON / URL-encoded parse, return
+ *                              body string + original byte size + client IP.
+ *   - wrapResponse(res)     — monkey-patch res.write/res.end to accumulate
+ *                              response chunks, cap at 100 KB, return wrapper
+ *                              with finish event handler that builds RequestRecord.
+ *
+ * Uses Node.js built-ins only (no external deps).
+ * Compiles under strict: true.
+ */
+import { IncomingMessage, ServerResponse } from 'http';
+import type { RequestRecord } from './types';
+/**
+ * Extracts the client IP address from the request.
+ *
+ * Prefers the first entry of the `X-Forwarded-For` header (proxy-aware),
+ * falling back to `req.socket.remoteAddress`. Returns `"0.0.0.0"` when
+ * neither is available.
+ *
+ * @param req  Node.js IncomingMessage (or Express Request)
+ */
+export declare function parseClientIp(req: IncomingMessage): string;
+/**
+ * Consumes the `req` stream and buffers up to {@link MAX_BODY_BYTES} bytes.
+ *
+ * Behaviour:
+ * 1. Collects `Buffer` chunks from `data` events; tracks total byte length.
+ * 2. On `end`: concatenates chunks, slices to MAX_BODY_BYTES; appends
+ *    `"[truncated]"` when the original size exceeded the limit.
+ * 3. Attempts `JSON.parse` → stores normalised JSON string.
+ * 4. On JSON failure, attempts `URLSearchParams` parse → stores JSON map.
+ * 5. On both failures, stores the raw string as-is.
+ * 6. On stream `error`, resolves with `{ body: '', bodySize: 0, clientIp }`.
+ *
+ * @param req  Node.js IncomingMessage (or Express Request)
+ * @returns    Resolved promise with body string, original byte size, and IP.
+ */
+export declare function bufferRequestBody(req: IncomingMessage): Promise<{
+    body: string;
+    bodySize: number;
+    clientIp: string;
+}>;
+/**
+ * Symbol used to attach error data to the request object for the finish handler.
+ */
+export declare const ERROR_DATA_SYMBOL: unique symbol;
+/**
+ * Error data attached to the request via the error middleware.
+ */
+export interface ErrorData {
+    message: string;
+    stack: string;
+    statusCode: number;
+}
+/**
+ * Wraps a ServerResponse to accumulate response chunks.
+ *
+ * Monkey-patches `res.write` and `res.end` to accumulate response body chunks.
+ * Caps the buffer at MAX_RESPONSE_BODY_BYTES; beyond that stores first
+ * MAX_RESPONSE_BODY_BYTES bytes + "[truncated]". Records responseBodySize as
+ * the original Content-Length or accumulated size.
+ *
+ * On the `finish` event, builds a RequestRecord with:
+ * - UUIDv4 id
+ * - process.hrtime-based responseTime
+ * - maskObject() applied to request headers and request body
+ * - maskObject() applied to response headers
+ * - Enqueues the record synchronously via the provided callback
+ *
+ * If wrapping fails (stream/binary response), sets responseBody = "",
+ * reads Content-Length header as responseBodySize, and calls original write/end
+ * without disrupting the response.
+ *
+ * @param res - Node.js ServerResponse (or Express Response)
+ * @param req - Node.js IncomingMessage (or Express Request)
+ * @param requestBody - Buffered request body string
+ * @param requestBodySize - Original request body byte size
+ * @param clientIp - Client IP address
+ * @param sensitiveFields - Set of sensitive field names to mask
+ * @param enqueueRecord - Callback to enqueue the RequestRecord synchronously
+ * @returns The wrapped response (same object, with patched methods)
+ */
+export declare function wrapResponse(res: ServerResponse, req: IncomingMessage, requestBody: string, requestBodySize: number, clientIp: string, sensitiveFields: Set<string>, enqueueRecord: (record: RequestRecord) => void): ServerResponse;

package/dist/types/config.d.ts

@@ -0,0 +1,38 @@
+/**
+ * RequestScope — Configuration validation, defaults, and sensitive-field set.
+ *
+ * All validation errors are thrown synchronously so that `requestscope()` fails
+ * fast at startup before any middleware is registered.
+ */
+import type { RequestScopeConfig } from './types';
+/**
+ * Fills in missing optional fields with their documented default values.
+ * Mutates the config object in place and returns it for chaining.
+ *
+ * Defaults applied:
+ *   retentionDays  → 30
+ *   ignore         → []
+ *   maskFields     → []
+ *   storage.poolSize → 5
+ *   storage.ssl    → false
+ */
+export declare function applyDefaults(config: RequestScopeConfig): RequestScopeConfig;
+/**
+ * Validates the configuration object and throws a synchronous `Error` for
+ * any invalid value.
+ *
+ * Checks (in order):
+ *   1. `storage.type` must be one of the supported values.
+ *   2. MongoDB requires `storage.uri`.
+ *   3. MySQL / PostgreSQL require `host`, `database`, `username`, `password`.
+ *   4. `retentionDays` (when provided) must be a positive integer in [1, 365].
+ */
+export declare function validateConfig(config: RequestScopeConfig): void;
+/**
+ * Constructs the `Set<string>` of sensitive field names by forming the union
+ * of the built-in defaults and any user-supplied `maskFields`.
+ *
+ * All names are lowercased so that lookups from `maskObject()` can compare
+ * case-insensitively by lowercasing the inspected key.
+ */
+export declare function buildSensitiveFieldSet(config: RequestScopeConfig): Set<string>;

package/dist/types/dashboard/api.d.ts

@@ -0,0 +1,49 @@
+/**
+ * RequestScope — Dashboard API handlers.
+ *
+ * Provides Express route handlers for the dashboard:
+ *   - GET /api/records — List records with filtering, sorting, and pagination
+ *   - GET /api/records/:id — Get a single record by ID
+ *
+ * Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6
+ */
+import type { Request, Response } from 'express';
+/**
+ * GET /api/records handler.
+ *
+ * Query parameters:
+ *   - search: string (optional) — case-insensitive substring match on url
+ *   - startDate: string (optional) — ISO 8601 timestamp, inclusive lower bound
+ *   - endDate: string (optional) — ISO 8601 timestamp, inclusive upper bound
+ *   - statusCodeGroup: string (optional) — '2xx', '3xx', '4xx', or '5xx'
+ *   - statusCode: number (optional) — exact status code match
+ *   - method: string (optional) — exact HTTP method match (case-insensitive)
+ *   - sortBy: string (optional) — 'timestamp', 'responseTime', or 'statusCode'
+ *   - sortOrder: string (optional) — 'asc' or 'desc'
+ *   - page: number (optional) — page number, default 1
+ *   - pageSize: number (optional) — page size, default 25
+ *
+ * Returns:
+ *   - 200 with { records: RequestRecord[], total: number }
+ *   - 400 for malformed query parameters
+ */
+export declare function getRecords(req: Request, res: Response): Promise<void>;
+/**
+ * GET /api/records/:id handler.
+ *
+ * Returns:
+ *   - 200 with the RequestRecord
+ *   - 404 if the record is not found
+ *   - 400 for malformed ID
+ */
+export declare function getRecordById(req: Request, res: Response): Promise<void>;
+/**
+ * DELETE /api/records handler.
+ *
+ * Deletes all records from the database.
+ *
+ * Returns:
+ *   - 200 with { deleted: number }
+ *   - 500 for server errors
+ */
+export declare function deleteAllRecords(req: Request, res: Response): Promise<void>;