bunqueue 2.8.59 → 2.9.0

package/dist/application/postgres-queue-manager/projectionRefreshes.js

@@ -0,0 +1,170 @@
+export function applyPostgresJobProjection(snapshot, activeTokens, id, projection) {
+    snapshot.reconcile(id, projection.row, projection.completion);
+    const token = activeTokens.get(id);
+    if (token && (projection.row?.state !== 'active' || projection.row.token !== token)) {
+        activeTokens.delete(id);
+    }
+}
+/** Coalesced, generation-fenced repair of the local PostgreSQL read model. */
+export class PostgresProjectionRefreshes {
+    load;
+    apply;
+    report;
+    retryDelayMs;
+    static MAX_ACTIVE_BATCHES = 2;
+    static MAX_REQUESTS_PER_BATCH = 1_000;
+    generations = new Map();
+    generationQueues = new Map();
+    pending = new Map();
+    active = new Set();
+    timer = null;
+    accepting = true;
+    started = false;
+    constructor(load, apply, report, retryDelayMs) {
+        this.load = load;
+        this.apply = apply;
+        this.report = report;
+        this.retryDelayMs = retryDelayMs;
+    }
+    request(id, queue) {
+        if (!this.accepting)
+            return;
+        const generation = this.beginGeneration(id, queue);
+        this.pending.set(id, { queue, generation });
+        this.schedule(0);
+    }
+    supersede(id) {
+        this.pending.delete(id);
+        this.generations.delete(id);
+        this.generationQueues.delete(id);
+    }
+    supersedeQueue(queue) {
+        for (const [id, generationQueue] of this.generationQueues) {
+            if (generationQueue === queue)
+                this.supersede(id);
+        }
+    }
+    async refreshNow(id, queue) {
+        const projections = await this.refreshManyNow([{ id, queue }]);
+        return projections.get(id) ?? { row: null, completion: null };
+    }
+    async refreshManyNow(requests) {
+        let remaining = [...requests];
+        const loaded = new Map();
+        for (let attempt = 0; attempt < 2 && remaining.length > 0; attempt++) {
+            const generations = new Map();
+            for (const { id, queue } of remaining) {
+                const generation = this.beginGeneration(id, queue);
+                this.pending.delete(id);
+                generations.set(id, generation);
+            }
+            try {
+                const projections = await this.load(remaining);
+                const invalidated = [];
+                for (const request of remaining) {
+                    const projection = projections.get(request.id) ?? { row: null, completion: null };
+                    loaded.set(request.id, projection);
+                    if (this.generations.get(request.id) !== generations.get(request.id)) {
+                        invalidated.push(request);
+                        continue;
+                    }
+                    this.apply(request.id, projection);
+                    this.report(request.queue, request.id, null);
+                    this.endGeneration(request.id, generations.get(request.id));
+                }
+                remaining = invalidated;
+            }
+            catch (error) {
+                for (const { id, queue } of remaining) {
+                    const generation = generations.get(id);
+                    if (this.generations.get(id) === generation) {
+                        this.report(queue, id, error);
+                        this.endGeneration(id, generation);
+                    }
+                }
+                throw error;
+            }
+        }
+        for (const { id, queue } of remaining)
+            this.request(id, queue);
+        return loaded;
+    }
+    start() {
+        if (!this.accepting || this.started)
+            return;
+        this.started = true;
+        this.schedule(0);
+    }
+    close() {
+        this.accepting = false;
+        this.pending.clear();
+        this.generations.clear();
+        this.generationQueues.clear();
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+    }
+    async drain() {
+        await Promise.all([...this.active]);
+    }
+    schedule(delayMs) {
+        if (!this.accepting ||
+            !this.started ||
+            this.timer ||
+            this.active.size >= PostgresProjectionRefreshes.MAX_ACTIVE_BATCHES ||
+            this.pending.size === 0) {
+            return;
+        }
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            const execution = this.runBatch();
+            this.active.add(execution);
+            void execution.then((retry) => {
+                this.active.delete(execution);
+                this.schedule(retry ? this.retryDelayMs : 0);
+            });
+        }, delayMs);
+    }
+    async runBatch() {
+        const batch = [...this.pending.entries()].slice(0, PostgresProjectionRefreshes.MAX_REQUESTS_PER_BATCH);
+        for (const [id] of batch)
+            this.pending.delete(id);
+        if (batch.length === 0)
+            return false;
+        try {
+            const projections = await this.load(batch.map(([id, { queue }]) => ({ id, queue })));
+            for (const [id, request] of batch) {
+                if (this.generations.get(id) !== request.generation)
+                    continue;
+                this.apply(id, projections.get(id) ?? { row: null, completion: null });
+                this.report(request.queue, id, null);
+                this.endGeneration(id, request.generation);
+            }
+            return false;
+        }
+        catch (error) {
+            for (const [id, request] of batch) {
+                if (this.generations.get(id) === request.generation && this.accepting) {
+                    this.pending.set(id, request);
+                    this.report(request.queue, id, error);
+                }
+                else {
+                    this.endGeneration(id, request.generation);
+                }
+            }
+            return true;
+        }
+    }
+    beginGeneration(id, queue) {
+        const generation = Symbol();
+        this.generations.set(id, generation);
+        this.generationQueues.set(id, queue);
+        return generation;
+    }
+    endGeneration(id, generation) {
+        if (generation && this.generations.get(id) === generation && !this.pending.has(id)) {
+            this.generations.delete(id);
+            this.generationQueues.delete(id);
+        }
+    }
+}

