@db3.ai/app 0.1.0-beta.1 → 0.1.0-beta.4

package/dist/logging/drivers/PinoLoggerDriver.js

@@ -3,6 +3,8 @@ import { fileURLToPath } from 'node:url';
 import { hostname } from 'node:os';
 import pino from 'pino';
 import { isInteractiveDevelopmentEnvironment } from '../../devtools/index.js';
+import { EmailLogTransport } from '../transports/EmailLogTransport.js';
+import { acquireDevelopmentConsole } from '../acquireDevelopmentConsole.js';
 const defaultRedactions = [
     'password',
     '*.password',
@@ -24,6 +26,8 @@ const defaultRedactions = [
 export class PinoLoggerDriver {
     logger;
     #transport;
+    #emails = [];
+    #console;
     #closed = false;
     #closing = false;
     #closePromise = null;
@@ -32,10 +36,24 @@ export class PinoLoggerDriver {
      *
      * @param options - Framework logging configuration.
      * @param destination - Optional direct destination used by focused tests.
+     * @param mail - Application-owned mail service used by the email destination.
      */
-    constructor(options = {}, destination) {
+    constructor(options = {}, destination, mail) {
         const environment = options.environment ?? process.env.NODE_ENV ?? 'development';
         const level = resolveLogLevel(options, process.env);
+        if ((options.transports?.filter(transport => transport.type === 'console').length ?? 0) > 1)
+            throw new Error('Configure at most one console log transport.');
+        for (const transport of options.transports ?? []) {
+            if (!['console', 'file', 'email', 'devtools'].includes(transport.type))
+                throw new Error('Unknown logging transport type.');
+            if (transport.level !== undefined && !isLogLevel(transport.level))
+                throw new Error('Invalid logging transport level.');
+            if (transport.type === 'email' && transport.level !== 'silent') {
+                if (!mail)
+                    throw new Error('Email logging requires an application Mail resolver.');
+                this.#emails.push({ level: transport.level ?? 'error', stream: new EmailLogTransport(transport, mail) });
+            }
+        }
         const source = options.source
             ?? process.env.PLATFORM_LOG_SOURCE
             ?? process.env.npm_package_name
@@ -58,28 +76,51 @@ export class PinoLoggerDriver {
         };
         if (destination) {
             this.#transport = null;
-            this.logger = pino(pinoOptions, destination);
+            this.logger = pino(pinoOptions, this.#destinations(destination));
+            return;
+        }
+        const format = options.consoleFormat ?? process.env.PLATFORM_LOG_FORMAT ?? 'auto';
+        if (!['auto', 'pretty', 'json'].includes(format))
+            throw new Error(`Invalid PLATFORM_LOG_FORMAT value "${format}". Use auto, pretty, or json.`);
+        const consoleTransport = options.transports?.find(transport => transport.type === 'console');
+        const consoleEnabled = options.transports ? Boolean(consoleTransport) : options.console !== false;
+        const pretty = consoleEnabled && consoleTransport?.level !== 'silent' && level !== 'silent' && (format === 'pretty' || (format === 'auto' && isInteractiveDevelopmentEnvironment(environment) && Boolean(process.stdout.isTTY)));
+        const targets = transportTargets(pretty ? { ...options, console: false, transports: options.transports?.filter(transport => transport.type !== 'console') } : options, level, environment, process.env);
+        if (pretty) {
+            this.#transport = targets.length ? pino.transport({ targets }) : null;
+            this.#transport?.on('error', reportTransportError);
+            this.#console = acquireDevelopmentConsole();
+            const streams = [{ level: (consoleTransport?.level === 'silent' ? 'trace' : consoleTransport?.level) ?? level, stream: this.#console.console }];
+            if (this.#transport)
+                streams.push({ level: 'trace', stream: this.#transport });
+            this.logger = pino(pinoOptions, this.#destinations(pino.multistream(streams)));
             return;
         }
-        const targets = transportTargets(options, level, environment, process.env);
         if (targets.length === 0) {
             this.#transport = null;
             this.logger = pino({
                 ...pinoOptions,
-                level: 'silent',
-            });
+                level: this.#emails.length ? level : 'silent',
+            }, this.#emails.length ? this.#destinations({ /** Discards the disabled console destination. */ write() { } }) : undefined);
             return;
         }
-        if (targets.length === 1 && targets[0]?.target === 'pino/file') {
+        if (targets.length === 1 && targets[0]?.target === 'pino/file' && targets[0]?.options?.destination === 1 && targets[0]?.level === level) {
             this.#transport = null;
-            this.logger = pino(pinoOptions);
+            this.logger = pino(pinoOptions, this.#destinations(process.stdout));
             return;
         }
         this.#transport = pino.transport({
             targets,
         });
         this.#transport.on('error', reportTransportError);
-        this.logger = pino(pinoOptions, this.#transport);
+        this.logger = pino(pinoOptions, this.#destinations(this.#transport));
+    }
+    /** Fans already serialized and redacted records out to ordinary destinations and operator email. */
+    #destinations(destination) {
+        return this.#emails.length ? pino.multistream([
+            { level: 'trace', stream: destination },
+            ...this.#emails,
+        ]) : destination;
     }
     /**
      * Waits until Pino has handed accepted records to its destination.
@@ -94,7 +135,8 @@ export class PinoLoggerDriver {
                 this.#transport.ref();
             }
             await new Promise((resolve, reject) => {
-                this.logger.flush((error) => {
+                const destination = this.#transport ?? this.logger;
+                destination.flush((error) => {
                     if (error) {
                         reject(error);
                         return;
@@ -102,6 +144,8 @@ export class PinoLoggerDriver {
                     resolve();
                 });
             });
+            await this.#console?.console.flush();
+            await Promise.all(this.#emails.map(email => email.stream.flush()));
         }
         finally {
             if (!this.#closing) {
@@ -123,6 +167,7 @@ export class PinoLoggerDriver {
         if (this.#closed)
             return;
         this.#closing = true;
+        this.#console?.release();
         await this.flush();
         this.#closed = true;
         if (!this.#transport)
@@ -162,15 +207,29 @@ function transportTargets(options, level, environment, env) {
     if (level === 'silent')
         return [];
     const targets = [];
+    if (options.transports) {
+        for (const transport of options.transports) {
+            const minimum = transport.level ?? level;
+            if (minimum === 'silent')
+                continue;
+            if (transport.type === 'console')
+                targets.push({ target: 'pino/file', level: minimum, options: { destination: 1 } });
+            if (transport.type === 'file') {
+                if (!transport.destination)
+                    throw new Error('File logging requires a destination.');
+                targets.push({ target: 'pino/file', level: minimum, options: { destination: transport.destination, mkdir: true } });
+            }
+            if (transport.type === 'devtools')
+                targets.push({ target: devtoolsTransportTarget(), level: minimum, options: transport.options ?? {} });
+        }
+        return targets;
+    }
     if (options.console !== false) {
-        targets.push({
-            target: 'pino/file',
-            level,
-            options: {
-                destination: 1,
-            },
-        });
+        targets.push({ target: 'pino/file', level, options: { destination: 1 } });
     }
+    const file = options.file ?? env.PLATFORM_LOG_FILE;
+    if (file)
+        targets.push({ target: 'pino/file', level, options: { destination: file, mkdir: true } });
     if (devtoolsEnabled(options.devtools, environment, env)) {
         targets.push({
             target: devtoolsTransportTarget(),

package/dist/logging/formatLogEmail.d.ts

@@ -0,0 +1,4 @@
+import type { MailMessage } from '../mail/index.js';
+import type { EmailLogOptions } from './contracts/index.js';
+/** Formats a redacted log record without copying arbitrary nested payloads or exception properties into email. */
+export declare function formatLogEmail(record: Record<string, unknown>, options: EmailLogOptions): MailMessage;

package/dist/logging/formatLogEmail.js

@@ -0,0 +1,21 @@
+import { redactLogEmail } from './redactLogEmail.js';
+/** Formats a redacted log record without copying arbitrary nested payloads or exception properties into email. */
+export function formatLogEmail(record, options) {
+    const context = Object.fromEntries(Object.entries(record).filter(([key, value]) => key !== 'err' && (value === null || ['string', 'number', 'boolean'].includes(typeof value))));
+    const sections = [`Log context (JSON):\n${JSON.stringify(context, null, 2)}`];
+    let error = record.err;
+    if (typeof error === 'string')
+        sections.push(`Exception: ${error}`);
+    for (let depth = 0; error && typeof error === 'object' && depth < 4; depth++) {
+        const value = error;
+        sections.push(`${depth ? 'Caused by' : 'Exception'}: ${String(value.type ?? value.name ?? 'Error')}\nMessage: ${String(value.message ?? 'Unavailable')}\nStack trace:\n${String(value.stack ?? 'Unavailable')}`);
+        error = value.cause;
+    }
+    const text = redactLogEmail(sections.join('\n\n'));
+    const subject = redactLogEmail(`${options.subjectPrefix ?? 'Application error'}: ${String(record.msg ?? 'Exception logged')}`).replace(/[\r\n]/g, ' ').slice(0, 200);
+    return { to: options.to, subject, text, html: `<pre style="white-space:pre-wrap">${escapeHtml(text)}</pre>` };
+}
+/** Escapes log text as inert HTML content in the email's preformatted body. */
+function escapeHtml(text) {
+    return text.replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[character]);
+}

package/dist/logging/highlightQueueMessage.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Colours the parts of a queue log message that are scanned most: the state
+ * verb after `[queue] ` (blue in progress, green done, yellow retrying, red
+ * failed) and job labels (bold magenta). Other messages are returned unchanged
+ * apart from job labels.
+ *
+ * @param message - Plain log message.
+ * @param paint - Wraps text in an SGR code, such as `'32'` or `'1;35'`.
+ * @returns The message with colour codes.
+ */
+export declare function highlightQueueMessage(message: string, paint: (text: string, code: string) => string): string;

package/dist/logging/highlightQueueMessage.js

@@ -0,0 +1,36 @@
+/** Terminal colour for each queue state verb at the start of a `[queue]` message. */
+const STATES = [
+    [/^(Claimed|Running|Dispatched)\b/, '34'],
+    [/^(Processed|Retried)\b/, '32'],
+    [/^(Released|Deferred)\b/, '33'],
+    [/^(Failed|Lost lease|Stopped fenced)\b/, '31'],
+];
+/** A job label such as `CollectKeywordRanksJob#5249`. */
+const JOB_LABEL = /\b[A-Z][A-Za-z0-9_]*#\d+\b/g;
+/**
+ * Colours the parts of a queue log message that are scanned most: the state
+ * verb after `[queue] ` (blue in progress, green done, yellow retrying, red
+ * failed) and job labels (bold magenta). Other messages are returned unchanged
+ * apart from job labels.
+ *
+ * @param message - Plain log message.
+ * @param paint - Wraps text in an SGR code, such as `'32'` or `'1;35'`.
+ * @returns The message with colour codes.
+ */
+export function highlightQueueMessage(message, paint) {
+    let prefix = '';
+    let rest = message;
+    if (rest.startsWith('[queue] ')) {
+        prefix = '[queue] ';
+        rest = rest.slice(prefix.length);
+        for (const [pattern, code] of STATES) {
+            const match = pattern.exec(rest);
+            if (match) {
+                prefix += paint(match[0], code);
+                rest = rest.slice(match[0].length);
+                break;
+            }
+        }
+    }
+    return prefix + rest.replace(JOB_LABEL, label => paint(label, '1;35'));
+}

package/dist/logging/httpBodyCapture.d.ts

@@ -0,0 +1,24 @@
+import type { HttpBodyLog } from './contracts/index.js';
+/**
+ * Captures one request or response body without retaining unbounded payloads.
+ *
+ * @param payload - Parsed request body or outgoing Fastify payload.
+ * @param contentType - Media type reported by the HTTP message.
+ * @param maxBodyBytes - Maximum UTF-8 bytes retained in the log record.
+ * @returns Bounded body metadata and an inspectable value when safe.
+ */
+export declare function captureBody(payload: unknown, contentType: string | undefined, maxBodyBytes: number): HttpBodyLog;
+/**
+ * Redacts credential-bearing headers before a record reaches Pino.
+ *
+ * @param headers - Fastify request or response header collection.
+ * @returns Header object safe for local request inspection.
+ */
+export declare function redactHeaders(headers: Readonly<Record<string, unknown>>): Record<string, unknown>;
+/**
+ * Converts a Fastify header into one displayable content-type string.
+ *
+ * @param value - Request or response content-type header.
+ * @returns First string value when present.
+ */
+export declare function headerValue(value: unknown): string | undefined;

package/dist/logging/httpBodyCapture.js

@@ -0,0 +1,321 @@
+const maximumCapturedProperties = 2_000;
+const maximumCaptureDepth = 12;
+const maximumHeaderValueLength = 4_096;
+const redactedValue = '[Redacted]';
+/**
+ * Captures one request or response body without retaining unbounded payloads.
+ *
+ * @param payload - Parsed request body or outgoing Fastify payload.
+ * @param contentType - Media type reported by the HTTP message.
+ * @param maxBodyBytes - Maximum UTF-8 bytes retained in the log record.
+ * @returns Bounded body metadata and an inspectable value when safe.
+ */
+export function captureBody(payload, contentType, maxBodyBytes) {
+    if (payload === undefined || payload === null || payload === '') {
+        return {
+            kind: 'empty',
+            contentType,
+        };
+    }
+    if (isStreamLike(payload)) {
+        return {
+            kind: 'stream',
+            contentType,
+            note: 'Streaming response body omitted.',
+        };
+    }
+    if (Buffer.isBuffer(payload) || payload instanceof Uint8Array) {
+        const buffer = Buffer.from(payload);
+        if (!isTextContentType(contentType)) {
+            return {
+                kind: 'binary',
+                contentType,
+                sizeBytes: buffer.byteLength,
+                note: 'Binary body omitted.',
+            };
+        }
+        return captureText(buffer.toString('utf8'), contentType, maxBodyBytes);
+    }
+    if (typeof payload === 'string') {
+        return captureText(payload, contentType, maxBodyBytes);
+    }
+    return captureJson(payload, contentType, maxBodyBytes);
+}
+/**
+ * Captures textual content, parsing JSON so nested secrets can be redacted.
+ *
+ * @param value - Original textual payload.
+ * @param contentType - Media type reported by the HTTP message.
+ * @param maxBodyBytes - Maximum UTF-8 bytes retained in the log record.
+ * @returns Text or JSON body capture.
+ */
+function captureText(value, contentType, maxBodyBytes) {
+    if (isFormContentType(contentType)) {
+        return captureJson(formBodyFromText(value), contentType, maxBodyBytes);
+    }
+    if (isJsonContentType(contentType) || looksLikeJson(value)) {
+        try {
+            return captureJson(JSON.parse(value), contentType, maxBodyBytes);
+        }
+        catch {
+            // Malformed JSON remains useful as bounded response text.
+        }
+    }
+    const sizeBytes = Buffer.byteLength(value);
+    return {
+        kind: 'text',
+        contentType,
+        sizeBytes,
+        truncated: sizeBytes > maxBodyBytes,
+        value: truncateUtf8(value, maxBodyBytes),
+    };
+}
+/**
+ * Converts URL-encoded form text into a shape that supports field redaction.
+ *
+ * Repeated form keys remain arrays so the inspector does not silently discard
+ * submitted values.
+ *
+ * @param value - URL-encoded request body.
+ * @returns Parsed form object suitable for normal JSON sanitization.
+ */
+function formBodyFromText(value) {
+    const captured = {};
+    for (const [key, item] of new URLSearchParams(value)) {
+        const existing = captured[key];
+        if (existing === undefined) {
+            captured[key] = item;
+            continue;
+        }
+        captured[key] = Array.isArray(existing)
+            ? [...existing, item]
+            : [existing, item];
+    }
+    return captured;
+}
+/**
+ * Produces a JSON-safe, recursively redacted representation of a payload.
+ *
+ * @param value - Parsed body value.
+ * @param contentType - Media type reported by the HTTP message.
+ * @param maxBodyBytes - Maximum UTF-8 bytes retained in the log record.
+ * @returns JSON body capture.
+ */
+function captureJson(value, contentType, maxBodyBytes) {
+    const sanitized = sanitizeBodyValue(value, '', {
+        seen: new WeakSet(),
+        remainingProperties: maximumCapturedProperties,
+    });
+    const serialized = JSON.stringify(sanitized);
+    if (serialized === undefined) {
+        return captureText(String(value), contentType, maxBodyBytes);
+    }
+    const sizeBytes = Buffer.byteLength(serialized);
+    return {
+        kind: 'json',
+        contentType,
+        sizeBytes,
+        truncated: sizeBytes > maxBodyBytes,
+        value: sizeBytes > maxBodyBytes
+            ? truncateUtf8(serialized, maxBodyBytes)
+            : sanitized,
+    };
+}
+/**
+ * Recursively removes sensitive fields and bounds complex object traversal.
+ *
+ * @param value - Current body value.
+ * @param key - Owning object key used for sensitive-name detection.
+ * @param state - Shared circular-reference and property-count state.
+ * @param depth - Current traversal depth.
+ * @returns JSON-safe value suitable for structured logging.
+ */
+function sanitizeBodyValue(value, key, state, depth = 0) {
+    if (isSensitiveName(key))
+        return redactedValue;
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (typeof value !== 'object')
+        return String(value);
+    if (state.seen.has(value))
+        return '[Circular]';
+    if (depth >= maximumCaptureDepth)
+        return '[Maximum depth reached]';
+    state.seen.add(value);
+    if (value instanceof Date)
+        return value.toISOString();
+    if (value instanceof Error) {
+        return {
+            name: value.name,
+            message: value.message,
+            stack: value.stack,
+        };
+    }
+    if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+        return `[Binary ${value.byteLength} bytes]`;
+    }
+    if (Array.isArray(value)) {
+        const captured = [];
+        for (const item of value) {
+            if (state.remainingProperties <= 0) {
+                captured.push('[Capture limit reached]');
+                break;
+            }
+            state.remainingProperties -= 1;
+            captured.push(sanitizeBodyValue(item, '', state, depth + 1));
+        }
+        return captured;
+    }
+    const captured = {};
+    for (const [childKey, childValue] of Object.entries(value)) {
+        if (state.remainingProperties <= 0) {
+            captured['[capture]'] = 'Property limit reached';
+            break;
+        }
+        state.remainingProperties -= 1;
+        captured[childKey] = sanitizeBodyValue(childValue, childKey, state, depth + 1);
+    }
+    return captured;
+}
+/**
+ * Redacts credential-bearing headers before a record reaches Pino.
+ *
+ * @param headers - Fastify request or response header collection.
+ * @returns Header object safe for local request inspection.
+ */
+export function redactHeaders(headers) {
+    const captured = {};
+    for (const [name, value] of Object.entries(headers)) {
+        captured[name] = isSensitiveName(name)
+            ? redactedValue
+            : boundedHeaderValue(value);
+    }
+    return captured;
+}
+/**
+ * Bounds one response or request header value.
+ *
+ * @param value - Original Fastify header value.
+ * @returns Original scalar shape with long strings shortened.
+ */
+function boundedHeaderValue(value) {
+    if (typeof value === 'string') {
+        return value.length > maximumHeaderValueLength
+            ? `${value.slice(0, maximumHeaderValueLength)}…`
+            : value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(item => boundedHeaderValue(item));
+    }
+    return value;
+}
+/**
+ * Detects common credential and session field names.
+ *
+ * @param name - Header or JSON property name.
+ * @returns True when the value must be removed from the capture.
+ */
+function isSensitiveName(name) {
+    const normalized = name.toLowerCase().replace(/[-_]/g, '');
+    return normalized === 'authorization'
+        || normalized === 'proxyauthorization'
+        || normalized === 'cookie'
+        || normalized === 'setcookie'
+        || normalized === 'password'
+        || normalized === 'passphrase'
+        || normalized === 'secret'
+        || normalized === 'token'
+        || normalized === 'accesstoken'
+        || normalized === 'refreshtoken'
+        || normalized === 'apikey'
+        || normalized === 'xapikey';
+}
+/**
+ * Converts a Fastify header into one displayable content-type string.
+ *
+ * @param value - Request or response content-type header.
+ * @returns First string value when present.
+ */
+export function headerValue(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value) && typeof value[0] === 'string')
+        return value[0];
+    return undefined;
+}
+/**
+ * Identifies payloads that Fastify will stream instead of serialize.
+ *
+ * @param value - Candidate outgoing response payload.
+ * @returns True when the value exposes the Node stream pipe contract.
+ */
+function isStreamLike(value) {
+    return typeof value === 'object'
+        && value !== null
+        && 'pipe' in value
+        && typeof value.pipe === 'function';
+}
+/**
+ * Identifies media types that are safe to decode as UTF-8 text.
+ *
+ * @param contentType - HTTP content type.
+ * @returns True for JSON and common textual media types.
+ */
+function isTextContentType(contentType) {
+    const normalized = (contentType || '').toLowerCase();
+    return normalized.startsWith('text/')
+        || normalized.includes('json')
+        || normalized.includes('xml')
+        || normalized.includes('javascript')
+        || normalized.includes('x-www-form-urlencoded')
+        || normalized.includes('svg');
+}
+/**
+ * Identifies JSON media types.
+ *
+ * @param contentType - HTTP content type.
+ * @returns True when the media type uses JSON.
+ */
+function isJsonContentType(contentType) {
+    return (contentType || '').toLowerCase().includes('json');
+}
+/**
+ * Identifies URL-encoded form media types requiring field-level redaction.
+ *
+ * @param contentType - HTTP content type.
+ * @returns True when the body uses URL-encoded form syntax.
+ */
+function isFormContentType(contentType) {
+    return (contentType || '').toLowerCase().includes('x-www-form-urlencoded');
+}
+/**
+ * Detects likely JSON text when a content type was omitted or incorrect.
+ *
+ * @param value - Textual payload.
+ * @returns True when the trimmed body begins with a JSON container.
+ */
+function looksLikeJson(value) {
+    const trimmed = value.trim();
+    return (trimmed.startsWith('{') && trimmed.endsWith('}'))
+        || (trimmed.startsWith('[') && trimmed.endsWith(']'));
+}
+/**
+ * Truncates text by UTF-8 byte length rather than JavaScript character count.
+ *
+ * @param value - Original text.
+ * @param maxBytes - Maximum bytes to retain.
+ * @returns Original or shortened UTF-8 text.
+ */
+function truncateUtf8(value, maxBytes) {
+    const buffer = Buffer.from(value);
+    if (buffer.byteLength <= maxBytes)
+        return value;
+    const marker = '…';
+    const contentBytes = Math.max(0, maxBytes - Buffer.byteLength(marker));
+    return `${buffer.subarray(0, contentBytes).toString('utf8')}…`;
+}

package/dist/logging/index.d.ts

@@ -1,3 +1,5 @@
 export * from './contracts/index.js';
 export * from './drivers/index.js';
 export * from './Log.js';
+export * from './DevelopmentConsole.js';
+export * from './registerHttpExchangeMonitor.js';

package/dist/logging/index.js

@@ -1,3 +1,5 @@
 export * from './contracts/index.js';
 export * from './drivers/index.js';
 export * from './Log.js';
+export * from './DevelopmentConsole.js';
+export * from './registerHttpExchangeMonitor.js';

package/dist/logging/redactLogEmail.d.ts

@@ -0,0 +1,2 @@
+/** Redacts common credential forms while preserving exception wording and stack locations. */
+export declare function redactLogEmail(text: string): string;

package/dist/logging/redactLogEmail.js

@@ -0,0 +1,12 @@
+/** Redacts common credential forms while preserving exception wording and stack locations. */
+export function redactLogEmail(text) {
+    return text
+        .replace(/\b(?:Bearer|Basic)\s+[^\s"',;]+/gi, '[REDACTED authorization]')
+        .replace(/\b(?:sk-|sk_|rk_|ghp_|github_pat_)[A-Za-z0-9_-]+/g, '[REDACTED key]')
+        .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, '[REDACTED token]')
+        .replace(/(["']?(?:password|passwd|api[_-]?key|access[_-]?token|refresh[_-]?token|client[_-]?secret|authorization|token|secret)["']?\s*[:=]\s*)(?:"[^"\n]*"|'[^'\n]*'|[^\s,;]+)/gi, '$1[REDACTED]')
+        .replace(/((?:set-cookie|cookie)\s*:\s*)[^\r\n]+/gi, '$1[REDACTED]')
+        .replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s<>"']+/gi, url => url
+        .replace(/(\/\/)[^/@\s]+@/, '$1[REDACTED]@')
+        .replace(/[?#].*$/, '?[REDACTED parameters]'));
+}

package/dist/logging/registerHttpExchangeMonitor.d.ts

@@ -0,0 +1,10 @@
+import type { FastifyInstance } from 'fastify';
+import type * as logging from './contracts/index.js';
+/**
+ * Captures bounded, redacted payloads for grouped console logs and devtools.
+ * Register before routes on a Fastify host using app.log.logger. Fastify's own
+ * arrival/completion records provide lifecycle timing; streams are never consumed.
+ * @param server - Caller-owned HTTP server.
+ * @param options - Development capture and private-route exclusion policy.
+ */
+export declare function registerHttpExchangeMonitor(server: FastifyInstance, options?: logging.HttpExchangeMonitorOptions): void;

package/dist/logging/registerHttpExchangeMonitor.js

@@ -0,0 +1,43 @@
+import { isInteractiveDevelopmentEnvironment } from '../devtools/index.js';
+import { captureBody, headerValue, redactHeaders } from './httpBodyCapture.js';
+/**
+ * Captures bounded, redacted payloads for grouped console logs and devtools.
+ * Register before routes on a Fastify host using app.log.logger. Fastify's own
+ * arrival/completion records provide lifecycle timing; streams are never consumed.
+ * @param server - Caller-owned HTTP server.
+ * @param options - Development capture and private-route exclusion policy.
+ */
+export function registerHttpExchangeMonitor(server, options = {}) {
+    if (options.enabled === false || !isInteractiveDevelopmentEnvironment(options.environment ?? process.env.NODE_ENV))
+        return;
+    const configured = options.maxBodyBytes;
+    const maxBodyBytes = configured && Number.isFinite(configured) && configured > 0 ? Math.min(65536, Math.floor(configured)) : 16384;
+    const ended = new WeakSet();
+    /** Reports one terminal interruption even if timeout and socket close both fire. */
+    function interrupted(request, message) {
+        if (ended.has(request))
+            return;
+        ended.add(request);
+        request.log.warn(message);
+    }
+    server.addHook('onRequest', (request, reply, done) => {
+        reply.raw.once('close', () => {
+            if (!reply.raw.writableFinished)
+                interrupted(request, 'request aborted');
+        });
+        done();
+    });
+    server.addHook('onTimeout', (request, _reply, done) => { interrupted(request, 'request timed out'); done(); });
+    server.addHook('onRequestAbort', (request, done) => { interrupted(request, 'request aborted'); done(); });
+    server.addHook('onResponse', (request, _reply, done) => { ended.add(request); done(); });
+    server.addHook('onSend', (request, reply, payload, done) => {
+        if (!options.exclude?.(request)) {
+            const httpExchange = {
+                request: { method: request.method, url: request.url, headers: redactHeaders(request.headers), body: captureBody(request.body, headerValue(request.headers['content-type']), maxBodyBytes) },
+                response: { statusCode: reply.statusCode, headers: redactHeaders(reply.getHeaders()), body: captureBody(payload, headerValue(reply.getHeader('content-type')), maxBodyBytes) },
+            };
+            request.log.info({ httpExchange }, 'request exchange');
+        }
+        done(null, payload);
+    });
+}