bunqueue-client 0.1.2 → 0.1.3

package/src/bunqueue/dlq-rate-limit.ts

@@ -0,0 +1,89 @@
+/**
+ * Bunqueue Simple Mode — DLQ and rate limit helpers.
+ * Port of src/client/bunqueue/dlqRateLimit.ts. Delegates to the TCP Queue;
+ * the DLQ filter and stats are computed client-side from the fetched entries
+ * (the embedded original reads them in-process).
+ */
+
+import type { Queue } from '../queue.js';
+import type { BunqueueDlqConfig } from './types.js';
+
+type Raw = Record<string, unknown>;
+
+/** Filter for DLQ queries (mirrors the official DlqFilter). */
+export interface DlqFilter {
+  reason?: string;
+  jobName?: string;
+  since?: number;
+}
+
+/** Aggregate DLQ statistics (mirrors the official DlqStats). */
+export interface DlqStats {
+  total: number;
+  byReason: Record<string, number>;
+}
+
+function entryReason(entry: Raw): string {
+  return String(entry.reason ?? (entry.entry as Raw | undefined)?.reason ?? 'unknown');
+}
+
+function entryName(entry: Raw): string | undefined {
+  const data = (entry.data ?? (entry.entry as Raw | undefined)?.data) as Raw | undefined;
+  return data?.name === undefined ? undefined : String(data.name);
+}
+
+export class DlqRateLimitManager<T = unknown> {
+  constructor(private readonly queue: Queue<T>) {}
+
+  // ------------------------------------------------------------------- dlq
+
+  async setDlqConfig(config: BunqueueDlqConfig): Promise<void> {
+    await this.queue.setDlqConfig(config as Raw);
+  }
+
+  getDlqConfig(): Promise<Raw> {
+    return this.queue.getDlqConfig();
+  }
+
+  async getDlq(filter?: DlqFilter): Promise<Raw[]> {
+    const entries = await this.queue.getDlq();
+    if (!filter) return entries;
+    return entries.filter((entry) => {
+      if (filter.reason && entryReason(entry) !== filter.reason) return false;
+      if (filter.jobName && entryName(entry) !== filter.jobName) return false;
+      if (filter.since !== undefined) {
+        const at = Number(entry.enteredAt ?? entry.failedAt ?? 0);
+        if (at < filter.since) return false;
+      }
+      return true;
+    });
+  }
+
+  async getDlqStats(): Promise<DlqStats> {
+    const entries = await this.queue.getDlq();
+    const byReason: Record<string, number> = {};
+    for (const entry of entries) {
+      const reason = entryReason(entry);
+      byReason[reason] = (byReason[reason] ?? 0) + 1;
+    }
+    return { total: entries.length, byReason };
+  }
+
+  retryDlq(id?: string): Promise<number> {
+    return this.queue.retryDlq(id);
+  }
+
+  purgeDlq(): Promise<number> {
+    return this.queue.purgeDlq();
+  }
+
+  // ----------------------------------------------------------- rate limiting
+
+  async setGlobalRateLimit(max: number, duration?: number): Promise<void> {
+    await this.queue.setGlobalRateLimit(max, duration);
+  }
+
+  async removeGlobalRateLimit(): Promise<void> {
+    await this.queue.removeGlobalRateLimit();
+  }
+}

package/src/bunqueue/rate-gate.ts

