@zintrust/workers 0.1.28 → 0.1.30

package/dist/WorkerFactory.js

@@ -3,7 +3,7 @@
  * Central factory for creating workers with all advanced features
  * Sealed namespace for immutability
  */
-import { appConfig, createRedisConnection, databaseConfig, Env, ErrorFactory, getBullMQSafeQueueName, Logger, NodeSingletons, queueConfig, registerDatabasesFromRuntimeConfig, useEnsureDbConnected, workersConfig, } from '@zintrust/core';
+import { appConfig, createRedisConnection, databaseConfig, Env, ErrorFactory, getBullMQSafeQueueName, Logger, NodeSingletons, queueConfig, registerDatabasesFromRuntimeConfig, useEnsureDbConnected, workersConfig, ZintrustLang, } from '@zintrust/core';
 import { Worker } from 'bullmq';
 import { AutoScaler } from './AutoScaler';
 import { CanaryController } from './CanaryController';
@@ -71,6 +71,9 @@ let workerStoreConfig = null;
 const processorRegistry = new Map();
 const processorPathRegistry = new Map();
 const processorResolvers = [];
+const processorSpecRegistry = new Map();
+const processorCache = new Map();
+let processorCacheSize = 0;
 const buildPersistenceBootstrapConfig = () => {
     const driver = Env.get('WORKER_PERSISTENCE_DRIVER', 'memory');
     const config = {
@@ -112,10 +115,98 @@ const registerProcessorPaths = (paths) => {
 const registerProcessorResolver = (resolver) => {
     processorResolvers.push(resolver);
 };
+const registerProcessorSpec = (spec, processor) => {
+    if (!spec || typeof processor !== 'function')
+        return;
+    processorSpecRegistry.set(normalizeProcessorSpec(spec), processor);
+};
 const decodeProcessorPathEntities = (value) => value
     .replaceAll(///gi, '/')
     .replaceAll('/', '/')
     .replaceAll(///gi, '/');
+const isUrlSpec = (spec) => {
+    if (spec.startsWith('url:'))
+        return true;
+    return spec.includes('://');
+};
+const normalizeProcessorSpec = (spec) => spec.startsWith('url:') ? spec.slice(4) : spec;
+const parseCacheControl = (value) => {
+    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 = () => workersConfig.processorSpec;
+const computeSha256 = async (value) => {
+    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) => {
+    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) => {
+    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) => {
+    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, entry, maxSize) => {
+    const existing = processorCache.get(key);
+    if (existing) {
+        processorCacheSize -= existing.size;
+    }
+    processorCache.set(key, entry);
+    processorCacheSize += entry.size;
+    evictCacheIfNeeded(maxSize);
+};
+const isAllowedRemoteHost = (host) => {
+    const allowlist = getProcessorSpecConfig().remoteAllowlist.map((value) => value.toLowerCase());
+    return allowlist.includes(host.toLowerCase());
+};
 const waitForWorkerConnection = async (worker, name, _queueName, timeoutMs) => {
     const startTime = Date.now();
     const checkInterval = 100; // 100ms between checks
@@ -174,6 +265,185 @@ const sanitizeProcessorPath = (value) => {
     const relativePath = base.startsWith('.') ? base : `./${base}`;
     return isAbsolutePath ? base : path.resolve(process.cwd(), relativePath);
 };
+const stripProcessorExtension = (value) => value.replace(/\.(ts|js)$/i, '');
+const normalizeModulePath = (value) => value.replaceAll('\\', '/');
+const buildProcessorModuleCandidates = (modulePath, resolvedPath) => {
+    const candidates = [];
+    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, source) => {
+    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;
+};
+const extractZinTrustProcessor = (mod, source) => {
+    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;
+};
+const readResponseBody = async (response, maxSize) => {
+    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, cacheControl) => Math.min(config.cacheMaxTtlSeconds, cacheControl.maxAge ?? config.cacheDefaultTtlSeconds);
+const refreshCachedProcessor = (existing, config, cacheControl) => {
+    const ttl = computeCacheTtlSeconds(config, cacheControl);
+    const now = Date.now();
+    existing.expiresAt = now + ttl * 1000;
+    existing.lastAccess = now;
+    return existing.processor;
+};
+const cacheProcessorFromResponse = async (params) => {
+    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, 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) => new Promise((resolve) => {
+    globalThis.setTimeout(resolve, ms);
+});
+const fetchProcessorAttempt = async (params) => {
+    const { normalized, config, cacheKey, existing, attempt, maxAttempts } = params;
+    const controller = new AbortController();
+    const timeoutId = globalThis.setTimeout(() => controller.abort(), config.fetchTimeoutMs);
+    try {
+        const headers = {};
+        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) => {
+    const normalized = normalizeProcessorSpec(spec);
+    let parsed;
+    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) => {
+    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) => {
     const trimmed = modulePath.trim();
     if (!trimmed)
@@ -181,20 +451,35 @@ const resolveProcessorFromPath = async (modulePath) => {
     const resolved = sanitizeProcessorPath(trimmed);
     if (!resolved)
         return undefined;
+    const importProcessorFromCandidates = async (candidates) => {
+        if (candidates.length === 0)
+            return undefined;
+        const [candidatePath, ...rest] = candidates;
+        try {
+            const mod = await import(candidatePath);
+            const candidate = pickProcessorFromModule(mod, candidatePath);
+            if (candidate)
+                return candidate;
+        }
+        catch (candidateError) {
+            Logger.debug(`Processor module candidate import failed: ${candidatePath}`, candidateError);
+        }
+        return importProcessorFromCandidates(rest);
+    };
     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)})`);
-        }
-        return typeof candidate === 'function'
-            ? candidate
-            : undefined;
+        const candidate = pickProcessorFromModule(mod, 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 (name) => {
     const direct = processorRegistry.get(name);
@@ -203,7 +488,7 @@ const resolveProcessor = async (name) => {
     const pathHint = processorPathRegistry.get(name);
     if (pathHint) {
         try {
-            const resolved = await resolveProcessorFromPath(pathHint);
+            const resolved = await resolveProcessorSpec(pathHint);
             if (resolved)
                 return resolved;
         }
@@ -494,8 +779,12 @@ 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', ''),
     };
 };
@@ -503,7 +792,7 @@ const resolveRedisConfigFromEnv = (config, context) => {
     const fallback = resolveRedisFallbacks();
     const host = requireRedisHost(resolveEnvString(config.host ?? 'REDIS_HOST', fallback.host), 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 {
         host,
@@ -716,8 +1005,8 @@ const ensureWorkerStoreConfigured = async () => {
 };
 const buildWorkerRecord = (config, status) => {
     const now = new Date();
-    const decodedProcessorPath = config.processorPath
-        ? decodeProcessorPathEntities(config.processorPath)
+    const normalizedProcessorSpec = config.processorSpec
+        ? normalizeProcessorSpec(config.processorSpec)
         : null;
     return {
         name: config.name,
@@ -727,7 +1016,8 @@ const buildWorkerRecord = (config, status) => {
         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,
@@ -994,6 +1284,7 @@ const registerWorkerInstance = (params) => {
     WorkerRegistry.register({
         name: config.name,
         config: {},
+        activeStatus: config.activeStatus ?? true,
         version: workerVersion,
         region: config.datacenter?.primaryRegion,
         queues: [queueName],
@@ -1007,6 +1298,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,
@@ -1064,7 +1356,9 @@ export const WorkerFactory = Object.freeze({
     registerProcessors,
     registerProcessorPaths,
     registerProcessorResolver,
+    registerProcessorSpec,
     resolveProcessorPath,
+    resolveProcessorSpec,
     /**
      * Create new worker with full setup
      */
@@ -1134,10 +1428,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] === true),
-            });
             return worker;
         }
         catch (error) {
@@ -1190,12 +1480,15 @@ export const WorkerFactory = Object.freeze({
     /**
      * Stop worker
      */
-    async stop(name, persistenceOverride) {
+    async stop(name, persistenceOverride, options) {
+        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;
         }
         // Execute beforeStop hooks
@@ -1230,15 +1523,17 @@ export const WorkerFactory = Object.freeze({
         instance.status = WorkerCreationStatus.STOPPED;
         // 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);
+        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);
+            }
         }
         await WorkerRegistry.stop(name);
         // Execute afterStop hooks
@@ -1327,6 +1622,35 @@ export const WorkerFactory = Object.freeze({
         }
         await WorkerFactory.startFromPersisted(name, persistenceOverride);
     },
+    /**
+     * Update active status for a worker
+     */
+    async setWorkerActiveStatus(name, activeStatus, persistenceOverride) {
+        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, persistenceOverride) {
+        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.
      */
@@ -1355,6 +1679,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 ?? cfg.infrastructure,
                 features: merged.features ?? cfg.features,
                 datacenter: merged.datacenter ?? cfg.datacenter,
@@ -1371,6 +1697,13 @@ export const WorkerFactory = Object.freeze({
         if (!instance) {
             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);
         instance.status = WorkerCreationStatus.RUNNING;
@@ -1392,12 +1725,15 @@ export const WorkerFactory = Object.freeze({
         return records.map((record) => record.name);
     },
     async listPersistedRecords(persistenceOverride, options) {
+        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);
     },
     /**
      * Start a worker from persisted storage when it is not registered.
@@ -1407,24 +1743,29 @@ export const WorkerFactory = Object.freeze({
         if (!record) {
             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);
             }
         }
         if (!processor) {
-            throw ErrorFactory.createConfigError(`Worker "${name}" processor is not registered or resolvable. Register the processor at startup or persist a processorPath.`);
+            throw ErrorFactory.createConfigError(`Worker "${name}" processor is not registered or resolvable. Register the processor at startup or persist a processorSpec.`);
         }
         await WorkerFactory.create({
             name: record.name,
             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 },
             infrastructure: record.infrastructure,
@@ -1506,8 +1847,37 @@ export const WorkerFactory = Object.freeze({
      */
     async shutdown() {
         Logger.info('WorkerFactory shutting down...');
-        const workerNames = Array.from(workers.keys());
-        await Promise.all(workerNames.map(async (name) => WorkerFactory.stop(name)));
+        const workerEntries = Array.from(workers.entries());
+        const workerNames = workerEntries.map(([name]) => 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();
+        // 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();
         await WorkerMetrics.shutdown();
@@ -1527,5 +1897,15 @@ export const WorkerFactory = Object.freeze({
         workers.clear();
         Logger.info('WorkerFactory shutdown complete');
     },
+    /**
+     * Reset persistence connection state.
+     * Useful when connections become stale in long-running processes or serverless environments.
+     */
+    async resetPersistence() {
+        workerStoreConfigured = false;
+        workerStore = InMemoryWorkerStore.create();
+        storeInstanceCache.clear();
+        Logger.info('Worker persistence configuration reset');
+    },
 });
 // Graceful shutdown handled by WorkerShutdown

package/dist/WorkerInit.js

@@ -115,7 +115,7 @@ async function initialize(options = {}) {
 async function autoStartPersistedWorkers() {
     // Check if auto-start is enabled globally via environment variable
     Logger.debug('Auto-start check', {
-        envAutoStart: process.env['WORKER_AUTO_START'],
+        envAutoStart: Env.getBool('WORKER_AUTO_START', false),
         configAutoStart: workersConfig.defaultWorker?.autoStart,
     });
     if (workersConfig.defaultWorker?.autoStart !== true) {
@@ -129,6 +129,9 @@ async function autoStartPersistedWorkers() {
             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;
@@ -153,7 +156,8 @@ async function autoStartPersistedWorkers() {
                 return { name: record.name, started: true, skipped: false };
             }
             catch (error) {
-                Logger.warn(`Auto-start failed for worker ${record.name}`, 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 };
             }
         }));
@@ -166,7 +170,8 @@ async function autoStartPersistedWorkers() {
         });
     }
     catch (error) {
-        Logger.warn('Auto-start persisted workers failed', error);
+        const message = error instanceof Error ? error.message : String(error);
+        Logger.warn(`Auto-start persisted workers failed: ${message}`);
     }
 }
 /**