bunqueue 2.8.53 → 2.8.56

package/dist/client/worker/processorHandlers.js

@@ -1,400 +1,4 @@
-/**
- * Processor Handler Factories
- * Creates callback handlers for job operations during processing
- */
-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) {
-            const manager = getSharedManager();
-            await manager.updateProgress(jobId(id), progress, message);
-        }
-        else if (tcp) {
-            await tcp.send({ cmd: 'Progress', id, progress, message });
-        }
-        emitter.emit('progress', jobHolder.current, progress);
-    };
-}
-export function createLogHandler(embedded, tcp, emitter, jobHolder) {
-    return async (id, message) => {
-        if (embedded) {
-            const manager = getSharedManager();
-            manager.addLog(jobId(id), message);
-        }
-        else if (tcp) {
-            await tcp.send({ cmd: 'AddLog', id, message });
-        }
-        emitter.emit('log', jobHolder.current, message);
-    };
-}
-export function createGetStateHandler(embedded, tcp) {
-    return async (id) => {
-        if (embedded) {
-            const manager = getSharedManager();
-            return (await manager.getJobState(jobId(id)));
-        }
-        else if (tcp) {
-            const response = await tcp.send({ cmd: 'GetState', id });
-            return (response.state ?? 'unknown');
-        }
-        return 'unknown';
-    };
-}
-export function createGetChildrenValuesHandler(embedded, tcp) {
-    return async (id) => {
-        if (embedded) {
-            const manager = getSharedManager();
-            return manager.getChildrenValues(jobId(id));
-        }
-        else if (tcp) {
-            const response = await tcp.send({ cmd: 'GetChildrenValues', id });
-            const data = response.data;
-            return data?.values ?? {};
-        }
-        return {};
-    };
-}
-export function createGetFailedChildrenValuesHandler(embedded, tcp) {
-    return async (id) => {
-        if (embedded) {
-            const manager = getSharedManager();
-            return manager.getFailedChildrenValues(jobId(id));
-        }
-        if (!tcp)
-            return {};
-        const res = await tcp.send({ cmd: 'GetFailedChildrenValues', id });
-        return res.values ?? {};
-    };
-}
-export function createGetIgnoredChildrenFailuresHandler(embedded, tcp) {
-    return async (id) => {
-        if (embedded) {
-            const manager = getSharedManager();
-            return manager.getIgnoredChildrenFailures(jobId(id));
-        }
-        if (!tcp)
-            return {};
-        const res = await tcp.send({ cmd: 'GetIgnoredChildrenFailures', id });
-        return res.values ?? {};
-    };
-}
-export function createRemoveChildDependencyHandler(embedded, tcp) {
-    return async (id) => {
-        if (embedded) {
-            const manager = getSharedManager();
-            return manager.removeChildDependency(jobId(id));
-        }
-        if (!tcp)
-            return false;
-        const res = await tcp.send({ cmd: 'RemoveChildDependency', id });
-        return res.ok === true;
-    };
-}
-export function createRemoveUnprocessedChildrenHandler(embedded, tcp) {
-    return async (id) => {
-        if (embedded) {
-            const manager = getSharedManager();
-            return manager.removeUnprocessedChildren(jobId(id));
-        }
-        if (!tcp)
-            return;
-        await tcp.send({ cmd: 'RemoveUnprocessedChildren', id });
-    };
-}
-/**
- * Bug #74: split an Error's stack into trimmed, non-empty lines.
- * `wireStack` is the bandwidth-capped copy sent to the server (50 lines); the
- * authoritative cap (job.stackTraceLimit) is applied server-side in failJob.
- * Shared by the natural-throw path (handleJobFailure) and the explicit
- * moveToFailed() path so both persist the stack identically.
- */
-export function computeStackLines(err) {
-    const stackLines = err.stack
-        ? err.stack
-            .split('\n')
-            .map((l) => l.trim())
-            .filter(Boolean)
-        : [];
-    const wireStack = stackLines.length > 0 ? stackLines.slice(0, 50) : undefined;
-    return { stackLines, wireStack };
-}
-/** Issue #82: Create moveToFailed handler for use inside processor */
-export function createMoveToFailedHandler(embedded, tcp, internalJob, token, onCalled) {
-    return async (_id, error, _lockToken) => {
-        // Bug #74 follow-up: carry the stack on explicit moveToFailed() too. The
-        // 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, unrecoverable, wireStack);
-        }
-        else if (tcp) {
-            await tcp.send({
-                cmd: 'FAIL',
-                id: internalJob.id,
-                error: error.message,
-                ...(wireStack ? { stack: wireStack } : {}),
-                ...(token ? { token } : {}),
-                ...(unrecoverable ? { unrecoverable: true } : {}),
-            });
-        }
-        onCalled(error);
-    };
-}
-/** Issue #82: Create moveToCompleted handler for use inside processor */
-export function createMoveToCompletedHandler(embedded, ackBatcher, internalJob, token, onCalled) {
-    return async (_id, returnValue, _lockToken) => {
-        if (embedded) {
-            const manager = getSharedManager();
-            await manager.ack(internalJob.id, returnValue, token ?? undefined);
-        }
-        else {
-            await ackBatcher.queue(String(internalJob.id), returnValue, token ?? undefined);
-        }
-        onCalled(returnValue);
-        return null;
-    };
-}
-// ============================================================
-// Job mutation handlers (Issue #82 follow-up: wire remaining no-op methods)
-// ============================================================
-export function createRemoveHandler(embedded, tcp) {
-    return async (id) => {
-        if (embedded) {
-            await getSharedManager().cancel(jobId(id));
-            return;
-        }
-        if (!tcp)
-            return;
-        await tcp.send({ cmd: 'Cancel', id });
-    };
-}
-export function createRetryHandler(embedded, tcp, internalJob) {
-    return async (id) => {
-        // BullMQ contract: Job.retry() moves a failed job back to waiting.
-        // Dispatch by state so it also works on an active job that wants to requeue.
-        if (embedded) {
-            const mgr = getSharedManager();
-            const state = await mgr.getJobState(jobId(id));
-            if (state === 'failed') {
-                const count = mgr.retryDlq(internalJob.queue, jobId(id));
-                if (count === 0)
-                    throw new Error(`Job ${id} is failed but not present in DLQ`);
-                return;
-            }
-            if (state === 'active') {
-                const ok = await mgr.moveActiveToWait(jobId(id));
-                if (!ok)
-                    throw new Error(`Failed to retry active job ${id}`);
-                return;
-            }
-            if (state === 'waiting' || state === 'prioritized' || state === 'delayed')
-                return;
-            throw new Error(`Cannot retry job ${id} from state '${state}'`);
-        }
-        if (!tcp)
-            return;
-        const res = await tcp.send({ cmd: 'MoveToWait', id });
-        if (res.ok !== true) {
-            const err = typeof res.error === 'string' ? res.error : 'retry failed';
-            throw new Error(err);
-        }
-    };
-}
-export function createUpdateDataHandler(embedded, tcp) {
-    return async (id, data) => {
-        if (embedded) {
-            await getSharedManager().updateJobData(jobId(id), data);
-            return;
-        }
-        if (!tcp)
-            return;
-        await tcp.send({ cmd: 'Update', id, data });
-    };
-}
-export function createPromoteHandler(embedded, tcp) {
-    return async (id) => {
-        if (embedded) {
-            await getSharedManager().promote(jobId(id));
-            return;
-        }
-        if (!tcp)
-            return;
-        await tcp.send({ cmd: 'Promote', id });
-    };
-}
-export function createChangeDelayHandler(embedded, tcp) {
-    return async (id, delay) => {
-        if (embedded) {
-            await getSharedManager().changeDelay(jobId(id), delay);
-            return;
-        }
-        if (!tcp)
-            return;
-        await tcp.send({ cmd: 'ChangeDelay', id, delay });
-    };
-}
-export function createChangePriorityHandler(embedded, tcp) {
-    return async (id, opts) => {
-        if (embedded) {
-            await getSharedManager().changePriority(jobId(id), opts.priority, opts.lifo);
-            return;
-        }
-        if (!tcp)
-            return;
-        await tcp.send({ cmd: 'ChangePriority', id, priority: opts.priority, lifo: opts.lifo });
-    };
-}
-export function createExtendLockHandler(embedded, tcp) {
-    return async (id, token, duration) => {
-        if (embedded) {
-            const ok = await getSharedManager().extendLock(jobId(id), token, duration);
-            return ok ? duration : 0;
-        }
-        if (!tcp)
-            return 0;
-        const res = await tcp.send({ cmd: 'ExtendLock', id, token, duration });
-        return res.ok === true ? duration : 0;
-    };
-}
-export function createClearLogsHandler(embedded, tcp) {
-    return async (id, keepLogs) => {
-        if (embedded) {
-            getSharedManager().clearLogs(jobId(id), keepLogs);
-            return;
-        }
-        if (!tcp)
-            return;
-        await tcp.send({ cmd: 'ClearLogs', id, keepLogs });
-    };
-}
-export function createMoveToWaitHandler(embedded, tcp) {
-    return async (id, _token) => {
-        if (embedded) {
-            return await getSharedManager().moveActiveToWait(jobId(id));
-        }
-        if (!tcp)
-            return false;
-        const res = await tcp.send({ cmd: 'MoveToWait', id });
-        return res.ok === true;
-    };
-}
-export function createMoveToDelayedHandler(embedded, tcp) {
-    return async (id, timestamp, _token) => {
-        // BullMQ API passes absolute timestamp; server expects relative delay (ms)
-        const delay = Math.max(0, timestamp - Date.now());
-        if (embedded) {
-            await getSharedManager().moveToDelayed(jobId(id), delay);
-            return;
-        }
-        if (!tcp)
-            return;
-        await tcp.send({ cmd: 'MoveToDelayed', id, delay });
-    };
-}
-export function createMoveToWaitingChildrenHandler(embedded, tcp) {
-    return async (id) => {
-        if (embedded) {
-            return await getSharedManager().moveToWaitingChildren(jobId(id));
-        }
-        if (!tcp)
-            return false;
-        throw new Error('moveToWaitingChildren is not supported in TCP mode — no server command available');
-    };
-}
-export function createWaitUntilFinishedHandler(embedded, tcp) {
-    return async (id, _queueEvents, ttl) => {
-        const timeout = ttl ?? 30000;
-        if (embedded) {
-            const manager = getSharedManager();
-            const job = await manager.getJob(jobId(id));
-            if (!job)
-                throw new Error(`Job ${id} not found`);
-            if (job.completedAt)
-                return manager.getResult(jobId(id));
-            const completed = await manager.waitForJobCompletion(jobId(id), timeout);
-            if (!completed)
-                throw new Error(`waitUntilFinished timed out after ${timeout}ms`);
-            return manager.getResult(jobId(id));
-        }
-        if (!tcp)
-            throw new Error('waitUntilFinished: no connection');
-        const res = await tcp.send({ cmd: 'WaitJob', id, timeout });
-        const typed = res;
-        if (!typed.completed)
-            throw new Error(`waitUntilFinished timed out after ${timeout}ms`);
-        return typed.result;
-    };
-}
-export function createDiscardHandler(embedded, tcp) {
-    return (id) => {
-        if (embedded) {
-            void getSharedManager().discard(jobId(id));
-            return;
-        }
-        if (!tcp)
-            return;
-        void tcp.send({ cmd: 'Discard', id });
-    };
-}
-/**
- * getDependencies — compute from internalJob.childrenIds by querying each child's state.
- * No dedicated server API; derive from existing job state queries.
- */
-export function createGetDependenciesHandler(embedded, tcp, internalJob) {
-    return async () => {
-        const childIds = internalJob.childrenIds;
-        const processed = {};
-        const unprocessed = [];
-        for (const cid of childIds) {
-            let state = 'unknown';
-            let result;
-            if (embedded) {
-                const mgr = getSharedManager();
-                state = await mgr.getJobState(cid);
-                if (state === 'completed')
-                    result = mgr.getResult(cid);
-            }
-            else if (tcp) {
-                const r = await tcp.send({ cmd: 'GetState', id: String(cid) });
-                state = r.state ?? 'unknown';
-                if (state === 'completed') {
-                    const rr = await tcp.send({ cmd: 'GetResult', id: String(cid) });
-                    result = rr.result;
-                }
-            }
-            const key = `${internalJob.queue}:${String(cid)}`;
-            if (state === 'completed' || state === 'failed') {
-                processed[key] = result ?? null;
-            }
-            else {
-                unprocessed.push(key);
-            }
-        }
-        return { processed, unprocessed };
-    };
-}
-export function createGetDependenciesCountHandler(embedded, tcp, internalJob) {
-    const getDeps = createGetDependenciesHandler(embedded, tcp, internalJob);
-    return async (id) => {
-        const deps = await getDeps(id);
-        return {
-            processed: Object.keys(deps.processed).length,
-            unprocessed: deps.unprocessed.length,
-        };
-    };
-}
-/**
- * removeDeduplicationKey — no server primitive; throw explicit error so callers
- * learn this isn't supported rather than silently getting `false`.
- */
-export function createRemoveDeduplicationKeyHandler() {
-    return () => Promise.reject(new Error('removeDeduplicationKey is not implemented — no server primitive available'));
-}
+export * from './handlers/completion';
+export * from './handlers/dependencies';
+export * from './handlers/mutations';
+export * from './handlers/queries';

