@zintrust/core 0.4.26 → 0.4.28

package/packages/workers/src/PriorityQueue.js

@@ -0,0 +1,276 @@
+/**
+ * Priority Queue Manager
+ * BullMQ priority levels with datacenter affinity
+ * Sealed namespace for immutability
+ */
+import { ErrorFactory, Logger } from '../../../src/index.js';
+// Priority mappings
+const PRIORITY_VALUES = {
+    critical: 10,
+    high: 5,
+    normal: 1,
+    low: 0,
+};
+let queueRedisModule;
+let hasWarnedMissingQueueRedis = false;
+const loadQueueRedisModule = async () => {
+    if (queueRedisModule)
+        return queueRedisModule;
+    try {
+        queueRedisModule = (await import('../../queue-redis/src/index.js'));
+        return queueRedisModule;
+    }
+    catch (error) {
+        if (!hasWarnedMissingQueueRedis) {
+            hasWarnedMissingQueueRedis = true;
+            Logger.warn('Optional package "@zintrust/queue-redis" is not installed. PriorityQueue features are disabled until it is installed.', error);
+        }
+        return undefined;
+    }
+};
+/**
+ * Helper: Get or create queue via shared driver
+ */
+const getQueue = async (queueName) => {
+    const queueRedis = await loadQueueRedisModule();
+    if (!queueRedis) {
+        throw ErrorFactory.createWorkerError('Optional package "@zintrust/queue-redis" is required for PriorityQueue. Install it to use queue features.');
+    }
+    return queueRedis.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 = await 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 = await 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 = await getQueue(queueName);
+        return queue.getJob(jobId);
+    },
+    /**
+     * Remove a job
+     */
+    async removeJob(queueName, jobId) {
+        const queue = await 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 = await getQueue(queueName);
+        await queue.pause();
+        Logger.info(`Paused queue "${queueName}"`);
+    },
+    /**
+     * Resume a queue
+     */
+    async resume(queueName) {
+        const queue = await getQueue(queueName);
+        await queue.resume();
+        Logger.info(`Resumed queue "${queueName}"`);
+    },
+    /**
+     * Get queue information
+     */
+    async getQueueInfo(queueName) {
+        const queue = await 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
+     */
+    async getQueueNames() {
+        const queueRedis = await loadQueueRedisModule();
+        if (!queueRedis)
+            return [];
+        return queueRedis.BullMQRedisQueue.getQueueNames();
+    },
+    /**
+     * Drain queue (remove all jobs)
+     */
+    async drain(queueName, delayed = false) {
+        const queue = await 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 = await 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 = await getQueue(queueName);
+        await queue.obliterate({ force });
+        const queueRedis = await loadQueueRedisModule();
+        if (queueRedis) {
+            await queueRedis.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) {
+        const queueRedis = await loadQueueRedisModule();
+        if (!queueRedis)
+            return;
+        await queueRedis.BullMQRedisQueue.closeQueue(queueName);
+        Logger.info(`Closed queue "${queueName}"`);
+    },
+    /**
+     * Shutdown and close all queues
+     */
+    async shutdown() {
+        Logger.info('PriorityQueue shutting down via BullMQRedisQueue...');
+        const queueRedis = await loadQueueRedisModule();
+        if (!queueRedis)
+            return;
+        await queueRedis.BullMQRedisQueue.shutdown();
+        Logger.info('PriorityQueue shutdown complete');
+    },
+});
+// Graceful shutdown handled by WorkerShutdown

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

@@ -0,0 +1,165 @@
+/**
+ * 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;
+}>;
+//# sourceMappingURL=ResourceMonitor.d.ts.map

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

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