bunqueue-client 0.1.0

package/src/connection.ts

@@ -0,0 +1,242 @@
+/**
+ * TCP connection to a bunqueue server — cross-runtime (Node.js, Bun, Deno).
+ *
+ * Requests carry a `reqId` string; the server echoes it back, enabling
+ * pipelining (many in-flight commands per socket). Uses only `node:`
+ * 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 { pack, unpack } from 'msgpackr';
+import type {
+  Command,
+  ConnectionOptions,
+  Pending,
+  Response,
+  TlsOption,
+} from './connection-types.js';
+import { AuthError, CommandError, CommandTimeoutError, ConnectionClosedError } from './errors.js';
+import { compact, FrameParser, frame, PROTOCOL_VERSION } from './frame.js';
+
+export type { Command, ConnectionOptions, Response, TlsOption } from './connection-types.js';
+
+/** A single pipelined TCP connection to a bunqueue server. */
+export class Connection {
+  readonly host: string;
+  readonly port: number;
+  readonly token: string | undefined;
+  readonly tls: TlsOption;
+  readonly connectTimeoutMs: number;
+  readonly commandTimeoutMs: number;
+
+  private socket: Socket | null = null;
+  private connected = false;
+  private closed = false;
+  private connecting: Promise<void> | null = null;
+  private pending = new Map<string, Pending>();
+  private reqCounter = 0;
+  private parser = new FrameParser();
+
+  constructor(options: ConnectionOptions = {}) {
+    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;
+  }
+
+  get isConnected(): boolean {
+    return this.connected;
+  }
+
+  /** 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');
+    if (this.connecting) return this.connecting;
+    this.connecting = this.doConnect().finally(() => {
+      this.connecting = null;
+    });
+    return this.connecting;
+  }
+
+  private async doConnect(): Promise<void> {
+    const socket = await this.openSocket();
+    socket.setNoDelay(true);
+    this.parser.clear();
+    this.socket = socket;
+
+    socket.on('data', (chunk: Buffer) => this.handleData(chunk));
+    socket.on('error', () => this.teardown());
+    socket.on('close', () => this.teardown());
+
+    this.connected = true;
+
+    if (this.token) {
+      try {
+        await this.call({ cmd: 'Auth', token: this.token });
+      } catch (err) {
+        this.teardown();
+        if (err instanceof CommandError) throw new AuthError(err.message);
+        throw err;
+      }
+    }
+  }
+
+  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.
+   */
+  async call(command: Command, timeoutMs?: number): Promise<Response> {
+    if (!this.connected) await this.connect();
+    const socket = this.socket;
+    if (!socket) throw new ConnectionClosedError('not connected');
+
+    this.reqCounter = (this.reqCounter + 1) & 0x7fffffff;
+    const reqId = String(this.reqCounter);
+    const payload = pack({ ...compact(command), reqId });
+
+    return new Promise<Response>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(reqId);
+        reject(new CommandTimeoutError(`no response for ${command.cmd} within timeout`));
+      }, timeoutMs ?? this.commandTimeoutMs);
+
+      this.pending.set(reqId, {
+        resolve: (response) => {
+          clearTimeout(timer);
+          if (!response.ok) {
+            reject(new CommandError(String(response.error ?? 'unknown server error')));
+          } else {
+            resolve(response);
+          }
+        },
+        reject: (err) => {
+          clearTimeout(timer);
+          reject(err);
+        },
+        timer,
+      });
+
+      socket.write(frame(payload), (err) => {
+        if (err) {
+          const entry = this.pending.get(reqId);
+          this.pending.delete(reqId);
+          entry?.reject(new ConnectionClosedError(`send failed: ${err.message}`));
+          this.teardown();
+        }
+      });
+    });
+  }
+
+  /** Ping the server; returns true when it answers pong. */
+  async ping(): Promise<boolean> {
+    try {
+      const response = await this.call({ cmd: 'Ping' });
+      const data = response.data as Record<string, unknown> | undefined;
+      return data?.pong === true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Protocol negotiation; returns server name/version/protocolVersion. */
+  hello(): Promise<Response> {
+    return this.call({
+      cmd: 'Hello',
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: ['pipelining'],
+    });
+  }
+
+  /** Close permanently; in-flight commands reject. */
+  close(): void {
+    this.closed = true;
+    this.teardown();
+  }
+
+  private handleData(chunk: Buffer): void {
+    let frames: Buffer[];
+    try {
+      frames = this.parser.addData(chunk);
+    } catch {
+      this.teardown();
+      return;
+    }
+    for (const framePayload of frames) {
+      let message: unknown;
+      try {
+        message = unpack(framePayload);
+      } catch {
+        continue; // skip unparseable frame; a desynced stream dies via socket error
+      }
+      if (typeof message !== 'object' || message === null) continue;
+      const response = message as Response;
+      const reqId = response.reqId;
+      if (reqId === undefined || reqId === null) continue; // server-push unsupported
+      const entry = this.pending.get(String(reqId));
+      if (entry) {
+        this.pending.delete(String(reqId));
+        entry.resolve(response);
+      }
+    }
+  }
+
+  private teardown(): void {
+    this.connected = false;
+    const socket = this.socket;
+    this.socket = null;
+    if (socket) {
+      socket.removeAllListeners();
+      socket.destroy();
+    }
+    const pending = this.pending;
+    this.pending = new Map();
+    for (const entry of pending.values()) {
+      clearTimeout(entry.timer);
+      entry.reject(new ConnectionClosedError('connection lost'));
+    }
+  }
+}

package/src/errors.ts

@@ -0,0 +1,26 @@
+/** Exception hierarchy for the bunqueue cross-runtime SDK. */
+
+export class BunqueueError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = new.target.name;
+  }
+}
+
+/** The TCP connection is closed or was lost mid-command. */
+export class ConnectionClosedError extends BunqueueError {}
+
+/** No response received for a command within the timeout. */
+export class CommandTimeoutError extends BunqueueError {}
+
+/** The server answered ok=false; message carries the server error. */
+export class CommandError extends BunqueueError {}
+
+/** Authentication with the server failed. */
+export class AuthError extends BunqueueError {}
+
+/**
+ * Throw inside a Worker processor to fail the job terminally: skips all
+ * remaining retry attempts and sends the job straight to the DLQ.
+ */
+export class UnrecoverableError extends BunqueueError {}

