bunqueue 2.8.0 → 2.8.2

package/dist/infrastructure/server/socketWriteQueue.js

@@ -0,0 +1,126 @@
+/**
+ * Per-socket write queue
+ * =================================================================
+ * Bun's `socket.write()` may write FEWER bytes than provided when the kernel
+ * send buffer is full (backpressure). The unwritten tail is NOT retained by
+ * Bun — the caller is responsible for buffering it and resending once the
+ * socket fires `drain`. Ignoring the short count silently drops response
+ * bytes, corrupting the length-prefixed frame protocol.
+ *
+ * This helper buffers any unwritten tail per-socket and preserves ordering:
+ * while a pending tail exists, all subsequent writes are appended to the queue
+ * (never written ahead of older bytes), and the queue is flushed in order from
+ * the `drain` handler.
+ */
+/** Per-socket pending write state. Stored on `socket.data`. */
+export class SocketWriteQueue {
+    /** Buffered chunks waiting to be (re)written, in order. */
+    pending = [];
+    /** Byte offset into pending[0] already written by a short write. */
+    offset = 0;
+    /** Total queued bytes (for bounds / observability). */
+    queuedBytes = 0;
+    /** Max queued bytes before the queue reports over-budget (0 = unbounded). */
+    maxBytes;
+    /**
+     * @param maxBytes Soft cap on buffered bytes. When `bytesQueued` exceeds this,
+     *   `isOverBudget` becomes true and the owner should drop the connection
+     *   (bounds write-side memory for a client that stopped reading). 0 disables.
+     */
+    constructor(maxBytes = 0) {
+        this.maxBytes = maxBytes > 0 ? maxBytes : 0;
+    }
+    /**
+     * True once the buffered byte count exceeds the configured cap. The owner is
+     * expected to terminate the connection and `clear()` the queue.
+     */
+    get isOverBudget() {
+        return this.maxBytes > 0 && this.queuedBytes > this.maxBytes;
+    }
+    /**
+     * Enqueue `data` for delivery on `socket`, preserving order.
+     * Returns false if the socket appears closed (write threw / returned < 0).
+     */
+    write(socket, data) {
+        if (data.length === 0)
+            return true;
+        // If a tail is already pending, do NOT write ahead of it — append and wait
+        // for drain to flush in order.
+        if (this.pending.length > 0) {
+            this.pending.push(data);
+            this.queuedBytes += data.length;
+            return true;
+        }
+        let written;
+        try {
+            written = socket.write(data);
+        }
+        catch {
+            return false;
+        }
+        if (written < 0) {
+            // Socket closed.
+            return false;
+        }
+        if (written < data.length) {
+            // Short write: buffer the unwritten tail; flush on drain.
+            const tail = data.subarray(written);
+            this.pending.push(tail);
+            this.queuedBytes += tail.length;
+        }
+        return true;
+    }
+    /**
+     * Flush as much of the pending queue as the socket accepts.
+     * Call from the socket's `drain` handler. Stops at the first short write,
+     * leaving the remainder queued for the next drain.
+     */
+    flush(socket) {
+        while (this.pending.length > 0) {
+            const chunk = this.pending[0];
+            const view = this.offset > 0 ? chunk.subarray(this.offset) : chunk;
+            let written;
+            try {
+                written = socket.write(view);
+            }
+            catch {
+                return;
+            }
+            if (written <= 0) {
+                // Socket not ready / closed; wait for the next drain.
+                return;
+            }
+            if (written < view.length) {
+                // Still backpressured: advance offset within the current chunk.
+                this.offset += written;
+                this.queuedBytes -= written;
+                return;
+            }
+            // Whole chunk flushed.
+            this.queuedBytes -= view.length;
+            this.pending.shift();
+            this.offset = 0;
+        }
+    }
+    /** Number of bytes still buffered awaiting drain. */
+    get bytesQueued() {
+        return this.queuedBytes;
+    }
+    /** Whether there is unwritten data awaiting drain. */
+    get hasPending() {
+        return this.pending.length > 0;
+    }
+    /** Drop all buffered data (e.g. on close). */
+    clear() {
+        this.pending = [];
+        this.offset = 0;
+        this.queuedBytes = 0;
+    }
+}
+/**
+ * Convenience: write through a socket whose `data` carries a `writeQueue`.
+ * Keeps call sites in tcp.ts terse and consistent.
+ */
+export function queuedWrite(socket, data) {
+    socket.data.writeQueue.write(socket, data);
+}

