bunqueue 2.8.58 → 2.8.60

package/README.md

@@ -67,6 +67,10 @@ docker run -d -p 6789:6789 -p 6790:6790 \
   ghcr.io/egeominotti/bunqueue:latest
 ```
 
+Release images also carry the exact package version. For reproducible
+deployments, pin `ghcr.io/egeominotti/bunqueue:2.8.60`; `latest` points to the
+same multi-arch image at release time.
+
 Then produce and process from the language you already use:
 
 ```bash
@@ -85,7 +89,7 @@ new Worker('emails', async (job) => ({ sent: true }), { concurrency: 10 });
 Python, PHP, Go, Rust and Elixir clients speak the same protocol — see
 [One Queue, Any Language](#one-queue-any-language-sdks).
 
-> Only the server and embedded mode are **Bun-only** (`bun >= 1.3.9`,
+> Only the server and embedded mode are **Bun-only** (`bun >= 1.4.0`,
 > [bun.sh](https://bun.sh)); producers and workers can run anywhere.
 
 [Quick Start guide →](https://bunqueue.dev/guide/quickstart/)

package/dist/application/dlqManager.d.ts

@@ -19,7 +19,7 @@ export interface DlqContext {
     };
     storage: SqliteStorage | null;
 }
-export { processAutoRetry, retryDlqByFilter, retryDlqJob, retryDlqJobs, } from './dlqRetry';
+export { processAutoRetry, retryDlqByFilter, retryDlqJob, retryDlqJobs } from './dlqRetry';
 /** Get jobs from DLQ (backward compatible) */
 export declare function getDlqJobs(queue: string, ctx: DlqContext, count?: number): Job[];
 /** Get DLQ entries with full metadata */

package/dist/application/dlqManager.js

@@ -5,7 +5,7 @@
 import { MAX_TIMELINE_ENTRIES } from '../domain/types/job';
 import { setDlqRetryState } from '../domain/types/dlq';
 import { shardIndex } from '../shared/hash';
-export { processAutoRetry, retryDlqByFilter, retryDlqJob, retryDlqJobs, } from './dlqRetry';
+export { processAutoRetry, retryDlqByFilter, retryDlqJob, retryDlqJobs } from './dlqRetry';
 /** Get jobs from DLQ (backward compatible) */
 export function getDlqJobs(queue, ctx, count) {
     const idx = shardIndex(queue);

package/dist/application/lockManager.js

@@ -78,7 +78,7 @@ export async function checkExpiredLocks(ctx) {
  * Process a single expired lock (called with both locks already held)
  * Lock hierarchy already satisfied: shardLock -> processingLock held by caller
  */
-// biome-ignore lint/complexity/useMaxParams: lock-processing inner fn needs the full lock context (7 params)
+// oxlint-disable-next-line max-params -- lock-processing inner fn needs the full lock context (7 params)
 function processExpiredLockInner(jobId, lock, job, shardIdx, procIdx, ctx, now) {
     const shard = ctx.shards[shardIdx];
     const queue = shard.getQueue(job.queue);

package/dist/application/queue-manager/ack.js

@@ -126,7 +126,7 @@ export class QueueManagerAck extends QueueManagerDelivery {
                 this.syncJobTimeout(item.id);
         }
     }
-    // biome-ignore lint/complexity/useMaxParams: public compatibility signature carries removal policy.
+    // oxlint-disable-next-line max-params -- public compatibility signature carries removal policy
     async fail(jobId, error, token, unrecoverable = false, stack, removeOnFail) {
         return this.failWithOptions(jobId, error, token, { unrecoverable, stack, removeOnFail });
     }

package/dist/application/queue-manager/delivery.js

@@ -40,7 +40,7 @@ export class QueueManagerDelivery extends QueueManagerState {
             this.scheduleJobTimeout(job);
         return jobs;
     }
-    // biome-ignore lint/complexity/useMaxParams: public API includes cancellation and lock policy
+    // oxlint-disable-next-line max-params -- public API includes cancellation and lock policy
     async pullBatchWithLock(queue, count, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL, signal) {
         const jobs = await pullJobBatch(queue, count, timeoutMs, this.contextFactory.getPullContext(), signal);
         const tokens = jobs.map((job) => lockMgr.createLock(job.id, owner, this.contextFactory.getLockContext(), lockTtl) ?? '');

package/dist/application/statsManager.d.ts

@@ -3,7 +3,7 @@
  * Provides system metrics and memory compaction utilities
  */
 import type { StatsContext } from './types';
-export { getAllQueueJobCounts, getPerQueueStats, getQueueJobCounts, } from './queueStatsAggregator';
+export { getAllQueueJobCounts, getPerQueueStats, getQueueJobCounts } from './queueStatsAggregator';
 export type { PerQueueStats, QueueJobCounts } from './queueStatsAggregator';
 export interface QueueStats {
     waiting: number;

package/dist/application/statsManager.js

@@ -3,7 +3,7 @@
  * Provides system metrics and memory compaction utilities
  */
 import { SHARD_COUNT } from '../shared/hash';
-export { getAllQueueJobCounts, getPerQueueStats, getQueueJobCounts, } from './queueStatsAggregator';
+export { getAllQueueJobCounts, getPerQueueStats, getQueueJobCounts } from './queueStatsAggregator';
 /**
  * Get queue statistics - uses running counters + priority scan
  */

package/dist/client/events.js

@@ -41,11 +41,11 @@ export class QueueEvents extends EventEmitter {
         this.queueKey = (options.prefixKey ?? '') + name;
         this.start();
     }
-    // biome-ignore lint/suspicious/noExplicitAny: EventEmitter's fallback overload requires any[].
+    // oxlint-disable-next-line typescript/no-explicit-any -- EventEmitter's fallback overload requires any[]
     on(event, listener) {
         return super.on(event, listener);
     }
-    // biome-ignore lint/suspicious/noExplicitAny: EventEmitter's fallback overload requires any[].
+    // oxlint-disable-next-line typescript/no-explicit-any -- EventEmitter's fallback overload requires any[]
     once(event, listener) {
         return super.once(event, listener);
     }

package/dist/client/flow.js

@@ -129,7 +129,6 @@ export class FlowProducer extends EventEmitter {
         return plan.roots.map((root) => this.buildPlannedNode(root, snapshotsById));
     }
     /** Get a flow tree starting from a job (BullMQ v5 compatible). */
-    // biome-ignore lint/suspicious/useAwait: preserves the public Promise return contract.
     async getFlow(opts) {
         return readFlow({
             embedded: this.embedded,

package/dist/client/queue/operations/add/single.js

@@ -57,7 +57,7 @@ export async function add(context, jobName, data, options = {}) {
             updateProgress: async (id, progress, message) => {
                 await manager.updateProgress(jobId(id), progress, message);
             },
-            // biome-ignore lint/suspicious/useAwait: public callback contract is asynchronous.
+            // oxlint-disable-next-line typescript/require-await -- public callback contract is asynchronous
             log: async (id, message) => {
                 manager.addLog(jobId(id), message);
             },

package/dist/client/sandboxed/runtime/state.js

@@ -3,11 +3,11 @@ import { getSharedManager } from '../../manager';
 import { getSharedPool } from '../../tcpPool';
 import { createEmbeddedOps, createTcpOps } from '../queueOps';
 export class SandboxedState extends EventEmitter {
-    // biome-ignore lint/suspicious/noExplicitAny: EventEmitter's fallback listener is intentionally untyped
+    // oxlint-disable-next-line typescript/no-explicit-any -- EventEmitter's fallback listener is intentionally untyped
     on(event, listener) {
         return super.on(event, listener);
     }
-    // biome-ignore lint/suspicious/noExplicitAny: EventEmitter's fallback listener is intentionally untyped
+    // oxlint-disable-next-line typescript/no-explicit-any -- EventEmitter's fallback listener is intentionally untyped
     once(event, listener) {
         return super.once(event, listener);
     }

package/dist/client/tcp/connection.d.ts

@@ -1,4 +1,4 @@
 /** Stable low-level TCP connection import surface. */
 export { CommandQueue } from './commandQueue';
-export { buildClientTls, createConnection, tlsRequiresVerification, } from './transport';
+export { buildClientTls, createConnection, tlsRequiresVerification } from './transport';
 export type { ConnectionEvents, ConnectionResult, ConnectionTarget } from './transport';

package/dist/client/tcp/connection.js

@@ -1,3 +1,3 @@
 /** Stable low-level TCP connection import surface. */
 export { CommandQueue } from './commandQueue';
-export { buildClientTls, createConnection, tlsRequiresVerification, } from './transport';
+export { buildClientTls, createConnection, tlsRequiresVerification } from './transport';

package/dist/client/tcp/runtime/state.js

@@ -5,11 +5,11 @@ import { ReconnectManager } from '../reconnect';
 import { DEFAULT_CONNECTION } from '../types';
 /** Shared TCP client state and event contract. */
 export class TcpClientState extends EventEmitter {
-    // biome-ignore lint/suspicious/noExplicitAny: EventEmitter's fallback overload requires any[]
+    // oxlint-disable-next-line typescript/no-explicit-any -- EventEmitter's fallback overload requires any[]
     on(event, listener) {
         return super.on(event, listener);
     }
-    // biome-ignore lint/suspicious/noExplicitAny: EventEmitter's fallback overload requires any[]
+    // oxlint-disable-next-line typescript/no-explicit-any -- EventEmitter's fallback overload requires any[]
     once(event, listener) {
         return super.once(event, listener);
     }

package/dist/client/types/metrics.d.ts

@@ -1 +1 @@
-export type { QueueMetrics, QueueMetricsMeta, QueueMetricType, } from '../../domain/types/metrics';
+export type { QueueMetrics, QueueMetricsMeta, QueueMetricType } from '../../domain/types/metrics';

package/dist/client/worker/runtime/control.js

@@ -152,7 +152,6 @@ export class WorkerControl extends WorkerState {
     async startStalledCheckTimer() {
         // No-op for API compatibility; stall detection is automatic.
     }
-    // biome-ignore lint/suspicious/useAwait: public compatibility contract is asynchronous
     async delay(milliseconds = 0, abortController) {
         if (milliseconds <= 0)
             return;

package/dist/client/worker/runtime/lifecycle.js

@@ -2,7 +2,6 @@ import { jobId } from '../../../domain/types/job';
 import { getSharedManager } from '../../manager';
 import { WorkerManual } from './manual';
 export class WorkerLifecycle extends WorkerManual {
-    // biome-ignore lint/suspicious/useAwait: preserves the public async close contract
     async close(force = false) {
         if (this.closed)
             return;

package/dist/client/worker/runtime/state.js

@@ -46,15 +46,15 @@ export class WorkerState extends EventEmitter {
     lastDrainedEmit = 0;
     stalledUnsubscribe = null;
     stalledSubscription = null;
-    // biome-ignore lint/suspicious/noExplicitAny: EventEmitter's fallback listener is intentionally untyped
+    // oxlint-disable-next-line typescript/no-explicit-any -- EventEmitter's fallback listener is intentionally untyped
     on(event, listener) {
         return super.on(event, listener);
     }
-    // biome-ignore lint/suspicious/noExplicitAny: EventEmitter's fallback listener is intentionally untyped
+    // oxlint-disable-next-line typescript/no-explicit-any -- EventEmitter's fallback listener is intentionally untyped
     once(event, listener) {
         return super.once(event, listener);
     }
-    // biome-ignore lint/suspicious/noExplicitAny: EventEmitter's fallback listener is intentionally untyped
+    // oxlint-disable-next-line typescript/no-explicit-any -- EventEmitter's fallback listener is intentionally untyped
     off(event, listener) {
         return super.off(event, listener);
     }

package/dist/client/workflow/compensationChild.d.ts

@@ -11,6 +11,7 @@ export interface ChildUnwindRequest {
     emitter: WorkflowEmitter | null;
     workflows?: Map<string, Workflow>;
     retryFailed?: boolean;
+    assertActive: () => void;
 }
 export type ChildUnwind = (request: ChildUnwindRequest) => Promise<'ran' | LostCompensationClaim>;
 export interface UnwindChildRequest {
@@ -20,6 +21,7 @@ export interface UnwindChildRequest {
     workflows?: Map<string, Workflow>;
     runChild: ChildUnwind;
     retryFailed?: boolean;
+    assertActive: () => void;
 }
 /** Run the child workflow's own unwind and propagate every uncertain outcome. */
 export declare function unwindChild(request: UnwindChildRequest): Promise<void>;

package/dist/client/workflow/compensationChild.js

@@ -2,7 +2,8 @@
 import { isLive } from './admission';
 /** Run the child workflow's own unwind and propagate every uncertain outcome. */
 export async function unwindChild(request) {
-    const { record, store, emitter, workflows, runChild, retryFailed } = request;
+    const { record, store, emitter, workflows, runChild, retryFailed, assertActive } = request;
+    assertActive();
     const childId = record.childExecutionId;
     if (!childId)
         throw new Error('sub-workflow record carries no child execution id');
@@ -29,6 +30,7 @@ export async function unwindChild(request) {
         emitter,
         workflows,
         retryFailed,
+        assertActive,
     });
     if (outcome !== 'ran') {
         throw new Error(`child "${child.workflowName}" (${childId}) is being rolled back by another driver; ` +

package/dist/client/workflow/compensationPass.d.ts

@@ -12,5 +12,6 @@ export interface UnwindPass {
     eligible: [string, StepRecord][];
     workflows?: Map<string, Workflow>;
     retryFailed?: boolean;
+    assertActive: () => void;
 }
 export declare function unwind(pass: UnwindPass, runChild: ChildUnwind): Promise<void>;

package/dist/client/workflow/compensationPass.js

@@ -1,14 +1,16 @@
 /** One checkpointed compensation pass. */
 import { compensationContext, settle } from './compensationSupport';
 import { unwindChild } from './compensationChild';
+import { isWorkflowExecutionClosed } from './executionFence';
 import { describeError } from './identity';
 import { buildContext, findStepDef, runWithTimeout } from './runner';
 import { decideUnwindAction } from './unwindPlan';
 export async function unwind(pass, runChild) {
-    const { exec, wf, store, emitter, eligible, workflows, retryFailed } = pass;
+    const { exec, wf, store, emitter, eligible, workflows, retryFailed, assertActive } = pass;
     const baseCtx = buildContext(exec);
     let haltedAt = null;
     let writeFailure;
+    assertActive();
     exec.state = 'compensating';
     try {
         store.update(exec);
@@ -20,8 +22,10 @@ export async function unwind(pass, runChild) {
     }
     if (writeFailure === undefined) {
         emitter?.emitWorkflow('workflow:compensating', exec.id, exec.workflowName, 'compensating');
+        assertActive();
     }
     for (const [name, record] of eligible) {
+        assertActive();
         if (writeFailure !== undefined)
             break;
         const action = decideUnwindAction(wf, name, record, haltedAt !== null, retryFailed);
@@ -39,12 +43,22 @@ export async function unwind(pass, runChild) {
             emitter?.emitStep('compensation:failed', exec.id, exec.workflowName, name, {
                 error: 'step no longer declared',
             });
+            assertActive();
             continue;
         }
         emitter?.emitStep('compensation:started', exec.id, exec.workflowName, name);
+        assertActive();
         try {
             if (action.kind === 'unwind-child') {
-                await unwindChild({ record, store, emitter, workflows, runChild, retryFailed });
+                await unwindChild({
+                    record,
+                    store,
+                    emitter,
+                    workflows,
+                    runChild,
+                    retryFailed,
+                    assertActive,
+                });
             }
             else {
                 const def = findStepDef(wf, name);
@@ -59,6 +73,8 @@ export async function unwind(pass, runChild) {
             emitter?.emitStep('compensation:completed', exec.id, exec.workflowName, name);
         }
         catch (error) {
+            if (isWorkflowExecutionClosed(error))
+                throw error;
             const message = describeError(error);
             settle(record, 'compensation-failed', message);
             emitter?.emitStep('compensation:failed', exec.id, exec.workflowName, name, {

package/dist/client/workflow/compensator.d.ts

@@ -25,9 +25,10 @@ export type UnwindOutcome = 'ran' | LostCompensationClaim;
 /** Run compensation handlers in reverse start order for every eligible step. */
 export declare function runCompensation(exec: Execution, wf: Workflow, store: WorkflowStore, emitter: WorkflowEmitter | null, workflows?: Map<string, Workflow>, opts?: {
     retryFailed?: boolean;
+    assertActive?: () => void;
 }): Promise<UnwindOutcome>;
 /**
  * Give up on a parked unwind and record an explicit skipped outcome for every
  * remaining eligible step.
  */
-export declare function abandonCompensation(exec: Execution, wf: Workflow, store: WorkflowStore, emitter: WorkflowEmitter | null): void;
+export declare function abandonCompensation(exec: Execution, wf: Workflow, store: WorkflowStore, emitter: WorkflowEmitter | null, assertActive?: () => void): void;

package/dist/client/workflow/compensator.js

@@ -9,6 +9,7 @@ import { unwind } from './compensationPass';
 import { AbandonedCompensationError } from './compensationChild';
 import { acquireCompensationClaim } from './compensationClaim';
 import { settle, unwindSet } from './compensationSupport';
+import { assertWorkflowActive } from './executionFence';
 import { owesOutcome } from './unwindPlan';
 export { AbandonedCompensationError, CommittedChildError } from './compensationChild';
 /** Sentinel thrown when an execution deliberately parks for a signal. */
@@ -20,8 +21,10 @@ export class WaitForSignalError extends Error {
     }
 }
 /** Run compensation handlers in reverse start order for every eligible step. */
-// biome-ignore lint/complexity/useMaxParams: registry and operator retry are independent inputs
+// oxlint-disable-next-line max-params -- registry and operator retry are independent inputs
 export async function runCompensation(exec, wf, store, emitter, workflows, opts = {}) {
+    const assertActive = opts.assertActive ?? assertWorkflowActive;
+    assertActive();
     // `failed` + `stuck` is the durable terminal form written by an explicit
     // abandon. No caller, including an ancestor retry, may reopen that decision.
     if (exec.state === 'failed' && exec.rollbackStatus === 'stuck') {
@@ -29,17 +32,19 @@ export async function runCompensation(exec, wf, store, emitter, workflows, opts
     }
     const eligible = unwindSet(exec, wf);
     if (eligible.length === 0) {
+        assertActive();
         exec.rollbackStatus = 'not-applicable';
         if (exec.state !== 'failed' && exec.state !== 'completed')
             exec.state = 'failed';
         store.update(exec);
         return 'ran';
     }
+    assertActive();
     const claim = acquireCompensationClaim(exec.id, store);
     if (claim.kind === 'claim-lost')
         return claim;
     try {
-        await unwind({ exec, wf, store, emitter, eligible, workflows, ...opts }, ({ exec, workflow, store, emitter, workflows, retryFailed }) => runCompensation(exec, workflow, store, emitter, workflows, { retryFailed }));
+        await unwind({ exec, wf, store, emitter, eligible, workflows, ...opts, assertActive }, ({ exec, workflow, store, emitter, workflows, retryFailed, assertActive }) => runCompensation(exec, workflow, store, emitter, workflows, { retryFailed, assertActive }));
     }
     finally {
         claim.release();
@@ -50,8 +55,9 @@ export async function runCompensation(exec, wf, store, emitter, workflows, opts
  * Give up on a parked unwind and record an explicit skipped outcome for every
  * remaining eligible step.
  */
-export function abandonCompensation(exec, wf, store, emitter) {
+export function abandonCompensation(exec, wf, store, emitter, assertActive = assertWorkflowActive) {
     for (const [name, record] of unwindSet(exec, wf)) {
+        assertActive();
         if (record.compensation)
             continue;
         if (!owesOutcome(wf, name, record))
@@ -59,7 +65,9 @@ export function abandonCompensation(exec, wf, store, emitter) {
         const reason = 'unwind abandoned by operator';
         settle(record, 'compensation-skipped', reason);
         emitter?.emitStep('compensation:skipped', exec.id, exec.workflowName, name, { error: reason });
+        assertActive();
     }
+    assertActive();
     exec.state = 'failed';
     exec.rollbackStatus = 'stuck';
     store.update(exec);

package/dist/client/workflow/engine.js

@@ -136,7 +136,7 @@ export class Engine {
         // Before the worker: a waitFor timer that fires during shutdown enqueues a step
         // job, and a queue closing underneath it turns an orderly shutdown into a rejected
         // add. Releasing the timers first makes the order irrelevant.
-        this.executor.close();
+        this.executor.close(force);
         await this.worker.close(force);
         this.queue.close();
         this.store.close();

package/dist/client/workflow/executionFence.d.ts

@@ -0,0 +1,15 @@
+/** Lifecycle fence shared by every asynchronous workflow execution path. */
+/** Internal control-flow signal used to abandon work owned by a closed Engine. */
+export declare class WorkflowExecutionClosedError extends Error {
+    constructor();
+}
+export declare function isWorkflowExecutionClosed(error: unknown): boolean;
+/** A graceful close leaves this active; only close(true) aborts in-flight control flow. */
+export declare class WorkflowExecutionFence {
+    private readonly controller;
+    readonly assertActive: () => void;
+    isActive(): boolean;
+    close(force: boolean): void;
+}
+/** Default for isolated runner tests that do not own an Engine lifecycle. */
+export declare const assertWorkflowActive: () => void;

package/dist/client/workflow/executionFence.js

@@ -0,0 +1,29 @@
+/** Lifecycle fence shared by every asynchronous workflow execution path. */
+/** Internal control-flow signal used to abandon work owned by a closed Engine. */
+export class WorkflowExecutionClosedError extends Error {
+    constructor() {
+        super('Workflow execution belongs to a force-closed Engine');
+        this.name = 'WorkflowExecutionClosedError';
+    }
+}
+export function isWorkflowExecutionClosed(error) {
+    return (error instanceof WorkflowExecutionClosedError ||
+        (error instanceof AggregateError && error.errors.some(isWorkflowExecutionClosed)));
+}
+/** A graceful close leaves this active; only close(true) aborts in-flight control flow. */
+export class WorkflowExecutionFence {
+    controller = new AbortController();
+    assertActive = () => {
+        if (this.controller.signal.aborted)
+            throw new WorkflowExecutionClosedError();
+    };
+    isActive() {
+        return !this.controller.signal.aborted;
+    }
+    close(force) {
+        if (force)
+            this.controller.abort();
+    }
+}
+/** Default for isolated runner tests that do not own an Engine lifecycle. */
+export const assertWorkflowActive = () => undefined;

package/dist/client/workflow/executor.d.ts

@@ -10,13 +10,14 @@ export declare class WorkflowExecutor {
     private readonly emitter;
     private readonly workflows;
     private readonly timeoutTimers;
+    private readonly fence;
     /**
      * Release every armed waitFor timer. The engine owns the executor's lifetime, so
      * `Engine.close()` must call this: an armed timer would otherwise fire into a
      * closing queue, and a caller that keeps the process alive after closing one engine
      * has no other handle on them.
      */
-    close(): void;
+    close(force?: boolean): void;
     private readonly updateFn;
     constructor(store: WorkflowStore, queue: Queue, emitter?: WorkflowEmitter | null);
     register(workflow: Workflow): void;
@@ -24,16 +25,9 @@ export declare class WorkflowExecutor {
     /**
      * Nodes this process is currently executing, keyed `<execution>:<nodeIndex>`.
      *
-     * The cursor guard below rejects a job for a node the run has already left, but not
-     * a SECOND job for the node it is on right now: both carry the same index. That is
-     * the reachable duplicate, because `recover()` re-enqueues the current node of every
-     * `running` execution and is documented as callable on a live engine. Without this
-     * claim the node runs twice and each copy advances the run independently, doubling
-     * every side effect after it while the run still ends `completed`.
-     *
-     * A claim, not a queue-level dedup: a deterministic `jobId` was tried and could
-     * swallow a LEGITIMATE later re-enqueue of the same node, wedging the run forever.
-     * This drops only a duplicate that overlaps in time.
+     * The cursor rejects stale jobs but not two overlapping deliveries for the current
+     * node. This process-local claim drops that overlap. Queue-level dedup is unsuitable:
+     * a retained ID can swallow a legitimate recovery enqueue and wedge the run.
      */
     private readonly nodesInFlight;
     processStep(data: StepJobData): Promise<unknown>;