@archlast/server 0.1.8 → 0.1.9

package/dist/jobs/bullmq-metrics.js

@@ -0,0 +1,323 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BullMQMetricsCollector = void 0;
+exports.setupBullMQPrometheusExporter = setupBullMQPrometheusExporter;
+const bullmq_1 = require("bullmq");
+const prom_client_1 = require("prom-client");
+/**
+ * Collects metrics from BullMQ queues and exports to Prometheus.
+ * Tracks job lifecycle events, processing times, and queue state.
+ */
+class BullMQMetricsCollector {
+    queueEvents = null;
+    metrics;
+    startTimes;
+    queue;
+    gaugeUpdateInterval = null;
+    options;
+    // Prometheus metrics
+    prometheusMetrics = null;
+    constructor(queueName, connection, options = {}) {
+        this.options = {
+            prometheusRegistry: options.prometheusRegistry ?? new prom_client_1.Registry(),
+            enableHistograms: options.enableHistograms ?? true,
+            gaugeUpdateIntervalMs: options.gaugeUpdateIntervalMs ?? 10000,
+        };
+        this.queue = new bullmq_1.Queue(queueName, { connection });
+        this.startTimes = new Map();
+        this.metrics = this.createEmptyMetrics();
+        this.setupPrometheusMetrics();
+    }
+    /**
+     * Creates an empty metrics object with initial values
+     */
+    createEmptyMetrics() {
+        return {
+            jobsCompleted: 0,
+            jobsFailed: 0,
+            jobsDelayed: 0,
+            jobsStalled: 0,
+            processingTimeMs: [],
+            queueWaitTimeMs: [],
+            pendingJobs: 0,
+            activeJobs: 0,
+            completedJobs: 0,
+            failedJobs: 0,
+            delayedJobs: 0,
+            errorTypes: {},
+        };
+    }
+    /**
+     * Sets up Prometheus metrics with the registry
+     */
+    setupPrometheusMetrics() {
+        const register = this.options.prometheusRegistry;
+        this.prometheusMetrics = {
+            jobsCompleted: new prom_client_1.Counter({
+                name: "archlast_jobs_completed_total",
+                help: "Total number of completed jobs",
+                labelNames: ["queue", "job_name"],
+                registers: [register],
+            }),
+            jobsFailed: new prom_client_1.Counter({
+                name: "archlast_jobs_failed_total",
+                help: "Total number of failed jobs",
+                labelNames: ["queue", "job_name", "error_type"],
+                registers: [register],
+            }),
+            jobsRetried: new prom_client_1.Counter({
+                name: "archlast_jobs_retried_total",
+                help: "Total number of job retries",
+                labelNames: ["queue", "job_name"],
+                registers: [register],
+            }),
+            jobsTimedOut: new prom_client_1.Counter({
+                name: "archlast_jobs_timed_out_total",
+                help: "Total number of jobs that timed out",
+                labelNames: ["queue", "job_name"],
+                registers: [register],
+            }),
+            jobsPending: new prom_client_1.Gauge({
+                name: "archlast_jobs_pending",
+                help: "Number of jobs currently pending",
+                labelNames: ["queue"],
+                registers: [register],
+            }),
+            jobsActive: new prom_client_1.Gauge({
+                name: "archlast_jobs_active",
+                help: "Number of jobs currently being processed",
+                labelNames: ["queue"],
+                registers: [register],
+            }),
+            jobsInDLQ: new prom_client_1.Gauge({
+                name: "archlast_jobs_dlq_total",
+                help: "Number of jobs in dead letter queue",
+                labelNames: ["queue"],
+                registers: [register],
+            }),
+            jobDuration: new prom_client_1.Histogram({
+                name: "archlast_job_duration_seconds",
+                help: "Job processing duration in seconds",
+                labelNames: ["queue", "job_name"],
+                buckets: [0.1, 0.5, 1, 2, 5, 10, 30, 60],
+                registers: [register],
+            }),
+            jobQueueWait: new prom_client_1.Histogram({
+                name: "archlast_job_queue_wait_seconds",
+                help: "Time jobs spent waiting in queue",
+                labelNames: ["queue", "job_name"],
+                buckets: [1, 10, 60, 300, 600, 1800, 3600],
+                registers: [register],
+            }),
+        };
+    }
+    /**
+     * Categorizes error messages into types for metrics
+     */
+    categorizeError(reason) {
+        if (!reason)
+            return "unknown";
+        const lowerReason = reason.toLowerCase();
+        if (lowerReason.includes("timeout"))
+            return "timeout";
+        if (lowerReason.includes("econnrefused") ||
+            lowerReason.includes("etimedout") ||
+            lowerReason.includes("enotfound"))
+            return "network";
+        if (lowerReason.includes("validation") || lowerReason.includes("invalid"))
+            return "validation";
+        if (lowerReason.includes("circuit"))
+            return "circuit_breaker";
+        if (lowerReason.includes("rate limit") || lowerReason.includes("ratelimit"))
+            return "rate_limit";
+        if (lowerReason.includes("unauthorized") || lowerReason.includes("forbidden"))
+            return "auth";
+        return "unknown";
+    }
+    /**
+     * Gets the job name from the job object or returns 'unknown'
+     */
+    getJobName(job) {
+        return job.name ?? job.data?.name ?? "unknown";
+    }
+    /**
+     * Starts collecting metrics from the queue.
+     * Sets up event listeners and begins periodic gauge updates.
+     */
+    async start() {
+        if (this.queueEvents) {
+            throw new Error("Metrics collector is already started");
+        }
+        // Create QueueEvents instance for listening to queue events
+        this.queueEvents = new bullmq_1.QueueEvents(this.queue.name, {
+            connection: this.queue.opts?.connection,
+        });
+        // Set up event listeners
+        this.queueEvents.on("completed", async ({ jobId, returnvalue }) => {
+            this.metrics.jobsCompleted++;
+            const startTime = this.startTimes.get(jobId);
+            if (startTime) {
+                const processingTime = Date.now() - startTime;
+                this.metrics.processingTimeMs.push(processingTime);
+                this.startTimes.delete(jobId);
+                // Update Prometheus histogram if enabled
+                if (this.prometheusMetrics && this.options.enableHistograms) {
+                    const job = await this.queue.getJob(jobId);
+                    const jobName = this.getJobName(job ?? {});
+                    this.prometheusMetrics.jobDuration.observe({ queue: this.queue.name, job_name: jobName }, processingTime / 1000 // Convert to seconds
+                    );
+                }
+            }
+            // Update Prometheus counter
+            if (this.prometheusMetrics) {
+                const job = await this.queue.getJob(jobId);
+                const jobName = this.getJobName(job ?? {});
+                this.prometheusMetrics.jobsCompleted.inc({
+                    queue: this.queue.name,
+                    job_name: jobName,
+                });
+            }
+        });
+        this.queueEvents.on("failed", async ({ jobId, failedReason }) => {
+            this.metrics.jobsFailed++;
+            const errorType = this.categorizeError(failedReason);
+            this.metrics.errorTypes[errorType] = (this.metrics.errorTypes[errorType] || 0) + 1;
+            this.startTimes.delete(jobId);
+            // Update Prometheus counter
+            if (this.prometheusMetrics) {
+                const job = await this.queue.getJob(jobId);
+                const jobName = this.getJobName(job ?? {});
+                this.prometheusMetrics.jobsFailed.inc({
+                    queue: this.queue.name,
+                    job_name: jobName,
+                    error_type: errorType,
+                });
+            }
+        });
+        this.queueEvents.on("stalled", ({ jobId }) => {
+            this.metrics.jobsStalled++;
+        });
+        this.queueEvents.on("active", ({ jobId, prev }) => {
+            this.startTimes.set(jobId, Date.now());
+            // Track queue wait time if we have previous state
+            if (prev === "waiting" && this.prometheusMetrics) {
+                this.queue
+                    .getJob(jobId)
+                    .then((job) => {
+                    if (job && job.timestamp) {
+                        const waitTime = Date.now() - job.timestamp;
+                        this.metrics.queueWaitTimeMs.push(waitTime);
+                        if (this.options.enableHistograms) {
+                            const jobName = this.getJobName(job);
+                            this.prometheusMetrics?.jobQueueWait.observe({ queue: this.queue.name, job_name: jobName }, waitTime / 1000 // Convert to seconds
+                            );
+                        }
+                    }
+                })
+                    .catch(() => {
+                    // Ignore errors when getting job for metrics
+                });
+            }
+        });
+        this.queueEvents.on("delayed", ({ jobId }) => {
+            this.metrics.jobsDelayed++;
+        });
+        this.queueEvents.on("retries-exhausted", async ({ jobId }) => {
+            if (this.prometheusMetrics) {
+                const job = await this.queue.getJob(jobId);
+                const jobName = this.getJobName(job ?? {});
+                this.prometheusMetrics.jobsTimedOut.inc({
+                    queue: this.queue.name,
+                    job_name: jobName,
+                });
+            }
+        });
+        // Set up periodic gauge updates
+        await this.updateGauges();
+        this.gaugeUpdateInterval = setInterval(() => this.updateGauges(), this.options.gaugeUpdateIntervalMs);
+    }
+    /**
+     * Stops collecting metrics and cleans up resources.
+     */
+    async stop() {
+        // Clear the gauge update interval
+        if (this.gaugeUpdateInterval) {
+            clearInterval(this.gaugeUpdateInterval);
+            this.gaugeUpdateInterval = null;
+        }
+        // Close QueueEvents
+        if (this.queueEvents) {
+            await this.queueEvents.close();
+            this.queueEvents = null;
+        }
+        // Close the queue connection
+        await this.queue.close();
+    }
+    /**
+     * Gets a snapshot of the current metrics.
+     */
+    getMetrics() {
+        return { ...this.metrics };
+    }
+    /**
+     * Resets all metrics to their initial values.
+     */
+    reset() {
+        this.metrics = this.createEmptyMetrics();
+        this.startTimes.clear();
+    }
+    /**
+     * Updates gauge values by fetching current queue state.
+     */
+    async updateGauges() {
+        try {
+            const counts = await this.queue.getJobCounts("waiting", "active", "completed", "failed", "delayed");
+            this.metrics.pendingJobs = counts.waiting;
+            this.metrics.activeJobs = counts.active;
+            this.metrics.completedJobs = counts.completed;
+            this.metrics.failedJobs = counts.failed;
+            this.metrics.delayedJobs = counts.delayed;
+            // Update Prometheus gauges
+            if (this.prometheusMetrics) {
+                this.prometheusMetrics.jobsPending.set({ queue: this.queue.name }, counts.waiting);
+                this.prometheusMetrics.jobsActive.set({ queue: this.queue.name }, counts.active);
+                this.prometheusMetrics.jobsInDLQ.set({ queue: this.queue.name }, counts.failed);
+            }
+        }
+        catch (error) {
+            // Silently ignore gauge update errors to prevent metric collection
+            // from affecting the main application
+        }
+    }
+    /**
+     * Gets the Prometheus registry associated with this collector.
+     */
+    getPrometheusRegistry() {
+        return this.options.prometheusRegistry;
+    }
+}
+exports.BullMQMetricsCollector = BullMQMetricsCollector;
+/**
+ * Convenience function to set up a BullMQ metrics collector with Prometheus export.
+ *
+ * @param queueName - Name of the BullMQ queue to monitor
+ * @param connection - Redis connection (optional, will create default if not provided)
+ * @param register - Prometheus registry to use
+ * @returns Configured BullMQMetricsCollector instance
+ *
+ * @example
+ * ```typescript
+ * const collector = setupBullMQPrometheusExporter('my-queue', redis, register);
+ * await collector.start();
+ *
+ * // Later...
+ * await collector.stop();
+ * ```
+ */
+function setupBullMQPrometheusExporter(queueName, connection, register) {
+    return new BullMQMetricsCollector(queueName, connection, {
+        prometheusRegistry: register,
+        enableHistograms: true,
+    });
+}
+//# sourceMappingURL=bullmq-metrics.js.map

