bunqueue 2.8.60 → 2.9.2

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

@@ -0,0 +1,100 @@
+import { PostgresQueueManagerRelationships } from './relationships';
+function matchesFilter(entry, filter, now) {
+    if (filter.reason && entry.reason !== filter.reason)
+        return false;
+    if (filter.olderThan !== undefined && entry.enteredAt >= filter.olderThan)
+        return false;
+    if (filter.newerThan !== undefined && entry.enteredAt <= filter.newerThan)
+        return false;
+    if (filter.expired !== undefined &&
+        (entry.expiresAt !== null && entry.expiresAt <= now) !== filter.expired) {
+        return false;
+    }
+    return true;
+}
+function boundedLimit(value) {
+    if (value === undefined)
+        return Number.MAX_SAFE_INTEGER;
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+/** Durable maintenance commands that cannot use the synchronous SQLite façade. */
+export class PostgresQueueManagerMaintenance extends PostgresQueueManagerRelationships {
+    async retryDlqDurable(queue, id, count, filter) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const limit = boundedLimit(count ?? filter?.limit);
+            if (limit === 0)
+                return 0;
+            const now = await this.postgresStore.now();
+            let entries = await this.postgresStore.getDlq(queue, 2_147_483_647);
+            if (id)
+                entries = entries.filter((entry) => entry.job.id === id);
+            if (filter)
+                entries = entries.filter((entry) => matchesFilter(entry, filter, now));
+            const offset = Math.max(0, filter?.offset ?? 0);
+            entries = entries.slice(offset, offset + limit);
+            let retried = 0;
+            for (const entry of entries) {
+                if (await this.postgresStore.retry(entry.job.id))
+                    retried++;
+            }
+            if (retried > 0)
+                await this.refreshQueueAfterCommit(queue);
+            return retried;
+        });
+    }
+    async purgeDlqDurable(queue) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const ids = await this.postgresStore.purgeDlq(queue);
+            if (ids.length > 0)
+                await this.refreshQueueAfterCommit(queue);
+            return ids.length;
+        });
+    }
+    async removeDlqJobDurable(queue, id) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const removed = await this.postgresStore.removeDlq(queue, id);
+            if (removed)
+                this.postgresSnapshot.remove(id);
+            return removed;
+        });
+    }
+    async retryCompletedDurable(queue, id, options = {}) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const limit = boundedLimit(options.limit);
+            if (limit === 0)
+                return 0;
+            let rows = await this.postgresStore.list(queue, {
+                states: ['completed'],
+                limit: 2_147_483_647,
+                asc: true,
+            });
+            if (id)
+                rows = rows.filter((row) => row.job.id === id);
+            const timestamp = options.timestamp;
+            if (timestamp !== undefined) {
+                rows = rows.filter((row) => (row.job.completedAt ?? Infinity) <= timestamp);
+            }
+            let retried = 0;
+            for (const row of rows.slice(0, limit)) {
+                if (await this.postgresStore.retry(row.job.id))
+                    retried++;
+            }
+            if (retried > 0)
+                await this.refreshQueueAfterCommit(queue);
+            return retried;
+        });
+    }
+    async cleanDurable(queue, graceMs, state, limit) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const ids = await this.postgresStore.clean(queue, graceMs, state, limit);
+            if (ids.length > 0)
+                await this.refreshQueueAfterCommit(queue);
+            return ids;
+        });
+    }
+}

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

@@ -0,0 +1,26 @@
+export type PostgresSyncAdmission<T> = {
+    readonly accepted: true;
+    readonly value: T;
+} | {
+    readonly accepted: false;
+};
+/** Stop new PostgreSQL operations and drain work admitted before shutdown. */
+export declare class PostgresOperationGate {
+    private readonly maxConcurrent;
+    private readonly maxQueued;
+    private readonly scopes;
+    private accepting;
+    private active;
+    private running;
+    private readonly queued;
+    private drainPromise;
+    private resolveDrain;
+    constructor(maxConcurrent?: number, maxQueued?: number);
+    run<T>(operation: () => Promise<T>): Promise<T>;
+    runSync<T>(operation: () => T): T;
+    tryRunSync<T>(operation: () => T): PostgresSyncAdmission<T>;
+    closeAndDrain(): Promise<void>;
+    private admit;
+    private enterSync;
+    private finish;
+}

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

