bunqueue 2.8.53 → 2.8.56

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

@@ -0,0 +1,127 @@
+import { decodeMessagePack } from '../../../shared/msgpack';
+import { TcpClientConnectivity } from './connectivity';
+function isJobEvent(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const event = value;
+    return (typeof event.eventType === 'string' &&
+        typeof event.queue === 'string' &&
+        typeof event.jobId === 'string' &&
+        typeof event.timestamp === 'number' &&
+        Number.isFinite(event.timestamp));
+}
+/** Response dispatch, health tracking, and reconnect decisions. */
+export class TcpClientHealth extends TcpClientConnectivity {
+    handleData(frame) {
+        try {
+            const response = decodeMessagePack(frame);
+            if (response.type === 'event') {
+                if (!isJobEvent(response.event))
+                    throw new Error('Invalid queue event frame');
+                this.emit('queueEvent', response.event);
+                return;
+            }
+            const reqId = response.reqId;
+            if (reqId) {
+                const pending = this.commands.removeByReqId(reqId);
+                if (pending) {
+                    clearTimeout(pending.timeout);
+                    pending.resolve(response);
+                    this.processQueue();
+                    return;
+                }
+            }
+            const current = this.commands.getCurrentCommand();
+            if (current) {
+                clearTimeout(current.timeout);
+                current.resolve(response);
+                this.commands.setCurrentCommand(null);
+                this.processQueue();
+                return;
+            }
+            this.emit('warning', { type: 'unknown_response', reqId });
+        }
+        catch {
+            const error = new Error('Invalid response from server');
+            this.emit('warning', { type: 'malformed_frame' });
+            this.commands.rejectAll(error);
+            this.forceReconnect();
+        }
+    }
+    handleClose() {
+        const wasConnected = this.connected;
+        this.connected = false;
+        this.connecting = false;
+        this.socket = null;
+        this.health.stopPing();
+        this.commands.rejectAll(new Error('Connection lost'));
+        if (wasConnected) {
+            this.emit('disconnected');
+            if (this.reconnect.canReconnect()) {
+                this.reconnect.scheduleReconnect(() => this.connect());
+            }
+        }
+    }
+    async ping() {
+        if (!this.connected)
+            return false;
+        try {
+            const start = Date.now();
+            const response = await this.send({ cmd: 'Ping' });
+            const data = response.data;
+            const success = data?.pong === true;
+            if (success) {
+                this.health.recordPingSuccess(Date.now() - start);
+                this.emit('health', { type: 'ping_success', latency: Date.now() - start });
+            }
+            else {
+                this.handlePingFailure();
+            }
+            return success;
+        }
+        catch {
+            this.handlePingFailure();
+            return false;
+        }
+    }
+    handlePingFailure() {
+        if (this.health.recordPingFailure()) {
+            this.emit('health', { type: 'unhealthy', reason: 'max_ping_failures' });
+            this.forceReconnect();
+        }
+        else {
+            this.emit('health', { type: 'ping_failed' });
+        }
+    }
+    handleCommandTimeout() {
+        if (this.health.recordCommandTimeout()) {
+            this.emit('health', { type: 'unhealthy', reason: 'max_command_timeouts' });
+            this.forceReconnect();
+        }
+    }
+    forceReconnect() {
+        if (this.reconnect.isClosed())
+            return;
+        if (this.socket) {
+            try {
+                this.socket.end();
+            }
+            catch {
+                // Socket already torn down.
+            }
+            this.socket = null;
+        }
+        this.connected = false;
+        this.health.stopPing();
+        this.commands.rejectAll(new Error('Connection lost'));
+        if (this.reconnect.canReconnect())
+            this.reconnect.scheduleReconnect(() => this.connect());
+    }
+    getHealth() {
+        return this.health.getHealth(this.getState());
+    }
+    generateReqId() {
+        this.reqIdCounter = (this.reqIdCounter + 1) & 0x7fffffff;
+        return String(this.reqIdCounter);
+    }
+}

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

