bunqueue 2.8.60 → 2.9.2

package/dist/application/dlqRetry.js

@@ -3,33 +3,63 @@ import { MAX_TIMELINE_ENTRIES } from '../domain/types/job';
 import { retainDlqRetryState, scheduleNextRetry, setDlqRetryState } from '../domain/types/dlq';
 import { shardIndex } from '../shared/hash';
 function prepareRetry(job, now) {
-    job.attempts = 0;
-    job.runAt = now;
-    job.startedAt = null;
-    job.stallCount = 0;
-    job.lastHeartbeat = now;
-    if (job.timeline.length < MAX_TIMELINE_ENTRIES) {
-        job.timeline.push({ state: 'waiting', timestamp: now });
-    }
+    const timeline = [...job.timeline];
+    if (timeline.length < MAX_TIMELINE_ENTRIES)
+        timeline.push({ state: 'waiting', timestamp: now });
+    return {
+        ...job,
+        attempts: 0,
+        lastHeartbeat: now,
+        runAt: now,
+        stallCount: 0,
+        startedAt: null,
+        timeline,
+    };
+}
+function canRetry(queue, job, ctx) {
+    const idx = shardIndex(queue);
+    const shard = ctx.shards[idx];
+    const location = ctx.jobIndex.get(job.id);
+    if (location?.type !== 'dlq' || location.queueName !== queue)
+        return false;
+    const customOwner = job.customId ? ctx.customIdMap.get(job.customId) : undefined;
+    if (customOwner && customOwner !== job.id)
+        return false;
+    const keyOwner = job.uniqueKey ? shard.getUniqueKeyEntry(queue, job.uniqueKey) : null;
+    return keyOwner === null || keyOwner.jobId === job.id;
 }
-function enqueueRetry(queue, job, now, ctx) {
+function publishRetry(queue, job, ctx) {
     const idx = shardIndex(queue);
     const shard = ctx.shards[idx];
-    prepareRetry(job, now);
     shard.getQueue(queue).push(job);
-    shard.incrementQueued(job.id, job.runAt > now, job.createdAt, queue, job.runAt);
+    shard.incrementQueued(job.id, false, job.createdAt, queue, job.runAt);
     ctx.jobIndex.set(job.id, { type: 'queue', shardIdx: idx, queueName: queue });
+    if (job.customId)
+        ctx.customIdMap.set(job.customId, job.id);
+    if (job.uniqueKey) {
+        shard.registerUniqueKeyWithTtl(queue, job.uniqueKey, job.id, job.deduplicationTtl ?? undefined);
+    }
+}
+function retryEntry(queue, entry, ctx, now, prepareState) {
+    if (!canRetry(queue, entry.job, ctx))
+        return null;
+    const job = prepareRetry(entry.job, now);
+    ctx.shards[shardIndex(queue)].assignGroupFifoOrder(job);
+    prepareState(job);
     ctx.storage?.requeueDlqJob(job);
+    const removed = ctx.shards[shardIndex(queue)].removeFromDlq(queue, entry.job.id);
+    if (!removed)
+        throw new Error('DLQ entry disappeared after its retry committed');
+    publishRetry(queue, job, ctx);
+    return job;
 }
 /** Retry a single job from DLQ and reset the automatic retry generation. */
 export function retryDlqJob(queue, jobId, ctx) {
     const shard = ctx.shards[shardIndex(queue)];
-    const entry = shard.removeFromDlq(queue, jobId);
+    const entry = shard.getDlqEntries(queue).find((candidate) => candidate.job.id === jobId);
     if (!entry)
         return null;
-    setDlqRetryState(entry.job, null);
-    enqueueRetry(queue, entry.job, Date.now(), ctx);
-    return entry.job;
+    return retryEntry(queue, entry, ctx, Date.now(), (job) => setDlqRetryState(job, null));
 }
 /** Retry jobs from DLQ, optionally bounded to the oldest `limit` entries. */
 export function retryDlqJobs(queue, ctx, jobId, limit) {
@@ -49,29 +79,21 @@ export function retryDlqJobs(queue, ctx, jobId, limit) {
         }
         return retried;
     }
-    const entries = [...shard.getDlqEntries(queue)];
-    shard.clearDlq(queue);
-    ctx.storage?.clearDlqQueue(queue);
-    const now = Date.now();
-    for (const entry of entries) {
-        setDlqRetryState(entry.job, null);
-        enqueueRetry(queue, entry.job, now, ctx);
-    }
-    return entries.length;
+    const ids = shard.getDlqEntries(queue).map((entry) => entry.job.id);
+    let retried = 0;
+    for (const id of ids)
+        if (retryDlqJob(queue, id, ctx))
+            retried++;
+    return retried;
 }
 /** Retry all DLQ entries selected by a metadata filter. */
 export function retryDlqByFilter(queue, ctx, filter) {
     const shard = ctx.shards[shardIndex(queue)];
     const entries = [...shard.getDlqFiltered(queue, filter)];
-    const now = Date.now();
     let retried = 0;
     for (const entry of entries) {
-        const removed = shard.removeFromDlq(queue, entry.job.id);
-        if (!removed)
-            continue;
-        setDlqRetryState(removed.job, null);
-        enqueueRetry(queue, removed.job, now, ctx);
-        retried++;
+        if (retryDlqJob(queue, entry.job.id, ctx))
+            retried++;
     }
     return retried;
 }
