bunqueue 2.8.8 → 2.8.9

package/dist/client/forwarder.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Forwarder — store-and-forward from a local (edge) queue to a remote
+ * bunqueue server.
+ *
+ * The edge pattern: jobs buffer in the local queue (typically embedded
+ * SQLite on a gateway); the Forwarder drains them to a central server over
+ * TCP/TLS. A remote failure makes the local job fail → local retry/backoff →
+ * local DLQ, so nothing is lost while the uplink is down.
+ *
+ * Idempotency: every forwarded job carries the deterministic remote jobId
+ * `fwd:<localQueueKey>:<localJobId>`. The server dedupes custom jobIds, so a
+ * re-forward after a crash or retry never duplicates the job remotely.
+ */
+import { EventEmitter } from 'events';
+import type { ConnectionOptions, QueueOptions } from './types';
+/** Options for queue.forward() */
+export interface ForwardOptions {
+    /** Remote server connection (host/port/tls/token...) */
+    to: ConnectionOptions;
+    /** Remote queue name (default: same as the source queue) */
+    queue?: string;
+    /** Parallel forwards (default: 4) */
+    concurrency?: number;
+    /** Push to the remote with durable: true (immediate fsync server-side) */
+    durable?: boolean;
+}
+/** Source queue identity + config, provided by Queue.forward() */
+export interface ForwardSource {
+    /** Logical source queue name */
+    name: string;
+    /** Source queue key (prefixKey + name) — used in the deterministic jobId */
+    queueKey: string;
+    prefixKey?: string;
+    embedded: boolean;
+    dataPath?: string;
+    connection?: ConnectionOptions;
+}
+/** Minimal remote-queue surface the Forwarder needs (avoids a Queue import cycle) */
+interface RemoteQueueLike {
+    add(name: string, data: unknown, opts?: {
+        jobId?: string;
+        priority?: number;
+        durable?: boolean;
+    }): Promise<unknown>;
+    close(): Promise<void> | void;
+}
+/** Constructor for the remote queue, injected by Queue.forward() */
+export type RemoteQueueCtor = new (name: string, opts: QueueOptions) => RemoteQueueLike;
+/** Info emitted with each 'forwarded' event */
+export interface ForwardedInfo {
+    /** Local job id */
+    id: string;
+    /** Deterministic remote job id (fwd:<queueKey>:<id>) */
+    remoteId: string;
+    /** Job name */
+    name: string;
+}
+/**
+ * Drains a local queue into a remote bunqueue server.
+ * Create via `queue.forward(options)`; stop with `close()`.
+ */
+export declare class Forwarder extends EventEmitter {
+    on(event: 'forwarded', listener: (info: ForwardedInfo) => void): this;
+    on(event: 'error', listener: (error: Error) => void): this;
+    private readonly remote;
+    private readonly worker;
+    private closed;
+    constructor(source: ForwardSource, options: ForwardOptions, RemoteQueue: RemoteQueueCtor);
+    /** Stop forwarding and release connections. Safe to call more than once. */
+    close(): Promise<void>;
+}
+export {};

package/dist/client/forwarder.js

