@zintrust/workers 0.1.28 → 0.1.30

package/src/http/WorkerController.ts

@@ -4,10 +4,9 @@
  * HTTP handlers for worker management API
  */
 
-import { Logger, getValidatedBody, type IRequest, type IResponse } from '@zintrust/core';
+import { Env, Logger, getValidatedBody, type IRequest, type IResponse } from '@zintrust/core';
 import type { Job } from 'bullmq';
 import { CanaryController } from '../CanaryController';
-import { getWorkers } from '../dashboard/workers-api';
 import { HealthMonitor } from '../HealthMonitor';
 import { getParam } from '../helper';
 import { SLAMonitor } from '../index';
@@ -19,6 +18,7 @@ import { WorkerRegistry } from '../WorkerRegistry';
 import { WorkerShutdown } from '../WorkerShutdown';
 import { WorkerVersioning } from '../WorkerVersioning';
 import type { InfrastructureConfig } from './middleware/InfrastructureValidator';
+import { WorkerMonitoringService } from './WorkerMonitoringService';
 
 /**
  * Helper to get request body
@@ -62,13 +62,13 @@ async function create(req: IRequest, res: IResponse): Promise<void> {
 
     const rawProcessor = body.processor;
     let processor: (job: Job) => Promise<unknown>;
-    let processorPath: string | undefined;
+    let processorSpec: string | undefined;
 
     if (typeof rawProcessor === 'string') {
-      processorPath = rawProcessor;
-      const resolved = await WorkerFactory.resolveProcessorPath(rawProcessor);
+      processorSpec = rawProcessor;
+      const resolved = await WorkerFactory.resolveProcessorSpec(rawProcessor);
       if (!resolved) {
-        res.setStatus(400).json({ error: 'Processor path could not be resolved' });
+        res.setStatus(400).json({ error: 'Processor spec could not be resolved' });
         return;
       }
       processor = resolved;
@@ -84,7 +84,7 @@ async function create(req: IRequest, res: IResponse): Promise<void> {
     const config = {
       ...(body as WorkerFactoryConfig),
       processor,
-      processorPath,
+      processorSpec,
     };
 
     await WorkerFactory.create(config);
@@ -114,6 +114,8 @@ async function start(req: IRequest, res: IResponse): Promise<void> {
       return;
     }
     const persistenceOverride = resolvePersistenceOverride(req);
+    const isActive = await ensureActiveWorker(name, persistenceOverride, res);
+    if (!isActive) return;
     const registered = WorkerRegistry.list().includes(name);
 
     if (!registered) {
@@ -138,6 +140,8 @@ async function stop(req: IRequest, res: IResponse): Promise<void> {
   try {
     const name = getParam(req, 'name');
     const persistenceOverride = resolvePersistenceOverride(req);
+    const isActive = await ensureActiveWorker(name, persistenceOverride, res);
+    if (!isActive) return;
     await WorkerFactory.stop(name, persistenceOverride);
     res.json({ ok: true, message: `Worker ${name} stopped` });
   } catch (error) {
@@ -155,6 +159,8 @@ async function restart(req: IRequest, res: IResponse): Promise<void> {
   try {
     const name = getParam(req, 'name');
     const persistenceOverride = resolvePersistenceOverride(req);
+    const isActive = await ensureActiveWorker(name, persistenceOverride, res);
+    if (!isActive) return;
     await WorkerFactory.restart(name, persistenceOverride);
     res.json({ ok: true, message: `Worker ${name} restarted` });
   } catch (error) {
@@ -190,6 +196,8 @@ async function setAutoStart(req: IRequest, res: IResponse): Promise<void> {
     }
 
     const persistenceOverride = resolvePersistenceOverride(req);
+    const isActive = await ensureActiveWorker(name, persistenceOverride, res);
+    if (!isActive) return;
 
     await WorkerFactory.setAutoStart(name, enabled, persistenceOverride);
 
@@ -209,6 +217,8 @@ async function pause(req: IRequest, res: IResponse): Promise<void> {
   try {
     const name = getParam(req, 'name');
     const persistenceOverride = resolvePersistenceOverride(req);
+    const isActive = await ensureActiveWorker(name, persistenceOverride, res);
+    if (!isActive) return;
     await WorkerFactory.pause(name, persistenceOverride);
     res.json({ ok: true, message: `Worker ${name} paused` });
   } catch (error) {
@@ -226,6 +236,8 @@ async function resume(req: IRequest, res: IResponse): Promise<void> {
   try {
     const name = getParam(req, 'name');
     const persistenceOverride = resolvePersistenceOverride(req);
+    const isActive = await ensureActiveWorker(name, persistenceOverride, res);
+    if (!isActive) return;
     await WorkerFactory.resume(name, persistenceOverride);
     res.json({ ok: true, message: `Worker ${name} resumed` });
   } catch (error) {
@@ -305,6 +317,32 @@ const resolvePersistenceOverride = (
   return undefined;
 };
 
+const ensureActiveWorker = async (
+  name: string | undefined,
+  persistenceOverride:
+    | { driver: 'memory' }
+    | { driver: 'redis'; redis: { env: true }; keyPrefix?: string }
+    | { driver: 'database'; connection?: string; table?: string }
+    | undefined,
+  res: IResponse
+): Promise<boolean> => {
+  if (!name) return false;
+
+  const instance = WorkerFactory.get(name);
+  if (instance?.config?.activeStatus === false) {
+    res.setStatus(410).json({ error: 'Worker is inactive', code: 'WORKER_INACTIVE' });
+    return false;
+  }
+
+  const persisted = await WorkerFactory.getPersisted(name, persistenceOverride);
+  if (persisted?.activeStatus === false) {
+    res.setStatus(410).json({ error: 'Worker is inactive', code: 'WORKER_INACTIVE' });
+    return false;
+  }
+
+  return true;
+};
+
 /**
  * Get a specific worker instance
  * @param req.params.name - Worker name
@@ -354,9 +392,15 @@ async function update(req: IRequest, res: IResponse): Promise<void> {
       return;
     }
 
-    // Validate and merge updates (excluding immutable fields)
+    // Remove immutable fields and prepare updates
     const { name: _name, driver: _driver, ...updateData } = reqData; // Remove immutable fields
 
+    const processorValid = await validateProcessorSpecIfNeeded(updateData);
+    if (!processorValid) {
+      res.setStatus(400).json({ error: 'Processor spec could not be resolved' });
+      return;
+    }
+
     // Note: driver is determined by persistence configuration, not stored in worker record
     const updatedRecord = {
       ...currentRecord,
@@ -367,39 +411,16 @@ async function update(req: IRequest, res: IResponse): Promise<void> {
 
     (updatedRecord.infrastructure as unknown as InfrastructureConfig).persistence.driver = driver;
 
-    // Update persistence store with the complete updated record
-    try {
-      // Persist merged record via WorkerFactory API
-      await WorkerFactory.update(
-        name,
-        updatedRecord as unknown as WorkerRecord,
-        persistenceOverride
-      );
-      Logger.info(`Worker ${name} persistence updated with fields:`, Object.keys(updateData));
-    } catch (persistError) {
-      Logger.warn(`Failed to persist some updates for ${name}`, persistError as Error);
-      // Continue with restart even if persistence update partially fails
-    }
+    await persistUpdatedRecord(name, updatedRecord, persistenceOverride, updateData);
 
-    // If worker is currently running, restart it to apply new configuration changes
-    // This ensures new concurrency, queue settings, and other config take effect
     const currentInstance = WorkerFactory.get(name);
-    let restartError: string | undefined;
-
-    if (currentInstance && currentInstance.status === 'running') {
-      try {
-        Logger.info(`Restarting worker ${name} to apply configuration changes`);
-        await WorkerFactory.restart(name, persistenceOverride);
-      } catch (error) {
-        restartError = (error as Error).message;
-        Logger.warn(`Failed to restart worker ${name} after update`, error as Error);
-        // Don't fail the update, but warn about restart failure
-      }
-    } else {
-      Logger.info(
-        `Worker ${name} is not running (status: ${currentInstance?.status || 'not found'}), skipping restart`
-      );
-    }
+    const restartError = await restartIfNeeded(
+      name,
+      currentInstance,
+      updatedRecord,
+      currentRecord,
+      persistenceOverride
+    );
 
     // Worker configuration updated in persistence and memory
     Logger.info(`Worker configuration updated: ${name}`, {
@@ -420,6 +441,64 @@ async function update(req: IRequest, res: IResponse): Promise<void> {
   }
 }
 
+// Helpers extracted from update() to reduce complexity
+async function validateProcessorSpecIfNeeded(
+  updateData: Record<string, unknown>
+): Promise<boolean> {
+  if (typeof updateData['processorSpec'] === 'string') {
+    const resolved = await WorkerFactory.resolveProcessorSpec(
+      updateData['processorSpec'] as string
+    );
+    return Boolean(resolved);
+  }
+  return true;
+}
+
+async function persistUpdatedRecord(
+  name: string,
+  updatedRecord: WorkerRecord | unknown,
+  persistenceOverride: ReturnType<typeof resolvePersistenceOverride> | undefined,
+  updateData: Record<string, unknown>
+): Promise<void> {
+  try {
+    await WorkerFactory.update(name, updatedRecord as unknown as WorkerRecord, persistenceOverride);
+    Logger.info(`Worker ${name} persistence updated with fields:`, Object.keys(updateData));
+  } catch (persistError) {
+    Logger.warn(`Failed to persist some updates for ${name}`, persistError as Error);
+    // Continue execution even if persistence update partially fails
+  }
+}
+
+async function restartIfNeeded(
+  name: string,
+  currentInstance: ReturnType<typeof WorkerFactory.get> | undefined,
+  updatedRecord: WorkerRecord,
+  currentRecord: WorkerRecord,
+  persistenceOverride: ReturnType<typeof resolvePersistenceOverride> | undefined
+): Promise<string | undefined> {
+  if (
+    !currentInstance ||
+    currentInstance.status !== 'running' ||
+    updatedRecord.activeStatus === false ||
+    currentRecord.activeStatus === false
+  ) {
+    Logger.info(
+      `Worker ${name} is not running (status: ${currentInstance?.status || 'not found'}), skipping restart`
+    );
+    return undefined;
+  }
+
+  try {
+    Logger.info(`Restarting worker ${name} to apply configuration changes`);
+    await WorkerFactory.restart(name, persistenceOverride);
+    return undefined;
+  } catch (err) {
+    const restartError = (err as Error).message;
+    Logger.warn(`Failed to restart worker ${name} after update`, err as Error);
+    return restartError;
+  }
+}
+
 /**
  * Get worker status
  * @param req.params.name - Worker name
@@ -590,7 +669,7 @@ async function getSlaStatus(req: IRequest, res: IResponse): Promise<void> {
   } catch (error) {
     Logger.error('WorkerController.getSlaStatus failed', error);
     if ((error as Error).message.includes('SLA config not found')) {
-      res.setStatus(404).json({ error: 'SLA config not found for worker' });
+      res.setStatus(400).json({ error: 'SLA config not found for worker' });
     } else {
       res.setStatus(500).json({ error: (error as Error).message });
     }
@@ -1257,65 +1336,63 @@ async function monitoringSummary(_req: IRequest, res: IResponse): Promise<void>
   }
 }
 
+const SSE_HEARTBEAT_INTERVAL = Env.SSE_HEARTBEAT_INTERVAL;
+
 /**
  * SSE endpoint: stream worker and monitoring events
  * GET /api/workers/events
  */
 const eventsStream = async (_req: IRequest, res: IResponse): Promise<void> => {
-  const raw = res.getRaw();
+  try {
+    const raw = res.getRaw();
+    raw.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+      'X-Accel-Buffering': 'no',
+    });
 