@@ -0,0 +1,8 @@
+import { TcpClientCommands } from './commands';
+/** Public shutdown and connection-state inspection. */
+export declare class TcpClientLifecycle extends TcpClientCommands {
+    close(): void;
+    isConnected(): boolean;
+    getState(): 'connected' | 'connecting' | 'disconnected' | 'closed';
+    getInFlightCount(): number;
+}

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

@@ -0,0 +1,32 @@
+import { ClientClosedError, installClientClosedFilter } from '../errors';
+import { TcpClientCommands } from './commands';
+/** Public shutdown and connection-state inspection. */
+export class TcpClientLifecycle extends TcpClientCommands {
+    close() {
+        this.reconnect.setClosed(true);
+        this.health.stopPing();
+        this.reconnect.cancelReconnect();
+        installClientClosedFilter();
+        this.commands.rejectAll(new ClientClosedError());
+        if (this.socket) {
+            this.socket.end();
+            this.socket = null;
+            this.connected = false;
+        }
+    }
+    isConnected() {
+        return this.connected;
+    }
+    getState() {
+        if (this.reconnect.isClosed())
+            return 'closed';
+        if (this.connected)
+            return 'connected';
+        if (this.connecting)
+            return 'connecting';
+        return 'disconnected';
+    }
+    getInFlightCount() {
+        return this.commands.getInFlightCount();
+    }
+}

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

@@ -0,0 +1,50 @@
+import { EventEmitter } from 'events';
+import { CommandQueue } from '../connection';
+import { HealthTracker } from '../health';
+import { ReconnectManager } from '../reconnect';
+import type { ConnectionOptions, SocketWrapper } from '../types';
+import type { JobEvent } from '../../../domain/types/queue';
+/** Shared TCP client state and event contract. */
+export declare class TcpClientState extends EventEmitter {
+    on(event: 'connected' | 'disconnected' | 'maxReconnectAttemptsReached', listener: () => void): this;
+    on(event: 'reconnecting', listener: (data: {
+        attempt: number;
+        delay: number;
+    }) => void): this;
+    on(event: 'error', listener: (error: Error) => void): this;
+    on(event: 'warning', listener: (data: {
+        type: string;
+        reqId?: string;
+    }) => void): this;
+    on(event: 'queueEvent', listener: (event: JobEvent) => void): this;
+    on(event: 'health', listener: (data: {
+        type: string;
+        latency?: number;
+        reason?: string;
+    }) => void): this;
+    once(event: 'connected' | 'disconnected' | 'maxReconnectAttemptsReached', listener: () => void): this;
+    once(event: 'reconnecting', listener: (data: {
+        attempt: number;
+        delay: number;
+    }) => void): this;
+    once(event: 'error', listener: (error: Error) => void): this;
+    once(event: 'warning', listener: (data: {
+        type: string;
+        reqId?: string;
+    }) => void): this;
+    once(event: 'queueEvent', listener: (event: JobEvent) => void): this;
+    once(event: 'health', listener: (data: {
+        type: string;
+        latency?: number;
+        reason?: string;
+    }) => void): this;
+    protected socket: SocketWrapper | null;
+    protected connected: boolean;
+    protected connecting: boolean;
+    protected readonly options: Required<ConnectionOptions>;
+    protected readonly health: HealthTracker;
+    protected readonly reconnect: ReconnectManager;
+    protected readonly commands: CommandQueue;
+    protected reqIdCounter: number;
+    constructor(options?: Partial<ConnectionOptions>);
+}

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