package/dist/application/postgres-queue-manager/queries.d.ts

@@ -0,0 +1,142 @@
+import { type DlqEntry, type DlqFilter, type DlqStats } from '../../domain/types/dlq';
+import type { Job, JobId } from '../../domain/types/job';
+import { PostgresQueueManagerState } from './state';
+export declare class PostgresQueueManagerQueries extends PostgresQueueManagerState {
+    getJobIndex(): Map<JobId, import("../../domain/types").JobLocation>;
+    getCompletedJobs(): Set<JobId>;
+    getDepCompletions(): Set<JobId>;
+    getJob(jobId: JobId): Promise<Job | null>;
+    getJobState(jobId: JobId): Promise<string>;
+    getResult(jobId: JobId): unknown;
+    getCompletionAsync(jobId: JobId): Promise<{
+        found: boolean;
+        result: unknown;
+    }>;
+    getResultAsync(jobId: JobId): Promise<unknown>;
+    waitForJobCompletion(jobId: JobId, timeoutMs: number): Promise<boolean>;
+    getChildrenValues(parentJobId: JobId): Promise<Record<string, unknown>>;
+    getJobByCustomId(customId: string): Job | null;
+    getProgress(jobId: JobId): {
+        progress: number;
+        message: string | null;
+    } | null;
+    getJobs(queue: string, options?: {
+        state?: string | string[];
+        start?: number;
+        end?: number;
+        asc?: boolean;
+    }): Job[];
+    count(queue: string): number;
+    listQueues(): string[];
+    getCountsPerPriority(queue: string): Record<number, number>;
+    getDlq(queue: string, count?: number): Job[];
+    getDlqEntries(queue: string, filter?: DlqFilter): DlqEntry[];
+    getDlqCount(queue: string): number;
+    getDlqStats(queue: string): DlqStats;
+    isPaused(queue: string): boolean;
+    isPausedDurable(queue: string): Promise<boolean>;
+    getQueueLimits(queue: string): {
+        rateLimit: number | null;
+        concurrencyLimit: number | null;
+    };
+    getQueueLimitStatus(queue: string, _maxJobs?: number): {
+        rateLimit: {
+            max: number;
+            duration: number;
+        } | null;
+        rateLimitTtl: number;
+        concurrencyLimit: number | null;
+        maxed: boolean;
+    };
+    getQueueJobCounts(queueName: string): {
+        waiting: number;
+        prioritized: number;
+        delayed: number;
+        active: number;
+        completed: number;
+        failed: number;
+        'waiting-children': number;
+        totalCompleted: number;
+        totalFailed: number;
+    };
+    getQueueJobCountsBatch(queueNames: Iterable<string>): Map<string, {
+        waiting: number;
+        prioritized: number;
+        delayed: number;
+        active: number;
+        completed: number;
+        failed: number;
+        'waiting-children': number;
+        totalCompleted: number;
+        totalFailed: number;
+    }>;
+    getAllQueueJobCounts(): Map<string, {
+        waiting: number;
+        prioritized: number;
+        delayed: number;
+        active: number;
+        completed: number;
+        failed: number;
+        'waiting-children': number;
+        totalCompleted: number;
+        totalFailed: number;
+    }>;
+    getPerQueueStats(): Map<string, {
+        waiting: number;
+        prioritized: number;
+        delayed: number;
+        active: number;
+        dlq: number;
+    }>;
+    getStats(): {
+        waiting: number;
+        prioritized: number;
+        delayed: number;
+        active: number;
+        dlq: number;
+        completed: number;
+        'waiting-children': number;
+        totalPushed: bigint;
+        totalPulled: bigint;
+        totalCompleted: bigint;
+        totalFailed: bigint;
+        uptime: number;
+        cronJobs: number;
+        cronPending: number;
+    };
+    getQueuesSummary(): {
+        name: string;
+        paused: boolean;
+        counts: {
+            waiting: number;
+            prioritized: number;
+            active: number;
+            completed: number;
+            failed: number;
+            delayed: number;
+        };
+    }[];
+    getStorageStatus(): {
+        diskFull: boolean;
+        error: string | null;
+        since: number | null;
+    };
+    getMemoryStats(): {
+        jobIndex: number;
+        completedJobs: number;
+        jobResults: number;
+        jobLogs: number;
+        customIdMap: number;
+        jobLocks: number;
+        clientJobs: number;
+        clientJobsTotal: number;
+        pendingDepChecks: number;
+        stalledCandidates: number;
+        processingTotal: number;
+        queuedTotal: number;
+        waitingDepsTotal: number;
+        temporalIndexTotal: number;
+        delayedHeapTotal: number;
+    };
+    flushPersistence(): number;
+}

