@zintrust/core 0.1.42 → 0.1.44

package/packages/workers/src/PluginManager.js

@@ -0,0 +1,392 @@
+/**
+ * Plugin Manager
+ * Extensible plugin system with lifecycle hooks
+ * Sealed namespace for immutability
+ */
+import { ErrorFactory, Logger } from '../../../src/index.js';
+// Internal state
+const plugins = new Map();
+const hookExecutionHistory = [];
+const MAX_HISTORY = 1000;
+/**
+ * Helper: Validate plugin metadata
+ */
+const validatePlugin = (plugin) => {
+    if (!plugin.metadata.name) {
+        throw ErrorFactory.createWorkerError('Plugin name is required');
+    }
+    if (!plugin.metadata.version) {
+        throw ErrorFactory.createWorkerError('Plugin version is required');
+    }
+    if (Object.keys(plugin.hooks).length === 0) {
+        throw ErrorFactory.createWorkerError('Plugin must implement at least one hook');
+    }
+};
+/**
+ * Helper: Check plugin dependencies
+ */
+const checkDependencies = (plugin) => {
+    if (!plugin.metadata.dependencies || plugin.metadata.dependencies.length === 0) {
+        return { satisfied: true, missing: [] };
+    }
+    const missing = [];
+    for (const depName of plugin.metadata.dependencies) {
+        const dep = plugins.get(depName);
+        if (dep?.enabled !== true) {
+            missing.push(depName);
+        }
+    }
+    return {
+        satisfied: missing.length === 0,
+        missing,
+    };
+};
+/**
+ * Helper: Get enabled plugins for a hook, sorted by priority
+ */
+const getEnabledPluginsForHook = (hook) => {
+    const enabledPlugins = [];
+    for (const registered of plugins.values()) {
+        if (registered.enabled && registered.plugin.hooks[hook]) {
+            enabledPlugins.push(registered);
+        }
+    }
+    // Sort by priority (lower number = higher priority)
+    return enabledPlugins.sort((a, b) => a.priority - b.priority);
+};
+/**
+ * Helper: Store execution result
+ */
+const storeExecutionResult = (result) => {
+    hookExecutionHistory.push(result);
+    // Keep only last MAX_HISTORY results
+    if (hookExecutionHistory.length > MAX_HISTORY) {
+        hookExecutionHistory.shift();
+    }
+};
+/**
+ * Plugin Manager - Sealed namespace
+ */
+export const PluginManager = Object.freeze({
+    /**
+     * Register a plugin
+     */
+    async register(plugin, priority = 100) {
+        validatePlugin(plugin);
+        const { name } = plugin.metadata;
+        if (plugins.has(name)) {
+            throw ErrorFactory.createWorkerError(`Plugin "${name}" is already registered`);
+        }
+        // Check dependencies
+        const depCheck = checkDependencies(plugin);
+        if (!depCheck.satisfied) {
+            throw ErrorFactory.createWorkerError(`Plugin "${name}" has unsatisfied dependencies: ${depCheck.missing.join(', ')}`);
+        }
+        const registered = {
+            plugin,
+            enabled: true,
+            registeredAt: new Date(),
+            priority,
+        };
+        plugins.set(name, registered);
+        // Call onEnable if provided
+        if (plugin.onEnable) {
+            try {
+                await plugin.onEnable();
+            }
+            catch (error) {
+                Logger.error(`Plugin "${name}" onEnable failed`, error);
+                plugins.delete(name);
+                throw error;
+            }
+        }
+        Logger.info(`Plugin registered: ${name}@${plugin.metadata.version}`, {
+            hooks: Object.keys(plugin.hooks),
+            priority,
+        });
+    },
+    /**
+     * Unregister a plugin
+     */
+    async unregister(pluginName) {
+        const registered = plugins.get(pluginName);
+        if (!registered) {
+            throw ErrorFactory.createNotFoundError(`Plugin "${pluginName}" not found`);
+        }
+        // Check if other plugins depend on this one
+        const dependents = [];
+        for (const [name, reg] of plugins.entries()) {
+            if (name !== pluginName && reg.enabled) {
+                const deps = reg.plugin.metadata.dependencies ?? [];
+                if (deps.includes(pluginName)) {
+                    dependents.push(name);
+                }
+            }
+        }
+        if (dependents.length > 0) {
+            throw ErrorFactory.createWorkerError(`Cannot unregister plugin "${pluginName}": required by ${dependents.join(', ')}`);
+        }
+        // Call onDisable if provided
+        if (registered.plugin.onDisable) {
+            try {
+                await registered.plugin.onDisable();
+            }
+            catch (error) {
+                Logger.error(`Plugin "${pluginName}" onDisable failed`, error);
+            }
+        }
+        plugins.delete(pluginName);
+        Logger.info(`Plugin unregistered: ${pluginName}`);
+    },
+    /**
+     * Enable a plugin
+     */
+    async enable(pluginName) {
+        const registered = plugins.get(pluginName);
+        if (!registered) {
+            throw ErrorFactory.createNotFoundError(`Plugin "${pluginName}" not found`);
+        }
+        if (registered.enabled) {
+            Logger.warn(`Plugin "${pluginName}" is already enabled`);
+            return;
+        }
+        // Check dependencies
+        const depCheck = checkDependencies(registered.plugin);
+        if (!depCheck.satisfied) {
+            throw ErrorFactory.createWorkerError(`Cannot enable plugin "${pluginName}": unsatisfied dependencies: ${depCheck.missing.join(', ')}`);
+        }
+        registered.enabled = true;
+        // Call onEnable if provided
+        if (registered.plugin.onEnable) {
+            try {
+                await registered.plugin.onEnable();
+            }
+            catch (error) {
+                Logger.error(`Plugin "${pluginName}" onEnable failed`, error);
+                registered.enabled = false;
+                throw error;
+            }
+        }
+        Logger.info(`Plugin enabled: ${pluginName}`);
+    },
+    /**
+     * Disable a plugin
+     */
+    async disable(pluginName) {
+        const registered = plugins.get(pluginName);
+        if (!registered) {
+            throw ErrorFactory.createNotFoundError(`Plugin "${pluginName}" not found`);
+        }
+        if (!registered.enabled) {
+            Logger.warn(`Plugin "${pluginName}" is already disabled`);
+            return;
+        }
+        // Check if other enabled plugins depend on this one
+        const dependents = [];
+        for (const [name, reg] of plugins.entries()) {
+            if (name !== pluginName && reg.enabled) {
+                const deps = reg.plugin.metadata.dependencies ?? [];
+                if (deps.includes(pluginName)) {
+                    dependents.push(name);
+                }
+            }
+        }
+        if (dependents.length > 0) {
+            throw ErrorFactory.createWorkerError(`Cannot disable plugin "${pluginName}": required by enabled plugins: ${dependents.join(', ')}`);
+        }
+        registered.enabled = false;
+        // Call onDisable if provided
+        if (registered.plugin.onDisable) {
+            try {
+                await registered.plugin.onDisable();
+            }
+            catch (error) {
+                Logger.error(`Plugin "${pluginName}" onDisable failed`, error);
+            }
+        }
+        Logger.info(`Plugin disabled: ${pluginName}`);
+    },
+    /**
+     * Execute hooks for a lifecycle event
+     */
+    async executeHook(hook, context) {
+        const startTime = Date.now();
+        const enabledPlugins = getEnabledPluginsForHook(hook);
+        const result = {
+            data: context.jobData,
+            hook,
+            executionTime: 0,
+            pluginsExecuted: 0,
+            errors: [],
+            context,
+            modified: false,
+            stopped: false,
+        };
+        const currentContext = { ...context };
+        let stopped = false;
+        const executeHandler = async (registered) => {
+            if (stopped)
+                return;
+            const { plugin } = registered;
+            const handler = plugin.hooks[hook];
+            if (!handler)
+                return;
+            try {
+                const hookResult = await handler(currentContext);
+                result.pluginsExecuted++;
+                if (hookResult !== undefined) {
+                    if (hookResult.modified === true) {
+                        result.modified = true;
+                    }
+                    if (hookResult.jobData !== undefined) {
+                        currentContext.jobData = hookResult.jobData;
+                        result.data = hookResult.jobData;
+                    }
+                    if (hookResult.stop === true) {
+                        result.stopped = true;
+                        stopped = true;
+                        Logger.warn(`Hook execution stopped by plugin: ${plugin.metadata.name}`, { hook });
+                    }
+                    if (hookResult.error instanceof Error) {
+                        result.errors.push({
+                            pluginName: plugin.metadata.name,
+                            error: hookResult.error,
+                        });
+                    }
+                }
+            }
+            catch (error) {
+                Logger.error(`Plugin "${plugin.metadata.name}" hook "${hook}" failed`, error);
+                result.errors.push({
+                    pluginName: plugin.metadata.name,
+                    error: error,
+                });
+                if (hook === 'beforeStart' || hook === 'beforeStop') {
+                    result.stopped = true;
+                    stopped = true;
+                }
+            }
+        };
+        let chain = Promise.resolve();
+        for (const registered of enabledPlugins) {
+            chain = chain.then(async () => executeHandler(registered));
+        }
+        await chain;
+        result.executionTime = Date.now() - startTime;
+        storeExecutionResult(result);
+        Logger.debug(`Hook executed: ${hook}`, {
+            pluginsExecuted: result.pluginsExecuted,
+            executionTime: result.executionTime,
+            errors: result.errors.length,
+        });
+        return result;
+    },
+    /**
+     * Get registered plugins
+     */
+    getPlugins() {
+        return Array.from(plugins.entries()).map(([name, registered]) => ({
+            name,
+            ...registered,
+        }));
+    },
+    /**
+     * Get plugin by name
+     */
+    getPlugin(pluginName) {
+        const registered = plugins.get(pluginName);
+        if (!registered)
+            return null;
+        return {
+            name: pluginName,
+            ...registered,
+        };
+    },
+    /**
+     * Check if plugin is registered
+     */
+    isRegistered(pluginName) {
+        return plugins.has(pluginName);
+    },
+    /**
+     * Check if plugin is enabled
+     */
+    isEnabled(pluginName) {
+        const registered = plugins.get(pluginName);
+        return registered ? registered.enabled : false;
+    },
+    /**
+     * Get hook execution history
+     */
+    getExecutionHistory(hook, limit = 100) {
+        let history = hookExecutionHistory;
+        if (hook) {
+            history = history.filter((result) => result.hook === hook);
+        }
+        return history.slice(-limit).map((result) => ({ ...result }));
+    },
+    /**
+     * Get plugin statistics
+     */
+    getStatistics() {
+        const stats = {
+            totalPlugins: plugins.size,
+            enabledPlugins: 0,
+            disabledPlugins: 0,
+            totalHookExecutions: hookExecutionHistory.length,
+            hookExecutionsByType: {},
+            averageExecutionTime: 0,
+            totalErrors: 0,
+        };
+        for (const registered of plugins.values()) {
+            if (registered.enabled) {
+                stats.enabledPlugins++;
+            }
+            else {
+                stats.disabledPlugins++;
+            }
+        }
+        let totalExecutionTime = 0;
+        for (const result of hookExecutionHistory) {
+            const hookType = result.hook;
+            stats.hookExecutionsByType[hookType] = (stats.hookExecutionsByType[hookType] || 0) + 1;
+            totalExecutionTime += result.executionTime;
+            stats.totalErrors += result.errors.length;
+        }
+        if (hookExecutionHistory.length > 0) {
+            stats.averageExecutionTime = totalExecutionTime / hookExecutionHistory.length;
+        }
+        return stats;
+    },
+    /**
+     * Clear execution history
+     */
+    clearHistory() {
+        hookExecutionHistory.length = 0;
+        Logger.info('Plugin execution history cleared');
+    },
+    /**
+     * Shutdown and disable all plugins
+     */
+    async shutdown() {
+        Logger.info('PluginManager shutting down...');
+        // Disable all plugins in reverse order of priority
+        const sortedPlugins = Array.from(plugins.entries()).sort(([, a], [, b]) => b.priority - a.priority);
+        const disableTasks = sortedPlugins.map(async ([name, registered]) => {
+            if (!registered.enabled || !registered.plugin.onDisable)
+                return;
+            try {
+                await registered.plugin.onDisable();
+                Logger.debug(`Plugin disabled: ${name}`);
+            }
+            catch (error) {
+                Logger.error(`Plugin "${name}" onDisable failed during shutdown`, error);
+            }
+        });
+        await Promise.allSettled(disableTasks);
+        plugins.clear();
+        hookExecutionHistory.length = 0;
+        Logger.info('PluginManager shutdown complete');
+    },
+});
+// Graceful shutdown handled by WorkerShutdown