package/src/flow-types.ts

@@ -0,0 +1,40 @@
+/** FlowProducer types. */
+
+import type { Connection, TlsOption } from './connection.js';
+import type { Job } from './job.js';
+import type { JobOptions } from './types.js';
+
+export interface FlowJob<T = unknown> {
+  name: string;
+  queueName: string;
+  data?: T;
+  opts?: JobOptions;
+  children?: FlowJob<T>[];
+}
+
+export interface JobNode<T = unknown> {
+  job: Job<T>;
+  children?: JobNode<T>[];
+}
+
+export interface FlowStep<T = unknown> {
+  name: string;
+  queueName: string;
+  data?: T;
+  opts?: JobOptions;
+}
+
+export interface FlowProducerOptions {
+  host?: string;
+  port?: number;
+  token?: string;
+  tls?: TlsOption;
+  connection?: Connection;
+}
+
+export interface GetFlowOptions {
+  id: string;
+  queueName?: string;
+  depth?: number;
+  maxChildren?: number;
+}

package/src/flow.ts

@@ -0,0 +1,236 @@
+/**
+ * FlowProducer: parent/children job trees, chains and fan-in flows.
+ * Mirrors the official client's TCP flow logic (bottom-up creation,
+ * UpdateParent fix-up, rollback via Cancel on failure).
+ */
+
+import { Connection } from './connection.js';
+import type {
+  FlowJob,
+  FlowProducerOptions,
+  FlowStep,
+  GetFlowOptions,
+  JobNode,
+} from './flow-types.js';
+import { compact } from './frame.js';
+import { Job } from './job.js';
+import { type JobOptions, jobPayload, wireJobOptions } from './types.js';
+
+export class FlowProducer {
+  readonly connection: Connection;
+  private readonly ownsConnection: boolean;
+
+  constructor(opts: FlowProducerOptions = {}) {
+    this.connection =
+      opts.connection ??
+      new Connection({ host: opts.host, port: opts.port, token: opts.token, tls: opts.tls });
+    this.ownsConnection = opts.connection === undefined;
+  }
+
+  /** Add a flow tree. Children are created (and processed) BEFORE their parent. */
+  async add<T = unknown>(flow: FlowJob<T>): Promise<JobNode<T>> {
+    const created: string[] = [];
+    try {
+      return await this.addNode(flow, null, created);
+    } catch (err) {
+      await this.rollback(created);
+      throw err;
+    }
+  }
+
+  async addBulk<T = unknown>(flows: FlowJob<T>[]): Promise<JobNode<T>[]> {
+    const created: string[] = [];
+    const results: JobNode<T>[] = [];
+    try {
+      for (const flow of flows) {
+        results.push(await this.addNode(flow, null, created));
+      }
+      return results;
+    } catch (err) {
+      await this.rollback(created);
+      throw err;
+    }
+  }
+
+  /** 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);
+  }
+
+  /** Add a sequential chain: step[0] → step[1] → ... via dependsOn. */
+  async addChain<T = unknown>(steps: FlowStep<T>[]): Promise<{ jobIds: string[] }> {
+    if (steps.length === 0) return { jobIds: [] };
+    const jobIds: string[] = [];
+    let prevId: string | null = null;
+    try {
+      for (const step of steps) {
+        const data = 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 }
+        );
+        const id = String(response.id);
+        jobIds.push(id);
+        prevId = id;
+      }
+      return { jobIds };
+    } catch (err) {
+      await this.rollback(jobIds);
+      throw err;
+    }
+  }
+
+  /** Parallel jobs converging into a final fan-in job. */
+  async addBulkThen<T = unknown>(
+    parallel: FlowStep<T>[],
+    final: FlowStep<T>
+  ): Promise<{ parallelIds: string[]; finalId: string }> {
+    const parallelIds: string[] = [];
+    try {
+      const results = await Promise.allSettled(
+        parallel.map(async (step) => {
+          const response = await this.connection.call(
+            compact({
+              cmd: 'PUSH',
+              queue: step.queueName,
+              data: jobPayload(step.name, step.data),
+              ...wireJobOptions(step.opts),
+            }) as { cmd: string }
+          );
+          return String(response.id);
+        })
+      );
+      const errors: unknown[] = [];
+      for (const r of results) {
+        if (r.status === 'fulfilled') parallelIds.push(r.value);
+        else errors.push(r.reason);
+      }
+      if (errors.length > 0) {
+        await this.rollback(parallelIds);
+        throw errors[0] instanceof Error ? errors[0] : new Error(String(errors[0]));
+      }
+
+      const finalData = {
+        ...jobPayload(final.name, final.data),
+        __flowParentIds: parallelIds,
+      };
+      const finalId = await this.pushWithParent(
+        final.queueName,
+        finalData,
+        final.opts,
+        null,
+        parallelIds
+      );
+      return { parallelIds, finalId };
+    } catch (err) {
+      await this.rollback(parallelIds);
+      throw err;
+    }
+  }
+
+  close(): void {
+    if (this.ownsConnection) this.connection.close();
+  }
+
+  // ----------------------------------------------------------------- internals
+
+  private async addNode<T>(
+    node: FlowJob<T>,
+    parentRef: { id: string; queue: string } | null,
+    created: string[]
+  ): Promise<JobNode<T>> {
+    const childNodes: JobNode<T>[] = [];
+    const childIds: string[] = [];
+
+    if (node.children && node.children.length > 0) {
+      const tempParent = { id: 'pending', queue: node.queueName };
+      const results = await Promise.all(
+        node.children.map((child) => this.addNode(child, tempParent, created))
+      );
+      for (const childNode of results) {
+        childNodes.push(childNode);
+        childIds.push(childNode.job.id);
+      }
+    }
+
+    const jobData: Record<string, unknown> = jobPayload(node.name, node.data);
+    if (parentRef) {
+      jobData.__parentId = parentRef.id;
+      jobData.__parentQueue = parentRef.queue;
+    }
+    if (childIds.length > 0) jobData.__childrenIds = childIds;
+
+    const id = await this.pushWithParent(node.queueName, jobData, node.opts, parentRef, childIds);
+    created.push(id);
+
+    const job = new Job<T>({ id, queue: node.queueName, data: jobData }, this.connection);
+    return { job, children: childNodes.length > 0 ? childNodes : undefined };
+  }
+
+  private async pushWithParent(
+    queue: string,
+    data: Record<string, unknown>,
+    opts: JobOptions | undefined,
+    parentRef: { id: string; queue: string } | null,
+    childIds: string[]
+  ): Promise<string> {
+    const response = await this.connection.call(
+      compact({
+        cmd: 'PUSH',
+        queue,
+        data,
+        ...wireJobOptions(opts),
+        parentId: parentRef?.id,
+        childrenIds: childIds.length > 0 ? childIds : undefined,
+        dependsOn: childIds.length > 0 ? childIds : undefined,
+      }) as { cmd: string }
+    );
+    const parentJobId = String(response.id);
+
+    // fix up children with the real parent id (like the official client)
+    for (const childId of childIds) {
+      await this.connection.call({ cmd: 'UpdateParent', childId, parentId: parentJobId });
+    }
+    return parentJobId;
+  }
+
+  private async fetchNode<T>(
+    id: string,
+    depth: number,
+    maxChildren?: number
+  ): Promise<JobNode<T> | null> {
+    const response = await this.connection.call({ cmd: 'GetJob', id });
+    const raw = response.job as Record<string, unknown> | null;
+    if (!raw) return null;
+    const job = new Job<T>(raw, this.connection);
+    if (depth <= 0 || job.childrenIds.length === 0) return { job };
+
+    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);
+      if (child) children.push(child);
+    }
+    return { job, children: children.length > 0 ? children : undefined };
+  }
+
+  private async rollback(jobIds: string[]): Promise<void> {
+    await Promise.all(
+      jobIds.map(async (id) => {
+        try {
+          await this.connection.call({ cmd: 'Cancel', id });
+        } catch {
+          // ignore cleanup errors
+        }
+      })
+    );
+  }
+}

