@zintrust/trace 1.6.6 → 1.6.7

package/src/watchers/EventWatcher.ts

@@ -1,46 +0,0 @@
-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

@@ -1,130 +0,0 @@
-/**
- * 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

@@ -1,53 +0,0 @@
-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

@@ -1,219 +0,0 @@
-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

@@ -1,249 +0,0 @@
-/**
- * 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;
-  },
-});