@zintrust/trace 0.4.76 → 0.4.77

package/dist/storage/TraceWriteDiagnostics.d.ts

@@ -0,0 +1,19 @@
+import type { ITraceStorage } from '../types';
+type TraceLogger = {
+    warn: (message: string, context?: Record<string, unknown>) => void;
+};
+type TraceWriteDiagnosticsSnapshot = {
+    degraded: boolean;
+    lastErrorMessage: string | null;
+    lastFailureAt: number | null;
+    totalFailures: number;
+};
+export declare const TraceWriteDiagnostics: Readonly<{
+    getSnapshot(): TraceWriteDiagnosticsSnapshot;
+    reset(): void;
+    wrapStorage(storage: ITraceStorage, options: {
+        connectionName: string;
+        logger?: TraceLogger;
+    }): ITraceStorage;
+}>;
+export {};

package/dist/storage/TraceWriteDiagnostics.js

@@ -0,0 +1,98 @@
+const LOG_WINDOW_MS = 30_000;
+const diagnosticsState = {
+    degraded: false,
+    lastErrorMessage: null,
+    lastFailureAt: null,
+    lastLoggedAtByFingerprint: new Map(),
+    totalFailures: 0,
+};
+const getErrorMessage = (error) => {
+    if (error instanceof Error && error.message.trim() !== '')
+        return error.message;
+    if (typeof error === 'string' && error.trim() !== '')
+        return error;
+    try {
+        const serialized = JSON.stringify(error);
+        if (typeof serialized === 'string' && serialized !== '')
+            return serialized;
+    }
+    catch {
+        // ignore serialization failures
+    }
+    return 'Unknown trace storage error';
+};
+const buildFingerprint = (context) => {
+    return [
+        context.connectionName,
+        context.operation,
+        context.watcherType ?? 'unknown',
+        getErrorMessage(context.error),
+    ].join('|');
+};
+const reportFailure = (logger, context) => {
+    const now = Date.now();
+    const errorMessage = getErrorMessage(context.error);
+    const fingerprint = buildFingerprint(context);
+    const lastLoggedAt = diagnosticsState.lastLoggedAtByFingerprint.get(fingerprint);
+    diagnosticsState.degraded = true;
+    diagnosticsState.lastErrorMessage = errorMessage;
+    diagnosticsState.lastFailureAt = now;
+    diagnosticsState.totalFailures += 1;
+    if (!logger)
+        return;
+    if (typeof lastLoggedAt === 'number' && now - lastLoggedAt < LOG_WINDOW_MS)
+        return;
+    diagnosticsState.lastLoggedAtByFingerprint.set(fingerprint, now);
+    logger.warn('[trace] Trace storage write degraded', {
+        connectionName: context.connectionName,
+        error: errorMessage,
+        lastFailureAt: now,
+        operation: context.operation,
+        totalFailures: diagnosticsState.totalFailures,
+        watcherType: context.watcherType ?? null,
+    });
+};
+const wrapStorageMethod = (method, describeFailure, connectionName, logger) => {
+    return async (...args) => {
+        try {
+            return await method(...args);
+        }
+        catch (error) {
+            reportFailure(logger, {
+                ...describeFailure(...args),
+                connectionName,
+                error,
+            });
+            throw error;
+        }
+    };
+};
+export const TraceWriteDiagnostics = Object.freeze({
+    getSnapshot() {
+        return {
+            degraded: diagnosticsState.degraded,
+            lastErrorMessage: diagnosticsState.lastErrorMessage,
+            lastFailureAt: diagnosticsState.lastFailureAt,
+            totalFailures: diagnosticsState.totalFailures,
+        };
+    },
+    reset() {
+        diagnosticsState.degraded = false;
+        diagnosticsState.lastErrorMessage = null;
+        diagnosticsState.lastFailureAt = null;
+        diagnosticsState.totalFailures = 0;
+        diagnosticsState.lastLoggedAtByFingerprint.clear();
+    },
+    wrapStorage(storage, options) {
+        return Object.freeze({
+            ...storage,
+            writeEntry: wrapStorageMethod(storage.writeEntry.bind(storage), (entry) => ({ operation: 'writeEntry', watcherType: entry.type }), options.connectionName, options.logger),
+            updateEntry: wrapStorageMethod(storage.updateEntry.bind(storage), (_uuid, _patch) => ({ operation: 'updateEntry' }), options.connectionName, options.logger),
+            markFamilyStale: wrapStorageMethod(storage.markFamilyStale.bind(storage), (_familyHash, _exceptUuid) => ({ operation: 'markFamilyStale' }), options.connectionName, options.logger),
+            prune: wrapStorageMethod(storage.prune.bind(storage), (_olderThanMs, _keepExceptions) => ({ operation: 'prune' }), options.connectionName, options.logger),
+            clear: wrapStorageMethod(storage.clear.bind(storage), () => ({ operation: 'clear' }), options.connectionName, options.logger),
+            addMonitoring: wrapStorageMethod(storage.addMonitoring.bind(storage), (_tag) => ({ operation: 'addMonitoring' }), options.connectionName, options.logger),
+            removeMonitoring: wrapStorageMethod(storage.removeMonitoring.bind(storage), (_tag) => ({ operation: 'removeMonitoring' }), options.connectionName, options.logger),
+        });
+    },
+});

