@zintrust/workers 0.1.27

package/dist/WorkerRegistry.js

@@ -0,0 +1,319 @@
+/**
+ * Worker Registry
+ * Central registry for all background workers with lifecycle management
+ * Sealed namespace for immutability
+ */
+import { ErrorFactory, Logger } from '@zintrust/core';
+// Internal storage
+const workers = new Map();
+const registrations = new Map();
+/**
+ * Helper: Calculate uptime in seconds
+ */
+const calculateUptime = (startedAt) => {
+    if (!startedAt)
+        return null;
+    return Math.floor((Date.now() - startedAt.getTime()) / 1000);
+};
+/**
+ * Helper: Validate worker name
+ */
+const validateWorkerName = (name) => {
+    if (!name || typeof name !== 'string') {
+        throw ErrorFactory.createWorkerError('Worker name must be a non-empty string');
+    }
+    if (!/^[a-z0-9-]+$/.test(name)) {
+        throw ErrorFactory.createWorkerError('Worker name must contain only lowercase letters, numbers, and hyphens');
+    }
+};
+/**
+ * Worker Registry - Sealed namespace
+ */
+export const WorkerRegistry = Object.freeze({
+    /**
+     * Register a worker with the registry
+     */
+    register(options) {
+        validateWorkerName(options.name);
+        if (registrations.has(options.name)) {
+            Logger.warn(`Worker "${options.name}" is already registered. Skipping.`);
+            return;
+        }
+        registrations.set(options.name, options);
+        Logger.info(`Worker "${options.name}" registered successfully`);
+    },
+    /**
+     * Start a worker
+     */
+    async start(name, version) {
+        validateWorkerName(name);
+        const registration = registrations.get(name);
+        if (!registration) {
+            throw ErrorFactory.createWorkerError(`Worker "${name}" is not registered`);
+        }
+        if (workers.has(name)) {
+            const existing = workers.get(name);
+            if (existing?.metadata.status === 'running') {
+                Logger.warn(`Worker "${name}" is already running`);
+                return;
+            }
+        }
+        const versionSuffix = version === undefined ? '' : ` version ${version}`;
+        Logger.info(`Starting worker "${name}"${versionSuffix}...`);
+        try {
+            const instance = await registration.factory();
+            instance.metadata.status = 'starting';
+            instance.metadata.version = version ?? '1.0.0';
+            workers.set(name, instance);
+            instance.start();
+            instance.metadata.status = 'running';
+            instance.metadata.startedAt = new Date();
+            instance.metadata.stoppedAt = null;
+            Logger.info(`Worker "${name}" started successfully`);
+        }
+        catch (error) {
+            Logger.error(`Failed to start worker "${name}"`, error);
+            throw error;
+        }
+    },
+    /**
+     * Stop a worker
+     */
+    async stop(name) {
+        validateWorkerName(name);
+        const instance = workers.get(name);
+        if (!instance) {
+            Logger.warn(`Worker "${name}" is not running`);
+            return;
+        }
+        if (instance.metadata.status === 'stopped') {
+            Logger.warn(`Worker "${name}" is already stopped`);
+            return;
+        }
+        Logger.info(`Stopping worker "${name}"...`);
+        try {
+            instance.metadata.status = 'stopping';
+            await instance.stop();
+            instance.metadata.status = 'stopped';
+            instance.metadata.stoppedAt = new Date();
+            Logger.info(`Worker "${name}" stopped successfully`);
+        }
+        catch (error) {
+            Logger.error(`Failed to stop worker "${name}"`, error);
+            throw error;
+        }
+    },
+    /**
+     * Restart a worker (stop + start)
+     */
+    async restart(name) {
+        validateWorkerName(name);
+        const instance = workers.get(name);
+        if (instance) {
+            await WorkerRegistry.stop(name);
+            instance.metadata.restartCount += 1;
+        }
+        await WorkerRegistry.start(name);
+        Logger.info(`Worker "${name}" restarted successfully`);
+    },
+    /**
+     * Sleep a worker (pause processing but keep lock)
+     */
+    async sleep(name) {
+        validateWorkerName(name);
+        const instance = workers.get(name);
+        if (!instance) {
+            throw ErrorFactory.createWorkerError(`Worker "${name}" is not running`);
+        }
+        if (instance.metadata.status === 'sleeping') {
+            Logger.warn(`Worker "${name}" is already sleeping`);
+            return;
+        }
+        Logger.info(`Putting worker "${name}" to sleep...`);
+        try {
+            await instance.sleep();
+            instance.metadata.status = 'sleeping';
+            Logger.info(`Worker "${name}" is now sleeping`);
+        }
+        catch (error) {
+            Logger.error(`Failed to sleep worker "${name}"`, error);
+            throw error;
+        }
+    },
+    /**
+     * Wakeup a worker (resume from sleep)
+     */
+    async wakeup(name) {
+        validateWorkerName(name);
+        const instance = workers.get(name);
+        if (!instance) {
+            throw ErrorFactory.createWorkerError(`Worker "${name}" is not found`);
+        }
+        if (instance.metadata.status !== 'sleeping') {
+            Logger.warn(`Worker "${name}" is not sleeping (status: ${instance.metadata.status})`);
+            return;
+        }
+        Logger.info(`Waking up worker "${name}"...`);
+        try {
+            instance.wakeup();
+            instance.metadata.status = 'running';
+            Logger.info(`Worker "${name}" is now awake and running`);
+        }
+        catch (error) {
+            Logger.error(`Failed to wake up worker "${name}"`, error);
+            throw error;
+        }
+    },
+    /**
+     * Get worker status
+     */
+    status(name) {
+        validateWorkerName(name);
+        const instance = workers.get(name);
+        if (!instance) {
+            return null;
+        }
+        return { ...instance.metadata };
+    },
+    /**
+     * List all registered workers
+     */
+    list() {
+        return Array.from(registrations.keys());
+    },
+    /**
+     * List all running workers
+     */
+    listRunning() {
+        const running = [];
+        for (const [name, instance] of workers.entries()) {
+            if (instance.metadata.status === 'running') {
+                running.push(name);
+            }
+        }
+        return running;
+    },
+    /**
+     * Stop all running workers
+     */
+    async stopAll() {
+        Logger.info('Stopping all running workers...');
+        const running = WorkerRegistry.listRunning();
+        const tasks = running.map(async (name) => WorkerRegistry.stop(name));
+        try {
+            await Promise.all(tasks);
+            Logger.info(`Stopped ${running.length} workers successfully`);
+        }
+        catch (error) {
+            Logger.error('Failed to stop some workers', error);
+            throw error;
+        }
+    },
+    /**
+     * Get worker metrics
+     */
+    getMetrics(name) {
+        validateWorkerName(name);
+        const instance = workers.get(name);
+        if (!instance) {
+            return null;
+        }
+        return {
+            processedCount: instance.metadata.processedCount,
+            errorCount: instance.metadata.errorCount,
+            memoryUsage: instance.metadata.memoryUsage,
+            cpuUsage: instance.metadata.cpuUsage,
+        };
+    },
+    /**
+     * Get worker health status
+     */
+    getHealth(name) {
+        validateWorkerName(name);
+        const instance = workers.get(name);
+        if (!instance) {
+            return null;
+        }
+        return instance.getHealth();
+    },
+    /**
+     * Get registry snapshot
+     */
+    getSnapshot() {
+        const allWorkers = Array.from(workers.entries()).map(([name, instance]) => ({
+            name,
+            status: instance.metadata.status,
+            health: instance.getHealth(),
+            uptime: calculateUptime(instance.metadata.startedAt),
+            processedCount: instance.metadata.processedCount,
+            errorCount: instance.metadata.errorCount,
+        }));
+        const statusCounts = allWorkers.reduce((acc, w) => {
+            if (w.status === 'running')
+                acc.running++;
+            else if (w.status === 'stopped')
+                acc.stopped++;
+            else if (w.status === 'sleeping')
+                acc.sleeping++;
+            if (w.health === 'red')
+                acc.unhealthy++;
+            return acc;
+        }, { running: 0, stopped: 0, sleeping: 0, unhealthy: 0 });
+        return {
+            timestamp: new Date(),
+            totalWorkers: registrations.size,
+            runningWorkers: statusCounts.running,
+            stoppedWorkers: statusCounts.stopped,
+            sleepingWorkers: statusCounts.sleeping,
+            unhealthyWorkers: statusCounts.unhealthy,
+            workers: allWorkers,
+        };
+    },
+    /**
+     * Get worker topology (cluster view)
+     */
+    getTopology() {
+        const topology = {};
+        for (const [name, instance] of workers.entries()) {
+            const region = instance.metadata.region;
+            if (topology[region].count <= 0) {
+                topology[region] = { workers: [], count: 0 };
+            }
+            topology[region].workers.push(name);
+            topology[region].count++;
+        }
+        return topology;
+    },
+    /**
+     * Unregister a worker and clear its instance
+     */
+    unregister(name) {
+        validateWorkerName(name);
+        const instance = workers.get(name);
+        if (instance?.metadata.status === 'running') {
+            Logger.warn(`Worker "${name}" is still running during unregister`);
+        }
+        workers.delete(name);
+        registrations.delete(name);
+        Logger.info(`Worker "${name}" unregistered`);
+    },
+    /**
+     * Check if worker is registered
+     */
+    isRegistered(name) {
+        return registrations.has(name);
+    },
+    /**
+     * Check if worker is running
+     */
+    isRunning(name) {
+        const instance = workers.get(name);
+        return instance?.metadata.status === 'running';
+    },
+    /**
+     * Get worker instance (internal use)
+     */
+    getInstance(name) {
+        return workers.get(name) ?? null;
+    },
+});

