@zintrust/trace 1.6.4 → 1.6.6

package/dist/build-manifest.json

@@ -1,14 +1,14 @@
 {
   "name": "@zintrust/trace",
-  "version": "1.5.1",
-  "buildDate": "2026-04-28T16:08:58.961Z",
+  "version": "1.6.4",
+  "buildDate": "2026-04-30T15:30:37.643Z",
   "buildEnvironment": {
-    "node": "v22.22.1",
+    "node": "v25.6.1",
     "platform": "darwin",
     "arch": "arm64"
   },
   "git": {
-    "commit": "6c6a3f59",
+    "commit": "f235df8b",
     "branch": "release"
   },
   "package": {
@@ -31,7 +31,7 @@
     },
     "build-manifest.json": {
       "size": 15912,
-      "sha256": "b7ce0234e13707d03336dbad905b5c1403a910880469504ec6cde78ad67fe9a9"
+      "sha256": "6732e16044ffbcb77bf9873cf30a671007b5acc4aa2f3edf5071da667d4df534"
     },
     "cli-register.d.ts": {
       "size": 255,
@@ -87,7 +87,7 @@
     },
     "index.js": {
       "size": 3421,
-      "sha256": "6cab0d02424c088c23dce13c349f177993fd55f21864eea1842c2276a81ad526"
+      "sha256": "ee5aca20d1e6d980fa0b2c02e4832c35e8a18fff9fe63a7bf6a26ae8f734d377"
     },
     "ingest/TraceIngestGateway.d.ts": {
       "size": 786,
@@ -150,8 +150,8 @@
       "sha256": "535869aa1bfcdf0ec26fad27d7f18bb8822bc586c38fcc5ffdde5274ecbea17e"
     },
     "register.js": {
-      "size": 20927,
-      "sha256": "026fd79a98596d2be108b350668f4345b11020953f24369866c0aad42cd7ba0f"
+      "size": 19680,
+      "sha256": "042a7585e68a8a676e25f33c9a176c6f263bccb4a63090b4d2cea52b9bcdd193"
     },
     "storage/DebuggerStorage.d.ts": {
       "size": 517,
@@ -174,8 +174,8 @@
       "sha256": "606a37af0a4aef4866c22cc727f67f485c43181b40eb831e1920b8b90fdaf503"
     },
     "storage/TraceContentBudget.js": {
-      "size": 11434,
-      "sha256": "f53229e7233cf13b095780451b68c912a95dc3f44e17c49289446219231e7e06"
+      "size": 11495,
+      "sha256": "8ed670773814f7b86b916c43ac43b048defc6a102593d808dfb4c8cf7606edf3"
     },
     "storage/TraceContentRedaction.d.ts": {
       "size": 207,
@@ -190,8 +190,8 @@
       "sha256": "a1158cedb4e4e749658127086e138e47886422366a697619d6ea9bd3338066e6"
     },
     "storage/TraceEntryFiltering.js": {
-      "size": 2465,
-      "sha256": "ace7e492373d2dccdbefe20040d30fffd7ad9f8e71113b7a044bddf92dcdf6fb"
+      "size": 1579,
+      "sha256": "a096b0fadf21cd692e554e6ca7789f08759cffe1c690845cb33c5876c8587cc5"
     },
     "storage/TraceServiceTag.d.ts": {
       "size": 224,
@@ -422,8 +422,8 @@
       "sha256": "5d5046c65e5b683369c7709f1acd09b60aec3e7f44748fd1baeb35498836465b"
     },
     "watchers/QueryWatcher.js": {
-      "size": 3023,
-      "sha256": "edede157915aa7832d602c92f4c2220daaf1d799210eae931b1638da883742ca"
+      "size": 2855,
+      "sha256": "dcb9fe2049e71b5fc850286758737d80738a07dd470d96f36e418d4f54e16263"
     },
     "watchers/RedisWatcher.d.ts": {
       "size": 294,

package/dist/storage/TraceContentBudget.js

@@ -162,6 +162,7 @@ const hasQueueDispatch = (config) => {
     const driver = config.contentDispatch.driver?.trim();
     return typeof driver === 'string' && driver !== '';
 };
+const WORKERS_PACKAGE_SPECIFIER = '@zintrust/workers';
 const getCoreRuntime = async () => {
     try {
         const mod = (await import('@zintrust/core'));
@@ -180,7 +181,7 @@ const getCoreRuntime = async () => {
 const getQueueWorkerApi = async () => {
     try {
         // @ts-ignore
-        const mod = (await import('@zintrust/workers'));
+        const mod = (await import(WORKERS_PACKAGE_SPECIFIER));
         return typeof mod.createQueueWorker === 'function' ? mod : null;
     }
     catch {

package/dist/watchers/HttpWatcher.js

@@ -1,3 +1,4 @@
+import { Logger } from '@zintrust/core';
 import { TraceContext } from '../context.js';
 import { EntryType } from '../types.js';
 import { AuthTag } from '../utils/authTag.js';
@@ -35,8 +36,9 @@ const resolveRequestPayload = (req, config) => {
 };
 const registerCompletionHandler = (response, onComplete) => {
     const raw = response.getRaw();
-    if (typeof raw.once !== 'function')
-        return () => undefined;
+    if (typeof raw.once !== 'function') {
+        return { attached: false, cleanup: () => undefined };
+    }
     let completed = false;
     const cleanup = () => {
         if (typeof raw.off === 'function') {
@@ -53,7 +55,11 @@ const registerCompletionHandler = (response, onComplete) => {
     };
     raw.once('finish', markCompleted);
     raw.once('close', markCompleted);
-    return cleanup;
+    return { attached: true, cleanup };
+};
+const isResponseComplete = (response) => {
+    const raw = response.getRaw();
+    return raw.writableEnded === true || raw.finished === true;
 };
 const captureResponse = (response, config) => {
     const headers = {};
@@ -147,8 +153,7 @@ export const HttpWatcher = Object.freeze({
                 if (content.responseStatus >= 500)
                     tags.push('failed');
                 responseCapture.restore();
-                storage
-                    .writeEntry({
+                const entry = {
                     uuid: crypto.randomUUID(),
                     batchId,
                     type: EntryType.REQUEST,
@@ -156,11 +161,21 @@ export const HttpWatcher = Object.freeze({
                     tags,
                     isLatest: true,
                     createdAt: TraceContext.now(),
-                })
-                    .catch(() => undefined); // fire-and-forget
+                };
+                storage.writeEntry(entry).catch((error) => {
+                    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
             };
-            registerCompletionHandler(response, persistEntry);
+            const completionHandler = registerCompletionHandler(response, persistEntry);
             await next();
+            if (!completionHandler.attached || isResponseComplete(response)) {
+                persistEntry();
+            }
         };
         registerMiddleware(middleware);
         return () => undefined;

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@zintrust/trace",
-  "version": "1.6.4",
+  "version": "1.6.6",
   "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"
+    "dist",
+    "src"
   ],
   "exports": {
     ".": {

package/src/TraceConnection.ts

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

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