@zintrust/workers 0.1.31 → 0.1.52

package/src/WorkerInit.ts

@@ -8,10 +8,12 @@
  * - Ensures graceful startup and shutdown
  */
 
-import { Env, Logger, workersConfig } from '@zintrust/core';
+import { Env, Logger } from '@zintrust/core';
 import { ResourceMonitor } from './ResourceMonitor';
+import type { WorkerPersistenceConfig } from './WorkerFactory';
 import { WorkerFactory } from './WorkerFactory';
 import { WorkerShutdown } from './WorkerShutdown';
+import { keyPrefix } from './config/workerConfig';
 
 // ============================================================================
 // Types
@@ -105,6 +107,22 @@ function initializeResourceMonitoring(
   return false;
 }
 
+const getPersistenceOverride = (driver: string): WorkerPersistenceConfig => {
+  if (driver === 'redis') {
+    return { driver: 'redis', keyPrefix: keyPrefix() };
+  }
+
+  if (driver === 'memory') {
+    return { driver: 'memory' };
+  }
+
+  return {
+    driver: 'database',
+    connection: Env.get('WORKER_PERSISTENCE_DB_CONNECTION', 'default') ?? 'default',
+    table: Env.get('WORKER_PERSISTENCE_TABLE', 'zintrust_workers') ?? 'zintrust_workers',
+  };
+};
+
 /**
  * Check if any workers have resource monitoring enabled
  */
@@ -120,6 +138,146 @@ function shouldStartResourceMonitoring(): boolean {
   }
 }
 
