bunqueue 2.8.26 → 2.8.28

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/backgroundTasks.js

@@ -105,6 +105,12 @@ function getLockContext(ctx) {
         shardLocks: ctx.shardLocks,
         eventsManager: ctx.eventsManager,
         dashboardEmit: ctx.dashboardEmit,
+        // #110: without storage, handleMaxStallsExceeded's saveDlqEntry/deleteJob
+        // (the #97 fix) silently no-op via optional chaining on the ONLY
+        // production path to checkExpiredLocks — the DLQ move never persists and
+        // SQLite keeps an orphan `active` row. LockContext.storage is optional,
+        // which is why this omission compiled unnoticed since 2.8.17.
+        storage: ctx.storage,
     };
 }
 // ============ Job Timeouts ============

package/dist/application/dlqManager.d.ts

@@ -11,7 +11,7 @@ import type { SqliteStorage } from '../infrastructure/persistence/sqlite';
 export interface DlqContext {
     shards: Shard[];
     jobIndex: Map<JobId, JobLocation>;
-    storage?: SqliteStorage | null;
+    storage: SqliteStorage | null;
 }
 /** Get jobs from DLQ (backward compatible) */
 export declare function getDlqJobs(queue: string, ctx: DlqContext, count?: number): Job[];

package/dist/application/operations/queueControl.d.ts

@@ -19,7 +19,7 @@ export interface QueueControlContext {
     completedJobsData?: MapLike<JobId, Job>;
     jobResults?: MapLike<JobId, unknown>;
     jobLogs?: MapLike<JobId, unknown>;
-    storage?: SqliteStorage | null;
+    storage: SqliteStorage | null;
 }
 /** Pause a queue */
 export declare function pauseQueue(queue: string, ctx: QueueControlContext): void;

package/dist/application/types.d.ts

@@ -92,7 +92,7 @@ export interface LockContext {
     shardLocks: RWLock[];
     eventsManager: EventsManager;
     dashboardEmit?: (event: string, data: Record<string, unknown>) => void;
-    storage?: SqliteStorage | null;
+    storage: SqliteStorage | null;
 }
 /** Context for background tasks */
 export interface BackgroundContext extends QueueManagerState {

package/dist/client/queue/helpers.js

@@ -19,6 +19,10 @@ export function getDlqContext(manager) {
     return {
         shards: getShards(manager),
         jobIndex: manager.getJobIndex(),
+        // #110-class: without storage, retryDlqByFilter's deleteDlqEntry/insertJob
+        // silently no-op — filtered retries were never persisted in embedded mode
+        // (dlq rows resurrected the jobs into the DLQ on restart).
+        storage: manager.storage,
     };
 }
 /** Convert client filter to domain filter */

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/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/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/package.json

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