@@ -0,0 +1,45 @@
+import { EventEmitter } from 'events';
+import { CommandQueue } from '../connection';
+import { HealthTracker } from '../health';
+import { ReconnectManager } from '../reconnect';
+import { DEFAULT_CONNECTION } from '../types';
+/** Shared TCP client state and event contract. */
+export class TcpClientState extends EventEmitter {
+    // biome-ignore lint/suspicious/noExplicitAny: EventEmitter's fallback overload requires any[]
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: EventEmitter's fallback overload requires any[]
+    once(event, listener) {
+        return super.once(event, listener);
+    }
+    socket = null;
+    connected = false;
+    connecting = false;
+    options;
+    health;
+    reconnect;
+    commands;
+    reqIdCounter = 0;
+    constructor(options = {}) {
+        super();
+        this.options = { ...DEFAULT_CONNECTION, ...options };
+        this.commands = new CommandQueue();
+        this.health = new HealthTracker({
+            pingInterval: this.options.pingInterval,
+            maxPingFailures: this.options.maxPingFailures,
+            maxCommandTimeouts: this.options.maxCommandTimeouts,
+        });
+        this.reconnect = new ReconnectManager({
+            maxReconnectAttempts: this.options.maxReconnectAttempts,
+            reconnectDelay: this.options.reconnectDelay,
+            maxReconnectDelay: this.options.maxReconnectDelay,
+            autoReconnect: this.options.autoReconnect,
+        });
+        this.reconnect.on('reconnecting', (data) => this.emit('reconnecting', data));
+        this.reconnect.on('maxReconnectAttemptsReached', () => {
+            this.emit('maxReconnectAttemptsReached');
+            this.commands.rejectAll(new Error('Max reconnection attempts reached'));
+        });
+    }
+}

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

@@ -0,0 +1,18 @@
+import type { ClientTlsOptions, SocketWrapper } from './types';
+export interface ConnectionEvents {
+    onData: (frame: Uint8Array) => void;
+    onClose: () => void;
+    onError: (error: Error) => void;
+}
+export interface ConnectionResult {
+    socket: SocketWrapper;
+    cleanup: () => void;
+}
+export interface ConnectionTarget {
+    host?: string;
+    port?: number;
+    tls?: boolean | ClientTlsOptions;
+}
+export declare function buildClientTls(tls: boolean | ClientTlsOptions | undefined): true | Record<string, unknown> | undefined;
+export declare function tlsRequiresVerification(tls: boolean | ClientTlsOptions | undefined): boolean;
+export declare function createConnection(target: ConnectionTarget, connectTimeout: number, events: ConnectionEvents): Promise<ConnectionResult>;

package/dist/client/tcp/transport.js