package/dist/WorkerShutdown.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Worker Shutdown Coordinator
+ *
+ * Centralized graceful shutdown handling for the worker management system.
+ * Coordinates orderly shutdown of all worker modules and the WorkerFactory.
+ */
+export interface IShutdownOptions {
+    /**
+     * Timeout for graceful shutdown in milliseconds
+     */
+    timeout?: number;
+    /**
+     * Whether to force exit after timeout
+     */
+    forceExit?: boolean;
+    /**
+     * Signal that triggered shutdown (SIGTERM, SIGINT, etc.)
+     */
+    signal?: string;
+}
+interface IShutdownState {
+    isShuttingDown: boolean;
+    completedAt: Date | null;
+    startedAt: Date | null;
+    reason: string | null;
+}
+/**
+ * Perform graceful shutdown of all worker modules
+ */
+declare function shutdown(options?: IShutdownOptions): Promise<void>;
+/**
+ * Register process signal handlers for graceful shutdown
+ */
+declare function registerShutdownHandlers(): void;
+/**
+ * Check if system is currently shutting down
+ */
+declare function isShuttingDown(): boolean;
+/**
+ * Get current shutdown state
+ */
+declare function getShutdownState(): Readonly<IShutdownState>;
+export declare const WorkerShutdown: Readonly<{
+    /**
+     * Perform graceful shutdown of all worker modules
+     */
+    shutdown: typeof shutdown;
+    /**
+     * Register process signal handlers for graceful shutdown
+     */
+    registerShutdownHandlers: typeof registerShutdownHandlers;
+    /**
+     * Check if system is currently shutting down
+     */
+    isShuttingDown: typeof isShuttingDown;
+    /**
+     * Get current shutdown state
+     */
+    getShutdownState: typeof getShutdownState;
+}>;
+export {};