@@ -0,0 +1,96 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** Stop new PostgreSQL operations and drain work admitted before shutdown. */
+export class PostgresOperationGate {
+    maxConcurrent;
+    maxQueued;
+    scopes = new AsyncLocalStorage();
+    accepting = true;
+    active = 0;
+    running = 0;
+    queued = [];
+    drainPromise = null;
+    resolveDrain = null;
+    constructor(maxConcurrent = Number.POSITIVE_INFINITY, maxQueued = Number.POSITIVE_INFINITY) {
+        this.maxConcurrent = maxConcurrent;
+        this.maxQueued = maxQueued;
+    }
+    async run(operation) {
+        const parent = this.scopes.getStore();
+        const nested = parent?.active === true;
+        await this.admit(nested);
+        const scope = { active: true };
+        try {
+            return await this.scopes.run(scope, operation);
+        }
+        finally {
+            this.finish(scope, nested);
+        }
+    }
+    runSync(operation) {
+        const scope = this.enterSync();
+        try {
+            return this.scopes.run(scope, operation);
+        }
+        finally {
+            this.finish(scope, true);
+        }
+    }
+    tryRunSync(operation) {
+        if (!this.accepting && !this.scopes.getStore()?.active)
+            return { accepted: false };
+        return { accepted: true, value: this.runSync(operation) };
+    }
+    closeAndDrain() {
+        if (this.scopes.getStore()?.active) {
+            throw new Error('Cannot shut down PostgreSQL from an active queue operation');
+        }
+        this.accepting = false;
+        if (this.active === 0)
+            return Promise.resolve();
+        this.drainPromise ??= new Promise((resolve) => {
+            this.resolveDrain = resolve;
+        });
+        return this.drainPromise;
+    }
+    async admit(nested) {
+        if (!this.accepting && !this.scopes.getStore()?.active) {
+            throw new Error('PostgreSQL queue manager is shutting down');
+        }
+        if (nested) {
+            this.active++;
+            return;
+        }
+        if (this.running < this.maxConcurrent) {
+            this.running++;
+            this.active++;
+            return;
+        }
+        if (this.queued.length >= this.maxQueued) {
+            throw new Error('PostgreSQL operation queue is saturated');
+        }
+        this.active++;
+        await new Promise((resolve) => this.queued.push({ resolve }));
+    }
+    enterSync() {
+        if (!this.accepting && !this.scopes.getStore()?.active) {
+            throw new Error('PostgreSQL queue manager is shutting down');
+        }
+        this.active++;
+        return { active: true };
+    }
+    finish(scope, nested) {
+        scope.active = false;
+        this.active--;
+        if (!nested) {
+            const next = this.queued.shift();
+            if (next)
+                next.resolve();
+            else
+                this.running--;
+        }
+        if (this.active !== 0)
+            return;
+        this.resolveDrain?.();
+        this.resolveDrain = null;
+    }
+}

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

@@ -0,0 +1,25 @@
+import type { JobId } from '../../domain/types/job';
+import { PostgresQueueManagerCloud } from './cloud';
+export declare class PostgresQueueManagerOperations extends PostgresQueueManagerCloud {
+    private readonly clientReleaseSessions;
+    cancel(id: JobId): Promise<boolean>;
+    updateProgress(id: JobId, progress: number, message?: string): Promise<boolean>;
+    updateJobData(id: JobId, data: unknown): Promise<boolean>;
+    changePriority(id: JobId, priority: number, lifo?: boolean): Promise<boolean>;
+    promote(id: JobId): Promise<boolean>;
+    promoteJobs(queue: string, count?: number): Promise<number>;
+    moveToDelayed(id: JobId, delay: number, token?: string): Promise<boolean>;
+    changeDelay(id: JobId, delay: number, token?: string): Promise<boolean>;
+    moveActiveToWait(id: JobId, token?: string): Promise<boolean>;
+    changeWaitingDelay(id: JobId, delay: number): Promise<boolean>;
+    moveToWaitingChildren(id: JobId, token?: string): Promise<boolean>;
+    discard(id: JobId, token?: string): Promise<boolean>;
+    getDeduplicationJobId(queue: string, key: string): string | null;
+    removeDeduplicationKey(queue: string, key: string): Promise<number>;
+    removeJobDeduplicationKey(id: string): Promise<boolean>;
+    releaseClientJobs(clientId: string): Promise<number>;
+    forceReleaseClientJobs(clientId: string): number;
+    private getClientReleaseSession;
+    private runClientRelease;
+    private releaseClientSession;
+}

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

