bunqueue-client 0.1.5 → 0.1.7

package/src/ack-batcher.ts

@@ -0,0 +1,76 @@
+/**
+ * Batches completed-job ACKs into ACKB round-trips for higher throughput.
+ *
+ * Opt-in (see WorkerOptions.ackBatch). Items flush when the buffer reaches
+ * `maxSize` or after `maxDelayMs`, whichever comes first; `flush()` drains the
+ * rest on shutdown. Each item's `onSettled` fires after the batch is acked
+ * (or errored), so the worker keeps a job "active" — and its lock renewed —
+ * until the server has confirmed the ack.
+ */
+
+import type { Connection } from './connection.js';
+import { compact } from './frame.js';
+
+export interface AckItem {
+  id: string;
+  token: string;
+  result: unknown;
+  /** Called once the batch settles: `err` set on failure, undefined on ack. */
+  onSettled: (err?: unknown) => void;
+}
+
+export class AckBatcher {
+  private buffer: AckItem[] = [];
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(
+    private readonly connection: Connection,
+    private readonly maxSize: number,
+    private readonly maxDelayMs: number
+  ) {}
+
+  add(item: AckItem): void {
+    this.buffer.push(item);
+    if (this.buffer.length >= this.maxSize) {
+      void this.flush();
+    } else if (!this.timer) {
+      this.timer = setTimeout(() => void this.flush(), this.maxDelayMs);
+      this.timer.unref?.(); // don't keep the process alive for a pending flush
+    }
+  }
+
+  /** Send the buffered ACKs as one ACKB (no-op when empty). */
+  async flush(): Promise<void> {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    if (this.buffer.length === 0) return;
+    const batch = this.buffer;
+    this.buffer = [];
+    // Capture the wire outcome first; settle callbacks run OUTSIDE the try so
+    // a throwing callback can neither be re-invoked with an error (double
+    // settle) nor starve the remaining items of their callback.
+    let error: unknown;
+    try {
+      await this.connection.call(
+        compact({
+          cmd: 'ACKB',
+          ids: batch.map((b) => b.id),
+          tokens: batch.map((b) => b.token),
+          results: batch.map((b) => b.result),
+        }) as { cmd: string }
+      );
+    } catch (err) {
+      error = err ?? new Error('ACKB failed');
+    }
+    for (const item of batch) {
+      try {
+        item.onSettled(error);
+      } catch {
+        // A callback error (e.g. an unhandled 'error' emit in the worker)
+        // must never prevent the other items from settling.
+      }
+    }
+  }
+}

package/src/backpressure.ts

@@ -0,0 +1,40 @@
+/**
+ * Backpressure gate: bounds the number of in-flight commands on a connection.
+ *
+ * When the in-flight count reaches `max`, `acquire()` parks the caller until a
+ * slot frees (a pending command settles). This turns unbounded memory growth
+ * under a fast producer / slow server into cooperative flow control. `max <= 0`
+ * disables the gate (unbounded, the default).
+ */
+export class Backpressure {
+  private readonly waiters: Array<() => void> = [];
+
+  constructor(
+    private readonly max: number,
+    private readonly onWait?: () => void
+  ) {}
+
+  /** Resolve immediately if under the limit, else park until a slot frees. */
+  acquire(inFlight: number): Promise<void> | void {
+    if (this.max <= 0 || inFlight < this.max) return;
+    this.onWait?.();
+    return new Promise<void>((resolve) => {
+      this.waiters.push(resolve);
+    });
+  }
+
+  /** Release one parked caller (call when a pending command settles). */
+  release(): void {
+    this.waiters.shift()?.();
+  }
+
+  /** Release every parked caller (call on teardown so none hang forever). */
+  clear(): void {
+    while (this.waiters.length > 0) this.waiters.shift()?.();
+  }
+
+  /** Number of callers currently parked. */
+  get waiting(): number {
+    return this.waiters.length;
+  }
+}

package/src/bunqueue/bunqueue.ts

