@zintrust/workers 0.1.28 → 0.1.30

package/src/WorkerFactory.ts

@@ -17,6 +17,7 @@ import {
   registerDatabasesFromRuntimeConfig,
   useEnsureDbConnected,
   workersConfig,
+  ZintrustLang,
   type IDatabase,
   type RedisConfig,
   type WorkerStatus,
@@ -110,9 +111,10 @@ export type WorkerFactoryConfig = {
   version?: string;
   queueName: string;
   processor: (job: Job) => Promise<unknown>;
-  processorPath?: string;
+  processorSpec?: string;
   options?: WorkerOptions;
   autoStart?: boolean;
+  activeStatus?: boolean;
   infrastructure?: {
     redis?: RedisConfigInput;
     persistence?: WorkerPersistenceConfig;
@@ -189,7 +191,8 @@ const workers = new Map<string, WorkerInstance>();
 let workerStore: WorkerStore = InMemoryWorkerStore.create();
 let workerStoreConfigured = false;
 let workerStoreConfig: WorkerPersistenceConfig | null = null;
-type ProcessorResolver = (
+
+export type ProcessorResolver = (
   name: string
 ) =>
   | WorkerFactoryConfig['processor']
@@ -199,6 +202,20 @@ type ProcessorResolver = (
 const processorRegistry = new Map<string, WorkerFactoryConfig['processor']>();
 const processorPathRegistry = new Map<string, string>();
 const processorResolvers: ProcessorResolver[] = [];
+const processorSpecRegistry = new Map<string, WorkerFactoryConfig['processor']>();
+
+type CachedProcessor = {
+  code: string;
+  processor: WorkerFactoryConfig['processor'];
+  etag?: string;
+  cachedAt: number;
+  expiresAt: number;
+  size: number;
+  lastAccess: number;
+};
+
+const processorCache = new Map<string, CachedProcessor>();
+let processorCacheSize = 0;
 
 const buildPersistenceBootstrapConfig = (): WorkerFactoryConfig => {
   const driver = Env.get('WORKER_PERSISTENCE_DRIVER', 'memory') as 'memory' | 'redis' | 'database';
@@ -249,12 +266,110 @@ const registerProcessorResolver = (resolver: ProcessorResolver): void => {
   processorResolvers.push(resolver);
 };
 
+const registerProcessorSpec = (spec: string, processor: WorkerFactoryConfig['processor']): void => {
+  if (!spec || typeof processor !== 'function') return;
+  processorSpecRegistry.set(normalizeProcessorSpec(spec), processor);
+};
+
 const decodeProcessorPathEntities = (value: string): string =>
   value
     .replaceAll(/&#x2F;/gi, '/')
     .replaceAll('&#47;', '/')
     .replaceAll(/&sol;/gi, '/');
 
+const isUrlSpec = (spec: string): boolean => {
+  if (spec.startsWith('url:')) return true;
+  return spec.includes('://');
+};
+
+const normalizeProcessorSpec = (spec: string): string =>
+  spec.startsWith('url:') ? spec.slice(4) : spec;
+
+const parseCacheControl = (value: string | null): { maxAge?: number } => {
+  if (!value) return {};
+  const parts = value.split(',').map((part) => part.trim().toLowerCase());
+  const maxAge = parts.find((part) => part.startsWith('max-age='));
+  if (!maxAge) return {};
+  const raw = maxAge.split('=')[1];
+  const parsed = Number.parseInt(raw ?? '', 10);
+  return Number.isFinite(parsed) ? { maxAge: parsed } : {};
+};
+
+const getProcessorSpecConfig = (): typeof workersConfig.processorSpec =>
+  workersConfig.processorSpec;
+
+const computeSha256 = async (value: string): Promise<string> => {
+  if (typeof globalThis !== 'undefined' && globalThis.crypto?.subtle) {
+    const data = new TextEncoder().encode(value);
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', data);
+    return Array.from(new Uint8Array(digest))
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('');
+  }
+
+  if (typeof NodeSingletons.createHash === 'function') {
+    return NodeSingletons.createHash('sha256').update(value).digest('hex');
+  }
+
+  return String(Math.random()).slice(2);
+};
+
+const toBase64 = (value: string): string => {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(value, 'utf-8').toString('base64');
+  }
+
+  if (typeof globalThis !== 'undefined' && typeof globalThis.btoa === 'function') {
+    const bytes = new TextEncoder().encode(value);
+    let binary = '';
+    bytes.forEach((byte) => {
+      binary += String.fromCodePoint(byte);
+    });
+    return globalThis.btoa(binary);
+  }
+
+  return value;
+};
+
+const getCachedProcessor = (key: string): CachedProcessor | null => {
+  const entry = processorCache.get(key);
+  if (!entry) return null;
+  const now = Date.now();
+  if (entry.expiresAt <= now) {
+    processorCache.delete(key);
+    processorCacheSize -= entry.size;
+    return null;
+  }
+  entry.lastAccess = now;
+  return entry;
+};
+
+const evictCacheIfNeeded = (maxSize: number): void => {
+  if (processorCacheSize <= maxSize) return;
+  const entries = Array.from(processorCache.entries());
+  entries.sort((a, b) => a[1].lastAccess - b[1].lastAccess);
+  for (const [key, entry] of entries) {
+    if (processorCacheSize <= maxSize) break;
+    processorCache.delete(key);
+    processorCacheSize -= entry.size;
+  }
+};
+
+const setCachedProcessor = (key: string, entry: CachedProcessor, maxSize: number): void => {
+  const existing = processorCache.get(key);
+  if (existing) {
+    processorCacheSize -= existing.size;
+  }
+  processorCache.set(key, entry);
+  processorCacheSize += entry.size;
+  evictCacheIfNeeded(maxSize);
+};
+
+const isAllowedRemoteHost = (host: string): boolean => {
+  const allowlist = getProcessorSpecConfig().remoteAllowlist.map((value) => value.toLowerCase());
+  return allowlist.includes(host.toLowerCase());
+};
+
 const waitForWorkerConnection = async (
   worker: Worker,
   name: string,
@@ -329,6 +444,250 @@ const sanitizeProcessorPath = (value: string): string => {
   return isAbsolutePath ? base : path.resolve(process.cwd(), relativePath);
 };
 
+const stripProcessorExtension = (value: string): string => value.replace(/\.(ts|js)$/i, '');
+
+const normalizeModulePath = (value: string): string => value.replaceAll('\\', '/');
+
+const buildProcessorModuleCandidates = (modulePath: string, resolvedPath: string): string[] => {
+  const candidates: string[] = [];
+  const normalized = normalizeModulePath(modulePath.trim());
+  const normalizedResolved = normalizeModulePath(resolvedPath);
+
+  if (normalized.startsWith('/app/')) {
+    candidates.push(`@app/${stripProcessorExtension(normalized.slice(5))}`);
+  } else if (normalized.startsWith('app/')) {
+    candidates.push(`@app/${stripProcessorExtension(normalized.slice(4))}`);
+  }
+
+  const appIndex = normalizedResolved.lastIndexOf('/app/');
+  if (appIndex !== -1) {
+    const relative = normalizedResolved.slice(appIndex + 5);
+    if (relative) {
+      candidates.push(`@app/${stripProcessorExtension(relative)}`);
+    }
+  }
+
+  return Array.from(new Set(candidates));
+};
+
+const pickProcessorFromModule = (
+  mod: Record<string, unknown> | undefined,
+  source: string
+): WorkerFactoryConfig['processor'] | undefined => {
+  const candidate = mod?.['default'] ?? mod?.['processor'] ?? mod?.['handler'] ?? mod?.['handle'];
+  if (typeof candidate !== 'function') {
+    const keys = mod ? Object.keys(mod) : [];
+    Logger.warn(
+      `Module imported from ${source} but no valid processor function found (exported: ${keys.join(', ')})`
+    );
+    return undefined;
+  }
+
+  return candidate as WorkerFactoryConfig['processor'];
+};
+
+const extractZinTrustProcessor = (
+  mod: Record<string, unknown> | undefined,
+  source: string
+): WorkerFactoryConfig['processor'] | undefined => {
+  const candidate = mod?.['ZinTrustProcessor'];
+  if (typeof candidate !== 'function') {
+    const keys = mod ? Object.keys(mod) : [];
+    Logger.warn(
+      `Module imported from ${source} but missing ZinTrustProcessor export (exported: ${keys.join(', ')})`
+    );
+    return undefined;
+  }
+
+  return candidate as WorkerFactoryConfig['processor'];
+};
+
+const readResponseBody = async (response: Response, maxSize: number): Promise<string> => {
+  const contentLength = response.headers.get('content-length');
+  if (contentLength) {
+    const size = Number.parseInt(contentLength, 10);
+    if (Number.isFinite(size) && size > maxSize) {
+      throw ErrorFactory.createConfigError('PROCESSOR_FETCH_SIZE_EXCEEDED');
+    }
+  }
+
+  const buffer = await response.arrayBuffer();
+  if (buffer.byteLength > maxSize) {
+    throw ErrorFactory.createConfigError('PROCESSOR_FETCH_SIZE_EXCEEDED');
+  }
+
+  return new TextDecoder().decode(buffer);
+};
+
+const computeCacheTtlSeconds = (
+  config: ReturnType<typeof getProcessorSpecConfig>,
+  cacheControl: { maxAge?: number }
+): number =>
+  Math.min(config.cacheMaxTtlSeconds, cacheControl.maxAge ?? config.cacheDefaultTtlSeconds);
+
+const refreshCachedProcessor = (
+  existing: CachedProcessor,
+  config: ReturnType<typeof getProcessorSpecConfig>,
+  cacheControl: { maxAge?: number }
+): WorkerFactoryConfig['processor'] => {
+  const ttl = computeCacheTtlSeconds(config, cacheControl);
+  const now = Date.now();
+  existing.expiresAt = now + ttl * 1000;
+  existing.lastAccess = now;
+  return existing.processor;
+};
+
+const cacheProcessorFromResponse = async (params: {
+  response: Response;
+  normalized: string;
+  config: ReturnType<typeof getProcessorSpecConfig>;
+  cacheKey: string;
+}): Promise<WorkerFactoryConfig['processor']> => {
+  const { response, normalized, config, cacheKey } = params;
+  const code = await readResponseBody(response, config.fetchMaxSizeBytes);
+  const dataUrl = `data:text/javascript;base64,${toBase64(code)}`;
+  const mod = await import(dataUrl);
+  const processor = extractZinTrustProcessor(mod as Record<string, unknown>, normalized);
+  if (!processor) {
+    throw ErrorFactory.createConfigError('INVALID_PROCESSOR_URL_EXPORT');
+  }
+
+  const cacheControl = parseCacheControl(response.headers.get('cache-control'));
+  const ttl = computeCacheTtlSeconds(config, cacheControl);
+  const size = new TextEncoder().encode(code).byteLength;
+  const now = Date.now();
+  setCachedProcessor(
+    cacheKey,
+    {
+      code,
+      processor,
+      etag: response.headers.get('etag') ?? undefined,
+      cachedAt: now,
+      expiresAt: now + ttl * 1000,
+      size,
+      lastAccess: now,
+    },
+    config.cacheMaxSizeBytes
+  );
+
+  return processor;
+};
+
+const delay = (ms: number): Promise<void> =>
+  new Promise((resolve) => {
+    globalThis.setTimeout(resolve, ms);
+  });
+
+const fetchProcessorAttempt = async (params: {
+  normalized: string;
+  config: ReturnType<typeof getProcessorSpecConfig>;
+  cacheKey: string;
+  existing: CachedProcessor | undefined;
+  attempt: number;
+  maxAttempts: number;
+}): Promise<WorkerFactoryConfig['processor'] | undefined> => {
+  const { normalized, config, cacheKey, existing, attempt, maxAttempts } = params;
+  const controller = new AbortController();
+  const timeoutId = globalThis.setTimeout(() => controller.abort(), config.fetchTimeoutMs);
+
+  try {
+    const headers: Record<string, string> = {};
+    if (existing?.etag) headers['If-None-Match'] = existing.etag;
+
+    const response = await fetch(normalized, {
+      method: 'GET',
+      headers,
+      signal: controller.signal,
+    });
+
+    if (response.status === 304 && existing) {
+      const cacheControl = parseCacheControl(response.headers.get('cache-control'));
+      return refreshCachedProcessor(existing, config, cacheControl);
+    }
+
+    if (!response.ok) {
+      throw ErrorFactory.createConfigError(`PROCESSOR_FETCH_FAILED:${response.status}`);
+    }
+
+    return await cacheProcessorFromResponse({ response, normalized, config, cacheKey });
+  } catch (error) {
+    if (controller.signal.aborted) {
+      Logger.error('Processor URL fetch timeout', error);
+    } else {
+      Logger.error('Processor URL fetch failed', error);
+    }
+
+    if (attempt >= maxAttempts) {
+      return undefined;
+    }
+
+    await delay(config.retryBackoffMs * attempt);
+    return fetchProcessorAttempt({
+      normalized,
+      config,
+      cacheKey,
+      existing,
+      attempt: attempt + 1,
+      maxAttempts,
+    });
+  } finally {
+    clearTimeout(timeoutId);
+  }
+};
+
+const resolveProcessorFromUrl = async (
+  spec: string
+): Promise<WorkerFactoryConfig['processor'] | undefined> => {
+  const normalized = normalizeProcessorSpec(spec);
+  let parsed: URL;
+  try {
+    parsed = new URL(normalized);
+  } catch (error) {
+    Logger.error('Invalid processor URL spec', error);
+    return undefined;
+  }
+
+  if (parsed.protocol === 'file:') {
+    const filePath = decodeURIComponent(parsed.pathname);
+    return resolveProcessorFromPath(filePath);
+  }
+
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'file:') {
+    Logger.warn(
+      `Invalid processor URL protocol: ${parsed.protocol}. Only https:// and file:// are supported.`
+    );
+  }
+
+  if (!isAllowedRemoteHost(parsed.host) && parsed.protocol !== 'file:') {
+    Logger.warn(`Invalid processor URL host: ${parsed.host}. Host is not in the allowlist.`);
+  }
+
+  const config = getProcessorSpecConfig();
+  const cacheKey = await computeSha256(normalized);
+  const cached = getCachedProcessor(cacheKey);
+  if (cached) return cached.processor;
+
+  return fetchProcessorAttempt({
+    normalized,
+    config,
+    cacheKey,
+    existing: processorCache.get(cacheKey),
+    attempt: 1,
+    maxAttempts: Math.max(1, config.retryAttempts),
+  });
+};
+
+const resolveProcessorSpec = async (
+  spec: string
+): Promise<WorkerFactoryConfig['processor'] | undefined> => {
+  if (!spec) return undefined;
+  const normalized = normalizeProcessorSpec(spec);
+  const prebuilt = processorSpecRegistry.get(normalized) ?? processorSpecRegistry.get(spec);
+  if (prebuilt) return prebuilt;
+  if (isUrlSpec(spec)) return resolveProcessorFromUrl(spec);
+  return resolveProcessorFromPath(spec);
+};
+
 const resolveProcessorFromPath = async (
   modulePath: string
 ): Promise<WorkerFactoryConfig['processor'] | undefined> => {
@@ -338,23 +697,34 @@ const resolveProcessorFromPath = async (
   const resolved = sanitizeProcessorPath(trimmed);
   if (!resolved) return undefined;
 
-  try {
-    const mod = await import(resolved);
-    const candidate = mod?.default ?? mod?.processor ?? mod?.handler ?? mod?.handle;
-
-    if (typeof candidate !== 'function') {
-      Logger.warn(
-        `Module imported from ${resolved} but no valid processor function found (exported: ${Object.keys(mod)})`
-      );
+  const importProcessorFromCandidates = async (
+    candidates: string[]
+  ): Promise<WorkerFactoryConfig['processor'] | undefined> => {
+    if (candidates.length === 0) return undefined;
+    const [candidatePath, ...rest] = candidates;
+    try {
+      const mod = await import(candidatePath);
+      const candidate = pickProcessorFromModule(mod as Record<string, unknown>, candidatePath);
+      if (candidate) return candidate;
+    } catch (candidateError) {
+      Logger.debug(`Processor module candidate import failed: ${candidatePath}`, candidateError);
     }
 
-    return typeof candidate === 'function'
-      ? (candidate as WorkerFactoryConfig['processor'])
-      : undefined;
+    return importProcessorFromCandidates(rest);
+  };
+
+  try {
+    const mod = await import(resolved);
+    const candidate = pickProcessorFromModule(mod as Record<string, unknown>, resolved);
+    if (candidate) return candidate;
   } catch (err) {
+    const candidates = buildProcessorModuleCandidates(trimmed, resolved);
+    const resolvedCandidate = await importProcessorFromCandidates(candidates);
+    if (resolvedCandidate) return resolvedCandidate;
     Logger.error(`Failed to import processor from path: ${resolved}`, err);
-    return undefined;
   }
+
+  return undefined;
 };
 
 const resolveProcessor = async (
@@ -366,7 +736,7 @@ const resolveProcessor = async (
   const pathHint = processorPathRegistry.get(name);
   if (pathHint) {
     try {
-      const resolved = await resolveProcessorFromPath(pathHint);
+      const resolved = await resolveProcessorSpec(pathHint);
       if (resolved) return resolved;
     } catch (error) {
       Logger.error(`Failed to resolve processor module for "${name}"`, error);
@@ -823,8 +1193,14 @@ const resolveRedisFallbacks = (): {
   const queueRedis = queueConfig.drivers.redis;
   return {
     host: queueRedis?.driver === 'redis' ? queueRedis.host : Env.get('REDIS_HOST', '127.0.0.1'),
-    port: queueRedis?.driver === 'redis' ? queueRedis.port : Env.getInt('REDIS_PORT', 6379),
-    db: queueRedis?.driver === 'redis' ? queueRedis.database : Env.getInt('REDIS_DB', 0),
+    port:
+      queueRedis?.driver === 'redis'
+        ? queueRedis.port
+        : Env.getInt('REDIS_PORT', ZintrustLang.REDIS_DEFAULT_PORT),
+    db:
+      queueRedis?.driver === 'redis'
+        ? queueRedis.database
+        : Env.getInt('REDIS_QUEUE_DB', ZintrustLang.REDIS_DEFAULT_DB),
     password:
       queueRedis?.driver === 'redis' ? (queueRedis.password ?? '') : Env.get('REDIS_PASSWORD', ''),
   };
@@ -837,7 +1213,9 @@ const resolveRedisConfigFromEnv = (config: RedisEnvConfig, context: string): Red
     context
   );
   const port = resolveEnvInt(String(config.port ?? 'REDIS_PORT'), fallback.port);
-  const db = config.db ? Number(config.db) : Env.getInt('REDIS_DB', fallback.db);
+
+  const db = resolveEnvInt(config.db ?? 'REDIS_QUEUE_DB', fallback.db);
+
   const password = resolveEnvString(config.password ?? 'REDIS_PASSWORD', fallback.password);
 
   return {
@@ -1117,8 +1495,9 @@ const ensureWorkerStoreConfigured = async (): Promise<void> => {
 
 const buildWorkerRecord = (config: WorkerFactoryConfig, status: string): WorkerRecord => {
   const now = new Date();
-  const decodedProcessorPath = config.processorPath
-    ? decodeProcessorPathEntities(config.processorPath)
+
+  const normalizedProcessorSpec = config.processorSpec
+    ? normalizeProcessorSpec(config.processorSpec)
     : null;
   return {
     name: config.name,
@@ -1128,7 +1507,8 @@ const buildWorkerRecord = (config: WorkerFactoryConfig, status: string): WorkerR
     autoStart: resolveAutoStart(config),
     concurrency: config.options?.concurrency ?? 1,
     region: config.datacenter?.primaryRegion ?? null,
-    processorPath: decodedProcessorPath,
+    processorSpec: normalizedProcessorSpec ?? null,
+    activeStatus: config.activeStatus ?? true,
     features: config.features ? { ...config.features } : null,
     infrastructure: config.infrastructure ? { ...config.infrastructure } : null,
     datacenter: config.datacenter ? { ...config.datacenter } : null,
@@ -1473,6 +1853,7 @@ const registerWorkerInstance = (params: {
   WorkerRegistry.register({
     name: config.name,
     config: {},
+    activeStatus: config.activeStatus ?? true,
     version: workerVersion,
     region: config.datacenter?.primaryRegion,
     queues: [queueName],
@@ -1486,6 +1867,7 @@ const registerWorkerInstance = (params: {
           region: config.datacenter?.primaryRegion ?? 'unknown',
           queueName,
           concurrency: options?.concurrency ?? 1,
+          activeStatus: config.activeStatus ?? true,
           startedAt: new Date(),
           stoppedAt: null,
           lastProcessedAt: null,
@@ -1548,7 +1930,9 @@ export const WorkerFactory = Object.freeze({
   registerProcessors,
   registerProcessorPaths,
   registerProcessorResolver,
+  registerProcessorSpec,
   resolveProcessorPath,
+  resolveProcessorSpec,
 
   /**
    * Create new worker with full setup
@@ -1638,13 +2022,6 @@ export const WorkerFactory = Object.freeze({
       // Start health monitoring for the worker
       startHealthMonitoring(name, worker, queueName);
 
-      Logger.info(`Worker created: ${name}@${workerVersion}`, {
-        queueName,
-        features: Object.keys(features ?? {}).filter(
-          (k) => features?.[k as keyof typeof features] === true
-        ),
-      });
-
       return worker;
     } catch (error) {
       // Handle failure - update status to "failed"
@@ -1702,13 +2079,20 @@ export const WorkerFactory = Object.freeze({
   /**
    * Stop worker
    */
-  async stop(name: string, persistenceOverride?: WorkerPersistenceConfig): Promise<void> {
+  async stop(
+    name: string,
+    persistenceOverride?: WorkerPersistenceConfig,
+    options?: { skipPersistedUpdate?: boolean }
+  ): Promise<void> {
+    const skipPersistedUpdate = options?.skipPersistedUpdate === true;
     const instance = workers.get(name);
     const store = await validateAndGetStore(name, instance?.config, persistenceOverride);
 
     if (!instance) {
-      await store.update(name, { status: 'stopped', updatedAt: new Date() });
-      Logger.info(`Worker marked stopped (not running): ${name}`);
+      if (!skipPersistedUpdate) {
+        await store.update(name, { status: 'stopped', updatedAt: new Date() });
+        Logger.info(`Worker marked stopped (not running): ${name}`);
+      }
       return;
     }
 
@@ -1747,14 +2131,16 @@ export const WorkerFactory = Object.freeze({
     // Stop health monitoring for this worker
     HealthMonitor.unregister(name);
 
-    try {
-      await store.update(name, {
-        status: WorkerCreationStatus.STOPPED,
-        updatedAt: new Date(),
-      });
-      Logger.info(`Worker "${name}" status updated to stopped`);
-    } catch (error) {
-      Logger.error(`Failed to update worker "${name}" status`, error as Error);
+    if (!skipPersistedUpdate) {
+      try {
+        await store.update(name, {
+          status: WorkerCreationStatus.STOPPED,
+          updatedAt: new Date(),
+        });
+        Logger.info(`Worker "${name}" status updated to stopped`);
+      } catch (error) {
+        Logger.error(`Failed to update worker "${name}" status`, error as Error);
+      }
     }
 
     await WorkerRegistry.stop(name);
@@ -1870,6 +2256,47 @@ export const WorkerFactory = Object.freeze({
     await WorkerFactory.startFromPersisted(name, persistenceOverride);
   },
 
+  /**
+   * Update active status for a worker
+   */
+  async setWorkerActiveStatus(
+    name: string,
+    activeStatus: boolean,
+    persistenceOverride?: WorkerPersistenceConfig
+  ): Promise<void> {
+    const instance = workers.get(name);
+    const store = await validateAndGetStore(name, instance?.config, persistenceOverride);
+
+    if (instance) {
+      instance.config.activeStatus = activeStatus;
+    }
+
+    await store.update(name, { activeStatus, updatedAt: new Date() });
+    WorkerRegistry.setActiveStatus(name, activeStatus);
+
+    if (activeStatus === false && instance) {
+      await WorkerFactory.stop(name, persistenceOverride);
+    }
+  },
+
+  /**
+   * Get active status for a worker
+   */
+  async getWorkerActiveStatus(
+    name: string,
+    persistenceOverride?: WorkerPersistenceConfig
+  ): Promise<boolean | null> {
+    const instance = workers.get(name);
+    if (instance?.config.activeStatus !== undefined) {
+      return instance.config.activeStatus;
+    }
+
+    const store = await getStoreForWorker(instance?.config, persistenceOverride);
+    const record = await store.get(name);
+    if (!record) return null;
+    return record.activeStatus ?? true;
+  },
+
   /**
    * Update persisted worker record and in-memory config if running.
    */
@@ -1906,6 +2333,8 @@ export const WorkerFactory = Object.freeze({
           ...cfg.options,
           concurrency: merged.concurrency ?? cfg.options?.concurrency,
         },
+        processorSpec: merged.processorSpec ?? cfg.processorSpec,
+        activeStatus: merged.activeStatus ?? cfg.activeStatus,
         infrastructure: (merged.infrastructure as unknown) ?? cfg.infrastructure,
         features: (merged.features as unknown) ?? cfg.features,
         datacenter: (merged.datacenter as unknown) ?? cfg.datacenter,
@@ -1925,6 +2354,15 @@ export const WorkerFactory = Object.freeze({
       throw ErrorFactory.createNotFoundError(`Worker "${name}" not found`);
     }
 
+    if (instance.config.activeStatus === false) {
+      throw ErrorFactory.createConfigError(`Worker "${name}" is inactive`);
+    }
+
+    const persisted = await store.get(name);
+    if (persisted?.activeStatus === false) {
+      throw ErrorFactory.createConfigError(`Worker "${name}" is inactive`);
+    }
+
     const version = instance.config.version ?? '1.0.0';
     await WorkerRegistry.start(name, version);
 
@@ -1948,7 +2386,7 @@ export const WorkerFactory = Object.freeze({
    */
   async listPersisted(
     persistenceOverride?: WorkerPersistenceConfig,
-    options?: { offset?: number; limit?: number; search?: string }
+    options?: { offset?: number; limit?: number; search?: string; includeInactive?: boolean }
   ): Promise<string[]> {
     const records = await WorkerFactory.listPersistedRecords(persistenceOverride, options);
     return records.map((record) => record.name);
@@ -1956,15 +2394,18 @@ export const WorkerFactory = Object.freeze({
 
   async listPersistedRecords(
     persistenceOverride?: WorkerPersistenceConfig,
-    options?: { offset?: number; limit?: number; search?: string }
+    options?: { offset?: number; limit?: number; search?: string; includeInactive?: boolean }
   ): Promise<WorkerRecord[]> {
+    const includeInactive = options?.includeInactive === true;
     if (!persistenceOverride) {
       await ensureWorkerStoreConfigured();
-      return workerStore.list(options);
+      const records = await workerStore.list(options);
+      return includeInactive ? records : records.filter((record) => record.activeStatus !== false);
     }
 
     const store = await resolveWorkerStoreForPersistence(persistenceOverride);
-    return store.list(options);
+    const records = await store.list(options);
+    return includeInactive ? records : records.filter((record) => record.activeStatus !== false);
   },
 
   /**
@@ -1979,11 +2420,16 @@ export const WorkerFactory = Object.freeze({
       throw ErrorFactory.createNotFoundError(`Worker "${name}" not found in persistence store`);
     }
 
+    if (record.activeStatus === false) {
+      throw ErrorFactory.createConfigError(`Worker "${name}" is inactive`);
+    }
+
     let processor = await resolveProcessor(name);
 
-    if (!processor && record.processorPath) {
+    const spec = record.processorSpec ?? undefined;
+    if (!processor && spec) {
       try {
-        processor = await resolveProcessorFromPath(record.processorPath);
+        processor = await resolveProcessorSpec(spec);
       } catch (error) {
         Logger.error(`Failed to resolve processor module for "${name}"`, error);
       }
@@ -1991,7 +2437,7 @@ export const WorkerFactory = Object.freeze({
 
     if (!processor) {
       throw ErrorFactory.createConfigError(
-        `Worker "${name}" processor is not registered or resolvable. Register the processor at startup or persist a processorPath.`
+        `Worker "${name}" processor is not registered or resolvable. Register the processor at startup or persist a processorSpec.`
       );
     }
 
@@ -2000,7 +2446,8 @@ export const WorkerFactory = Object.freeze({
       queueName: record.queueName,
       version: record.version ?? undefined,
       processor,
-      processorPath: record.processorPath ?? undefined,
+      processorSpec: record.processorSpec ?? undefined,
+      activeStatus: record.activeStatus ?? true,
       autoStart: true, // Override to true when manually starting
       options: { concurrency: record.concurrency } as WorkerOptions,
       infrastructure: record.infrastructure as WorkerFactoryConfig['infrastructure'],
@@ -2104,9 +2551,47 @@ export const WorkerFactory = Object.freeze({
   async shutdown(): Promise<void> {
     Logger.info('WorkerFactory shutting down...');
 
-    const workerNames = Array.from(workers.keys());
+    const workerEntries = Array.from(workers.entries());
+    const workerNames = workerEntries.map(([name]) => name);
 
-    await Promise.all(workerNames.map(async (name) => WorkerFactory.stop(name)));
+    // Bulk-update persisted statuses before stopping workers to avoid per-worker DB updates
+    // during shutdown (which can fail if DB connections are closing).
+    const storeGroups = new Map<WorkerStore, string[]>();
+
+    // Parallel get stores for all workers
+    const storePromises = workerEntries.map(async ([name, instance]) => {
+      const store = await getStoreForWorker(instance.config);
+      return { name, store };
+    });
+
+    const storeMappings = await Promise.all(storePromises);
+
+    for (const { name, store } of storeMappings) {
+      const existing = storeGroups.get(store);
+      if (existing) {
+        existing.push(name);
+      } else {
+        storeGroups.set(store, [name]);
+      }
+    }
+
+    // Parallel bulk updates for all store groups
+    const updatePromises = Array.from(storeGroups.entries()).map(async ([store, names]) => {
+      if (typeof store.updateMany === 'function') {
+        await store.updateMany(names, {
+          status: WorkerCreationStatus.STOPPED,
+          updatedAt: new Date(),
+        });
+      }
+    });
+
+    await Promise.all(updatePromises);
+
+    await Promise.all(
+      workerNames.map(async (name) =>
+        WorkerFactory.stop(name, undefined, { skipPersistedUpdate: true })
+      )
+    );
 
     // Shutdown all modules
     ResourceMonitor.stop();
@@ -2129,6 +2614,17 @@ export const WorkerFactory = Object.freeze({
 
     Logger.info('WorkerFactory shutdown complete');
   },
+
+  /**
+   * Reset persistence connection state.
+   * Useful when connections become stale in long-running processes or serverless environments.
+   */
+  async resetPersistence(): Promise<void> {
+    workerStoreConfigured = false;
+    workerStore = InMemoryWorkerStore.create();
+    storeInstanceCache.clear();
+    Logger.info('Worker persistence configuration reset');
+  },
 });
 
 // Graceful shutdown handled by WorkerShutdown