package/dist/WorkerShutdown.js

@@ -0,0 +1,159 @@
+/**
+ * Worker Shutdown Coordinator
+ *
+ * Centralized graceful shutdown handling for the worker management system.
+ * Coordinates orderly shutdown of all worker modules and the WorkerFactory.
+ */
+import { Logger } from '@zintrust/core';
+import { WorkerFactory } from './WorkerFactory';
+// ============================================================================
+// Implementation
+// ============================================================================
+const state = {
+    isShuttingDown: false,
+    completedAt: null,
+    startedAt: null,
+    reason: null,
+};
+let shutdownHandlersRegistered = false;
+/**
+ * Perform graceful shutdown of all worker modules
+ */
+async function shutdown(options = {}) {
+    const { timeout = 30000, forceExit = true, signal = 'unknown' } = options;
+    // Prevent concurrent shutdowns
+    if (state.isShuttingDown) {
+        Logger.warn('Shutdown already in progress, ignoring duplicate request');
+        return;
+    }
+    state.isShuttingDown = true;
+    state.startedAt = new Date();
+    state.reason = `Signal: ${signal}`;
+    Logger.info('🛑 Initiating graceful shutdown of worker management system', {
+        signal,
+        timeout,
+        forceExit,
+    });
+    // Setup timeout for forced shutdown
+    let timeoutHandle = null;
+    if (forceExit && timeout > 0) {
+        // eslint-disable-next-line no-restricted-syntax
+        timeoutHandle = setTimeout(() => {
+            Logger.error('❌ Graceful shutdown timeout exceeded, forcing exit', { timeout });
+            process.exit(1);
+        }, timeout);
+    }
+    try {
+        // Shutdown WorkerFactory - this will coordinate shutdown of all modules
+        await WorkerFactory.shutdown();
+        state.completedAt = new Date();
+        const duration = state.completedAt.getTime() - (state.startedAt?.getTime() ?? 0);
+        Logger.info('✅ Worker management system shutdown complete', {
+            duration: `${duration}ms`,
+            signal,
+        });
+        // Clear timeout if successful
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+        }
+    }
+    catch (error) {
+        Logger.error('❌ Error during worker management system shutdown', error);
+        throw error;
+    }
+}
+/**
+ * Register process signal handlers for graceful shutdown
+ */
+function registerShutdownHandlers() {
+    if (shutdownHandlersRegistered) {
+        Logger.debug('Shutdown handlers already registered, skipping');
+        return;
+    }
+    Logger.debug('Registering worker management system shutdown handlers');
+    // SIGTERM - graceful shutdown (Docker, systemd, etc.)
+    process.on('SIGTERM', async () => {
+        Logger.info('📨 Received SIGTERM signal');
+        try {
+            await shutdown({ signal: 'SIGTERM', timeout: 30000, forceExit: true });
+        }
+        catch (error) {
+            Logger.error('Error during SIGTERM shutdown', error);
+        }
+    });
+    // SIGINT - user interrupt (Ctrl+C) - REMOVED: handled by bootstrap.ts to prevent race condition
+    // process.on('SIGINT', async () => {
+    //   Logger.info('📨 Received SIGINT signal');
+    //   try {
+    //     await shutdown({ signal: 'SIGINT', timeout: 30000, forceExit: true });
+    //   } catch (error) {
+    //     Logger.error('Error during SIGINT shutdown', error);
+    //   }
+    // });
+    // SIGHUP - terminal closed
+    process.on('SIGHUP', async () => {
+        Logger.info('📨 Received SIGHUP signal');
+        try {
+            await shutdown({ signal: 'SIGHUP', timeout: 30000, forceExit: true });
+        }
+        catch (error) {
+            Logger.error('Error during SIGHUP shutdown', error);
+        }
+    });
+    // Handle uncaught errors during shutdown
+    process.on('uncaughtException', async (error) => {
+        Logger.error('💥 Uncaught exception during worker operations', error);
+        try {
+            await shutdown({ signal: 'uncaughtException', timeout: 10000, forceExit: true });
+        }
+        catch {
+            // Ignore errors during emergency shutdown
+        }
+        process.exit(1);
+    });
+    process.on('unhandledRejection', async (reason) => {
+        Logger.error('💥 Unhandled promise rejection during worker operations', reason);
+        try {
+            await shutdown({ signal: 'unhandledRejection', timeout: 10000, forceExit: true });
+        }
+        catch {
+            // Ignore errors during emergency shutdown
+        }
+        process.exit(1);
+    });
+    shutdownHandlersRegistered = true;
+    Logger.debug('Worker management system shutdown handlers registered');
+}
+/**
+ * Check if system is currently shutting down
+ */
+function isShuttingDown() {
+    return state.isShuttingDown;
+}
+/**
+ * Get current shutdown state
+ */
+function getShutdownState() {
+    return { ...state };
+}
+// ============================================================================
+// Public API (Sealed Namespace)
+// ============================================================================
+export const WorkerShutdown = Object.freeze({
+    /**
+     * Perform graceful shutdown of all worker modules
+     */
+    shutdown,
+    /**
+     * Register process signal handlers for graceful shutdown
+     */
+    registerShutdownHandlers,
+    /**
+     * Check if system is currently shutting down
+     */
+    isShuttingDown,
+    /**
+     * Get current shutdown state
+     */
+    getShutdownState,
+});

