bunqueue 2.8.40 → 2.8.42

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

@@ -2,30 +2,9 @@
  * Pull Operations
  * Job pull logic with timeout support
  */
-import { type Job, type JobId } from '../../domain/types/job';
-import type { JobLocation, EventType } from '../../domain/types/queue';
-import type { Shard } from '../../domain/queue/shard';
-import type { SqliteStorage } from '../../infrastructure/persistence/sqlite';
-import type { RWLock } from '../../shared/lock';
-/** Pull operation context */
-export interface PullContext {
-    storage: SqliteStorage | null;
-    shards: Shard[];
-    shardLocks: RWLock[];
-    processingShards: Map<JobId, Job>[];
-    processingLocks: RWLock[];
-    jobIndex: Map<JobId, JobLocation>;
-    totalPulled: {
-        value: bigint;
-    };
-    broadcast: (event: {
-        eventType: EventType;
-        queue: string;
-        jobId: JobId;
-        timestamp: number;
-    }) => void;
-    dashboardEmit?: (event: string, data: Record<string, unknown>) => void;
-}
+import type { Job } from '../../domain/types/job';
+import { type PullContext } from './pullStateTransition';
+export type { PullContext } from './pullStateTransition';
 /**
  * Pull next job from queue
  */

package/dist/application/operations/pull.js

@@ -2,125 +2,11 @@
  * Pull Operations
  * Job pull logic with timeout support
  */
-import { isExpired, isReady, MAX_TIMELINE_ENTRIES, } from '../../domain/types/job';
 import { withWriteLock } from '../../shared/lock';
 import { shardIndex, processingShardIndex } from '../../shared/hash';
 import { latencyTracker } from '../latencyTracker';
 import { throughputTracker } from '../throughputTracker';
-/**
- * Dequeue the highest-ranked eligible job without letting a delayed or
- * group-blocked heap root stall unrelated work.
- *
- * The priority heap cannot encode time-varying readiness or active-group
- * membership in its comparator. Temporarily park ineligible roots, select the
- * first eligible entry (therefore the best eligible entry in heap order), and
- * restore every parked job before leaving the shard critical section. Parked
- * jobs remain logically queued throughout: their shard counters and jobIndex
- * entries are deliberately untouched.
- *
- * Complexity is O((k + 1) log n) time and O(k) scratch space, where k is the
- * number of higher-ranked ineligible jobs skipped. A separate delayed heap and
- * per-group eligible-head heap can reduce this to O(log n), but this scan keeps
- * the existing queue representation and state transitions intact.
- */
-function tryDequeueNextJob(shard, queue, now, ctx) {
-    const q = shard.getQueue(queue);
-    const parked = [];
-    let nextRunAt = null;
-    try {
-        while (true) {
-            const job = q.peek();
-            if (!job)
-                return { status: 'stop', nextRunAt };
-            // Expired entries are not parked: they are genuinely removed from the
-            // logical queue and therefore update counters/index exactly once.
-            if (isExpired(job, now)) {
-                // Delete persistence before mutating the in-memory indexes. deleteJob
-                // also removes a pending buffered INSERT, so the expired job cannot be
-                // flushed after this pull or resurrect during crash recovery. This is
-                // synchronous and therefore keeps the shard critical section await-free.
-                ctx.storage?.deleteJob(job.id);
-                q.pop();
-                shard.decrementQueued(job.id);
-                ctx.jobIndex.delete(job.id);
-                ctx.dashboardEmit?.('job:expired', {
-                    queue,
-                    jobId: String(job.id),
-                    ttl: job.ttl,
-                    age: now - job.createdAt,
-                });
-                continue;
-            }
-            if (!isReady(job, now)) {
-                const delayed = q.pop();
-                if (delayed)
-                    parked.push(delayed);
-                nextRunAt = nextRunAt === null ? job.runAt : Math.min(nextRunAt, job.runAt);
-                continue;
-            }
-            if (job.groupId && shard.isGroupActive(queue, job.groupId)) {
-                const blocked = q.pop();
-                if (blocked)
-                    parked.push(blocked);
-                continue;
-            }
-            // Check capacity only after proving that an eligible job exists. Check
-            // concurrency first because that slot can be returned if rate limiting
-            // rejects; rate-limit tokens have no rollback operation.
-            if (!shard.tryAcquireConcurrency(queue)) {
-                ctx.dashboardEmit?.('concurrency:rejected', { queue });
-                return { status: 'stop', nextRunAt };
-            }
-            if (!shard.tryAcquireRateLimit(queue)) {
-                shard.releaseConcurrency(queue);
-                ctx.dashboardEmit?.('ratelimit:rejected', { queue });
-                return { status: 'stop', nextRunAt };
-            }
-            // Dequeue and update. q.peek() and q.pop() are synchronous under the
-            // shard write lock, so pop returns the same eligible entry selected above.
-            const dequeued = q.pop();
-            if (!dequeued) {
-                shard.releaseConcurrency(queue);
-                return { status: 'stop', nextRunAt };
-            }
-            shard.decrementQueued(dequeued.id);
-            if (dequeued.groupId) {
-                shard.activateGroup(queue, dequeued.groupId);
-            }
-            dequeued.startedAt = now;
-            dequeued.lastHeartbeat = now;
-            if (dequeued.timeline.length < MAX_TIMELINE_ENTRIES) {
-                dequeued.timeline.push({ state: 'active', timestamp: now });
-            }
-            // Make the queue -> processing transition atomic for observers. From the
-            // pop above, the job is no longer findable in the shard queue, so a
-            // jobIndex entry still saying 'queue' would make getJob/getJobState return
-            // a false null/'unknown' for an existing job (JOB -> null -> JOB(active)
-            // flicker), and cleanOrphanedJobIndex would even drop its index entry.
-            // Insert into processingShards and flip the index HERE, in the same
-            // synchronous critical section as the pop (the caller holds the shard
-            // write lock; JS is single-threaded, so no other task can interleave).
-            // Writing processingShards without its RWLock is safe: until this
-            // statement the index said 'queue', so no id-targeted critical section
-            // (ack/fail/discard operate only on ids they find as 'processing') can be
-            // mid-operation on this id; a sync Map.set cannot corrupt a paused
-            // critical section; and lock-free sync access to processingShards is
-            // established practice (stallDetection phases 1/2, collectActiveJobs,
-            // getJobProgress). Acquiring the async RWLock here would instead hold the
-            // hot shard write lock across an await.
-            const procIdx = processingShardIndex(dequeued.id);
-            ctx.processingShards[procIdx].set(dequeued.id, dequeued);
-            ctx.jobIndex.set(dequeued.id, { type: 'processing', shardIdx: procIdx });
-            return { status: 'job', job: dequeued };
-        }
-    }
-    finally {
-        // Restore only the priority-queue membership. The logical queue counters,
-        // temporal index and global jobIndex never changed for parked entries.
-        for (const parkedJob of parked)
-            q.push(parkedJob);
-    }
-}
+import { createDequeueScan, requeueJob, restoreParkedJobs, tryDequeueNextJob, } from './pullStateTransition';
 /** Wait until either a notification arrives, the next delay matures, or the pull deadline. */
 async function waitForNextCandidate(options) {
     const { shard, queue, deadline, now, nextRunAt, signal } = options;
@@ -175,46 +61,6 @@ function finalizeProcessingBatch(jobs, queue, ctx) {
     }
     return delivered;
 }
