@zintrust/trace 0.4.75

package/src/watchers/CommandWatcher.ts

@@ -0,0 +1,55 @@
+import { TraceContext } from '../context';
+import type { CommandContent, ITraceWatcher, ITraceWatcherConfig } from '../types';
+import { EntryType } from '../types';
+import { redactObject } from '../utils/redact';
+import { RequestFilter } from '../utils/requestFilter';
+
+let _storage: ITraceWatcherConfig['storage'] | null = null;
+let _redactKeys: string[] = [];
+let _ignoreRoutes: string[] = [];
+
+const emit = (
+  name: string,
+  args: Record<string, unknown>,
+  exitCode: number,
+  duration: number,
+  output?: string
+): void => {
+  if (!_storage) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) return;
+  const tags = [name];
+  if (exitCode !== 0) tags.push('failed');
+  const content: CommandContent = {
+    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: ITraceWatcher & { emit: typeof emit } = Object.freeze({
+  emit,
+  register({ storage, config }: ITraceWatcherConfig): () => void {
+    if (config.watchers.command === false) return () => undefined;
+    _storage = storage;
+    _redactKeys = config.redaction?.body ?? [];
+    _ignoreRoutes = config.ignoreRoutes;
+    return () => {
+      _storage = null;
+      _ignoreRoutes = [];
+    };
+  },
+});

package/src/watchers/DumpWatcher.ts

@@ -0,0 +1,42 @@
+import { TraceContext } from '../context';
+import type { DumpContent, ITraceWatcher, ITraceWatcherConfig } from '../types';
+import { EntryType } from '../types';
+import { RequestFilter } from '../utils/requestFilter';
+
+let _storage: ITraceWatcherConfig['storage'] | null = null;
+let _enabled = false;
+let _ignoreRoutes: string[] = [];
+
+/** Explicitly opt-in (enabled only when config.watchers.dump === true, not just non-false). */
+const emit = (value: unknown, file?: string, line?: number): void => {
+  if (!_storage || !_enabled) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) return;
+  const content: DumpContent = { 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: ITraceWatcher & { emit: typeof emit } = Object.freeze({
+  emit,
+  register({ storage, config }: ITraceWatcherConfig): () => void {
+    // 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/src/watchers/EventWatcher.ts

@@ -0,0 +1,43 @@
+import { TraceContext } from '../context';
+import type { EventContent, ITraceWatcher, ITraceWatcherConfig } from '../types';
+import { EntryType } from '../types';
+import { AuthTag } from '../utils/authTag';
+import { RequestFilter } from '../utils/requestFilter';
+
+let _storage: ITraceWatcherConfig['storage'] | null = null;
+let _ignoreRoutes: string[] = [];
+
+const emit = (name: string, listenerCount: number, payload?: unknown): void => {
+  if (!_storage) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) return;
+  const content: EventContent = {
+    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: ITraceWatcher & { emit: typeof emit } = Object.freeze({
+  emit,
+  register({ storage, config }: ITraceWatcherConfig): () => void {
+    if (config.watchers.event === false) return () => undefined;
+    _storage = storage;
+    _ignoreRoutes = config.ignoreRoutes;
+    return () => {
+      _storage = null;
+      _ignoreRoutes = [];
+    };
+  },
+});

package/src/watchers/ExceptionWatcher.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 type { ExceptionContent, ITraceWatcher, ITraceWatcherConfig } from '../types';
+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: string, _line: number): Record<string, string> => {
+  return {};
+};
+
+const buildContent = (err: Error): ExceptionContent => {
+  const stack = err.stack ?? '';
+  const trace: ExceptionContent['trace'] = stack
+    .split('\n')
+    .slice(1)
+    .map(parseStackFrameLine)
+    .filter((x): x is { file: string; line: number } => 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: ITraceWatcherConfig['storage'] | null = null;
+let _listenerRefCount = 0;
+let _ignoreRoutes: string[] = [];
+
+const handleUncaughtException = (error: unknown): void => {
+  captureException(error);
+};
+
+const handleUnhandledRejection = (reason: unknown): void => {
+  captureException(reason);
+};
+
+const registerProcessListeners = (): void => {
+  if (typeof process === 'undefined') return;
+  process.on('uncaughtException', handleUncaughtException);
+  process.on('unhandledRejection', handleUnhandledRejection);
+};
+
+const unregisterProcessListeners = (): void => {
+  if (typeof process === 'undefined') return;
+  process.off('uncaughtException', handleUncaughtException);
+  process.off('unhandledRejection', handleUnhandledRejection);
+};
+
+const captureException = (err: unknown): void => {
+  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: ITraceWatcher & { capture: (err: unknown) => void } = Object.freeze({
+  capture: captureException,
+
+  register({ storage, config }: ITraceWatcherConfig): () => void {
+    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/src/watchers/GateWatcher.ts

@@ -0,0 +1,50 @@
+import { TraceContext } from '../context';
+import type { GateContent, ITraceWatcher, ITraceWatcherConfig } from '../types';
+import { EntryType } from '../types';
+import { RequestFilter } from '../utils/requestFilter';
+
+let _storage: ITraceWatcherConfig['storage'] | null = null;
+let _ignoreRoutes: string[] = [];
+
+const emit = (
+  ability: string,
+  result: GateContent['result'],
+  userId?: string,
+  subject?: string
+): void => {
+  if (!_storage) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) return;
+  const tags: string[] = [ability, result];
+  if (userId) tags.push(`Auth:${userId}`);
+  const content: GateContent = {
+    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: ITraceWatcher & { emit: typeof emit } = Object.freeze({
+  emit,
+  register({ storage, config }: ITraceWatcherConfig): () => void {
+    if (config.watchers.gate === false) return () => undefined;
+    _storage = storage;
+    _ignoreRoutes = config.ignoreRoutes;
+    return () => {
+      _storage = null;
+      _ignoreRoutes = [];
+    };
+  },
+});

package/src/watchers/HttpClientWatcher.ts

@@ -0,0 +1,56 @@
+import { TraceContext } from '../context';
+import type { ClientRequestContent, ITraceWatcher, ITraceWatcherConfig } from '../types';
+import { EntryType } from '../types';
+import { AuthTag } from '../utils/authTag';
+import { redactHeaders } from '../utils/redact';
+import { RequestFilter } from '../utils/requestFilter';
+
+let _storage: ITraceWatcherConfig['storage'] | null = null;
+let _redactHeaderNames: string[] = [];
+let _ignoreRoutes: string[] = [];
+
+const emit = (
+  method: string,
+  url: string,
+  requestHeaders: Record<string, string>,
+  responseStatus: number,
+  duration: number
+): void => {
+  if (!_storage) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) return;
+  const tags = AuthTag.append([method.toUpperCase()]);
+  if (responseStatus >= 400) tags.push('failed');
+  const content: ClientRequestContent = {
+    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: ITraceWatcher & { emit: typeof emit } = Object.freeze({
+  emit,
+  register({ storage, config }: ITraceWatcherConfig): () => void {
+    if (config.watchers.clientRequest === false) return () => undefined;
+    _storage = storage;
+    _redactHeaderNames = config.redaction?.headers ?? [];
+    _ignoreRoutes = config.ignoreRoutes;
+    return () => {
+      _storage = null;
+      _ignoreRoutes = [];
+    };
+  },
+});

package/src/watchers/HttpWatcher.ts

@@ -0,0 +1,94 @@
+/**
+ * HttpWatcher — records inbound HTTP requests as trace entries.
+ * Registers as a global middleware via Kernel.registerGlobalMiddleware().
+ */
+import type { IRequest, IResponse } from '@zintrust/core';
+import { TraceContext } from '../context';
+import type { ITraceConfig, ITraceWatcher, ITraceWatcherConfig, RequestContent } from '../types';
+import { EntryType } from '../types';
+import { AuthTag } from '../utils/authTag';
+import { redactHeaders, redactObject } from '../utils/redact';
+import { RequestFilter } from '../utils/requestFilter';
+
+const normalizeHeaders = (headers: IRequest['headers']): Record<string, string> => {
+  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: IRequest,
+  res: IResponse,
+  start: number,
+  config: ITraceConfig
+): RequestContent => {
+  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: IRequest, config: ITraceConfig): boolean => {
+  return RequestFilter.matchesIgnoredPath(req.getPath(), config.ignoreRoutes);
+};
+
+const isWatcherEnabled = (config: ITraceConfig): boolean => config.watchers.request !== false;
+
+export const HttpWatcher: ITraceWatcher = Object.freeze({
+  register({ storage, config, registerMiddleware }: ITraceWatcherConfig): () => void {
+    if (!isWatcherEnabled(config)) return () => undefined;
+    if (!registerMiddleware) return () => undefined;
+
+    const middleware: Parameters<
+      NonNullable<ITraceWatcherConfig['registerMiddleware']>
+    >[0] = async (req: unknown, res: unknown, next: () => Promise<void>): Promise<void> => {
+      const request = req as IRequest;
+      const response = res as IResponse;
+
+      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/src/watchers/JobWatcher.ts

@@ -0,0 +1,121 @@
+/**
+ * JobWatcher — records job dispatch, completion, and failure.
+ * Subsystems must call JobWatcher.onDispatch / onProcess / onFail from
+ * within their queue implementation for full tracking.
+ */
+import { TraceContext } from '../context';
+import type { ITraceWatcher, ITraceWatcherConfig, JobContent } from '../types';
+import { EntryType } from '../types';
+import { RequestFilter } from '../utils/requestFilter';
+import { parseStackFrameLine } from '../utils/stackFrame';
+
+// Module-level storage ref so emit helpers can be called from outside.
+let _storage: ITraceWatcherConfig['storage'] | null = null;
+let _ignoreRoutes: string[] = [];
+const MAX_TRACKED_JOBS = 1000;
+
+type PendingJob = { uuid: string; content: JobContent };
+
+const pendingJobs = new Map<string, PendingJob[]>();
+
+const trackPendingJob = (name: string, job: PendingJob): void => {
+  const jobs = pendingJobs.get(name) ?? [];
+  jobs.push(job);
+  if (jobs.length > MAX_TRACKED_JOBS) {
+    jobs.shift();
+  }
+  pendingJobs.set(name, jobs);
+};
+
+const takePendingJob = (name: string): PendingJob | null => {
+  const jobs = pendingJobs.get(name);
+  if (!jobs || jobs.length === 0) return null;
+
+  const job = jobs.shift() ?? null;
+  if (jobs.length === 0) {
+    pendingJobs.delete(name);
+  } else {
+    pendingJobs.set(name, jobs);
+  }
+
+  return job;
+};
+
+const emitDispatch = (name: string, queue: string, connection: string, data?: unknown): void => {
+  if (!_storage) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) return;
+  const uuid = crypto.randomUUID();
+  const content: JobContent = {
+    status: 'pending',
+    connection,
+    queue,
+    name,
+    data,
+    hostname: TraceContext.getHostname(),
+  };
+  _storage
+    .writeEntry({
+      uuid,
+      batchId: TraceContext.getBatchId(),
+      type: EntryType.JOB,
+      content,
+      tags: [name],
+      isLatest: true,
+      createdAt: TraceContext.now(),
+    })
+    .catch(() => undefined);
+
+  trackPendingJob(name, { uuid, content });
+};
+
+const emitProcessed = (name: string): void => {
+  if (!_storage) return;
+  const pendingJob = takePendingJob(name);
+  if (pendingJob === null) return;
+
+  const patch: JobContent = { ...pendingJob.content, status: 'processed' };
+  void _storage.updateEntry(pendingJob.uuid, { content: patch }).catch(() => undefined);
+};
+
+const emitFailed = (name: string, error: Error): void => {
+  if (!_storage) return;
+  const pendingJob = takePendingJob(name);
+  if (pendingJob === null) return;
+
+  const patch: JobContent = {
+    ...pendingJob.content,
+    status: 'failed',
+    exception: {
+      message: error.message,
+      trace: (error.stack ?? '')
+        .split('\n')
+        .slice(1)
+        .map(parseStackFrameLine)
+        .filter((trace): trace is { file: string; line: number } => trace !== null)
+        .slice(0, 10),
+    },
+  };
+
+  void _storage.updateEntry(pendingJob.uuid, { content: patch }).catch(() => undefined);
+};
+
+export const JobWatcher: ITraceWatcher & {
+  onDispatch: typeof emitDispatch;
+  onProcessed: typeof emitProcessed;
+  onFailed: typeof emitFailed;
+} = Object.freeze({
+  onDispatch: emitDispatch,
+  onProcessed: emitProcessed,
+  onFailed: emitFailed,
+
+  register({ storage, config }: ITraceWatcherConfig): () => void {
+    if (config.watchers.job === false) return () => undefined;
+    _storage = storage;
+    _ignoreRoutes = config.ignoreRoutes;
+    return () => {
+      _storage = null;
+      _ignoreRoutes = [];
+      pendingJobs.clear();
+    };
+  },
+});

package/src/watchers/LogWatcher.ts

@@ -0,0 +1,61 @@
+/**
+ * LogWatcher — captures Logger output via Logger.addSink().
+ */
+import { Logger } from '@zintrust/core';
+import { TraceContext } from '../context';
+import type { ITraceWatcher, ITraceWatcherConfig, LogContent } from '../types';
+import { EntryType } from '../types';
+import { AuthTag } from '../utils/authTag';
+import { RequestFilter } from '../utils/requestFilter';
+
+type LoggerSink = (level: string, message: string, context?: Record<string, unknown>) => void;
+
+const LEVEL_PRIORITY: Record<string, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  fatal: 4,
+};
+
+export const LogWatcher: ITraceWatcher = Object.freeze({
+  register({ storage, config }: ITraceWatcherConfig): () => void {
+    if (config.watchers.log === false) return () => undefined;
+
+    const minPriority = LEVEL_PRIORITY[config.logMinLevel] ?? 1;
+
+    const loggerWithSink = Logger as typeof Logger & {
+      addSink?: (fn: LoggerSink) => () => void;
+    };
+
+    if (typeof loggerWithSink.addSink !== 'function') {
+      return () => undefined;
+    }
+
+    const unsubscribe = loggerWithSink.addSink((level, message, context) => {
+      if ((LEVEL_PRIORITY[level] ?? 0) < minPriority) return;
+      if (RequestFilter.shouldIgnoreCurrentRequest(config.ignoreRoutes)) return;
+
+      const content: LogContent = {
+        level,
+        message,
+        context: context ?? undefined,
+        hostname: TraceContext.getHostname(),
+      };
+
+      storage
+        .writeEntry({
+          uuid: crypto.randomUUID(),
+          batchId: TraceContext.getBatchId(),
+          type: EntryType.LOG,
+          content,
+          tags: AuthTag.append([]),
+          isLatest: true,
+          createdAt: TraceContext.now(),
+        })
+        .catch(() => undefined);
+    });
+
+    return unsubscribe;
+  },
+});

package/src/watchers/MailWatcher.ts

@@ -0,0 +1,47 @@
+/**
+ * MailWatcher — records mail dispatch intent.
+ * Body is never captured; only to/subject/template.
+ */
+import { TraceContext } from '../context';
+import type { ITraceWatcher, ITraceWatcherConfig, MailContent } from '../types';
+import { EntryType } from '../types';
+import { RequestFilter } from '../utils/requestFilter';
+
+let _storage: ITraceWatcherConfig['storage'] | null = null;
+let _ignoreRoutes: string[] = [];
+
+const emit = (to: string, subject: string, template?: string): void => {
+  if (!_storage) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) return;
+  const content: MailContent = {
+    to,
+    subject,
+    template,
+    hostname: TraceContext.getHostname(),
+  };
+  _storage
+    .writeEntry({
+      uuid: crypto.randomUUID(),
+      batchId: TraceContext.getBatchId(),
+      type: EntryType.MAIL,
+      content,
+      tags: [],
+      isLatest: true,
+      createdAt: TraceContext.now(),
+    })
+    .catch(() => undefined);
+};
+
+export const MailWatcher: ITraceWatcher & { emit: typeof emit } = Object.freeze({
+  emit,
+
+  register({ storage, config }: ITraceWatcherConfig): () => void {
+    if (config.watchers.mail === false) return () => undefined;
+    _storage = storage;
+    _ignoreRoutes = config.ignoreRoutes;
+    return () => {
+      _storage = null;
+      _ignoreRoutes = [];
+    };
+  },
+});