package/dist/application/postgres-queue-manager/queries.js

@@ -0,0 +1,231 @@
+import { PostgresQueueManagerState } from './state';
+function jobCounts(counts, totals) {
+    return {
+        waiting: counts.waiting,
+        prioritized: counts.prioritized,
+        delayed: counts.delayed,
+        active: counts.active,
+        completed: counts.completed,
+        failed: counts.failed,
+        'waiting-children': counts.waitingChildren,
+        totalCompleted: Number(totals?.totalCompleted ?? 0n),
+        totalFailed: Number(totals?.totalFailed ?? 0n),
+    };
+}
+export class PostgresQueueManagerQueries extends PostgresQueueManagerState {
+    getJobIndex() {
+        return this.postgresSnapshot.locations();
+    }
+    getCompletedJobs() {
+        return this.postgresSnapshot.completedIds();
+    }
+    getDepCompletions() {
+        return this.postgresSnapshot.completionIds();
+    }
+    async getJob(jobId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const row = await this.fetchPostgresJob(jobId);
+            return row?.job ?? null;
+        });
+    }
+    async getJobState(jobId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const row = await this.fetchPostgresJob(jobId);
+            return row?.state ?? 'unknown';
+        });
+    }
+    getResult(jobId) {
+        return this.postgresSnapshot.getResult(jobId);
+    }
+    async getCompletionAsync(jobId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.getResult(jobId);
+        });
+    }
+    async getResultAsync(jobId) {
+        return (await this.getCompletionAsync(jobId)).result;
+    }
+    async waitForJobCompletion(jobId, timeoutMs) {
+        const controller = new AbortController();
+        const waiting = super.waitForJobCompletion(jobId, timeoutMs, controller.signal);
+        try {
+            const completed = (await this.getCompletionAsync(jobId)).found;
+            return completed || (await waiting);
+        }
+        finally {
+            controller.abort();
+        }
+    }
+    async getChildrenValues(parentJobId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.getChildrenValues(parentJobId);
+        });
+    }
+    getJobByCustomId(customId) {
+        return this.postgresSnapshot.getByCustomId(customId);
+    }
+    getProgress(jobId) {
+        const row = this.postgresSnapshot.get(jobId);
+        if (row?.state !== 'active')
+            return null;
+        return { progress: row.job.progress, message: row.job.progressMessage };
+    }
+    getJobs(queue, options = {}) {
+        return this.postgresSnapshot.list(queue, options);
+    }
+    count(queue) {
+        const counts = this.postgresSnapshot.counts(queue);
+        return counts.waiting + counts.prioritized + counts.delayed;
+    }
+    listQueues() {
+        return this.postgresSnapshot.queueNames();
+    }
+    getCountsPerPriority(queue) {
+        return this.postgresSnapshot.priorities(queue);
+    }
+    getDlq(queue, count) {
+        return this.postgresSnapshot
+            .dlq(queue, count === undefined ? undefined : { limit: count })
+            .map((entry) => entry.job);
+    }
+    getDlqEntries(queue, filter) {
+        return this.postgresSnapshot.dlq(queue, filter);
+    }
+    getDlqCount(queue) {
+        return this.postgresSnapshot.counts(queue).failed;
+    }
+    getDlqStats(queue) {
+        const entries = this.postgresSnapshot.dlq(queue);
+        const now = Date.now();
+        const byReason = {
+            ["explicit_fail" /* FailureReason.ExplicitFail */]: 0,
+            ["max_attempts_exceeded" /* FailureReason.MaxAttemptsExceeded */]: 0,
+            ["timeout" /* FailureReason.Timeout */]: 0,
+            ["stalled" /* FailureReason.Stalled */]: 0,
+            ["ttl_expired" /* FailureReason.TtlExpired */]: 0,
+            ["worker_lost" /* FailureReason.WorkerLost */]: 0,
+            ["unknown" /* FailureReason.Unknown */]: 0,
+        };
+        for (const entry of entries)
+            byReason[entry.reason]++;
+        return {
+            total: entries.length,
+            byReason,
+            byQueue: { [queue]: entries.length },
+            pendingRetry: entries.filter((entry) => entry.nextRetryAt !== null && entry.nextRetryAt <= now).length,
+            expired: entries.filter((entry) => entry.expiresAt !== null && entry.expiresAt <= now).length,
+            oldestEntry: entries.length === 0 ? null : Math.min(...entries.map((entry) => entry.enteredAt)),
+            newestEntry: entries.length === 0 ? null : Math.max(...entries.map((entry) => entry.enteredAt)),
+        };
+    }
+    isPaused(queue) {
+        return this.postgresSnapshot.queueState(queue)?.paused ?? false;
+    }
+    async isPausedDurable(queue) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return (await this.postgresStore.getQueueState(queue)).paused;
+        });
+    }
+    getQueueLimits(queue) {
+        const state = this.postgresSnapshot.queueState(queue);
+        const rateExpired = state?.rateExpiresAt !== null && (state?.rateExpiresAt ?? 0) <= Date.now();
+        return {
+            rateLimit: rateExpired ? null : (state?.rateLimit ?? null),
+            concurrencyLimit: state?.concurrencyLimit ?? null,
+        };
+    }
+    getQueueLimitStatus(queue, _maxJobs) {
+        const state = this.postgresSnapshot.queueState(queue);
+        const active = this.postgresSnapshot.counts(queue).active;
+        const concurrencyLimit = state?.concurrencyLimit ?? null;
+        const duration = state?.rateDurationMs ?? 1000;
+        const rateExpired = state?.rateExpiresAt !== null && (state?.rateExpiresAt ?? 0) <= Date.now();
+        const rateLimitTtl = state?.rateWindowStartedAt
+            ? Math.max(0, state.rateWindowStartedAt + duration - Date.now())
+            : 0;
+        return {
+            rateLimit: rateExpired || state?.rateLimit === null || state?.rateLimit === undefined
+                ? null
+                : { max: state.rateLimit, duration },
+            rateLimitTtl,
+            concurrencyLimit,
+            maxed: concurrencyLimit !== null && active >= concurrencyLimit,
+        };
+    }
+    getQueueJobCounts(queueName) {
+        return jobCounts(this.postgresSnapshot.counts(queueName), this.perQueueMetrics.get(queueName));
+    }
+    getQueueJobCountsBatch(queueNames) {
+        return new Map([...queueNames].map((queue) => [queue, this.getQueueJobCounts(queue)]));
+    }
+    getAllQueueJobCounts() {
+        return this.getQueueJobCountsBatch(this.listQueues());
+    }
+    getPerQueueStats() {
+        return new Map(this.listQueues().map((queue) => {
+            const counts = this.postgresSnapshot.counts(queue);
+            return [
+                queue,
+                {
+                    waiting: counts.waiting,
+                    prioritized: counts.prioritized,
+                    delayed: counts.delayed,
+                    active: counts.active,
+                    dlq: counts.failed,
+                },
+            ];
+        }));
+    }
+    getStats() {
+        const counts = this.postgresSnapshot.counts();
+        const cron = this.cronScheduler.getStats();
+        return {
+            waiting: counts.waiting,
+            prioritized: counts.prioritized,
+            delayed: counts.delayed,
+            active: counts.active,
+            dlq: counts.failed,
+            completed: counts.completed,
+            'waiting-children': counts.waitingChildren,
+            totalPushed: this.metrics.totalPushed.value,
+            totalPulled: this.metrics.totalPulled.value,
+            totalCompleted: this.metrics.totalCompleted.value,
+            totalFailed: this.metrics.totalFailed.value,
+            uptime: Date.now() - this.startTime,
+            cronJobs: cron.total,
+            cronPending: cron.pending,
+        };
+    }
+    getQueuesSummary() {
+        return this.listQueues().map((name) => {
+            const counts = this.postgresSnapshot.counts(name);
+            return {
+                name,
+                paused: this.isPaused(name),
+                counts: {
+                    waiting: counts.waiting,
+                    prioritized: counts.prioritized,
+                    active: counts.active,
+                    completed: counts.completed,
+                    failed: counts.failed,
+                    delayed: counts.delayed,
+                },
+            };
+        });
+    }
+    getStorageStatus() {
+        const health = this.postgresStore.health();
+        return { diskFull: false, error: health.error, since: health.since };
+    }
+    getMemoryStats() {
+        return { ...super.getMemoryStats(), jobIndex: this.postgresSnapshot.size() };
+    }
+    flushPersistence() {
+        return 0;
+    }
+}

