bunqueue 2.8.25 → 2.8.27

package/README.md

@@ -27,11 +27,15 @@
 
 ## Requirements
 
-bunqueue is **Bun-only** (`bun >= 1.3.9`). The client, TCP transport and persistence
-rely on Bun's runtime APIs (`Bun.connect`, `Bun.file`, `Bun.hash`, …) and ship as
-ESM with extensionless specifiers, so they do **not** run under Node.js. Importing
-the package from Node fails fast with a clear error pointing here rather than a
-cryptic resolver crash. Install Bun from [bun.sh](https://bun.sh) and run with `bun`.
+The bunqueue **server** (and the embedded mode) is **Bun-only** (`bun >= 1.3.9`):
+persistence and transport rely on Bun's runtime APIs. Install Bun from
+[bun.sh](https://bun.sh) and run with `bun`. Importing the `bunqueue` package from
+Node fails fast with a clear error rather than a cryptic resolver crash.
+
+**Your producers and workers don't have to run on Bun.** Official client SDKs
+connect to the server from **Node.js, Deno, Cloudflare Workers**
+([`bunqueue-client`](https://www.npmjs.com/package/bunqueue-client) on npm) and
+**Python** (`bunqueue-client`, PyPI coming soon) — see [One Queue, Any Language](#one-queue-any-language-sdks).
 
 ## Quickstart
 
@@ -626,13 +630,22 @@ await engine.signal(run.id, 'manager-approval', { approved: true });
 
 <p align="center">
   <strong>bunqueue Dashboard</strong><br/>
-  <sub>A visual interface for managing queues, jobs, workers and monitoring in real time. Currently in beta.</sub>
+  <sub>A web dashboard that fully drives your bunqueue server &mdash; queues, jobs, DLQ, cron, webhooks, workers, live activity, SQLite inspector, and an AI Copilot. Open source, currently in beta. Requires Bun.</sub>
 </p>
 
 https://github.com/user-attachments/assets/e8a8d38e-b4a6-4dc8-8360-876c0f24d116
 
+```bash
+bunx bunqueue-dashboard
+```
+
 <p align="center">
-  <sub>Want early access? Reach out at <b>egeominotti@gmail.com</b></sub>
+  <sub>
+    <a href="https://egeominotti.github.io/bunqueue-dashboard/">Live demo</a> &middot;
+    <a href="https://egeominotti.github.io/bunqueue-dashboard/docs/user-guide">User guide</a> &middot;
+    <a href="https://github.com/egeominotti/bunqueue-dashboard">GitHub</a> &middot;
+    <a href="https://www.npmjs.com/package/bunqueue-dashboard">npm: bunqueue-dashboard</a>
+  </sub>
 </p>
 
 ---
@@ -740,7 +753,9 @@ bunqueue is for when you **don't want to run Redis**. SQLite with WAL mode handl
 bun add bunqueue
 ```
 
-> Requires [Bun](https://bun.sh) runtime. Node.js is not supported.
+> The server and embedded mode require the [Bun](https://bun.sh) runtime. To
+> connect **clients** from Node.js, Deno, Cloudflare Workers or Python, use the
+> [SDKs](#one-queue-any-language-sdks) instead.
 
 ## Two Modes
 
@@ -804,6 +819,40 @@ const worker = new Worker(
 await queue.add('process', { data: 'hello' });
 ```
 
+## One Queue, Any Language (SDKs)
+
+The server does all the heavy lifting — retries, priorities, scheduling, DLQ.
+Official client SDKs speak the native TCP protocol (msgpack, pipelined) with
+full feature parity, so producers and workers can live anywhere in your stack:
+
+| Where your code runs | Install | Status |
+| -------------------- | ------- | ------ |
+| **Node.js ≥ 20, Deno ≥ 2, Bun, Cloudflare Workers** | [`npm install bunqueue-client`](https://www.npmjs.com/package/bunqueue-client) | 58/58 e2e per runtime + 11/11 inside workerd |
+| **Python ≥ 3.9** | PyPI coming soon — today: `pip install "git+https://github.com/egeominotti/bunqueue.git#subdirectory=sdk/python"` | 44/44 e2e |
+
+```typescript
+// Node.js / Deno / Cloudflare Workers
+import { Queue, Worker } from 'bunqueue-client';
+
+const queue = new Queue('emails', { host: 'localhost', port: 6789 });
+await queue.add('welcome', { to: 'user@example.com' });
+
+new Worker('emails', async (job) => ({ sent: true }), { concurrency: 10 });
+```
+
+```python
+# Python
+from bunqueue import Queue, Worker
+
+queue = Queue("emails", host="localhost", port=6789)
+queue.add("welcome", {"to": "user@example.com"})
+
+Worker("emails", lambda job: {"sent": True}, concurrency=10).run()
+```
+
+Mix and match: a Next.js API adds jobs, a Python service processes them.
+Docs: [bunqueue.dev/guide/sdks](https://bunqueue.dev/guide/sdks/) · Sources: [`sdk/`](./sdk/)
+
 ### Simple Mode
 
 One object. Queue + Worker + Routes + Middleware + Cron. Zero boilerplate.

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/tcp/connection.d.ts

@@ -26,8 +26,19 @@ export interface ConnectionTarget {
 /**
  * Map client TLS options to the `tls` value accepted by Bun.connect.
  * Returns undefined when TLS is disabled (plaintext, the default).
+ *
+ * The CA is read into bytes (not passed as a `Bun.file` handle): Bun computes
+ * the peer's `authorizationError` from this `ca`, and we enforce it in the
+ * `handshake` handler (see `tlsRequiresVerification` / #109) — Bun.connect
+ * itself never rejects an unauthorized peer on the client side.
  */
 export declare function buildClientTls(tls: boolean | ClientTlsOptions | undefined): true | Record<string, unknown> | undefined;
+/**
+ * Whether the caller asked us to authenticate the server certificate.
+ * Verification is the default for any TLS connection; only an explicit
+ * `rejectUnauthorized: false` opts out (encryption-only). #109
+ */
+export declare function tlsRequiresVerification(tls: boolean | ClientTlsOptions | undefined): boolean;
 /**
  * Establish TCP connection to server
  */

package/dist/client/tcp/connection.js

@@ -2,10 +2,16 @@
  * TCP Connection Handler
  * Manages low-level socket connection and data handling (msgpack binary protocol)
  */
+import { readFileSync } from 'node:fs';
 import { FrameParser, FrameSizeError } from '../../infrastructure/server/protocol';
 /**
  * Map client TLS options to the `tls` value accepted by Bun.connect.
  * Returns undefined when TLS is disabled (plaintext, the default).
+ *
+ * The CA is read into bytes (not passed as a `Bun.file` handle): Bun computes
+ * the peer's `authorizationError` from this `ca`, and we enforce it in the
+ * `handshake` handler (see `tlsRequiresVerification` / #109) — Bun.connect
+ * itself never rejects an unauthorized peer on the client side.
  */
 export function buildClientTls(tls) {
     if (!tls)
@@ -14,9 +20,21 @@ export function buildClientTls(tls) {
         return true;
     return {
         ...(tls.rejectUnauthorized !== undefined && { rejectUnauthorized: tls.rejectUnauthorized }),
-        ...(tls.caFile !== undefined && { ca: Bun.file(tls.caFile) }),
+        ...(tls.caFile !== undefined && { ca: readFileSync(tls.caFile) }),
     };
 }
+/**
+ * Whether the caller asked us to authenticate the server certificate.
+ * Verification is the default for any TLS connection; only an explicit
+ * `rejectUnauthorized: false` opts out (encryption-only). #109
+ */
+export function tlsRequiresVerification(tls) {
+    if (!tls)
+        return false;
+    if (tls === true)
+        return true;
+    return tls.rejectUnauthorized !== false;
+}
 /**
  * Establish TCP connection to server
  */
@@ -29,6 +47,35 @@ export async function createConnection(target, connectTimeout, events) {
         };
         let connectionResolved = false;
         let timeoutId = null;
+        // TLS server-certificate verification. Bun.connect never rejects an
+        // unauthorized peer on the client side, but it DOES compute the peer's
+        // authorizationError and hand it to the `handshake` callback — so we gate
+        // the connection on it ourselves. #109
+        //
+        // Crucially, once a `handshake` handler is registered, Bun fires `open`
+        // BEFORE the TLS handshake completes (without it, `open` fires only after).
+        // So for EVERY TLS connection we must resolve on `handshake`, not `open` —
+        // otherwise the pool writes its first command onto a socket whose handshake
+        // is still in flight and the bytes are lost. Plaintext has no handshake
+        // event, so it still resolves in `open`.
+        const tlsValue = buildClientTls(target.tls);
+        const isTls = tlsValue !== undefined;
+        const verifyTls = tlsRequiresVerification(target.tls);
+        let opened = false;
+        let handshakeOk = !isTls; // plaintext: nothing to wait for; TLS: wait for handshake
+        const maybeResolveOpen = () => {
+            if (opened && handshakeOk && !connectionResolved) {
+                connectionResolved = true;
+                // Clear the connect timeout only now that we are actually resolving.
+                // For TLS, `open` fires BEFORE `handshake`, so clearing the timeout in
+                // `open` would leave the handshake phase unbounded — a stalled/malicious
+                // peer that completes TCP but never drives the TLS handshake (no error,
+                // no close) would hang this promise forever. Keeping the timeout armed
+                // until resolve preserves connectTimeout as a bound over the handshake.
+                cleanup();
+                resolve({ socket: socketData, cleanup });
+            }
+        };
         const cleanup = () => {
             if (timeoutId) {
                 clearTimeout(timeoutId);
@@ -58,7 +105,9 @@ export async function createConnection(target, connectTimeout, events) {
                 }
             },
             open(sock) {
-                cleanup();
+                // NB: do NOT clear the connect timeout here. For TLS, `open` precedes
+                // `handshake`; the timeout must stay armed until `maybeResolveOpen`
+                // actually resolves (or a stalled handshake could hang forever). #109
                 // Enable TCP keepalive so the OS probes idle connections and surfaces a
                 // dead peer (suspended host, NAT/LB drop) via an error/close event,
                 // instead of a half-open socket lingering until tcp_retries2 (~15 min).
@@ -72,8 +121,31 @@ export async function createConnection(target, connectTimeout, events) {
                 }
                 socketData.write = (d) => sock.write(d);
                 socketData.end = () => sock.end();
-                connectionResolved = true;
-                resolve({ socket: socketData, cleanup });
+                opened = true;
+                maybeResolveOpen();
+            },
+            handshake(sock, success, authorizationError) {
+                // Fires only for TLS. When verification is required, a failed handshake
+                // or any authorizationError (wrong/absent CA, self-signed, host
+                // mismatch) must abort — otherwise TLS is encryption-only and an active
+                // MITM can impersonate the broker and harvest the auth token. #109
+                if (verifyTls && (!success || authorizationError)) {
+                    if (!connectionResolved) {
+                        connectionResolved = true;
+                        cleanup();
+                        const why = authorizationError?.message ?? 'handshake failed';
+                        reject(new Error(`TLS verification failed for ${targetDesc}: ${why}`));
+                    }
+                    try {
+                        sock.end();
+                    }
+                    catch {
+                        /* already closing */
+                    }
+                    return;
+                }
+                handshakeOk = true;
+                maybeResolveOpen();
             },
             close() {
                 if (!connectionResolved) {
@@ -99,8 +171,8 @@ export async function createConnection(target, connectTimeout, events) {
                 }
             },
         };
-        // Connect via TCP (optionally wrapped in TLS — protocol is unchanged)
-        const tlsValue = buildClientTls(target.tls);
+        // Connect via TCP (optionally wrapped in TLS — protocol is unchanged).
+        // `tlsValue`/`isTls` were computed above to drive handshake-gated resolve.
         void Bun.connect({
             hostname: target.host ?? 'localhost',
             port: target.port ?? 6789,

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/domain/types/command.d.ts

@@ -16,7 +16,10 @@ export interface PushCommand extends BaseCommand {
     readonly priority?: number;
     readonly delay?: number;
     readonly maxAttempts?: number;
-    readonly backoff?: number;
+    readonly backoff?: number | {
+        type: 'fixed' | 'exponential';
+        delay: number;
+    };
     readonly ttl?: number;
     readonly timeout?: number;
     readonly uniqueKey?: string;
@@ -31,11 +34,24 @@ export interface PushCommand extends BaseCommand {
     readonly removeOnFail?: boolean;
     /** Force immediate persistence to disk (bypass write buffer) */
     readonly durable?: boolean;
-    /** Repeat configuration for recurring jobs */
+    /**
+     * Repeat configuration for recurring jobs. The wire object is preserved
+     * verbatim by `unpack` and consumed by the domain `parseRepeatConfig`, so
+     * the type mirrors `JobInput['repeat']` — under-declaring it (e.g. only
+     * `every`/`limit`/`count`) silently hid `pattern`/`tz`/dates from callers.
+     */
     readonly repeat?: {
         every?: number;
         limit?: number;
+        pattern?: string;
         count?: number;
+        startDate?: number;
+        endDate?: number;
+        tz?: string;
+        immediately?: boolean;
+        prevMillis?: number;
+        offset?: number;
+        jobId?: string;
     };
     /** BullMQ v5 flow failure propagation options */
     readonly failParentOnFailure?: boolean;

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/infrastructure/server/protocol.d.ts

@@ -20,6 +20,13 @@ export declare function validateNumericField(value: unknown, name: string, optio
     max?: number;
     required?: boolean;
 }): string | null;
+/**
+ * Validate the backoff field, which the public JobOptions type allows in two
+ * forms: a plain number (delay ms) or `{ type: 'fixed' | 'exponential', delay
+ * }`. Embedded mode already accepts both (domain parseBackoff); the TCP path
+ * must too, or the object form throws over the wire while working embedded.
+ */
+export declare function validateBackoffField(value: unknown): string | null;
 /** Validate job options numeric fields */
 export declare function validateJobOptions(options: Record<string, unknown>): string | null;
 /** Re-export from shared module for backward compatibility */

package/dist/infrastructure/server/protocol.js

@@ -77,6 +77,28 @@ export function validateNumericField(value, name, options = {}) {
     }
     return null;
 }
+/**
+ * Validate the backoff field, which the public JobOptions type allows in two
+ * forms: a plain number (delay ms) or `{ type: 'fixed' | 'exponential', delay
+ * }`. Embedded mode already accepts both (domain parseBackoff); the TCP path
+ * must too, or the object form throws over the wire while working embedded.
+ */
+export function validateBackoffField(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value === 'object') {
+        const obj = value;
+        if (obj['type'] !== 'fixed' && obj['type'] !== 'exponential') {
+            return "backoff.type must be 'fixed' or 'exponential'";
+        }
+        return validateNumericField(obj['delay'], 'backoff.delay', {
+            min: 0,
+            max: 24 * 60 * 60 * 1000, // max 1 day
+            required: true,
+        });
+    }
+    return validateNumericField(value, 'backoff', { min: 0, max: 24 * 60 * 60 * 1000 }); // max 1 day
+}
 /** Validate job options numeric fields */
 export function validateJobOptions(options) {
     const validations = [
@@ -84,7 +106,7 @@ export function validateJobOptions(options) {
         validateNumericField(options['delay'], 'delay', { min: 0, max: 365 * 24 * 60 * 60 * 1000 }), // max 1 year
         validateNumericField(options['timeout'], 'timeout', { min: 0, max: 24 * 60 * 60 * 1000 }), // max 1 day
         validateNumericField(options['maxAttempts'], 'maxAttempts', { min: 1, max: 1000 }),
-        validateNumericField(options['backoff'], 'backoff', { min: 0, max: 24 * 60 * 60 * 1000 }), // max 1 day
+        validateBackoffField(options['backoff']),
         validateNumericField(options['ttl'], 'ttl', { min: 0, max: 365 * 24 * 60 * 60 * 1000 }), // max 1 year
         validateNumericField(options['stallTimeout'], 'stallTimeout', {
             min: 0,

package/dist/infrastructure/server/tcp.d.ts

@@ -54,6 +54,18 @@ interface ConnectionData {
 export declare function createTcpServer(queueManager: QueueManager, config: TcpServerConfig): {
     server: TCPSocketListener<ConnectionData>;
     connections: Map<string, Socket<ConnectionData>>;
+    /**
+     * Raw Bun socket handlers. Exposed for tests that need to drive the socket
+     * lifecycle directly (e.g. a `data` event arriving before `open` under TLS,
+     * #108) — production code goes through Bun.listen above.
+     */
+    _socketHandlers: {
+        open(socket: Socket<ConnectionData>): void;
+        data(socket: Socket<ConnectionData>, data: Buffer): Promise<void>;
+        close(socket: Socket<ConnectionData>): void;
+        error(_socket: Socket<ConnectionData>, error: Error): void;
+        drain(socket: Socket<ConnectionData>): void;
+    };
     /** Get connection count */
     getConnectionCount(): number;
     /** Broadcast to all connections */

package/dist/infrastructure/server/tcp.js

@@ -103,28 +103,45 @@ export function createTcpServer(queueManager, config) {
             socket.terminate();
         }, idleTimeoutMs);
     }
+    /**
+     * Initialise the per-socket state. Idempotent: safe to call from both `open`
+     * and lazily from `data`. Under native TLS, Bun can deliver a `data` event
+     * BEFORE `open` has run (observed near-deterministically when a Worker boots
+     * its connections concurrently) — the handler would then destructure a null
+     * `socket.data` and the resulting TypeError escalates to the process-level
+     * unhandledRejection handler, taking the whole server down (a pre-auth remote
+     * DoS on an exposed TLS port). Initialising lazily preserves that first frame
+     * instead of dropping it; the guard makes a second `open` a no-op. See #108.
+     */
+    function initConnection(socket) {
+        if (socket.data)
+            return;
+        const clientId = uuid();
+        const state = createConnectionState(clientId);
+        const ctx = {
+            queueManager,
+            authTokens,
+            authenticated: authTokens.size === 0, // Auto-auth if no tokens
+            clientId, // For job ownership tracking
+        };
+        socket.data = {
+            state,
+            frameParser: new FrameParser(),
+            ctx,
+            semaphore: new Semaphore(MAX_CONCURRENT_PER_CONNECTION),
+            writeQueue: new SocketWriteQueue(maxWriteQueueBytes),
+            stallTimer: null,
+        };
+        connections.set(clientId, socket);
+        queueManager.emitDashboardEvent('client:connected', { clientId, transport: 'tcp' });
+    }
     const socketHandlers = {
         open(socket) {
-            const clientId = uuid();
-            const state = createConnectionState(clientId);
-            const ctx = {
-                queueManager,
-                authTokens,
-                authenticated: authTokens.size === 0, // Auto-auth if no tokens
-                clientId, // For job ownership tracking
-            };
-            socket.data = {
-                state,
-                frameParser: new FrameParser(),
-                ctx,
-                semaphore: new Semaphore(MAX_CONCURRENT_PER_CONNECTION),
-                writeQueue: new SocketWriteQueue(maxWriteQueueBytes),
-                stallTimer: null,
-            };
-            connections.set(clientId, socket);
-            queueManager.emitDashboardEvent('client:connected', { clientId, transport: 'tcp' });
+            initConnection(socket);
         },
         async data(socket, data) {
+            // TLS may deliver `data` before `open` — ensure per-socket state exists. #108
+            initConnection(socket);
             const { frameParser, ctx, state, semaphore, writeQueue } = socket.data;
             const rateLimiter = getRateLimiter();
             // Check rate limit
@@ -203,6 +220,10 @@ export function createTcpServer(queueManager, config) {
             await Promise.all(frames.map(processFrame));
         },
         close(socket) {
+            // A socket can close before `open`/`data` ever initialised its state
+            // (e.g. TLS handshake aborted) — nothing to release. #108
+            if (!socket.data)
+                return;
             const clientId = socket.data.state.clientId;
             // Cancel the slowloris stall timer and drop any buffered-but-unwritten
             // bytes; the socket is gone.
@@ -235,6 +256,9 @@ export function createTcpServer(queueManager, config) {
             tcpLog.error('Connection error', { error: error.message });
         },
         drain(socket) {
+            // Can fire before per-socket state is initialised under TLS. #108
+            if (!socket.data)
+                return;
             // Socket is ready for more writes after backpressure: flush any unwritten
             // tail bytes buffered by short writes, preserving frame order.
             socket.data.writeQueue.flush(socket);
@@ -252,6 +276,12 @@ export function createTcpServer(queueManager, config) {
     return {
         server,
         connections,
+        /**
+         * Raw Bun socket handlers. Exposed for tests that need to drive the socket
+         * lifecycle directly (e.g. a `data` event arriving before `open` under TLS,
+         * #108) — production code goes through Bun.listen above.
+         */
+        _socketHandlers: socketHandlers,
         /** Get connection count */
         getConnectionCount() {
             return connections.size;

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.27",
   "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",
@@ -76,12 +76,12 @@
     "msgpackr": "^1.11.8"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.0",
+    "@biomejs/biome": "2.5.1",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@types/bun": "^1.3.9",
-    "bullmq": "^5.70.1",
+    "bullmq": "^5.79.3",
     "elysia": "^1.4.25",
-    "ioredis": "^5.9.3",
+    "ioredis": "^5.11.1",
     "typescript": "^5.9.3",
     "zod": "^4.3.6"
   },
@@ -146,4 +146,4 @@
   "engines": {
     "bun": ">=1.3.9"
   }
-}
+}