@@ -85,13 +107,13 @@ export function processAutoRetry(queue, ctx) {
     const entries = [...shard.getAutoRetryEntries(queue, now)];
     let retried = 0;
     for (const entry of entries) {
-        const removed = shard.removeFromDlq(queue, entry.job.id);
-        if (!removed)
-            continue;
-        scheduleNextRetry(removed, config);
-        retainDlqRetryState(removed.job, removed);
-        enqueueRetry(queue, removed.job, now, ctx);
-        retried++;
+        const scheduled = { ...entry, attempts: [...entry.attempts] };
+        scheduleNextRetry(scheduled, config);
+        const job = retryEntry(queue, entry, ctx, now, (candidate) => {
+            retainDlqRetryState(candidate, scheduled);
+        });
+        if (job)
+            retried++;
     }
     return retried;
 }

package/dist/application/eventsManager.d.ts

@@ -7,11 +7,14 @@ import { EventType, type JobEvent } from '../domain/types/queue';
 import type { WebhookManager } from './webhookManager';
 /** Event subscriber callback */
 export type EventSubscriber = (event: JobEvent) => void;
+export type EventBatchSubscriber = (events: readonly JobEvent[]) => void;
 /** Events manager class */
 export declare class EventsManager {
     private readonly webhookManager;
     /** Use Set for O(1) subscribe/unsubscribe instead of indexOf+splice */
     private readonly subscribers;
+    /** Optional batch path for internal subscribers such as durable telemetry. */
+    private readonly batchSubscribers;
     /** Waiters for specific job completions - for efficient WaitJob implementation */
     private readonly completionWaiters;
     constructor(webhookManager: WebhookManager);
@@ -20,14 +23,14 @@ export declare class EventsManager {
     /** Number of jobs with active completion waiters */
     get completionWaiterCount(): number;
     /** Subscribe to job events - O(1) add and remove */
-    subscribe(callback: EventSubscriber): () => void;
+    subscribe(callback: EventSubscriber, batchCallback?: EventBatchSubscriber): () => void;
     /** Clear all subscribers (for shutdown) */
     clear(): void;
     /**
      * Wait for a specific job to complete - event-driven, no polling
      * Returns true if job completed, false if timeout
      */
-    waitForJobCompletion(jobId: JobId, timeoutMs: number): Promise<boolean>;
+    waitForJobCompletion(jobId: JobId, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
     /** Check if broadcast has any listeners - for batch optimizations */
     needsBroadcast(): boolean;
     /** Broadcast event to all subscribers - optimized to skip work when no listeners */
@@ -38,6 +41,10 @@ export declare class EventsManager {
         timestamp: number;
         error?: string;
     }): void;
+    /** Broadcast an ordered batch while allowing internal subscribers to persist once. */
+    broadcastBatch(events: readonly JobEvent[]): void;
+    private notifyCompletionWaiters;
+    private triggerWebhook;
     /** Map internal event type to webhook event */
     private mapEventToWebhook;
 }

package/dist/application/eventsManager.js

@@ -8,6 +8,8 @@ export class EventsManager {
     webhookManager;
     /** Use Set for O(1) subscribe/unsubscribe instead of indexOf+splice */
     subscribers = new Set();
+    /** Optional batch path for internal subscribers such as durable telemetry. */
+    batchSubscribers = new Map();
     /** Waiters for specific job completions - for efficient WaitJob implementation */
     completionWaiters = new Map();
     constructor(webhookManager) {
@@ -22,21 +24,24 @@ export class EventsManager {
         return this.completionWaiters.size;
     }
     /** Subscribe to job events - O(1) add and remove */
-    subscribe(callback) {
+    subscribe(callback, batchCallback) {
         this.subscribers.add(callback);
+        if (batchCallback)
+            this.batchSubscribers.set(callback, batchCallback);
         return () => {
             this.subscribers.delete(callback); // O(1) instead of O(n)
+            this.batchSubscribers.delete(callback);
         };
     }
     /** Clear all subscribers (for shutdown) */
     clear() {
         this.subscribers.clear();
+        this.batchSubscribers.clear();
         // Clear all waiters
         for (const waiters of this.completionWaiters.values()) {
             for (const waiter of waiters) {
-                if (!waiter.cancelled) {
+                if (!waiter.cancelled)
                     waiter.resolve();
-                }
             }
         }
         this.completionWaiters.clear();
@@ -45,40 +50,45 @@ export class EventsManager {
      * Wait for a specific job to complete - event-driven, no polling
      * Returns true if job completed, false if timeout
      */
-    waitForJobCompletion(jobId, timeoutMs) {
+    waitForJobCompletion(jobId, timeoutMs, signal) {
         const jobKey = String(jobId);
+        if (signal?.aborted)
+            return Promise.resolve(false);
         return new Promise((resolve) => {
+            let settled = false;
+            const cleanup = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+                const waiters = this.completionWaiters.get(jobKey);
+                waiters?.delete(waiter);
+                if (waiters?.size === 0)
+                    this.completionWaiters.delete(jobKey);
+            };
+            const finish = (completed) => {
+                if (settled)
+                    return;
+                settled = true;
+                waiter.cancelled = !completed;
+                cleanup();
+                resolve(completed);
+            };
+            const onAbort = () => finish(false);
             const waiter = {
-                resolve: () => {
-                    clearTimeout(timer);
-                    resolve(true);
-                },
+                resolve: () => finish(true),
+                cancel: () => finish(false),
                 cancelled: false,
             };
-            const timer = setTimeout(() => {
-                // Timeout - mark as cancelled and remove from map to prevent memory leak
-                waiter.cancelled = true;
-                // Remove the waiter from the array
-                const waiters = this.completionWaiters.get(jobKey);
-                if (waiters) {
-                    const index = waiters.indexOf(waiter);
-                    if (index !== -1) {
-                        waiters.splice(index, 1);
-                    }
-                    // Clean up empty arrays to free memory
-                    if (waiters.length === 0) {
-                        this.completionWaiters.delete(jobKey);
-                    }
-                }
-                resolve(false);
-            }, timeoutMs);
             // Add to waiters
             let waiters = this.completionWaiters.get(jobKey);
             if (!waiters) {
-                waiters = [];
+                waiters = new Set();
                 this.completionWaiters.set(jobKey, waiters);
             }
-            waiters.push(waiter);
+            waiters.add(waiter);
+            const timer = setTimeout(() => finish(false), timeoutMs);
+            signal?.addEventListener('abort', onAbort, { once: true });
+            if (signal?.aborted)
+                onAbort();
         });
     }
     /** Check if broadcast has any listeners - for batch optimizations */
@@ -108,40 +118,81 @@ export class EventsManager {
                 }
             }
         }
-        // Notify completion waiters for WaitJob - O(1) lookup
-        if (hasWaiters) {
-            const jobKey = String(event.jobId);
-            const waiters = this.completionWaiters.get(jobKey);
-            if (waiters) {
-                this.completionWaiters.delete(jobKey);
-                // Only notify non-cancelled waiters
-                for (const waiter of waiters) {
-                    if (!waiter.cancelled) {
-                        waiter.resolve();
-                    }
+        if (hasWaiters)
+            this.notifyCompletionWaiters(event);
+        if (hasWebhooks)
+            this.triggerWebhook(event);
+    }
+    /** Broadcast an ordered batch while allowing internal subscribers to persist once. */
+    broadcastBatch(events) {
+        if (events.length === 0)
+            return;
+        const hasSubscribers = this.subscribers.size > 0;
+        const hasWebhooks = this.webhookManager.hasEnabledWebhooks();
+        const hasWaiters = this.completionWaiters.size > 0;
+        if (!hasSubscribers && !hasWebhooks && !hasWaiters)
+            return;
+        if (hasSubscribers) {
+            for (const [subscriber, batchSubscriber] of this.batchSubscribers) {
+                if (!this.subscribers.has(subscriber))
+                    continue;
+                try {
+                    batchSubscriber(events);
+                }
+                catch {
+                    // Ignore subscriber errors.
                 }
             }
         }
-        // Trigger webhooks - only if there are enabled webhooks
-        if (hasWebhooks) {
-            const webhookEvent = this.mapEventToWebhook(event.eventType);
-            if (webhookEvent) {
-                this.webhookManager
-                    .trigger(webhookEvent, String(event.jobId), event.queue, {
-                    data: event.data,
-                    error: event.error,
-                })
-                    .catch((err) => {
-                    webhookLog.error('Webhook trigger failed', {
-                        event: webhookEvent,
-                        jobId: String(event.jobId),
-                        queue: event.queue,
-                        error: String(err),
-                    });
-                });
+        for (const event of events) {
+            if (hasSubscribers) {
+                for (const subscriber of this.subscribers) {
+                    if (this.batchSubscribers.has(subscriber))
+                        continue;
+                    try {
+                        subscriber(event);
+                    }
+                    catch {
+                        // Ignore subscriber errors and continue with the ordered batch.
+                    }
+                }
             }
+            if (hasWaiters && event.eventType === "completed" /* EventType.Completed */) {
+                this.notifyCompletionWaiters(event);
+            }
+            if (hasWebhooks)
+                this.triggerWebhook(event);
+        }
+    }
+    notifyCompletionWaiters(event) {
+        const jobKey = String(event.jobId);
+        const waiters = this.completionWaiters.get(jobKey);
+        if (!waiters)
+            return;
+        this.completionWaiters.delete(jobKey);
+        for (const waiter of waiters) {
+            if (!waiter.cancelled)
+                waiter.resolve();
         }
     }
+    triggerWebhook(event) {
+        const webhookEvent = this.mapEventToWebhook(event.eventType);
+        if (!webhookEvent)
+            return;
+        this.webhookManager
+            .trigger(webhookEvent, String(event.jobId), event.queue, {
+            data: event.data,
+            error: event.error,
+        })
+            .catch((err) => {
+            webhookLog.error('Webhook trigger failed', {
+                event: webhookEvent,
+                jobId: String(event.jobId),
+                queue: event.queue,
+                error: String(err),
+            });
+        });
+    }
     /** Map internal event type to webhook event */
     mapEventToWebhook(eventType) {
         switch (eventType) {

package/dist/application/operations/ackHelpers.d.ts

@@ -2,10 +2,7 @@
 import type { Job, JobId } from '../../domain/types/job';
 import type { BatchContext, ExtractedJob, FinalizeContext } from '../types/ack';
 export type { BatchContext, ExtractedJob, FinalizeContext } from '../types/ack';
-/**
- * Group job IDs by processing shard
- * Returns Map<shardIndex, jobIds[]>
- */
+/** Group job IDs by processing shard. */
 export declare function groupByProcShard(jobIds: JobId[]): Map<number, JobId[]>;
 /**
  * Group items by processing shard (with results)

package/dist/application/operations/ackHelpers.js

@@ -4,10 +4,30 @@ import { withWriteLock } from '../../shared/lock';
 import { shardIndex, processingShardIndex } from '../../shared/hash';
 import { throughputTracker } from '../throughputTracker';
 import { commitRemovedCompletion } from '../dependencyCompletions';
-/**
- * Group job IDs by processing shard
- * Returns Map<shardIndex, jobIds[]>
- */
+/** Batch only when no per-job durable result/removal ordering must be preserved. */
+function persistCompletedBatch(extractedJobs, ctx, includeResults, now) {
+    const storage = ctx.storage;
+    if (!storage || extractedJobs.length === 0)
+        return false;
+    if (extractedJobs.some(({ job, removeOnComplete }) => job.removeOnComplete || removeOnComplete === true) ||
+        (includeResults && extractedJobs.some(({ result }) => result !== undefined))) {
+        return false;
+    }
+    try {
+        storage.markCompletedBatch(extractedJobs.map(({ id: jobId, job }) => ({
+            jobId,
+            completedAt: now,
+            timeline: job.timeline.length < MAX_TIMELINE_ENTRIES
+                ? [...job.timeline, { state: 'completed', timestamp: now }]
+                : job.timeline,
+        })));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Group job IDs by processing shard. */
 export function groupByProcShard(jobIds) {
     const byProcShard = new Map();
     for (const jobId of jobIds) {
@@ -119,6 +139,7 @@ export function finalizeBatchAck(extractedJobs, ctx, includeResults) {
     const jobCount = extractedJobs.length;
     const needsBroadcast = ctx.needsBroadcast?.() ?? true;
     const hasPendingDeps = ctx.hasPendingDeps?.() ?? true;
+    const completionBatchPersisted = persistCompletedBatch(extractedJobs, ctx, includeResults, now);
     // Batch counter update
     ctx.totalCompleted.value += BigInt(jobCount);
     // Per-queue completed counter update
@@ -160,8 +181,9 @@ export function finalizeBatchAck(extractedJobs, ctx, includeResults) {
             // 2. Update job index and store job data for completed listing
             ctx.jobIndex.set(jobId, { type: 'completed', queueName: job.queue });
             ctx.completedJobsData.set(jobId, job);
-            if (hasStorage)
+            if (hasStorage && !completionBatchPersisted) {
                 storage.markCompleted(jobId, now, job.timeline);
+            }
             // 3. Mark as completed LAST - this is the signal other threads wait for
             ctx.completedJobs.add(jobId);
         }
@@ -180,15 +202,18 @@ export function finalizeBatchAck(extractedJobs, ctx, includeResults) {
     }
     // Broadcast events
     if (needsBroadcast) {
-        for (let i = 0; i < jobCount; i++) {
-            const { id: jobId, job, result } = extractedJobs[i];
-            ctx.broadcast({
-                eventType: 'completed',
-                queue: job.queue,
-                jobId,
-                timestamp: now,
-                data: includeResults ? result : undefined,
-            });
+        const events = extractedJobs.map(({ id: jobId, job, result }) => ({
+            eventType: 'completed',
+            queue: job.queue,
+            jobId,
+            timestamp: now,
+            data: includeResults ? result : undefined,
+        }));
+        if (ctx.broadcastBatch)
+            ctx.broadcastBatch(events);
+        else {
+            for (const event of events)
+                ctx.broadcast(event);
         }
     }
     // Notify completions

package/dist/application/operations/flowPush.js

@@ -29,6 +29,7 @@ function assertIdsAvailable(batch, ctx) {
 function prepareJobs(batch, ctx, now) {
     return batch.jobs.map((planned) => {
         const job = createJob(planned.id, planned.queue, planned.input, now);
+        ctx.shards[shardIndex(planned.queue)].assignGroupFifoOrder(job);
         job.timeline.push({ state: initialJobState(job, ctx, now), timestamp: now });
         return job;
     });

package/dist/application/operations/flowValidation.js

@@ -1,3 +1,4 @@
+import { validateGroupId } from '../../domain/types/group';
 import { normalizeJobPayload } from '../../domain/types/job';
 import { validateFlowTopology } from './flowTopologyValidation';
 const MAX_FLOW_JOBS = 10_000;
@@ -52,10 +53,9 @@ function validateOptions(input) {
             throw new Error(`${name} must be a boolean`);
         }
     }
-    if (input.groupId !== undefined &&
-        (typeof input.groupId !== 'string' || input.groupId.length > 256)) {
-        throw new Error('groupId must be a string of at most 256 characters');
-    }
+    const groupError = validateGroupId(input.groupId);
+    if (groupError)
+        throw new Error(groupError);
     if (input.tags !== undefined &&
         (!Array.isArray(input.tags) ||
             input.tags.some((tag) => typeof tag !== 'string' || tag.length > 256))) {

package/dist/application/operations/jobManagement.d.ts

@@ -26,6 +26,10 @@ export interface JobManagementContext {
     eventsManager: EventsManager;
     repeatChain?: Map<JobId, JobId>;
     dependencyResults: DependencyResultTracker;
+    customIdMap: {
+        get(id: string): JobId | undefined;
+        delete(id: string): boolean;
+    };
     depCompletions?: DependencyCompletionTracker;
     maxDependencyCompletions: number;
 }

package/dist/application/operations/jobMoveOperations.js

@@ -75,7 +75,7 @@ export async function discardJob(jobId, ctx) {
     const validJob = job;
     const idx = shardIndex(validJob.queue);
     const fromProcessing = location.type === 'processing';
-    const entry = await withWriteLock(ctx.shardLocks[idx], () => {
+    await withWriteLock(ctx.shardLocks[idx], () => {
         const shard = ctx.shards[idx];
         if (fromProcessing) {
             shard.releaseJobResources(validJob.queue, validJob.uniqueKey, validJob.groupId, validJob.id);
@@ -86,9 +86,14 @@ export async function discardJob(jobId, ctx) {
         }
         const dlqEntry = shard.addToDlq(validJob);
         ctx.jobIndex.set(jobId, { type: 'dlq', queueName: validJob.queue });
-        return dlqEntry;
+        // SQLite writes are synchronous. Keeping them in this critical section
+        // prevents a concurrent permanent removal from racing a late DLQ insert.
+        ctx.storage?.saveDlqEntry(dlqEntry);
+        ctx.storage?.deleteJob(jobId);
+        ctx.dependencyResults.releaseConsumer(jobId);
+        if (validJob.customId && ctx.customIdMap.get(validJob.customId) === jobId) {
+            ctx.customIdMap.delete(validJob.customId);
+        }
     });
-    ctx.storage?.saveDlqEntry(entry);
-    ctx.storage?.deleteJob(jobId);
     return true;
 }

package/dist/application/operations/pull.d.ts

@@ -3,13 +3,18 @@
  * Job pull logic with timeout support
  */
 import type { Job } from '../../domain/types/job';
+import { type GroupPullOptions } from '../../domain/types/group';
 import { type PullContext } from './pullStateTransition';
 export type { PullContext } from './pullStateTransition';
+interface PullRequestOptions {
+    signal?: AbortSignal;
+    group?: GroupPullOptions;
+}
 /**
  * Pull next job from queue
  */
-export declare function pullJob(queue: string, timeoutMs: number, ctx: PullContext, signal?: AbortSignal): Promise<Job | null>;
+export declare function pullJob(queue: string, timeoutMs: number, ctx: PullContext, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<Job | null>;
 /**
  * Pull multiple jobs from queue
  */
-export declare function pullJobBatch(queue: string, count: number, timeoutMs: number, ctx: PullContext, signal?: AbortSignal): Promise<Job[]>;
+export declare function pullJobBatch(queue: string, count: number, timeoutMs: number, ctx: PullContext, options?: PullRequestOptions): Promise<Job[]>;