@@ -0,0 +1,158 @@
+import { readFileSync } from 'node:fs';
+import { FrameParser, FrameSizeError } from '../../infrastructure/server/protocol';
+import { SocketWriteQueue } from '../../infrastructure/server/socketWriteQueue';
+const CLIENT_MAX_WRITE_QUEUE_BYTES = 64 * 1024 * 1024;
+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) }),
+    };
+}
+export function tlsRequiresVerification(tls) {
+    if (!tls)
+        return false;
+    if (tls === true)
+        return true;
+    return tls.rejectUnauthorized !== false;
+}
+export function createConnection(target, connectTimeout, events) {
+    return new Promise((resolve, reject) => {
+        const writeQueue = new SocketWriteQueue(CLIENT_MAX_WRITE_QUEUE_BYTES);
+        const socketData = {
+            write: () => undefined,
+            end: () => undefined,
+            frameParser: new FrameParser(),
+        };
+        let connectionResolved = false;
+        let timeoutId = null;
+        const tlsValue = buildClientTls(target.tls);
+        const isTls = tlsValue !== undefined;
+        const verifyTls = tlsRequiresVerification(target.tls);
+        let opened = false;
+        let handshakeOk = !isTls;
+        const maybeResolveOpen = () => {
+            if (opened && handshakeOk && !connectionResolved) {
+                connectionResolved = true;
+                cleanup();
+                resolve({ socket: socketData, cleanup });
+            }
+        };
+        const cleanup = () => {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+                timeoutId = null;
+            }
+        };
+        const targetDescription = `${target.host}:${target.port}`;
+        const socketHandlers = {
+            data(_socket, data) {
+                let frames;
+                try {
+                    frames = socketData.frameParser.addData(data);
+                }
+                catch (error) {
+                    if (error instanceof FrameSizeError) {
+                        events.onError(new Error(`Frame too large: ${error.requestedSize} bytes exceeds maximum ${error.maxSize}`));
+                        return;
+                    }
+                    throw error;
+                }
+                for (const frame of frames)
+                    events.onData(frame);
+            },
+            open(socket) {
+                try {
+                    socket.setKeepAlive?.(true, 15000);
+                }
+                catch {
+                    // Keepalive is best-effort.
+                }
+                socketData.write = (data) => {
+                    const bytes = typeof data === 'string' ? Buffer.from(data) : data;
+                    if (!writeQueue.write(socket, bytes) || writeQueue.isOverBudget) {
+                        writeQueue.clear();
+                        socket.terminate();
+                    }
+                };
+                socketData.end = () => {
+                    writeQueue.clear();
+                    socket.end();
+                };
+                opened = true;
+                maybeResolveOpen();
+            },
+            handshake(socket, success, authorizationError) {
+                if (verifyTls && (!success || authorizationError)) {
+                    if (!connectionResolved) {
+                        connectionResolved = true;
+                        cleanup();
+                        const reason = authorizationError?.message ?? 'handshake failed';
+                        reject(new Error(`TLS verification failed for ${targetDescription}: ${reason}`));
+                    }
+                    try {
+                        socket.end();
+                    }
+                    catch {
+                        // Socket is already closing.
+                    }
+                    return;
+                }
+                handshakeOk = true;
+                maybeResolveOpen();
+            },
+            close() {
+                writeQueue.clear();
+                if (!connectionResolved) {
+                    connectionResolved = true;
+                    cleanup();
+                    reject(new Error('Connection closed'));
+                }
+                events.onClose();
+            },
+            drain(socket) {
+                if (!writeQueue.flush(socket)) {
+                    writeQueue.clear();
+                    socket.terminate();
+                }
+            },
+            error(_socket, error) {
+                if (!connectionResolved) {
+                    connectionResolved = true;
+                    cleanup();
+                    reject(new Error(`Connection error: ${error.message}`));
+                }
+                events.onError(error);
+            },
+            connectError(_socket, error) {
+                if (!connectionResolved) {
+                    connectionResolved = true;
+                    cleanup();
+                    reject(new Error(`Failed to connect to ${targetDescription}: ${error.message}`));
+                }
+            },
+        };
+        void Bun.connect({
+            hostname: target.host ?? 'localhost',
+            port: target.port ?? 6789,
+            ...(tlsValue !== undefined && { tls: tlsValue }),
+            socket: socketHandlers,
+        }).catch((error) => {
+            if (!connectionResolved) {
+                connectionResolved = true;
+                cleanup();
+                const message = error instanceof Error ? error.message : String(error);
+                reject(new Error(`Failed to connect to ${targetDescription}: ${message}`));
+            }
+        });
+        timeoutId = setTimeout(() => {
+            if (!connectionResolved) {
+                connectionResolved = true;
+                reject(new Error(`Connection timeout to ${targetDescription}`));
+            }
+        }, connectTimeout);
+    });
+}

package/dist/client/tcp/types/command.d.ts

@@ -0,0 +1,9 @@
+export interface PendingCommand {
+    id: number;
+    reqId: string;
+    command: Record<string, unknown>;
+    resolve: (value: Record<string, unknown>) => void;
+    reject: (error: Error) => void;
+    timeout: ReturnType<typeof setTimeout>;
+    promise?: Promise<Record<string, unknown>>;
+}

package/dist/client/tcp/types/command.js

@@ -0,0 +1 @@
+export {};

package/dist/client/tcp/types/connection.d.ts

