@zintrust/trace 0.4.75

package/dist/watchers/AuthWatcher.d.ts

@@ -0,0 +1,6 @@
+import type { AuthContent, ITraceWatcher } from '../types';
+declare const emit: (event: AuthContent["event"], userId?: string) => void;
+export declare const AuthWatcher: ITraceWatcher & {
+    emit: typeof emit;
+};
+export {};

package/dist/watchers/AuthWatcher.js

@@ -0,0 +1,49 @@
+/**
+ * AuthWatcher — records login/logout/failed auth events.
+ * Credentials are never stored; only the outcome.
+ */
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { RequestFilter } from '../utils/requestFilter';
+let _storage = null;
+let _ignoreRoutes = [];
+const emit = (event, userId) => {
+    if (!_storage)
+        return;
+    if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes))
+        return;
+    const content = {
+        event,
+        userId,
+        hostname: TraceContext.getHostname(),
+    };
+    const tags = [];
+    if (userId)
+        tags.push(`Auth:${userId}`);
+    if (event === 'failed')
+        tags.push('failed');
+    _storage
+        .writeEntry({
+        uuid: crypto.randomUUID(),
+        batchId: TraceContext.getBatchId(),
+        type: EntryType.AUTH,
+        content,
+        tags,
+        isLatest: true,
+        createdAt: TraceContext.now(),
+    })
+        .catch(() => undefined);
+};
+export const AuthWatcher = Object.freeze({
+    emit,
+    register({ storage, config }) {
+        if (config.watchers.auth === false)
+            return () => undefined;
+        _storage = storage;
+        _ignoreRoutes = config.ignoreRoutes;
+        return () => {
+            _storage = null;
+            _ignoreRoutes = [];
+        };
+    },
+});

package/dist/watchers/BatchWatcher.d.ts

@@ -0,0 +1,6 @@
+import type { BatchContent, ITraceWatcher } from '../types';
+declare const emit: (name: string, total: number, processed: number, failed: number, status: BatchContent["status"]) => void;
+export declare const BatchWatcher: ITraceWatcher & {
+    emit: typeof emit;
+};
+export {};

package/dist/watchers/BatchWatcher.js

@@ -0,0 +1,46 @@
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { RequestFilter } from '../utils/requestFilter';
+let _storage = null;
+let _ignoreRoutes = [];
+const emit = (name, total, processed, failed, status) => {
+    if (!_storage)
+        return;
+    if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes))
+        return;
+    const tags = [name];
+    if (failed > 0)
+        tags.push('failed');
+    const content = {
+        name,
+        total,
+        processed,
+        failed,
+        status,
+        hostname: TraceContext.getHostname(),
+    };
+    _storage
+        .writeEntry({
+        uuid: crypto.randomUUID(),
+        batchId: TraceContext.getBatchId(),
+        type: EntryType.BATCH,
+        content,
+        tags,
+        isLatest: true,
+        createdAt: TraceContext.now(),
+    })
+        .catch(() => undefined);
+};
+export const BatchWatcher = Object.freeze({
+    emit,
+    register({ storage, config }) {
+        if (config.watchers.batch === false)
+            return () => undefined;
+        _storage = storage;
+        _ignoreRoutes = config.ignoreRoutes;
+        return () => {
+            _storage = null;
+            _ignoreRoutes = [];
+        };
+    },
+});

package/dist/watchers/CacheWatcher.d.ts

@@ -0,0 +1,6 @@
+import type { CacheContent, ITraceWatcher } from '../types';
+declare const emit: (operation: CacheContent["operation"], key: string, duration: number, hit?: boolean) => void;
+export declare const CacheWatcher: ITraceWatcher & {
+    emit: typeof emit;
+};
+export {};

package/dist/watchers/CacheWatcher.js