package/dist/client/worker/processorOutcome.d.ts

@@ -0,0 +1,14 @@
+import type { EventEmitter } from 'events';
+import type { Job as InternalJob } from '../../domain/types/job';
+import type { FlowJobData, Job } from '../types';
+import type { FailureContext, ProcessorConfig } from './types';
+import type { ManualMove } from './types';
+/** Settle an explicit processor-owned outcome or nonterminal transition. */
+export declare function handleManualMove<T extends FlowJobData>(manualMove: ManualMove, job: Job<T>, config: {
+    onOutcome?: (succeeded: boolean) => void;
+    emitter: EventEmitter;
+    shouldAbandonOutcome?: () => boolean;
+}, internalJob: InternalJob): Promise<boolean>;
+/** Identify an outcome that lost its processing generation before completion. */
+export declare function isJobNotFoundError(err: Error): boolean;
+export declare function handleJobFailure<T, R>(internalJob: InternalJob, error: unknown, config: ProcessorConfig<T, R>, context: FailureContext<T & FlowJobData>): Promise<void>;

package/dist/client/worker/processorOutcome.js

@@ -0,0 +1,125 @@
+import { DelayedError, UnrecoverableError } from '../errors';
+import { getSharedManager } from '../manager';
+import { computeStackLines } from './processorHandlers';
+import { outcomeWasApplied } from './ackOutcome';
+/** Settle an explicit processor-owned outcome or nonterminal transition. */
+export async function handleManualMove(manualMove, job, config, internalJob) {
+    const result = manualMove.result;
+    if (result?.type === 'pending-transition') {
+        const settlement = await result.pending;
+        manualMove.result = { type: 'transitioned' };
+        if (settlement.status === 'failed' && !config.shouldAbandonOutcome?.()) {
+            config.emitter.emit('error', Object.assign(settlement.error, {
+                context: result.context,
+                jobId: String(internalJob.id),
+            }));
+        }
+        return true;
+    }
+    if (result?.type === 'ignored' || result?.type === 'transitioned') {
+        return true;
+    }
+    if (result?.type === 'failed') {
+        const err = result.error ?? new Error('Job manually moved to failed');
+        job.failedReason = err.message;
+        if (err.stack) {
+            const { stackLines } = computeStackLines(err);
+            job.stacktrace = stackLines.slice(0, internalJob.stackTraceLimit);
+        }
+        config.onOutcome?.(false);
+        config.emitter.emit('failed', job, err);
+        return true;
+    }
+    if (result?.type === 'completed') {
+        job.returnvalue = result.value;
+        config.onOutcome?.(true);
+        config.emitter.emit('completed', job, result.value);
+        return true;
+    }
+    return false;
+}
+/** Identify an outcome that lost its processing generation before completion. */
+export function isJobNotFoundError(err) {
+    return err.message.includes('not found') || err.message.includes('not in processing');
+}
+async function handleDelayedError(internalJob, config, context) {
+    const { embedded, tcp, emitter } = config;
+    if (config.shouldAbandonOutcome?.())
+        return;
+    try {
+        if (embedded) {
+            await getSharedManager().moveToDelayed(internalJob.id, internalJob.backoff || 1000, context.token ?? undefined);
+        }
+        else if (tcp) {
+            await tcp.send({
+                cmd: 'MoveToDelayed',
+                id: internalJob.id,
+                delay: internalJob.backoff || 1000,
+                ...(context.token ? { token: context.token } : {}),
+            });
+        }
+    }
+    catch (delayError) {
+        if (config.shouldAbandonOutcome?.())
+            return;
+        const wrappedError = delayError instanceof Error ? delayError : new Error(String(delayError));
+        if (!isJobNotFoundError(wrappedError)) {
+            emitter.emit('error', Object.assign(wrappedError, { context: 'delay', jobId: context.jobIdStr }));
+        }
+    }
+}
+export async function handleJobFailure(internalJob, error, config, context) {
+    const { embedded, tcp, emitter } = config;
+    const { job, jobIdStr, token } = context;
+    const err = error instanceof Error ? error : new Error(String(error));
+    if (config.shouldAbandonOutcome?.())
+        return;
+    if (err instanceof DelayedError) {
+        await handleDelayedError(internalJob, config, { jobIdStr, token });
+        return;
+    }
+    if (err instanceof UnrecoverableError) {
+        internalJob.maxAttempts = 1;
+        internalJob.attempts = 0;
+    }
+    const { stackLines, wireStack } = computeStackLines(err);
+    try {
+        let applied = true;
+        if (embedded) {
+            const outcome = await getSharedManager().fail(internalJob.id, err.message, token ?? undefined, undefined, wireStack, config.removeOnFail);
+            applied = outcome?.applied !== false;
+        }
+        else if (tcp) {
+            const response = await tcp.send({
+                cmd: 'FAIL',
+                id: internalJob.id,
+                error: err.message,
+                ...(wireStack ? { stack: wireStack } : {}),
+                ...(token ? { token } : {}),
+                ...(err instanceof UnrecoverableError ? { unrecoverable: true } : {}),
+                ...(config.removeOnFail ? { removeOnFail: true } : {}),
+            });
+            if (response.ok !== true) {
+                throw new Error(typeof response.error === 'string' ? response.error : 'FAIL failed');
+            }
+            applied = outcomeWasApplied(response.data);
+        }
+        if (!applied)
+            return;
+    }
+    catch (failError) {
+        if (config.shouldAbandonOutcome?.())
+            return;
+        const wrappedError = failError instanceof Error ? failError : new Error(String(failError));
+        if (!isJobNotFoundError(wrappedError)) {
+            emitter.emit('error', Object.assign(wrappedError, { context: 'fail', jobId: jobIdStr }));
+        }
+        return;
+    }
+    job.failedReason = err.message;
+    if (err.stack) {
+        job.stacktrace = stackLines.slice(0, internalJob.stackTraceLimit);
+    }
+    config.onOutcome?.(false);
+    emitter.emit('failed', job, err);
+}

