bunqueue 2.8.54 → 2.8.56

package/dist/client/tcp/connection.js

@@ -1,315 +1,3 @@
-/**
- * TCP Connection Handler
- * Manages low-level socket connection and data handling (msgpack binary protocol)
- */
-import { readFileSync } from 'node:fs';
-import { FrameParser, FrameSizeError } from '../../infrastructure/server/protocol';
-/**
- * Map client TLS options to the `tls` value accepted by Bun.connect.
- * Returns undefined when TLS is disabled (plaintext, the default).
- *
- * The CA is read into bytes (not passed as a `Bun.file` handle): Bun computes
- * the peer's `authorizationError` from this `ca`, and we enforce it in the
- * `handshake` handler (see `tlsRequiresVerification` / #109) — Bun.connect
- * itself never rejects an unauthorized peer on the client side.
- */
-export function buildClientTls(tls) {
-    if (!tls)
-        return undefined;
-    if (tls === true)
-        return true;
-    return {
-        ...(tls.rejectUnauthorized !== undefined && { rejectUnauthorized: tls.rejectUnauthorized }),
-        ...(tls.caFile !== undefined && { ca: readFileSync(tls.caFile) }),
-    };
-}
-/**
- * Whether the caller asked us to authenticate the server certificate.
- * Verification is the default for any TLS connection; only an explicit
- * `rejectUnauthorized: false` opts out (encryption-only). #109
- */
-export function tlsRequiresVerification(tls) {
-    if (!tls)
-        return false;
-    if (tls === true)
-        return true;
-    return tls.rejectUnauthorized !== false;
-}
-/**
- * Establish TCP connection to server
- */
-export async function createConnection(target, connectTimeout, events) {
-    return new Promise((resolve, reject) => {
-        const socketData = {
-            write: () => { },
-            end: () => { },
-            frameParser: new FrameParser(),
-        };
-        let connectionResolved = false;
-        let timeoutId = null;
-        // TLS server-certificate verification. Bun.connect never rejects an
-        // unauthorized peer on the client side, but it DOES compute the peer's
-        // authorizationError and hand it to the `handshake` callback — so we gate
-        // the connection on it ourselves. #109
-        //
-        // Crucially, once a `handshake` handler is registered, Bun fires `open`
-        // BEFORE the TLS handshake completes (without it, `open` fires only after).
-        // So for EVERY TLS connection we must resolve on `handshake`, not `open` —
-        // otherwise the pool writes its first command onto a socket whose handshake
-        // is still in flight and the bytes are lost. Plaintext has no handshake
-        // event, so it still resolves in `open`.
-        const tlsValue = buildClientTls(target.tls);
-        const isTls = tlsValue !== undefined;
-        const verifyTls = tlsRequiresVerification(target.tls);
-        let opened = false;
-        let handshakeOk = !isTls; // plaintext: nothing to wait for; TLS: wait for handshake
-        const maybeResolveOpen = () => {
-            if (opened && handshakeOk && !connectionResolved) {
-                connectionResolved = true;
-                // Clear the connect timeout only now that we are actually resolving.
-                // For TLS, `open` fires BEFORE `handshake`, so clearing the timeout in
-                // `open` would leave the handshake phase unbounded — a stalled/malicious
-                // peer that completes TCP but never drives the TLS handshake (no error,
-                // no close) would hang this promise forever. Keeping the timeout armed
-                // until resolve preserves connectTimeout as a bound over the handshake.
-                cleanup();
-                resolve({ socket: socketData, cleanup });
-            }
-        };
-        const cleanup = () => {
-            if (timeoutId) {
-                clearTimeout(timeoutId);
-                timeoutId = null;
-            }
-        };
-        const targetDesc = `${target.host}:${target.port}`;
-        // Socket handlers
-        const socketHandlers = {
-            data(_sock, data) {
-                let frames;
-                try {
-                    // `data` (Bun Buffer) is copied into addData's own buffer synchronously
-                    // and never retained, so the `new Uint8Array(data)` wrapper was a
-                    // redundant full copy per read on the client response path.
-                    frames = socketData.frameParser.addData(data);
-                }
-                catch (err) {
-                    if (err instanceof FrameSizeError) {
-                        events.onError(new Error(`Frame too large: ${err.requestedSize} bytes exceeds maximum ${err.maxSize}`));
-                        return;
-                    }
-                    throw err;
-                }
-                for (const frame of frames) {
-                    events.onData(frame);
-                }
-            },
-            open(sock) {
-                // NB: do NOT clear the connect timeout here. For TLS, `open` precedes
-                // `handshake`; the timeout must stay armed until `maybeResolveOpen`
-                // actually resolves (or a stalled handshake could hang forever). #109
-                // Enable TCP keepalive so the OS probes idle connections and surfaces a
-                // dead peer (suspended host, NAT/LB drop) via an error/close event,
-                // instead of a half-open socket lingering until tcp_retries2 (~15 min).
-                // Best-effort: not all platforms honor the delay, and older Bun builds
-                // may lack the method — never let it abort connection setup. See #94.
-                try {
-                    sock.setKeepAlive?.(true, 15000);
-                }
-                catch {
-                    /* keepalive unsupported on this platform/runtime */
-                }
-                socketData.write = (d) => sock.write(d);
-                socketData.end = () => sock.end();
-                opened = true;
-                maybeResolveOpen();
-            },
-            handshake(sock, success, authorizationError) {
-                // Fires only for TLS. When verification is required, a failed handshake
-                // or any authorizationError (wrong/absent CA, self-signed, host
-                // mismatch) must abort — otherwise TLS is encryption-only and an active
-                // MITM can impersonate the broker and harvest the auth token. #109
-                if (verifyTls && (!success || authorizationError)) {
-                    if (!connectionResolved) {
-                        connectionResolved = true;
-                        cleanup();
-                        const why = authorizationError?.message ?? 'handshake failed';
-                        reject(new Error(`TLS verification failed for ${targetDesc}: ${why}`));
-                    }
-                    try {
-                        sock.end();
-                    }
-                    catch {
-                        /* already closing */
-                    }
-                    return;
-                }
-                handshakeOk = true;
-                maybeResolveOpen();
-            },
-            close() {
-                if (!connectionResolved) {
-                    connectionResolved = true;
-                    cleanup();
-                    reject(new Error('Connection closed'));
-                }
-                events.onClose();
-            },
-            error(_sock, error) {
-                if (!connectionResolved) {
-                    connectionResolved = true;
-                    cleanup();
-                    reject(new Error(`Connection error: ${error.message}`));
-                }
-                events.onError(error);
-            },
-            connectError(_sock, error) {
-                if (!connectionResolved) {
-                    connectionResolved = true;
-                    cleanup();
-                    reject(new Error(`Failed to connect to ${targetDesc}: ${error.message}`));
-                }
-            },
-        };
-        // Connect via TCP (optionally wrapped in TLS — protocol is unchanged).
-        // `tlsValue`/`isTls` were computed above to drive handshake-gated resolve.
-        void Bun.connect({
-            hostname: target.host ?? 'localhost',
-            port: target.port ?? 6789,
-            ...(tlsValue !== undefined && { tls: tlsValue }),
-            socket: socketHandlers,
-        }).catch((error) => {
-            // Bun.connect rejects (instead of firing connectError) for some failure
-            // modes, e.g. a TLS handshake refused synchronously. Route it through the
-            // same rejection path so callers never hang until the connect timeout.
-            if (!connectionResolved) {
-                connectionResolved = true;
-                cleanup();
-                const message = error instanceof Error ? error.message : String(error);
-                reject(new Error(`Failed to connect to ${targetDesc}: ${message}`));
-            }
-        });
-        timeoutId = setTimeout(() => {
-            if (!connectionResolved) {
-                connectionResolved = true;
-                reject(new Error(`Connection timeout to ${targetDesc}`));
-            }
-        }, connectTimeout);
-    });
-}
-/**
- * Command queue for managing pending commands
- * Supports both legacy single-command mode and pipelining mode with reqId tracking
- */
-export class CommandQueue {
-    pendingCommands = new Map();
-    pendingQueue = [];
-    currentCommand = null;
-    commandIdCounter = 0;
-    /** In-flight commands tracked by reqId for pipelining */
-    inFlightByReqId = new Map();
-    /** Get current command being processed (legacy mode) */
-    getCurrentCommand() {
-        return this.currentCommand;
-    }
-    /** Set current command (legacy mode) */
-    setCurrentCommand(cmd) {
-        this.currentCommand = cmd;
-    }
-    /** Check if has pending commands in queue */
-    hasPending() {
-        return this.pendingCommands.size > 0;
-    }
-    /** Get number of in-flight commands */
-    getInFlightCount() {
-        return this.inFlightByReqId.size;
-    }
-    /** Check if can send more commands (pipelining backpressure) */
-    canSendMore(maxInFlight) {
-        return this.inFlightByReqId.size < maxInFlight;
-    }
-    /** Add command to in-flight tracking by reqId */
-    addInFlight(command) {
-        this.inFlightByReqId.set(command.reqId, command);
-    }
-    /** Get in-flight command by reqId */
-    getByReqId(reqId) {
-        return this.inFlightByReqId.get(reqId);
-    }
-    /** Remove in-flight command by reqId */
-    removeByReqId(reqId) {
-        const cmd = this.inFlightByReqId.get(reqId);
-        if (cmd) {
-            this.inFlightByReqId.delete(reqId);
-        }
-        return cmd;
-    }
-    /** Add command to queue */
-    enqueue(command) {
-        this.pendingCommands.set(command.id, command);
-        this.pendingQueue.push(command.id);
-    }
-    /** Get next command ID */
-    nextId() {
-        return ++this.commandIdCounter;
-    }
-    /** Dequeue next command */
-    dequeue() {
-        const nextId = this.pendingQueue.shift();
-        if (nextId === undefined)
-            return null;
-        const next = this.pendingCommands.get(nextId);
-        if (!next)
-            return null;
-        this.pendingCommands.delete(nextId);
-        return next;
-    }
-    /** Remove command by ID */
-    remove(id) {
-        if (!this.pendingCommands.has(id))
-            return false;
-        this.pendingCommands.delete(id);
-        const queueIdx = this.pendingQueue.indexOf(id);
-        if (queueIdx !== -1) {
-            this.pendingQueue.splice(queueIdx, 1);
-        }
-        return true;
-    }
-    /** Reject all pending and in-flight commands */
-    rejectAll(error) {
-        // Reject queued commands. Attach a silent .catch BEFORE rejecting so that
-        // callers without a .catch in place (fire-and-forget heartbeats, polling
-        // loops mid-await on intentional close) don't surface as unhandled
-        // rejections and force non-zero process exit.
-        for (const cmd of this.pendingCommands.values()) {
-            clearTimeout(cmd.timeout);
-            cmd.promise?.catch(() => { });
-            cmd.reject(error);
-        }
-        this.pendingCommands.clear();
-        this.pendingQueue = [];
-        // Reject in-flight commands (pipelining)
-        for (const cmd of this.inFlightByReqId.values()) {
-            clearTimeout(cmd.timeout);
-            cmd.promise?.catch(() => { });
-            cmd.reject(error);
-        }
-        this.inFlightByReqId.clear();
-        // Reject current command (legacy)
-        if (this.currentCommand) {
-            clearTimeout(this.currentCommand.timeout);
-            this.currentCommand.reject(error);
-            this.currentCommand = null;
-        }
-    }
-    /** Clear current command with optional rejection (legacy mode) */
-    clearCurrent(error) {
-        if (this.currentCommand) {
-            clearTimeout(this.currentCommand.timeout);
-            if (error) {
-                this.currentCommand.reject(error);
-            }
-            this.currentCommand = null;
-        }
-    }
-}
+/** Stable low-level TCP connection import surface. */
+export { CommandQueue } from './commandQueue';
+export { buildClientTls, createConnection, tlsRequiresVerification, } from './transport';

