bunqueue 2.8.28 → 2.8.29

package/dist/application/dlqManager.d.ts

@@ -22,7 +22,7 @@ export declare function getDlqStats(queue: string, ctx: DlqContext): DlqStats;
 /** Retry a single job from DLQ */
 export declare function retryDlqJob(queue: string, jobId: JobId, ctx: DlqContext): Job | null;
 /** Retry jobs from DLQ (backward compatible) */
-export declare function retryDlqJobs(queue: string, ctx: DlqContext, jobId?: JobId): number;
+export declare function retryDlqJobs(queue: string, ctx: DlqContext, jobId?: JobId, limit?: number): number;
 /** Retry jobs by filter */
 export declare function retryDlqByFilter(queue: string, ctx: DlqContext, filter: DlqFilter): number;
 /** Process auto-retry for a queue */

package/dist/application/dlqManager.js

@@ -86,10 +86,34 @@ export function retryDlqJob(queue, jobId, ctx) {
     return job;
 }
 /** Retry jobs from DLQ (backward compatible) */
-export function retryDlqJobs(queue, ctx, jobId) {
+export function retryDlqJobs(queue, ctx, jobId, limit) {
     if (jobId) {
         return retryDlqJob(queue, jobId, ctx) ? 1 : 0;
     }
+    // Bounded retry (#111-class: `retryJobs({ state:'failed', count })`). Retry
+    // only the first `limit` DLQ entries, reusing the tested single-entry path so
+    // the remaining entries stay in the DLQ (memory + SQLite) instead of the
+    // clear-all fast path below wrongly draining the whole queue. Any provided
+    // `limit` engages the bounded path; a negative/NaN/fractional cap is clamped
+    // to a safe non-negative integer so it can never fall through to clear-all
+    // (skeptic: `limit >= 0` let `-1`/`NaN` drain the entire DLQ). `undefined`
+    // (no cap requested) still means "retry all" via the fast path below.
+    if (limit !== undefined) {
+        const cap = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : 0;
+        const idx = shardIndex(queue);
+        const shard = ctx.shards[idx];
+        // Snapshot ids first: retryDlqJob mutates the DLQ as it goes.
+        const ids = shard
+            .getDlqEntries(queue)
+            .slice(0, cap)
+            .map((e) => e.job.id);
+        let retried = 0;
+        for (const id of ids) {
+            if (retryDlqJob(queue, id, ctx))
+                retried++;
+        }
+        return retried;
+    }
     const idx = shardIndex(queue);
     const shard = ctx.shards[idx];
     const entries = shard.getDlqEntries(queue);

package/dist/application/queueManager.d.ts

@@ -193,7 +193,7 @@ export declare class QueueManager {
     getDlqEntries(queue: string, filter?: DlqFilter): DlqEntry[];
     getDlqCount(queue: string): number;
     getDlqStats(queue: string): DlqStats;
-    retryDlq(queue: string, jobId?: JobId): number;
+    retryDlq(queue: string, jobId?: JobId, limit?: number): number;
     purgeDlq(queue: string): number;
     retryCompleted(queue: string, jobId?: JobId): number;
     setRateLimit(queue: string, limit: number): void;

package/dist/application/queueManager.js

@@ -849,8 +849,8 @@ export class QueueManager {
     getDlqStats(queue) {
         return dlqOps.getDlqStats(queue, this.contextFactory.getDlqContext());
     }
-    retryDlq(queue, jobId) {
-        return dlqOps.retryDlqJobs(queue, this.contextFactory.getDlqContext(), jobId);
+    retryDlq(queue, jobId, limit) {
+        return dlqOps.retryDlqJobs(queue, this.contextFactory.getDlqContext(), jobId, limit);
     }
     purgeDlq(queue) {
         return dlqOps.purgeDlqJobs(queue, this.contextFactory.getDlqContext());

package/dist/client/bunqueue.d.ts

@@ -43,9 +43,11 @@ export declare class Bunqueue<T = unknown, R = unknown> {
     countAsync(): Promise<number>;
     cron(id: string, pattern: string, data?: T, opts?: {
         timezone?: string;
+        limit?: number;
         jobOpts?: JobOptions;
     }): Promise<SchedulerInfo | null>;
     every(id: string, intervalMs: number, data?: T, opts?: {
+        limit?: number;
         jobOpts?: JobOptions;
     }): Promise<SchedulerInfo | null>;
     removeCron(id: string): Promise<boolean>;

package/dist/client/bunqueue.js

@@ -171,10 +171,10 @@ export class Bunqueue {
     }
     // ============ Cron ============
     cron(id, pattern, data, opts) {
-        return this.queue.upsertJobScheduler(id, { pattern, timezone: opts?.timezone }, { name: id, data, opts: opts?.jobOpts });
+        return this.queue.upsertJobScheduler(id, { pattern, timezone: opts?.timezone, limit: opts?.limit }, { name: id, data, opts: opts?.jobOpts });
     }
     every(id, intervalMs, data, opts) {
-        return this.queue.upsertJobScheduler(id, { every: intervalMs }, { name: id, data, opts: opts?.jobOpts });
+        return this.queue.upsertJobScheduler(id, { every: intervalMs, limit: opts?.limit }, { name: id, data, opts: opts?.jobOpts });
     }
     removeCron(id) {
         return this.queue.removeJobScheduler(id);

package/dist/client/flowJobFactory.js

@@ -3,6 +3,7 @@
  * Creates simple Job objects for FlowProducer results
  */
 import { getSharedManager } from './manager';
+import { buildFailCommand, failEmbeddedArgs } from './queue/failWire';
 import { jobId } from '../domain/types/job';
 /** Extract user data (remove internal fields like __parentId, __childrenIds, name) */
 export function extractUserDataFromInternal(data) {
@@ -254,12 +255,13 @@ export function createFlowJobObject(id, name, data, queueName, callbacks) {
             return null;
         },
         moveToFailed: async (error) => {
+            // Forward stacktrace + UnrecoverableError (was dropped; #74/#111-class).
             if (embedded) {
-                await getSharedManager().fail(jobId(id), error.message);
+                await getSharedManager().fail(jobId(id), ...failEmbeddedArgs(error));
                 return;
             }
             if (tcp)
-                await tcp.send({ cmd: 'FAIL', id, error: error.message });
+                await tcp.send(buildFailCommand(id, error));
         },
         moveToWait: async () => {
             if (embedded)

package/dist/client/queue/failWire.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared FAIL payload builder.
+ *
+ * Several client entry points move a job to `failed` (the Queue reflection API
+ * `queue.getJob(id).moveToFailed()`, the job proxies, and `moveJobToFailed`).
+ * They must all persist the stacktrace (#74) and honour `UnrecoverableError`,
+ * exactly like the worker failure path — otherwise the stack and the
+ * "do not retry" intent are silently dropped (the #111 silent-loss class).
+ * Centralising the mapping here keeps every site consistent.
+ */
+/** Build the TCP `FAIL` command for an explicit job failure. */
+export declare function buildFailCommand(id: string, error: Error, token?: string): Record<string, unknown>;
+/**
+ * Decompose an error into the trailing args of the embedded
+ * `manager.fail(jobId, error?, token?, unrecoverable?, stack?)` signature.
+ */
+export declare function failEmbeddedArgs(error: Error, token?: string): [string, string | undefined, boolean, string[] | undefined];

package/dist/client/queue/failWire.js

@@ -0,0 +1,32 @@
+/**
+ * Shared FAIL payload builder.
+ *
+ * Several client entry points move a job to `failed` (the Queue reflection API
+ * `queue.getJob(id).moveToFailed()`, the job proxies, and `moveJobToFailed`).
+ * They must all persist the stacktrace (#74) and honour `UnrecoverableError`,
+ * exactly like the worker failure path — otherwise the stack and the
+ * "do not retry" intent are silently dropped (the #111 silent-loss class).
+ * Centralising the mapping here keeps every site consistent.
+ */
+import { UnrecoverableError } from '../errors';
+import { computeStackLines } from '../worker/processorHandlers';
+/** Build the TCP `FAIL` command for an explicit job failure. */
+export function buildFailCommand(id, error, token) {
+    const { wireStack } = computeStackLines(error);
+    return {
+        cmd: 'FAIL',
+        id,
+        error: error.message,
+        ...(wireStack ? { stack: wireStack } : {}),
+        ...(token ? { token } : {}),
+        ...(error instanceof UnrecoverableError ? { unrecoverable: true } : {}),
+    };
+}
+/**
+ * Decompose an error into the trailing args of the embedded
+ * `manager.fail(jobId, error?, token?, unrecoverable?, stack?)` signature.
+ */
+export function failEmbeddedArgs(error, token) {
+    const { wireStack } = computeStackLines(error);
+    return [error.message, token, error instanceof UnrecoverableError, wireStack];
+}

package/dist/client/queue/jobMove.d.ts

@@ -15,7 +15,7 @@ interface JobMoveContext {
 /** Move job to completed state */
 export declare function moveJobToCompleted(ctx: JobMoveContext, id: string, returnValue: unknown, _token?: string): Promise<unknown>;
 /** Move job to failed state */
-export declare function moveJobToFailed(ctx: JobMoveContext, id: string, error: Error, _token?: string): Promise<void>;
+export declare function moveJobToFailed(ctx: JobMoveContext, id: string, error: Error, token?: string): Promise<void>;
 /** Move job back to waiting state */
 export declare function moveJobToWait(ctx: JobMoveContext, id: string, _token?: string): Promise<boolean>;
 /** Move job to delayed state */

package/dist/client/queue/jobMove.js

@@ -4,6 +4,7 @@
  */
 import { getSharedManager } from '../manager';
 import { jobId } from '../../domain/types/job';
+import { buildFailCommand, failEmbeddedArgs } from './failWire';
 /** Move job to completed state */
 export async function moveJobToCompleted(ctx, id, returnValue, _token) {
     if (ctx.embedded) {
@@ -14,12 +15,16 @@ export async function moveJobToCompleted(ctx, id, returnValue, _token) {
     return null;
 }
 /** Move job to failed state */
-export async function moveJobToFailed(ctx, id, error, _token) {
+export async function moveJobToFailed(ctx, id, error, token) {
+    // Mirror the worker failure path: persist the stacktrace (#74) and honour
+    // UnrecoverableError so a job explicitly failed via the Queue reflection API
+    // is not silently retried and does not lose its stack. Previously both were
+    // dropped on this path (same silent-loss class as #111).
     if (ctx.embedded) {
-        await getSharedManager().fail(jobId(id), error.message);
+        await getSharedManager().fail(jobId(id), ...failEmbeddedArgs(error, token));
     }
     else {
-        await ctx.tcp.send({ cmd: 'FAIL', id, error: error.message });
+        await ctx.tcp.send(buildFailCommand(id, error, token));
     }
 }
 /** Move job back to waiting state */

package/dist/client/queue/jobProxy.js

@@ -4,6 +4,7 @@
  */
 import { getSharedManager } from '../manager';
 import { jobId } from '../../domain/types/job';
+import { buildFailCommand, failEmbeddedArgs } from './failWire';
 function reflectFields(id, queueName, meta) {
     const opts = meta?.opts ?? {};
     const p = opts.parent;
@@ -130,7 +131,8 @@ export function createJobProxy(id, name, data, ctx, meta) {
             return null;
         },
         moveToFailed: async (error) => {
-            await tcp.send({ cmd: 'FAIL', id, error: error.message });
+            // Forward stacktrace + UnrecoverableError (was dropped; #74/#111-class).
+            await tcp.send(buildFailCommand(id, error));
         },
         moveToWait: async () => {
             const res = await tcp.send({ cmd: 'MoveToWait', id });
@@ -352,12 +354,13 @@ export function createSimpleJob(id, name, data, timestamp, ctx) {
             return null;
         },
         moveToFailed: async (error) => {
+            // Forward stacktrace + UnrecoverableError (was dropped; #74/#111-class).
             if (embedded) {
-                await getSharedManager().fail(jobId(id), error.message);
+                await getSharedManager().fail(jobId(id), ...failEmbeddedArgs(error));
                 return;
             }
             if (tcp)
-                await tcp.send({ cmd: 'FAIL', id, error: error.message });
+                await tcp.send(buildFailCommand(id, error));
         },
         moveToWait: async () => {
             if (embedded) {

package/dist/client/queue/operations/management.js

@@ -56,7 +56,8 @@ export async function retryJob(ctx, id) {
 export async function retryJobs(ctx, opts) {
     if (ctx.embedded) {
         if (opts?.state === 'failed') {
-            getSharedManager().retryDlq(ctx.name);
+            // #111-class: forward the count cap (was ignored → retried the whole DLQ).
+            getSharedManager().retryDlq(ctx.name, undefined, opts?.count);
         }
         return;
     }

package/dist/client/queue/scheduler.d.ts

@@ -45,6 +45,8 @@ export interface SchedulerInfo {
     next: number;
     pattern?: string;
     every?: number;
+    /** Max number of times the scheduler will fire (RepeatOpts.limit). #111 */
+    limit?: number;
 }
 /** Create or update a job scheduler */
 export declare function upsertJobScheduler(ctx: SchedulerContext, schedulerId: string, repeatOpts: RepeatOpts, jobTemplate?: JobTemplate): Promise<SchedulerInfo | null>;

package/dist/client/queue/scheduler.js

@@ -78,6 +78,8 @@ export async function upsertJobScheduler(ctx, schedulerId, repeatOpts, jobTempla
             repeatEvery,
             priority,
             timezone: repeatOpts.timezone ?? 'UTC',
+            // #111: forward the run cap; addCron ignores <=0/undefined (stored NULL).
+            maxLimit: repeatOpts.limit,
             skipMissedOnRestart: repeatOpts.skipMissedOnRestart,
             immediately: repeatOpts.immediately,
             skipIfNoWorker: repeatOpts.skipIfNoWorker,
@@ -89,6 +91,7 @@ export async function upsertJobScheduler(ctx, schedulerId, repeatOpts, jobTempla
             id: schedulerId,
             name: jobTemplate?.name ?? 'default',
             next: Date.now() + (repeatEvery ?? 60000),
+            limit: repeatOpts.limit && repeatOpts.limit > 0 ? repeatOpts.limit : undefined,
         };
     }
     const response = await ctx.tcp.send({
@@ -100,6 +103,8 @@ export async function upsertJobScheduler(ctx, schedulerId, repeatOpts, jobTempla
         repeatEvery,
         priority,
         timezone: repeatOpts.timezone,
+        // #111: forward the run cap on the TCP path too.
+        maxLimit: repeatOpts.limit,
         skipMissedOnRestart: repeatOpts.skipMissedOnRestart,
         immediately: repeatOpts.immediately,
         skipIfNoWorker: repeatOpts.skipIfNoWorker,
@@ -113,6 +118,7 @@ export async function upsertJobScheduler(ctx, schedulerId, repeatOpts, jobTempla
         id: schedulerId,
         name: jobTemplate?.name ?? 'default',
         next: (response.nextRun ?? Date.now()),
+        limit: repeatOpts.limit && repeatOpts.limit > 0 ? repeatOpts.limit : undefined,
     };
 }
 /** Remove a job scheduler */
@@ -139,6 +145,7 @@ export async function getJobScheduler(ctx, schedulerId) {
             next: cron.nextRun,
             pattern: cron.schedule ?? undefined,
             every: cron.repeatEvery ?? undefined,
+            limit: cron.maxLimit ?? undefined,
         };
     }
     const response = await ctx.tcp.send({ cmd: 'CronList' });
@@ -154,6 +161,7 @@ export async function getJobScheduler(ctx, schedulerId) {
         next: cron.nextRun,
         pattern: cron.schedule ?? undefined,
         every: cron.repeatEvery ?? undefined,
+        limit: cron.maxLimit ?? undefined,
     };
 }
 /** Get all job schedulers for this queue */
@@ -168,6 +176,7 @@ export async function getJobSchedulers(ctx, _start = 0, _end = -1, _asc = true)
             next: c.nextRun,
             pattern: c.schedule ?? undefined,
             every: c.repeatEvery ?? undefined,
+            limit: c.maxLimit ?? undefined,
         }));
     }
     const response = await ctx.tcp.send({ cmd: 'CronList' });
@@ -182,6 +191,7 @@ export async function getJobSchedulers(ctx, _start = 0, _end = -1, _asc = true)
         next: c.nextRun,
         pattern: c.schedule ?? undefined,
         every: c.repeatEvery ?? undefined,
+        limit: c.maxLimit ?? undefined,
     }));
 }
 /** Get count of job schedulers */

package/dist/client/sandboxed/worker.js

@@ -7,6 +7,7 @@ import { getSharedManager } from '../manager';
 import { getSharedPool, releaseSharedPool } from '../tcpPool';
 import { createPublicJob } from '../jobConversion';
 import { jobId } from '../../domain/types/job';
+import { buildFailCommand, failEmbeddedArgs } from '../queue/failWire';
 import { createProgressHandler, createLogHandler, createGetStateHandler, createGetChildrenValuesHandler, createGetFailedChildrenValuesHandler, createGetIgnoredChildrenFailuresHandler, createRemoveChildDependencyHandler, createRemoveUnprocessedChildrenHandler, createRemoveHandler, createRetryHandler, createUpdateDataHandler, createPromoteHandler, createChangeDelayHandler, createChangePriorityHandler, createExtendLockHandler, createClearLogsHandler, createMoveToWaitHandler, createMoveToDelayedHandler, createMoveToWaitingChildrenHandler, createWaitUntilFinishedHandler, createDiscardHandler, createGetDependenciesHandler, createGetDependenciesCountHandler, createRemoveDeduplicationKeyHandler, } from '../worker/processorHandlers';
 import { createWrapperScript, cleanupWrapperScript } from './wrapper';
 import { createEmbeddedOps, createTcpOps } from './queueOps';
@@ -514,12 +515,13 @@ export class SandboxedWorker extends EventEmitter {
             }
             return null;
         };
-        const moveToFailed = async (id, error, _token) => {
+        const moveToFailed = async (id, error, token) => {
+            // Forward stacktrace + UnrecoverableError (was dropped; #74/#111-class).
             if (embedded) {
-                await getSharedManager().fail(jobId(id), error.message);
+                await getSharedManager().fail(jobId(id), ...failEmbeddedArgs(error, token));
             }
             else if (tcp) {
-                await tcp.send({ cmd: 'FAIL', id, error: error.message });
+                await tcp.send(buildFailCommand(id, error, token));
             }
         };
         return createPublicJob({

package/dist/client/worker/processorHandlers.js

@@ -4,6 +4,7 @@
  */
 import { jobId } from '../../domain/types/job';
 import { getSharedManager } from '../manager';
+import { UnrecoverableError } from '../errors';
 export function createProgressHandler(embedded, tcp, emitter, jobHolder) {
     return async (id, progress, message) => {
         if (embedded) {
@@ -126,9 +127,13 @@ export function createMoveToFailedHandler(embedded, tcp, internalJob, token, onC
         // natural-throw path already does; @arthurvanl's repro showed the manual
         // path lost it. Compute before the send so the server can persist it.
         const { wireStack } = computeStackLines(error);
+        // Honour UnrecoverableError on the in-processor moveToFailed() path too, so
+        // it matches the natural-throw and Queue-reflection paths (skeptic: this was
+        // the one site still retrying an UnrecoverableError). #74/#82/#111-class.
+        const unrecoverable = error instanceof UnrecoverableError;
         if (embedded) {
             const manager = getSharedManager();
-            await manager.fail(internalJob.id, error.message, token ?? undefined, undefined, wireStack);
+            await manager.fail(internalJob.id, error.message, token ?? undefined, unrecoverable, wireStack);
         }
         else if (tcp) {
             await tcp.send({
@@ -137,6 +142,7 @@ export function createMoveToFailedHandler(embedded, tcp, internalJob, token, onC
                 error: error.message,
                 ...(wireStack ? { stack: wireStack } : {}),
                 ...(token ? { token } : {}),
+                ...(unrecoverable ? { unrecoverable: true } : {}),
             });
         }
         onCalled(error);

package/dist/client/worker/worker.js

@@ -322,7 +322,11 @@ export class Worker extends EventEmitter {
         if (this.embedded) {
             const manager = getSharedManager();
             if (this.opts.useLocks) {
-                const { job, token: lockToken } = await manager.pullWithLock(this.queueKey, this.workerId, 0);
+                // Forward the configured lock duration; without it pullWithLock falls
+                // back to the server default and a custom `lockDuration` is silently
+                // ignored on this manual-acquire path (same class as #111). The main
+                // run-loop path (workerPull.ts) already forwards it.
+                const { job, token: lockToken } = await manager.pullWithLock(this.queueKey, this.workerId, 0, this.opts.lockDuration);
                 if (job && lockToken) {
                     const jobIdStr = String(job.id);
                     this.pulledJobIds.add(jobIdStr);
@@ -346,6 +350,10 @@ export class Worker extends EventEmitter {
         };
         if (this.opts.useLocks) {
             cmd.owner = this.workerId;
+            // Forward the configured lock TTL (mirrors workerPull.ts); otherwise the
+            // server applies its 30s default and a custom lockDuration is dropped.
+            if (this.opts.lockDuration !== undefined)
+                cmd.lockTtl = this.opts.lockDuration;
             if (token)
                 cmd.token = token;
         }

package/dist/domain/types/command.d.ts

@@ -237,6 +237,8 @@ export interface RetryDlqCommand extends BaseCommand {
     readonly cmd: 'RetryDlq';
     readonly queue: string;
     readonly jobId?: string;
+    /** Cap the number of DLQ entries retried (omit = retry all). #111-class. */
+    readonly count?: number;
 }
 export interface PurgeDlqCommand extends BaseCommand {
     readonly cmd: 'PurgeDlq';

package/dist/infrastructure/server/handlers/dlq.js

@@ -12,7 +12,8 @@ export function handleDlq(cmd, ctx, reqId) {
 /** Handle RetryDlq command - retry DLQ jobs */
 export function handleRetryDlq(cmd, ctx, reqId) {
     const jid = cmd.jobId ? jobId(cmd.jobId) : undefined;
-    const count = ctx.queueManager.retryDlq(cmd.queue, jid);
+    // #111-class: honour the caller's `count` cap instead of retrying the whole DLQ.
+    const count = ctx.queueManager.retryDlq(cmd.queue, jid, cmd.count);
     if (count > 0) {
         const event = jid ? 'dlq:retried' : 'dlq:retry-all';
         const data = { queue: cmd.queue, count };

package/package.json

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