@zintrust/trace 0.4.75

package/src/types.ts

@@ -0,0 +1,317 @@
+/**
+ * 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: Record<string, unknown>;
+  responseStatus: number;
+  responseHeaders: Record<string, string>;
+  duration: number;
+  memory: number | null;
+  middleware: string[];
+  hostname: string;
+  userId?: string;
+}
+
+export interface QueryContent {
+  connection: string;
+  sql: string;
+  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;
+  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;
+  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;
+  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 {
+  method: string;
+  url: string;
+  requestHeaders: Record<string, string>;
+  responseStatus: number;
+  duration: number;
+  hostname: 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;
+}
+
+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[]>;
+  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 = {
+  headers: string[];
+  body: string[];
+  query: string[];
+};
+
+export type WatcherToggles = {
+  request?: boolean;
+  query?: boolean;
+  exception?: boolean;
+  log?: boolean;
+  job?: boolean;
+  cache?: boolean;
+  schedule?: boolean;
+  mail?: boolean;
+  auth?: boolean;
+  event?: boolean;
+  model?: boolean;
+  notification?: boolean;
+  redis?: boolean;
+  gate?: boolean;
+  middleware?: boolean;
+  command?: boolean;
+  batch?: boolean;
+  dump?: boolean;
+  view?: boolean;
+  clientRequest?: boolean;
+};
+
+export interface ITraceConfig {
+  enabled: boolean;
+  connection?: string;
+  pruneAfterHours: number;
+  ignoreRoutes: string[];
+  slowQueryThreshold: number;
+  logMinLevel: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+  watchers: WatcherToggles;
+  redaction: RedactionConfig;
+}
+
+export type TraceConfigOverrides = Partial<ITraceConfig>;

package/src/ui.ts

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

@@ -0,0 +1,20 @@
+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/familyHash.ts

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

@@ -0,0 +1,64 @@
+/**
+ * Redaction helpers for @zintrust/trace watchers.
+ */
+
+const REDACTED = '[REDACTED]';
+
+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 = new Set(fields.map((f) => f.toLowerCase()));
+  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 redactObject = (
+  obj: Record<string, unknown>,
+  fields: string[]
+): Record<string, unknown> => {
+  const lower = new Set(fields.map((f) => f.toLowerCase()));
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    out[k] = lower.has(k.toLowerCase()) ? REDACTED : v;
+  }
+  return out;
+};
+
+export const redactString = (value: string, fields: string[]): string => {
+  const lower = new Set(fields.map((f) => f.toLowerCase()));
+  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

@@ -0,0 +1,33 @@
+import { TraceContext } from '../context';
+
+const normalizePath = (input: string): string => {
+  const trimmed = input.trim();
+  const [pathOnly] = trimmed.split('?');
+  if (!pathOnly || pathOnly === '') return '/';
+  return pathOnly.startsWith('/') ? pathOnly : `/${pathOnly}`;
+};
+
+const matchesIgnoredPath = (path: string, ignoreRoutes: string[]): boolean => {
+  const normalizedPath = normalizePath(path);
+
+  return ignoreRoutes.some((route) => {
+    const normalizedRoute = normalizePath(route);
+    return (
+      normalizedPath === normalizedRoute ||
+      normalizedPath.startsWith(
+        normalizedRoute.endsWith('/') ? normalizedRoute : `${normalizedRoute}/`
+      )
+    );
+  });
+};
+
+const shouldIgnoreCurrentRequest = (ignoreRoutes: string[]): boolean => {
+  const currentPath = TraceContext.getRequestPath();
+  if (typeof currentPath !== 'string' || currentPath === '') return false;
+  return matchesIgnoredPath(currentPath, ignoreRoutes);
+};
+
+export const RequestFilter = Object.freeze({
+  matchesIgnoredPath,
+  shouldIgnoreCurrentRequest,
+});

package/src/utils/stackFrame.ts

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

@@ -0,0 +1,50 @@
+/**
+ * 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[] = [];
+
+const emit = (event: AuthContent['event'], userId?: string): void => {
+  if (!_storage) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) 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;
+    return () => {
+      _storage = null;
+      _ignoreRoutes = [];
+    };
+  },
+});

package/src/watchers/BatchWatcher.ts

@@ -0,0 +1,52 @@
+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[] = [];
+
+const emit = (
+  name: string,
+  total: number,
+  processed: number,
+  failed: number,
+  status: BatchContent['status']
+): void => {
+  if (!_storage) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) 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;
+    return () => {
+      _storage = null;
+      _ignoreRoutes = [];
+    };
+  },
+});

package/src/watchers/CacheWatcher.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 } from '../utils/redact';
+import { RequestFilter } from '../utils/requestFilter';
+
+let _storage: ITraceWatcherConfig['storage'] | null = null;
+let _redactionFields: string[] = [];
+let _ignoreRoutes: string[] = [];
+
+const emit = (
+  operation: CacheContent['operation'],
+  key: string,
+  duration: number,
+  hit?: boolean
+): void => {
+  if (!_storage) return;
+  if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) return;
+  const safeKey = redactString(key, _redactionFields);
+  const content: CacheContent = {
+    operation,
+    key: safeKey,
+    hit,
+    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;
+    _redactionFields = config.redaction.query;
+    _ignoreRoutes = config.ignoreRoutes;
+    return () => {
+      _storage = null;
+      _ignoreRoutes = [];
+    };
+  },
+});