@@ -0,0 +1,53 @@
+/**
+ * Bunqueue Simple Mode — client-side rate limiter for the worker.
+ *
+ * The official client passes `rateLimit`/`limiter` to the embedded Worker,
+ * which throttles job starts to `max` per `duration` window, optionally per
+ * group (`groupKey` names a field of job.data). This SDK reproduces the same
+ * semantics as a gate awaited before each job runs: a job whose window is
+ * full waits (holding its concurrency slot) until the window frees.
+ */
+
+import type { RateLimiterOptions } from './types.js';
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+export class RateGate {
+  private readonly max: number;
+  private readonly duration: number;
+  private readonly groupKey: string | undefined;
+  private readonly windows = new Map<string, number[]>();
+
+  constructor(options: RateLimiterOptions) {
+    this.max = options.max;
+    this.duration = options.duration;
+    this.groupKey = options.groupKey;
+  }
+
+  /** Resolve the rate-limit group for a job's data. */
+  groupFor(data: unknown): string {
+    if (!this.groupKey) return '';
+    if (typeof data === 'object' && data !== null) {
+      const value = (data as Record<string, unknown>)[this.groupKey];
+      if (value !== undefined && value !== null) return String(value);
+    }
+    return '';
+  }
+
+  /** Wait until the group's window has room, then record the start. */
+  async acquire(group: string): Promise<void> {
+    for (;;) {
+      const now = Date.now();
+      const window = this.windows.get(group) ?? [];
+      const fresh = window.filter((t) => now - t < this.duration);
+      if (fresh.length < this.max) {
+        fresh.push(now);
+        this.windows.set(group, fresh);
+        return;
+      }
+      this.windows.set(group, fresh);
+      const oldest = fresh[0];
+      await sleep(Math.max(oldest + this.duration - now, 10));
+    }
+  }
+}

package/src/bunqueue/retry.ts

@@ -0,0 +1,72 @@
+/**
+ * Bunqueue Simple Mode — advanced in-process retry with backoff strategies.
+ * 1:1 port of src/client/bunqueue/retry.ts (identical formulas).
+ */
+
+import type { RetryConfig, RetryStrategy } from './types.js';
+
+/** Calculate backoff delay based on strategy. */
+export function calculateBackoff(
+  strategy: RetryStrategy,
+  attempt: number,
+  baseDelay: number,
+  error: Error,
+  config: RetryConfig
+): number {
+  switch (strategy) {
+    case 'fixed':
+      return baseDelay;
+
+    case 'exponential':
+      return baseDelay * 2 ** (attempt - 1);
+
+    case 'jitter': {
+      const exp = baseDelay * 2 ** (attempt - 1);
+      return Math.floor(exp * (0.5 + Math.random()));
+    }
+
+    case 'fibonacci': {
+      let a = 1;
+      let b = 1;
+      for (let i = 0; i < attempt - 1; i++) {
+        const next = a + b;
+        a = b;
+        b = next;
+      }
+      return baseDelay * b;
+    }
+
+    case 'custom':
+      if (config.customBackoff) {
+        return config.customBackoff(attempt, error);
+      }
+      return baseDelay;
+
+    default:
+      return baseDelay;
+  }
+}
+
+/** Execute a function with retry logic (the job stays active throughout). */
+export function executeWithRetry<R>(fn: () => Promise<R>, config: RetryConfig): Promise<R> {
+  const maxAttempts = config.maxAttempts ?? 3;
+  const baseDelay = config.delay ?? 1000;
+  const strategy = config.strategy ?? 'exponential';
+
+  const attempt = (n: number): Promise<R> => {
+    return fn().catch((err: unknown) => {
+      const error = err instanceof Error ? err : new Error(String(err));
+      if (n >= maxAttempts) throw error;
+      if (config.retryIf && !config.retryIf(error, n)) throw error;
+
+      const delay = calculateBackoff(strategy, n, baseDelay, error, config);
+      return new Promise<R>((resolve) => {
+        setTimeout(() => {
+          resolve(attempt(n + 1));
+        }, delay);
+      });
+    });
+  };
+
+  return attempt(1);
+}

package/src/bunqueue/triggers.ts

