bunqueue-client 0.1.4 → 0.1.6

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;
@@ -40,14 +49,26 @@ export class Connection {
   private connectGeneration = 0;
   private failedAttempts = 0;
   private nextAttemptAt = 0;
+  // Half-open recovery (#94): after this many consecutive command timeouts the
+  // 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 {
@@ -85,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(() => {
@@ -94,8 +116,12 @@ 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
+    // drop with no FIN/RST) in seconds instead of ~tcp_retries2 minutes.
+    socket.setKeepAlive(true, 15_000);
     this.parser.clear();
     this.socket = socket;
 
@@ -105,11 +131,21 @@ 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
+    // `await` between this line and the Auth socket.write, so no concurrent
+    // call() can interleave a frame ahead of Auth on the wire. Do NOT insert
+    // an await here or before the Auth call, or a command could race ahead of
+    // Auth (the Python SDK guards this with a lock; JS relies on this ordering).
     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;
@@ -121,28 +157,39 @@ 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);
 
       this.pending.set(reqId, {
         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) => {
@@ -156,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();
         }
@@ -211,12 +259,28 @@ export class Connection {
       const entry = this.pending.get(String(reqId));
       if (entry) {
         this.pending.delete(String(reqId));
+        this.backpressure.release();
         entry.resolve(response);
       }
     }
   }
 
+  /**
+   * A dead/half-open link makes every command time out while the socket still
+   * looks connected. After maxCommandTimeouts consecutive timeouts, tear down
+   * so the next call() reconnects instead of wedging (mirrors #94).
+   */
+  private noteTimeout(gen: number): void {
+    // A timeout from an already-replaced connection must not tear down (or
+    // miscount against) the current one.
+    if (gen !== this.connectGeneration) return;
+    this.consecutiveTimeouts += 1;
+    if (this.consecutiveTimeouts >= this.maxCommandTimeouts) this.teardown();
+  }
+
   private teardown(): void {
+    const wasConnected = this.socket !== null;
+    const gen = this.connectGeneration;
     this.connected = false;
     const socket = this.socket;
     this.socket = null;
@@ -230,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

@@ -5,6 +5,7 @@
  */
 
 import { Connection } from './connection.js';
+import { CommandError } from './errors.js';
 import type {
   FlowJob,
   FlowProducerOptions,
@@ -14,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 {
@@ -23,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;
   }
 
@@ -54,7 +63,12 @@ export class FlowProducer {
 
   /** Fetch a flow tree starting from a job id (recursive over childrenIds). */
   getFlow<T = unknown>(opts: GetFlowOptions): Promise<JobNode<T> | null> {
-    return this.fetchNode<T>(opts.id, opts.depth ?? Number.POSITIVE_INFINITY, opts.maxChildren);
+    return this.fetchNode<T>(
+      opts.id,
+      opts.depth ?? Number.POSITIVE_INFINITY,
+      opts.maxChildren,
+      new Set()
+    );
   }
 
   /** Add a sequential chain: step[0] → step[1] → ... via dependsOn. */
@@ -64,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;
@@ -97,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,
@@ -182,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,
@@ -205,10 +219,24 @@ export class FlowProducer {
   private async fetchNode<T>(
     id: string,
     depth: number,
-    maxChildren?: number
+    maxChildren: number | undefined,
+    visited: Set<string>
   ): Promise<JobNode<T> | null> {
-    const response = await this.connection.call({ cmd: 'GetJob', id });
-    const raw = response.job as Record<string, unknown> | null;
+    if (visited.has(id)) return null; // cycle guard: id already on the current path
+    visited.add(id);
+    // 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: JobResponse;
+    try {
+      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;
     if (!raw) return null;
     const job = new Job<T>(raw, this.connection);
     if (depth <= 0 || job.childrenIds.length === 0) return { job };
@@ -216,7 +244,7 @@ export class FlowProducer {
     const limit = maxChildren ?? job.childrenIds.length;
     const children: JobNode<T>[] = [];
     for (const childId of job.childrenIds.slice(0, limit)) {
-      const child = await this.fetchNode<T>(childId, depth - 1, maxChildren);
+      const child = await this.fetchNode<T>(childId, depth - 1, maxChildren, visited);
       if (child) children.push(child);
     }
     return { job, children: children.length > 0 ? children : undefined };

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,6 @@ export type {
   RepeatOptions,
 } from './types.js';
 export { Worker } from './worker.js';
-export type { Processor, WorkerOptions } from './worker-types.js';
+export type { AckBatchOptions, Processor, WorkerOptions } from './worker-types.js';
 
-export const __version__ = '0.1.2';
+export const __version__ = '0.1.6';

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;

package/src/observability.ts

@@ -0,0 +1,158 @@
+/**
+ * Observability primitives: a pluggable structured logger and a telemetry
+ * sink. Zero hard dependencies — wire your own OpenTelemetry / Prometheus /
+ * logging stack through these interfaces. Defaults are no-ops, so the SDK is
+ * silent unless you opt in.
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface Logger {
+  debug(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+}
+
+/** Silent logger (the default). */
+export const noopLogger: Logger = {
+  debug() {},
+  info() {},
+  warn() {},
+  error() {},
+};
+
+const LEVELS: Record<LogLevel, number> = { debug: 10, info: 20, warn: 30, error: 40 };
+
+/**
+ * A console-backed logger. Levels below `min` are dropped. Opt-in — pass it as
+ * `logger` when you want the SDK to log to the console.
+ */
+export function consoleLogger(min: LogLevel = 'info'): Logger {
+  const floor = LEVELS[min];
+  const line = (lvl: LogLevel, msg: string, meta?: Record<string, unknown>) => {
+    if (LEVELS[lvl] < floor) return;
+    const suffix = meta && Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : '';
+    const sink = lvl === 'debug' ? console.log : console[lvl];
+    sink(`[bunqueue] ${lvl} ${msg}${suffix}`);
+  };
+  return {
+    debug: (m, meta) => line('debug', m, meta),
+    info: (m, meta) => line('info', m, meta),
+    warn: (m, meta) => line('warn', m, meta),
+    error: (m, meta) => line('error', m, meta),
+  };
+}
+
+/** A single telemetry data point. A discriminated union keyed on `type`. */
+export type TelemetryEvent =
+  | { type: 'command'; cmd: string; reqId: string; durationMs: number; ok: boolean }
+  | { type: 'command_timeout'; cmd: string; reqId: string }
+  | { type: 'connect'; host: string; port: number; generation: number; durationMs: number }
+  | { type: 'disconnect'; host: string; port: number; generation: number }
+  | { type: 'reconnect_scheduled'; host: string; port: number; attempt: number; delayMs: number }
+  | { type: 'auth'; ok: boolean }
+  | { type: 'backpressure'; inFlight: number; maxInFlight: number };
+
+export type TelemetryHandler = (event: TelemetryEvent) => void;
+
+/** Lifecycle telemetry types that are ALSO emitted as EventEmitter events. */
+export const LIFECYCLE_EVENTS = ['connect', 'disconnect', 'reconnect_scheduled'] as const;
+
+export interface Observability {
+  /** Structured logger; defaults to {@link noopLogger}. */
+  logger?: Logger;
+  /**
+   * Telemetry sink for metrics and tracing. Receives every command's latency,
+   * connect/disconnect/reconnect, auth and backpressure events. Bridge it to
+   * OpenTelemetry spans or Prometheus counters without the SDK depending on
+   * either.
+   */
+  onTelemetry?: TelemetryHandler;
+}
+
+/** High-resolution monotonic clock (Node/Bun/Deno all expose `performance`). */
+export const nowMs = (): number => performance.now();
+
+/**
+ * Fans a telemetry event out to (1) the telemetry sink, (2) the logger, and
+ * (3) — for lifecycle events — the owning EventEmitter, so users can both
+ * scrape metrics and attach imperative `connection.on('connect', …)` handlers.
+ */
+export class Telemetry {
+  private readonly logger: Logger;
+  private readonly sink: TelemetryHandler | undefined;
+  private readonly emit: (event: string, payload: unknown) => void;
+
+  constructor(obs: Observability | undefined, emit: (event: string, payload: unknown) => void) {
+    // Wrap the user logger so a throwing logger can never break the transport
+    // hot path (dispatch runs inside socket 'data' handlers and connect).
+    const inner = obs?.logger ?? noopLogger;
+    this.logger =
+      inner === noopLogger
+        ? inner
+        : {
+            debug: (m, meta) => Telemetry.safely(() => inner.debug(m, meta)),
+            info: (m, meta) => Telemetry.safely(() => inner.info(m, meta)),
+            warn: (m, meta) => Telemetry.safely(() => inner.warn(m, meta)),
+            error: (m, meta) => Telemetry.safely(() => inner.error(m, meta)),
+          };
+    this.sink = obs?.onTelemetry;
+    this.emit = emit;
+  }
+
+  /** Observability must never break the client: swallow consumer errors. */
+  private static safely(fn: () => void): void {
+    try {
+      fn();
+    } catch {
+      /* consumer logging/telemetry error — intentionally ignored */
+    }
+  }
+
+  get log(): Logger {
+    return this.logger;
+  }
+
+  /** Record a completed command's latency and outcome. */
+  command(cmd: string, reqId: string, startMs: number, ok: boolean): void {
+    this.dispatch({ type: 'command', cmd, reqId, durationMs: nowMs() - startMs, ok });
+  }
+
+  timeout(cmd: string, reqId: string): void {
+    this.logger.warn('command timed out', { cmd, reqId });
+    this.dispatch({ type: 'command_timeout', cmd, reqId });
+  }
+
+  connected(host: string, port: number, generation: number, startMs: number): void {
+    this.logger.info('connected', { host, port, generation });
+    this.dispatch({ type: 'connect', host, port, generation, durationMs: nowMs() - startMs });
+  }
+
+  disconnected(host: string, port: number, generation: number): void {
+    this.logger.info('disconnected', { host, port, generation });
+    this.dispatch({ type: 'disconnect', host, port, generation });
+  }
+
+  reconnectScheduled(host: string, port: number, attempt: number, delayMs: number): void {
+    this.logger.warn('reconnect scheduled', { host, port, attempt, delayMs });
+    this.dispatch({ type: 'reconnect_scheduled', host, port, attempt, delayMs });
+  }
+
+  auth(ok: boolean): void {
+    this.dispatch({ type: 'auth', ok });
+  }
+
+  backpressure(inFlight: number, maxInFlight: number): void {
+    this.dispatch({ type: 'backpressure', inFlight, maxInFlight });
+  }
+
+  private dispatch(event: TelemetryEvent): void {
+    // A throwing sink or lifecycle listener must never break the transport:
+    // dispatch runs inside socket 'data' handlers and the connect path.
+    Telemetry.safely(() => this.sink?.(event));
+    if ((LIFECYCLE_EVENTS as readonly string[]).includes(event.type)) {
+      Telemetry.safely(() => this.emit(event.type, event));
+    }
+  }
+}

package/src/queue-control.ts

@@ -5,6 +5,7 @@
 
 import { compact } from './frame.js';
 import type { Queue } from './queue.js';
+import type { CountResponse, PausedResponse } from './responses.js';
 import type { JobStateName } from './types.js';
 
 type Ctx = Queue<unknown>;
@@ -19,8 +20,7 @@ export const controlMethods = {
   },
 
   async isPaused(this: Ctx): Promise<boolean> {
-    const response = await this.call({ cmd: 'IsPaused', queue: this.name });
-    return response.paused === true;
+    return (await this.call<PausedResponse>({ cmd: 'IsPaused', queue: this.name })).paused === true;
   },
 
   async drain(this: Ctx): Promise<void> {
@@ -33,10 +33,10 @@ export const controlMethods = {
 
   /** Remove old jobs; returns how many were removed. */
   async clean(this: Ctx, graceMs: number, limit?: number, state?: JobStateName): Promise<number> {
-    const response = await this.call(
+    const response = await this.call<CountResponse>(
       compact({ cmd: 'Clean', queue: this.name, grace: graceMs, limit, state }) as { cmd: string }
     );
-    return Number(response.count ?? 0);
+    return response.count ?? 0;
   },
 
   async remove(this: Ctx, id: string): Promise<void> {
@@ -53,10 +53,10 @@ export const controlMethods = {
 
   /** Promote delayed jobs to waiting; returns how many were promoted. */
   async promoteJobs(this: Ctx, opts: { count?: number } = {}): Promise<number> {
-    const response = await this.call(
+    const response = await this.call<CountResponse>(
       compact({ cmd: 'PromoteJobs', queue: this.name, count: opts.count }) as { cmd: string }
     );
-    return Number(response.count ?? 0);
+    return response.count ?? 0;
   },
 
   /** BullMQ contract: failed → waiting. */
@@ -72,11 +72,9 @@ export const controlMethods = {
       await this.call({ cmd: 'RetryCompleted', queue: this.name });
       return;
     }
-    await this.call(
-      compact({ cmd: 'RetryDlq', queue: this.name, count: opts.count }) as {
-        cmd: string;
-      }
-    );
+    // `count` is accepted for API parity but not sent: the server has no
+    // partial RetryDlq — it retries the whole DLQ (BullMQ semantics).
+    await this.call({ cmd: 'RetryDlq', queue: this.name });
   },
 
   async retryCompleted(this: Ctx, id?: string): Promise<void> {