@zintrust/trace 1.6.1 → 1.6.3

package/src/ui.ts

@@ -1,9 +0,0 @@
-/**
- * Lightweight UI/dashboard entrypoint for @zintrust/trace.
- *
- * Import this subpath when you only need trace dashboard registration
- * without pulling in the package root re-export surface.
- */
-
-export { registerTraceDashboard, registerTraceRoutes } from './dashboard/routes';
-export type { TraceDashboardOptions, TraceDashboardRegistrationOptions } from './dashboard/routes';

package/src/utils/authTag.ts

@@ -1,20 +0,0 @@
-import { TraceContext } from '../context';
-
-const resolveAuthTag = (): string | undefined => {
-  const userId = TraceContext.getUserId();
-  if (userId === undefined || userId === '') return undefined;
-  return `Auth:${userId}`;
-};
-
-const appendAuthTag = (tags: string[]): string[] => {
-  const authTag = resolveAuthTag();
-  if (authTag === undefined || tags.includes(authTag)) return tags;
-  return [...tags, authTag];
-};
-
-export const AuthTag = Object.freeze({
-  append: appendAuthTag,
-  resolve: resolveAuthTag,
-});
-
-export default AuthTag;

package/src/utils/entryFilter.ts

@@ -1,131 +0,0 @@
-import type {
-  ITraceConfig,
-  ITraceEntry,
-  TraceClientRequestWatcherConfig,
-  TraceFilterRule,
-  TraceRequestWatcherConfig,
-  WatcherToggles,
-} from '../types';
-import { EntryType } from '../types';
-
-const isObjectValue = (value: unknown): value is Record<string, unknown> => {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-};
-
-const normalizeTerms = (terms?: string[]): string[] => {
-  if (!Array.isArray(terms)) return [];
-
-  return terms
-    .filter((term): term is string => typeof term === 'string')
-    .map((term) => term.trim().toLowerCase())
-    .filter((term) => term !== '');
-};
-
-const matchesRule = (haystack: string, rule?: TraceFilterRule): boolean => {
-  if (!rule) return true;
-  if (rule.enabled === false) return false;
-
-  const include = normalizeTerms(rule.include);
-  const exclude = normalizeTerms(rule.exclude);
-
-  if (exclude.some((term) => haystack.includes(term))) return false;
-  if (include.length === 0) return true;
-
-  return include.some((term) => haystack.includes(term));
-};
-
-const toSearchableText = (entry: ITraceEntry): string => {
-  const sections = [entry.type, entry.batchId, ...(entry.tags ?? [])];
-
-  try {
-    sections.push(JSON.stringify(entry.content) ?? '');
-  } catch {
-    sections.push(String(entry.content ?? ''));
-  }
-
-  return sections.join(' ').toLowerCase();
-};
-
-const watcherKeyByEntryType: Record<ITraceEntry['type'], keyof WatcherToggles> = {
-  [EntryType.REQUEST]: 'request',
-  [EntryType.QUERY]: 'query',
-  [EntryType.EXCEPTION]: 'exception',
-  [EntryType.LOG]: 'log',
-  [EntryType.JOB]: 'job',
-  [EntryType.CACHE]: 'cache',
-  [EntryType.SCHEDULE]: 'schedule',
-  [EntryType.MAIL]: 'mail',
-  [EntryType.AUTH]: 'auth',
-  [EntryType.EVENT]: 'event',
-  [EntryType.MODEL]: 'model',
-  [EntryType.NOTIFICATION]: 'notification',
-  [EntryType.REDIS]: 'redis',
-  [EntryType.GATE]: 'gate',
-  [EntryType.MIDDLEWARE]: 'middleware',
-  [EntryType.COMMAND]: 'command',
-  [EntryType.BATCH]: 'batch',
-  [EntryType.DUMP]: 'dump',
-  [EntryType.VIEW]: 'view',
-  [EntryType.CLIENT_REQUEST]: 'clientRequest',
-};
-
-const getRequestMethodRule = (
-  watcher: TraceRequestWatcherConfig,
-  entry: ITraceEntry
-): TraceFilterRule | undefined => {
-  if (entry.type !== EntryType.REQUEST) return undefined;
-
-  const content = isObjectValue(entry.content) ? entry.content : undefined;
-  const methodValue = content?.['method'];
-  const method = typeof methodValue === 'string' ? methodValue.trim().toLowerCase() : '';
-
-  if (method === 'get') return watcher.get;
-  if (method === 'post') return watcher.post;
-  if (method === 'put') return watcher.put;
-  if (method === 'patch') return watcher.patch;
-  if (method === 'delete' || method === 'del') return watcher.delete;
-
-  return watcher.all;
-};
-
-const getClientRequestSourceRule = (
-  watcher: TraceClientRequestWatcherConfig,
-  entry: ITraceEntry
-): TraceFilterRule | undefined => {
-  if (entry.type !== EntryType.CLIENT_REQUEST) return undefined;
-
-  const content = isObjectValue(entry.content) ? entry.content : undefined;
-  const sourceValue = content?.['source'];
-  const source = typeof sourceValue === 'string' ? sourceValue.trim().toLowerCase() : '';
-
-  if (source === '') return undefined;
-  return watcher.sources?.[source];
-};
-
-export const TraceEntryFilter = Object.freeze({
-  shouldCapture(entry: ITraceEntry, config: ITraceConfig): boolean {
-    const watcherKey = watcherKeyByEntryType[entry.type];
-    const watcher = config.watchers[watcherKey];
-    if (watcher === false) return false;
-    if (!isObjectValue(watcher)) return true;
-
-    const haystack = toSearchableText(entry);
-    if (!matchesRule(haystack, watcher)) return false;
-
-    if (watcherKey === 'request') {
-      const requestWatcher = watcher as TraceRequestWatcherConfig;
-      const methodRule = getRequestMethodRule(requestWatcher, entry);
-      if (!matchesRule(haystack, requestWatcher.all)) return false;
-      if (!matchesRule(haystack, methodRule)) return false;
-    }
-
-    if (watcherKey === 'clientRequest') {
-      const clientRequestWatcher = watcher as TraceClientRequestWatcherConfig;
-      const sourceRule = getClientRequestSourceRule(clientRequestWatcher, entry);
-      if (sourceRule?.enabled === false) return false;
-      if (!matchesRule(haystack, sourceRule)) return false;
-    }
-
-    return true;
-  },
-});

