bunqueue 2.8.25 → 2.8.26

package/dist/application/operations/jobManagement.js

@@ -206,6 +206,11 @@ export async function moveJobToDelayed(jobId, delay, ctx) {
         shard.incrementQueued(jobId, isDelayed, job.createdAt, job.queue, job.runAt);
         ctx.jobIndex.set(jobId, { type: 'queue', shardIdx: idx, queueName: job.queue });
     });
+    // Persist the move so the delay survives a restart: the on-disk row was
+    // `state='active'` with the old run_at, which recovery would otherwise treat as a
+    // stalled active job. updateRunAt re-derives 'delayed' from the future run_at and
+    // clears started_at.
+    ctx.storage?.updateRunAt(jobId, job.runAt);
     // Emit delayed event (BullMQ v5)
     ctx.eventsManager.broadcast({
         eventType: "delayed" /* EventType.Delayed */,

package/dist/application/operations/jobStateTransitions.js

@@ -57,6 +57,9 @@ export async function changeWaitingDelay(jobId, delay, ctx) {
         if (!job)
             return false;
         q.updateRunAt(jobId, newRunAt);
+        // Persist so the delay survives a restart (otherwise recovery reloads the
+        // stale on-disk run_at and the job is immediately pullable again).
+        ctx.storage?.updateRunAt(jobId, newRunAt);
         return true;
     });
 }

package/dist/application/operations/push.js

@@ -17,12 +17,32 @@ function handleCustomId(input, shard, ctx) {
     }
     const id = jobId(input.customId);
     const existing = ctx.customIdMap.get(input.customId);