package/dist/client/tcp/errors.d.ts

@@ -0,0 +1,6 @@
+/** Synthetic rejection issued when a client closes with commands pending. */
+export declare class ClientClosedError extends Error {
+    constructor(message?: string);
+}
+/** Install the one-time process filter for synthetic close rejections. */
+export declare function installClientClosedFilter(): void;

package/dist/client/tcp/errors.js

@@ -0,0 +1,18 @@
+/** Synthetic rejection issued when a client closes with commands pending. */
+export class ClientClosedError extends Error {
+    constructor(message = 'Client closed') {
+        super(message);
+        this.name = 'ClientClosedError';
+    }
+}
+let clientClosedFilterInstalled = false;
+/** Install the one-time process filter for synthetic close rejections. */
+export function installClientClosedFilter() {
+    if (clientClosedFilterInstalled)
+        return;
+    clientClosedFilterInstalled = true;
+    process.on('unhandledRejection', (reason) => {
+        if (reason instanceof ClientClosedError)
+            return;
+    });
+}

package/dist/client/tcp/runtime/commands.d.ts

@@ -0,0 +1,9 @@
+import type { HelloResponse } from '../../../domain/types/response';
+import { TcpClientHealth } from './health';
+/** Command framing, queueing, pipelining, and timeout handling. */
+export declare abstract class TcpClientCommands extends TcpClientHealth {
+    hello(): Promise<HelloResponse>;
+    protected sendDirect(command: Record<string, unknown>): Promise<Record<string, unknown>>;
+    protected processQueue(): void;
+    send(command: Record<string, unknown>): Promise<Record<string, unknown>>;
+}

