@zintrust/workers 0.1.27

package/dist/PriorityQueue.js

@@ -0,0 +1,244 @@
+/**
+ * Priority Queue Manager
+ * BullMQ priority levels with datacenter affinity
+ * Sealed namespace for immutability
+ */
+import { ErrorFactory, Logger } from '@zintrust/core';
+import { BullMQRedisQueue } from '@zintrust/queue-redis';
+// Priority mappings
+const PRIORITY_VALUES = {
+    critical: 10,
+    high: 5,
+    normal: 1,
+    low: 0,
+};
+/**
+ * Helper: Get or create queue via shared driver
+ */
+const getQueue = (queueName) => {
+    return BullMQRedisQueue.getQueue(queueName);
+};
+/**
+ * Helper: Build job options with priority
+ */
+const buildJobOptions = (options) => {
+    const jobOptions = {
+        priority: PRIORITY_VALUES[options.priority],
+    };
+    if (options.delay !== undefined) {
+        jobOptions['delay'] = options.delay;
+    }
+    if (options.attempts !== undefined) {
+        jobOptions['attempts'] = options.attempts;
+    }
+    if (options.backoff) {
+        jobOptions['backoff'] = options.backoff;
+    }
+    if (options.removeOnComplete !== undefined) {
+        jobOptions['removeOnComplete'] = options.removeOnComplete;
+    }
+    if (options.removeOnFail !== undefined) {
+        jobOptions['removeOnFail'] = options.removeOnFail;
+    }
+    // Store datacenter affinity in job data (workers can read this)
+    if (options.datacenter) {
+        jobOptions['datacenter'] = options.datacenter;
+    }
+    return jobOptions;
+};
+/**
+ * Helper: Match datacenter affinity
+ */
+const matchesDatacenterAffinity = (jobDatacenter, workerRegion) => {
+    if (!jobDatacenter) {
+        return true; // No affinity, can be processed anywhere
+    }
+    // Check preferred datacenters first
+    if (jobDatacenter.preferred.includes(workerRegion)) {
+        return true;
+    }
+    // Check fallback datacenters
+    if (jobDatacenter.fallback.includes(workerRegion)) {
+        return true;
+    }
+    return false;
+};
+/**
+ * Priority Queue Manager - Sealed namespace
+ */
+export const PriorityQueue = Object.freeze({
+    /**
+     * Initialize with Redis configuration
+     */
+    initialize(_config) {
+        Logger.debug('PriorityQueue.initialize() called - auto-initialized via BullMQRedisQueue');
+    },
+    /**
+     * Add a job to the queue with priority
+     */
+    async addJob(queueName, jobName, data, options) {
+        const queue = getQueue(queueName);
+        const jobOptions = buildJobOptions(options);
+        try {
+            const job = await queue.add(jobName, data, jobOptions);
+            Logger.debug(`Added job "${jobName}" to queue "${queueName}"`, {
+                jobId: job.id,
+                priority: options.priority,
+                datacenter: options.datacenter,
+            });
+            if (job.id === undefined) {
+                throw ErrorFactory.createWorkerError(`Failed to add job "${jobName}" to queue "${queueName}": missing job id`);
+            }
+            return job.id;
+        }
+        catch (error) {
+            Logger.error(`Failed to add job "${jobName}" to queue "${queueName}"`, error);
+            throw error;
+        }
+    },
+    /**
+     * Add multiple jobs in bulk
+     */
+    async addBulk(queueName, jobs) {
+        const queue = getQueue(queueName);
+        try {
+            const bulkJobs = jobs.map((job) => ({
+                name: job.name,
+                data: job.data,
+                opts: buildJobOptions(job.options),
+            }));
+            const addedJobs = await queue.addBulk(bulkJobs);
+            Logger.info(`Added ${addedJobs.length} jobs to queue "${queueName}"`);
+            return addedJobs.map((job) => {
+                if (job.id === undefined) {
+                    throw ErrorFactory.createWorkerError(`Failed to add job to queue "${queueName}": missing job id`);
+                }
+                return job.id;
+            });
+        }
+        catch (error) {
+            Logger.error(`Failed to add bulk jobs to queue "${queueName}"`, error);
+            throw error;
+        }
+    },
+    /**
+     * Get job by ID
+     */
+    async getJob(queueName, jobId) {
+        const queue = getQueue(queueName);
+        return queue.getJob(jobId);
+    },
+    /**
+     * Remove a job
+     */
+    async removeJob(queueName, jobId) {
+        const queue = getQueue(queueName);
+        const job = await queue.getJob(jobId);
+        if (job) {
+            await job.remove();
+            Logger.debug(`Removed job ${jobId} from queue "${queueName}"`);
+        }
+    },
+    /**
+     * Pause a queue
+     */
+    async pause(queueName) {
+        const queue = getQueue(queueName);
+        await queue.pause();
+        Logger.info(`Paused queue "${queueName}"`);
+    },
+    /**
+     * Resume a queue
+     */
+    async resume(queueName) {
+        const queue = getQueue(queueName);
+        await queue.resume();
+        Logger.info(`Resumed queue "${queueName}"`);
+    },
+    /**
+     * Get queue information
+     */
+    async getQueueInfo(queueName) {
+        const queue = getQueue(queueName);
+        const isPaused = await queue.isPaused();
+        const jobCounts = await queue.getJobCounts();
+        return {
+            name: queueName,
+            isPaused,
+            jobCounts: {
+                active: jobCounts['active'] || 0,
+                waiting: jobCounts['waiting'] || 0,
+                completed: jobCounts['completed'] || 0,
+                failed: jobCounts['failed'] || 0,
+                delayed: jobCounts['delayed'] || 0,
+                paused: jobCounts['paused'] || 0,
+            },
+        };
+    },
+    /**
+     * Get all queue names
+     */
+    getQueueNames() {
+        return BullMQRedisQueue.getQueueNames();
+    },
+    /**
+     * Drain queue (remove all jobs)
+     */
+    async drain(queueName, delayed = false) {
+        const queue = getQueue(queueName);
+        await queue.drain(delayed);
+        Logger.info(`Drained queue "${queueName}"`, { delayed });
+    },
+    /**
+     * Clean old jobs from queue
+     */
+    async clean(queueName, grace, limit, type = 'completed') {
+        const queue = getQueue(queueName);
+        const jobs = await queue.clean(grace, limit, type);
+        Logger.info(`Cleaned ${jobs.length} ${type} jobs from queue "${queueName}"`);
+        return jobs;
+    },
+    /**
+     * Obliterate queue (remove all data including queue itself)
+     */
+    async obliterate(queueName, force = false) {
+        const queue = getQueue(queueName);
+        await queue.obliterate({ force });
+        await BullMQRedisQueue.closeQueue(queueName);
+        Logger.warn(`Obliterated queue "${queueName}"`);
+    },
+    /**
+     * Get priority value for level
+     */
+    getPriorityValue(level) {
+        return PRIORITY_VALUES[level];
+    },
+    /**
+     * Check if job matches datacenter affinity
+     */
+    matchesDatacenter(jobDatacenter, workerRegion) {
+        return matchesDatacenterAffinity(jobDatacenter, workerRegion);
+    },
+    /**
+     * Get queue instance (internal use)
+     */
+    getQueueInstance(queueName) {
+        return getQueue(queueName);
+    },
+    /**
+     * Close a queue
+     */
+    async closeQueue(queueName) {
+        await BullMQRedisQueue.closeQueue(queueName);
+        Logger.info(`Closed queue "${queueName}"`);
+    },
+    /**
+     * Shutdown and close all queues
+     */
+    async shutdown() {
+        Logger.info('PriorityQueue shutting down via BullMQRedisQueue...');
+        await BullMQRedisQueue.shutdown();
+        Logger.info('PriorityQueue shutdown complete');
+    },
+});
+// Graceful shutdown handled by WorkerShutdown