@@ -0,0 +1,194 @@
+import { PostgresQueueManagerCloud } from './cloud';
+export class PostgresQueueManagerOperations extends PostgresQueueManagerCloud {
+    clientReleaseSessions = new Map();
+    async cancel(id) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const removed = await this.postgresStore.cancel(id);
+            if (removed)
+                this.postgresSnapshot.remove(id);
+            return removed;
+        });
+    }
+    async updateProgress(id, progress, message) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const updated = await this.postgresStore.updateProgress(id, progress, message);
+            if (updated)
+                await this.refreshJob(id);
+            return updated;
+        });
+    }
+    async updateJobData(id, data) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const updated = await this.postgresStore.updateData(id, data);
+            if (updated)
+                await this.refreshJob(id);
+            return updated;
+        });
+    }
+    async changePriority(id, priority, lifo) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const updated = await this.postgresStore.changePriority(id, priority, lifo);
+            if (updated)
+                await this.refreshJob(id);
+            return updated;
+        });
+    }
+    async promote(id) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const promoted = await this.postgresStore.promote(id);
+            if (promoted)
+                await this.refreshJob(id);
+            return promoted;
+        });
+    }
+    async promoteJobs(queue, count) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const promoted = await this.postgresStore.promoteMany(queue, count);
+            if (promoted.length > 0)
+                await this.refreshQueueAfterCommit(queue);
+            return promoted.length;
+        });
+    }
+    async moveToDelayed(id, delay, token) {
+        return await this.runPostgresOperation(() => this.changeDelay(id, delay, token));
+    }
+    async changeDelay(id, delay, token) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const now = await this.postgresStore.now();
+            const changed = await this.postgresStore.changeDelay(id, now + Math.max(0, delay), this.tokenFor(id, token) ?? undefined);
+            if (changed) {
+                this.forgetToken(id);
+                await this.refreshJob(id);
+            }
+            return changed;
+        });
+    }
+    async moveActiveToWait(id, token) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const now = await this.postgresStore.now();
+            const moved = await this.postgresStore.changeDelay(id, now, this.tokenFor(id, token) ?? undefined);
+            if (moved) {
+                this.forgetToken(id);
+                await this.refreshJob(id);
+            }
+            return moved;
+        });
+    }
+    async changeWaitingDelay(id, delay) {
+        return await this.runPostgresOperation(() => this.changeDelay(id, delay));
+    }
+    async moveToWaitingChildren(id, token) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const moved = await this.postgresStore.moveToWaitingChildren(id, this.tokenFor(id, token) ?? undefined);
+            if (moved) {
+                this.forgetToken(id);
+                await this.refreshJob(id);
+            }
+            return moved;
+        });
+    }
+    async discard(id, token) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const removed = await this.postgresStore.discard(id, this.tokenFor(id, token) ?? undefined);
+            if (removed) {
+                this.forgetToken(id);
+                await this.refreshJob(id);
+            }
+            return removed;
+        });
+    }
+    getDeduplicationJobId(queue, key) {
+        return this.postgresSnapshot.getByUniqueKey(queue, key)?.id ?? null;
+    }
+    async removeDeduplicationKey(queue, key) {
+        return await this.runPostgresOperation(async () => {
+            const job = this.postgresSnapshot.getByUniqueKey(queue, key);
+            if (!job)
+                return 0;
+            const removed = await this.postgresStore.clearUniqueKey(job.id);
+            if (removed)
+                await this.refreshJob(job.id);
+            return removed ? 1 : 0;
+        });
+    }
+    async removeJobDeduplicationKey(id) {
+        return await this.runPostgresOperation(async () => {
+            await this.postgresReady;
+            const removed = await this.postgresStore.clearUniqueKey(id);
+            if (removed)
+                await this.refreshJob(id);
+            return removed;
+        });
+    }
+    async releaseClientJobs(clientId) {
+        return await this.runPostgresOperation(() => this.runClientRelease(clientId));
+    }
+    forceReleaseClientJobs(clientId) {
+        const admitted = this.operations.tryRunSync(() => {
+            const session = this.getClientReleaseSession(clientId);
+            const tracked = session.leases.size;
+            if (tracked > 0)
+                this.enqueueWrite(() => this.runClientRelease(clientId).then(() => undefined));
+            return tracked;
+        });
+        if (admitted.accepted)
+            return admitted.value;
+        return this.clientReleaseSessions.get(clientId)?.leases.size ?? 0;
+    }
+    getClientReleaseSession(clientId) {
+        const current = this.clientReleaseSessions.get(clientId);
+        if (current)
+            return current;
+        const leases = new Map();
+        for (const id of this.clientJobs.get(clientId) ?? []) {
+            const token = this.tokenFor(id);
+            if (token)
+                leases.set(id, token);
+            else
+                this.clientJobs.get(clientId)?.delete(id);
+        }
+        if (this.clientJobs.get(clientId)?.size === 0)
+            this.clientJobs.delete(clientId);
+        const session = { leases, released: 0, inFlight: null };
+        this.clientReleaseSessions.set(clientId, session);
+        return session;
+    }
+    async runClientRelease(clientId) {
+        const session = this.getClientReleaseSession(clientId);
+        if (session.inFlight)
+            return await session.inFlight;
+        const attempt = this.releaseClientSession(clientId, session).finally(() => {
+            if (session.inFlight === attempt)
+                session.inFlight = null;
+        });
+        session.inFlight = attempt;
+        return await attempt;
+    }
+    async releaseClientSession(clientId, session) {
+        for (const [id, token] of [...session.leases]) {
+            const released = await this.postgresStore.releaseClientLease(id, token);
+            session.leases.delete(id);
+            this.clientJobs.get(clientId)?.delete(id);
+            if (this.clientJobs.get(clientId)?.size === 0)
+                this.clientJobs.delete(clientId);
+            if (this.activeTokens.get(id) === token)
+                this.activeTokens.delete(id);
+            if (released)
+                session.released++;
+            await this.refreshJob(id);
+        }
+        if (session.leases.size === 0)
+            this.clientReleaseSessions.delete(clientId);
+        return session.released;
+    }
+}

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