package/src/utils/familyHash.ts

@@ -1,8 +0,0 @@
-export const familyHash = (input: string): string => {
-  let hash = 2166136261;
-  for (let index = 0; index < input.length; index++) {
-    hash ^= input.codePointAt(index) ?? 0;
-    hash = (hash * 16777619) >>> 0;
-  }
-  return hash.toString(16).padStart(8, '0');
-};

package/src/utils/redact.ts

@@ -1,112 +0,0 @@
-/**
- * Redaction helpers for @zintrust/trace watchers.
- */
-
-const REDACTED = '****';
-
-const isArrayValue = (value: unknown): value is unknown[] => Array.isArray(value);
-
-const isObjectValue = (value: unknown): value is Record<string, unknown> => {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-};
-
-const normalizeFields = (fields: string[]): Set<string> => {
-  const normalized = new Set<string>();
-
-  for (const field of fields) {
-    if (typeof field !== 'string') continue;
-    const key = field.trim().toLowerCase();
-    if (key !== '') normalized.add(key);
-  }
-
-  return normalized;
-};
-
-const redactUnknownValue = (
-  value: unknown,
-  fields: Set<string>,
-  seen: WeakSet<object>
-): unknown => {
-  if (isArrayValue(value)) {
-    return value.map((item) => redactUnknownValue(item, fields, seen));
-  }
-
-  if (!isObjectValue(value)) {
-    return value;
-  }
-
-  if (seen.has(value)) {
-    return '[Circular]';
-  }
-
-  seen.add(value);
-  const out: Record<string, unknown> = {};
-
-  for (const [key, entryValue] of Object.entries(value)) {
-    out[key] = fields.has(key.toLowerCase())
-      ? REDACTED
-      : redactUnknownValue(entryValue, fields, seen);
-  }
-
-  seen.delete(value);
-  return out;
-};
-
-const redactQuerySegment = (segment: string, fields: Set<string>): string => {
-  const separatorIndex = segment.indexOf('=');
-  if (separatorIndex <= 0) return segment;
-
-  const key = segment.slice(0, separatorIndex);
-  const value = segment.slice(separatorIndex + 1);
-  if (!fields.has(key.toLowerCase())) return `${key}=${value}`;
-
-  return `${key}=${REDACTED}`;
-};
-
-export const redactHeaders = (
-  headers: Record<string, string>,
-  fields: string[]
-): Record<string, string> => {
-  const lower = normalizeFields(fields);
-  const out: Record<string, string> = {};
-  for (const [k, v] of Object.entries(headers)) {
-    out[k] = lower.has(k.toLowerCase()) ? REDACTED : v;
-  }
-  return out;
-};
-
-export const redactUnknown = (value: unknown, fields: string[]): unknown => {
-  return redactUnknownValue(value, normalizeFields(fields), new WeakSet<object>());
-};
-
-export const redactObject = (
-  obj: Record<string, unknown>,
-  fields: string[]
-): Record<string, unknown> => {
-  const redacted = redactUnknown(obj, fields);
-  return isObjectValue(redacted) ? redacted : {};
-};
-
-export const redactString = (value: string, fields: string[]): string => {
-  const lower = normalizeFields(fields);
-  if (value === '') return value;
-
-  let output = '';
-  let segmentStart = 0;
-
-  for (let index = 0; index <= value.length; index += 1) {
-    const isBoundary = index === value.length || value[index] === '&';
-    if (!isBoundary) continue;
-
-    const segment = value.slice(segmentStart, index);
-    output += redactQuerySegment(segment, lower);
-
-    if (index < value.length) {
-      output += '&';
-    }
-
-    segmentStart = index + 1;
-  }
-
-  return output;
-};