@@ -0,0 +1,51 @@
+/**
+ * Bunqueue Simple Mode — event triggers.
+ * 1:1 port of src/client/bunqueue/triggers.ts: when a job completes/fails,
+ * automatically create another job.
+ */
+
+import type { Job } from '../job.js';
+import type { Queue } from '../queue.js';
+import type { Worker } from '../worker.js';
+import type { TriggerRule } from './types.js';
+
+export class TriggerManager<T = unknown, R = unknown> {
+  private readonly rules: TriggerRule<T>[] = [];
+  private active = false;
+  private readonly queue: Queue<T>;
+  private readonly worker: Worker<T, R>;
+
+  constructor(queue: Queue<T>, worker: Worker<T, R>) {
+    this.queue = queue;
+    this.worker = worker;
+  }
+
+  add(rule: TriggerRule<T>): void {
+    this.rules.push(rule);
+    this.ensureActive();
+  }
+
+  private ensureActive(): void {
+    if (this.active) return;
+    this.active = true;
+
+    this.worker.on('completed', (job, result) => {
+      this.fire('completed', job as Job<T>, result);
+    });
+
+    this.worker.on('failed', (job, error) => {
+      this.fire('failed', job as Job<T>, error);
+    });
+  }
+
+  private fire(event: 'completed' | 'failed', job: Job<T>, resultOrError: unknown): void {
+    for (const rule of this.rules) {
+      if (rule.on !== job.name) continue;
+      if ((rule.event ?? 'completed') !== event) continue;
+      if (rule.condition && !rule.condition(resultOrError, job)) continue;
+
+      const data = rule.data(resultOrError, job);
+      void this.queue.add(rule.create, data, rule.opts);
+    }
+  }
+}

package/src/bunqueue/ttl.ts

@@ -0,0 +1,38 @@
+/**
+ * Bunqueue Simple Mode — job TTL (time to live).
+ * 1:1 port of src/client/bunqueue/ttl.ts: expire unprocessed jobs, checked
+ * when the worker picks the job up. Resolution: perName -> defaultTtl -> 0.
+ */
+
+import type { JobTtlConfig } from './types.js';
+
+export class TtlChecker {
+  private readonly config: JobTtlConfig;
+
+  constructor(config: JobTtlConfig) {
+    this.config = config;
+  }
+
+  /** Get TTL for a specific job name. */
+  getTtl(jobName: string): number {
+    return this.config.perName?.[jobName] ?? this.config.defaultTtl ?? 0;
+  }
+
+  /** Check if a job has expired. */
+  isExpired(jobName: string, jobTimestamp: number): boolean {
+    const ttl = this.getTtl(jobName);
+    if (ttl <= 0) return false;
+    return Date.now() - jobTimestamp > ttl;
+  }
+
+  /** Set default TTL. */
+  setDefaultTtl(ttlMs: number): void {
+    this.config.defaultTtl = ttlMs;
+  }
+
+  /** Set TTL for a specific job name. */
+  setNameTtl(jobName: string, ttlMs: number): void {
+    this.config.perName ??= {};
+    this.config.perName[jobName] = ttlMs;
+  }
+}

package/src/bunqueue/types.ts