@@ -0,0 +1,51 @@
+/**
+ * CacheWatcher — records cache operations.
+ * Call CacheWatcher.emit() from within your cache driver instrumentation.
+ */
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { AuthTag } from '../utils/authTag';
+import { redactString } from '../utils/redact';
+import { RequestFilter } from '../utils/requestFilter';
+let _storage = null;
+let _redactionFields = [];
+let _ignoreRoutes = [];
+const emit = (operation, key, duration, hit) => {
+    if (!_storage)
+        return;
+    if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes))
+        return;
+    const safeKey = redactString(key, _redactionFields);
+    const content = {
+        operation,
+        key: safeKey,
+        hit,
+        duration,
+        hostname: TraceContext.getHostname(),
+    };
+    _storage
+        .writeEntry({
+        uuid: crypto.randomUUID(),
+        batchId: TraceContext.getBatchId(),
+        type: EntryType.CACHE,
+        content,
+        tags: AuthTag.append([]),
+        isLatest: true,
+        createdAt: TraceContext.now(),
+    })
+        .catch(() => undefined);
+};
+export const CacheWatcher = Object.freeze({
+    emit,
+    register({ storage, config }) {
+        if (config.watchers.cache === false)
+            return () => undefined;
+        _storage = storage;
+        _redactionFields = config.redaction.query;
+        _ignoreRoutes = config.ignoreRoutes;
+        return () => {
+            _storage = null;
+            _ignoreRoutes = [];
+        };
+    },
+});

package/dist/watchers/CommandWatcher.d.ts

@@ -0,0 +1,6 @@
+import type { ITraceWatcher } from '../types';
+declare const emit: (name: string, args: Record<string, unknown>, exitCode: number, duration: number, output?: string) => void;
+export declare const CommandWatcher: ITraceWatcher & {
+    emit: typeof emit;
+};
+export {};

package/dist/watchers/CommandWatcher.js

@@ -0,0 +1,49 @@
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { redactObject } from '../utils/redact';
+import { RequestFilter } from '../utils/requestFilter';
+let _storage = null;
+let _redactKeys = [];
+let _ignoreRoutes = [];
+const emit = (name, args, exitCode, duration, output) => {
+    if (!_storage)
+        return;
+    if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes))
+        return;
+    const tags = [name];
+    if (exitCode !== 0)
+        tags.push('failed');
+    const content = {
+        name,
+        arguments: redactObject(args, _redactKeys),
+        exitCode,
+        duration,
+        output,
+        hostname: TraceContext.getHostname(),
+    };
+    _storage
+        .writeEntry({
+        uuid: crypto.randomUUID(),
+        batchId: TraceContext.getBatchId(),
+        type: EntryType.COMMAND,
+        content,
+        tags,
+        isLatest: true,
+        createdAt: TraceContext.now(),
+    })
+        .catch(() => undefined);
+};
+export const CommandWatcher = Object.freeze({
+    emit,
+    register({ storage, config }) {
+        if (config.watchers.command === false)
+            return () => undefined;
+        _storage = storage;
+        _redactKeys = config.redaction?.body ?? [];
+        _ignoreRoutes = config.ignoreRoutes;
+        return () => {
+            _storage = null;
+            _ignoreRoutes = [];
+        };
+    },
+});

package/dist/watchers/DumpWatcher.d.ts

@@ -0,0 +1,7 @@
+import type { ITraceWatcher } from '../types';
+/** Explicitly opt-in (enabled only when config.watchers.dump === true, not just non-false). */
+declare const emit: (value: unknown, file?: string, line?: number) => void;
+export declare const DumpWatcher: ITraceWatcher & {
+    emit: typeof emit;
+};
+export {};

package/dist/watchers/DumpWatcher.js