+type AutoStartCandidate = {
+  name: string;
+  autoStart: boolean;
+  activeStatus?: boolean;
+};
+
+type PersistenceOverride = WorkerPersistenceConfig;
+
+type AutoStartTask = AutoStartCandidate & {
+  persistenceOverride: PersistenceOverride;
+  source: 'database' | 'redis' | 'memory';
+};
+
+const resolveAutoStartCandidates = (records: AutoStartCandidate[]): AutoStartCandidate[] => {
+  return records.filter((record) => record.activeStatus !== false && record.autoStart === true);
+};
+
+const resolvePersistenceTargets = (): Array<{
+  source: 'database' | 'redis' | 'memory';
+  persistenceOverride: PersistenceOverride;
+}> => {
+  const configuredDriver = (Env.get('WORKER_PERSISTENCE_DRIVER', 'memory') || '')
+    .toLowerCase()
+    .trim();
+  const targets: Array<{
+    source: 'database' | 'redis' | 'memory';
+    persistenceOverride: PersistenceOverride;
+  }> =
+    configuredDriver === 'database'
+      ? [
+          { source: 'database', persistenceOverride: getPersistenceOverride('database') },
+          { source: 'redis', persistenceOverride: getPersistenceOverride('redis') },
+          { source: 'memory', persistenceOverride: { driver: 'memory' } },
+        ]
+      : [
+          { source: 'redis', persistenceOverride: getPersistenceOverride('redis') },
+          { source: 'memory', persistenceOverride: { driver: 'memory' } },
+        ];
+
+  // Sort so the configured driver comes first (priority)
+  return targets.sort((a, b) => {
+    const aIsConfigured = a.persistenceOverride.driver === configuredDriver;
+    const bIsConfigured = b.persistenceOverride.driver === configuredDriver;
+
+    if (aIsConfigured && !bIsConfigured) return -1;
+    if (!aIsConfigured && bIsConfigured) return 1;
+    return 0;
+  });
+};
+
+const collectAutoStartTasks = async (): Promise<AutoStartTask[]> => {
+  const targets = resolvePersistenceTargets();
+  const tasks: AutoStartTask[] = [];
+  const seenWorkerNames = new Set<string>();
+
+  for (const target of targets) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const records = await WorkerFactory.listPersistedRecords(target.persistenceOverride);
+      const candidates = resolveAutoStartCandidates(records);
+
+      Logger.debug('Auto-start discovery', {
+        source: target.source,
+        totalRecords: records.length,
+        candidateCount: candidates.length,
+      });
+
+      for (const record of candidates) {
+        if (seenWorkerNames.has(record.name)) {
+          Logger.warn(
+            `Worker ${record.name} appears in multiple persistence stores; keeping first discovered source and skipping duplicate from ${target.source}.`
+          );
+          continue;
+        }
+
+        seenWorkerNames.add(record.name);
+        tasks.push({
+          ...record,
+          persistenceOverride: target.persistenceOverride,
+          source: target.source,
+        });
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      Logger.warn(`Auto-start discovery failed for ${target.source} persistence: ${message}`);
+    }
+  }
+
+  return tasks;
+};
+
+const isWorkerTrulyRunning = async (name: string): Promise<boolean> => {
+  const existing = WorkerFactory.get(name);
+  if (!existing) return false;
+
+  const workerLike = existing.worker as {
+    isRunning?: () => boolean | Promise<boolean>;
+    isPaused?: () => boolean;
+  };
+
+  const isRunning =
+    typeof workerLike.isRunning === 'function'
+      ? await Promise.resolve(workerLike.isRunning())
+      : false;
+  const isPaused = typeof workerLike.isPaused === 'function' ? workerLike.isPaused() : false;
+  return isRunning && !isPaused;
+};
+
+const autoStartOneWorker = async (
+  record: AutoStartTask
+): Promise<{ name: string; started: boolean; skipped: boolean }> => {
+  const existing = WorkerFactory.get(record.name);
+  if (existing) {
+    try {
+      if (await isWorkerTrulyRunning(record.name)) {
+        return { name: record.name, started: false, skipped: true };
+      }
+
+      Logger.warn(
+        `Worker ${record.name} was registered but not truly running. Restarting to recover from stale state.`
+      );
+      await WorkerFactory.restart(record.name, record.persistenceOverride);
+      return { name: record.name, started: true, skipped: false };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      Logger.warn(`Auto-start recovery failed for worker ${record.name}: ${message}`);
+      return { name: record.name, started: false, skipped: false };
+    }
+  }
+
+  try {
+    await WorkerFactory.startFromPersisted(record.name, record.persistenceOverride);
+    return { name: record.name, started: true, skipped: false };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    Logger.warn(`Auto-start failed for worker ${record.name}: ${message}`);
+    return { name: record.name, started: false, skipped: false };
+  }
+};
+
 /**
  * Initialize the worker management system
  */