package/dist/jobs/bullmq-metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bullmq-metrics.js","sourceRoot":"","sources":["../../src/jobs/bullmq-metrics.ts"],"names":[],"mappings":"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"}

package/dist/jobs/bullmq-priority-service.d.ts

@@ -0,0 +1,173 @@
+import Redis from "ioredis";
+/**
+ * Aging metadata tracked for each job to prevent priority starvation.
+ * Stored within the job data under the `__aging__` key.
+ */
+export interface AgingJobData {
+    /** Original priority as set by user (1-20, where 1 is highest priority) */
+    originalPriority: number;
+    /** Current aging bonus (0-5), increases the longer a job waits */
+    agingBonus: number;
+    /** Timestamp when job was created */
+    createdAt: number;
+    /** Timestamp of last aging check */
+    lastAgingCheck: number;
+}
+/**
+ * Options for configuring the priority aging service.
+ */
+interface PriorityAgingServiceOptions {
+    /** How often to check for aging in milliseconds (default: 60000) */
+    checkIntervalMs?: number;
+    /** Maximum jobs to process per check (default: 100) */
+    maxJobsPerCheck?: number;
+}
+/**
+ * Service that implements priority aging for BullMQ jobs.
+ *
+ * Priority aging prevents job starvation by boosting the priority of jobs
+ * that have been waiting in the queue for an extended period. Every 15 minutes,
+ * a job's priority is increased by 1 level (up to a maximum bonus of 5).
+ *
+ * This service runs a background worker that periodically scans waiting jobs
+ * and updates their priorities based on their wait time.
+ *
+ * @example
+ * ```typescript
+ * const agingService = new BullMQPriorityAgingService(
+ *   "my-queue",
+ *   redisConnection,
+ *   { checkIntervalMs: 60000 }
+ * );
+ *
+ * await agingService.start();
+ *
+ * // When enqueueing jobs, prepare data with aging metadata:
+ * const jobData = BullMQPriorityAgingService.prepareJobData(payload, priority);
+ * await queue.add("job-name", jobData, { priority: toBullMQPriority(priority) });
+ * ```
+ */
+export declare class BullMQPriorityAgingService {
+    private readonly AGING_INTERVAL_MS;
+    private readonly MAX_AGING_BONUS;
+    private readonly DEFAULT_CHECK_INTERVAL_MS;
+    private readonly DEFAULT_MAX_JOBS_PER_CHECK;
+    private queue;
+    private agingWorker;
+    private workerConnection;
+    private checkIntervalMs;
+    private maxJobsPerCheck;
+    private queueName;
+    private connection;
+    private _isRunning;
+    private agingInterval;
+    /**
+     * Creates a new BullMQPriorityAgingService instance.
+     *
+     * @param queueName - The name of the BullMQ queue to monitor
+     * @param connection - Redis connection for BullMQ
+     * @param options - Optional configuration for the aging service
+     */
+    constructor(queueName: string, connection: Redis, options?: PriorityAgingServiceOptions);
+    /**
+     * Start the priority aging service.
+     *
+     * This creates a background worker that periodically checks waiting jobs
+     * and applies priority boosts to jobs that have been waiting too long.
+     *
+     * @returns Promise that resolves when the service is started
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the priority aging service.
+     *
+     * Closes the aging worker and clears the check interval.
+     *
+     * @returns Promise that resolves when the service is stopped
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if the aging service is currently running.
+     *
+     * @returns true if the service is running, false otherwise
+     */
+    isRunning(): boolean;
+    /**
+     * Manually trigger an aging check.
+     *
+     * This method scans waiting jobs, calculates their effective priority based on
+     * wait time, and updates job priorities if the aging bonus has increased.
+     *
+     * @returns Statistics about the aging check
+     */
+    applyAging(): Promise<{
+        jobsChecked: number;
+        jobsBoosted: number;
+        averageWaitTimeMs: number;
+    }>;
+    /**
+     * Calculate the effective priority for a job based on its base priority and creation time.
+     *
+     * The aging algorithm adds 1 priority level for every 15 minutes of wait time,
+     * up to a maximum bonus of 5 levels.
+     *
+     * @param basePriority - The original priority (1-20, where 1 is highest)
+     * @param createdAt - Timestamp when the job was created
+     * @param now - Optional current timestamp (defaults to Date.now())
+     * @returns Object containing the effective priority and the calculated aging bonus
+     */
+    static calculateEffectivePriority(basePriority: number, createdAt: number, now?: number): {
+        effectivePriority: number;
+        agingBonus: number;
+    };
+    /**
+     * Convert system priority (1-20) to BullMQ priority (1-2097152).
+     *
+     * BullMQ uses lower numbers for higher priority. The mapping:
+     * - System 1 (highest) → BullMQ 1
+     * - System 10 → BullMQ ~1104750
+     * - System 20 (lowest) → BullMQ 2097152
+     *
+     * @param systemPriority - Priority in system format (1-20)
+     * @returns Priority in BullMQ format (1-2097152)
+     */
+    static toBullMQPriority(systemPriority: number): number;
+    /**
+     * Convert BullMQ priority (1-2097152) back to system priority (1-20).
+     *
+     * @param bullmqPriority - Priority in BullMQ format
+     * @returns Priority in system format (1-20)
+     */
+    static fromBullMQPriority(bullmqPriority: number): number;
+    /**
+     * Prepare job data with aging tracking metadata.
+     *
+     * This should be called when creating a new job to ensure aging metadata
+     * is properly attached to the job data.
+     *
+     * @param payload - The job payload/data
+     * @param priority - The original priority (1-20)
+     * @returns Object containing the payload and aging metadata
+     */
+    static prepareJobData(payload: unknown, priority: number): {
+        name?: string;
+        payload: unknown;
+        __aging__: AgingJobData;
+    };
+    /**
+     * Extract aging metadata from BullMQ job data.
+     *
+     * @param jobData - The job data from BullMQ
+     * @returns The aging data if present, null otherwise
+     */
+    static extractAgingData(jobData: unknown): AgingJobData | null;
+    /**
+     * Perform the actual aging check on waiting jobs.
+     *
+     * This is the internal implementation that scans waiting jobs and applies
+     * priority updates based on their wait time.
+     */
+    private performAgingCheck;
+}
+export default BullMQPriorityAgingService;
+//# sourceMappingURL=bullmq-priority-service.d.ts.map