package/dist/ResourceMonitor.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Resource Monitor
+ * Real-time resource tracking with cost calculation
+ * Sealed namespace for immutability
+ */
+export type ResourceSnapshot = {
+    timestamp: Date;
+    cpu: {
+        usage: number;
+        loadAverage: number[];
+        cores: number;
+    };
+    memory: {
+        total: number;
+        used: number;
+        free: number;
+        usage: number;
+    };
+    disk: {
+        read: number;
+        write: number;
+    };
+    network: {
+        received: number;
+        transmitted: number;
+    };
+    process: {
+        pid: number;
+        uptime: number;
+        memoryUsage: NodeJS.MemoryUsage;
+        cpuUsage: NodeJS.CpuUsage;
+    };
+};
+export type WorkerResourceUsage = {
+    cpu: number;
+    memory: {
+        number: number;
+        percent: number;
+        used: number;
+        free: number;
+    };
+    cost: {
+        hourly: number;
+        daily: number;
+    };
+    workerName: string;
+    resourceSnapshot: ResourceSnapshot;
+    estimatedCost: {
+        perHour: number;
+        perDay: number;
+        perMonth: number;
+    };
+    efficiency: {
+        cpuEfficiency: number;
+        memoryEfficiency: number;
+        overallScore: number;
+    };
+};
+export type CostCalculationConfig = {
+    computeCostPerCoreHour: number;
+    memoryCostPerGBHour: number;
+    networkCostPerGB: number;
+    diskCostPerGB: number;
+    spotInstanceDiscount: number;
+};
+export type ResourceAlert = {
+    timestamp: Date;
+    workerName: string;
+    alertType: 'cpu-high' | 'memory-high' | 'disk-high' | 'cost-high';
+    severity: 'warning' | 'critical';
+    message: string;
+    currentValue: number;
+    threshold: number;
+    recommendation?: string;
+};
+export type ResourceTrend = {
+    workerName: string;
+    metric: 'cpu' | 'memory' | 'disk' | 'network' | 'cost';
+    period: 'hour' | 'day' | 'week';
+    trend: 'increasing' | 'decreasing' | 'stable';
+    changePercentage: number;
+    predictions: {
+        nextHour: number;
+        nextDay: number;
+        nextWeek: number;
+    };
+};
+/**
+ * Resource Monitor - Sealed namespace
+ */
+export declare const ResourceMonitor: Readonly<{
+    /**
+     * Initialize resource monitor
+     */
+    initialize(config?: Partial<CostCalculationConfig>): void;
+    /**
+     * Check whether monitoring is running
+     */
+    isRunning(): boolean;
+    /**
+     * Start monitoring
+     */
+    start(intervalSeconds?: number): void;
+    /**
+     * Stop monitoring
+     */
+    stop(): void;
+    /**
+     * Get current resource usage
+     */
+    getCurrentUsage(workerName: string, useSpotDiscount?: boolean): WorkerResourceUsage;
+    /**
+     * Get resource history
+     */
+    getHistory(workerName: string, limit?: number): ReadonlyArray<ResourceSnapshot>;
+    /**
+     * Get alerts
+     */
+    getAlerts(workerName: string, limit?: number): ReadonlyArray<ResourceAlert>;
+    /**
+     * Get trend analysis
+     */
+    getTrend(workerName: string, metric: ResourceTrend["metric"], period: ResourceTrend["period"]): ResourceTrend | null;
+    /**
+     * Get all trends
+     */
+    getAllTrends(workerName: string, period: ResourceTrend["period"]): Record<ResourceTrend["metric"], ResourceTrend | null>;
+    /**
+     * Update cost configuration
+     */
+    updateCostConfig(config: Partial<CostCalculationConfig>): void;
+    /**
+     * Get cost configuration
+     */
+    getCostConfig(): CostCalculationConfig;
+    /**
+     * Calculate projected cost
+     */
+    calculateProjectedCost(cpuUsagePercent: number, memoryGB: number, hoursPerDay: number, useSpotDiscount?: boolean): {
+        daily: number;
+        monthly: number;
+        yearly: number;
+    };
+    /**
+     * Get system information
+     */
+    getSystemInfo(): {
+        platform: string;
+        arch: string;
+        hostname: string;
+        cpus: number;
+        totalMemory: number;
+        freeMemory: number;
+        uptime: number;
+    };
+    /**
+     * Clear history for a worker
+     */
+    clearHistory(workerName: string): void;
+    /**
+     * Shutdown
+     */
+    shutdown(): void;
+}>;