@@ -0,0 +1,43 @@
+import type { JobId } from '../../domain/types/job';
+import type { PostgresJobProjection } from '../../infrastructure/persistence/postgres/readModels';
+import type { PostgresQueueSnapshot } from './snapshot';
+export type { PostgresJobProjection } from '../../infrastructure/persistence/postgres/readModels';
+export declare function applyPostgresJobProjection(snapshot: PostgresQueueSnapshot, activeTokens: Map<JobId, string>, id: JobId, projection: PostgresJobProjection): void;
+type ProjectionLoader = (requests: readonly {
+    id: JobId;
+    queue: string;
+}[]) => Promise<ReadonlyMap<JobId, PostgresJobProjection>>;
+type ProjectionApplier = (id: JobId, projection: PostgresJobProjection) => void;
+type ProjectionReporter = (queue: string, id: JobId, error: unknown) => void;
+/** Coalesced, generation-fenced repair of the local PostgreSQL read model. */
+export declare class PostgresProjectionRefreshes {
+    private readonly load;
+    private readonly apply;
+    private readonly report;
+    private readonly retryDelayMs;
+    private static readonly MAX_ACTIVE_BATCHES;
+    private static readonly MAX_REQUESTS_PER_BATCH;
+    private readonly generations;
+    private readonly generationQueues;
+    private readonly pending;
+    private readonly active;
+    private timer;
+    private accepting;
+    private started;
+    constructor(load: ProjectionLoader, apply: ProjectionApplier, report: ProjectionReporter, retryDelayMs: number);
+    request(id: JobId, queue: string): void;
+    supersede(id: JobId): void;
+    supersedeQueue(queue: string): void;
+    refreshNow(id: JobId, queue: string): Promise<PostgresJobProjection>;
+    refreshManyNow(requests: readonly {
+        id: JobId;
+        queue: string;
+    }[]): Promise<ReadonlyMap<JobId, PostgresJobProjection>>;
+    start(): void;
+    close(): void;
+    drain(): Promise<void>;
+    private schedule;
+    private runBatch;
+    private beginGeneration;
+    private endGeneration;
+}

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);
+        }
+    }
+}