@@ -0,0 +1,171 @@
+/**
+ * Bunqueue Simple Mode — type definitions.
+ * 1:1 port of src/client/bunqueue/types.ts from the official client, minus
+ * the embedded-mode options (this SDK is TCP-only).
+ */
+
+import type { TlsOption } from '../connection.js';
+import type { Job } from '../job.js';
+import type { JobOptions } from '../types.js';
+import type { Processor } from '../worker-types.js';
+
+/** Connection options accepted by Simple Mode (mirrors ConnectionOptions). */
+export interface BunqueueConnection {
+  host?: string;
+  port?: number;
+  token?: string;
+  tls?: TlsOption;
+}
+
+/** Middleware function: receives job and next(), returns result. */
+export type BunqueueMiddleware<T = unknown, R = unknown> = (
+  job: Job<T>,
+  next: () => Promise<R>
+) => Promise<R>;
+
+/** Retry strategy for advanced backoff. */
+export type RetryStrategy = 'fixed' | 'exponential' | 'jitter' | 'fibonacci' | 'custom';
+
+/** Advanced retry configuration (in-process; the job stays active). */
+export interface RetryConfig {
+  /** Max attempts (default: 3). */
+  maxAttempts?: number;
+  /** Base delay in ms (default: 1000). */
+  delay?: number;
+  /** Strategy (default: exponential). */
+  strategy?: RetryStrategy;
+  /** Custom backoff function: attempt, error -> delay in ms. */
+  customBackoff?: (attempt: number, error: Error) => number;
+  /** Only retry if this returns true. */
+  retryIf?: (error: Error, attempt: number) => boolean;
+}
+
+/** Circuit breaker configuration. */
+export interface CircuitBreakerConfig {
+  /** Max consecutive failures before opening (default: 5). */
+  threshold?: number;
+  /** Time in ms before half-open retry (default: 30000). */
+  resetTimeout?: number;
+  onOpen?: (failures: number) => void;
+  onClose?: () => void;
+  onHalfOpen?: () => void;
+}
+
+/** Circuit breaker state. */
+export type CircuitState = 'closed' | 'open' | 'half-open';
+
+/** Event trigger rule. */
+export interface TriggerRule<T = unknown> {
+  /** Job name that triggers this rule. */
+  on: string;
+  /** Event type (default: completed). */
+  event?: 'completed' | 'failed';
+  /** Job name to create. */
+  create: string;
+  /** Data builder from the triggering job. */
+  data: (result: unknown, job: Job<T>) => T;
+  /** Optional job options. */
+  opts?: JobOptions;
+  /** Optional condition. */
+  condition?: (result: unknown, job: Job<T>) => boolean;
+}
+
+/** Priority aging configuration. */
+export interface PriorityAgingConfig {
+  /** Check interval in ms (default: 60000). */
+  interval?: number;
+  /** Min age in ms before boost (default: 60000). */
+  minAge?: number;
+  /** Priority boost per interval (default: 1). */
+  boost?: number;
+  /** Max priority cap (default: 100). */
+  maxPriority?: number;
+  /** Max jobs to scan per tick (default: 100). */
+  maxScan?: number;
+}
+
+/** Batch processor function. */
+export type BatchProcessor<T = unknown, R = unknown> = (jobs: Array<Job<T>>) => Promise<R[]>;
+
+/** Batch processing configuration. */
+export interface BatchConfig<T = unknown, R = unknown> {
+  /** Batch size (default: 10). */
+  size: number;
+  /** Max wait in ms before flushing a partial batch (default: 5000). */
+  timeout?: number;
+  processor: BatchProcessor<T, R>;
+}
+
+/** Job TTL configuration. */
+export interface JobTtlConfig {
+  /** Default TTL in ms (0 = no TTL). */
+  defaultTtl?: number;
+  /** Per-job-name TTL overrides. */
+  perName?: Record<string, number>;
+}
+
+/** Deduplication defaults for Simple Mode. */
+export interface BunqueueDeduplicationConfig {
+  /** Default deduplication TTL in ms (default: 3600000 = 1 hour). */
+  ttl?: number;
+  /** Extend TTL when a duplicate arrives (default: false). */
+  extend?: boolean;
+  /** Replace data when a duplicate arrives in delayed state (default: false). */
+  replace?: boolean;
+}
+
+/** Debounce defaults for Simple Mode. */
+export interface BunqueueDebounceConfig {
+  /** Debounce TTL in ms. */
+  ttl: number;
+}
+
+/** DLQ configuration for Simple Mode (forwarded to the server). */
+export interface BunqueueDlqConfig {
+  autoRetry?: boolean;
+  autoRetryInterval?: number;
+  maxAutoRetries?: number;
+  maxAge?: number | null;
+  maxEntries?: number;
+}
+
+/** Client-side rate limiter options (max job starts per duration window). */
+export interface RateLimiterOptions {
+  max: number;
+  duration: number;
+  /** Group jobs by this data field (e.g. per-customer limits). */
+  groupKey?: string;
+}
+
+/** Bunqueue Simple Mode options. */
+export interface BunqueueOptions<T = unknown, R = unknown> {
+  processor?: Processor<T, R>;
+  routes?: Record<string, Processor<T, R>>;
+  batch?: BatchConfig<T, R>;
+  concurrency?: number;
+  connection?: BunqueueConnection;
+  defaultJobOptions?: JobOptions;
+  autorun?: boolean;
+  /** Worker heartbeat interval in ms (official-client unit). */
+  heartbeatInterval?: number;
+  batchSize?: number;
+  /** Long-poll timeout in ms. */
+  pollTimeout?: number;
+  limiter?: RateLimiterOptions;
+  removeOnComplete?: boolean;
+  removeOnFail?: boolean;
+  retry?: RetryConfig;
+  circuitBreaker?: CircuitBreakerConfig;
+  ttl?: JobTtlConfig;
+  priorityAging?: PriorityAgingConfig;
+  /** Job deduplication defaults, merged into every add(). */
+  deduplication?: BunqueueDeduplicationConfig;
+  /** Job debouncing defaults, merged into every add(). */
+  debounce?: BunqueueDebounceConfig;
+  /** Rate limiting for the worker (alias of limiter, takes precedence). */
+  rateLimit?: RateLimiterOptions;
+  /** Dead letter queue auto-management (forwarded to the server). */
+  dlq?: BunqueueDlqConfig;
+  /** Namespace prefix prepended to the queue name on the server. */
+  prefixKey?: string;
+}