-/**
- * Requeue a job whose handoff to the worker failed after dequeue.
- * The dequeue critical section moved the job to processingShards and flipped
- * jobIndex to 'processing'; this restores both, keeping the same atomicity
- * rule: the job becomes findable in the queue (push + index flip in ONE
- * shard-lock section) BEFORE the processing entry is dropped, so a reader
- * never sees a location that misses. Lock order shard -> processing matches
- * the documented hierarchy.
- */
-async function requeueJob(job, queue, idx, ctx) {
-    const procIdx = processingShardIndex(job.id);
-    let requeued = false;
-    await withWriteLock(ctx.shardLocks[idx], () => {
-        // A management op (discardJob, moveJobToDelayed) may have claimed the job
-        // from processingShards after the failed handoff; it owns the job now.
-        if (!ctx.processingShards[procIdx].has(job.id))
-            return;
-        const shard = ctx.shards[idx];
-        if (job.groupId)
-            shard.releaseGroup(queue, job.groupId);
-        shard.releaseConcurrency(queue);
-        // Reset job state (was modified in tryDequeueNextJob)
-        job.startedAt = null;
-        shard.getQueue(queue).push(job);
-        shard.incrementQueued(job.id, false, job.createdAt, queue, job.runAt);
-        ctx.jobIndex.set(job.id, { type: 'queue', shardIdx: idx, queueName: queue });
-        shard.notify(queue);
-        requeued = true;
-    });
-    if (!requeued)
-        return;
-    await withWriteLock(ctx.processingLocks[procIdx], () => {
-        // A concurrent pull may have re-popped the job between the two lock
-        // sections and flipped the index back to 'processing'; do not delete the
-        // (re-inserted, same-object) entry out from under it.
-        if (ctx.jobIndex.get(job.id)?.type !== 'processing') {
-            ctx.processingShards[procIdx].delete(job.id);
-        }
-    });
-}
 /**
  * Pull next job from queue
  */
