@zintrust/trace 1.6.4 → 1.6.6

package/src/watchers/EventWatcher.ts

@@ -0,0 +1,46 @@
+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[] = [];
+let _ignorePaths: string[] = [];
+
+const emit = (name: string, listenerCount: number, payload?: unknown): void => {
+  if (!_storage) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes, _ignorePaths)) 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;
+    _ignorePaths = config.ignorePaths;
+    return () => {
+      _storage = null;
+      _ignoreRoutes = [];
+      _ignorePaths = [];
+    };
+  },
+});

package/src/watchers/ExceptionWatcher.ts

@@ -0,0 +1,130 @@
+/**
+ * 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';
+
+type ExceptionCaptureContext = {
+  batchId?: string;
+  hostname?: string;
+  path?: string;
+  userId?: string;
+};
+
+const getLinePreview = (_file: string, _line: number): Record<string, string> => {
+  return {};
+};
+
+const buildContent = (err: Error, context?: ExceptionCaptureContext): 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: context?.hostname ?? TraceContext.getHostname(),
+    userId: context?.userId ?? TraceContext.getUserId(),
+  };
+};
+
+let _storage: ITraceWatcherConfig['storage'] | null = null;
+let _listenerRefCount = 0;
+let _ignoreRoutes: string[] = [];
+let _ignorePaths: 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, context?: ExceptionCaptureContext): void => {
+  const storage = _storage;
+  if (!storage) return;
+  if (!(err instanceof Error)) return;
+  if (context?.path !== undefined) {
+    if (RequestFilter.matchesIgnoredPath(context.path, _ignoreRoutes, _ignorePaths)) return;
+  } else if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes, _ignorePaths)) {
+    return;
+  }
+
+  const content = buildContent(err, context);
+  const hash = familyHash(`${content.class}:${content.file}:${content.line}`);
+  const uuid = crypto.randomUUID();
+
+  storage
+    .writeEntry({
+      uuid,
+      batchId: context?.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, context?: ExceptionCaptureContext) => void;
+} = Object.freeze({
+  capture: captureException,
+
+  register({ storage, config }: ITraceWatcherConfig): () => void {
+    if (config.watchers.exception === false) return () => undefined;
+    _storage = storage;
+    _ignoreRoutes = config.ignoreRoutes;
+    _ignorePaths = config.ignorePaths;
+
+    if (_listenerRefCount === 0) {
+      registerProcessListeners();
+    }
+    _listenerRefCount += 1;
+
+    return () => {
+      _listenerRefCount = Math.max(0, _listenerRefCount - 1);
+      if (_listenerRefCount === 0) {
+        unregisterProcessListeners();
+      }
+      _storage = null;
+      _ignoreRoutes = [];
+      _ignorePaths = [];
+    };
+  },
+});

package/src/watchers/GateWatcher.ts

@@ -0,0 +1,53 @@
+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[] = [];
+let _ignorePaths: string[] = [];
+
+const emit = (
+  ability: string,
+  result: GateContent['result'],
+  userId?: string,
+  subject?: string
+): void => {
+  if (!_storage) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes, _ignorePaths)) 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;
+    _ignorePaths = config.ignorePaths;
+    return () => {
+      _storage = null;
+      _ignoreRoutes = [];
+      _ignorePaths = [];
+    };
+  },
+});

package/src/watchers/HttpClientWatcher.ts

@@ -0,0 +1,219 @@
+import { TraceContext } from '../context';
+import {
+  EntryType,
+  type ClientRequestContent,
+  type ClientRequestTraceInput,
+  type ITraceWatcher,
+  type ITraceWatcherConfig,
+  type TraceClientRequestCaptureRule,
+  type TraceClientRequestWatcherConfig,
+} from '../types';
+import { AuthTag } from '../utils/authTag';
+import { redactHeaders, redactUnknown } from '../utils/redact';
+import { RequestFilter } from '../utils/requestFilter';
+
+let _storage: ITraceWatcherConfig['storage'] | null = null;
+let _redactHeaderNames: string[] = [];
+let _redactBodyFields: string[] = [];
+let _ignoreRoutes: string[] = [];
+let _ignorePaths: string[] = [];
+let _clientRequestWatcher: TraceClientRequestWatcherConfig | undefined;
+
+const isObjectValue = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+
+const resolveSource = (value: unknown): string | undefined => {
+  if (typeof value !== 'string') return undefined;
+  const normalized = value.trim().toLowerCase();
+  return normalized === '' ? undefined : normalized;
+};
+
+const resolveSourceRule = (
+  source: string | undefined
+): TraceClientRequestCaptureRule | undefined => {
+  if (source === undefined) return undefined;
+  return _clientRequestWatcher?.sources?.[source];
+};
+
+const shouldCaptureField = (
+  field: keyof Pick<
+    TraceClientRequestCaptureRule,
+    'requestHeaders' | 'requestBody' | 'responseHeaders' | 'responseBody'
+  >,
+  sourceRule: TraceClientRequestCaptureRule | undefined
+): boolean => {
+  const scoped = sourceRule?.[field];
+  if (typeof scoped === 'boolean') return scoped;
+  const global = _clientRequestWatcher?.[field];
+  if (typeof global === 'boolean') return global;
+  return true;
+};
+
+const buildRequestHeaders = (
+  requestHeaders: Record<string, string>,
+  sourceRule: TraceClientRequestCaptureRule | undefined
+): Pick<ClientRequestContent, 'requestHeaders'> => {
+  return shouldCaptureField('requestHeaders', sourceRule)
+    ? { requestHeaders: redactHeaders(requestHeaders, _redactHeaderNames) }
+    : { requestHeaders: {} };
+};
+
+const buildRequestBody = (
+  requestBody: unknown,
+  sourceRule: TraceClientRequestCaptureRule | undefined
+): Partial<Pick<ClientRequestContent, 'requestBody'>> => {
+  if (requestBody === undefined) return {};
+  if (!shouldCaptureField('requestBody', sourceRule)) return {};
+  return { requestBody: redactUnknown(requestBody, _redactBodyFields) };
+};
+
+const buildResponseHeaders = (
+  responseHeaders: Record<string, string> | undefined,
+  sourceRule: TraceClientRequestCaptureRule | undefined
+): Partial<Pick<ClientRequestContent, 'responseHeaders'>> => {
+  if (responseHeaders === undefined) return {};
+  if (!shouldCaptureField('responseHeaders', sourceRule)) return {};
+  return { responseHeaders: redactHeaders(responseHeaders, _redactHeaderNames) };
+};
+
+const buildResponseBody = (
+  responseBody: unknown,
+  sourceRule: TraceClientRequestCaptureRule | undefined
+): Partial<Pick<ClientRequestContent, 'responseBody'>> => {
+  if (responseBody === undefined) return {};
+  if (!shouldCaptureField('responseBody', sourceRule)) return {};
+  return { responseBody: redactUnknown(responseBody, _redactBodyFields) };
+};
+
+const applySource = (content: ClientRequestContent, normalizedSource: string | undefined): void => {
+  if (normalizedSource !== undefined) {
+    content.source = normalizedSource;
+  }
+};
+
+const applyResponseStatus = (
+  content: ClientRequestContent,
+  responseStatus: number | undefined
+): void => {
+  if (responseStatus !== undefined) {
+    content.responseStatus = responseStatus;
+  }
+};
+
+const applyError = (content: ClientRequestContent, error: unknown): void => {
+  if (typeof error === 'string' && error !== '') {
+    content.error = error;
+  }
+};
+
+const mergePartialContent = (
+  content: ClientRequestContent,
+  partial: Partial<ClientRequestContent>
+): void => {
+  Object.assign(content, partial);
+};
+
+const buildClientRequestContent = (
+  input: ClientRequestTraceInput,
+  sourceRule: TraceClientRequestCaptureRule | undefined,
+  normalizedSource: string | undefined
+): ClientRequestContent => {
+  const content: ClientRequestContent = {
+    method: input.method.toUpperCase(),
+    url: input.url,
+    requestHeaders: {},
+    duration: input.duration,
+    hostname: TraceContext.getHostname(),
+  };
+
+  applySource(content, normalizedSource);
+  mergePartialContent(content, buildRequestHeaders(input.requestHeaders, sourceRule));
+  mergePartialContent(content, buildRequestBody(input.requestBody, sourceRule));
+  applyResponseStatus(content, input.responseStatus);
+  mergePartialContent(content, buildResponseHeaders(input.responseHeaders, sourceRule));
+  mergePartialContent(content, buildResponseBody(input.responseBody, sourceRule));
+  applyError(content, input.error);
+
+  return content;
+};
+
+const isWatcherEnabled = (
+  value: ITraceWatcherConfig['config']['watchers']['clientRequest']
+): boolean => {
+  if (value === false) return false;
+  if (isObjectValue(value) && value.enabled === false) return false;
+  return true;
+};
+
+const emit = ({
+  source,
+  method,
+  url,
+  requestHeaders,
+  responseStatus,
+  duration,
+  requestBody,
+  responseHeaders,
+  responseBody,
+  error,
+}: ClientRequestTraceInput): void => {
+  if (!_storage) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes, _ignorePaths)) return;
+  const normalizedSource = resolveSource(source);
+  const sourceRule = resolveSourceRule(normalizedSource);
+  if (sourceRule?.enabled === false) return;
+  const tags = AuthTag.append([method.toUpperCase()]);
+  if ((responseStatus ?? 0) >= 400 || error) tags.push('failed');
+  if (normalizedSource !== undefined) tags.push(normalizedSource);
+  const content = buildClientRequestContent(
+    {
+      source,
+      method,
+      url,
+      requestHeaders,
+      responseStatus,
+      duration,
+      requestBody,
+      responseHeaders,
+      responseBody,
+      error,
+    },
+    sourceRule,
+    normalizedSource
+  );
+  _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 (!isWatcherEnabled(config.watchers.clientRequest)) return () => undefined;
+    _storage = storage;
+    _clientRequestWatcher =
+      typeof config.watchers.clientRequest === 'object' && config.watchers.clientRequest !== null
+        ? config.watchers.clientRequest
+        : undefined;
+    _redactHeaderNames = [...(config.redaction?.keys ?? []), ...(config.redaction?.headers ?? [])];
+    _redactBodyFields = [...(config.redaction?.keys ?? []), ...(config.redaction?.body ?? [])];
+    _ignoreRoutes = config.ignoreRoutes;
+    _ignorePaths = config.ignorePaths;
+    return () => {
+      _storage = null;
+      _clientRequestWatcher = undefined;
+      _redactBodyFields = [];
+      _ignoreRoutes = [];
+      _ignorePaths = [];
+    };
+  },
+});

package/src/watchers/HttpWatcher.ts

@@ -0,0 +1,249 @@
+/**
+ * HttpWatcher — records inbound HTTP requests as trace entries.
+ * Registers as a global middleware via Kernel.registerGlobalMiddleware().
+ */
+import type { IRequest, IResponse } from '@zintrust/core';
+import { Logger } 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, redactUnknown } 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 normalizeHeaderValue = (value: string | string[]): string => {
+  return Array.isArray(value) ? value.join(', ') : value;
+};
+
+const resolveRouteMiddleware = (req: IRequest): string[] => {
+  const middleware = req.context?.['traceRouteMiddleware'];
+  return Array.isArray(middleware)
+    ? middleware.filter((value): value is string => typeof value === 'string')
+    : [];
+};
+
+const resolveRequestPayload = (req: IRequest, config: ITraceConfig): unknown => {
+  const redactFields = [...config.redaction.keys, ...config.redaction.body];
+  const requestBody = typeof req.getBody === 'function' ? req.getBody() : req.body;
+
+  if (requestBody === undefined || requestBody === null) return {};
+  if (typeof requestBody === 'object') {
+    return redactObject(requestBody as Record<string, unknown>, redactFields);
+  }
+
+  return redactUnknown(requestBody, redactFields);
+};
+
+type ResponseCapture = {
+  headers: Record<string, string>;
+  body?: unknown;
+  restore(): void;
+};
+
+type RawResponseWithLifecycle = ReturnType<IResponse['getRaw']> & {
+  once?: (event: 'finish' | 'close', listener: () => void) => unknown;
+  off?: (event: 'finish' | 'close', listener: () => void) => unknown;
+  writableEnded?: boolean;
+  finished?: boolean;
+};
+
+type CompletionHandlerRegistration = {
+  attached: boolean;
+  cleanup(): void;
+};
+
+const registerCompletionHandler = (
+  response: IResponse,
+  onComplete: () => void
+): CompletionHandlerRegistration => {
+  const raw: RawResponseWithLifecycle = response.getRaw();
+  if (typeof raw.once !== 'function') {
+    return { attached: false, cleanup: () => undefined };
+  }
+
+  let completed = false;
+
+  const cleanup = (): void => {
+    if (typeof raw.off === 'function') {
+      raw.off('finish', markCompleted);
+      raw.off('close', markCompleted);
+    }
+  };
+
+  const markCompleted = (): void => {
+    if (completed) return;
+    completed = true;
+    cleanup();
+    onComplete();
+  };
+
+  raw.once('finish', markCompleted);
+  raw.once('close', markCompleted);
+
+  return { attached: true, cleanup };
+};
+
+const isResponseComplete = (response: IResponse): boolean => {
+  const raw: RawResponseWithLifecycle = response.getRaw();
+  return raw.writableEnded === true || raw.finished === true;
+};
+
+const captureResponse = (response: IResponse, config: ITraceConfig): ResponseCapture => {
+  const headers: Record<string, string> = {};
+  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: ResponseCapture = {
+    headers,
+    body: undefined,
+    restore(): void {
+      response.setHeader = originalSetHeader;
+      response.json = originalJson;
+      response.text = originalText;
+      response.html = originalHtml;
+      response.send = originalSend;
+    },
+  };
+
+  response.setHeader = function setHeader(name: string, value: string | string[]): IResponse {
+    headers[name] = normalizeHeaderValue(value);
+    return originalSetHeader.call(this, name, value);
+  };
+
+  response.json = function json(data: unknown): void {
+    capture.body = redactUnknown(data, redactFields);
+    originalJson.call(this, data);
+  };
+
+  response.text = function text(value: string): void {
+    capture.body = value;
+    originalText.call(this, value);
+  };
+
+  response.html = function html(value: string): void {
+    capture.body = value;
+    originalHtml.call(this, value);
+  };
+
+  response.send = function send(data: string | Buffer): void {
+    capture.body = typeof data === 'string' ? data : `[binary ${data.length} bytes]`;
+    originalSend.call(this, data);
+  };
+
+  return capture;
+};
+
+const buildEntry = (
+  req: IRequest,
+  res: IResponse,
+  start: number,
+  config: ITraceConfig,
+  responseCapture: ResponseCapture
+): RequestContent => {
+  const headers = redactHeaders(normalizeHeaders(req.headers), [
+    ...config.redaction.keys,
+    ...config.redaction.headers,
+  ]);
+
+  return {
+    method: req.getMethod(),
+    uri: req.getPath(),
+    headers,
+    payload: resolveRequestPayload(req, config),
+    responseStatus: res.getStatus(),
+    responseHeaders: redactHeaders(responseCapture.headers, [
+      ...config.redaction.keys,
+      ...config.redaction.headers,
+    ]),
+    responseBody: responseCapture.body,
+    duration: Date.now() - start,
+    memory: TraceContext.getMemory(),
+    middleware: resolveRouteMiddleware(req),
+    hostname: TraceContext.getHostname(),
+    userId: TraceContext.getUserId(),
+  };
+};
+
+const shouldIgnore = (req: IRequest, config: ITraceConfig): boolean => {
+  return RequestFilter.matchesIgnoredPath(req.getPath(), config);
+};
+
+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();
+      const responseCapture = captureResponse(response, config);
+      let didPersist = false;
+
+      const persistEntry = (): void => {
+        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();
+
+        const entry = {
+          uuid: crypto.randomUUID(),
+          batchId,
+          type: EntryType.REQUEST,
+          content,
+          tags,
+          isLatest: true,
+          createdAt: TraceContext.now(),
+        };
+
+        storage.writeEntry(entry).catch((error: unknown) => {
+          Logger.warn('[trace] HttpWatcher writeEntry failed', {
+            method: content.method,
+            uri: content.uri,
+            entryUuid: entry.uuid,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }); // fire-and-forget
+      };
+
+      const completionHandler = registerCompletionHandler(response, persistEntry);
+      await next();
+
+      if (!completionHandler.attached || isResponseComplete(response)) {
+        persistEntry();
+      }
+    };
+
+    registerMiddleware(middleware);
+    return () => undefined;
+  },
+});