package/dist/client/worker/runtime/buffer.d.ts

@@ -0,0 +1,8 @@
+import { WorkerLifecycle } from './lifecycle';
+import type { PulledJob, WorkerDelivery } from './state';
+export declare abstract class WorkerBuffer<T = unknown, R = unknown> extends WorkerLifecycle<T, R> {
+    protected registerPulledJobs(items: PulledJob[]): WorkerDelivery[];
+    protected getBufferedJob(): WorkerDelivery | null;
+    protected requeueItem(item: WorkerDelivery): void;
+    protected getNextEligibleJob(): WorkerDelivery | null;
+}

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

@@ -0,0 +1,50 @@
+import { sendHeartbeat } from '../workerHeartbeat';
+import { WorkerLifecycle } from './lifecycle';
+export class WorkerBuffer extends WorkerLifecycle {
+    registerPulledJobs(items) {
+        const deliveries = items.map((item) => this.trackDelivery(item));
+        if (this.opts.useLocks && items.length > 0 && this.tcpPool && this.tcpPool.getPoolSize() > 1) {
+            void sendHeartbeat(this.getHeartbeatDeps());
+        }
+        return deliveries;
+    }
+    getBufferedJob() {
+        if (this.pendingJobsHead >= this.pendingJobs.length)
+            return null;
+        const item = this.pendingJobs[this.pendingJobsHead++];
+        if (this.pendingJobsHead > 500 && this.pendingJobsHead >= this.pendingJobs.length / 2) {
+            this.pendingJobs = this.pendingJobs.slice(this.pendingJobsHead);
+            this.pendingJobsHead = 0;
+        }
+        return item;
+    }
+    requeueItem(item) {
+        if (this.pendingJobsHead > 0) {
+            this.pendingJobs[--this.pendingJobsHead] = item;
+        }
+        else {
+            this.pendingJobs.unshift(item);
+        }
+    }
+    getNextEligibleJob() {
+        if (this.pendingJobsHead >= this.pendingJobs.length)
+            return null;
+        if (!this.groupLimiter)
+            return this.getBufferedJob();
+        const start = this.pendingJobsHead;
+        const end = this.pendingJobs.length;
+        for (let index = start; index < end; index++) {
+            const item = this.pendingJobs[index];
+            if (this.groupLimiter.canProcess(item.job)) {
+                this.pendingJobs[index] = this.pendingJobs[this.pendingJobsHead];
+                this.pendingJobsHead++;
+                if (this.pendingJobsHead > 500 && this.pendingJobsHead >= this.pendingJobs.length / 2) {
+                    this.pendingJobs = this.pendingJobs.slice(this.pendingJobsHead);
+                    this.pendingJobsHead = 0;
+                }
+                return item;
+            }
+        }
+        return null;
+    }
+}

package/dist/client/worker/runtime/control.d.ts

@@ -0,0 +1,26 @@
+import { WorkerState } from './state';
+export declare abstract class WorkerControl<T = unknown, R = unknown> extends WorkerState<T, R> {
+    run(): void;
+    protected subscribeToStalledEvents(): void;
+    pause(): void;
+    resume(): void;
+    isRunning(): boolean;
+    isPaused(): boolean;
+    isClosed(): boolean;
+    get concurrency(): number;
+    set concurrency(value: number);
+    get closing(): Promise<void> | null;
+    waitUntilReady(): Promise<void>;
+    cancelJob(jobId: string, reason?: string): boolean;
+    cancelAllJobs(reason?: string): void;
+    isJobCancelled(jobId: string): boolean;
+    getRateLimiterInfo(): {
+        current: number;
+        max: number;
+        duration: number;
+    } | null;
+    rateLimit(expireTimeMs: number): void;
+    isRateLimited(): boolean;
+    startStalledCheckTimer(): Promise<void>;
+    delay(milliseconds?: number, abortController?: AbortController): Promise<void>;
+}