@@ -0,0 +1,41 @@
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { RequestFilter } from '../utils/requestFilter';
+let _storage = null;
+let _enabled = false;
+let _ignoreRoutes = [];
+/** Explicitly opt-in (enabled only when config.watchers.dump === true, not just non-false). */
+const emit = (value, file, line) => {
+    if (!_storage || !_enabled)
+        return;
+    if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes))
+        return;
+    const content = { value, file, line, hostname: TraceContext.getHostname() };
+    _storage
+        .writeEntry({
+        uuid: crypto.randomUUID(),
+        batchId: TraceContext.getBatchId(),
+        type: EntryType.DUMP,
+        content,
+        tags: [],
+        isLatest: true,
+        createdAt: TraceContext.now(),
+    })
+        .catch(() => undefined);
+};
+export const DumpWatcher = Object.freeze({
+    emit,
+    register({ storage, config }) {
+        // DumpWatcher requires explicit opt-in (=== true), not just absence of false
+        if (config.watchers.dump !== true)
+            return () => undefined;
+        _storage = storage;
+        _enabled = true;
+        _ignoreRoutes = config.ignoreRoutes;
+        return () => {
+            _storage = null;
+            _enabled = false;
+            _ignoreRoutes = [];
+        };
+    },
+});

package/dist/watchers/EventWatcher.d.ts

@@ -0,0 +1,6 @@
+import type { ITraceWatcher } from '../types';
+declare const emit: (name: string, listenerCount: number, payload?: unknown) => void;
+export declare const EventWatcher: ITraceWatcher & {
+    emit: typeof emit;
+};
+export {};

package/dist/watchers/EventWatcher.js

@@ -0,0 +1,42 @@
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { AuthTag } from '../utils/authTag';
+import { RequestFilter } from '../utils/requestFilter';
+let _storage = null;
+let _ignoreRoutes = [];
+const emit = (name, listenerCount, payload) => {
+    if (!_storage)
+        return;
+    if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes))
+        return;
+    const content = {
+        name,
+        payload,
+        listenerCount,
+        hostname: TraceContext.getHostname(),
+    };
+    _storage
+        .writeEntry({
+        uuid: crypto.randomUUID(),
+        batchId: TraceContext.getBatchId(),
+        type: EntryType.EVENT,
+        content,
+        tags: AuthTag.append([name]),
+        isLatest: true,
+        createdAt: TraceContext.now(),
+    })
+        .catch(() => undefined);
+};
+export const EventWatcher = Object.freeze({
+    emit,
+    register({ storage, config }) {
+        if (config.watchers.event === false)
+            return () => undefined;
+        _storage = storage;
+        _ignoreRoutes = config.ignoreRoutes;
+        return () => {
+            _storage = null;
+            _ignoreRoutes = [];
+        };
+    },
+});

package/dist/watchers/ExceptionWatcher.d.ts

@@ -0,0 +1,4 @@
+import type { ITraceWatcher } from '../types';
+export declare const ExceptionWatcher: ITraceWatcher & {
+    capture: (err: unknown) => void;
+};

package/dist/watchers/ExceptionWatcher.js