@@ -276,10 +122,16 @@ async function tryPullFromShard(queue, idx, ctx, signal) {
             return { job: null, nextRunAt: null };
         }
         const now = Date.now();
-        const result = tryDequeueNextJob(shard, queue, now, ctx);
-        return result.status === 'job'
-            ? { job: result.job, nextRunAt: null }
-            : { job: null, nextRunAt: result.nextRunAt };
+        const scan = createDequeueScan();
+        try {
+            const result = tryDequeueNextJob(shard, queue, now, ctx, scan);
+            return result.status === 'job'
+                ? { job: result.job, nextRunAt: null }
+                : { job: null, nextRunAt: scan.nextRunAt };
+        }
+        finally {
+            restoreParkedJobs(shard, queue, scan);
+        }
     });
 }
 /**
@@ -352,17 +204,21 @@ async function tryPullBatchFromShard(queue, idx, count, ctx, signal) {
         if (state.paused)
             return { jobs, nextRunAt: null };
         const now = Date.now();
-        let nextRunAt = null;
-        while (jobs.length < count) {
-            const result = tryDequeueNextJob(shard, queue, now, ctx);
-            if (result.status === 'job') {
-                jobs.push(result.job);
-            }
-            else {
-                nextRunAt = result.nextRunAt;
-                break;
+        const scan = createDequeueScan();
+        try {
+            while (jobs.length < count) {
+                const result = tryDequeueNextJob(shard, queue, now, ctx, scan);
+                if (result.status === 'job') {
+                    jobs.push(result.job);
+                }
+                else {
+                    break;
+                }
             }
+            return { jobs, nextRunAt: scan.nextRunAt };
+        }
+        finally {
+            restoreParkedJobs(shard, queue, scan);
         }
-        return { jobs, nextRunAt };
     });
 }

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

@@ -0,0 +1,50 @@
+/**
+ * Atomic queue-state transitions used by single and batch pull orchestration.
+ */
+import type { Shard } from '../../domain/queue/shard';
+import { type Job, type JobId } from '../../domain/types/job';
+import type { EventType, JobLocation } from '../../domain/types/queue';
+import type { SqliteStorage } from '../../infrastructure/persistence/sqlite';
+import type { RWLock } from '../../shared/lock';
+/** Dependencies shared by the single and batch pull paths. */
+export interface PullContext {
+    storage: SqliteStorage | null;
+    shards: Shard[];
+    shardLocks: RWLock[];
+    processingShards: Map<JobId, Job>[];
+    processingLocks: RWLock[];
+    jobIndex: Map<JobId, JobLocation>;
+    totalPulled: {
+        value: bigint;
+    };
+    broadcast: (event: {
+        eventType: EventType;
+        queue: string;
+        jobId: JobId;
+        timestamp: number;
+    }) => void;
+    dashboardEmit?: (event: string, data: Record<string, unknown>) => void;
+}
+export interface DequeueScan {
+    parked: Job[];
+    nextRunAt: number | null;
+}
+export type DequeueResult = {
+    status: 'job';
+    job: Job;
+} | {
+    status: 'stop';
+};
+export declare function createDequeueScan(): DequeueScan;
+/** Restore physical heap membership without changing logical queue state. */
+export declare function restoreParkedJobs(shard: Shard, queue: string, scan: DequeueScan): void;
+/**
+ * Remove the best eligible job while retaining ineligible roots in `scan`.
+ *
+ * A batch reuses one scan, because readiness cannot change while the synchronous
+ * shard critical section is held: time is fixed and active FIFO groups only
+ * grow. Its parked jobs therefore need to be restored only once after the batch.
+ */
+export declare function tryDequeueNextJob(shard: Shard, queue: string, now: number, ctx: PullContext, scan: DequeueScan): DequeueResult;
+/** Restore a dequeued job when its handoff to the worker cannot complete. */
+export declare function requeueJob(job: Job, queue: string, idx: number, ctx: PullContext): Promise<void>;

package/dist/application/operations/pullStateTransition.js