package/src/frame.ts

@@ -0,0 +1,62 @@
+/**
+ * Wire framing for the bunqueue TCP protocol: 4-byte big-endian length
+ * prefix + msgpack payload. Runtime-neutral (plain Buffer operations).
+ */
+
+import { ConnectionClosedError } from './errors.js';
+
+export const PROTOCOL_VERSION = 1;
+export const MAX_FRAME_SIZE = 64 * 1024 * 1024; // mirror server-side limit
+
+/** Drop undefined-valued keys so the msgpack frame stays minimal. */
+export function compact<T extends Record<string, unknown>>(obj: T): T {
+  const out: Record<string, unknown> = {};
+  for (const key in obj) {
+    if (obj[key] !== undefined) out[key] = obj[key];
+  }
+  return out as T;
+}
+
+/** Frame a msgpack payload with the 4-byte big-endian length prefix. */
+export function frame(payload: Uint8Array): Buffer {
+  const framed = Buffer.allocUnsafe(4 + payload.length);
+  framed.writeUInt32BE(payload.length, 0);
+  framed.set(payload, 4);
+  return framed;
+}
+
+/** Incremental length-prefixed frame parser (O(total bytes) via offset cursor). */
+export class FrameParser {
+  private buffer: Buffer = Buffer.alloc(0);
+
+  addData(data: Buffer): Buffer[] {
+    const buffer = this.buffer.length === 0 ? data : Buffer.concat([this.buffer, data]);
+    const frames: Buffer[] = [];
+    let offset = 0;
+
+    while (buffer.length - offset >= 4) {
+      const length = buffer.readUInt32BE(offset);
+      if (length > MAX_FRAME_SIZE) {
+        this.buffer = Buffer.alloc(0);
+        throw new ConnectionClosedError(`frame size ${length} exceeds maximum`);
+      }
+      if (buffer.length - offset < 4 + length) break;
+      // explicit copy so frames never alias the retained tail
+      frames.push(Buffer.from(buffer.subarray(offset + 4, offset + 4 + length)));
+      offset += 4 + length;
+    }
+
+    if (offset >= buffer.length) {
+      this.buffer = Buffer.alloc(0);
+    } else if (offset === 0) {
+      this.buffer = buffer;
+    } else {
+      this.buffer = Buffer.from(buffer.subarray(offset));
+    }
+    return frames;
+  }
+
+  clear(): void {
+    this.buffer = Buffer.alloc(0);
+  }
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+/**
+ * bunqueue-client — cross-runtime TypeScript SDK for bunqueue (TCP mode).
+ * Works on Node.js ≥20, Bun and Deno ≥2 (uses only node: builtins + msgpackr).
+ */
+
+export type { Command, ConnectionOptions, Response, TlsOption } from './connection.js';
+export { Connection } from './connection.js';
+export {
+  AuthError,
+  BunqueueError,
+  CommandError,
+  CommandTimeoutError,
+  ConnectionClosedError,
+  UnrecoverableError,
+} from './errors.js';
+export { FlowProducer } from './flow.js';
+export type {
+  FlowJob,
+  FlowProducerOptions,
+  FlowStep,
+  GetFlowOptions,
+  JobNode,
+} from './flow-types.js';
+export { MAX_FRAME_SIZE, PROTOCOL_VERSION } from './frame.js';
+export type { JobRaw } from './job.js';
+export { Job } from './job.js';
+export type { BulkJobEntry, QueueOptions } from './queue.js';
+export { Queue } from './queue.js';
+export type { SchedulerOptions } from './queue-admin.js';
+export type {
+  BackoffOptions,
+  DeduplicationOptions,
+  JobCounts,
+  JobOptions,
+  JobStateName,
+  RepeatOptions,
+} from './types.js';
+export { Worker } from './worker.js';
+export type { Processor, WorkerOptions } from './worker-types.js';
+
+export const __version__ = '0.1.0';