@@ -0,0 +1,31 @@
+import type { ClientTlsOptions } from './tls';
+export interface ConnectionOptions {
+    host: string;
+    port: number;
+    token?: string;
+    tls?: boolean | ClientTlsOptions;
+    maxReconnectAttempts?: number;
+    reconnectDelay?: number;
+    maxReconnectDelay?: number;
+    connectTimeout?: number;
+    commandTimeout?: number;
+    autoReconnect?: boolean;
+    pingInterval?: number;
+    maxPingFailures?: number;
+    maxCommandTimeouts?: number;
+    pipelining?: boolean;
+    maxInFlight?: number;
+}
+export interface ConnectionHealth {
+    healthy: boolean;
+    state: 'connected' | 'connecting' | 'disconnected' | 'closed';
+    lastSuccessAt: number | null;
+    lastErrorAt: number | null;
+    avgLatencyMs: number;
+    consecutivePingFailures: number;
+    consecutiveCommandTimeouts: number;
+    totalCommands: number;
+    totalErrors: number;
+    uptimeMs: number;
+}
+export declare const DEFAULT_CONNECTION: Required<ConnectionOptions>;

package/dist/client/tcp/types/connection.js

@@ -0,0 +1,17 @@
+export const DEFAULT_CONNECTION = {
+    host: 'localhost',
+    port: 6789,
+    token: '',
+    tls: false,
+    maxReconnectAttempts: Infinity,
+    reconnectDelay: 100,
+    maxReconnectDelay: 30000,
+    connectTimeout: 5000,
+    commandTimeout: 30000,
+    autoReconnect: true,
+    pingInterval: 30000,
+    maxPingFailures: 3,
+    maxCommandTimeouts: 3,
+    pipelining: true,
+    maxInFlight: 100,
+};

package/dist/client/tcp/types/index.d.ts

@@ -0,0 +1,5 @@
+export type { PendingCommand } from './command';
+export { DEFAULT_CONNECTION } from './connection';
+export type { ConnectionHealth, ConnectionOptions } from './connection';
+export type { FrameParser, SocketWrapper } from './socket';
+export type { ClientTlsOptions } from './tls';

package/dist/client/tcp/types/index.js

@@ -0,0 +1 @@
+export { DEFAULT_CONNECTION } from './connection';

package/dist/client/tcp/types/socket.d.ts

@@ -0,0 +1,8 @@
+export interface SocketWrapper {
+    write: (data: Uint8Array | string) => void;
+    end: () => void;
+    frameParser: FrameParser;
+}
+export interface FrameParser {
+    addData(data: Uint8Array): Uint8Array[];
+}

package/dist/client/tcp/types/socket.js

@@ -0,0 +1 @@
+export {};

package/dist/client/tcp/types/tls.d.ts

@@ -0,0 +1,4 @@
+export interface ClientTlsOptions {
+    rejectUnauthorized?: boolean;
+    caFile?: string;
+}

