@zintrust/workers 0.4.48 → 0.4.60

package/dist/ui/workers/zintrust.svg

@@ -0,0 +1,30 @@
+<svg width="120" height="120" viewBox="0 0 100 100" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="zt-g2d" x1="10" y1="50" x2="90" y2="50" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#22c55e" />
+      <stop offset="1" stop-color="#38bdf8" />
+    </linearGradient>
+  </defs>
+  <circle cx="50" cy="50" r="34" stroke="rgba(255,255,255,0.16)" stroke-width="4" />
+  <ellipse cx="50" cy="50" rx="40" ry="18" stroke="url(#zt-g2d)" stroke-width="4" />
+  <ellipse cx="50" cy="50" rx="18" ry="40" stroke="url(#zt-g2d)" stroke-width="4" opacity="0.75" />
+  <circle cx="50" cy="50" r="6" fill="url(#zt-g2d)" />
+  <path
+    d="M40 52C35 52 32 49 32 44C32 39 35 36 40 36H48"
+    stroke="white"
+    stroke-width="6"
+    stroke-linecap="round"
+  />
+  <path
+    d="M60 48C65 48 68 51 68 56C68 61 65 64 60 64H52"
+    stroke="white"
+    stroke-width="6"
+    stroke-linecap="round"
+  />
+  <path
+    d="M44 50H56"
+    stroke="rgba(255,255,255,0.22)"
+    stroke-width="6"
+    stroke-linecap="round"
+  />
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/workers",
-  "version": "0.4.48",
+  "version": "0.4.60",
   "description": "Worker orchestration and background job management for ZinTrust.",
   "private": false,
   "type": "module",
@@ -40,7 +40,7 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "@zintrust/core": "^0.4.48",
+    "@zintrust/core": ">=0.4.0 <0.5.0",
     "@zintrust/queue-monitor": "*",
     "@zintrust/queue-redis": "*"
   },

package/src/WorkerFactory.ts