@@ -185,62 +343,23 @@ async function initialize(options: IWorkerInitOptions = {}): Promise<void> {
 }
 
 async function autoStartPersistedWorkers(): Promise<void> {
-  // Check if auto-start is enabled globally via environment variable
+  const envAutoStart = Env.getBool('WORKER_AUTO_START', false);
+  const shouldAutoStart = envAutoStart;
+
   Logger.debug('Auto-start check', {
-    envAutoStart: Env.getBool('WORKER_AUTO_START', false),
-    configAutoStart: workersConfig.defaultWorker?.autoStart,
+    envAutoStart,
+    shouldAutoStart,
   });
 
-  if (workersConfig.defaultWorker?.autoStart !== true) {
+  if (!shouldAutoStart) {
     Logger.debug('Auto-start disabled - WORKER_AUTO_START is not true');
     return;
   }
 
   try {
-    const records = await WorkerFactory.listPersistedRecords();
-    Logger.debug('Found persisted records', {
-      count: records.length,
-      records: records.map((r) => ({ name: r.name, autoStart: r.autoStart })),
-    });
-
-    const candidates = records.filter((record) => {
-      if (record.activeStatus === false) {
-        return false;
-      }
-      // If autoStart is explicitly true, always include
-      if (record.autoStart === true) {
-        return true;
-      }
-      // If autoStart is null or undefined and global auto-start is enabled, include
-      if (
-        (record.autoStart === null || record.autoStart === undefined) &&
-        workersConfig.defaultWorker?.autoStart === true
-      ) {
-        return true;
-      }
+    const candidates = await collectAutoStartTasks();
 
-      return false;
-    });
-
-    Logger.debug('Auto-start candidates', {
-      count: candidates.length,
-      candidates: candidates.map((c) => c.name),
-    });
-    const results = await Promise.all(
-      candidates.map(async (record) => {
-        if (WorkerFactory.get(record.name)) {
-          return { name: record.name, started: false, skipped: true };
-        }
-        try {
-          await WorkerFactory.startFromPersisted(record.name);
-          return { name: record.name, started: true, skipped: false };
-        } catch (error) {
-          const message = error instanceof Error ? error.message : String(error);
-          Logger.warn(`Auto-start failed for worker ${record.name}: ${message}`);
-          return { name: record.name, started: false, skipped: false };
-        }
-      })
-    );
+    const results = await Promise.all(candidates.map(async (record) => autoStartOneWorker(record)));
 
     const startedCount = results.filter((item) => item.started).length;
     const skippedCount = results.filter((item) => item.skipped).length;

package/src/WorkerMetrics.ts

@@ -11,8 +11,9 @@ import {
   createRedisConnection,
   type RedisConfig,
 } from '@zintrust/core';
-import type IORedis from 'ioredis';
-import type { ChainableCommander } from 'ioredis';
+
+type RedisConnection = ReturnType<typeof createRedisConnection>;
+type RedisPipeline = ReturnType<RedisConnection['pipeline']>;
 
 export type MetricType =
   | 'processed'
@@ -96,14 +97,14 @@ const runInBatches = async <T>(
 };
 
 // Internal state
-let redisClient: IORedis | null = null;
+let redisClient: RedisConnection | null = null;
 let cachedConfig: RedisConfig | null = null;
 let keepLoggin = 0;
 
 /**
  * Helper: Get valid Redis client
  */
-const getValidClient = async (): Promise<IORedis> => {
+const getValidClient = async (): Promise<RedisConnection> => {
   if (!cachedConfig) {
     throw ErrorFactory.createWorkerError('WorkerMetrics not initialized. Call initialize() first.');
   }
@@ -113,7 +114,12 @@ const getValidClient = async (): Promise<IORedis> => {
     redisClient = createRedisConnection(cachedConfig);
   }
 
-  return redisClient;
+  const client = redisClient;
+  if (!client) {
+    throw ErrorFactory.createConnectionError('Failed to initialize Redis client');
+  }
+
+  return client;
 };
 
 /**
@@ -166,7 +172,7 @@ const roundTimestamp = (date: Date, granularity: MetricGranularity): Date => {
  * Helper: Clean up old metrics based on retention policy
  */
 const cleanupOldMetrics = async (
-  client: IORedis,
+  client: RedisConnection,
   key: string,
   granularity: MetricGranularity
 ): Promise<void> => {
@@ -280,9 +286,9 @@ const handleUninitializedMetrics = (optionsList: MetricQueryOptions[]): Aggregat
  * Helper: Build Redis pipeline for batch metrics query
  */
 const buildMetricsPipeline = (
-  client: IORedis,
+  client: RedisConnection,
   optionsList: MetricQueryOptions[]
-): ChainableCommander => {
+): RedisPipeline => {
   const pipeline = client.pipeline();
 
   for (const options of optionsList) {

package/src/WorkerRegistry.ts

@@ -82,6 +82,13 @@ const registrations = new Map<string, RegisterWorkerOptions>();
 const STOPPED_WORKER_CLEANUP_DELAY = 5 * 60 * 1000; // 5 minutes
 const cleanupTimers = new Map<string, NodeJS.Timeout>();
 
+type UnrefableTimer = { unref: () => void };
+
+const isUnrefableTimer = (value: unknown): value is UnrefableTimer => {
+  if (typeof value !== 'object' || value === null) return false;
+  return 'unref' in value && typeof (value as UnrefableTimer).unref === 'function';
+};
+
 /**
  * Helper: Schedule cleanup of stopped worker
  */
@@ -109,6 +116,10 @@ const scheduleStoppedWorkerCleanup = (name: string): void => {
     }
   }, STOPPED_WORKER_CLEANUP_DELAY);
 
+  if (isUnrefableTimer(timer)) {
+    timer.unref();
+  }
+
   cleanupTimers.set(name, timer);
 };
 

package/src/WorkerShutdown.ts

@@ -5,7 +5,7 @@
  * Coordinates orderly shutdown of all worker modules and the WorkerFactory.
  */
 
-import { Cloudflare, Logger } from '@zintrust/core';
+import { Logger } from '@zintrust/core';
 import { WorkerFactory } from './WorkerFactory';
 
 // ============================================================================
@@ -36,12 +36,6 @@ interface IShutdownState {
   reason: string | null;
 }
 
-type DurableShutdownState = {
-  shuttingDown: boolean;
-  startedAt?: string;
-  reason?: string;
-};
-
 // ============================================================================
 // Implementation
 // ============================================================================
@@ -53,58 +47,6 @@ const state: IShutdownState = {
   reason: null,
 };
 
-const getDurableShutdownStub = (): {
-  fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
-} | null => {
-  const env = Cloudflare.getWorkersEnv();
-  if (env === null) return null;
-
-  const namespace = env['WORKER_SHUTDOWN'] as
-    | {
-        idFromName?: (name: string) => unknown;
-        get?: (id: unknown) => {
-          fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
-        };
-      }
-    | undefined;
-
-  if (
-    !namespace ||
-    typeof namespace.idFromName !== 'function' ||
-    typeof namespace.get !== 'function'
-  ) {
-    return null;
-  }
-
-  const id = namespace.idFromName('zintrust-shutdown');
-  return namespace.get(id) ?? null;
-};
-
-const requestDurableShutdown = async (reason = 'manual'): Promise<boolean> => {
-  const stub = getDurableShutdownStub();
-  if (!stub) {
-    Logger.warn('Worker shutdown Durable Object binding not configured');
-    return false;
-  }
-
-  const res = await stub.fetch('https://worker-shutdown/shutdown', {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ reason }),
-  });
-
-  return res.ok;
-};
-
-const getDurableShutdownState = async (): Promise<DurableShutdownState | null> => {
-  const stub = getDurableShutdownStub();
-  if (!stub) return null;
-
-  const res = await stub.fetch('https://worker-shutdown/status');
-  if (!res.ok) return null;
-  return (await res.json()) as DurableShutdownState;
-};
-
 let shutdownHandlersRegistered = false;
 
 const signalHandlers: {
@@ -300,14 +242,4 @@ export const WorkerShutdown = Object.freeze({
    * Get current shutdown state
    */
   getShutdownState,
-
-  /**
-   * Request shutdown via Durable Object (Workers)
-   */
-  requestDurableShutdown,
-
-  /**
-   * Read shutdown state from Durable Object (Workers)
-   */
-  getDurableShutdownState,
 });

package/src/config/workerConfig.ts

@@ -1,4 +1,4 @@
-import { Env } from '@zintrust/core';
+import { Env, appConfig } from '@zintrust/core';
 
 const normalizeBaseUrl = (value: string): string => {
   let end = value.length;
@@ -23,3 +23,11 @@ const resolveWorkerApiUrl = (): string => {
 export const WorkerConfig = Object.freeze({
   getWorkerBaseUrl: resolveWorkerApiUrl,
 });
+
+export const keyPrefix = (): string => {
+  const redisKeyPrefix = (Env.get('WORKER_PERSISTENCE_REDIS_KEY_PREFIX', '') ?? '').trim();
+
+  return redisKeyPrefix
+    ? `${redisKeyPrefix}_worker_${appConfig.prefix}`
+    : `worker_${appConfig.prefix}`;
+};