bunqueue-client 0.1.8 → 0.2.0

package/dist/chunk-jxkszwqp.js

@@ -0,0 +1,573 @@
+import {
+  ConnectionClosedError2,
+  CommandTimeoutError2,
+  CommandError2,
+  SerializationError2,
+  AuthError2,
+  PROTOCOL_VERSION2,
+  frame2,
+  FrameParser2
+} from "./chunk-b967v3w3.js";
+
+// src/observability.ts
+var noopLogger2 = {
+  debug() {},
+  info() {},
+  warn() {},
+  error() {}
+};
+var LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+function consoleLogger2(min = "info") {
+  const floor = LEVELS[min];
+  const line = (lvl, msg, meta) => {
+    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)
+  };
+}
+var LIFECYCLE_EVENTS = ["connect", "disconnect", "reconnect_scheduled"];
+var nowMs = () => performance.now();
+var ERROR_MESSAGES = {
+  connect: "connection failed",
+  socket: "socket failed",
+  write: "socket write failed",
+  serialization: "command serialization failed"
+};
+
+class Telemetry {
+  logger;
+  sink;
+  emit;
+  constructor(obs, emit) {
+    const inner = obs?.logger ?? noopLogger2;
+    this.logger = inner === noopLogger2 ? 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;
+  }
+  static safely(fn) {
+    try {
+      fn();
+    } catch {}
+  }
+  get log() {
+    return this.logger;
+  }
+  command(cmd, reqId, startMs, ok) {
+    this.dispatch({ type: "command", cmd, reqId, durationMs: nowMs() - startMs, ok });
+  }
+  timeout(cmd, reqId) {
+    this.logger.warn("command timed out", { cmd, reqId });
+    this.dispatch({ type: "command_timeout", cmd, reqId });
+  }
+  connected(host, port, generation, startMs) {
+    this.logger.info("connected", { host, port, generation });
+    this.dispatch({ type: "connect", host, port, generation, durationMs: nowMs() - startMs });
+  }
+  disconnected(host, port, generation) {
+    this.logger.info("disconnected", { host, port, generation });
+    this.dispatch({ type: "disconnect", host, port, generation });
+  }
+  reconnectScheduled(host, port, attempt, delayMs) {
+    this.logger.warn("reconnect scheduled", { host, port, attempt, delayMs });
+    this.dispatch({ type: "reconnect_scheduled", host, port, attempt, delayMs });
+  }
+  auth(ok) {
+    this.dispatch({ type: "auth", ok });
+  }
+  backpressure(inFlight, maxInFlight) {
+    this.dispatch({ type: "backpressure", inFlight, maxInFlight });
+  }
+  error(operation, error) {
+    const errorType = error instanceof Error && /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(error.name) ? error.name : "Error";
+    const rawCode = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+    const code = typeof rawCode === "string" && /^[A-Z0-9_]{1,32}$/.test(rawCode) ? rawCode : undefined;
+    const event = {
+      type: "error",
+      operation,
+      errorType,
+      message: ERROR_MESSAGES[operation],
+      ...code ? { code } : {}
+    };
+    this.logger.error(event.message, { operation, errorType, ...code ? { code } : {} });
+    this.dispatch(event);
+  }
+  capture(operation, fn) {
+    try {
+      return fn();
+    } catch (error) {
+      this.error(operation, error);
+      throw error;
+    }
+  }
+  async captureAsync(operation, promise) {
+    try {
+      return await promise;
+    } catch (error) {
+      this.error(operation, error);
+      throw error;
+    }
+  }
+  dispatch(event) {
+    Telemetry.safely(() => this.sink?.(event));
+    if (LIFECYCLE_EVENTS.includes(event.type)) {
+      Telemetry.safely(() => this.emit(event.type, event));
+    }
+  }
+}
+
+// src/connection.ts
+import { EventEmitter } from "node:events";
+import { unpack } from "msgpackr";
+
+// src/backpressure.ts
+class Backpressure {
+  max;
+  onWait;
+  waiters = [];
+  constructor(max, onWait) {
+    this.max = max;
+    this.onWait = onWait;
+  }
+  acquire(inFlight) {
+    if (this.max <= 0 || inFlight < this.max)
+      return;
+    this.onWait?.();
+    return new Promise((resolve) => {
+      this.waiters.push(resolve);
+    });
+  }
+  release() {
+    this.waiters.shift()?.();
+  }
+  clear() {
+    while (this.waiters.length > 0)
+      this.waiters.shift()?.();
+  }
+  get waiting() {
+    return this.waiters.length;
+  }
+}
+
+// src/serialization.ts
+import { pack } from "msgpackr";
+var invalid = (reason) => {
+  throw new SerializationError2(`cannot serialize command as MessagePack: ${reason}`);
+};
+function normalizeWireValue(value, active) {
+  if (value === null || typeof value === "string" || typeof value === "boolean")
+    return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value))
+      invalid("numbers must be finite");
+    return value;
+  }
+  if (typeof value === "bigint")
+    invalid("BigInt is not JavaScript-safe on the broker");
+  if (typeof value === "undefined")
+    invalid("nested undefined values are not portable");
+  if (typeof value === "symbol" || typeof value === "function") {
+    invalid(`${typeof value} values are unsupported`);
+  }
+  if (typeof value !== "object")
+    invalid("unsupported value");
+  const objectValue = value;
+  if (value instanceof Date) {
+    if (!Number.isFinite(value.getTime()))
+      invalid("invalid Date");
+    return new Date(value.getTime());
+  }
+  if (value instanceof Uint8Array || value instanceof ArrayBuffer)
+    return value;
+  if (active.has(objectValue))
+    invalid("cyclic structures are unsupported");
+  active.add(objectValue);
+  try {
+    if (Array.isArray(value)) {
+      return Array.from(value, (entry) => normalizeWireValue(entry, active));
+    }
+    if (value instanceof Map) {
+      const normalized = new Map;
+      for (const [key, entry] of value) {
+        if (typeof key !== "string")
+          invalid("map keys must be strings");
+        normalized.set(key, normalizeWireValue(entry, active));
+      }
+      return normalized;
+    }
+    const prototype = Object.getPrototypeOf(objectValue);
+    if (prototype !== Object.prototype && prototype !== null) {
+      invalid("only plain objects, arrays, maps, dates, and binary values are supported");
+    }
+    const normalized = Object.create(null);
+    for (const key of Reflect.ownKeys(objectValue)) {
+      if (typeof key !== "string")
+        invalid("symbol object keys are unsupported");
+      const stringKey = key;
+      const descriptor = Object.getOwnPropertyDescriptor(objectValue, stringKey);
+      if (!descriptor?.enumerable)
+        continue;
+      if (!("value" in descriptor))
+        invalid("accessor properties are unsupported");
+      normalized[stringKey] = normalizeWireValue(descriptor.value, active);
+    }
+    return normalized;
+  } finally {
+    active.delete(objectValue);
+  }
+}
+function prepareCommand(command, reqId) {
+  const envelope = Object.create(null);
+  for (const key of Reflect.ownKeys(command)) {
+    if (typeof key !== "string")
+      invalid("symbol command keys are unsupported");
+    const stringKey = key;
+    const descriptor = Object.getOwnPropertyDescriptor(command, stringKey);
+    if (!descriptor?.enumerable)
+      continue;
+    if (!("value" in descriptor))
+      invalid("accessor command properties are unsupported");
+    if (descriptor.value === undefined)
+      continue;
+    envelope[stringKey] = descriptor.value;
+  }
+  envelope.reqId = reqId;
+  return normalizeWireValue(envelope, new WeakSet);
+}
+function serializeCommand(command, reqId) {
+  try {
+    return frame2(pack(prepareCommand(command, reqId)));
+  } catch (error) {
+    if (error instanceof SerializationError2)
+      throw error;
+    throw new SerializationError2("cannot serialize command as MessagePack");
+  }
+}
+
+// src/socket-factory.ts
+import { readFileSync } from "node:fs";
+import { connect as netConnect } from "node:net";
+import { connect as tlsConnect } from "node:tls";
+function openSocket(host, port, tls, connectTimeoutMs) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled)
+        return;
+      settled = true;
+      socket.destroy();
+      reject(new ConnectionClosedError2(`connect timeout to ${host}:${port}`));
+    }, connectTimeoutMs);
+    const onError = (err) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      reject(new ConnectionClosedError2(`connect failed: ${err.message}`));
+    };
+    const onReady = () => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      socket.off("error", onError);
+      resolve(socket);
+    };
+    let socket;
+    if (tls) {
+      const tlsOpts = { host, port };
+      if (typeof tls === "object") {
+        if (tls.caFile)
+          tlsOpts.ca = readFileSync(tls.caFile);
+        if (tls.rejectUnauthorized === false)
+          tlsOpts.rejectUnauthorized = false;
+      }
+      socket = tlsConnect(tlsOpts, onReady);
+    } else {
+      socket = netConnect({ host, port }, onReady);
+    }
+    socket.on("error", onError);
+  });
+}
+
+// src/connection.ts
+class Connection2 extends EventEmitter {
+  host;
+  port;
+  token;
+  tls;
+  connectTimeoutMs;
+  commandTimeoutMs;
+  socket = null;
+  connected = false;
+  closed = false;
+  connecting = null;
+  pending = new Map;
+  reqCounter = 0;
+  parser = new FrameParser2;
+  connectGeneration = 0;
+  failedAttempts = 0;
+  nextAttemptAt = 0;
+  maxCommandTimeouts = 3;
+  consecutiveTimeouts = 0;
+  telemetry;
+  backpressure;
+  constructor(options = {}) {
+    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 ?? 1e4;
+    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() {
+    return this.connected;
+  }
+  get generation() {
+    return this.connectGeneration;
+  }
+  async connect() {
+    if (this.connected)
+      return;
+    if (this.closed)
+      throw new ConnectionClosedError2("connection closed by client");
+    if (Date.now() < this.nextAttemptAt) {
+      throw new ConnectionClosedError2(`server unreachable, retry in ${this.nextAttemptAt - Date.now()}ms`);
+    }
+    if (this.connecting)
+      return this.connecting;
+    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;
+      this.telemetry.reconnectScheduled(this.host, this.port, this.failedAttempts, backoff);
+      throw err;
+    }).finally(() => {
+      this.connecting = null;
+    });
+    return this.connecting;
+  }
+  async doConnect() {
+    const startMs = nowMs();
+    const socket = await this.telemetry.captureAsync("connect", openSocket(this.host, this.port, this.tls, this.connectTimeoutMs));
+    socket.setNoDelay(true);
+    socket.setKeepAlive(true, 15000);
+    this.parser.clear();
+    this.socket = socket;
+    socket.on("data", (chunk) => this.handleData(chunk));
+    socket.on("error", (error) => {
+      this.telemetry.error("socket", error);
+      this.teardown();
+    });
+    socket.on("close", () => this.teardown());
+    this.connected = true;
+    this.connectGeneration += 1;
+    this.consecutiveTimeouts = 0;
+    this.telemetry.connected(this.host, this.port, this.connectGeneration, startMs);
+    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 CommandError2)
+          throw new AuthError2(err.message);
+        throw err;
+      }
+    }
+  }
+  async call(command, timeoutMs) {
+    if (!this.connected)
+      await this.connect();
+    this.reqCounter = this.reqCounter + 1 & 2147483647;
+    const reqId = String(this.reqCounter);
+    const outbound = this.telemetry.capture("serialization", () => serializeCommand(command, reqId));
+    const gate = this.backpressure.acquire(this.pending.size);
+    if (gate)
+      await gate;
+    const socket = this.socket;
+    if (!this.connected || !socket)
+      throw new ConnectionClosedError2("not connected");
+    const gen = this.connectGeneration;
+    const startMs = nowMs();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(reqId);
+        this.backpressure.release();
+        this.telemetry.timeout(command.cmd, reqId);
+        this.noteTimeout(gen);
+        reject(new CommandTimeoutError2(`no response for ${command.cmd} within timeout`));
+      }, timeoutMs ?? this.commandTimeoutMs);
+      this.pending.set(reqId, {
+        resolve: (response) => {
+          clearTimeout(timer);
+          this.consecutiveTimeouts = 0;
+          this.telemetry.command(command.cmd, reqId, startMs, response.ok);
+          if (!response.ok) {
+            reject(new CommandError2(String(response.error ?? "unknown server error")));
+          } else {
+            resolve(response);
+          }
+        },
+        reject: (err) => {
+          clearTimeout(timer);
+          reject(err);
+        },
+        timer
+      });
+      socket.write(outbound, (err) => {
+        if (err) {
+          this.telemetry.error("write", err);
+          const entry = this.pending.get(reqId);
+          this.pending.delete(reqId);
+          this.backpressure.release();
+          entry?.reject(new ConnectionClosedError2(`send failed: ${err.message}`));
+          this.teardown();
+        }
+      });
+    });
+  }
+  async ping() {
+    try {
+      const response = await this.call({ cmd: "Ping" });
+      const data = response.data;
+      return data?.pong === true;
+    } catch {
+      return false;
+    }
+  }
+  hello() {
+    return this.call({
+      cmd: "Hello",
+      protocolVersion: PROTOCOL_VERSION2,
+      capabilities: ["pipelining", "separate-job-name"]
+    });
+  }
+  close() {
+    this.closed = true;
+    this.teardown();
+  }
+  handleData(chunk) {
+    let frames;
+    try {
+      frames = this.parser.addData(chunk);
+    } catch {
+      this.teardown();
+      return;
+    }
+    for (const framePayload of frames) {
+      let message;
+      try {
+        message = unpack(framePayload);
+      } catch {
+        continue;
+      }
+      if (typeof message !== "object" || message === null)
+        continue;
+      const response = message;
+      const reqId = response.reqId;
+      if (reqId === undefined || reqId === null)
+        continue;
+      const entry = this.pending.get(String(reqId));
+      if (entry) {
+        this.pending.delete(String(reqId));
+        this.backpressure.release();
+        entry.resolve(response);
+      }
+    }
+  }
+  noteTimeout(gen) {
+    if (gen !== this.connectGeneration)
+      return;
+    this.consecutiveTimeouts += 1;
+    if (this.consecutiveTimeouts >= this.maxCommandTimeouts)
+      this.teardown();
+  }
+  teardown() {
+    const wasConnected = this.socket !== null;
+    const gen = this.connectGeneration;
+    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 ConnectionClosedError2("connection lost"));
+    }
+    this.backpressure.clear();
+    if (wasConnected)
+      this.telemetry.disconnected(this.host, this.port, gen);
+  }
+}
+
+// src/connection-pool.ts
+import { EventEmitter as EventEmitter2 } from "node:events";
+class ConnectionPool2 extends EventEmitter2 {
+  connections;
+  cursor = 0;
+  constructor(size, options = {}) {
+    super();
+    const n = Math.max(1, Math.floor(size));
+    this.connections = Array.from({ length: n }, () => {
+      const conn = new Connection2(options);
+      for (const event of LIFECYCLE_EVENTS) {
+        conn.on(event, (payload) => this.emit(event, payload));
+      }
+      return conn;
+    });
+  }
+  get size() {
+    return this.connections.length;
+  }
+  next() {
+    const conn = this.connections[this.cursor];
+    this.cursor = (this.cursor + 1) % this.connections.length;
+    return conn;
+  }
+  call(command, timeoutMs) {
+    return this.next().call(command, timeoutMs);
+  }
+  ping() {
+    return this.connections[0].ping();
+  }
+  async connect() {
+    await Promise.all(this.connections.map((conn) => conn.connect()));
+  }
+  close() {
+    for (const conn of this.connections)
+      conn.close();
+  }
+  get isConnected() {
+    return this.connections.some((conn) => conn.isConnected);
+  }
+  get generation() {
+    return this.connections[0].generation;
+  }
+}
+
+export { noopLogger2, consoleLogger2, Connection2, ConnectionPool2 };