@@ -0,0 +1,114 @@
+/**
+ * Atomic queue-state transitions used by single and batch pull orchestration.
+ */
+import { isExpired, isReady, MAX_TIMELINE_ENTRIES, } from '../../domain/types/job';
+import { processingShardIndex } from '../../shared/hash';
+import { withWriteLock } from '../../shared/lock';
+export function createDequeueScan() {
+    return { parked: [], nextRunAt: null };
+}
+/** Restore physical heap membership without changing logical queue state. */
+export function restoreParkedJobs(shard, queue, scan) {
+    const priorityQueue = shard.getQueue(queue);
+    for (const job of scan.parked)
+        priorityQueue.push(job);
+    scan.parked.length = 0;
+}
+/**
+ * Remove the best eligible job while retaining ineligible roots in `scan`.
+ *
+ * A batch reuses one scan, because readiness cannot change while the synchronous
+ * shard critical section is held: time is fixed and active FIFO groups only
+ * grow. Its parked jobs therefore need to be restored only once after the batch.
+ */
+export function tryDequeueNextJob(shard, queue, now, ctx, scan) {
+    const priorityQueue = shard.getQueue(queue);
+    while (true) {
+        const job = priorityQueue.peek();
+        if (!job)
+            return { status: 'stop' };
+        if (isExpired(job, now)) {
+            // Persistence is removed first so a failed durable delete leaves the
+            // in-memory job available for a later attempt.
+            ctx.storage?.deleteJob(job.id);
+            priorityQueue.pop();
+            shard.decrementQueued(job.id);
+            ctx.jobIndex.delete(job.id);
+            ctx.dashboardEmit?.('job:expired', {
+                queue,
+                jobId: String(job.id),
+                ttl: job.ttl,
+                age: now - job.createdAt,
+            });
+            continue;
+        }
+        if (!isReady(job, now)) {
+            const delayed = priorityQueue.pop();
+            if (delayed)
+                scan.parked.push(delayed);
+            scan.nextRunAt = scan.nextRunAt === null ? job.runAt : Math.min(scan.nextRunAt, job.runAt);
+            continue;
+        }
+        if (job.groupId && shard.isGroupActive(queue, job.groupId)) {
+            const blocked = priorityQueue.pop();
+            if (blocked)
+                scan.parked.push(blocked);
+            continue;
+        }
+        // Capacity is consumed only after an eligible job has been found.
+        if (!shard.tryAcquireConcurrency(queue)) {
+            ctx.dashboardEmit?.('concurrency:rejected', { queue });
+            return { status: 'stop' };
+        }
+        if (!shard.tryAcquireRateLimit(queue)) {
+            shard.releaseConcurrency(queue);
+            ctx.dashboardEmit?.('ratelimit:rejected', { queue });
+            return { status: 'stop' };
+        }
+        const dequeued = priorityQueue.pop();
+        if (!dequeued) {
+            shard.releaseConcurrency(queue);
+            return { status: 'stop' };
+        }
+        shard.decrementQueued(dequeued.id);
+        if (dequeued.groupId)
+            shard.activateGroup(queue, dequeued.groupId);
+        dequeued.startedAt = now;
+        dequeued.lastHeartbeat = now;
+        if (dequeued.timeline.length < MAX_TIMELINE_ENTRIES) {
+            dequeued.timeline.push({ state: 'active', timestamp: now });
+        }
+        // Queue -> processing is atomic for observers while the shard lock is held.
+        const procIdx = processingShardIndex(dequeued.id);
+        ctx.processingShards[procIdx].set(dequeued.id, dequeued);
+        ctx.jobIndex.set(dequeued.id, { type: 'processing', shardIdx: procIdx });
+        return { status: 'job', job: dequeued };
+    }
+}
+/** Restore a dequeued job when its handoff to the worker cannot complete. */
+export async function requeueJob(job, queue, idx, ctx) {
+    const procIdx = processingShardIndex(job.id);
+    let requeued = false;
+    await withWriteLock(ctx.shardLocks[idx], () => {
+        if (!ctx.processingShards[procIdx].has(job.id))
+            return;
+        const shard = ctx.shards[idx];
+        if (job.groupId)
+            shard.releaseGroup(queue, job.groupId);
+        shard.releaseConcurrency(queue);
+        job.startedAt = null;
+        shard.getQueue(queue).push(job);
+        shard.incrementQueued(job.id, false, job.createdAt, queue, job.runAt);
+        ctx.jobIndex.set(job.id, { type: 'queue', shardIdx: idx, queueName: queue });
+        shard.notify(queue);
+        requeued = true;
+    });
+    if (!requeued)
+        return;
+    await withWriteLock(ctx.processingLocks[procIdx], () => {
+        // A concurrent pull may already have moved the same object back to active.
+        if (ctx.jobIndex.get(job.id)?.type !== 'processing') {
+            ctx.processingShards[procIdx].delete(job.id);
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunqueue",
-  "version": "2.8.40",
+  "version": "2.8.42",
   "description": "High-performance job queue for Bun & AI agents. SQLite persistence, cron scheduling, priorities, retries, DLQ, webhooks, native MCP server. Zero external infrastructure.",
   "type": "module",
   "main": "dist/main.js",