@zintrust/trace 1.6.6 → 1.6.7

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@zintrust/trace",
-  "version": "1.6.6",
+  "version": "1.6.7",
   "description": "Trace assistant for ZinTrust: logs requests, queries, exceptions, jobs, and more.",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "exports": {
     ".": {

package/src/TraceConnection.ts

@@ -1,182 +0,0 @@
-import type { IDatabase } from '@zintrust/core';
-
-type TraceErrorFactory = {
-  createConfigError?(message: string, details?: unknown): Error;
-};
-
-type TraceErrorApi = {
-  ErrorFactory?: TraceErrorFactory;
-};
-
-type TraceEnvApi = {
-  get(key: string, fallback: string): string;
-};
-
-type GlobalTraceConnectionState = {
-  __zintrust_system_trace_connection_name__?: string;
-  __zintrust_system_trace_plugin_requested__?: boolean;
-};
-
-export const TRACE_REQUIRED_TABLES = [
-  'zin_trace_entries',
-  'zin_trace_entries_tags',
-  'zin_trace_monitoring',
-] as const;
-
-const createFallbackTraceConfigError = (message: string, details?: unknown): Error => {
-  const error = new globalThis.Error(message) as Error & {
-    code?: string;
-    details?: unknown;
-    name?: string;
-    statusCode?: number;
-  };
-  error.name = 'ConfigError';
-  error.code = 'CONFIG_ERROR';
-  error.statusCode = 500;
-  error.details = details;
-  return error;
-};
-
-export const createTraceConfigError = (
-  coreApi: TraceErrorApi,
-  message: string,
-  details?: unknown
-): Error => {
-  if (coreApi.ErrorFactory?.createConfigError !== undefined) {
-    return coreApi.ErrorFactory.createConfigError(message, details);
-  }
-
-  return createFallbackTraceConfigError(message, details);
-};
-
-export const getRuntimeTraceConnectionName = (): string | undefined => {
-  const runtimeConnection = (
-    globalThis as GlobalTraceConnectionState
-  ).__zintrust_system_trace_connection_name__?.trim();
-
-  return runtimeConnection === undefined || runtimeConnection === ''
-    ? undefined
-    : runtimeConnection;
-};
-
-export const resolveDashboardTraceConnectionName = (
-  coreApi: TraceErrorApi,
-  input: {
-    explicitConnectionName?: string;
-    configuredConnectionName?: string;
-  }
-): string => {
-  const explicitConnection = input.explicitConnectionName?.trim();
-  if (explicitConnection !== undefined && explicitConnection !== '') {
-    return explicitConnection;
-  }
-
-  const runtimeConnection = getRuntimeTraceConnectionName();
-  if (runtimeConnection !== undefined) {
-    return runtimeConnection;
-  }
-
-  const configuredConnection = input.configuredConnectionName?.trim();
-  if (configuredConnection !== undefined && configuredConnection !== '') {
-    return configuredConnection;
-  }
-
-  throw createTraceConfigError(coreApi, 'Trace dashboard connection is not configured.', {
-    envKey: 'TRACE_DB_CONNECTION',
-    hint: 'Import @zintrust/trace/register before mounting the dashboard, pass connectionName explicitly, or set TRACE_DB_CONNECTION to the trace storage connection.',
-  });
-};
-
-export const resolveTraceConnectionName = (
-  env: Pick<TraceEnvApi, 'get'> | undefined,
-  configuredConnection?: string
-): string => {
-  const resolveDefaultConnection = (): string => {
-    const defaultConnection = env?.get('DB_CONNECTION', '').trim() ?? '';
-    if (defaultConnection === '' || defaultConnection === 'default') return 'default';
-    return defaultConnection;
-  };
-
-  const explicitConnection = configuredConnection?.trim();
-  if (explicitConnection !== undefined && explicitConnection !== '') {
-    return explicitConnection === 'default' ? resolveDefaultConnection() : explicitConnection;
-  }
-
-  return resolveDefaultConnection();
-};
-
-export const resolveObservedConnectionName = (
-  env: Pick<TraceEnvApi, 'get'> | undefined,
-  configuredObservedConnection: string | undefined,
-  storageConnectionName: string
-): string => {
-  if (
-    typeof configuredObservedConnection === 'string' &&
-    configuredObservedConnection.trim() !== ''
-  ) {
-    return resolveTraceConnectionName(env, configuredObservedConnection);
-  }
-
-  const defaultConnectionName = resolveTraceConnectionName(env);
-  if (storageConnectionName !== defaultConnectionName) {
-    return defaultConnectionName;
-  }
-
-  return storageConnectionName;
-};
-
-export function assertTraceConnectionResolved(
-  coreApi: TraceErrorApi,
-  db: IDatabase | undefined,
-  params: { connectionName: string; envKey: 'TRACE_DB_CONNECTION' | 'TRACE_QUERY_CONNECTION' }
-): asserts db is IDatabase {
-  if (db !== undefined) {
-    return;
-  }
-
-  const pluginRequested =
-    (globalThis as GlobalTraceConnectionState).__zintrust_system_trace_plugin_requested__ === true;
-  let hint =
-    'Configure TRACE_QUERY_CONNECTION, or ensure DB_CONNECTION resolves to an existing database connection.';
-
-  if (params.envKey === 'TRACE_DB_CONNECTION') {
-    hint = pluginRequested
-      ? 'Configure TRACE_DB_CONNECTION to an existing database connection before enabling TRACE_ENABLED.'
-      : 'If this module is being imported from zintrust.plugins.*, switch that import to @zintrust/trace/plugin so trace registration runs after database runtime registration. Otherwise configure TRACE_DB_CONNECTION to an existing database connection before enabling TRACE_ENABLED.';
-  }
-
-  throw createTraceConfigError(
-    coreApi,
-    `Trace connection "${params.connectionName}" could not be resolved.`,
-    {
-      connectionName: params.connectionName,
-      envKey: params.envKey,
-      hint,
-    }
-  );
-}
-
-export const assertTraceStorageReady = async (
-  coreApi: TraceErrorApi,
-  db: IDatabase,
-  connectionName: string,
-  operation = 'Trace storage connection'
-): Promise<void> => {
-  try {
-    await Promise.all(
-      TRACE_REQUIRED_TABLES.map(async (table) => {
-        await db.queryOne(`SELECT 1 AS ok FROM ${table} LIMIT 1`, []);
-      })
-    );
-  } catch (error) {
-    throw createTraceConfigError(
-      coreApi,
-      `${operation} "${connectionName}" is not ready. Create the database if needed and run \`zin migrate:trace\` before enabling TRACE_ENABLED.`,
-      {
-        connectionName,
-        error,
-        requiredTables: [...TRACE_REQUIRED_TABLES],
-      }
-    );
-  }
-};

package/src/cli-register.ts

@@ -1,63 +0,0 @@
-type Registry = {
-  register: (id: string, provider: CliCommandProvider) => void;
-};
-
-type CliCommandProvider = {
-  getCommand: () => unknown;
-  name?: string;
-};
-
-type TraceCommandsModule = {
-  TraceCommands: {
-    createTracePruneProvider: () => CliCommandProvider;
-    createTraceClearProvider: () => CliCommandProvider;
-    createTraceStatusProvider: () => CliCommandProvider;
-    createTraceMigrateProvider: () => CliCommandProvider;
-  };
-};
-
-const commandModule = (await import('@zintrust/core/cli')) as unknown as TraceCommandsModule;
-
-const getTraceProviders = (): Array<[string, CliCommandProvider]> => {
-  const { TraceCommands } = commandModule;
-
-  return [
-    ['trace:prune', TraceCommands.createTracePruneProvider()],
-    ['trace:clear', TraceCommands.createTraceClearProvider()],
-    ['trace:status', TraceCommands.createTraceStatusProvider()],
-    ['migrate:trace', TraceCommands.createTraceMigrateProvider()],
-  ];
-};
-
-export function registerTraceCliCommands(registry: Registry): void {
-  for (const [id, provider] of getTraceProviders()) {
-    registry.register(id, provider);
-  }
-}
-
-type GlobalWithRegistry = {
-  __zintrust_cli_command_registry__?: Map<string, CliCommandProvider>;
-};
-
-const globalWithRegistry = globalThis as unknown as GlobalWithRegistry;
-const globalRegistry =
-  globalWithRegistry.__zintrust_cli_command_registry__ ??
-  (globalWithRegistry.__zintrust_cli_command_registry__ = new Map<string, CliCommandProvider>());
-
-registerTraceCliCommands({
-  register: (id, provider) => {
-    globalRegistry.set(id, provider);
-  },
-});
-
-try {
-  const coreCli = (await import('@zintrust/core/cli')) as unknown as {
-    OptionalCliCommandRegistry?: Registry;
-  };
-
-  if (coreCli.OptionalCliCommandRegistry !== undefined) {
-    registerTraceCliCommands(coreCli.OptionalCliCommandRegistry);
-  }
-} catch {
-  // no-op
-}

package/src/config.ts

@@ -1,383 +0,0 @@
-/**
- * TraceConfig — defaults and merge helper for @zintrust/trace
- */
-import type {
-  ITraceConfig,
-  TraceClientRequestCaptureRule,
-  TraceClientRequestWatcherToggle,
-  TraceConfigOverrides,
-  TraceContentDispatchConfig,
-  TraceFilterRule,
-  TraceProxyConfig,
-  TraceRequestWatcherConfig,
-  TraceWatcherToggle,
-} from './types';
-
-const mergeStringLists = (base: string[], override?: string[]): string[] => {
-  const merged = new Set<string>();
-
-  for (const value of [...base, ...(override ?? [])]) {
-    if (typeof value !== 'string') continue;
-    const normalized = value.trim();
-    if (normalized !== '') merged.add(normalized);
-  }
-
-  return [...merged];
-};
-
-const isObjectValue = (value: unknown): value is Record<string, unknown> => {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-};
-
-const resolveEnabled = (
-  base?: TraceFilterRule,
-  override?: TraceFilterRule
-): boolean | undefined => {
-  return override?.enabled ?? base?.enabled;
-};
-
-const hasMergedRuleValues = (
-  include: string[],
-  exclude: string[],
-  enabled: boolean | undefined
-): boolean => {
-  return include.length > 0 || exclude.length > 0 || enabled !== undefined;
-};
-
-const buildFilterRule = (input: {
-  include: string[];
-  exclude: string[];
-  enabled: boolean | undefined;
-}): TraceFilterRule => {
-  return Object.freeze({
-    ...(input.enabled === undefined ? {} : { enabled: input.enabled }),
-    ...(input.include.length > 0 ? { include: input.include } : {}),
-    ...(input.exclude.length > 0 ? { exclude: input.exclude } : {}),
-  });
-};
-
-const mergeFilterRule = (
-  base?: TraceFilterRule,
-  override?: TraceFilterRule
-): TraceFilterRule | undefined => {
-  const include = mergeStringLists(base?.include ?? [], override?.include);
-  const exclude = mergeStringLists(base?.exclude ?? [], override?.exclude);
-  const enabled = resolveEnabled(base, override);
-
-  if (!hasMergedRuleValues(include, exclude, enabled)) return undefined;
-
-  return buildFilterRule({ include, exclude, enabled });
-};
-
-const mergeWatcherToggle = (
-  base?: TraceWatcherToggle,
-  override?: TraceWatcherToggle
-): TraceWatcherToggle | undefined => {
-  if (override === undefined) return base;
-  if (override === false || override === true) return override;
-
-  const baseRule = isObjectValue(base) ? base : undefined;
-  return mergeFilterRule(baseRule, override);
-};
-
-type ClientRequestCaptureFlags = Pick<
-  TraceClientRequestCaptureRule,
-  'requestHeaders' | 'requestBody' | 'responseHeaders' | 'responseBody'
->;
-
-const resolveClientRequestCaptureFlags = (
-  base?: TraceClientRequestCaptureRule,
-  override?: TraceClientRequestCaptureRule
-): ClientRequestCaptureFlags => {
-  return {
-    requestHeaders: override?.requestHeaders ?? base?.requestHeaders,
-    requestBody: override?.requestBody ?? base?.requestBody,
-    responseHeaders: override?.responseHeaders ?? base?.responseHeaders,
-    responseBody: override?.responseBody ?? base?.responseBody,
-  };
-};
-
-const hasClientRequestCaptureFlags = (flags: ClientRequestCaptureFlags): boolean => {
-  return Object.values(flags).some((value) => value !== undefined);
-};
-
-const buildClientRequestCaptureRule = (
-  mergedRule: TraceFilterRule | undefined,
-  flags: ClientRequestCaptureFlags
-): TraceClientRequestCaptureRule => {
-  const baseRule = mergedRule ? { ...mergedRule } : {};
-
-  return Object.freeze({
-    ...baseRule,
-    ...(flags.requestHeaders === undefined ? {} : { requestHeaders: flags.requestHeaders }),
-    ...(flags.requestBody === undefined ? {} : { requestBody: flags.requestBody }),
-    ...(flags.responseHeaders === undefined ? {} : { responseHeaders: flags.responseHeaders }),
-    ...(flags.responseBody === undefined ? {} : { responseBody: flags.responseBody }),
-  });
-};
-
-const mergeClientRequestCaptureRule = (
-  base?: TraceClientRequestCaptureRule,
-  override?: TraceClientRequestCaptureRule
-): TraceClientRequestCaptureRule | undefined => {
-  const mergedRule = mergeFilterRule(base, override);
-  const flags = resolveClientRequestCaptureFlags(base, override);
-
-  if (mergedRule === undefined && !hasClientRequestCaptureFlags(flags)) {
-    return undefined;
-  }
-
-  return buildClientRequestCaptureRule(mergedRule, flags);
-};
-
-const collectClientRequestSourceKeys = (
-  base?: TraceClientRequestWatcherToggle,
-  override?: Exclude<TraceClientRequestWatcherToggle, boolean>
-): string[] => {
-  const overrideSources = override?.sources ?? {};
-  const sourceKeys = new Set<string>([
-    ...Object.keys(isObjectValue(base) ? (base.sources ?? {}) : {}),
-    ...Object.keys(overrideSources),
-  ]);
-
-  return [...sourceKeys];
-};
-
-const mergeClientRequestSources = (
-  base?: TraceClientRequestWatcherToggle,
-  override?: Exclude<TraceClientRequestWatcherToggle, boolean>
-): Record<string, TraceClientRequestCaptureRule> | undefined => {
-  if (override === undefined) return undefined;
-
-  const sources: Record<string, TraceClientRequestCaptureRule> = {};
-
-  for (const key of collectClientRequestSourceKeys(base, override)) {
-    const baseSources = isObjectValue(base) ? base.sources : undefined;
-    const sourceRule = mergeClientRequestCaptureRule(baseSources?.[key], override.sources?.[key]);
-    if (sourceRule !== undefined) {
-      sources[key] = sourceRule;
-    }
-  }
-
-  return Object.keys(sources).length === 0 ? undefined : sources;
-};
-
-const mergeClientRequestWatcherToggle = (
-  base?: TraceClientRequestWatcherToggle,
-  override?: TraceClientRequestWatcherToggle
-): TraceClientRequestWatcherToggle | undefined => {
-  if (override === undefined) return base;
-  if (override === false || override === true) return override;
-
-  const baseConfig = isObjectValue(base) ? base : undefined;
-  const merged = mergeClientRequestCaptureRule(baseConfig, override) ?? {};
-  const sources = mergeClientRequestSources(base, override);
-
-  if (sources === undefined) {
-    return merged;
-  }
-
-  return Object.freeze({
-    ...merged,
-    sources,
-  });
-};
-
-const REQUEST_METHOD_KEYS = ['all', 'get', 'post', 'put', 'patch', 'delete'] as const;
-
-const mergeRequestWatcherToggle = (
-  base?: ITraceConfig['watchers']['request'],
-  override?: ITraceConfig['watchers']['request']
-): ITraceConfig['watchers']['request'] | undefined => {
-  if (override === undefined) return base;
-  if (override === false || override === true) return override;
-
-  const baseConfig = isObjectValue(base) ? base : undefined;
-  const merged: TraceRequestWatcherConfig = mergeFilterRule(baseConfig, override) ?? {};
-
-  for (const key of REQUEST_METHOD_KEYS) {
-    const rule = mergeFilterRule(baseConfig?.[key], override[key]);
-    if (rule !== undefined) merged[key] = rule;
-  }
-
-  return merged;
-};
-
-const mergeWatchers = (
-  base: ITraceConfig['watchers'],
-  override?: TraceConfigOverrides['watchers']
-): ITraceConfig['watchers'] => {
-  if (override === undefined) return { ...base };
-
-  return {
-    ...base,
-    ...override,
-    request: mergeRequestWatcherToggle(base.request, override.request),
-    query: mergeWatcherToggle(base.query, override.query),
-    exception: mergeWatcherToggle(base.exception, override.exception),
-    log: mergeWatcherToggle(base.log, override.log),
-    job: mergeWatcherToggle(base.job, override.job),
-    cache: mergeWatcherToggle(base.cache, override.cache),
-    schedule: mergeWatcherToggle(base.schedule, override.schedule),
-    mail: mergeWatcherToggle(base.mail, override.mail),
-    auth: mergeWatcherToggle(base.auth, override.auth),
-    event: mergeWatcherToggle(base.event, override.event),
-    model: mergeWatcherToggle(base.model, override.model),
-    notification: mergeWatcherToggle(base.notification, override.notification),
-    redis: mergeWatcherToggle(base.redis, override.redis),
-    gate: mergeWatcherToggle(base.gate, override.gate),
-    middleware: mergeWatcherToggle(base.middleware, override.middleware),
-    command: mergeWatcherToggle(base.command, override.command),
-    batch: mergeWatcherToggle(base.batch, override.batch),
-    dump: mergeWatcherToggle(base.dump, override.dump),
-    view: mergeWatcherToggle(base.view, override.view),
-    clientRequest: mergeClientRequestWatcherToggle(base.clientRequest, override.clientRequest),
-  };
-};
-
-const mergeContentDispatch = (
-  base: TraceContentDispatchConfig,
-  override?: TraceConfigOverrides['contentDispatch']
-): TraceContentDispatchConfig => {
-  const workerOverride = override?.worker;
-
-  return {
-    ...base,
-    ...override,
-    worker:
-      workerOverride === undefined
-        ? base.worker
-        : {
-            ...base.worker,
-            ...workerOverride,
-          },
-  };
-};
-
-const mergeProxyConfig = (
-  base: TraceProxyConfig,
-  override?: TraceConfigOverrides['proxy']
-): TraceProxyConfig => {
-  if (override === undefined) return base;
-
-  return {
-    ...base,
-    ...override,
-  };
-};
-
-const DEFAULTS: ITraceConfig = Object.freeze({
-  enabled: false,
-  connection: undefined,
-  observeConnection: undefined,
-  serviceTag: undefined,
-  proxy: {
-    enabled: false,
-    url: undefined,
-    path: '/zin/trace/write',
-    keyId: undefined,
-    secret: undefined,
-    timeoutMs: 30000,
-  },
-  pruneAfterHours: 24,
-  ignoreRoutes: ['/trace', '/health', '/ping'],
-  ignorePaths: [],
-  slowQueryThreshold: 100,
-  captureCachePayloads: false,
-  captureQueryBindings: true,
-  logMinLevel: 'info',
-  contentDispatch: {
-    driver: undefined,
-    queueName: 'trace-content',
-    enqueueTimeoutMs: 25,
-    worker: {
-      enabled: true,
-      intervalMs: 1000,
-      maxDurationMs: 250,
-      concurrency: 1,
-    },
-  },
-  watchers: {},
-  redaction: {
-    keys: [
-      'password',
-      'pass',
-      'passwd',
-      'token',
-      'accessToken',
-      'access_token',
-      'refreshToken',
-      'refresh_token',
-      'secret',
-      'secretKey',
-      'secret_key',
-      'apiKey',
-      'api_key',
-      'auth',
-      'authToken',
-      'auth_token',
-      'authorization',
-      'cookie',
-      'session',
-      'sessionId',
-      'session_id',
-      'card',
-      'cardNumber',
-      'card_number',
-      'cardToken',
-      'card_token',
-      'cvv',
-      'cvc',
-      'pan',
-    ],
-    headers: ['authorization', 'cookie', 'x-api-key', 'x-auth-token'],
-    body: ['password', 'token', 'secret', 'apiKey', 'api_key', 'jwt', 'bearer'],
-    query: [],
-  },
-} satisfies ITraceConfig);
-
-const isWatcherEnabled = (config: ITraceConfig, key: keyof ITraceConfig['watchers']): boolean => {
-  const override = config.watchers[key];
-  if (override === false) return false;
-  if (isObjectValue(override) && override.enabled === false) return false;
-  return true; // undefined = enabled by default; explicit false = disabled
-};
-
-const getRedactionFields = (
-  config: ITraceConfig,
-  key: keyof ITraceConfig['redaction']
-): string[] => {
-  if (key === 'keys') {
-    return mergeStringLists([], config.redaction.keys);
-  }
-
-  return mergeStringLists(config.redaction.keys, config.redaction[key]);
-};
-
-export const TraceConfig = Object.freeze({
-  defaults(): ITraceConfig {
-    return DEFAULTS;
-  },
-
-  merge(overrides?: TraceConfigOverrides): ITraceConfig {
-    if (overrides === undefined || overrides === null) return DEFAULTS;
-    return Object.freeze({
-      ...DEFAULTS,
-      ...overrides,
-      proxy: mergeProxyConfig(DEFAULTS.proxy, overrides.proxy),
-      contentDispatch: mergeContentDispatch(DEFAULTS.contentDispatch, overrides.contentDispatch),
-      watchers: mergeWatchers(DEFAULTS.watchers, overrides.watchers),
-      redaction: {
-        keys: mergeStringLists(DEFAULTS.redaction.keys, overrides.redaction?.keys),
-        headers: mergeStringLists(DEFAULTS.redaction.headers, overrides.redaction?.headers),
-        body: mergeStringLists(DEFAULTS.redaction.body, overrides.redaction?.body),
-        query: mergeStringLists(DEFAULTS.redaction.query, overrides.redaction?.query),
-      },
-      ignoreRoutes: overrides.ignoreRoutes ?? DEFAULTS.ignoreRoutes,
-      ignorePaths: overrides.ignorePaths ?? DEFAULTS.ignorePaths,
-    });
-  },
-
-  getRedactionFields,
-  isWatcherEnabled,
-});