@@ -9,6 +9,7 @@ import {
   Cloudflare,
   createRedisConnection,
   databaseConfig,
+  DatabaseConnectionRegistry,
   Env,
   ErrorFactory,
   generateUuid,
@@ -46,6 +47,7 @@ import { WorkerMetrics } from './WorkerMetrics';
 import { WorkerRegistry, type WorkerInstance as RegistryWorkerInstance } from './WorkerRegistry';
 import { WorkerVersioning } from './WorkerVersioning';
 import { keyPrefix } from './config/workerConfig';
+import { recordQueueMonitorJob } from './queueMonitorHistory';
 import {
   DbWorkerStore,
   InMemoryWorkerStore,
@@ -108,7 +110,7 @@ const resolveRuntimeBridgeUrl = (specifier: string): string | null => {
   const filePath = path.join(dir, `${safeName}.bridge.mjs`);
   const exportLines = Object.keys(bridgeModule)
     .filter((key) => key !== 'default' && isValidBridgeExportName(key))
-    .sort()
+    .sort((a, b) => a.localeCompare(b))
     .map((key) => `export const ${key} = bridge[${JSON.stringify(key)}];`);
 
   const code = [
@@ -2226,20 +2228,27 @@ const resolvePersistenceConfig = (
 };
 
 const resolveDbClientFromEnv = async (connectionName = 'default'): Promise<IDatabase> => {
-  const connect = async (): Promise<IDatabase> =>
-    await useEnsureDbConnected(undefined, connectionName);
-
-  try {
-    return await connect();
-  } catch (error) {
-    Logger.error('Worker persistence failed to resolve database connection', error);
+  // Eagerly populate the registry when the requested connection is not yet
+  // registered.  On both the Cloudflare Workers runtime and Node, the registry
+  // may be empty when called from the workers-persistence path because
+  // registerDatabasesFromRuntimeConfig has not yet run for this connection. The
+  // old pattern of connecting first (which always fails) then registering as a
+  // fallback produced spurious [DEBUG] noise on every fresh start.
+  if (DatabaseConnectionRegistry.get(connectionName) === undefined) {
+    try {
+      registerDatabasesFromRuntimeConfig(databaseConfig);
+    } catch (registrationError) {
+      Logger.warn(
+        `[WorkerPersistence] Runtime database registration failed for connection '${connectionName}'`,
+        registrationError
+      );
+    }
   }
 
   try {
-    registerDatabasesFromRuntimeConfig(databaseConfig);
-    return await connect();
+    return await useEnsureDbConnected(undefined, connectionName);
   } catch (error) {
-    Logger.error('Worker persistence failed after registering runtime databases', error);
+    Logger.error('Worker persistence failed to resolve database connection', error);
     throw ErrorFactory.createConfigError(
       `Worker persistence requires a database client. Register connection '${connectionName}' or pass infrastructure.persistence.client.`
     );
@@ -2677,12 +2686,18 @@ const initializeDatacenter = (config: WorkerFactoryConfig): void => {
 const setupWorkerEventListeners = (
   worker: Worker,
   workerName: string,
+  queueName: string,
   workerVersion: string,
   features?: WorkerFactoryConfig['features']
 ): void => {
   worker.on('completed', (job: Job) => {
     try {
       Logger.debug(`Job completed: ${workerName}`, { jobId: job.id });
+      void recordQueueMonitorJob({
+        queueName,
+        status: 'completed',
+        job,
+      });
 
       if (features?.observability === true) {
         Observability.incrementCounter('worker.jobs.completed', 1, {
@@ -2699,6 +2714,14 @@ const setupWorkerEventListeners = (
   worker.on('failed', (job: Job | undefined, error: Error) => {
     try {
       Logger.error(`Job failed: ${workerName}`, { error, jobId: job?.id }, 'workers');
+      if (job) {
+        void recordQueueMonitorJob({
+          queueName,
+          status: 'failed',
+          job,
+          error,
+        });
+      }
 
       if (features?.observability === true) {
         Observability.incrementCounter('worker.jobs.failed', 1, {
@@ -2892,7 +2915,7 @@ export const WorkerFactory = Object.freeze({
       const resolvedOptions = resolveWorkerOptions(config, autoStart);
       const worker = new Worker(queueName, enhancedProcessor, resolvedOptions);
 
-      setupWorkerEventListeners(worker, name, workerVersion, features);
+      setupWorkerEventListeners(worker, name, queueName, workerVersion, features);
 
       // Update status to "starting"
       await store.update(name, {

package/src/createQueueWorker.ts

@@ -1,6 +1,7 @@
 import type { BullMQPayload, QueueMessage } from '@zintrust/core';
 import * as Core from '@zintrust/core';
 import { Env, Logger, Queue } from '@zintrust/core';
+import { recordQueueMonitorJob } from './queueMonitorHistory';
 
 type QueueApi = Readonly<{
   enqueue: (queue: string, payload: BullMQPayload, driverName?: string) => Promise<string>;
@@ -320,6 +321,19 @@ const onProcessSuccess = async <TPayload>(input: {
 }): Promise<boolean> => {
   await TypedQueue.ack(input.queueName, input.message.id, input.driverName);
 
+  await recordQueueMonitorJob({
+    queueName: input.queueName,
+    status: 'completed',
+    job: {
+      id: input.message.id,
+      name: `${input.queueName}-job`,
+      data: input.message.payload,
+      attemptsMade: getAttemptsFromMessage(input.message),
+      processedOn: input.startedAtMs,
+      finishedOn: Date.now(),
+    },
+  });
+
   if (typeof input.trackerApi.completed === 'function') {
     await input.trackerApi.completed({
       queueName: input.queueName,
@@ -386,6 +400,22 @@ const onProcessFailure = async <TPayload>(input: {
   }
 
   await TypedQueue.ack(input.queueName, input.message.id, input.driverName);
+
+  await recordQueueMonitorJob({
+    queueName: input.queueName,
+    status: 'failed',
+    job: {
+      id: input.message.id,
+      name: `${input.queueName}-job`,
+      data: input.message.payload,
+      attemptsMade: nextAttempts,
+      failedReason: failure.message,
+      processedOn: Date.now(),
+      finishedOn: Date.now(),
+    },
+    error: failure,
+  });
+
   await removeHeartbeatIfSupported(input.queueName, input.message.id);
 
   if (typeof input.trackerApi.failed === 'function') {

package/src/dashboard/workers-api.ts

@@ -591,6 +591,16 @@ async function getRedisQueueData(): Promise<QueueData> {
     }
 
     const monitor = QueueMonitor.create({
+      knownQueues: async () => {
+        const records = await WorkerFactory.listPersistedRecords();
+        return Array.from(
+          new Set(
+            records
+              .map((record) => record.queueName)
+              .filter((queueName) => typeof queueName === 'string')
+          )
+        ).sort((left, right) => left.localeCompare(right));
+      },
       redis: {
         host: redisConfig.host || 'localhost',
         port: redisConfig.port || 6379,

package/src/queueMonitorHistory.ts

@@ -0,0 +1,114 @@
+import { isNonEmptyString, isObject, Logger, queueConfig } from '@zintrust/core';
+
+type QueueMonitorStatus = 'completed' | 'failed';
+
+type QueueMonitorJobLike = {
+  id?: string;
+  name?: string;
+  data?: unknown;
+  attemptsMade?: number;
+  failedReason?: string;
+  processedOn?: number;
+  finishedOn?: number;
+};
+
+type QueueMonitorMetrics = {
+  recordJob: (
+    queueName: string,
+    status: QueueMonitorStatus,
+    job: QueueMonitorJobLike,
+    error?: Error
+  ) => Promise<void>;
+};
+
+type QueueMonitorModule = {
+  createMetrics?: (config: {
+    host: string;
+    port: number;
+    password?: string;
+    db: number;
+  }) => QueueMonitorMetrics;
+};
+
+let queueMonitorMetricsPromise: Promise<QueueMonitorMetrics | null> | null = null;
+
+const toFiniteInteger = (value: unknown, fallback: number): number => {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return Math.floor(value);
+  }
+
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) {
+      return Math.floor(parsed);
+    }
+  }
+
+  return fallback;
+};
+
+const resolveQueueMonitorRedisConfig = (): {
+  host: string;
+  port: number;
+  password?: string;
+  db: number;
+} | null => {
+  const redisConfig = queueConfig?.drivers?.redis;
+
+  if (!isObject(redisConfig) || redisConfig['driver'] !== 'redis') {
+    return null;
+  }
+
+  const host = isNonEmptyString(redisConfig['host']) ? redisConfig['host'].trim() : '127.0.0.1';
+  const port = toFiniteInteger(redisConfig['port'], 6379);
+  const db = toFiniteInteger(redisConfig['database'], 0);
+  const password = isNonEmptyString(redisConfig['password']) ? redisConfig['password'] : undefined;
+
+  return { host, port, password, db };
+};
+
+const loadQueueMonitorMetrics = async (): Promise<QueueMonitorMetrics | null> => {
+  const redisConfig = resolveQueueMonitorRedisConfig();
+  if (redisConfig === null) {
+    return null;
+  }
+
+  try {
+    const module = (await import('@zintrust/queue-monitor')) as QueueMonitorModule;
+    if (typeof module.createMetrics !== 'function') {
+      return null;
+    }
+
+    return module.createMetrics(redisConfig);
+  } catch (error) {
+    Logger.debug('Queue monitor metrics are unavailable for worker history recording', error);
+    return null;
+  }
+};
+
+const getQueueMonitorMetrics = async (): Promise<QueueMonitorMetrics | null> => {
+  queueMonitorMetricsPromise ??= loadQueueMonitorMetrics();
+  return queueMonitorMetricsPromise;
+};
+
+export const recordQueueMonitorJob = async (input: {
+  queueName: string;
+  status: QueueMonitorStatus;
+  job: QueueMonitorJobLike;
+  error?: Error;
+}): Promise<void> => {
+  const metrics = await getQueueMonitorMetrics();
+  if (metrics === null) {
+    return;
+  }
+
+  try {
+    await metrics.recordJob(input.queueName, input.status, input.job, input.error);
+  } catch (error) {
+    Logger.debug('Queue monitor history write failed', {
+      queueName: input.queueName,
+      status: input.status,
+      error,
+    });
+  }
+};

package/src/types/queue-monitor.d.ts

@@ -1,4 +1,43 @@
 declare module '@zintrust/queue-monitor' {
+  export type JobStatus = 'completed' | 'failed';
+
+  export type JobSummary = {
+    id: string | undefined;
+    name: string;
+    queue?: string;
+    data: unknown;
+    attempts: number;
+    status?: string;
+    failedReason?: string;
+    timestamp: number;
+    processedOn?: number;
+    finishedOn?: number;
+  };
+
+  export type Metrics = {
+    recordJob: (
+      queue: string,
+      status: JobStatus,
+      job: {
+        id?: string;
+        name?: string;
+        data?: unknown;
+        attemptsMade?: number;
+        failedReason?: string;
+        processedOn?: number;
+        finishedOn?: number;
+      },
+      error?: Error
+    ) => Promise<void>;
+    getStats: (
+      queue: string,
+      minutes?: number
+    ) => Promise<Array<{ time: string; completed: number; failed: number }>>;
+    getRecentJobs: (queue: string) => Promise<JobSummary[]>;
+    getFailedJobs: (queue: string) => Promise<JobSummary[]>;
+    close: () => Promise<void>;
+  };
+
   export type QueueCounts = {
     waiting: number;
     active: number;
@@ -24,6 +63,9 @@ declare module '@zintrust/queue-monitor' {
     autoRefresh?: boolean;
     refreshIntervalMs?: number;
     redis?: Record<string, unknown>;
+    knownQueues?:
+      | ReadonlyArray<string>
+      | (() => Promise<ReadonlyArray<string>> | ReadonlyArray<string>);
   };
 
   export type QueueMonitorApi = {
@@ -31,6 +73,13 @@ declare module '@zintrust/queue-monitor' {
     getSnapshot: () => Promise<QueueMonitorSnapshot>;
   };
 
+  export const createMetrics: (config: {
+    host: string;
+    port: number;
+    password?: string;
+    db: number;
+  }) => Metrics;
+
   export const QueueMonitor: Readonly<{
     create: (config: QueueMonitorConfig) => QueueMonitorApi;
   }>;