@@ -90,7 +90,18 @@ export class Bunqueue<T = unknown, R = unknown> {
 
     // DLQ & rate limit manager
     this.dlqrl = new DlqRateLimitManager<T>(this.queue);
-    if (opts.dlq) void this.dlqrl.setDlqConfig(opts.dlq);
+    // Fire-and-forget config push: without the catch, an unreachable server at
+    // construction time becomes an unhandled rejection that kills the process.
+    // Route the failure to the worker's 'error' event (the channel every other
+    // background command failure uses); with no listener attached, swallow it
+    // like pause()/resume() do — an unlistened 'error' emit would itself throw.
+    if (opts.dlq) {
+      void this.dlqrl.setDlqConfig(opts.dlq).catch((err: unknown) => {
+        if (this.worker.listenerCount('error') > 0) {
+          this.worker.emit('error', err instanceof Error ? err : new Error(String(err)));
+        }
+      });
+    }
 
     // Subsystems
     this.cb = opts.circuitBreaker

package/src/connection-pool.ts

@@ -0,0 +1,71 @@
+/**
+ * A round-robin pool of TCP connections for producer-side throughput.
+ *
+ * Each `call()` is dispatched to the next connection, so independent commands
+ * (PUSH, queries, control) fan out across N sockets instead of head-of-lining
+ * on one. Use it for {@link Queue} / {@link FlowProducer}; NOT for a Worker,
+ * whose pull→ack flow is bound to a single connection's lock ownership and
+ * reconnect/registration lifecycle.
+ *
+ * Satisfies {@link ConnectionLike}, so it is a drop-in for a single Connection.
+ * Lifecycle events from every member connection are re-emitted here.
+ */
+
+import { EventEmitter } from 'node:events';
+import { Connection } from './connection.js';
+import type { Command, ConnectionLike, ConnectionOptions, Response } from './connection-types.js';
+import { LIFECYCLE_EVENTS } from './observability.js';
+
+export class ConnectionPool extends EventEmitter implements ConnectionLike {
+  private readonly connections: Connection[];
+  private cursor = 0;
+
+  constructor(size: number, options: ConnectionOptions = {}) {
+    super();
+    const n = Math.max(1, Math.floor(size));
+    this.connections = Array.from({ length: n }, () => {
+      const conn = new Connection(options);
+      for (const event of LIFECYCLE_EVENTS) {
+        conn.on(event, (payload) => this.emit(event, payload));
+      }
+      return conn;
+    });
+  }
+
+  /** How many connections back this pool. */
+  get size(): number {
+    return this.connections.length;
+  }
+
+  private next(): Connection {
+    const conn = this.connections[this.cursor];
+    this.cursor = (this.cursor + 1) % this.connections.length;
+    return conn;
+  }
+
+  call<R = Response>(command: Command, timeoutMs?: number): Promise<R> {
+    return this.next().call<R>(command, timeoutMs);
+  }
+
+  ping(): Promise<boolean> {
+    return this.connections[0].ping();
+  }
+
+  async connect(): Promise<void> {
+    await Promise.all(this.connections.map((conn) => conn.connect()));
+  }
+
+  close(): void {
+    for (const conn of this.connections) conn.close();
+  }
+
+  /** True while at least one member connection is up. */
+  get isConnected(): boolean {
+    return this.connections.some((conn) => conn.isConnected);
+  }
+
+  /** Representative generation (first connection); pools are producer-side. */
+  get generation(): number {
+    return this.connections[0].generation;
+  }
+}

package/src/connection-types.ts

@@ -1,19 +1,41 @@
 /** Connection option and message types. */
 
+import type { Observability } from './observability.js';
+
 export type TlsOption = boolean | { caFile?: string; rejectUnauthorized?: boolean } | undefined;
 
-export interface ConnectionOptions {
+export interface ConnectionOptions extends Observability {
   host?: string;
   port?: number;
   token?: string;
   tls?: TlsOption;
   connectTimeoutMs?: number;
   commandTimeoutMs?: number;
+  /**
+   * Max in-flight commands before {@link Connection.call} applies backpressure
+   * (awaits a free slot). 0 / undefined = unbounded. Bounds memory under load.
+   */
+  maxInFlight?: number;
 }
 
 export type Command = Record<string, unknown> & { cmd: string };
 export type Response = Record<string, unknown> & { ok: boolean };
 
+/**
+ * The connection surface consumers (Queue, FlowProducer, Job) depend on.
+ * Both {@link Connection} and a round-robin ConnectionPool satisfy it, so a
+ * pool can be dropped in transparently for producer-side throughput.
+ */
+export interface ConnectionLike {
+  call<R = Response>(command: Command, timeoutMs?: number): Promise<R>;
+  ping(): Promise<boolean>;
+  connect(): Promise<void>;
+  close(): void;
+  readonly isConnected: boolean;
+  readonly generation: number;
+  on(event: string, listener: (...args: unknown[]) => void): this;
+}
+
 export interface Pending {
   resolve: (response: Response) => void;
   reject: (error: Error) => void;

package/src/connection.ts

@@ -6,8 +6,10 @@
  * builtins (net/tls), which Node, Bun and Deno all support.
  */
 
+import { EventEmitter } from 'node:events';
 import type { Socket } from 'node:net';
 import { pack, unpack } from 'msgpackr';
+import { Backpressure } from './backpressure.js';
 import type {
   Command,
   ConnectionOptions,
@@ -17,12 +19,19 @@ import type {
 } from './connection-types.js';
 import { AuthError, CommandError, CommandTimeoutError, ConnectionClosedError } from './errors.js';
 import { compact, FrameParser, frame, PROTOCOL_VERSION } from './frame.js';
+import { nowMs, Telemetry } from './observability.js';
 import { openSocket } from './socket-factory.js';
 
 export type { Command, ConnectionOptions, Response, TlsOption } from './connection-types.js';
 
-/** A single pipelined TCP connection to a bunqueue server. */
-export class Connection {
+/**
+ * A single pipelined TCP connection to a bunqueue server.
+ *
+ * Emits typed lifecycle events for observability: `connect`, `disconnect` and
+ * `reconnect_scheduled` (payloads mirror the telemetry events). Attach a
+ * telemetry sink via the `onTelemetry` option for per-command latency metrics.
+ */
+export class Connection extends EventEmitter {
   readonly host: string;
   readonly port: number;
   readonly token: string | undefined;
@@ -44,14 +53,22 @@ export class Connection {
   // socket is presumed dead and torn down so the next call reconnects.
   private readonly maxCommandTimeouts = 3;
   private consecutiveTimeouts = 0;
+  private readonly telemetry: Telemetry;
+  private readonly backpressure: Backpressure;
 
   constructor(options: ConnectionOptions = {}) {
+    super();
     this.host = options.host ?? 'localhost';
     this.port = options.port ?? 6789;
     this.token = options.token;
     this.tls = options.tls;
     this.connectTimeoutMs = options.connectTimeoutMs ?? 5000;
     this.commandTimeoutMs = options.commandTimeoutMs ?? 10_000;
+    this.telemetry = new Telemetry(options, (event, payload) => this.emit(event, payload));
+    const maxInFlight = options.maxInFlight ?? 0;
+    this.backpressure = new Backpressure(maxInFlight, () =>
+      this.telemetry.backpressure(this.pending.size, maxInFlight)
+    );
   }
 
   get isConnected(): boolean {
@@ -89,6 +106,7 @@ export class Connection {
         this.failedAttempts += 1;
         const backoff = Math.min(500 * 2 ** (this.failedAttempts - 1), 5000);
         this.nextAttemptAt = Date.now() + backoff;
+        this.telemetry.reconnectScheduled(this.host, this.port, this.failedAttempts, backoff);
         throw err;
       })
       .finally(() => {
@@ -98,6 +116,7 @@ export class Connection {
   }
 
   private async doConnect(): Promise<void> {
+    const startMs = nowMs();
     const socket = await openSocket(this.host, this.port, this.tls, this.connectTimeoutMs);
     socket.setNoDelay(true);
     // TCP keepalive (~15s idle) surfaces a half-open link (cloud LB/NAT idle
@@ -113,6 +132,7 @@ export class Connection {
     this.connected = true;
     this.connectGeneration += 1;
     this.consecutiveTimeouts = 0;
+    this.telemetry.connected(this.host, this.port, this.connectGeneration, startMs);
 
     // INVARIANT (H3): connected is flipped true before Auth, which is safe
     // ONLY because call() writes the Auth frame synchronously — there is no
@@ -123,7 +143,9 @@ export class Connection {
     if (this.token) {
       try {
         await this.call({ cmd: 'Auth', token: this.token });
+        this.telemetry.auth(true);
       } catch (err) {
+        this.telemetry.auth(false);
         this.teardown();
         if (err instanceof CommandError) throw new AuthError(err.message);
         throw err;
@@ -135,19 +157,26 @@ export class Connection {
    * Send a command and await its response. Rejects with CommandError when
    * the server answers ok=false. Reconnects lazily if the link was lost.
    */
-  async call(command: Command, timeoutMs?: number): Promise<Response> {
+  async call<R = Response>(command: Command, timeoutMs?: number): Promise<R> {
     if (!this.connected) await this.connect();
+    // Backpressure: park here if too many commands are already in flight. The
+    // socket may be torn down while parked, so re-check after the gate.
+    const gate = this.backpressure.acquire(this.pending.size);
+    if (gate) await gate;
     const socket = this.socket;
-    if (!socket) throw new ConnectionClosedError('not connected');
+    if (!this.connected || !socket) throw new ConnectionClosedError('not connected');
 
     this.reqCounter = (this.reqCounter + 1) & 0x7fffffff;
     const reqId = String(this.reqCounter);
     const payload = pack({ ...compact(command), reqId });
     const gen = this.connectGeneration; // snapshot: a timeout must not tear down a newer conn
+    const startMs = nowMs();
 
-    return new Promise<Response>((resolve, reject) => {
+    return new Promise<R>((resolve, reject) => {
       const timer = setTimeout(() => {
         this.pending.delete(reqId);
+        this.backpressure.release();
+        this.telemetry.timeout(command.cmd, reqId);
         this.noteTimeout(gen);
         reject(new CommandTimeoutError(`no response for ${command.cmd} within timeout`));
       }, timeoutMs ?? this.commandTimeoutMs);
@@ -156,10 +185,11 @@ export class Connection {
         resolve: (response) => {
           clearTimeout(timer);
           this.consecutiveTimeouts = 0; // any reply means the link is alive
+          this.telemetry.command(command.cmd, reqId, startMs, response.ok);
           if (!response.ok) {
             reject(new CommandError(String(response.error ?? 'unknown server error')));
           } else {
-            resolve(response);
+            resolve(response as R);
           }
         },
         reject: (err) => {
@@ -173,6 +203,7 @@ export class Connection {
         if (err) {
           const entry = this.pending.get(reqId);
           this.pending.delete(reqId);
+          this.backpressure.release();
           entry?.reject(new ConnectionClosedError(`send failed: ${err.message}`));
           this.teardown();
         }
@@ -228,6 +259,7 @@ export class Connection {
       const entry = this.pending.get(String(reqId));
       if (entry) {
         this.pending.delete(String(reqId));
+        this.backpressure.release();
         entry.resolve(response);
       }
     }
@@ -247,6 +279,8 @@ export class Connection {
   }
 
   private teardown(): void {
+    const wasConnected = this.socket !== null;
+    const gen = this.connectGeneration;
     this.connected = false;
     const socket = this.socket;
     this.socket = null;
@@ -260,5 +294,7 @@ export class Connection {
       clearTimeout(entry.timer);
       entry.reject(new ConnectionClosedError('connection lost'));
     }
+    this.backpressure.clear(); // release parked callers; they re-check + fail/reconnect
+    if (wasConnected) this.telemetry.disconnected(this.host, this.port, gen);
   }
 }

package/src/flow-types.ts

@@ -2,6 +2,7 @@
 
 import type { Connection, TlsOption } from './connection.js';
 import type { Job } from './job.js';
+import type { Observability } from './observability.js';
 import type { JobOptions } from './types.js';
 
 export interface FlowJob<T = unknown> {
@@ -24,7 +25,7 @@ export interface FlowStep<T = unknown> {
   opts?: JobOptions;
 }
 
-export interface FlowProducerOptions {
+export interface FlowProducerOptions extends Observability {
   host?: string;
   port?: number;
   token?: string;

package/src/flow.ts

@@ -15,6 +15,7 @@ import type {
 } from './flow-types.js';
 import { compact } from './frame.js';
 import { Job } from './job.js';
+import type { JobResponse, OkResponse } from './responses.js';
 import { type JobOptions, jobPayload, wireJobOptions } from './types.js';
 
 export class FlowProducer {
@@ -24,7 +25,14 @@ export class FlowProducer {
   constructor(opts: FlowProducerOptions = {}) {
     this.connection =
       opts.connection ??
-      new Connection({ host: opts.host, port: opts.port, token: opts.token, tls: opts.tls });
+      new Connection({
+        host: opts.host,
+        port: opts.port,
+        token: opts.token,
+        tls: opts.tls,
+        logger: opts.logger,
+        onTelemetry: opts.onTelemetry,
+      });
     this.ownsConnection = opts.connection === undefined;
   }
 
@@ -70,19 +78,19 @@ export class FlowProducer {
     let prevId: string | null = null;
     try {
       for (const step of steps) {
-        const data = compact({
+        const data: Record<string, unknown> = compact({
           ...jobPayload(step.name, step.data),
           __flowParentId: prevId ?? undefined,
         });
-        const response = await this.connection.call(
-          compact({
-            cmd: 'PUSH',
-            queue: step.queueName,
-            data,
-            ...wireJobOptions(step.opts),
-            dependsOn: prevId ? [prevId] : undefined,
-          }) as { cmd: string }
-        );
+        // Connection.call compacts internally, so no outer compact() is needed
+        // (nesting it confused generic inference of `data`/`response`).
+        const response: OkResponse = await this.connection.call<OkResponse>({
+          cmd: 'PUSH',
+          queue: step.queueName,
+          data,
+          ...wireJobOptions(step.opts),
+          dependsOn: prevId ? [prevId] : undefined,
+        });
         const id = String(response.id);
         jobIds.push(id);
         prevId = id;
@@ -103,7 +111,7 @@ export class FlowProducer {
     try {
       const results = await Promise.allSettled(
         parallel.map(async (step) => {
-          const response = await this.connection.call(
+          const response = await this.connection.call<OkResponse>(
             compact({
               cmd: 'PUSH',
               queue: step.queueName,
@@ -188,7 +196,7 @@ export class FlowProducer {
     parentRef: { id: string; queue: string } | null,
     childIds: string[]
   ): Promise<string> {
-    const response = await this.connection.call(
+    const response = await this.connection.call<OkResponse>(
       compact({
         cmd: 'PUSH',
         queue,
@@ -219,16 +227,16 @@ export class FlowProducer {
     // A missing job — the root, or a child removed via removeOnComplete/cancel
     // (childrenIds is a static push-time list, never pruned) — yields null and
     // is skipped, returning the surviving partial tree instead of throwing.
-    let response: Awaited<ReturnType<Connection['call']>>;
+    let response: JobResponse;
     try {
-      response = await this.connection.call({ cmd: 'GetJob', id });
+      response = await this.connection.call<JobResponse>({ cmd: 'GetJob', id });
     } catch (err) {
       // Only 'Job not found' means a removed node; a real server error must not
       // masquerade as a missing child and yield a misleading partial tree.
       if (err instanceof CommandError && /not found/i.test(err.message)) return null;
       throw err;
     }
-    const raw = response.job as Record<string, unknown> | null;
+    const raw = response.job;
     if (!raw) return null;
     const job = new Job<T>(raw, this.connection);
     if (depth <= 0 || job.childrenIds.length === 0) return { job };

package/src/index.ts

@@ -26,6 +26,8 @@ export type {
 } from './bunqueue/types.js';
 export type { Command, ConnectionOptions, Response, TlsOption } from './connection.js';
 export { Connection } from './connection.js';
+export { ConnectionPool } from './connection-pool.js';
+export type { ConnectionLike } from './connection-types.js';
 export {
   AuthError,
   BunqueueError,
@@ -45,9 +47,33 @@ export type {
 export { MAX_FRAME_SIZE, PROTOCOL_VERSION } from './frame.js';
 export type { JobRaw } from './job.js';
 export { Job } from './job.js';
+export type {
+  Logger,
+  LogLevel,
+  Observability,
+  TelemetryEvent,
+  TelemetryHandler,
+} from './observability.js';
+export { consoleLogger, noopLogger } from './observability.js';
 export type { BulkJobEntry, QueueOptions } from './queue.js';
 export { Queue } from './queue.js';
 export type { SchedulerOptions } from './queue-admin.js';
+export type {
+  BatchResponse,
+  CountResponse,
+  DataResponse,
+  JobCountsResponse,
+  JobResponse,
+  JobsResponse,
+  OkResponse,
+  PausedResponse,
+  ProgressResponse,
+  PulledJobResponse,
+  PulledJobsResponse,
+  ResultResponse,
+  StateResponse,
+  WaitJobResponse,
+} from './responses.js';
 export type {
   BackoffOptions,
   DeduplicationOptions,
@@ -57,6 +83,11 @@ export type {
   RepeatOptions,
 } from './types.js';
 export { Worker } from './worker.js';
-export type { Processor, WorkerOptions } from './worker-types.js';
+export type {
+  AckBatchOptions,
+  Processor,
+  WorkerEventMap,
+  WorkerOptions,
+} from './worker-types.js';
 
-export const __version__ = '0.1.2';
+export const __version__ = '0.1.7';

package/src/job.ts

@@ -3,7 +3,7 @@
  * Mirrors the official TS client's Job surface (TCP mode).
  */
 
-import type { Connection, Response } from './connection.js';
+import type { ConnectionLike, Response } from './connection-types.js';
 
 export type JobRaw = Record<string, unknown>;
 
@@ -12,10 +12,10 @@ export type ProgressHook = (job: Job, progress: number) => void;
 export class Job<T = unknown> {
   readonly raw: JobRaw;
   readonly token: string | undefined;
-  private readonly conn: Connection | undefined;
+  private readonly conn: ConnectionLike | undefined;
   private readonly onProgress: ProgressHook | undefined;
 
-  constructor(raw: JobRaw, connection?: Connection, token?: string, onProgress?: ProgressHook) {
+  constructor(raw: JobRaw, connection?: ConnectionLike, token?: string, onProgress?: ProgressHook) {
     this.raw = raw;
     this.conn = connection;
     this.token = token;