package/dist/application/postgres-queue-manager/relationships.d.ts

@@ -0,0 +1,10 @@
+import type { JobId } from '../../domain/types/job';
+import { PostgresQueueManagerLease } from './lease';
+/** PostgreSQL-backed parent/child relationship mutations. */
+export declare class PostgresQueueManagerRelationships extends PostgresQueueManagerLease {
+    getFailedChildrenValues(parentId: JobId): Promise<Record<string, string>>;
+    getIgnoredChildrenFailures(parentId: JobId): Promise<Record<string, string>>;
+    updateJobParent(childId: JobId, parentId: JobId): Promise<void>;
+    removeChildDependency(childId: JobId): Promise<boolean>;
+    removeUnprocessedChildren(parentId: JobId): Promise<void>;
+}

package/dist/application/postgres-queue-manager/relationships.js

@@ -0,0 +1,45 @@
+import { PostgresQueueManagerLease } from './lease';
+/** PostgreSQL-backed parent/child relationship mutations. */
+export class PostgresQueueManagerRelationships extends PostgresQueueManagerLease {
+    async getFailedChildrenValues(parentId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.getFailedChildrenValues(parentId);
+        });
+    }
+    async getIgnoredChildrenFailures(parentId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            return await this.postgresStore.getIgnoredChildrenFailures(parentId);
+        });
+    }
+    async updateJobParent(childId, parentId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            await this.postgresStore.updateParent(childId, parentId);
+            await Promise.all([this.refreshJob(childId), this.refreshJob(parentId)]);
+        });
+    }
+    async removeChildDependency(childId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const child = await this.postgresStore.getJob(childId);
+            const parentId = child?.job.parentId ?? null;
+            const removed = await this.postgresStore.removeDependency(childId);
+            if (removed) {
+                await this.refreshJob(childId);
+                if (parentId)
+                    await this.refreshJob(parentId);
+            }
+            return removed;
+        });
+    }
+    async removeUnprocessedChildren(parentId) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const removed = await this.postgresStore.removeUnprocessedChildren(parentId);
+            if (removed.length > 0)
+                await this.refreshJobs([parentId, ...removed]);
+        });
+    }
+}