@@ -0,0 +1,103 @@
+/**
+ * ExceptionWatcher — captures unhandled exceptions by hooking into the
+ * framework error middleware.  Core must call ExceptionWatcher.capture()
+ * from within its error handler, or the register() side-effect adds a
+ * process-level unhandledRejection/uncaughtException listener as fallback.
+ */
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { AuthTag } from '../utils/authTag';
+import { familyHash } from '../utils/familyHash';
+import { RequestFilter } from '../utils/requestFilter';
+import { parseStackFrameLine } from '../utils/stackFrame';
+const getLinePreview = (_file, _line) => {
+    return {};
+};
+const buildContent = (err) => {
+    const stack = err.stack ?? '';
+    const trace = stack
+        .split('\n')
+        .slice(1)
+        .map(parseStackFrameLine)
+        .filter((x) => x !== null)
+        .slice(0, 20);
+    const firstFrame = trace[0];
+    return {
+        class: err.constructor?.name ?? 'Error',
+        file: firstFrame?.file ?? 'unknown',
+        line: firstFrame?.line ?? 0,
+        message: err.message,
+        trace,
+        linePreview: firstFrame ? getLinePreview(firstFrame.file, firstFrame.line) : {},
+        occurrences: 1,
+        hostname: TraceContext.getHostname(),
+        userId: TraceContext.getUserId(),
+    };
+};
+let _storage = null;
+let _listenerRefCount = 0;
+let _ignoreRoutes = [];
+const handleUncaughtException = (error) => {
+    captureException(error);
+};
+const handleUnhandledRejection = (reason) => {
+    captureException(reason);
+};
+const registerProcessListeners = () => {
+    if (typeof process === 'undefined')
+        return;
+    process.on('uncaughtException', handleUncaughtException);
+    process.on('unhandledRejection', handleUnhandledRejection);
+};
+const unregisterProcessListeners = () => {
+    if (typeof process === 'undefined')
+        return;
+    process.off('uncaughtException', handleUncaughtException);
+    process.off('unhandledRejection', handleUnhandledRejection);
+};
+const captureException = (err) => {
+    const storage = _storage;
+    if (!storage)
+        return;
+    if (!(err instanceof Error))
+        return;
+    if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes))
+        return;
+    const content = buildContent(err);
+    const hash = familyHash(`${content.class}:${content.file}:${content.line}`);
+    const uuid = crypto.randomUUID();
+    storage
+        .writeEntry({
+        uuid,
+        batchId: TraceContext.getBatchId(),
+        familyHash: hash,
+        type: EntryType.EXCEPTION,
+        content,
+        tags: AuthTag.append([content.class]),
+        isLatest: true,
+        createdAt: TraceContext.now(),
+    })
+        .then(() => storage.markFamilyStale(hash, uuid))
+        .catch(() => undefined);
+};
+export const ExceptionWatcher = Object.freeze({
+    capture: captureException,
+    register({ storage, config }) {
+        if (config.watchers.exception === false)
+            return () => undefined;
+        _storage = storage;
+        _ignoreRoutes = config.ignoreRoutes;
+        if (_listenerRefCount === 0) {
+            registerProcessListeners();
+        }
+        _listenerRefCount += 1;
+        return () => {
+            _listenerRefCount = Math.max(0, _listenerRefCount - 1);
+            if (_listenerRefCount === 0) {
+                unregisterProcessListeners();
+            }
+            _storage = null;
+            _ignoreRoutes = [];
+        };
+    },
+});

package/dist/watchers/GateWatcher.d.ts

@@ -0,0 +1,6 @@
+import type { GateContent, ITraceWatcher } from '../types';
+declare const emit: (ability: string, result: GateContent["result"], userId?: string, subject?: string) => void;
+export declare const GateWatcher: ITraceWatcher & {
+    emit: typeof emit;
+};
+export {};

package/dist/watchers/GateWatcher.js

@@ -0,0 +1,45 @@
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { RequestFilter } from '../utils/requestFilter';
+let _storage = null;
+let _ignoreRoutes = [];
+const emit = (ability, result, userId, subject) => {
+    if (!_storage)
+        return;
+    if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes))
+        return;
+    const tags = [ability, result];
+    if (userId)
+        tags.push(`Auth:${userId}`);
+    const content = {
+        ability,
+        result,
+        userId,
+        subject,
+        hostname: TraceContext.getHostname(),
+    };
+    _storage
+        .writeEntry({
+        uuid: crypto.randomUUID(),
+        batchId: TraceContext.getBatchId(),
+        type: EntryType.GATE,
+        content,
+        tags,
+        isLatest: true,
+        createdAt: TraceContext.now(),
+    })
+        .catch(() => undefined);
+};
+export const GateWatcher = Object.freeze({
+    emit,
+    register({ storage, config }) {
+        if (config.watchers.gate === false)
+            return () => undefined;
+        _storage = storage;
+        _ignoreRoutes = config.ignoreRoutes;
+        return () => {
+            _storage = null;
+            _ignoreRoutes = [];
+        };
+    },
+});

package/dist/watchers/HttpClientWatcher.d.ts

@@ -0,0 +1,6 @@
+import type { ITraceWatcher } from '../types';
+declare const emit: (method: string, url: string, requestHeaders: Record<string, string>, responseStatus: number, duration: number) => void;
+export declare const HttpClientWatcher: ITraceWatcher & {
+    emit: typeof emit;
+};
+export {};

package/dist/watchers/HttpClientWatcher.js

