bunqueue 2.8.38 → 2.8.40

package/dist/application/queueManager.d.ts

@@ -31,6 +31,7 @@ export declare class QueueManager {
     private readonly depCompletions;
     private readonly timedOutJobs;
     private readonly jobResults;
+    private readonly dependencyResults;
     private readonly customIdMap;
     private readonly jobLogs;
     private readonly pendingDepChecks;
@@ -64,13 +65,13 @@ export declare class QueueManager {
     private handleRepeat;
     push(queue: string, input: JobInput): Promise<Job>;
     pushBatch(queue: string, inputs: JobInput[]): Promise<JobId[]>;
-    pull(queue: string, timeoutMs?: number): Promise<Job | null>;
-    pullWithLock(queue: string, owner: string, timeoutMs?: number, lockTtl?: number): Promise<{
+    pull(queue: string, timeoutMs?: number, signal?: AbortSignal): Promise<Job | null>;
+    pullWithLock(queue: string, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal): Promise<{
         job: Job | null;
         token: string | null;
     }>;
-    pullBatch(queue: string, count: number, timeoutMs?: number): Promise<Job[]>;
-    pullBatchWithLock(queue: string, count: number, owner: string, timeoutMs?: number, lockTtl?: number): Promise<{
+    pullBatch(queue: string, count: number, timeoutMs?: number, signal?: AbortSignal): Promise<Job[]>;
+    pullBatchWithLock(queue: string, count: number, owner: string, timeoutMs?: number, lockTtl?: number, signal?: AbortSignal): Promise<{
         jobs: Job[];
         tokens: string[];
     }>;

package/dist/application/queueManager.js

@@ -4,6 +4,7 @@
  */
 import { DEFAULT_LOCK_TTL } from '../domain/types/job';
 import { DEFAULT_STALL_CONFIG } from '../domain/types/stall';
+import { DEFAULT_DLQ_CONFIG } from '../domain/types/dlq';
 import { Shard } from '../domain/queue/shard';
 import { SqliteStorage } from '../infrastructure/persistence/sqlite';
 import { CronScheduler } from '../infrastructure/scheduler/cronScheduler';
@@ -32,6 +33,7 @@ import * as statsMgr from './statsManager';
 import { ContextFactory } from './contextFactory';
 import { processPendingDependencies } from './dependencyProcessor';
 import { handleTaskError, handleTaskSuccess } from './taskErrorTracking';
+import { DependencyResultTracker } from './dependencyResultTracker';
 /**
  * QueueManager - Central coordinator
  */
@@ -58,6 +60,7 @@ export class QueueManager {
     // current token and bypasses the stale-token recovery path entirely.
     timedOutJobs;
     jobResults;
+    dependencyResults = new DependencyResultTracker();
     customIdMap;
     jobLogs;
     // Deferred dependency resolution queue
@@ -178,6 +181,7 @@ export class QueueManager {
             depCompletions: this.depCompletions,
             timedOutJobs: this.timedOutJobs,
             jobResults: this.jobResults,
+            dependencyResults: this.dependencyResults,
             customIdMap: this.customIdMap,
             jobLogs: this.jobLogs,
             jobLocks: this.jobLocks,
@@ -254,21 +258,22 @@ export class QueueManager {
         this.registerQueueName(queue);
         return pushJobBatch(queue, inputs, this.contextFactory.getPushContext());
     }
-    async pull(queue, timeoutMs = 0) {
-        return pullJob(queue, timeoutMs, this.contextFactory.getPullContext());
+    async pull(queue, timeoutMs = 0, signal) {
+        return pullJob(queue, timeoutMs, this.contextFactory.getPullContext(), signal);
     }
-    async pullWithLock(queue, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL) {
-        const job = await pullJob(queue, timeoutMs, this.contextFactory.getPullContext());
+    async pullWithLock(queue, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL, signal) {
+        const job = await pullJob(queue, timeoutMs, this.contextFactory.getPullContext(), signal);
         if (!job)
             return { job: null, token: null };
         const token = lockMgr.createLock(job.id, owner, this.contextFactory.getLockContext(), lockTtl);
         return { job, token };
     }
-    async pullBatch(queue, count, timeoutMs = 0) {
-        return pullJobBatch(queue, count, timeoutMs, this.contextFactory.getPullContext());
+    async pullBatch(queue, count, timeoutMs = 0, signal) {
+        return pullJobBatch(queue, count, timeoutMs, this.contextFactory.getPullContext(), signal);
     }
-    async pullBatchWithLock(queue, count, owner, timeoutMs = 0, lockTtl = DEFAULT_LOCK_TTL) {
-        const jobs = await pullJobBatch(queue, count, timeoutMs, this.contextFactory.getPullContext());
+    // biome-ignore lint/complexity/useMaxParams: preserves the public API while adding cancellation
+    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 = [];
         for (const job of jobs) {
             const token = lockMgr.createLock(job.id, owner, this.contextFactory.getLockContext(), lockTtl);
@@ -541,6 +546,9 @@ export class QueueManager {
             ctx.jobIndex.delete(jId);
             ctx.storage?.deleteJob(jId);
         }
+        if (result !== undefined)
+            ctx.dependencyResults.retain(jId, result);
+        ctx.dependencyResults.releaseConsumer(jId);
         ctx.totalCompleted.value++;
         ctx.broadcast({
             eventType: 'completed',
@@ -769,6 +777,7 @@ export class QueueManager {
             this.jobResults.delete(jid);
             this.jobLogs.delete(jid);
             this.jobLocks.delete(jid);
+            this.dependencyResults.releaseConsumer(jid);
             this.failedChildrenValues.delete(jid);
             this.ignoredChildrenFailures.delete(jid);
             this.pendingDepChecks.delete(jid);
@@ -887,10 +896,16 @@ export class QueueManager {
             return;
         const state = this.shards[shardIndex(queue)].getState(queue);
         const stallConfig = this.shards[shardIndex(queue)].getStallConfig(queue);
+        const dlqConfig = this.shards[shardIndex(queue)].getDlqConfig(queue);
         const hasCustomStallConfig = stallConfig.enabled !== DEFAULT_STALL_CONFIG.enabled ||
             stallConfig.stallInterval !== DEFAULT_STALL_CONFIG.stallInterval ||
             stallConfig.maxStalls !== DEFAULT_STALL_CONFIG.maxStalls ||
             stallConfig.gracePeriod !== DEFAULT_STALL_CONFIG.gracePeriod;
+        const hasCustomDlqConfig = dlqConfig.autoRetry !== DEFAULT_DLQ_CONFIG.autoRetry ||
+            dlqConfig.autoRetryInterval !== DEFAULT_DLQ_CONFIG.autoRetryInterval ||
+            dlqConfig.maxAutoRetries !== DEFAULT_DLQ_CONFIG.maxAutoRetries ||
+            dlqConfig.maxAge !== DEFAULT_DLQ_CONFIG.maxAge ||
+            dlqConfig.maxEntries !== DEFAULT_DLQ_CONFIG.maxEntries;
         // When control-state returns fully to default (not paused, no limits), drop
         // the row instead of persisting an all-default placeholder. Keeps the table
         // free of noise rows for ephemeral queues that only ever call resume/clear*,
@@ -898,7 +913,8 @@ export class QueueManager {
         if (!state.paused &&
             state.rateLimit === null &&
             state.concurrencyLimit === null &&
-            !hasCustomStallConfig) {
+            !hasCustomStallConfig &&
+            !hasCustomDlqConfig) {
             this.storage.deleteQueueState(queue);
             return;
         }
@@ -909,6 +925,7 @@ export class QueueManager {
             rateLimitDuration: state.rateLimitDuration,
             rateLimitExpiresAt: state.rateLimitExpiresAt,
             stallConfig,
+            dlqConfig,
         });
     }
     /** Get rate limit and concurrency limit for a queue */
@@ -947,6 +964,7 @@ export class QueueManager {
     }
     setDlqConfig(queue, config) {
         this.shards[shardIndex(queue)].setDlqConfig(queue, config);
+        this.persistQueueState(queue);
     }
     getDlqConfig(queue) {
         return this.shards[shardIndex(queue)].getDlqConfig(queue);
@@ -1259,6 +1277,7 @@ export class QueueManager {
         // Parent reached a terminal (DLQ) state — release its flow-failure tracking.
         this.failedChildrenValues.delete(parentId);
         this.ignoredChildrenFailures.delete(parentId);
+        this.dependencyResults.releaseConsumer(parentId);
         // Broadcast failed event for parent
         this.eventsManager.broadcast({
             eventType: 'failed',
@@ -1282,11 +1301,15 @@ export class QueueManager {
         if (!childJob.parentId)
             return;
         if (childJob.continueParentOnFailure) {
-            this.continueParentOnChildFailure(childJob, error).catch(() => { });
+            this.continueParentOnChildFailure(childJob, error).catch(() => {
+                // Best-effort parent propagation; child failure is already durable.
+            });
         }
         else {
             // removeDependencyOnFailure or ignoreDependencyOnFailure
-            this.removeChildFromParentDeps(childJob, error, childJob.ignoreDependencyOnFailure).catch(() => { });
+            this.removeChildFromParentDeps(childJob, error, childJob.ignoreDependencyOnFailure).catch(() => {
+                // Best-effort parent propagation; child failure is already durable.
+            });
         }
     }
     /**
@@ -1396,6 +1419,7 @@ export class QueueManager {
             if (depIndex !== -1) {
                 parentJob.dependsOn.splice(depIndex, 1);
                 shard.unregisterDependencies(parentId, [childJob.id]);
+                this.dependencyResults.releaseDependency(parentId, childJob.id);
             }
             // If no more pending deps, the parent is ready to be promoted
             readyToPromote =
@@ -1449,6 +1473,7 @@ export class QueueManager {
             if (depIndex !== -1) {
                 parentJob.dependsOn.splice(depIndex, 1);
                 shard.unregisterDependencies(parentId, [childJobId]);
+                this.dependencyResults.releaseDependency(parentId, childJobId);
             }
             const allDone = parentJob.dependsOn.length === 0 ||
                 parentJob.dependsOn.every((dep) => this.completedJobs.has(dep));
@@ -1615,6 +1640,7 @@ export class QueueManager {
         this.depCompletions.clear();
         this.timedOutJobs.clear();
         this.jobResults.clear();
+        this.dependencyResults.clear();
         this.jobLogs.clear();
         this.customIdMap.clear();
         this.pendingDepChecks.clear();

package/dist/application/types.d.ts

@@ -12,6 +12,7 @@ import type { EventsManager } from './eventsManager';
 import type { WebhookManager } from './webhookManager';
 import type { WorkerManager } from './workerManager';
 import type { MonitoringState } from './monitoringChecks';
+import type { DependencyResultTracker } from './dependencyResultTracker';
 /** Queue Manager configuration */
 export interface QueueManagerConfig {
     dataPath?: string;
@@ -52,6 +53,7 @@ export interface QueueManagerState {
     readonly jobIndex: Map<JobId, JobLocation>;
     readonly completedJobs: BoundedSet<JobId>;
     readonly jobResults: LRUMap<JobId, unknown>;
+    readonly dependencyResults: DependencyResultTracker;
     readonly customIdMap: LRUMap<string, JobId>;
     readonly jobLogs: LRUMap<JobId, JobLogEntry[]>;
     readonly jobLocks: Map<JobId, JobLock>;

package/dist/cli/client.js

@@ -3,10 +3,11 @@
  * Connects to bunQ server and executes commands (msgpack binary protocol)
  */
 import { formatOutput, formatError } from './output';
-import { pack, unpack } from 'msgpackr';
 import { FrameParser, FrameSizeError } from '../infrastructure/server/protocol';
 import { CommandError } from './commands/types';
 import { buildClientTls } from '../client/tcp/connection';
+import { buildCommand } from './commandRouter';
+import { decodeMessagePack, encodeMessagePack } from '../shared/msgpack';
 /**
  * Client-side timeout for a command: base 30s; ONLY the long-poll commands
  * (PULL/WaitJob, where `timeout` means "how long the server may hold the
@@ -21,7 +22,7 @@ export function clientTimeoutFor(cmd) {
     return Math.max(30000, cmdTimeout + 10000);
 }
 /** Send a command and wait for response */
-async function sendCommand(socket, command, timeoutMs = 30000) {
+function sendCommand(socket, command, timeoutMs = 30000) {
     return new Promise((resolve, reject) => {
         const timeoutId = setTimeout(() => {
             socket.data.resolve = null;
@@ -36,11 +37,11 @@ async function sendCommand(socket, command, timeoutMs = 30000) {
             clearTimeout(timeoutId);
             reject(error);
         };
-        socket.write(FrameParser.frame(pack(command)));
+        socket.write(FrameParser.frame(encodeMessagePack(command)));
     });
 }
 /** Create TCP connection */
-async function connect(options) {
+function connect(options) {
     return new Promise((resolve, reject) => {
         const socketData = {
             frameParser: new FrameParser(),
@@ -73,7 +74,7 @@ async function connect(options) {
                 for (const frame of frames) {
                     if (socketData.resolve) {
                         try {
-                            const response = unpack(frame);
+                            const response = decodeMessagePack(frame);
                             socketData.resolve(response);
                             socketData.resolve = null;
                             socketData.reject = null;
@@ -200,45 +201,3 @@ export async function executeCommand(command, args, options) {
         connection?.close();
     }
 }
-/** Build a command from CLI arguments */
-async function buildCommand(command, args) {
-    // Import command builders
-    const { buildCoreCommand } = await import('./commands/core');
-    const { buildJobCommand } = await import('./commands/job');
-    const { buildQueueCommand } = await import('./commands/queue');
-    const { buildDlqCommand } = await import('./commands/dlq');
-    const { buildCronCommand } = await import('./commands/cron');
-    const { buildWorkerCommand } = await import('./commands/worker');
-    const { buildWebhookCommand } = await import('./commands/webhook');
-    const { buildRateLimitCommand } = await import('./commands/rateLimit');
-    const { buildMonitorCommand } = await import('./commands/monitor');
-    switch (command) {
-        case 'push':
-        case 'pull':
-        case 'ack':
-        case 'fail':
-            return buildCoreCommand(command, args);
-        case 'job':
-            return buildJobCommand(args);
-        case 'queue':
-            return buildQueueCommand(args);
-        case 'dlq':
-            return buildDlqCommand(args);
-        case 'cron':
-            return buildCronCommand(args);
-        case 'worker':
-            return buildWorkerCommand(args);
-        case 'webhook':
-            return buildWebhookCommand(args);
-        case 'rate-limit':
-        case 'concurrency':
-            return buildRateLimitCommand(command, args);
-        case 'stats':
-        case 'metrics':
-        case 'health':
-        case 'ping':
-            return buildMonitorCommand(command);
-        default:
-            return null;
-    }
-}

package/dist/cli/commandRegistry.d.ts

@@ -0,0 +1,27 @@
+/** Canonical CLI command surface used by routing, help conformance, and tests. */
+export declare const CLI_COMMAND_SURFACE: {
+    readonly push: readonly [];
+    readonly pull: readonly [];
+    readonly ack: readonly [];
+    readonly fail: readonly [];
+    readonly job: readonly ["get", "state", "result", "cancel", "progress", "update", "priority", "promote", "delay", "discard", "logs", "log", "wait"];
+    readonly queue: readonly ["list", "pause", "resume", "drain", "obliterate", "clean", "count", "jobs", "paused"];
+    readonly 'rate-limit': readonly ["set", "clear"];
+    readonly concurrency: readonly ["set", "clear"];
+    readonly dlq: readonly ["list", "retry", "purge"];
+    readonly cron: readonly ["list", "add", "delete"];
+    readonly worker: readonly ["list", "register", "unregister"];
+    readonly webhook: readonly ["list", "add", "remove"];
+    readonly stats: readonly [];
+    readonly metrics: readonly [];
+    readonly health: readonly [];
+    readonly ping: readonly [];
+};
+export type CliNetworkCommand = keyof typeof CLI_COMMAND_SURFACE;
+/** Commands handled locally instead of being translated to a TCP command. */
+export declare const CLI_LOCAL_COMMAND_SURFACE: {
+    readonly start: readonly [];
+    readonly version: readonly [];
+    readonly doctor: readonly [];
+    readonly backup: readonly ["now", "create", "list", "restore", "status"];
+};

package/dist/cli/commandRegistry.js

@@ -0,0 +1,40 @@
+/** Canonical CLI command surface used by routing, help conformance, and tests. */
+export const CLI_COMMAND_SURFACE = {
+    push: [],
+    pull: [],
+    ack: [],
+    fail: [],
+    job: [
+        'get',
+        'state',
+        'result',
+        'cancel',
+        'progress',
+        'update',
+        'priority',
+        'promote',
+        'delay',
+        'discard',
+        'logs',
+        'log',
+        'wait',
+    ],
+    queue: ['list', 'pause', 'resume', 'drain', 'obliterate', 'clean', 'count', 'jobs', 'paused'],
+    'rate-limit': ['set', 'clear'],
+    concurrency: ['set', 'clear'],
+    dlq: ['list', 'retry', 'purge'],
+    cron: ['list', 'add', 'delete'],
+    worker: ['list', 'register', 'unregister'],
+    webhook: ['list', 'add', 'remove'],
+    stats: [],
+    metrics: [],
+    health: [],
+    ping: [],
+};
+/** Commands handled locally instead of being translated to a TCP command. */
+export const CLI_LOCAL_COMMAND_SURFACE = {
+    start: [],
+    version: [],
+    doctor: [],
+    backup: ['now', 'create', 'list', 'restore', 'status'],
+};

package/dist/cli/commandRouter.d.ts

@@ -0,0 +1,3 @@
+export declare const CLI_NETWORK_COMMANDS: readonly ("push" | "queue" | "dlq" | "job" | "cron" | "worker" | "concurrency" | "ping" | "stats" | "metrics" | "pull" | "ack" | "fail" | "rate-limit" | "health" | "webhook")[];
+/** Build the protocol command for a routed network CLI command. */
+export declare function buildCommand(command: string, args: string[]): Promise<Record<string, unknown> | null>;

package/dist/cli/commandRouter.js

@@ -0,0 +1,44 @@
+import { CLI_COMMAND_SURFACE } from './commandRegistry';
+export const CLI_NETWORK_COMMANDS = Object.freeze(Object.keys(CLI_COMMAND_SURFACE));
+/** Build the protocol command for a routed network CLI command. */
+export async function buildCommand(command, args) {
+    if (!CLI_NETWORK_COMMANDS.includes(command))
+        return null;
+    const { buildCoreCommand } = await import('./commands/core');
+    const { buildJobCommand } = await import('./commands/job');
+    const { buildQueueCommand } = await import('./commands/queue');
+    const { buildDlqCommand } = await import('./commands/dlq');
+    const { buildCronCommand } = await import('./commands/cron');
+    const { buildWorkerCommand } = await import('./commands/worker');
+    const { buildWebhookCommand } = await import('./commands/webhook');
+    const { buildRateLimitCommand } = await import('./commands/rateLimit');
+    const { buildMonitorCommand } = await import('./commands/monitor');
+    switch (command) {
+        case 'push':
+        case 'pull':
+        case 'ack':
+        case 'fail':
+            return buildCoreCommand(command, args);
+        case 'job':
+            return buildJobCommand(args);
+        case 'queue':
+            return buildQueueCommand(args);
+        case 'dlq':
+            return buildDlqCommand(args);
+        case 'cron':
+            return buildCronCommand(args);
+        case 'worker':
+            return buildWorkerCommand(args);
+        case 'webhook':
+            return buildWebhookCommand(args);
+        case 'rate-limit':
+        case 'concurrency':
+            return buildRateLimitCommand(command, args);
+        case 'stats':
+        case 'metrics':
+        case 'health':
+        case 'ping':
+            return buildMonitorCommand(command);
+    }
+    return null;
+}

package/dist/cli/commands/backup.js

@@ -42,7 +42,7 @@ export async function executeBackupCommand(args) {
         case 'status':
             return executeBackupStatus(manager);
         default:
-            throw new CommandError(`Unknown backup subcommand: ${subcommand}. Use: now, list, restore, status`);
+            throw new CommandError(`Unknown backup subcommand: ${subcommand}. Use: now, create, list, restore, status`);
     }
 }
 async function executeBackupNow(manager) {

package/dist/cli/commands/core.js

@@ -4,6 +4,56 @@
  */
 import { parseArgs } from 'node:util';
 import { CommandError, requireArg, parseJsonArg, parseNumberArg, parseBigIntArg } from './types';
+const PUSH_VALUE_FLAGS = new Set([
+    '--priority',
+    '-P',
+    '--delay',
+    '-d',
+    '--max-attempts',
+    '--backoff',
+    '--ttl',
+    '--timeout',
+    '--unique-key',
+    '-u',
+    '--job-id',
+    '--depends-on',
+    '--tags',
+    '--group-id',
+    '-g',
+]);
+function protectNegativeJsonData(args) {
+    const protectedArgs = [...args];
+    const restore = new Map();
+    let positionals = 0;
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === '--')
+            break;
+        if (PUSH_VALUE_FLAGS.has(arg)) {
+            index++;
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            if (positionals !== 1)
+                continue;
+            try {
+                if (typeof JSON.parse(arg) !== 'number')
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const sentinel = `bunqueue-negative-json-${index}`;
+            protectedArgs[index] = sentinel;
+            restore.set(sentinel, arg);
+            positionals++;
+            continue;
+        }
+        if (!arg.startsWith('--') && !/^-[a-zA-Z]/.test(arg))
+            positionals++;
+    }
+    return { args: protectedArgs, restore };
+}
 /** Build a core command from CLI args */
 export function buildCoreCommand(command, args) {
     switch (command) {
@@ -21,8 +71,9 @@ export function buildCoreCommand(command, args) {
 }
 /** Build PUSH command */
 function buildPush(args) {
+    const protectedInput = protectNegativeJsonData(args);
     const { values, positionals } = parseArgs({
-        args,
+        args: protectedInput.args,
         options: {
             priority: { type: 'string', short: 'P' },
             delay: { type: 'string', short: 'd' },
@@ -43,7 +94,8 @@ function buildPush(args) {
         strict: false,
     });
     const queue = requireArg(positionals, 0, 'queue');
-    const data = parseJsonArg(requireArg(positionals, 1, 'data'), 'data');
+    const protectedData = requireArg(positionals, 1, 'data');
+    const data = parseJsonArg(protectedInput.restore.get(protectedData) ?? protectedData, 'data');
     const cmd = {
         cmd: 'PUSH',
         queue,

package/dist/cli/commands/doctor.d.ts

@@ -1,5 +1,50 @@
-/**
- * bunqueue doctor - Diagnostic command
- * Checks client/server version, connectivity, health, and queue state
- */
-export declare function runDoctor(host: string, httpPort: number): Promise<void>;
+export interface HealthData {
+    version?: string;
+    status?: string;
+    uptime?: number;
+    queues?: {
+        waiting?: number;
+        active?: number;
+        delayed?: number;
+        completed?: number;
+        dlq?: number;
+    };
+    connections?: {
+        tcp?: number;
+        ws?: number;
+        sse?: number;
+    };
+    memory?: {
+        heapUsed?: number;
+        heapTotal?: number;
+        rss?: number;
+    };
+}
+export type DoctorInput = {
+    kind: 'ok';
+    endpoint: string;
+    health: HealthData;
+} | {
+    kind: 'http-error';
+    endpoint: string;
+    status: number;
+} | {
+    kind: 'network-error';
+    endpoint: string;
+    message: string;
+};
+export interface DoctorReport {
+    clientVersion: string;
+    endpoint: string;
+    reachable: boolean;
+    health?: HealthData;
+    error?: string;
+    issues: number;
+    fatal: boolean;
+    exitCode: 0 | 1;
+}
+export declare function fetchDoctorHealth(host: string, httpPort: number): Promise<DoctorInput>;
+/** Evaluate diagnostics without performing I/O or reading clocks. */
+export declare function evaluateDoctor(input: DoctorInput): DoctorReport;
+export declare function formatDoctorText(report: DoctorReport): string;
+export declare function runDoctor(host: string, httpPort: number): Promise<DoctorReport>;