-    // If the existing job is still queued, the add is idempotent — return it.
-    if (existing) {
+    // Re-adding an existing custom id while its job is UNFINISHED is an idempotent
+    // no-op (BullMQ parity): return the existing job, never a second insert of the
+    // same deterministic id (which would collide on the jobs.id PRIMARY KEY). Three
+    // unfinished states are covered:
+    //   • waiting/delayed/prioritized — live in the priority queue → return the job.
+    //   • waiting-children — tracked under 'queue' but held in shard.waitingDeps (its
+    //     row is already persisted) → idempotent skip via the existing id.
+    //   • active (processing) — popped from the queue, still running on a worker; its
+    //     row survives on disk → idempotent skip via the existing id.
+    // PushContext has no processingShards, so for the latter two we cannot fetch the
+    // live Job here; pushJob rebuilds a placeholder { ...job, id } after createJob,
+    // exactly like handleDeduplication's active path. Completed (#92) and DLQ jobs
+    // are terminal and fall through to the reuse path below.
+    if (existing && !ctx.completedJobs.has(id)) {
         const location = ctx.jobIndex.get(existing);
-        const existingJob = location?.type === 'queue' ? shard.getQueue(location.queueName).find(existing) : null;
-        if (existingJob) {
-            return { skip: true, existingJob };
+        if (location?.type === 'queue') {
+            const existingJob = shard.getQueue(location.queueName).find(existing);
+            if (existingJob) {
+                return { skip: true, existingJob };
+            }
+            if (shard.waitingDeps.has(existing)) {
+                return { skip: true, existingId: id };
+            }
+        }
+        else if (location?.type === 'processing') {
+            return { skip: true, existingId: id };
         }
     }
     // Reuse path: the id is free in the queue (no mapping, or the prior job is
@@ -40,6 +60,13 @@ function handleCustomId(input, shard, ctx) {
         ctx.jobIndex.delete(id);
         ctx.storage?.deleteJob(id); // removes the surviving row + result + any buffered insert
     }
+    // NOTE on ORPHAN rows: a durable jobs row can outlive its in-memory tracking when
+    // obliterate() (fire-and-forget void over TCP) or a buffer flush races an in-flight
+    // durable insert. Reaching the reuse path with such a stale row no longer throws —
+    // the insert statements use ON CONFLICT(id) DO UPDATE (upsert), so the orphan is
+    // overwritten in place at insert time with ZERO per-push cost. We deliberately do
+    // NOT pre-delete here: deleteJob() is a synchronous DELETE + O(buffer) scan inside
+    // the shard lock and would halve customId push/addBulk throughput.
     // A recycled custom id may carry a stale timeout marker from a prior job (which
     // may have DLQ'd, so it is NOT in completedJobs above). Clear it so the new
     // job's stall-retry recovery is not wrongly discarded — otherwise the
@@ -158,7 +185,15 @@ export async function pushJob(queue, input, ctx) {
         // Check custom ID idempotency INSIDE lock to prevent race conditions
         const customIdResult = handleCustomId(input, shard, ctx);
         if (customIdResult.skip) {
-            result = { job: customIdResult.existingJob, persisted: false };
+            // Idempotent re-add: return the live queued job if we have it, otherwise
+            // (active / waiting-children) a placeholder carrying the existing id so the
+            // caller sees the right id without inserting a duplicate row.
+            result = {
+                job: 'existingJob' in customIdResult
+                    ? customIdResult.existingJob
+                    : createJob(customIdResult.existingId, queue, input, now),
+                persisted: false,
+            };
             return;
         }
         const job = createJob(customIdResult.id, queue, input, now);
@@ -218,7 +253,10 @@ export async function pushJobBatch(queue, inputs, ctx) {
             // Check custom ID idempotency
             const customIdResult = handleCustomId(input, shard, ctx);
             if (customIdResult.skip) {
-                resultIds.push(customIdResult.existingJob.id);
+                // Idempotent re-add (queued, active, or waiting-children) — no insert.
+                resultIds.push('existingJob' in customIdResult
+                    ? customIdResult.existingJob.id
+                    : customIdResult.existingId);
                 continue;
             }
             const job = createJob(customIdResult.id, queue, input, now);

package/dist/application/queueManager.js

@@ -978,7 +978,15 @@ export class QueueManager {
         return jobMgmt.promoteJob(jobId, this.contextFactory.getJobMgmtContext());
     }
     async moveToDelayed(jobId, delay) {
-        return jobMgmt.moveJobToDelayed(jobId, delay, this.contextFactory.getJobMgmtContext());
+        // moveToDelayed and changeDelay share identical routing in this engine: a job
+        // already in the queue (waiting/prioritized/delayed) gets its runAt updated in
+        // place so it becomes (or stays) delayed; an active/processing job is moved back
+        // to the queue with the new delay. Delegate to changeDelay so the in-queue case
+        // is handled — previously moveJobToDelayed only handled `processing` jobs, making
+        // a WAITING job a silent no-op over TCP/HTTP/MCP. Mirrors the embedded client's
+        // moveJobToDelayed branching (changeWaitingDelay for in-queue, moveJobToDelayed
+        // for active). See src/client/queue/jobMove.ts.
+        return this.changeDelay(jobId, delay);
     }
     async changeDelay(jobId, delay) {
         const ctx = this.contextFactory.getJobMgmtContext();

package/dist/client/jobConversionHelpers.js

@@ -28,7 +28,11 @@ export function buildJobProperties(job, name, stacktrace, token, processedBy) {
         opts: jobOpts,
         token,
         processedBy,
-        deduplicationId: job.customId ?? undefined,
+        // deduplicationId reflects the requested jobId OR deduplication.id. customId
+        // now holds ONLY an explicit jobId (the dedup id rides on uniqueKey since the
+        // dedup-replace fix), so fall back to uniqueKey — mirrors the TCP proxy's
+        // `opts.jobId ?? opts.deduplication?.id` (#90).
+        deduplicationId: job.customId ?? job.uniqueKey ?? undefined,
         repeatJobKey: buildRepeatJobKey(job),
         attemptsStarted: job.attempts,
     };

package/dist/client/queue/jobMove.js

@@ -78,7 +78,19 @@ export async function moveJobToDelayed(ctx, id, timestamp, _token) {
         }
     }
     else {
-        await ctx.tcp.send({ cmd: 'MoveToDelayed', id, timestamp });
+        // The public API takes an ABSOLUTE timestamp, but the server works in relative
+        // delay (runAt = now + delay) and both MoveToDelayedCommand and
+        // handleMoveToDelayed read the wire field `delay`. Sending `timestamp` left
+        // `delay` undefined server-side → runAt = now + undefined = NaN (an active job
+        // was re-queued as `waiting` with the delay dropped) or a silent no-op (a
+        // waiting job). Convert to relative delay here so the wire field matches.
+        const delay = Math.max(0, timestamp - Date.now());
+        const response = await ctx.tcp.send({ cmd: 'MoveToDelayed', id, delay });
+        // Surface server-side failures instead of silently ignoring the response
+        // (e.g. the job was completed/removed before the command arrived).
+        if (response.ok === false) {
+            throw new Error(typeof response.error === 'string' ? response.error : 'Failed to move job to delayed');
+        }
     }
 }
 /** Move job to waiting-children state */

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

@@ -44,7 +44,12 @@ export async function add(ctx, jobName, data, opts = {}) {
             ttl: merged.ttl,
             timeout: merged.timeout,
             uniqueKey: merged.deduplication?.id,
-            customId: merged.jobId ?? merged.deduplication?.id,
+            // Only an explicit jobId becomes the customId. The dedup id is carried by
+            // `uniqueKey` above into handleDeduplication (suppress/replace/extend). If we
+            // also mirrored it into customId, handleCustomId would short-circuit the re-add
+            // as an idempotent no-op BEFORE replace/extend run — silently dropping them in
+            // embedded mode. TCP/bulk already use `customId: jobId` only; this matches them.
+            customId: merged.jobId,
             dependsOn: merged.dependsOn?.map((id) => jobId(id)),
             tags: merged.tags,
             groupId: merged.groupId,

package/dist/client/queue/workers.js

@@ -28,8 +28,10 @@ export async function getMetrics(ctx, type, _start, _end) {
     const response = await ctx.tcp.send({ cmd: 'Metrics' });
     if (!response.ok)
         return { meta: { count: 0 }, data: [] };
-    const stats = response.stats;
-    const count = type === 'completed' ? (stats?.completed ?? 0) : (stats?.dlq ?? 0);
+    // The Metrics handler replies with { ok, metrics: { totalCompleted, totalFailed, ... } }
+    // (resp.metrics). Reading a non-existent `response.stats` always yielded 0.
+    const metrics = response.metrics;
+    const count = type === 'completed' ? (metrics?.totalCompleted ?? 0) : (metrics?.totalFailed ?? 0);
     return { meta: { count }, data: [] };
 }
 /** Trim events (no-op in bunqueue - events are real-time) */

package/dist/client/workflow/executor.js

@@ -89,10 +89,23 @@ export class WorkflowExecutor {
             clearTimeout(timer);
             this.timeoutTimers.delete(executionId);
         }
+        // Always record the payload (idempotent) and notify listeners. A signal that
+        // lands before the run parks at its waitFor is still consumed there, via the
+        // `signals[event] !== undefined` gate in runWaitFor.
         exec.signals[event] = payload;
+        this.emitter?.emitSignal('signal:received', exec.id, exec.workflowName, event, payload);
+        // Resume only a genuinely-parked run (state 'waiting'), and only once. The state
+        // check and the flip to 'running' are synchronous — no `await` between them — so a
+        // second concurrent/duplicate signal() (which can only run after the first yields
+        // at `await this.enqueue`, by which point `store.update` has persisted 'running')
+        // observes 'running' and returns early. This collapses duplicate/concurrent
+        // signals to a single resume, so every step after the waitFor runs exactly once.
+        if (exec.state !== 'waiting') {
+            this.store.update(exec);
+            return;
+        }
         exec.state = 'running';
         this.store.update(exec);
-        this.emitter?.emitSignal('signal:received', exec.id, exec.workflowName, event, payload);
         await this.enqueue(exec);
     }
     getExecution(id) {

package/dist/infrastructure/persistence/sqlite.d.ts

@@ -107,6 +107,15 @@ export declare class SqliteStorage {
     deleteJob(jobId: JobId): void;
     /** Update a job's data blob (e.g. after adding __parentId) */
     updateJobData(jobId: JobId, data: unknown): void;
+    /**
+     * Persist a delay change (moveToDelayed / changeDelay) so the new `run_at`
+     * survives a restart. Without this the delay lives only in the in-memory heap:
+     * recovery reloads the stale on-disk `run_at` and the job is immediately
+     * pullable again. State is re-derived from `run_at` (future → 'delayed'),
+     * mirroring the insert convention; `started_at` is cleared because a job moved
+     * back to the queue from `active` is no longer running.
+     */
+    updateRunAt(jobId: JobId, runAt: number): void;
     /** Update a job's children_ids blob and parent_id */
     updateJobChildrenIds(jobId: JobId, childrenIds: JobId[]): void;
     getJob(id: JobId): Job | null;

package/dist/infrastructure/persistence/sqlite.js

@@ -364,6 +364,27 @@ export class SqliteStorage {
             this.db.prepare('UPDATE jobs SET data = ? WHERE id = ?').run(pack(data), jobId);
         });
     }
+    /**
+     * Persist a delay change (moveToDelayed / changeDelay) so the new `run_at`
+     * survives a restart. Without this the delay lives only in the in-memory heap:
+     * recovery reloads the stale on-disk `run_at` and the job is immediately
+     * pullable again. State is re-derived from `run_at` (future → 'delayed'),
+     * mirroring the insert convention; `started_at` is cleared because a job moved
+     * back to the queue from `active` is no longer running.
+     */
+    updateRunAt(jobId, runAt) {
+        // Flush a still-buffered insert first (like markActive/markCompleted/markFailed)
+        // so the UPDATE lands on a real row — otherwise the delay would be lost across a
+        // restart when the job was added (non-durable) and re-delayed within the same
+        // ~10ms write-buffer window.
+        this.flushIfBuffered(jobId);
+        this.safeWrite(() => {
+            const state = runAt > Date.now() ? 'delayed' : 'waiting';
+            this.db
+                .prepare('UPDATE jobs SET run_at = ?, state = ?, started_at = NULL WHERE id = ?')
+                .run(runAt, state, jobId);
+        });
+    }
     /** Update a job's children_ids blob and parent_id */
     updateJobChildrenIds(jobId, childrenIds) {
         this.safeWrite(() => {

package/dist/infrastructure/persistence/sqliteBatch.js

@@ -77,11 +77,29 @@ export class BatchInsertManager {
         if (!stmt) {
             const rowPlaceholder = '(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)';
             const placeholders = Array(size).fill(rowPlaceholder).join(', ');
+            // ON CONFLICT(id) DO UPDATE (upsert): a colliding id overwrites in place instead
+            // of failing the whole flush. Without it, one stale ORPHAN row (left when
+            // obliterate()/a flush raced an in-flight insert) makes the batch throw UNIQUE,
+            // and reportLostJobs() then drops EVERY innocent job batched in the same flush
+            // window. Per-row conflict resolution isolates the collision; new ids stay a
+            // plain INSERT (zero extra cost). jobs has no triggers/FKs → no cascade.
             const sql = `INSERT INTO jobs (
         id, queue, data, priority, created_at, run_at, attempts, max_attempts,
         backoff, ttl, timeout, unique_key, custom_id, depends_on, parent_id,
         children_ids, tags, state, lifo, group_id, remove_on_complete, remove_on_fail, stall_timeout, timeline
-      ) VALUES ${placeholders}`;
+      ) VALUES ${placeholders}
+      ON CONFLICT(id) DO UPDATE SET
+        queue=excluded.queue, data=excluded.data, priority=excluded.priority,
+        created_at=excluded.created_at, run_at=excluded.run_at, attempts=excluded.attempts,
+        max_attempts=excluded.max_attempts, backoff=excluded.backoff, ttl=excluded.ttl,
+        timeout=excluded.timeout, unique_key=excluded.unique_key, custom_id=excluded.custom_id,
+        depends_on=excluded.depends_on, parent_id=excluded.parent_id, children_ids=excluded.children_ids,
+        tags=excluded.tags, state=excluded.state, lifo=excluded.lifo, group_id=excluded.group_id,
+        remove_on_complete=excluded.remove_on_complete, remove_on_fail=excluded.remove_on_fail,
+        stall_timeout=excluded.stall_timeout, timeline=excluded.timeline,
+        started_at=excluded.started_at, completed_at=excluded.completed_at,
+        progress=excluded.progress, progress_msg=excluded.progress_msg,
+        last_heartbeat=excluded.last_heartbeat, stacktrace=excluded.stacktrace`;
             stmt = this.db.prepare(sql);
             // Cache statements for common batch sizes (1-100)
             if (size <= 100) {

package/dist/infrastructure/persistence/statements.js

@@ -4,6 +4,12 @@
  */
 /** SQL statements */
 export const SQL_STATEMENTS = {
+    // ON CONFLICT(id) DO UPDATE (upsert): a brand-new id is a plain INSERT (zero extra
+    // cost); a colliding id overwrites the existing row in place. This makes durable
+    // inserts idempotent against ORPHAN rows — a jobs row that outlived its in-memory
+    // tracking when obliterate() or a buffer flush raced an in-flight insert — without
+    // any per-push delete on the hot path. jobs has no triggers/FKs, so DO UPDATE has
+    // no cascade side effects (unlike REPLACE = DELETE+INSERT).
     insertJob: `
     INSERT INTO jobs (
       id, queue, data, priority, created_at, run_at, attempts,
@@ -16,6 +22,22 @@ export const SQL_STATEMENTS = {
       ?, ?, ?, ?, ?, ?, ?,
       ?, ?, ?, ?
     )
+    ON CONFLICT(id) DO UPDATE SET
+      queue=excluded.queue, data=excluded.data, priority=excluded.priority,
+      created_at=excluded.created_at, run_at=excluded.run_at, attempts=excluded.attempts,
+      max_attempts=excluded.max_attempts, backoff=excluded.backoff, ttl=excluded.ttl,
+      timeout=excluded.timeout, unique_key=excluded.unique_key, custom_id=excluded.custom_id,
+      depends_on=excluded.depends_on, parent_id=excluded.parent_id, children_ids=excluded.children_ids,
+      tags=excluded.tags, state=excluded.state, lifo=excluded.lifo, group_id=excluded.group_id,
+      remove_on_complete=excluded.remove_on_complete, remove_on_fail=excluded.remove_on_fail,
+      stall_timeout=excluded.stall_timeout, timeline=excluded.timeline,
+      -- Per-execution columns are NOT in the INSERT column list, so excluded.<col>
+      -- resolves to each column's DEFAULT (NULL / 0) — i.e. the fresh-job value. Reset
+      -- them too, otherwise an upsert over an ORPHAN row would leave a brand-new job
+      -- carrying the prior life's progress=100 / completed_at / stacktrace etc.
+      started_at=excluded.started_at, completed_at=excluded.completed_at,
+      progress=excluded.progress, progress_msg=excluded.progress_msg,
+      last_heartbeat=excluded.last_heartbeat, stacktrace=excluded.stacktrace
   `,
     updateJobState: 'UPDATE jobs SET state = ?, started_at = ?, timeline = ? WHERE id = ?',
     completeJob: 'UPDATE jobs SET state = ?, completed_at = ?, progress = 100, timeline = ? WHERE id = ?',

package/dist/shared/webhookValidation.js

@@ -30,6 +30,63 @@ function checkPrivateIpv4(hostname) {
         return 'Webhook URL cannot point to loopback IP';
     return null;
 }
+/**
+ * Extract the embedded IPv4 from an IPv4-mapped IPv6 hostname, as dotted-decimal,
+ * or null if the hostname is not such a mapped address.
+ *
+ * The WHATWG URL parser normalizes `[::ffff:127.0.0.1]` to the hex form
+ * `[::ffff:7f00:1]`, so both must be handled: the dotted tail (`::ffff:a.b.c.d`)
+ * and the two-hextet tail (`::ffff:XXXX:YYYY`). These resolve to the embedded IPv4
+ * (e.g. 127.0.0.1) and so must run through the private/loopback octet check (SSRF).
+ */
+function extractMappedIpv4(hostname) {
+    let h = hostname;
+    if (h.startsWith('[') && h.endsWith(']'))
+        h = h.slice(1, -1);
+    const lower = h.toLowerCase();
+    // IPv4-mapped (::ffff:a.b.c.d) AND the deprecated IPv4-compatible (::a.b.c.d) form
+    // both embed an IPv4 in the low 32 bits — and the WHATWG parser normalizes the
+    // dotted tail to two hextets (::ffff:7f00:1 / ::7f00:1). Unwrap either prefix.
+    let tail;
+    if (lower.startsWith('::ffff:'))
+        tail = h.slice('::ffff:'.length);
+    else if (lower.startsWith('::') && lower.length > 2)
+        tail = h.slice('::'.length);
+    else
+        return null;
+    // Dotted form: a.b.c.d
+    if (/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(tail))
+        return tail;
+    // Hex-normalized form: XXXX:YYYY (each hextet 1-4 hex digits) → low 32 bits
+    const hx = tail.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+    if (hx) {
+        const hi = Number.parseInt(hx[1], 16);
+        const lo = Number.parseInt(hx[2], 16);
+        return `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
+    }
+    return null;
+}
+/**
+ * Block IPv6 private / link-local / unspecified ranges that resolve to the local
+ * network: ULA `fc00::/7` (first hextet fc__/fd__), link-local `fe80::/10`
+ * (fe80–febf), and `::` (unspecified). Returns an error message or null.
+ */
+function checkBlockedIpv6(hostname) {
+    let h = hostname;
+    if (h.startsWith('[') && h.endsWith(']'))
+        h = h.slice(1, -1);
+    const lower = h.toLowerCase();
+    if (!lower.includes(':'))
+        return null; // not an IPv6 literal
+    if (lower === '::')
+        return 'Webhook URL cannot point to unspecified IP';
+    const first = lower.split(':')[0];
+    if (/^f[cd][0-9a-f]{0,2}$/.test(first))
+        return 'Webhook URL cannot point to private (ULA) IP';
+    if (/^fe[89ab][0-9a-f]?$/.test(first))
+        return 'Webhook URL cannot point to link-local IP';
+    return null;
+}
 /** Check if hostname is a cloud metadata endpoint */
 function isCloudMetadata(hostname) {
     return (hostname === '169.254.169.254' ||
@@ -55,6 +112,19 @@ export function validateWebhookUrl(url) {
     const hostname = parsed.hostname.toLowerCase();
     if (isLocalhost(hostname))
         return 'Webhook URL cannot point to localhost';
+    // IPv4-mapped / IPv4-compatible IPv6 (e.g. [::ffff:127.0.0.1] → [::ffff:7f00:1],
+    // or [::127.0.0.1] → [::7f00:1]) resolves to the embedded IPv4 — unwrap it so
+    // loopback/private octets are blocked (SSRF).
+    const mapped = extractMappedIpv4(hostname);
+    if (mapped) {
+        const mappedError = checkPrivateIpv4(mapped);
+        if (mappedError)
+            return mappedError;
+    }
+    // IPv6 private (ULA) / link-local / unspecified ranges.
+    const ipv6Error = checkBlockedIpv6(hostname);
+    if (ipv6Error)
+        return ipv6Error;
     const ipError = checkPrivateIpv4(hostname);
     if (ipError)
         return ipError;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunqueue",
-  "version": "2.8.25",
+  "version": "2.8.26",
   "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",