package/dist/infrastructure/server/sseHandler.d.ts

@@ -60,4 +60,3 @@ export declare class SseHandler {
     /** Get clients map (for backward compatibility) */
     getClients(): Map<string, SseClient>;
 }
-//# sourceMappingURL=sseHandler.d.ts.map

package/dist/infrastructure/server/sseHandler.js

@@ -315,4 +315,3 @@ export class SseHandler {
         return this.clients;
     }
 }
-//# sourceMappingURL=sseHandler.js.map

package/dist/infrastructure/server/tcp.d.ts

@@ -8,6 +8,7 @@ import type { QueueManager } from '../../application/queueManager';
 import { type HandlerContext } from './handler';
 import { FrameParser, type ConnectionState } from './protocol';
 import { Semaphore } from '../../shared/semaphore';
+import { SocketWriteQueue } from './socketWriteQueue';
 /** TCP Server configuration */
 export interface TcpServerConfig {
     /** TCP port */
@@ -16,6 +17,18 @@ export interface TcpServerConfig {
     hostname?: string;
     /** Auth tokens for authentication */
     authTokens?: string[];
+    /**
+     * Slowloris stall timeout (ms): close a connection that started a frame but
+     * made no progress completing it within this window. 0 disables. Defaults to
+     * TCP_IDLE_TIMEOUT_MS env (60s). Mainly for tests.
+     */
+    idleTimeoutMs?: number;
+    /**
+     * Max outbound write-queue bytes before dropping a connection (write-side
+     * memory bound). 0 disables. Defaults to TCP_MAX_WRITE_QUEUE_BYTES env (64MB).
+     * Mainly for tests.
+     */
+    maxWriteQueueBytes?: number;
 }
 /** Per-connection data */
 interface ConnectionData {
@@ -24,6 +37,10 @@ interface ConnectionData {
     ctx: HandlerContext;
     /** Semaphore for limiting concurrent command processing (pipelining) */
     semaphore: Semaphore;
+    /** Backpressure-aware write queue: buffers unwritten tails, flushes on drain */
+    writeQueue: SocketWriteQueue;
+    /** Active partial-frame stall timer (slowloris mitigation); null when idle. */
+    stallTimer: ReturnType<typeof setTimeout> | null;
 }
 /**
  * Create and start TCP server
@@ -40,4 +57,3 @@ export declare function createTcpServer(queueManager: QueueManager, config: TcpS
 };
 export type TcpServer = ReturnType<typeof createTcpServer>;
 export {};
-//# sourceMappingURL=tcp.d.ts.map

package/dist/infrastructure/server/tcp.js

@@ -10,8 +10,29 @@ import { tcpLog } from '../../shared/logger';
 import { getRateLimiter } from './rateLimiter';
 import { pack, unpack } from 'msgpackr';
 import { Semaphore, withSemaphore } from '../../shared/semaphore';
+import { SocketWriteQueue } from './socketWriteQueue';
 /** Max concurrent commands per connection for pipelining */
 const MAX_CONCURRENT_PER_CONNECTION = 50;
+/**
+ * Idle/read stall timeout (ms) for the slowloris mitigation. A connection that
+ * has STARTED a frame (partial bytes buffered) but makes no further progress
+ * toward completing it within this window is closed. Healthy connections that
+ * are simply idle (no partial frame buffered) are never affected, so long-lived
+ * idle-but-healthy clients are not disturbed. 0 disables the timeout.
+ *
+ * Implemented with a manual per-connection timer (Bun.listen has no
+ * `idleTimeout` socket option as of Bun 1.3.x, and `socket.timeout()` resets on
+ * every byte — so a slowloris that trickles one byte per window would defeat
+ * it). The manual timer is armed only while a partial frame is in progress.
+ */
+const TCP_IDLE_TIMEOUT_MS = Math.max(0, parseInt(Bun.env.TCP_IDLE_TIMEOUT_MS ?? '60000', 10) || 0);
+/**
+ * Maximum bytes that may be buffered in a connection's outbound write queue
+ * before the connection is dropped. A client that stops reading while the
+ * server keeps producing responses would otherwise grow the pending queue
+ * without bound (write-side memory DoS). Generous default (64MB). 0 disables.
+ */
+const MAX_WRITE_QUEUE_BYTES = Math.max(0, parseInt(Bun.env.TCP_MAX_WRITE_QUEUE_BYTES ?? String(64 * 1024 * 1024), 10) || 0);
 /**
  * Release client jobs with retry logic and exponential backoff.
  * Ensures jobs are not left in an inconsistent state if release fails.
@@ -48,6 +69,39 @@ function errorResponse(message, reqId) {
 export function createTcpServer(queueManager, config) {
     const authTokens = new Set(config.authTokens ?? []);
     const connections = new Map();
+    const idleTimeoutMs = config.idleTimeoutMs ?? TCP_IDLE_TIMEOUT_MS;
+    const maxWriteQueueBytes = config.maxWriteQueueBytes ?? MAX_WRITE_QUEUE_BYTES;
+    /** Cancel any pending stall timer for a connection. */
+    function clearStallTimer(socket) {
+        if (socket.data.stallTimer !== null) {
+            clearTimeout(socket.data.stallTimer);
+            socket.data.stallTimer = null;
+        }
+    }
+    /**
+     * (Re)arm the slowloris stall timer based on parser state. The timer runs
+     * ONLY while a partial frame is buffered (a frame was started but not yet
+     * completed). It is reset on every data event that still leaves a partial
+     * frame, and cleared once the buffer drains to empty (frame completed). If it
+     * fires, the peer started a frame and then stalled -> terminate.
+     */
+    function updateStallTimer(socket) {
+        if (idleTimeoutMs <= 0)
+            return;
+        clearStallTimer(socket);
+        if (!socket.data.frameParser.hasPartialFrame)
+            return;
+        socket.data.stallTimer = setTimeout(() => {
+            socket.data.stallTimer = null;
+            tcpLog.warn('Closing stalled connection (incomplete frame)', {
+                clientId: socket.data.state.clientId,
+                bufferedBytes: socket.data.frameParser.bufferedBytes,
+                idleTimeoutMs,
+            });
+            socket.data.writeQueue.clear();
+            socket.terminate();
+        }, idleTimeoutMs);
+    }
     const socketHandlers = {
         open(socket) {
             const clientId = uuid();
@@ -63,17 +117,19 @@ export function createTcpServer(queueManager, config) {
                 frameParser: new FrameParser(),
                 ctx,
                 semaphore: new Semaphore(MAX_CONCURRENT_PER_CONNECTION),
+                writeQueue: new SocketWriteQueue(maxWriteQueueBytes),
+                stallTimer: null,
             };
             connections.set(clientId, socket);
             queueManager.emitDashboardEvent('client:connected', { clientId, transport: 'tcp' });
         },
         async data(socket, data) {
-            const { frameParser, ctx, state, semaphore } = socket.data;
+            const { frameParser, ctx, state, semaphore, writeQueue } = socket.data;
             const rateLimiter = getRateLimiter();
             // Check rate limit
             if (!rateLimiter.isAllowed(state.clientId)) {
                 ctx.queueManager.emitDashboardEvent('ratelimit:hit', { clientId: state.clientId });
-                socket.write(errorResponse('Rate limit exceeded'));
+                writeQueue.write(socket, errorResponse('Rate limit exceeded'));
                 return;
             }
             let frames;
@@ -82,12 +138,33 @@ export function createTcpServer(queueManager, config) {
             }
             catch (err) {
                 if (err instanceof FrameSizeError) {
-                    socket.write(errorResponse(`Frame too large: ${err.requestedSize} bytes exceeds maximum ${err.maxSize}`));
+                    clearStallTimer(socket);
+                    writeQueue.write(socket, errorResponse(`Frame too large: ${err.requestedSize} bytes exceeds maximum ${err.maxSize}`));
                     socket.end();
                     return;
                 }
                 throw err;
             }
+            // Slowloris mitigation: (re)arm the stall timer based on whether a partial
+            // frame is now buffered. Progress (a completed frame draining the buffer)
+            // disarms it; a started-but-unfinished frame arms it. This bounds memory
+            // held by a peer that declares a large (legal) frame then never finishes.
+            updateStallTimer(socket);
+            // Drop a connection whose outbound queue grew unbounded (client stopped
+            // reading while we keep producing responses) — bounds write-side memory.
+            const dropForWriteOverflow = () => {
+                if (writeQueue.isOverBudget) {
+                    tcpLog.warn('Closing connection: write queue exceeded budget', {
+                        clientId: state.clientId,
+                        queuedBytes: writeQueue.bytesQueued,
+                    });
+                    clearStallTimer(socket);
+                    writeQueue.clear();
+                    socket.terminate();
+                    return true;
+                }
+                return false;
+            };
             // Process frames in parallel for pipelining support
             // Each command is processed with semaphore-controlled concurrency
             const processFrame = async (frame) => {
@@ -96,23 +173,25 @@ export function createTcpServer(queueManager, config) {
                     cmd = unpack(frame);
                 }
                 catch {
-                    socket.write(errorResponse('Invalid command format'));
+                    writeQueue.write(socket, errorResponse('Invalid command format'));
                     return;
                 }
                 if (!cmd?.cmd) {
-                    socket.write(errorResponse('Invalid command'));
+                    writeQueue.write(socket, errorResponse('Invalid command'));
                     return;
                 }
                 // Process with concurrency limit
                 await withSemaphore(semaphore, async () => {
                     try {
                         const response = await handleCommand(cmd, ctx);
-                        socket.write(serializeResponse(response));
+                        writeQueue.write(socket, serializeResponse(response));
+                        dropForWriteOverflow();
                     }
                     catch (err) {
                         const raw = err instanceof Error ? err.message : 'Unknown error';
                         const message = raw.includes('SQLITE') || raw.includes('database') ? 'Internal server error' : raw;
-                        socket.write(errorResponse(message, cmd.reqId));
+                        writeQueue.write(socket, errorResponse(message, cmd.reqId));
+                        dropForWriteOverflow();
                     }
                 });
             };
@@ -121,6 +200,10 @@ export function createTcpServer(queueManager, config) {
         },
         close(socket) {
             const clientId = socket.data.state.clientId;
+            // Cancel the slowloris stall timer and drop any buffered-but-unwritten
+            // bytes; the socket is gone.
+            clearStallTimer(socket);
+            socket.data.writeQueue.clear();
             connections.delete(clientId);
             getRateLimiter().removeClient(clientId);
             queueManager.unregisterWorkersByClientId(clientId);
@@ -131,20 +214,26 @@ export function createTcpServer(queueManager, config) {
                 // Jobs released successfully
             })
                 .catch((err) => {
-                // After all retries failed, log the final error
-                // Jobs may be left in inconsistent state - manual intervention may be needed
-                tcpLog.error('Client jobs may be in inconsistent state', {
+                // After all retries failed, fall back to a force-release that
+                // unconditionally clears client tracking (prevents Map leak) and
+                // resets heartbeats so the stall detector recovers any orphaned
+                // 'active' jobs on its next tick.
+                const touched = queueManager.forceReleaseClientJobs(clientId);
+                tcpLog.error('Client jobs release failed; fell back to force-release', {
                     clientId,
                     error: String(err),
-                    action: 'Manual cleanup may be required',
+                    forcedJobs: touched,
+                    note: 'Stall detector will recover orphaned active jobs on next tick',
                 });
             });
         },
         error(_socket, error) {
             tcpLog.error('Connection error', { error: error.message });
         },
-        drain(_socket) {
-            // Called when socket is ready for more writes after backpressure
+        drain(socket) {
+            // Socket is ready for more writes after backpressure: flush any unwritten
+            // tail bytes buffered by short writes, preserving frame order.
+            socket.data.writeQueue.flush(socket);
         },
     };
     // Create TCP server
@@ -164,17 +253,25 @@ export function createTcpServer(queueManager, config) {
         broadcast(message) {
             const frame = FrameParser.frame(pack(message));
             for (const socket of connections.values()) {
-                socket.write(frame);
+                // Each connection writes through its own backpressure-aware queue so a
+                // slow reader buffers (in order) instead of dropping frame tail bytes.
+                socket.data.writeQueue.write(socket, frame);
+                // Drop any reader that has fallen too far behind (write-side bound).
+                if (socket.data.writeQueue.isOverBudget) {
+                    clearStallTimer(socket);
+                    socket.data.writeQueue.clear();
+                    socket.terminate();
+                }
             }
         },
         /** Stop the server */
         stop() {
             server.stop();
             for (const socket of connections.values()) {
+                clearStallTimer(socket);
                 socket.end();
             }
             connections.clear();
         },
     };
 }
-//# sourceMappingURL=tcp.js.map

package/dist/infrastructure/server/types.d.ts

@@ -10,4 +10,3 @@ export interface HandlerContext {
     /** Client ID for job ownership tracking */
     clientId?: string;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/infrastructure/server/types.js

@@ -2,4 +2,3 @@
  * Server types
  */
 export {};
-//# sourceMappingURL=types.js.map

package/dist/infrastructure/server/wsHandler.d.ts

@@ -55,4 +55,3 @@ export declare class WsHandler {
     private handleUnsubscribe;
     getClients(): Map<string, ServerWebSocket<WsData>>;
 }
-//# sourceMappingURL=wsHandler.d.ts.map

package/dist/infrastructure/server/wsHandler.js

@@ -429,4 +429,3 @@ export class WsHandler {
         return this.clients;
     }
 }
-//# sourceMappingURL=wsHandler.js.map

package/dist/main.d.ts

@@ -5,4 +5,3 @@
  */
 export { defineConfig } from './config';
 export type { BunqueueConfig } from './config';
-//# sourceMappingURL=main.d.ts.map

package/dist/main.js

@@ -3,39 +3,41 @@
  * bunqueue - High-performance job queue server for Bun
  * Main entry point - routes to CLI for client commands or starts server
  */
-// Check for CLI client commands (not server mode)
-const clientCommands = [
-    'push',
-    'pull',
-    'ack',
-    'fail',
-    'job',
-    'queue',
-    'dlq',
-    'cron',
-    'worker',
-    'webhook',
-    'rate-limit',
-    'concurrency',
-    'stats',
-    'metrics',
-    'health',
-    'backup',
-];
-const firstArg = process.argv[2];
-const isClientCommand = firstArg && clientCommands.includes(firstArg);
-const isStartCommand = firstArg === 'start';
-const hasHelpOrVersion = process.argv.includes('--help') || process.argv.includes('--version');
-// Route to CLI when flags are passed (e.g. `bunqueue -p 8945`)
-// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- process.argv[2] can be undefined at runtime
-const hasFlags = firstArg?.startsWith('-');
-// Route to CLI for client commands, help, version, start, or when flags are present
-if (isClientCommand || hasHelpOrVersion || isStartCommand || hasFlags) {
-    void import('./cli/index').then(({ main }) => main());
-}
-else {
-    // Direct server mode (no args at all)
-    void startServer();
+// Only run startup dispatch when this file is the program entry point.
+// Issue #85: re-exporting `defineConfig` means user config files import this
+// module; without this guard, the top-level dispatch would re-run the CLI/server
+// on every import and cause "Failed to listen at 0.0.0.0".
+if (import.meta.main) {
+    const clientCommands = [
+        'push',
+        'pull',
+        'ack',
+        'fail',
+        'job',
+        'queue',
+        'dlq',
+        'cron',
+        'worker',
+        'webhook',
+        'rate-limit',
+        'concurrency',
+        'stats',
+        'metrics',
+        'health',
+        'backup',
+    ];
+    const firstArg = process.argv[2];
+    const isClientCommand = firstArg && clientCommands.includes(firstArg);
+    const isStartCommand = firstArg === 'start';
+    const hasHelpOrVersion = process.argv.includes('--help') || process.argv.includes('--version');
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- process.argv[2] can be undefined at runtime
+    const hasFlags = firstArg?.startsWith('-');
+    if (isClientCommand || hasHelpOrVersion || isStartCommand || hasFlags) {
+        void import('./cli/index').then(({ main }) => main());
+    }
+    else {
+        void startServer();
+    }
 }
 import { QueueManager } from './application/queueManager';
 import { createTcpServer } from './infrastructure/server/tcp';
@@ -230,16 +232,18 @@ async function startServer() {
         });
     }, config.statsIntervalMs);
 }
-// Enable JSON logging if requested (fallback for CLI mode which doesn't go through startServer)
-if (Bun.env.LOG_FORMAT === 'json') {
-    Logger.enableJsonMode();
-}
-// Set log level from environment (fallback for CLI mode)
-if (Bun.env.LOG_LEVEL) {
-    const validLevels = ['debug', 'info', 'warn', 'error'];
-    const level = Bun.env.LOG_LEVEL.toLowerCase();
-    if (validLevels.includes(level)) {
-        Logger.setLevel(level);
+// Logger env-var bootstrap only applies when this file is the entry point.
+// Imported consumers (e.g. user config files using `defineConfig`) must not
+// have their process Logger state mutated as a side effect — see Issue #85.
+if (import.meta.main) {
+    if (Bun.env.LOG_FORMAT === 'json') {
+        Logger.enableJsonMode();
+    }
+    if (Bun.env.LOG_LEVEL) {
+        const validLevels = ['debug', 'info', 'warn', 'error'];
+        const level = Bun.env.LOG_LEVEL.toLowerCase();
+        if (validLevels.includes(level)) {
+            Logger.setLevel(level);
+        }
     }
 }
-//# sourceMappingURL=main.js.map

package/dist/mcp/adapter.d.ts

@@ -139,7 +139,7 @@ export interface McpBackend {
     obliterateQueue(queue: string): Promise<void>;
     listQueues(): Promise<string[]>;
     countJobs(queue: string): Promise<number>;
-    cleanQueue(queue: string, graceMs: number, state?: string, limit?: number): Promise<number>;
+    cleanQueue(queue: string, graceMs: number, state?: string, limit?: number): Promise<string[]>;
     isPaused(queue: string): Promise<boolean>;
     getCountsPerPriority(queue: string): Promise<Record<number, number>>;
     getDlq(queue: string, limit?: number): Promise<SerializedJob[]>;
@@ -242,7 +242,7 @@ export declare class EmbeddedBackend implements McpBackend {
     obliterateQueue(queue: string): Promise<void>;
     listQueues(): Promise<string[]>;
     countJobs(queue: string): Promise<number>;
-    cleanQueue(queue: string, graceMs: number, state?: string, limit?: number): Promise<number>;
+    cleanQueue(queue: string, graceMs: number, state?: string, limit?: number): Promise<import("../domain/types").JobId[]>;
     isPaused(queue: string): Promise<boolean>;
     getCountsPerPriority(queue: string): Promise<Record<number, number>>;
     getDlq(queue: string, limit?: number): Promise<SerializedJob[]>;
@@ -354,7 +354,7 @@ export declare class TcpBackend implements McpBackend {
     obliterateQueue(queue: string): Promise<void>;
     listQueues(): Promise<string[]>;
     countJobs(queue: string): Promise<number>;
-    cleanQueue(queue: string, graceMs: number, state?: string, limit?: number): Promise<number>;
+    cleanQueue(queue: string, graceMs: number, state?: string, limit?: number): Promise<string[]>;
     isPaused(queue: string): Promise<boolean>;
     getCountsPerPriority(queue: string): Promise<Record<number, number>>;
     getDlq(queue: string, limit?: number): Promise<SerializedJob[]>;
@@ -402,4 +402,3 @@ export declare class TcpBackend implements McpBackend {
 }
 /** Create backend based on environment configuration */
 export declare function createBackend(): Promise<McpBackend>;
-//# sourceMappingURL=adapter.d.ts.map