package/dist/types.d.ts

@@ -33,6 +33,7 @@ export interface RequestContent {
     payload: Record<string, unknown>;
     responseStatus: number;
     responseHeaders: Record<string, string>;
+    responseBody?: unknown;
     duration: number;
     memory: number | null;
     middleware: string[];
@@ -231,31 +232,47 @@ export interface ITraceWatcher {
     register(opts: ITraceWatcherConfig): () => void;
 }
 export type RedactionConfig = {
+    keys: string[];
     headers: string[];
     body: string[];
     query: string[];
 };
+export type TraceFilterRule = {
+    enabled?: boolean;
+    include?: string[];
+    exclude?: string[];
+};
+export type TraceRequestWatcherConfig = TraceFilterRule & {
+    all?: TraceFilterRule;
+    get?: TraceFilterRule;
+    post?: TraceFilterRule;
+    put?: TraceFilterRule;
+    patch?: TraceFilterRule;
+    delete?: TraceFilterRule;
+};
+export type TraceWatcherToggle = boolean | TraceFilterRule;
+export type TraceRequestWatcherToggle = boolean | TraceRequestWatcherConfig;
 export type WatcherToggles = {
-    request?: boolean;
-    query?: boolean;
-    exception?: boolean;
-    log?: boolean;
-    job?: boolean;
-    cache?: boolean;
-    schedule?: boolean;
-    mail?: boolean;
-    auth?: boolean;
-    event?: boolean;
-    model?: boolean;
-    notification?: boolean;
-    redis?: boolean;
-    gate?: boolean;
-    middleware?: boolean;
-    command?: boolean;
-    batch?: boolean;
-    dump?: boolean;
-    view?: boolean;
-    clientRequest?: boolean;
+    request?: TraceRequestWatcherToggle;
+    query?: TraceWatcherToggle;
+    exception?: TraceWatcherToggle;
+    log?: TraceWatcherToggle;
+    job?: TraceWatcherToggle;
+    cache?: TraceWatcherToggle;
+    schedule?: TraceWatcherToggle;
+    mail?: TraceWatcherToggle;
+    auth?: TraceWatcherToggle;
+    event?: TraceWatcherToggle;
+    model?: TraceWatcherToggle;
+    notification?: TraceWatcherToggle;
+    redis?: TraceWatcherToggle;
+    gate?: TraceWatcherToggle;
+    middleware?: TraceWatcherToggle;
+    command?: TraceWatcherToggle;
+    batch?: TraceWatcherToggle;
+    dump?: TraceWatcherToggle;
+    view?: TraceWatcherToggle;
+    clientRequest?: TraceWatcherToggle;
 };
 export interface ITraceConfig {
     enabled: boolean;

package/dist/utils/entryFilter.d.ts

@@ -0,0 +1,4 @@
+import type { ITraceConfig, ITraceEntry } from '../types';
+export declare const TraceEntryFilter: Readonly<{
+    shouldCapture(entry: ITraceEntry, config: ITraceConfig): boolean;
+}>;

package/dist/utils/entryFilter.js

@@ -0,0 +1,95 @@
+import { EntryType } from '../types.js';
+const isObjectValue = (value) => {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+const normalizeTerms = (terms) => {
+    if (!Array.isArray(terms))
+        return [];
+    return terms
+        .filter((term) => typeof term === 'string')
+        .map((term) => term.trim().toLowerCase())
+        .filter((term) => term !== '');
+};
+const matchesRule = (haystack, rule) => {
+    if (!rule)
+        return true;
+    const include = normalizeTerms(rule.include);
+    const exclude = normalizeTerms(rule.exclude);
+    if (exclude.some((term) => haystack.includes(term)))
+        return false;
+    if (include.length === 0)
+        return true;
+    return include.some((term) => haystack.includes(term));
+};
+const toSearchableText = (entry) => {
+    const sections = [entry.type, entry.batchId, ...(entry.tags ?? [])];
+    try {
+        sections.push(JSON.stringify(entry.content) ?? '');
+    }
+    catch {
+        sections.push(String(entry.content ?? ''));
+    }
+    return sections.join(' ').toLowerCase();
+};
+const watcherKeyByEntryType = {
+    [EntryType.REQUEST]: 'request',
+    [EntryType.QUERY]: 'query',
+    [EntryType.EXCEPTION]: 'exception',
+    [EntryType.LOG]: 'log',
+    [EntryType.JOB]: 'job',
+    [EntryType.CACHE]: 'cache',
+    [EntryType.SCHEDULE]: 'schedule',
+    [EntryType.MAIL]: 'mail',
+    [EntryType.AUTH]: 'auth',
+    [EntryType.EVENT]: 'event',
+    [EntryType.MODEL]: 'model',
+    [EntryType.NOTIFICATION]: 'notification',
+    [EntryType.REDIS]: 'redis',
+    [EntryType.GATE]: 'gate',
+    [EntryType.MIDDLEWARE]: 'middleware',
+    [EntryType.COMMAND]: 'command',
+    [EntryType.BATCH]: 'batch',
+    [EntryType.DUMP]: 'dump',
+    [EntryType.VIEW]: 'view',
+    [EntryType.CLIENT_REQUEST]: 'clientRequest',
+};
+const getRequestMethodRule = (watcher, entry) => {
+    if (entry.type !== EntryType.REQUEST)
+        return undefined;
+    const content = isObjectValue(entry.content) ? entry.content : undefined;
+    const methodValue = content?.['method'];
+    const method = typeof methodValue === 'string' ? methodValue.trim().toLowerCase() : '';
+    if (method === 'get')
+        return watcher.get;
+    if (method === 'post')
+        return watcher.post;
+    if (method === 'put')
+        return watcher.put;
+    if (method === 'patch')
+        return watcher.patch;
+    if (method === 'delete' || method === 'del')
+        return watcher.delete;
+    return watcher.all;
+};
+export const TraceEntryFilter = Object.freeze({
+    shouldCapture(entry, config) {
+        const watcherKey = watcherKeyByEntryType[entry.type];
+        const watcher = config.watchers[watcherKey];
+        if (watcher === false)
+            return false;
+        if (!isObjectValue(watcher))
+            return true;
+        const haystack = toSearchableText(entry);
+        if (!matchesRule(haystack, watcher))
+            return false;
+        if (watcherKey === 'request') {
+            const requestWatcher = watcher;
+            const methodRule = getRequestMethodRule(requestWatcher, entry);
+            if (!matchesRule(haystack, requestWatcher.all))
+                return false;
+            if (!matchesRule(haystack, methodRule))
+                return false;
+        }
+        return true;
+    },
+});

package/dist/utils/redact.d.ts

@@ -2,5 +2,6 @@
  * Redaction helpers for @zintrust/trace watchers.
  */
 export declare const redactHeaders: (headers: Record<string, string>, fields: string[]) => Record<string, string>;
+export declare const redactUnknown: (value: unknown, fields: string[]) => unknown;
 export declare const redactObject: (obj: Record<string, unknown>, fields: string[]) => Record<string, unknown>;
 export declare const redactString: (value: string, fields: string[]) => string;

package/dist/utils/redact.js

@@ -1,7 +1,42 @@
 /**
  * Redaction helpers for @zintrust/trace watchers.
  */
-const REDACTED = '[REDACTED]';
+const REDACTED = '****';
+const isArrayValue = (value) => Array.isArray(value);
+const isObjectValue = (value) => {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+const normalizeFields = (fields) => {
+    const normalized = new Set();
+    for (const field of fields) {
+        if (typeof field !== 'string')
+            continue;
+        const key = field.trim().toLowerCase();
+        if (key !== '')
+            normalized.add(key);
+    }
+    return normalized;
+};
+const redactUnknownValue = (value, fields, seen) => {
+    if (isArrayValue(value)) {
+        return value.map((item) => redactUnknownValue(item, fields, seen));
+    }
+    if (!isObjectValue(value)) {
+        return value;
+    }
+    if (seen.has(value)) {
+        return '[Circular]';
+    }
+    seen.add(value);
+    const out = {};
+    for (const [key, entryValue] of Object.entries(value)) {
+        out[key] = fields.has(key.toLowerCase())
+            ? REDACTED
+            : redactUnknownValue(entryValue, fields, seen);
+    }
+    seen.delete(value);
+    return out;
+};
 const redactQuerySegment = (segment, fields) => {
     const separatorIndex = segment.indexOf('=');
     if (separatorIndex <= 0)
@@ -13,23 +48,22 @@ const redactQuerySegment = (segment, fields) => {
     return `${key}=${REDACTED}`;
 };
 export const redactHeaders = (headers, fields) => {
-    const lower = new Set(fields.map((f) => f.toLowerCase()));
+    const lower = normalizeFields(fields);
     const out = {};
     for (const [k, v] of Object.entries(headers)) {
         out[k] = lower.has(k.toLowerCase()) ? REDACTED : v;
     }
     return out;
 };
+export const redactUnknown = (value, fields) => {
+    return redactUnknownValue(value, normalizeFields(fields), new WeakSet());
+};
 export const redactObject = (obj, fields) => {
-    const lower = new Set(fields.map((f) => f.toLowerCase()));
-    const out = {};
-    for (const [k, v] of Object.entries(obj)) {
-        out[k] = lower.has(k.toLowerCase()) ? REDACTED : v;
-    }
-    return out;
+    const redacted = redactUnknown(obj, fields);
+    return isObjectValue(redacted) ? redacted : {};
 };
 export const redactString = (value, fields) => {
-    const lower = new Set(fields.map((f) => f.toLowerCase()));
+    const lower = normalizeFields(fields);
     if (value === '')
         return value;
     let output = '';

package/dist/watchers/CommandWatcher.js

@@ -39,7 +39,7 @@ export const CommandWatcher = Object.freeze({
         if (config.watchers.command === false)
             return () => undefined;
         _storage = storage;
-        _redactKeys = config.redaction?.body ?? [];
+        _redactKeys = [...(config.redaction?.keys ?? []), ...(config.redaction?.body ?? [])];
         _ignoreRoutes = config.ignoreRoutes;
         return () => {
             _storage = null;

package/dist/watchers/HttpClientWatcher.js

@@ -40,7 +40,7 @@ export const HttpClientWatcher = Object.freeze({
         if (config.watchers.clientRequest === false)
             return () => undefined;
         _storage = storage;
-        _redactHeaderNames = config.redaction?.headers ?? [];
+        _redactHeaderNames = [...(config.redaction?.keys ?? []), ...(config.redaction?.headers ?? [])];
         _ignoreRoutes = config.ignoreRoutes;
         return () => {
             _storage = null;

package/dist/watchers/HttpWatcher.js

@@ -1,7 +1,7 @@
 import { TraceContext } from '../context.js';
 import { EntryType } from '../types.js';
 import { AuthTag } from '../utils/authTag.js';
-import { redactHeaders, redactObject } from '../utils/redact.js';
+import { redactHeaders, redactObject, redactUnknown } from '../utils/redact.js';
 import { RequestFilter } from '../utils/requestFilter.js';
 const normalizeHeaders = (headers) => {
     if (!headers)
@@ -14,16 +14,91 @@ const normalizeHeaders = (headers) => {
         return [];
     }));
 };
-const buildEntry = (req, res, start, config) => {
-    const headers = redactHeaders(normalizeHeaders(req.headers), config.redaction.headers);
-    const payload = req.body ? redactObject(req.body, config.redaction.body) : {};
+const normalizeHeaderValue = (value) => {
+    return Array.isArray(value) ? value.join(', ') : value;
+};
+const registerCompletionHandler = (response, onComplete) => {
+    const raw = response.getRaw();
+    if (typeof raw.once !== 'function')
+        return () => undefined;
+    let completed = false;
+    const cleanup = () => {
+        if (typeof raw.off === 'function') {
+            raw.off('finish', markCompleted);
+            raw.off('close', markCompleted);
+        }
+    };
+    const markCompleted = () => {
+        if (completed)
+            return;
+        completed = true;
+        cleanup();
+        onComplete();
+    };
+    raw.once('finish', markCompleted);
+    raw.once('close', markCompleted);
+    return cleanup;
+};
+const captureResponse = (response, config) => {
+    const headers = {};
+    const redactFields = [...config.redaction.keys, ...config.redaction.body];
+    const originalSetHeader = response.setHeader;
+    const originalJson = response.json;
+    const originalText = response.text;
+    const originalHtml = response.html;
+    const originalSend = response.send;
+    const capture = {
+        headers,
+        body: undefined,
+        restore() {
+            response.setHeader = originalSetHeader;
+            response.json = originalJson;
+            response.text = originalText;
+            response.html = originalHtml;
+            response.send = originalSend;
+        },
+    };
+    response.setHeader = function setHeader(name, value) {
+        headers[name] = normalizeHeaderValue(value);
+        return originalSetHeader.call(this, name, value);
+    };
+    response.json = function json(data) {
+        capture.body = redactUnknown(data, redactFields);
+        originalJson.call(this, data);
+    };
+    response.text = function text(value) {
+        capture.body = value;
+        originalText.call(this, value);
+    };
+    response.html = function html(value) {
+        capture.body = value;
+        originalHtml.call(this, value);
+    };
+    response.send = function send(data) {
+        capture.body = typeof data === 'string' ? data : `[binary ${data.length} bytes]`;
+        originalSend.call(this, data);
+    };
+    return capture;
+};
+const buildEntry = (req, res, start, config, responseCapture) => {
+    const headers = redactHeaders(normalizeHeaders(req.headers), [
+        ...config.redaction.keys,
+        ...config.redaction.headers,
+    ]);
+    const payload = req.body
+        ? redactObject(req.body, [...config.redaction.keys, ...config.redaction.body])
+        : {};
     return {
         method: req.getMethod(),
         uri: req.getPath(),
         headers,
         payload,
         responseStatus: res.getStatus(),
-        responseHeaders: {},
+        responseHeaders: redactHeaders(responseCapture.headers, [
+            ...config.redaction.keys,
+            ...config.redaction.headers,
+        ]),
+        responseBody: responseCapture.body,
         duration: Date.now() - start,
         memory: TraceContext.getMemory(),
         middleware: [],
@@ -48,22 +123,31 @@ export const HttpWatcher = Object.freeze({
                 return next();
             const start = TraceContext.now();
             const batchId = TraceContext.getBatchId();
+            const responseCapture = captureResponse(response, config);
+            let didPersist = false;
+            const persistEntry = () => {
+                if (didPersist)
+                    return;
+                didPersist = true;
+                const content = buildEntry(request, response, start, config, responseCapture);
+                const tags = AuthTag.append([]);
+                if (content.responseStatus >= 500)
+                    tags.push('failed');
+                responseCapture.restore();
+                storage
+                    .writeEntry({
+                    uuid: crypto.randomUUID(),
+                    batchId,
+                    type: EntryType.REQUEST,
+                    content,
+                    tags,
+                    isLatest: true,
+                    createdAt: TraceContext.now(),
+                })
+                    .catch(() => undefined); // fire-and-forget
+            };
+            registerCompletionHandler(response, persistEntry);
             await next();
-            const content = buildEntry(request, response, start, config);
-            const tags = AuthTag.append([]);
-            if (content.responseStatus >= 500)
-                tags.push('failed');
-            storage
-                .writeEntry({
-                uuid: crypto.randomUUID(),
-                batchId,
-                type: EntryType.REQUEST,
-                content,
-                tags,
-                isLatest: true,
-                createdAt: TraceContext.now(),
-            })
-                .catch(() => undefined); // fire-and-forget
         };
         registerMiddleware(middleware);
         return () => undefined;

package/dist/watchers/LogWatcher.js

@@ -6,6 +6,7 @@ import { TraceContext } from '../context.js';
 import { EntryType } from '../types.js';
 import { AuthTag } from '../utils/authTag.js';
 import { RequestFilter } from '../utils/requestFilter.js';
+// type LoggerSink = (level: string, message: string, context?: Record<string, unknown>) => void;
 const LEVEL_PRIORITY = {
     debug: 0,
     info: 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/trace",
-  "version": "0.4.76",
+  "version": "0.4.77",
   "description": "Trace assistant for ZinTrust: logs requests, queries, exceptions, jobs, and more.",
   "private": false,
   "type": "module",
@@ -40,7 +40,7 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "@zintrust/core": "^0.4.74"
+    "@zintrust/core": "^0.4.77"
   },
   "publishConfig": {
     "access": "public"
@@ -56,4 +56,4 @@
     "build": "tsc -p tsconfig.json && tsc -p tsconfig.migrations.json && node ../../scripts/fix-dist-esm-imports.mjs dist",
     "prepublishOnly": "npm run build"
   }
-}
+}