package/dist/client/tcp/runtime/commands.js

@@ -0,0 +1,124 @@
+import { FrameParser } from '../../../infrastructure/server/protocol';
+import { PROTOCOL_CAPABILITIES, PROTOCOL_VERSION } from '../../../domain/types/protocol';
+import { encodeMessagePack } from '../../../shared/msgpack';
+import { TcpClientHealth } from './health';
+/** Command framing, queueing, pipelining, and timeout handling. */
+export class TcpClientCommands extends TcpClientHealth {
+    async hello() {
+        const response = await this.send({
+            cmd: 'Hello',
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: [...PROTOCOL_CAPABILITIES],
+        });
+        if (response.ok !== true) {
+            const message = typeof response.error === 'string' ? response.error : 'Hello failed';
+            throw new Error(message);
+        }
+        return response;
+    }
+    sendDirect(command) {
+        if (!this.socket)
+            return Promise.reject(new Error('Not connected'));
+        const startTime = Date.now();
+        this.health.recordCommandSent();
+        const reqId = this.generateReqId();
+        const commandWithReqId = { ...command, reqId };
+        let pendingRef;
+        const promise = new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                const removed = this.commands.removeByReqId(reqId);
+                if (removed) {
+                    this.health.recordError();
+                    reject(new Error('Command timeout'));
+                }
+            }, this.options.commandTimeout);
+            pendingRef = {
+                id: 0,
+                reqId,
+                command: commandWithReqId,
+                resolve: (result) => {
+                    this.health.recordSuccess(Date.now() - startTime);
+                    resolve(result);
+                },
+                reject: (error) => {
+                    this.health.recordError();
+                    reject(error);
+                },
+                timeout,
+            };
+        });
+        pendingRef.promise = promise;
+        this.commands.addInFlight(pendingRef);
+        this.socket.write(FrameParser.frame(encodeMessagePack(commandWithReqId)));
+        return promise;
+    }
+    processQueue() {
+        if (!this.connected || !this.socket)
+            return;
+        while (this.commands.hasPending() && this.commands.canSendMore(this.options.maxInFlight)) {
+            const next = this.commands.dequeue();
+            if (!next)
+                break;
+            clearTimeout(next.timeout);
+            const newTimeout = setTimeout(() => {
+                const removed = this.commands.removeByReqId(next.reqId);
+                if (removed) {
+                    this.health.recordError();
+                    next.reject(new Error('Command timeout'));
+                    this.handleCommandTimeout();
+                }
+            }, this.options.commandTimeout);
+            next.timeout = newTimeout;
+            this.commands.addInFlight(next);
+            this.socket.write(FrameParser.frame(encodeMessagePack(next.command)));
+        }
+    }
+    send(command) {
+        const startTime = Date.now();
+        this.health.recordCommandSent();
+        const reqId = this.generateReqId();
+        const commandWithReqId = { ...command, reqId };
+        const id = this.commands.nextId();
+        let pendingRef;
+        const promise = new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                if (this.commands.remove(id)) {
+                    this.health.recordError();
+                    reject(new Error('Command timeout'));
+                    return;
+                }
+                const removed = this.commands.removeByReqId(reqId);
+                if (removed) {
+                    this.health.recordError();
+                    reject(new Error('Command timeout'));
+                    this.handleCommandTimeout();
+                }
+            }, this.options.commandTimeout);
+            pendingRef = {
+                id,
+                reqId,
+                command: commandWithReqId,
+                resolve: (result) => {
+                    this.health.recordSuccess(Date.now() - startTime);
+                    resolve(result);
+                },
+                reject: (error) => {
+                    this.health.recordError();
+                    reject(error);
+                },
+                timeout,
+            };
+        });
+        pendingRef.promise = promise;
+        this.commands.enqueue(pendingRef);
+        if (!this.connected && !this.connecting) {
+            this.connect().catch(() => {
+                // The queued command owns timeout and rejection reporting.
+            });
+        }
+        else if (this.connected) {
+            this.processQueue();
+        }
+        return promise;
+    }
+}