package/dist/WorkerVersioning.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Worker Versioning System
+ * Semantic versioning support for workers with backward compatibility
+ * Sealed namespace for immutability
+ */
+export type SemanticVersion = {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease?: string;
+    build?: string;
+};
+export type WorkerVersion = {
+    workerName: string;
+    version: SemanticVersion;
+    createdAt: Date;
+    deprecatedAt?: Date;
+    eolDate?: Date;
+    isActive: boolean;
+    isDeprecated: boolean;
+    migrationPath?: string;
+    changelog?: string;
+    breakingChanges?: string[];
+};
+export type VersionCompatibility = {
+    sourceVersion: SemanticVersion;
+    targetVersion: SemanticVersion;
+    compatible: boolean;
+    requiresMigration: boolean;
+    breakingChanges: string[];
+    recommendations: string[];
+};
+/**
+ * Worker Versioning - Sealed namespace
+ */
+export declare const WorkerVersioning: Readonly<{
+    /**
+     * Register a worker version
+     */
+    register(workerVersion: Omit<WorkerVersion, "createdAt" | "isActive" | "isDeprecated">): void;
+    /**
+     * Get worker version
+     */
+    getVersion(workerName: string, versionStr: string): WorkerVersion | null;
+    /**
+     * Get all versions for a worker
+     */
+    getVersions(workerName: string, includeDeprecated?: boolean): ReadonlyArray<WorkerVersion>;
+    /**
+     * Get latest version
+     */
+    getLatest(workerName: string): WorkerVersion | null;
+    /**
+     * Deprecate a version
+     */
+    deprecate(workerName: string, versionStr: string, migrationPath?: string, eolDate?: Date): void;
+    /**
+     * Deactivate a version (stop accepting new jobs)
+     */
+    deactivate(workerName: string, versionStr: string): void;
+    /**
+     * Activate a version
+     */
+    activate(workerName: string, versionStr: string): void;
+    /**
+     * Check compatibility between versions
+     */
+    checkCompatibility(workerName: string, sourceVersionStr: string, targetVersionStr: string): VersionCompatibility;
+    /**
+     * Set version alias
+     */
+    setAlias(workerName: string, alias: string, versionStr: string): void;
+    /**
+     * Get version by alias
+     */
+    resolveAlias(workerName: string, alias: string): string | null;
+    /**
+     * Parse version string
+     */
+    parse(versionStr: string): SemanticVersion;
+    /**
+     * Convert version to string
+     */
+    stringify(version: SemanticVersion): string;
+    /**
+     * Compare two versions
+     */
+    compare(v1Str: string, v2Str: string): number;
+    /**
+     * Get version summary
+     */
+    getSummary(workerName: string): {
+        totalVersions: number;
+        activeVersions: number;
+        deprecatedVersions: number;
+        latest: string | null;
+        stable: string | null;
+    };
+    /**
+     * Clear all versions for a worker
+     */
+    clear(workerName: string): void;
+    /**
+     * Shutdown
+     */
+    shutdown(): void;
+}>;