package/packages/workers/src/PriorityQueue.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Priority Queue Manager
+ * BullMQ priority levels with datacenter affinity
+ * Sealed namespace for immutability
+ */
+import { type RedisConfig } from '../../../src/index.js';
+import type { Queue } from 'bullmq';
+export type PriorityLevel = 'critical' | 'high' | 'normal' | 'low';
+export type JobPriority = {
+    level: PriorityLevel;
+    value: number;
+};
+export type DatacenterAffinity = {
+    preferred: string[];
+    fallback: string[];
+};
+export type PriorityJobOptions = {
+    priority: PriorityLevel;
+    datacenter?: DatacenterAffinity;
+    delay?: number;
+    attempts?: number;
+    backoff?: {
+        type: 'exponential' | 'fixed';
+        delay: number;
+    };
+    removeOnComplete?: boolean | number;
+    removeOnFail?: boolean | number;
+};
+export type QueueInfo = {
+    name: string;
+    isPaused: boolean;
+    jobCounts: {
+        active: number;
+        waiting: number;
+        completed: number;
+        failed: number;
+        delayed: number;
+        paused: number;
+    };
+};
+/**
+ * Priority Queue Manager - Sealed namespace
+ */
+export declare const PriorityQueue: Readonly<{
+    /**
+     * Initialize with Redis configuration
+     */
+    initialize(_config: RedisConfig): void;
+    /**
+     * Add a job to the queue with priority
+     */
+    addJob<T = unknown>(queueName: string, jobName: string, data: T, options: PriorityJobOptions): Promise<string>;
+    /**
+     * Add multiple jobs in bulk
+     */
+    addBulk<T = unknown>(queueName: string, jobs: Array<{
+        name: string;
+        data: T;
+        options: PriorityJobOptions;
+    }>): Promise<string[]>;
+    /**
+     * Get job by ID
+     */
+    getJob(queueName: string, jobId: string): Promise<import("bullmq").Job<any, any, string> | undefined>;
+    /**
+     * Remove a job
+     */
+    removeJob(queueName: string, jobId: string): Promise<void>;
+    /**
+     * Pause a queue
+     */
+    pause(queueName: string): Promise<void>;
+    /**
+     * Resume a queue
+     */
+    resume(queueName: string): Promise<void>;
+    /**
+     * Get queue information
+     */
+    getQueueInfo(queueName: string): Promise<QueueInfo>;
+    /**
+     * Get all queue names
+     */
+    getQueueNames(): Promise<string[]>;
+    /**
+     * Drain queue (remove all jobs)
+     */
+    drain(queueName: string, delayed?: boolean): Promise<void>;
+    /**
+     * Clean old jobs from queue
+     */
+    clean(queueName: string, grace: number, limit: number, type?: "completed" | "failed" | "delayed" | "wait" | "active" | "paused"): Promise<string[]>;
+    /**
+     * Obliterate queue (remove all data including queue itself)
+     */
+    obliterate(queueName: string, force?: boolean): Promise<void>;
+    /**
+     * Get priority value for level
+     */
+    getPriorityValue(level: PriorityLevel): number;
+    /**
+     * Check if job matches datacenter affinity
+     */
+    matchesDatacenter(jobDatacenter: DatacenterAffinity | undefined, workerRegion: string): boolean;
+    /**
+     * Get queue instance (internal use)
+     */
+    getQueueInstance(queueName: string): Promise<Queue>;
+    /**
+     * Close a queue
+     */
+    closeQueue(queueName: string): Promise<void>;
+    /**
+     * Shutdown and close all queues
+     */
+    shutdown(): Promise<void>;
+}>;
+//# sourceMappingURL=PriorityQueue.d.ts.map

package/packages/workers/src/PriorityQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PriorityQueue.d.ts","sourceRoot":"","sources":["../../../../packages/workers/src/PriorityQueue.ts"],"names":[],"mappings":"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"}