bunqueue-client 0.1.9 → 0.2.0

package/dist/bunqueue/retry.js

@@ -1,56 +0,0 @@
-/**
- * Bunqueue Simple Mode — advanced in-process retry with backoff strategies.
- * 1:1 port of src/client/bunqueue/retry.ts (identical formulas).
- */
-/** Calculate backoff delay based on strategy. */
-export function calculateBackoff(strategy, attempt, baseDelay, error, config) {
-    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(fn, config) {
-    const maxAttempts = config.maxAttempts ?? 3;
-    const baseDelay = config.delay ?? 1000;
-    const strategy = config.strategy ?? 'exponential';
-    const attempt = (n) => {
-        return fn().catch((err) => {
-            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((resolve) => {
-                setTimeout(() => {
-                    resolve(attempt(n + 1));
-                }, delay);
-            });
-        });
-    };
-    return attempt(1);
-}

package/dist/bunqueue/triggers.js

@@ -1,42 +0,0 @@
-/**
- * Bunqueue Simple Mode — event triggers.
- * 1:1 port of src/client/bunqueue/triggers.ts: when a job completes/fails,
- * automatically create another job.
- */
-export class TriggerManager {
-    rules = [];
-    active = false;
-    queue;
-    worker;
-    constructor(queue, worker) {
-        this.queue = queue;
-        this.worker = worker;
-    }
-    add(rule) {
-        this.rules.push(rule);
-        this.ensureActive();
-    }
-    ensureActive() {
-        if (this.active)
-            return;
-        this.active = true;
-        this.worker.on('completed', (job, result) => {
-            this.fire('completed', job, result);
-        });
-        this.worker.on('failed', (job, error) => {
-            this.fire('failed', job, error);
-        });
-    }
-    fire(event, job, resultOrError) {
-        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/dist/bunqueue/ttl.js

@@ -1,31 +0,0 @@
-/**
- * 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.
- */
-export class TtlChecker {
-    config;
-    constructor(config) {
-        this.config = config;
-    }
-    /** Get TTL for a specific job name. */
-    getTtl(jobName) {
-        return this.config.perName?.[jobName] ?? this.config.defaultTtl ?? 0;
-    }
-    /** Check if a job has expired. */
-    isExpired(jobName, jobTimestamp) {
-        const ttl = this.getTtl(jobName);
-        if (ttl <= 0)
-            return false;
-        return Date.now() - jobTimestamp > ttl;
-    }
-    /** Set default TTL. */
-    setDefaultTtl(ttlMs) {
-        this.config.defaultTtl = ttlMs;
-    }
-    /** Set TTL for a specific job name. */
-    setNameTtl(jobName, ttlMs) {
-        this.config.perName ??= {};
-        this.config.perName[jobName] = ttlMs;
-    }
-}

package/dist/bunqueue/types.js

@@ -1,6 +0,0 @@
-/**
- * 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).
- */
-export {};

package/dist/connection-pool.js

@@ -1,60 +0,0 @@
-/**
- * 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 { LIFECYCLE_EVENTS } from './observability.js';
-export class ConnectionPool extends EventEmitter {
-    connections;
-    cursor = 0;
-    constructor(size, options = {}) {
-        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() {
-        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();
-    }
-    /** True while at least one member connection is up. */
-    get isConnected() {
-        return this.connections.some((conn) => conn.isConnected);
-    }
-    /** Representative generation (first connection); pools are producer-side. */
-    get generation() {
-        return this.connections[0].generation;
-    }
-}

package/dist/connection-types.js

@@ -1,2 +0,0 @@
-/** Connection option and message types. */
-export {};

package/dist/connection.js

@@ -1,281 +0,0 @@
-/**
- * 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 { EventEmitter } from 'node:events';
-import { pack, unpack } from 'msgpackr';
-import { Backpressure } from './backpressure.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';
-/**
- * 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 {
-    host;
-    port;
-    token;
-    tls;
-    connectTimeoutMs;
-    commandTimeoutMs;
-    socket = null;
-    connected = false;
-    closed = false;
-    connecting = null;
-    pending = new Map();
-    reqCounter = 0;
-    parser = new FrameParser();
-    connectGeneration = 0;
-    failedAttempts = 0;
-    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.
-    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 ?? 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() {
-        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() {
-        return this.connectGeneration;
-    }
-    /** Open the socket (and authenticate) if not already connected. */
-    async connect() {
-        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()
-            .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 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;
-        socket.on('data', (chunk) => this.handleData(chunk));
-        socket.on('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);
-        // 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;
-            }
-        }
-    }
-    /**
-     * 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, timeoutMs) {
-        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 (!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((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);
-                    }
-                },
-                reject: (err) => {
-                    clearTimeout(timer);
-                    reject(err);
-                },
-                timer,
-            });
-            socket.write(frame(payload), (err) => {
-                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();
-                }
-            });
-        });
-    }
-    /** Ping the server; returns true when it answers pong. */
-    async ping() {
-        try {
-            const response = await this.call({ cmd: 'Ping' });
-            const data = response.data;
-            return data?.pong === true;
-        }
-        catch {
-            return false;
-        }
-    }
-    /** Protocol negotiation; returns server name/version/protocolVersion. */
-    hello() {
-        return this.call({
-            cmd: 'Hello',
-            protocolVersion: PROTOCOL_VERSION,
-            capabilities: ['pipelining'],
-        });
-    }
-    /** Close permanently; in-flight commands reject. */
-    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; // skip unparseable frame; a desynced stream dies via socket error
-            }
-            if (typeof message !== 'object' || message === null)
-                continue;
-            const response = message;
-            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));
-                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).
-     */
-    noteTimeout(gen) {
-        // 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();
-    }
-    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 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/dist/errors.js

@@ -1,25 +0,0 @@
-/** Exception hierarchy for the bunqueue cross-runtime SDK. */
-export class BunqueueError extends Error {
-    constructor(message) {
-        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/dist/flow-types.js

@@ -1,2 +0,0 @@
-/** FlowProducer types. */
-export {};