package/dist/client/tcp/runtime/connectivity.d.ts

@@ -0,0 +1,13 @@
+import { TcpClientState } from './state';
+/** Connection establishment and authentication lifecycle. */
+export declare abstract class TcpClientConnectivity extends TcpClientState {
+    protected abstract handleData(frame: Uint8Array): void;
+    protected abstract handleClose(): void;
+    protected abstract processQueue(): void;
+    protected abstract sendDirect(command: Record<string, unknown>): Promise<Record<string, unknown>>;
+    connect(): Promise<void>;
+    protected abstract ping(): Promise<boolean>;
+    private waitForConnection;
+    private doConnect;
+    private authenticate;
+}

package/dist/client/tcp/runtime/connectivity.js

@@ -0,0 +1,77 @@
+import { createConnection } from '../connection';
+import { TcpClientState } from './state';
+/** Connection establishment and authentication lifecycle. */
+export class TcpClientConnectivity extends TcpClientState {
+    async connect() {
+        if (this.connected)
+            return;
+        if (this.connecting)
+            return this.waitForConnection();
+        this.connecting = true;
+        this.reconnect.setClosed(false);
+        try {
+            await this.doConnect();
+            this.reconnect.reset();
+            this.emit('connected');
+            this.health.startPing(async () => {
+                await this.ping();
+            });
+            this.processQueue();
+        }
+        catch (error) {
+            this.connecting = false;
+            if (this.reconnect.canReconnect()) {
+                this.reconnect.scheduleReconnect(() => this.connect());
+            }
+            throw error;
+        }
+    }
+    waitForConnection() {
+        return new Promise((resolve, reject) => {
+            const onConnect = () => {
+                this.off('error', onError);
+                resolve();
+            };
+            const onError = (error) => {
+                this.off('connected', onConnect);
+                reject(error);
+            };
+            this.once('connected', onConnect);
+            this.once('error', onError);
+        });
+    }
+    async doConnect() {
+        const { socket } = await createConnection({
+            host: this.options.host,
+            port: this.options.port,
+            tls: this.options.tls,
+        }, this.options.connectTimeout, {
+            onData: (frame) => {
+                this.handleData(frame);
+            },
+            onClose: () => {
+                this.handleClose();
+            },
+            onError: (error) => this.emit('error', error),
+        });
+        this.socket = socket;
+        if (this.options.token) {
+            try {
+                await this.authenticate();
+            }
+            catch (error) {
+                this.socket.end();
+                this.socket = null;
+                throw error;
+            }
+        }
+        this.connected = true;
+        this.connecting = false;
+        this.health.recordConnected();
+    }
+    async authenticate() {
+        const response = await this.sendDirect({ cmd: 'Auth', token: this.options.token });
+        if (!response.ok)
+            throw new Error('Authentication failed');
+    }
+}

package/dist/client/tcp/runtime/health.d.ts

@@ -0,0 +1,14 @@
+import { TcpClientConnectivity } from './connectivity';
+/** Response dispatch, health tracking, and reconnect decisions. */
+export declare abstract class TcpClientHealth extends TcpClientConnectivity {
+    protected handleData(frame: Uint8Array): void;
+    protected handleClose(): void;
+    ping(): Promise<boolean>;
+    protected abstract send(command: Record<string, unknown>): Promise<Record<string, unknown>>;
+    private handlePingFailure;
+    protected handleCommandTimeout(): void;
+    private forceReconnect;
+    getHealth(): import("..").ConnectionHealth;
+    protected abstract getState(): 'connected' | 'connecting' | 'disconnected' | 'closed';
+    protected generateReqId(): string;
+}