@@ -0,0 +1,79 @@
+/**
+ * Forwarder — store-and-forward from a local (edge) queue to a remote
+ * bunqueue server.
+ *
+ * The edge pattern: jobs buffer in the local queue (typically embedded
+ * SQLite on a gateway); the Forwarder drains them to a central server over
+ * TCP/TLS. A remote failure makes the local job fail → local retry/backoff →
+ * local DLQ, so nothing is lost while the uplink is down.
+ *
+ * Idempotency: every forwarded job carries the deterministic remote jobId
+ * `fwd:<localQueueKey>:<localJobId>`. The server dedupes custom jobIds, so a
+ * re-forward after a crash or retry never duplicates the job remotely.
+ */
+import { EventEmitter } from 'events';
+import { Worker } from './worker';
+/**
+ * Drains a local queue into a remote bunqueue server.
+ * Create via `queue.forward(options)`; stop with `close()`.
+ */
+export class Forwarder extends EventEmitter {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    remote;
+    worker;
+    closed = false;
+    constructor(source, options, RemoteQueue) {
+        super();
+        this.remote = new RemoteQueue(options.queue ?? source.name, {
+            embedded: false,
+            connection: options.to,
+            autoBatch: { enabled: false },
+        });
+        this.worker = new Worker(source.name, async (job) => {
+            const remoteId = `fwd:${source.queueKey}:${job.id}`;
+            await this.remote.add(job.name, job.data, {
+                jobId: remoteId,
+                ...(job.opts.priority !== undefined && { priority: job.opts.priority }),
+                ...(options.durable && { durable: true }),
+            });
+            const info = { id: job.id, remoteId, name: job.name };
+            // A throwing user listener must not fail a forward that already
+            // succeeded remotely (it would trigger a local retry of a done job).
+            try {
+                this.emit('forwarded', info);
+            }
+            catch {
+                /* listener error — forward itself succeeded */
+            }
+            return info;
+        }, {
+            embedded: source.embedded,
+            dataPath: source.dataPath,
+            connection: source.connection,
+            prefixKey: source.prefixKey,
+            concurrency: options.concurrency ?? 4,
+        });
+        // A remote failure is already handled by the local retry/DLQ path; the
+        // event is observability. Guard: EventEmitter throws on 'error' without
+        // listeners, and a transient uplink failure must never crash the process.
+        this.worker.on('failed', (_job, err) => {
+            if (this.listenerCount('error') > 0)
+                this.emit('error', err);
+        });
+        this.worker.on('error', (err) => {
+            if (this.listenerCount('error') > 0)
+                this.emit('error', err);
+        });
+    }
+    /** Stop forwarding and release connections. Safe to call more than once. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.worker.close();
+        await this.remote.close();
+    }
+}

package/dist/client/index.d.ts

@@ -26,6 +26,8 @@ export { Worker } from './worker';
 export { Bunqueue } from './bunqueue';
 export type { BunqueueOptions, BunqueueMiddleware, RetryStrategy, RetryConfig, CircuitBreakerConfig, TriggerRule, PriorityAgingConfig, BatchProcessor, BatchConfig, JobTtlConfig, BunqueueDeduplicationConfig, BunqueueDebounceConfig, BunqueueDlqConfig, } from './bunqueue';
 export { SandboxedWorker } from './sandboxedWorker';
+export { Forwarder } from './forwarder';
+export type { ForwardOptions, ForwardedInfo } from './forwarder';
 export { QueueEvents } from './events';
 export { QueueGroup } from './queueGroup';
 export { FlowProducer } from './flow';

package/dist/client/index.js

@@ -25,6 +25,7 @@ export { Queue } from './queue';
 export { Worker } from './worker';
 export { Bunqueue } from './bunqueue';
 export { SandboxedWorker } from './sandboxedWorker';
+export { Forwarder } from './forwarder';
 export { QueueEvents } from './events';
 export { QueueGroup } from './queueGroup';
 export { FlowProducer } from './flow';

package/dist/client/queue/queue.d.ts

@@ -3,6 +3,7 @@
  * BullMQ-style queue for job management
  */
 import type { Job, JobOptions, QueueOptions, StallConfig, DlqConfig, DlqEntry, DlqStats, DlqFilter, ChangePriorityOpts, GetDependenciesOpts, JobDependencies, JobDependenciesCount, JobStateType } from '../types';
+import { Forwarder, type ForwardOptions } from '../forwarder';
 import * as countsOps from './operations/counts';
 import * as schedulerOps from './scheduler';
 import type { RepeatOpts, JobTemplate, SchedulerInfo } from './scheduler';
@@ -168,6 +169,14 @@ export declare class Queue<T = unknown> {
         };
         data: number[];
     }>;
+    /**
+     * Drain this queue's jobs to a remote bunqueue server (store-and-forward).
+     * Typical edge pattern: embedded local queue as offline buffer, forwarded
+     * to a central server over TCP/TLS. Remote failures leave jobs local
+     * (retry → DLQ) — nothing is lost while the uplink is down. Forwarded jobs
+     * carry a deterministic remote jobId so re-forwards never duplicate.
+     */
+    forward(options: ForwardOptions): Forwarder;
     disconnect(): Promise<void>;
     close(): void;
 }

package/dist/client/queue/queue.js

@@ -5,6 +5,7 @@
 import { TcpConnectionPool, getSharedPool, releaseSharedPool } from '../tcpPool';
 import { FORCE_EMBEDDED } from './helpers';
 import { AddBatcher } from './addBatcher';
+import { Forwarder } from '../forwarder';
 import { resolveToken } from '../resolveToken';
 import { getSharedManager } from '../manager';
 // Import operation modules
@@ -483,6 +484,24 @@ export class Queue {
     getMetrics(type, start, end) {
         return workersOps.getMetrics(this.ctx, type, start, end);
     }
+    // ============ Forwarding ============
+    /**
+     * Drain this queue's jobs to a remote bunqueue server (store-and-forward).
+     * Typical edge pattern: embedded local queue as offline buffer, forwarded
+     * to a central server over TCP/TLS. Remote failures leave jobs local
+     * (retry → DLQ) — nothing is lost while the uplink is down. Forwarded jobs
+     * carry a deterministic remote jobId so re-forwards never duplicate.
+     */
+    forward(options) {
+        return new Forwarder({
+            name: this.name,
+            queueKey: this.queueKey,
+            prefixKey: this.prefixKey || undefined,
+            embedded: this.embedded,
+            dataPath: this.opts.dataPath,
+            connection: this.opts.connection,
+        }, options, Queue);
+    }
     // ============ Connection ============
     async disconnect() {
         if (this.addBatcher) {

package/package.json

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