package/src/utils/requestFilter.ts

@@ -1,79 +0,0 @@
-import { TraceContext } from '../context';
-
-type RequestIgnoreRules = {
-  ignoreRoutes?: string[];
-  ignorePaths?: string[];
-};
-
-const normalizePath = (input: string): string => {
-  const trimmed = input.trim();
-  const [pathOnly] = trimmed.split('?');
-  if (!pathOnly || pathOnly === '') return '/';
-  return pathOnly.startsWith('/') ? pathOnly : `/${pathOnly}`;
-};
-
-const normalizeContainsPattern = (input: string): string => {
-  const trimmed = input.trim();
-  const [pathOnly] = trimmed.split('?');
-  return pathOnly ?? '';
-};
-
-const resolveRules = (
-  ignoreRoutesOrRules: string[] | RequestIgnoreRules,
-  ignorePaths?: string[]
-): Required<RequestIgnoreRules> => {
-  if (Array.isArray(ignoreRoutesOrRules)) {
-    return {
-      ignoreRoutes: ignoreRoutesOrRules,
-      ignorePaths: ignorePaths ?? [],
-    };
-  }
-
-  return {
-    ignoreRoutes: ignoreRoutesOrRules.ignoreRoutes ?? [],
-    ignorePaths: ignoreRoutesOrRules.ignorePaths ?? [],
-  };
-};
-
-const matchesIgnoredPath = (
-  path: string,
-  ignoreRoutesOrRules: string[] | RequestIgnoreRules,
-  ignorePaths?: string[]
-): boolean => {
-  const normalizedPath = normalizePath(path);
-  const rules = resolveRules(ignoreRoutesOrRules, ignorePaths);
-
-  if (
-    rules.ignoreRoutes.some((route) => {
-      const normalizedRoute = normalizePath(route);
-      return (
-        normalizedPath === normalizedRoute ||
-        normalizedPath.startsWith(
-          normalizedRoute.endsWith('/') ? normalizedRoute : `${normalizedRoute}/`
-        )
-      );
-    })
-  ) {
-    return true;
-  }
-
-  return rules.ignorePaths.some((route) => {
-    const containsPattern = normalizeContainsPattern(route);
-    if (containsPattern === '') return false;
-    return normalizedPath.includes(containsPattern);
-  });
-};
-
-const shouldIgnoreCurrentRequest = (
-  ignoreRoutesOrRules: string[] | RequestIgnoreRules,
-  ignorePaths?: string[]
-): boolean => {
-  const currentPath = TraceContext.getRequestPath();
-  if (typeof currentPath !== 'string' || currentPath === '') return false;
-  return matchesIgnoredPath(currentPath, ignoreRoutesOrRules, ignorePaths);
-};
-
-export const RequestFilter = Object.freeze({
-  matchesIgnoredPath,
-  shouldIgnoreCurrentRequest,
-});