package/dist/client/tcp/types/tls.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,106 +1,2 @@
-/**
- * TCP Client Types
- * Type definitions for TCP connection management
- */
-/**
- * TLS options for client connections.
- * `true` enables TLS with system CA verification; the object form allows
- * trusting a custom CA (self-signed server cert) or disabling verification.
- */
-export interface ClientTlsOptions {
-    /** Verify the server certificate (default: true). Set false for self-signed in dev. */
-    rejectUnauthorized?: boolean;
-    /** Path to a PEM CA certificate to trust (e.g. the self-signed server cert) */
-    caFile?: string;
-}
-/** Connection options */
-export interface ConnectionOptions {
-    /** Server host */
-    host: string;
-    /** Server port */
-    port: number;
-    /** Auth token */
-    token?: string;
-    /** Enable TLS: true (system CAs) or per-connection TLS options (default: false) */
-    tls?: boolean | ClientTlsOptions;
-    /** Max reconnection attempts (default: Infinity) */
-    maxReconnectAttempts?: number;
-    /** Initial reconnect delay in ms (default: 100) */
-    reconnectDelay?: number;
-    /** Max reconnect delay in ms (default: 30000) */
-    maxReconnectDelay?: number;
-    /** Connection timeout in ms (default: 5000) */
-    connectTimeout?: number;
-    /** Command timeout in ms (default: 30000) */
-    commandTimeout?: number;
-    /** Enable auto-reconnect (default: true) */
-    autoReconnect?: boolean;
-    /** Health check ping interval in ms (default: 30000, 0 to disable) */
-    pingInterval?: number;
-    /** Max consecutive ping failures before forcing reconnect (default: 3) */
-    maxPingFailures?: number;
-    /**
-     * Max consecutive command timeouts (with no intervening success) before the
-     * connection is concluded dead and reconnect is forced (default: 3, 0 to
-     * disable). This is the recovery path for a half-open socket when the
-     * health-check ping is disabled or slower than real traffic — a worker whose
-     * PULLs keep timing out no longer stalls forever waiting on the ping. See #94.
-     */
-    maxCommandTimeouts?: number;
-    /** Enable pipelining - multiple commands in flight (default: true) */
-    pipelining?: boolean;
-    /** Max commands in flight when pipelining (default: 100) */
-    maxInFlight?: number;
-}
-/** Connection health metrics */
-export interface ConnectionHealth {
-    /** Whether connection is currently healthy */
-    healthy: boolean;
-    /** Current connection state */
-    state: 'connected' | 'connecting' | 'disconnected' | 'closed';
-    /** Timestamp of last successful command */
-    lastSuccessAt: number | null;
-    /** Timestamp of last error */
-    lastErrorAt: number | null;
-    /** Average latency of last 10 commands in ms */
-    avgLatencyMs: number;
-    /** Consecutive ping failures */
-    consecutivePingFailures: number;
-    /** Consecutive command timeouts with no intervening success */
-    consecutiveCommandTimeouts: number;
-    /** Total commands sent */
-    totalCommands: number;
-    /** Total errors */
-    totalErrors: number;
-    /** Uptime since last connect in ms */
-    uptimeMs: number;
-}
-/** Default connection options */
-export declare const DEFAULT_CONNECTION: Required<ConnectionOptions>;
-/** Pending command awaiting response */
-export interface PendingCommand {
-    id: number;
-    /** Request ID for response matching (pipelining support) */
-    reqId: string;
-    command: Record<string, unknown>;
-    resolve: (value: Record<string, unknown>) => void;
-    reject: (error: Error) => void;
-    timeout: ReturnType<typeof setTimeout>;
-    /**
-     * Reference to the Promise returned to the caller. Used by rejectAll() on
-     * intentional shutdown to attach a silent .catch — prevents unhandled
-     * rejections from leaking when callers (fire-and-forget heartbeats, polling
-     * loops mid-await) don't have a .catch in place at the moment we reject.
-     */
-    promise?: Promise<Record<string, unknown>>;
-}
-/** Socket wrapper interface */
-export interface SocketWrapper {
-    write: (data: Uint8Array | string) => void;
-    end: () => void;
-    frameParser: FrameParser;
-}
-/** Frame parser interface for binary protocol parsing */
-export interface FrameParser {
-    addData(data: Uint8Array): Uint8Array[];
-}
+/** Backwards-compatible barrel for TCP client types. */
+export * from './types/index';

package/dist/client/tcp/types.js

@@ -1,22 +1,2 @@
-/**
- * TCP Client Types
- * Type definitions for TCP connection management
- */
-/** Default connection options */
-export const DEFAULT_CONNECTION = {
-    host: 'localhost',
-    port: 6789,
-    token: '',
-    tls: false,
-    maxReconnectAttempts: Infinity,
-    reconnectDelay: 100,
-    maxReconnectDelay: 30000,
-    connectTimeout: 5000,
-    commandTimeout: 30000,
-    autoReconnect: true,
-    pingInterval: 30000,
-    maxPingFailures: 3,
-    maxCommandTimeouts: 3,
-    pipelining: true,
-    maxInFlight: 100,
-};
+/** Backwards-compatible barrel for TCP client types. */
+export * from './types/index';