package/dist/application/postgres-queue-manager/services.d.ts

@@ -0,0 +1,31 @@
+import type { CronJob, CronJobInput } from '../../domain/types/cron';
+import type { JobId } from '../../domain/types/job';
+import type { QueueMetrics, QueueMetricType } from '../../domain/types/metrics';
+import type { CreateWorkerOptions, Worker } from '../../domain/types/worker';
+import { PostgresQueueManagerControl } from './control';
+/** Durable PostgreSQL-backed broker services shared across every broker instance. */
+export declare class PostgresQueueManagerServices extends PostgresQueueManagerControl {
+    registerWorker(name: string, queues: string[], concurrency?: number, options?: CreateWorkerOptions): Worker;
+    registerWorkerDurable(name: string, queues: string[], concurrency?: number, options?: CreateWorkerOptions): Promise<Worker>;
+    unregisterWorker(id: string): boolean;
+    unregisterWorkerDurable(id: string, clientId?: string): Promise<boolean>;
+    unregisterWorkersByClientId(clientId: string): number;
+    heartbeatWorkerDurable(id: string, stats?: {
+        activeJobs?: number;
+        processed?: number;
+        failed?: number;
+    }, clientId?: string): Promise<boolean>;
+    listWorkersDurable(): Promise<Worker[]>;
+    findMissingDependenciesDurable(ids: readonly JobId[]): Promise<JobId[]>;
+    addCron(input: CronJobInput): CronJob;
+    addCronDurable(input: CronJobInput): Promise<CronJob>;
+    removeCron(name: string): boolean;
+    removeCronDurable(name: string): Promise<boolean>;
+    getCronDurable(name: string): Promise<CronJob | undefined>;
+    listCronsDurable(): Promise<CronJob[]>;
+    addLogDurable(id: JobId, message: string, level?: 'info' | 'warn' | 'error'): Promise<boolean>;
+    getLogsDurable(id: JobId): Promise<import("../../domain/types/worker").JobLogEntry[]>;
+    clearLogsDurable(id: JobId, keepLogs?: number): Promise<void>;
+    getQueueMetricsDurable(queue: string, type: QueueMetricType, start?: number, end?: number): Promise<QueueMetrics>;
+    trimQueueEventsDurable(queue: string, maxLength: number): Promise<number>;
+}