package/src/utils/stackFrame.ts

@@ -1,44 +0,0 @@
-type StackFrame = { file: string; line: number };
-
-const FRAME_PREFIX = 'at ';
-
-const parsePositiveInt = (value: string): number | null => {
-  if (value === '') return null;
-
-  for (const char of value) {
-    if (char < '0' || char > '9') return null;
-  }
-
-  const parsed = Number.parseInt(value, 10);
-  return Number.isNaN(parsed) ? null : parsed;
-};
-
-const parseFrameLocation = (value: string): StackFrame | null => {
-  const columnSeparatorIndex = value.lastIndexOf(':');
-  if (columnSeparatorIndex <= 0) return null;
-
-  const lineSeparatorIndex = value.lastIndexOf(':', columnSeparatorIndex - 1);
-  if (lineSeparatorIndex <= 0) return null;
-
-  const file = value.slice(0, lineSeparatorIndex).trim();
-  const line = parsePositiveInt(value.slice(lineSeparatorIndex + 1, columnSeparatorIndex));
-  const column = parsePositiveInt(value.slice(columnSeparatorIndex + 1));
-
-  if (file === '' || line === null || column === null) return null;
-  return { file, line };
-};
-
-export const parseStackFrameLine = (line: string): StackFrame | null => {
-  const trimmed = line.trim();
-  if (!trimmed.startsWith(FRAME_PREFIX)) return null;
-
-  const body = trimmed.slice(FRAME_PREFIX.length).trim();
-  if (body === '') return null;
-
-  const wrappedStartIndex = body.lastIndexOf(' (');
-  if (wrappedStartIndex !== -1 && body.endsWith(')')) {
-    return parseFrameLocation(body.slice(wrappedStartIndex + 2, -1));
-  }
-
-  return parseFrameLocation(body);
-};

package/src/watchers/AuthWatcher.ts

@@ -1,53 +0,0 @@
-/**
- * AuthWatcher — records login/logout/failed auth events.
- * Credentials are never stored; only the outcome.
- */
-import { TraceContext } from '../context';
-import type { AuthContent, 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 = (event: AuthContent['event'], userId?: string): void => {
-  if (!_storage) return;
-  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes, _ignorePaths)) return;
-  const content: AuthContent = {
-    event,
-    userId,
-    hostname: TraceContext.getHostname(),
-  };
-  const tags: string[] = [];
-  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: ITraceWatcher & { emit: typeof emit } = Object.freeze({
-  emit,
-
-  register({ storage, config }: ITraceWatcherConfig): () => void {
-    if (config.watchers.auth === false) return () => undefined;
-    _storage = storage;
-    _ignoreRoutes = config.ignoreRoutes;
-    _ignorePaths = config.ignorePaths;
-    return () => {
-      _storage = null;
-      _ignoreRoutes = [];
-      _ignorePaths = [];
-    };
-  },
-});

package/src/watchers/BatchWatcher.ts