package/dist/jobs/bullmq-priority-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bullmq-priority-service.d.ts","sourceRoot":"","sources":["../../src/jobs/bullmq-priority-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,SAAS,CAAC;AAG5B;;;GAGG;AACH,MAAM,WAAW,YAAY;IACzB,2EAA2E;IAC3E,gBAAgB,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,cAAc,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,UAAU,2BAA2B;IACjC,oEAAoE;IACpE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC5B;AAWD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,0BAA0B;IACnC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAkB;IACpD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAK;IACrC,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAS;IACnD,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAO;IAElD,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,gBAAgB,CAAsB;IAC9C,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,aAAa,CAA+B;IAEpD;;;;;;OAMG;gBACS,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,2BAA2B;IAgBvF;;;;;;;OAOG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmE5B;;;;;;OAMG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA2C3B;;;;OAIG;IACH,SAAS,IAAI,OAAO;IAIpB;;;;;;;OAOG;IACG,UAAU,IAAI,OAAO,CAAC;QACxB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,iBAAiB,EAAE,MAAM,CAAC;KAC7B,CAAC;IAQF;;;;;;;;;;OAUG;IACH,MAAM,CAAC,0BAA0B,CAC7B,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,GAAG,CAAC,EAAE,MAAM,GACb;QAAE,iBAAiB,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;IAcpD;;;;;;;;;;OAUG;IACH,MAAM,CAAC,gBAAgB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM;IAMvD;;;;;OAKG;IACH,MAAM,CAAC,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM;IAKzD;;;;;;;;;OASG;IACH,MAAM,CAAC,cAAc,CACjB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,GACjB;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,YAAY,CAAA;KAAE;IAe/D;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI;IAiB9D;;;;;OAKG;YACW,iBAAiB;CAqHlC;AAED,eAAe,0BAA0B,CAAC"}