-  raw.writeHead(200, {
-    'Content-Type': 'text/event-stream',
-    'Cache-Control': 'no-cache, no-transform',
-    Connection: 'keep-alive',
-    'X-Accel-Buffering': 'no',
-  });
+    let closed = false;
 
-  let closed = false;
+    const send = (payload: unknown) => {
+      if (closed) return;
+      try {
+        const data = JSON.stringify(payload);
+        raw.write(`data: ${data}\n\n`);
+      } catch (err) {
+        Logger.error('WorkerController.eventsStream serialization failed', err);
+      }
+    };
 
-  const send = async (payload: unknown) => {
-    try {
-      const data = JSON.stringify(payload);
-      raw.write(`data: ${data}\n\n`);
-    } catch (err) {
-      Logger.error('WorkerController.eventsStream failed', err);
-      // ignore serialization errors
-    }
-  };
-
-  // Send initial hello
-  await send({ type: 'hello', ts: new Date().toISOString() });
-
-  // Periodic snapshot sender
-  const intervalMs = 5000;
-  const interval = setInterval(async () => {
-    try {
-      const monitoring = await HealthMonitor.getSummary();
-      // include full workers listing with metrics/pagination to allow clients to patch the UI
-      const workersPayload = await getWorkers({ page: 1, limit: 200 });
-      await send({
-        type: 'snapshot',
-        ts: new Date().toISOString(),
-        monitoring,
-        workers: workersPayload,
-      });
-    } catch (err) {
-      // send error event
-      await send({ type: 'error', ts: new Date().toISOString(), message: (err as Error).message });
+    // Send hello immediately
+    send({ type: 'hello', ts: new Date().toISOString() });
+
+    // Defined subscription callback
+    const onSnapshot = (data: unknown) => {
+      send(data);
+    };
+
+    // Subscribe to centralized service
+    WorkerMonitoringService.subscribe(onSnapshot);
+
+    // Heartbeat to keep connection alive
+    const hb = setInterval(() => {
+      if (!closed) raw.write(': ping\n\n');
+    }, SSE_HEARTBEAT_INTERVAL);
+
+    // Clean up when client disconnects
+    raw.on('close', () => {
+      closed = true;
+      clearInterval(hb);
+      WorkerMonitoringService.unsubscribe(onSnapshot);
+    });
+  } catch (error) {
+    Logger.error('WorkerController.eventsStream failed', error);
+    const raw = res.getRaw && typeof res.getRaw === 'function' ? res.getRaw() : null;
+    if (!raw?.headersSent) {
+      res.setStatus(500).json({ error: (error as Error).message });
     }
-  }, intervalMs);
-
-  // Heartbeat to keep connection alive
-  const hb = setInterval(() => {
-    if (!closed) raw.write(': ping\n\n');
-  }, 15000);
-
-  // Clean up when client disconnects
-  raw.on('close', () => {
-    closed = true;
-    clearInterval(interval);
-    clearInterval(hb);
-  });
+  }
 };
 
 /**

package/src/http/WorkerMonitoringService.ts

@@ -0,0 +1,77 @@
+import { Logger, NodeSingletons, workersConfig } from '@zintrust/core';
+import { HealthMonitor } from '../HealthMonitor';
+import { getWorkers } from '../dashboard/workers-api';
+
+type SnapshotData = {
+  type: string;
+  ts: string;
+  monitoring: unknown;
+  workers: unknown;
+};
+
+// Internal state
+const emitter = new NodeSingletons.EventEmitter();
+emitter.setMaxListeners(Infinity);
+let interval: NodeJS.Timeout | null = null;
+let subscribers = 0;
+const INTERVAL_MS = workersConfig?.intervalMs || 5000;
+
+const broadcastSnapshot = async (): Promise<void> => {
+  try {
+    if (subscribers <= 0) return;
+
+    const monitoring = await HealthMonitor.getSummary();
+    // Fetch full workers listing optimized for dashboard
+    const workersPayload = await getWorkers({ page: 1, limit: 200 });
+
+    const payload: SnapshotData = {
+      type: 'snapshot',
+      ts: new Date().toISOString(),
+      monitoring,
+      workers: workersPayload,
+    };
+
+    emitter.emit('snapshot', payload);
+  } catch (err) {
+    Logger.error('WorkerMonitoringService.broadcastSnapshot failed', err);
+    emitter.emit('error', err);
+  }
+};
+
+const startPolling = (): void => {
+  if (interval) return;
+
+  Logger.debug('Starting WorkerMonitoringService polling');
+  // Initial fetch
+  void broadcastSnapshot();
+
+  interval = setInterval(() => {
+    void broadcastSnapshot();
+  }, INTERVAL_MS);
+};
+
+const stopPolling = (): void => {
+  if (interval) {
+    Logger.debug('Stopping WorkerMonitoringService polling');
+    clearInterval(interval);
+    interval = null;
+  }
+};
+
+export const WorkerMonitoringService = Object.freeze({
+  subscribe(callback: (data: SnapshotData) => void): void {
+    emitter.on('snapshot', callback);
+    subscribers++;
+    if (subscribers === 1) {
+      startPolling();
+    }
+  },
+
+  unsubscribe(callback: (data: SnapshotData) => void): void {
+    emitter.off('snapshot', callback);
+    subscribers--;
+    if (subscribers <= 0) {
+      stopPolling();
+    }
+  },
+});

package/src/http/middleware/CustomValidation.ts

@@ -348,7 +348,7 @@ export const ValidationSchemas = {
     },
     driver: {
       type: 'string' as const,
-      allowedValues: ['db', 'redis', 'memory', ''],
+      allowedValues: ['db', 'database', 'redis', 'memory', ''],
       optional: true,
     },
     search: {

package/src/http/middleware/EditWorkerValidation.ts

@@ -14,7 +14,7 @@ import { withWorkerNameValidation } from './WorkerNameSanitizer';
 
 /**
  * Composite middleware for worker edit validation
- * Maps processorPath to processor for validation and validates all editable fields
+ * Maps processorSpec to processor for validation and validates all editable fields
  */
 export const withEditWorkerValidation = (handler: RouteHandler): RouteHandler => {
   return async (req: IRequest, res: IResponse): Promise<void> => {
@@ -22,12 +22,12 @@ export const withEditWorkerValidation = (handler: RouteHandler): RouteHandler =>
       const data = req.data();
       const currentBody = req.getBody() as Record<string, unknown>;
 
-      // Map processorPath to processor for validation if processorPath exists
+      // Map processorSpec/processorSpec to processor for validation if provided
       let mappedBody = { ...currentBody };
-      if (data['processorPath'] && !data['processor']) {
+      if (data['processorSpec'] && !data['processor']) {
         mappedBody = {
           ...mappedBody,
-          processor: data['processorPath'], // Map for validation
+          processor: data['processorSpec'],
         };
       }
 
@@ -39,8 +39,8 @@ export const withEditWorkerValidation = (handler: RouteHandler): RouteHandler =>
         [
           'name',
           'queueName',
-          'processor', // Validated field (mapped from processorPath)
-          'processorPath', // Original field
+          'processor', // Validated field (mapped from processorSpec)
+          'processorSpec',
           'version',
           'options', // Skip strict validation for editing
           'infrastructure',
@@ -49,6 +49,7 @@ export const withEditWorkerValidation = (handler: RouteHandler): RouteHandler =>
           'concurrency', // Original field
           'region',
           'autoStart',
+          'activeStatus',
           'status',
         ],
         withProcessorPathValidation(