@@ -1,55 +0,0 @@
-import { TraceContext } from '../context';
-import type { BatchContent, 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 = (
-  name: string,
-  total: number,
-  processed: number,
-  failed: number,
-  status: BatchContent['status']
-): void => {
-  if (!_storage) return;
-  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes, _ignorePaths)) return;
-  const tags = [name];
-  if (failed > 0) tags.push('failed');
-  const content: BatchContent = {
-    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: ITraceWatcher & { emit: typeof emit } = Object.freeze({
-  emit,
-  register({ storage, config }: ITraceWatcherConfig): () => void {
-    if (config.watchers.batch === false) return () => undefined;
-    _storage = storage;
-    _ignoreRoutes = config.ignoreRoutes;
-    _ignorePaths = config.ignorePaths;
-    return () => {
-      _storage = null;
-      _ignoreRoutes = [];
-      _ignorePaths = [];
-    };
-  },
-});

package/src/watchers/CacheWatcher.ts

@@ -1,72 +0,0 @@
-/**
- * CacheWatcher — records cache operations.
- * Call CacheWatcher.emit() from within your cache driver instrumentation.
- */
-import { TraceContext } from '../context';
-import type { CacheContent, ITraceWatcher, ITraceWatcherConfig } from '../types';
-import { EntryType } from '../types';
-import { AuthTag } from '../utils/authTag';
-import { redactString, redactUnknown } from '../utils/redact';
-import { RequestFilter } from '../utils/requestFilter';
-
-let _storage: ITraceWatcherConfig['storage'] | null = null;
-let _config: ITraceWatcherConfig['config'] | null = null;
-let _redactionFields: string[] = [];
-let _ignoreRoutes: string[] = [];
-let _ignorePaths: string[] = [];
-
-const emit = (
-  operation: CacheContent['operation'],
-  key: string,
-  duration: number,
-  hit?: boolean,
-  payload?: unknown,
-  store?: string,
-  ttl?: number
-): void => {
-  if (!_storage) return;
-  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes, _ignorePaths)) return;
-  const safeKey = redactString(key, _redactionFields);
-  const shouldLogPayload = _config?.captureCachePayloads === true;
-  const content: CacheContent = {
-    operation,
-    key: safeKey,
-    hit,
-    ...(typeof store === 'string' && store !== '' ? { store } : {}),
-    ...(typeof ttl === 'number' ? { ttl } : {}),
-    payloadLogged: shouldLogPayload,
-    ...(shouldLogPayload ? { payload: redactUnknown(payload, _redactionFields) } : {}),
-    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: ITraceWatcher & { emit: typeof emit } = Object.freeze({
-  emit,
-
-  register({ storage, config }: ITraceWatcherConfig): () => void {
-    if (config.watchers.cache === false) return () => undefined;
-    _storage = storage;
-    _config = config;
-    _redactionFields = config.redaction.query;
-    _ignoreRoutes = config.ignoreRoutes;
-    _ignorePaths = config.ignorePaths;
-    return () => {
-      _storage = null;
-      _config = null;
-      _ignoreRoutes = [];
-      _ignorePaths = [];
-    };
-  },
-});

package/src/watchers/CommandWatcher.ts

@@ -1,58 +0,0 @@
-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[] = [];
-let _ignorePaths: string[] = [];
-
-const emit = (
-  name: string,
-  args: Record<string, unknown>,
-  exitCode: number,
-  duration: number,
-  output?: string
-): void => {
-  if (!_storage) return;
-  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes, _ignorePaths)) 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?.keys ?? []), ...(config.redaction?.body ?? [])];
-    _ignoreRoutes = config.ignoreRoutes;
-    _ignorePaths = config.ignorePaths;
-    return () => {
-      _storage = null;
-      _ignoreRoutes = [];
-      _ignorePaths = [];
-    };
-  },
-});

package/src/watchers/DumpWatcher.ts

@@ -1,45 +0,0 @@
-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[] = [];
-let _ignorePaths: 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, _ignorePaths)) 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;
-    _ignorePaths = config.ignorePaths;
-    return () => {
-      _storage = null;
-      _enabled = false;
-      _ignoreRoutes = [];
-      _ignorePaths = [];
-    };
-  },
-});