package/src/connection.ts

@@ -6,9 +6,7 @@
  * builtins (net/tls), which Node, Bun and Deno all support.
  */
 
-import { readFileSync } from 'node:fs';
-import { connect as netConnect, type Socket } from 'node:net';
-import { type ConnectionOptions as TlsConnectOptions, connect as tlsConnect } from 'node:tls';
+import type { Socket } from 'node:net';
 import { pack, unpack } from 'msgpackr';
 import type {
   Command,
@@ -19,6 +17,7 @@ import type {
 } from './connection-types.js';
 import { AuthError, CommandError, CommandTimeoutError, ConnectionClosedError } from './errors.js';
 import { compact, FrameParser, frame, PROTOCOL_VERSION } from './frame.js';
+import { openSocket } from './socket-factory.js';
 
 export type { Command, ConnectionOptions, Response, TlsOption } from './connection-types.js';
 
@@ -38,6 +37,9 @@ export class Connection {
   private pending = new Map<string, Pending>();
   private reqCounter = 0;
   private parser = new FrameParser();
+  private connectGeneration = 0;
+  private failedAttempts = 0;
+  private nextAttemptAt = 0;
 
   constructor(options: ConnectionOptions = {}) {
     this.host = options.host ?? 'localhost';
@@ -52,19 +54,47 @@ export class Connection {
     return this.connected;
   }
 
+  /**
+   * Monotonic counter, incremented on every successful (re)connect. Consumers
+   * that hold per-connection server state (e.g. a Worker registration) compare
+   * it between operations and re-establish that state after a reconnect.
+   */
+  get generation(): number {
+    return this.connectGeneration;
+  }
+
   /** Open the socket (and authenticate) if not already connected. */
   async connect(): Promise<void> {
     if (this.connected) return;
     if (this.closed) throw new ConnectionClosedError('connection closed by client');
+    // Fast-fail while inside the reconnect backoff window: without this, a
+    // producer calling add() against a downed server pays the full connect
+    // timeout on EVERY call (reconnect storm).
+    if (Date.now() < this.nextAttemptAt) {
+      throw new ConnectionClosedError(
+        `server unreachable, retry in ${this.nextAttemptAt - Date.now()}ms`
+      );
+    }
     if (this.connecting) return this.connecting;
-    this.connecting = this.doConnect().finally(() => {
-      this.connecting = null;
-    });
+    this.connecting = this.doConnect()
+      .then(() => {
+        this.failedAttempts = 0;
+        this.nextAttemptAt = 0;
+      })
+      .catch((err) => {
+        this.failedAttempts += 1;
+        const backoff = Math.min(500 * 2 ** (this.failedAttempts - 1), 5000);
+        this.nextAttemptAt = Date.now() + backoff;
+        throw err;
+      })
+      .finally(() => {
+        this.connecting = null;
+      });
     return this.connecting;
   }
 
   private async doConnect(): Promise<void> {
-    const socket = await this.openSocket();
+    const socket = await openSocket(this.host, this.port, this.tls, this.connectTimeoutMs);
     socket.setNoDelay(true);
     this.parser.clear();
     this.socket = socket;
@@ -74,6 +104,7 @@ export class Connection {
     socket.on('close', () => this.teardown());
 
     this.connected = true;
+    this.connectGeneration += 1;
 
     if (this.token) {
       try {
@@ -86,45 +117,6 @@ export class Connection {
     }
   }
 
-  private openSocket(): Promise<Socket> {
-    return new Promise((resolve, reject) => {
-      let settled = false;
-      const timer = setTimeout(() => {
-        if (settled) return;
-        settled = true;
-        socket.destroy();
-        reject(new ConnectionClosedError(`connect timeout to ${this.host}:${this.port}`));
-      }, this.connectTimeoutMs);
-
-      const onError = (err: Error) => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        reject(new ConnectionClosedError(`connect failed: ${err.message}`));
-      };
-      const onReady = () => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        socket.off('error', onError);
-        resolve(socket);
-      };
-
-      let socket: Socket;
-      if (this.tls) {
-        const tlsOpts: TlsConnectOptions = { host: this.host, port: this.port };
-        if (typeof this.tls === 'object') {
-          if (this.tls.caFile) tlsOpts.ca = readFileSync(this.tls.caFile);
-          if (this.tls.rejectUnauthorized === false) tlsOpts.rejectUnauthorized = false;
-        }
-        socket = tlsConnect(tlsOpts, onReady);
-      } else {
-        socket = netConnect({ host: this.host, port: this.port }, onReady);
-      }
-      socket.on('error', onError);
-    });
-  }
-
   /**
    * Send a command and await its response. Rejects with CommandError when
    * the server answers ok=false. Reconnects lazily if the link was lost.

package/src/index.ts

@@ -3,6 +3,27 @@
  * Works on Node.js ≥20, Bun and Deno ≥2 (uses only node: builtins + msgpackr).
  */
 
+// Simple Mode (Bunqueue): all-in-one Queue + Worker, 1:1 with the official client
+export { Bunqueue } from './bunqueue/bunqueue.js';
+export type { DlqFilter, DlqStats } from './bunqueue/dlq-rate-limit.js';
+export type {
+  BatchConfig,
+  BatchProcessor,
+  BunqueueConnection,
+  BunqueueDebounceConfig,
+  BunqueueDeduplicationConfig,
+  BunqueueDlqConfig,
+  BunqueueMiddleware,
+  BunqueueOptions,
+  CircuitBreakerConfig,
+  CircuitState,
+  JobTtlConfig,
+  PriorityAgingConfig,
+  RateLimiterOptions,
+  RetryConfig,
+  RetryStrategy,
+  TriggerRule,
+} from './bunqueue/types.js';
 export type { Command, ConnectionOptions, Response, TlsOption } from './connection.js';
 export { Connection } from './connection.js';
 export {
@@ -38,4 +59,4 @@ export type {
 export { Worker } from './worker.js';
 export type { Processor, WorkerOptions } from './worker-types.js';
 
-export const __version__ = '0.1.0';
+export const __version__ = '0.1.2';

package/src/job.ts

@@ -62,6 +62,11 @@ export class Job<T = unknown> {
     return this.raw.createdAt === undefined ? undefined : Number(this.raw.createdAt);
   }
 
+  /** Creation time in epoch ms (BullMQ-parity alias of createdAt). */
+  get timestamp(): number {
+    return this.createdAt ?? Date.now();
+  }
+
   get startedAt(): number | null {
     return this.raw.startedAt === undefined || this.raw.startedAt === null
       ? null

package/src/queue-admin.ts

@@ -206,7 +206,8 @@ export const adminMethods = {
   },
 
   async setWebhookEnabled(this: Ctx, webhookId: string, enabled: boolean): Promise<void> {
-    await this.call({ cmd: 'SetWebhookEnabled', webhookId, enabled });
+    // wire field is `id` (SetWebhookEnabledCommand), unlike RemoveWebhook's `webhookId`
+    await this.call({ cmd: 'SetWebhookEnabled', id: webhookId, enabled });
   },
 };