@@ -0,0 +1,50 @@
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { AuthTag } from '../utils/authTag';
+import { redactHeaders } from '../utils/redact';
+import { RequestFilter } from '../utils/requestFilter';
+let _storage = null;
+let _redactHeaderNames = [];
+let _ignoreRoutes = [];
+const emit = (method, url, requestHeaders, responseStatus, duration) => {
+    if (!_storage)
+        return;
+    if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes))
+        return;
+    const tags = AuthTag.append([method.toUpperCase()]);
+    if (responseStatus >= 400)
+        tags.push('failed');
+    const content = {
+        method: method.toUpperCase(),
+        url,
+        requestHeaders: redactHeaders(requestHeaders, _redactHeaderNames),
+        responseStatus,
+        duration,
+        hostname: TraceContext.getHostname(),
+    };
+    _storage
+        .writeEntry({
+        uuid: crypto.randomUUID(),
+        batchId: TraceContext.getBatchId(),
+        type: EntryType.CLIENT_REQUEST,
+        content,
+        tags,
+        isLatest: true,
+        createdAt: TraceContext.now(),
+    })
+        .catch(() => undefined);
+};
+export const HttpClientWatcher = Object.freeze({
+    emit,
+    register({ storage, config }) {
+        if (config.watchers.clientRequest === false)
+            return () => undefined;
+        _storage = storage;
+        _redactHeaderNames = config.redaction?.headers ?? [];
+        _ignoreRoutes = config.ignoreRoutes;
+        return () => {
+            _storage = null;
+            _ignoreRoutes = [];
+        };
+    },
+});

package/dist/watchers/HttpWatcher.d.ts

@@ -0,0 +1,2 @@
+import type { ITraceWatcher } from '../types';
+export declare const HttpWatcher: ITraceWatcher;

package/dist/watchers/HttpWatcher.js

@@ -0,0 +1,71 @@
+import { TraceContext } from '../context';
+import { EntryType } from '../types';
+import { AuthTag } from '../utils/authTag';
+import { redactHeaders, redactObject } from '../utils/redact';
+import { RequestFilter } from '../utils/requestFilter';
+const normalizeHeaders = (headers) => {
+    if (!headers)
+        return {};
+    return Object.fromEntries(Object.entries(headers).flatMap(([key, value]) => {
+        if (typeof value === 'string')
+            return [[key, value]];
+        if (Array.isArray(value))
+            return [[key, value.join(', ')]];
+        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) : {};
+    return {
+        method: req.getMethod(),
+        uri: req.getPath(),
+        headers,
+        payload,
+        responseStatus: res.getStatus(),
+        responseHeaders: {},
+        duration: Date.now() - start,
+        memory: TraceContext.getMemory(),
+        middleware: [],
+        hostname: TraceContext.getHostname(),
+        userId: TraceContext.getUserId(),
+    };
+};
+const shouldIgnore = (req, config) => {
+    return RequestFilter.matchesIgnoredPath(req.getPath(), config.ignoreRoutes);
+};
+const isWatcherEnabled = (config) => config.watchers.request !== false;
+export const HttpWatcher = Object.freeze({
+    register({ storage, config, registerMiddleware }) {
+        if (!isWatcherEnabled(config))
+            return () => undefined;
+        if (!registerMiddleware)
+            return () => undefined;
+        const middleware = async (req, res, next) => {
+            const request = req;
+            const response = res;
+            if (shouldIgnore(request, config))
+                return next();
+            const start = TraceContext.now();
+            const batchId = TraceContext.getBatchId();
+            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/JobWatcher.d.ts

@@ -0,0 +1,10 @@
+import type { ITraceWatcher } from '../types';
+declare const emitDispatch: (name: string, queue: string, connection: string, data?: unknown) => void;
+declare const emitProcessed: (name: string) => void;
+declare const emitFailed: (name: string, error: Error) => void;
+export declare const JobWatcher: ITraceWatcher & {
+    onDispatch: typeof emitDispatch;
+    onProcessed: typeof emitProcessed;
+    onFailed: typeof emitFailed;
+};
+export {};