@zintrust/trace 1.6.6 → 1.6.7

package/src/storage/TraceWriteDiagnostics.ts

@@ -1,289 +0,0 @@
-import type { EntryTypeValue, ITraceEntry, ITraceStorage } from '../types';
-
-type TraceLogger = {
-  warn: (message: string, context?: Record<string, unknown>) => void;
-};
-
-type TraceWriteFailureContext = {
-  connectionName: string;
-  error: unknown;
-  operation: string;
-  watcherType?: EntryTypeValue;
-};
-
-type TraceWriteDiagnosticsSnapshot = {
-  degraded: boolean;
-  lastErrorMessage: string | null;
-  lastFailureAt: number | null;
-  totalFailures: number;
-};
-
-type TraceWriteDiagnosticsState = TraceWriteDiagnosticsSnapshot & {
-  lastLoggedAtByFingerprint: Map<string, number>;
-};
-
-const LOG_WINDOW_MS = 30_000;
-
-const diagnosticsState: TraceWriteDiagnosticsState = {
-  degraded: false,
-  lastErrorMessage: null,
-  lastFailureAt: null,
-  lastLoggedAtByFingerprint: new Map<string, number>(),
-  totalFailures: 0,
-};
-
-const asRecord = (value: unknown): Record<string, unknown> | null => {
-  if (value === null || typeof value !== 'object') return null;
-  return value as Record<string, unknown>;
-};
-
-const getAttachedErrorDetails = (error: unknown): unknown => {
-  if (error instanceof Error && 'details' in error) {
-    const details = (error as Error & { details?: unknown }).details;
-    if (details !== undefined) return details;
-  }
-
-  const record = asRecord(error);
-  return record?.['details'];
-};
-
-const getTextValue = (value: unknown): string | null => {
-  if (typeof value !== 'string') return null;
-
-  const trimmed = value.trim();
-  return trimmed === '' ? null : trimmed;
-};
-
-const describeBodyDetails = (body: Record<string, unknown>): string | null => {
-  const code = getTextValue(body['code']);
-  const message = getTextValue(body['message']);
-
-  if (code !== null && message !== null) return `${code}: ${message}`;
-  if (code !== null) return code;
-  if (message !== null) return message;
-
-  return null;
-};
-
-const describeRecordDetails = (record: Record<string, unknown>): string | null => {
-  const body = asRecord(record['body']);
-  if (body !== null) {
-    const describedBody = describeBodyDetails(body);
-    if (describedBody !== null) return describedBody;
-  }
-
-  const nested = describeErrorDetails(record['details']);
-  if (nested !== null) return nested;
-
-  const message = getTextValue(record['message']);
-  if (message !== null) return message;
-
-  const code = getTextValue(record['code']);
-  if (code !== null) return code;
-
-  return null;
-};
-
-const describeErrorDetails = (details: unknown): string | null => {
-  const text = getTextValue(details);
-  if (text !== null) return text;
-
-  const record = asRecord(details);
-  if (record === null) return null;
-  return describeRecordDetails(record);
-};
-
-const withOptionalDetail = (
-  context: Record<string, unknown>,
-  errorDetails: unknown
-): Record<string, unknown> => {
-  if (errorDetails === undefined) return context;
-  return { ...context, errorDetails };
-};
-
-const TRACE_SKIP_LOG_CONTEXT_KEY = '__zintrustSkipTraceLog';
-
-const withTraceSkipContext = (
-  logger: TraceLogger | undefined,
-  context: Record<string, unknown>
-): Record<string, unknown> => {
-  const loggerWithTraceSkip = logger as TraceLogger & {
-    withTraceSkipContext?: (ctx?: Record<string, unknown>) => Record<string, unknown>;
-  };
-
-  return (
-    loggerWithTraceSkip.withTraceSkipContext?.(context) ?? {
-      ...context,
-      [TRACE_SKIP_LOG_CONTEXT_KEY]: true,
-    }
-  );
-};
-
-const getErrorMessage = (error: unknown): string => {
-  let baseMessage = '';
-  if (error instanceof Error && error.message.trim() !== '') {
-    baseMessage = error.message;
-  } else if (typeof error === 'string' && error.trim() !== '') {
-    baseMessage = error;
-  } else {
-    try {
-      const serialized = JSON.stringify(error);
-      if (typeof serialized === 'string' && serialized !== '') baseMessage = serialized;
-    } catch {
-      // ignore serialization failures
-    }
-  }
-
-  const detailsSummary = describeErrorDetails(getAttachedErrorDetails(error));
-  if (
-    detailsSummary !== null &&
-    detailsSummary !== '' &&
-    baseMessage !== '' &&
-    !baseMessage.includes(detailsSummary)
-  ) {
-    return `${baseMessage} (${detailsSummary})`;
-  }
-
-  if (baseMessage !== '') return baseMessage;
-
-  if (detailsSummary !== null && detailsSummary !== '') return detailsSummary;
-
-  return 'Unknown trace storage error';
-};
-
-const buildFingerprint = (context: TraceWriteFailureContext): string => {
-  return [
-    context.connectionName,
-    context.operation,
-    context.watcherType ?? 'unknown',
-    getErrorMessage(context.error),
-  ].join('|');
-};
-
-const reportFailure = (
-  logger: TraceLogger | undefined,
-  context: TraceWriteFailureContext
-): void => {
-  const now = Date.now();
-  const errorMessage = getErrorMessage(context.error);
-  const errorDetails = getAttachedErrorDetails(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 === undefined) return;
-  if (typeof lastLoggedAt === 'number' && now - lastLoggedAt < LOG_WINDOW_MS) return;
-
-  diagnosticsState.lastLoggedAtByFingerprint.set(fingerprint, now);
-  logger.warn(
-    '[trace] Trace storage write degraded',
-    withTraceSkipContext(
-      logger,
-      withOptionalDetail(
-        {
-          connectionName: context.connectionName,
-          error: errorMessage,
-          lastFailureAt: now,
-          operation: context.operation,
-          totalFailures: diagnosticsState.totalFailures,
-          watcherType: context.watcherType ?? null,
-        },
-        errorDetails
-      )
-    )
-  );
-};
-
-const wrapStorageMethod = <TArgs extends unknown[], TResult>(
-  method: (...args: TArgs) => Promise<TResult>,
-  describeFailure: (...args: TArgs) => Omit<TraceWriteFailureContext, 'connectionName' | 'error'>,
-  connectionName: string,
-  logger?: TraceLogger
-): ((...args: TArgs) => Promise<TResult>) => {
-  return async (...args: TArgs): Promise<TResult> => {
-    try {
-      return await method(...args);
-    } catch (error) {
-      reportFailure(logger, {
-        ...describeFailure(...args),
-        connectionName,
-        error,
-      });
-      throw error;
-    }
-  };
-};
-
-export const TraceWriteDiagnostics = Object.freeze({
-  getSnapshot(): TraceWriteDiagnosticsSnapshot {
-    return {
-      degraded: diagnosticsState.degraded,
-      lastErrorMessage: diagnosticsState.lastErrorMessage,
-      lastFailureAt: diagnosticsState.lastFailureAt,
-      totalFailures: diagnosticsState.totalFailures,
-    };
-  },
-
-  reset(): void {
-    diagnosticsState.degraded = false;
-    diagnosticsState.lastErrorMessage = null;
-    diagnosticsState.lastFailureAt = null;
-    diagnosticsState.totalFailures = 0;
-    diagnosticsState.lastLoggedAtByFingerprint.clear();
-  },
-
-  wrapStorage(
-    storage: ITraceStorage,
-    options: { connectionName: string; logger?: TraceLogger }
-  ): ITraceStorage {
-    return Object.freeze({
-      ...storage,
-      writeEntry: wrapStorageMethod(
-        storage.writeEntry.bind(storage),
-        (entry: ITraceEntry) => ({ operation: 'writeEntry', watcherType: entry.type }),
-        options.connectionName,
-        options.logger
-      ),
-      updateEntry: wrapStorageMethod(
-        storage.updateEntry.bind(storage),
-        (_uuid: string, _patch) => ({ operation: 'updateEntry' }),
-        options.connectionName,
-        options.logger
-      ),
-      markFamilyStale: wrapStorageMethod(
-        storage.markFamilyStale.bind(storage),
-        (_familyHash: string, _exceptUuid: string) => ({ operation: 'markFamilyStale' }),
-        options.connectionName,
-        options.logger
-      ),
-      prune: wrapStorageMethod(
-        storage.prune.bind(storage),
-        (_olderThanMs: number, _keepExceptions?: boolean) => ({ 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: string) => ({ operation: 'addMonitoring' }),
-        options.connectionName,
-        options.logger
-      ),
-      removeMonitoring: wrapStorageMethod(
-        storage.removeMonitoring.bind(storage),
-        (_tag: string) => ({ operation: 'removeMonitoring' }),
-        options.connectionName,
-        options.logger
-      ),
-    });
-  },
-});

package/src/storage/index.ts

@@ -1,4 +0,0 @@
-export { TraceStorage } from './TraceStorage';
-export type { ITraceStorage } from './TraceStorage';
-export { ProxyTraceStorage } from './ProxyTraceStorage';
-export { TraceServiceTag } from './TraceServiceTag';

package/src/types.ts

@@ -1,430 +0,0 @@
-/**
- * Types for @zintrust/trace
- * Sealed type definitions — no side effects.
- */
-import type { IDatabase } from '@zintrust/core';
-
-// ---------------------------------------------------------------------------
-// Entry types used by the trace event stream.
-// ---------------------------------------------------------------------------
-
-export const EntryType = Object.freeze({
-  REQUEST: 'request',
-  QUERY: 'query',
-  EXCEPTION: 'exception',
-  LOG: 'log',
-  JOB: 'job',
-  CACHE: 'cache',
-  SCHEDULE: 'schedule',
-  MAIL: 'mail',
-  AUTH: 'auth',
-  EVENT: 'event',
-  MODEL: 'model',
-  NOTIFICATION: 'notification',
-  REDIS: 'redis',
-  GATE: 'gate',
-  MIDDLEWARE: 'middleware',
-  COMMAND: 'command',
-  BATCH: 'batch',
-  DUMP: 'dump',
-  VIEW: 'view',
-  CLIENT_REQUEST: 'client_request',
-} as const);
-
-export type EntryTypeValue = (typeof EntryType)[keyof typeof EntryType];
-
-// ---------------------------------------------------------------------------
-// Per-type content shapes
-// ---------------------------------------------------------------------------
-
-export interface RequestContent {
-  method: string;
-  uri: string;
-  headers: Record<string, string>;
-  payload: unknown;
-  responseStatus: number;
-  responseHeaders: Record<string, string>;
-  responseBody?: unknown;
-  duration: number;
-  memory: number | null;
-  middleware: string[];
-  hostname: string;
-  userId?: string;
-}
-
-export interface QueryContent {
-  connection: string;
-  sql: string;
-  statement?: string;
-  bindings?: unknown[];
-  bindingsIncluded?: boolean;
-  time: number;
-  duration: number;
-  slow: boolean;
-  hash: string;
-  hostname: string;
-}
-
-export interface ExceptionContent {
-  class: string;
-  file: string;
-  line: number;
-  message: string;
-  trace: Array<{ file: string; line: number; function?: string }>;
-  linePreview: Record<string, string>;
-  occurrences: number;
-  hostname: string;
-  userId?: string;
-}
-
-export interface LogContent {
-  level: string;
-  message: string;
-  context?: Record<string, unknown>;
-  hostname: string;
-}
-
-export interface JobContent {
-  status: 'pending' | 'processed' | 'failed';
-  connection: string;
-  queue: string;
-  name: string;
-  tries?: number;
-  timeout?: number;
-  data?: unknown;
-  exception?: { message: string; trace: Array<{ file: string; line: number }> };
-  hostname: string;
-}
-
-export interface CacheContent {
-  operation: 'get' | 'set' | 'delete' | 'clear' | 'has';
-  key: string;
-  hit?: boolean;
-  store?: string;
-  payload?: unknown;
-  payloadLogged?: boolean;
-  ttl?: number;
-  duration: number;
-  hostname: string;
-}
-
-export interface ScheduleContent {
-  name: string;
-  expression: string;
-  status: 'ran' | 'failed' | 'skipped';
-  duration: number;
-  output?: string;
-  hostname: string;
-}
-
-export interface MailContent {
-  to: string;
-  subject: string;
-  template?: string;
-  text?: string;
-  html?: string;
-  hostname: string;
-}
-
-export interface AuthContent {
-  event: 'login' | 'logout' | 'failed';
-  userId?: string;
-  hostname: string;
-}
-
-export interface EventContent {
-  name: string;
-  payload?: unknown;
-  listenerCount: number;
-  hostname: string;
-}
-
-export interface ModelContent {
-  action: 'create' | 'update' | 'delete';
-  model: string;
-  id?: string | number;
-  changes?: Record<string, unknown>;
-  hostname: string;
-}
-
-export interface NotificationContent {
-  channels: string[];
-  notifiable?: string;
-  notification: string;
-  message?: string;
-  payload?: unknown;
-  hostname: string;
-}
-
-export interface RedisContent {
-  command: string;
-  duration: number;
-  hostname: string;
-}
-
-export interface GateContent {
-  ability: string;
-  result: 'allowed' | 'denied';
-  userId?: string;
-  subject?: string;
-  hostname: string;
-}
-
-export interface MiddlewareContent {
-  name: string;
-  event: 'before' | 'after';
-  duration?: number;
-  hostname: string;
-}
-
-export interface CommandContent {
-  name: string;
-  arguments: Record<string, unknown>;
-  exitCode: number;
-  duration: number;
-  output?: string;
-  hostname: string;
-}
-
-export interface BatchContent {
-  name: string;
-  total: number;
-  processed: number;
-  failed: number;
-  status: 'pending' | 'processing' | 'finished' | 'failed';
-  hostname: string;
-}
-
-export interface DumpContent {
-  value: unknown;
-  file?: string;
-  line?: number;
-  hostname: string;
-}
-
-export interface ViewContent {
-  template: string;
-  duration: number;
-  hostname: string;
-}
-
-export interface ClientRequestContent {
-  source?: string;
-  method: string;
-  url: string;
-  requestHeaders: Record<string, string>;
-  requestBody?: unknown;
-  responseStatus?: number;
-  responseHeaders?: Record<string, string>;
-  responseBody?: unknown;
-  error?: string;
-  duration: number;
-  hostname: string;
-}
-
-export interface ClientRequestTraceInput {
-  source?: string;
-  method: string;
-  url: string;
-  requestHeaders: Record<string, string>;
-  responseStatus?: number;
-  duration: number;
-  requestBody?: unknown;
-  responseHeaders?: Record<string, string>;
-  responseBody?: unknown;
-  error?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Core domain records
-// ---------------------------------------------------------------------------
-
-export interface ITraceEntry<T = unknown> {
-  uuid: string;
-  batchId: string;
-  familyHash?: string;
-  type: EntryTypeValue;
-  content: T;
-  tags: string[];
-  isLatest: boolean;
-  createdAt: number;
-}
-
-// ---------------------------------------------------------------------------
-// Storage interface
-// ---------------------------------------------------------------------------
-
-export interface QueryEntriesOptions {
-  type?: EntryTypeValue;
-  tag?: string;
-  batchId?: string;
-  from?: number;
-  to?: number;
-  page?: number;
-  perPage?: number;
-  summary?: boolean;
-}
-
-export interface QueryBatchEntriesOptions {
-  type?: EntryTypeValue;
-  excludeTypes?: EntryTypeValue[];
-  page?: number;
-  perPage?: number;
-  summary?: boolean;
-  countsOnly?: boolean;
-}
-
-export interface QueryBatchEntriesResult {
-  entries: ITraceEntry[];
-  total: number;
-  counts: Partial<Record<EntryTypeValue, number>>;
-  page: number;
-  perPage: number;
-}
-
-export interface ITraceStorage {
-  writeEntry(entry: ITraceEntry): Promise<void>;
-  updateEntry(
-    uuid: string,
-    patch: Partial<Pick<ITraceEntry, 'content' | 'isLatest'>>
-  ): Promise<void>;
-  markFamilyStale(familyHash: string, exceptUuid: string): Promise<void>;
-  queryEntries(opts: QueryEntriesOptions): Promise<{ data: ITraceEntry[]; total: number }>;
-  getEntry(uuid: string): Promise<ITraceEntry | null>;
-  getBatch(batchId: string): Promise<ITraceEntry[]>;
-  queryBatchEntries(
-    batchId: string,
-    opts?: QueryBatchEntriesOptions
-  ): Promise<QueryBatchEntriesResult>;
-  prune(olderThanMs: number, keepExceptions?: boolean): Promise<number>;
-  clear(): Promise<void>;
-  getMonitoring(): Promise<string[]>;
-  addMonitoring(tag: string): Promise<void>;
-  removeMonitoring(tag: string): Promise<void>;
-  stats(): Promise<Record<EntryTypeValue, number>>;
-}
-
-// ---------------------------------------------------------------------------
-// Watcher interface
-// ---------------------------------------------------------------------------
-
-export interface ITraceWatcherConfig {
-  storage: ITraceStorage;
-  config: ITraceConfig;
-  db?: IDatabase;
-  /** Optional: provide to allow HttpWatcher to register as global middleware. */
-  registerMiddleware?: (
-    fn: (req: unknown, res: unknown, next: () => Promise<void>) => Promise<void>
-  ) => void;
-}
-
-export interface ITraceWatcher {
-  register(opts: ITraceWatcherConfig): () => void;
-}
-
-// ---------------------------------------------------------------------------
-// Config interface
-// ---------------------------------------------------------------------------
-
-export type RedactionConfig = {
-  keys: string[];
-  headers: string[];
-  body: string[];
-  query: string[];
-};
-
-export type TraceFilterRule = {
-  enabled?: boolean;
-  include?: string[];
-  exclude?: string[];
-};
-
-export type TraceClientRequestCaptureRule = TraceFilterRule & {
-  requestHeaders?: boolean;
-  requestBody?: boolean;
-  responseHeaders?: boolean;
-  responseBody?: boolean;
-};
-
-export type TraceRequestWatcherConfig = TraceFilterRule & {
-  all?: TraceFilterRule;
-  get?: TraceFilterRule;
-  post?: TraceFilterRule;
-  put?: TraceFilterRule;
-  patch?: TraceFilterRule;
-  delete?: TraceFilterRule;
-};
-
-export type TraceClientRequestWatcherConfig = TraceClientRequestCaptureRule & {
-  sources?: Record<string, TraceClientRequestCaptureRule>;
-};
-
-export type TraceContentDispatchWorkerConfig = {
-  enabled: boolean;
-  intervalMs: number;
-  maxDurationMs: number;
-  concurrency: number;
-};
-
-export type TraceContentDispatchConfig = {
-  driver?: string;
-  queueName: string;
-  enqueueTimeoutMs: number;
-  worker: TraceContentDispatchWorkerConfig;
-};
-
-export type TraceProxyConfig = {
-  enabled: boolean;
-  url?: string;
-  path: string;
-  keyId?: string;
-  secret?: string;
-  timeoutMs: number;
-};
-
-export type TraceWatcherToggle = boolean | TraceFilterRule;
-export type TraceRequestWatcherToggle = boolean | TraceRequestWatcherConfig;
-export type TraceClientRequestWatcherToggle = boolean | TraceClientRequestWatcherConfig;
-
-export type WatcherToggles = {
-  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?: TraceClientRequestWatcherToggle;
-};
-
-export interface ITraceConfig {
-  enabled: boolean;
-  connection?: string;
-  observeConnection?: string;
-  serviceTag?: string;
-  proxy: TraceProxyConfig;
-  pruneAfterHours: number;
-  ignoreRoutes: string[];
-  ignorePaths: string[];
-  slowQueryThreshold: number;
-  captureCachePayloads: boolean;
-  captureQueryBindings: boolean;
-  logMinLevel: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
-  contentDispatch: TraceContentDispatchConfig;
-  watchers: WatcherToggles;
-  redaction: RedactionConfig;
-}
-
-export type TraceConfigOverrides = Partial<ITraceConfig>;