bunqueue 2.8.38 → 2.8.40

package/dist/cli/index.js

@@ -1,373 +1,109 @@
 #!/usr/bin/env bun
-/**
- * bunqueue CLI Entry Point
- * Routes to server or client mode based on arguments
- */
-import { runServer } from './commands/server';
 import { executeCommand } from './client';
-import { printHelp, printVersion, printPushHelp, printCronAddHelp } from './help';
-import { isBackupCommand, executeBackupCommand } from './commands/backup';
-import { runDoctor } from './commands/doctor';
+import { executeBackupCommand, isBackupCommand } from './commands/backup';
+import { formatDoctorText, runDoctor } from './commands/doctor';
+import { runServer } from './commands/server';
+import { renderCronAddHelp, renderHelp, renderPushHelp, renderServerHelp, renderVersion, } from './help';
+import { parseGlobalOptions } from './globalOptions';
+import { collectVersionInfo, emitLocalOutput, formatVersionInfoText, } from './localOutput';
 import { VERSION } from '../shared/version';
-import { resolveToken } from '../client/resolveToken';
-/**
- * Resolve TCP port from env when not set via --port flag.
- * Priority: explicit CLI flag (caller-checked) > TCP_PORT (server's primary var)
- *          > BUNQUEUE_TCP_PORT > BQ_TCP_PORT. Reads TCP_PORT first so users
- * running both server and client in the same shell with TCP_PORT=X get
- * consistent behavior — same var binds the server AND routes the client.
- */
-function resolveEnvPort(currentPort) {
-    const envPort = Bun.env.TCP_PORT ?? Bun.env.BUNQUEUE_TCP_PORT ?? Bun.env.BQ_TCP_PORT;
-    if (!envPort)
-        return currentPort;
-    const parsed = parseInt(envPort, 10);
-    if (Number.isNaN(parsed) || parsed < 1 || parsed > 65535) {
-        console.warn(`Warning: Invalid env port "${envPort}". Using ${currentPort}.`);
-        return currentPort;
-    }
-    return parsed;
-}
-/**
- * Resolve host from env when not set via --host flag.
- * Priority: HOST (server's primary var) > BUNQUEUE_HOST > BQ_HOST.
- */
-function resolveEnvHost(currentHost) {
-    return Bun.env.HOST ?? Bun.env.BUNQUEUE_HOST ?? Bun.env.BQ_HOST ?? currentHost;
-}
-/**
- * Handle a `--tls*` global client flag and return the index to continue
- * scanning from. Flags that are NOT client TLS flags (e.g. the server's
- * --tls-cert/--tls-key) are passed through to `commandArgs`.
- */
-function applyTlsFlag(arg, allArgs, i, state, commandArgs) {
-    if (arg === '--tls') {
-        state.enabled = true;
-        return i;
-    }
-    if (arg === '--tls-no-verify') {
-        state.noVerify = true;
-        return i;
-    }
-    if (arg === '--tls-ca') {
-        const nextArg = allArgs[i + 1];
-        // A following flag is not a path: don't swallow it (--tls-ca --json ...)
-        if (nextArg === undefined || nextArg.startsWith('-')) {
-            console.warn('Warning: --tls-ca requires a file path. Option ignored.');
-            return i;
-        }
-        state.caFile = nextArg;
-        return i + 1;
-    }
-    if (arg.startsWith('--tls-ca=')) {
-        const val = arg.slice(9);
-        if (!val) {
-            console.warn('Warning: --tls-ca= requires a file path. Option ignored.');
-        }
-        else {
-            state.caFile = val;
-        }
-        return i;
-    }
-    commandArgs.push(arg); // --tls-cert / --tls-key etc. → server flags, pass through
-    return i;
-}
-/** Build the GlobalOptions.tls value: --tls-ca / --tls-no-verify imply TLS */
-function buildTlsOption(state) {
-    if (state.noVerify || state.caFile !== undefined) {
-        return {
-            ...(state.noVerify && { rejectUnauthorized: false }),
-            ...(state.caFile !== undefined && { caFile: state.caFile }),
-        };
-    }
-    return state.enabled ? true : undefined;
+export { parseGlobalOptions } from './globalOptions';
+function finish(output, json) {
+    emitLocalOutput(output, json);
+    process.exit(output.exitCode);
 }
-/**
- * Exactly two subcommands define their own short `-t` (--timeout):
- * `pull` and `job wait`. ONLY there `-t` is passed through instead of being
- * consumed as the global token flag — every other command keeps `-t TOKEN`
- * working anywhere on the line. The long form `--token` is global everywhere.
- */
-function commandOwnsShortT(commandArgs) {
-    return commandArgs[0] === 'pull' || (commandArgs[0] === 'job' && commandArgs[1] === 'wait');
+function helpFor(command, color) {
+    if (command === 'start')
+        return renderServerHelp();
+    if (command === 'push')
+        return renderPushHelp();
+    if (command === 'cron')
+        return renderCronAddHelp();
+    return renderHelp(color);
 }
-/**
- * Handle `--token` / global `-t` and return the index to continue scanning
- * from. When the command already parsed owns short `-t` (pull / job wait),
- * the flag is passed through to the subcommand instead of being consumed.
- */
-function applyTokenFlag(arg, allArgs, i, state, commandArgs) {
-    if (arg === '-t' && commandOwnsShortT(commandArgs)) {
-        commandArgs.push(arg); // pull / job wait own -t (timeout): pass through
-        return i;
-    }
-    const nextArg = allArgs[i + 1];
-    // A following flag is not a token: don't swallow it (--token --json ...)
-    if (nextArg === undefined || nextArg.startsWith('-')) {
-        console.warn('Warning: --token requires a value. Token not set.');
-        return i;
-    }
-    state.token = nextArg;
-    return i + 1;
-}
-/** Handle `--host`/`-H <value>`; refuses to swallow a following flag. */
-function applyHostFlag(allArgs, i, state) {
-    const nextArg = allArgs[i + 1];
-    if (nextArg === undefined || nextArg.startsWith('-')) {
-        console.warn('Warning: --host requires a value. Using localhost.');
-        return i;
-    }
-    state.host = nextArg;
-    state.hostExplicit = true;
-    return i + 1;
-}
-/** Handle `--port`/`-p <value>`; refuses to swallow a following flag. */
-function applyPortFlag(allArgs, i, state) {
-    const nextArg = allArgs[i + 1];
-    if (nextArg === undefined || nextArg.startsWith('-')) {
-        console.warn('Warning: --port requires a value. Using default port 6789.');
-        return i;
-    }
-    const parsed = parseInt(nextArg, 10);
-    if (Number.isNaN(parsed) || parsed < 1 || parsed > 65535) {
-        console.warn(`Warning: Invalid port "${nextArg}". Using default port 6789.`);
-        state.port = 6789;
-    }
-    else {
-        state.port = parsed;
-        state.portExplicit = true;
-    }
-    return i + 1;
-}
-/**
- * Attached-value short flags (-p10, -Hfoo) shadowing a global flag letter are
- * silently mis-parsed downstream (strict:false expands them to garbage
- * booleans — e.g. push -p10 dropped the priority and pushed anyway). Warn so
- * the user switches to the separated/long form. Exception: -t<value> after
- * pull/job wait, where parseArgs handles the attached form correctly.
- */
-function warnAmbiguousAttachedShort(arg, commandArgs) {
-    if (!/^-[Hpthv][^-\s]/.test(arg))
-        return;
-    if (arg.startsWith('-t') && commandOwnsShortT(commandArgs))
-        return;
-    console.warn(`Warning: "${arg}" looks like a short flag with an attached value; ` +
-        `use the separated form ("${arg.slice(0, 2)} ${arg.slice(2)}") or the long form.`);
-}
-/** Parse global options from process.argv */
-export function parseGlobalOptions() {
-    const allArgs = process.argv.slice(2);
-    // Extract global options manually to preserve subcommand flags
-    const hp = {
-        host: 'localhost',
-        port: 6789,
-        hostExplicit: false,
-        portExplicit: false,
-    };
-    const tokenState = {};
-    let json = false;
-    let help = false;
-    let version = false;
-    const tlsState = { enabled: false, noVerify: false };
-    const commandArgs = [];
-    let i = 0;
-    while (i < allArgs.length) {
-        const arg = allArgs[i];
-        if (arg === '--') {
-            // Separator: everything after -- is opaque to the global parser
-            commandArgs.push(...allArgs.slice(i + 1));
-            break;
-        }
-        if (arg === '--host' || arg === '-H') {
-            i = applyHostFlag(allArgs, i, hp);
-        }
-        else if (arg === '--port' || arg === '-p') {
-            i = applyPortFlag(allArgs, i, hp);
-        }
-        else if (arg === '--token' || arg === '-t') {
-            i = applyTokenFlag(arg, allArgs, i, tokenState, commandArgs);
-        }
-        else if (arg.startsWith('--tls')) {
-            i = applyTlsFlag(arg, allArgs, i, tlsState, commandArgs);
-        }
-        else if (arg === '--json') {
-            json = true;
-        }
-        else if (arg === '--help' || (arg === '-h' && commandArgs.length === 0)) {
-            // Short -h is global help ONLY before the command: after it, a typo of
-            // -H (host) must not suppress execution with a false-success exit 0.
-            help = true;
-        }
-        else if (arg === '--version' || (arg === '-v' && commandArgs.length === 0)) {
-            version = true;
-        }
-        else if (arg.startsWith('--host=')) {
-            hp.host = arg.slice(7);
-            hp.hostExplicit = true;
-        }
-        else if (arg.startsWith('--port=')) {
-            const raw = arg.slice(7);
-            const parsed = parseInt(raw, 10);
-            if (Number.isNaN(parsed) || parsed < 1 || parsed > 65535) {
-                console.warn(`Warning: Invalid port "${raw}". Using default port 6789.`);
-                hp.port = 6789;
-            }
-            else {
-                hp.port = parsed;
-                hp.portExplicit = true;
-            }
-        }
-        else if (arg.startsWith('--token=')) {
-            const val = arg.slice(8);
-            if (!val) {
-                console.warn('Warning: --token= requires a value. Token not set.');
-            }
-            else {
-                tokenState.token = val;
-            }
-        }
-        else {
-            warnAmbiguousAttachedShort(arg, commandArgs);
-            // Not a global option, pass to command
-            commandArgs.push(arg);
-        }
-        i++;
-    }
-    // Detect server mode: explicit 'start', no args, or first arg is a flag (server flags)
-    const isServerMode = commandArgs[0] === 'start' || commandArgs.length === 0 || commandArgs[0]?.startsWith('-');
-    // Re-inject explicitly-set --host and --port into commandArgs
-    // so they reach parseServerArgs in runServer().
-    // Global -p/--port maps to --tcp-port for the server command.
-    if (isServerMode) {
-        if (hp.hostExplicit) {
-            commandArgs.push('--host', hp.host);
-        }
-        if (hp.portExplicit) {
-            commandArgs.push('--tcp-port', String(hp.port));
-        }
+async function executeLocalCommand(command, args, host, port, json) {
+    if (command === 'version') {
+        const info = await collectVersionInfo(host, port + 1);
+        finish({
+            exitCode: 0,
+            json: { ok: true, ...info },
+            text: formatVersionInfoText(info),
+        }, json);
     }
-    // Fall back to environment variables for token if not set via CLI flag
-    // Priority: --token flag > BQ_TOKEN > BUNQUEUE_TOKEN
-    const token = resolveToken(tokenState.token);
-    const port = hp.portExplicit ? hp.port : resolveEnvPort(hp.port);
-    const host = hp.hostExplicit ? hp.host : resolveEnvHost(hp.host);
-    return {
-        options: { host, port, token, tls: buildTlsOption(tlsState), json, help, version },
-        commandArgs,
-    };
-}
-/** Show client + server version */
-async function printVersionInfo(host, httpPort) {
-    console.log(`Client: bunqueue v${VERSION}`);
+    if (command === 'doctor') {
+        const report = await runDoctor(host, port + 1);
+        finish({
+            exitCode: report.exitCode,
+            json: { ok: report.exitCode === 0, ...report },
+            text: formatDoctorText(report),
+        }, json);
+    }
+    if (!isBackupCommand(command))
+        return false;
     try {
-        const resp = await fetch(`http://${host}:${httpPort}/health`, {
-            signal: AbortSignal.timeout(3000),
-        });
-        if (!resp.ok)
-            return;
-        const data = (await resp.json());
-        if (!data.version)
-            return;
-        console.log(`Server: bunqueue v${data.version}`);
-        if (data.version !== VERSION) {
-            console.log(`\n⚠ Version mismatch! Update server or client to match.`);
-        }
-    }
-    catch {
-        console.log(`Server: not reachable (${host}:${httpPort})`);
+        const result = await executeBackupCommand(args);
+        finish({
+            exitCode: result.success ? 0 : 1,
+            json: result,
+            text: result.data
+                ? `${result.message}\n${JSON.stringify(result.data, null, 2)}`
+                : result.message,
+        }, json);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error occurred';
+        finish({
+            exitCode: 1,
+            json: { success: false, message },
+            text: `Error: ${message}`,
+            stream: 'stderr',
+        }, json);
     }
 }
-/** Main CLI entry */
 export async function main() {
     const { options, commandArgs } = parseGlobalOptions();
-    // Handle --version
+    const command = commandArgs[0];
     if (options.version) {
-        printVersion(VERSION);
-        process.exit(0);
+        finish({
+            exitCode: 0,
+            json: { ok: true, version: VERSION },
+            text: renderVersion(VERSION),
+        }, options.json);
     }
-    // Handle --help with no command
-    if (options.help && commandArgs.length === 0) {
-        printHelp();
-        process.exit(0);
+    if (options.help) {
+        const help = helpFor(command, !options.json);
+        finish({
+            exitCode: 0,
+            json: { ok: true, help },
+            text: help,
+        }, options.json);
     }
-    // Get the command (first positional argument)
-    const command = commandArgs[0];
-    // No command, 'start', or first arg is a flag (server flags like --tcp-port) = server mode
     if (!command || command === 'start' || command.startsWith('-')) {
         const serverArgs = command === 'start' ? commandArgs.slice(1) : commandArgs;
-        await runServer(serverArgs, options.help);
+        await runServer(serverArgs, false);
         return;
     }
-    // Help for specific command
-    if (options.help) {
-        if (command === 'push')
-            printPushHelp();
-        else if (command === 'cron')
-            printCronAddHelp();
-        else
-            printHelp();
-        process.exit(0);
-    }
-    // Version command - shows client version + server version if reachable
-    if (command === 'version') {
-        await printVersionInfo(options.host, options.port + 1);
-        process.exit(0);
-    }
-    // Doctor command - diagnostics, not via TCP
-    if (command === 'doctor') {
-        await runDoctor(options.host, options.port + 1);
-        return;
-    }
-    // Backup command - executed locally, not via TCP
-    if (isBackupCommand(command)) {
-        try {
-            const result = await executeBackupCommand(commandArgs.slice(1));
-            if (options.json) {
-                console.log(JSON.stringify(result, null, 2));
-            }
-            else {
-                console.log(result.message);
-                if (result.data) {
-                    console.log(JSON.stringify(result.data, null, 2));
-                }
-            }
-            process.exit(result.success ? 0 : 1);
-        }
-        catch (err) {
-            if (err instanceof Error) {
-                console.error(`Error: ${err.message}`);
-            }
-            else {
-                console.error('Unknown error occurred');
-            }
-            process.exit(1);
-        }
+    if (await executeLocalCommand(command, commandArgs.slice(1), options.host, options.port, options.json)) {
         return;
     }
-    // Client mode - execute command against server
-    try {
-        await executeCommand(command, commandArgs.slice(1), {
-            host: options.host,
-            port: options.port,
-            token: options.token,
-            tls: options.tls,
-            json: options.json,
-        });
-    }
-    catch (err) {
-        if (err instanceof Error) {
-            console.error(`Error: ${err.message}`);
-        }
-        else {
-            console.error('Unknown error occurred');
-        }
-        process.exit(1);
-    }
+    await executeCommand(command, commandArgs.slice(1), {
+        host: options.host,
+        port: options.port,
+        token: options.token,
+        tls: options.tls,
+        json: options.json,
+    });
 }
-// Run only if this file is the direct entry point
 if (import.meta.main) {
-    main().catch((err) => {
-        console.error('Fatal error:', err);
+    main().catch((error) => {
+        const message = error instanceof Error ? error.message : 'Unknown error occurred';
+        const json = process.argv.includes('--json');
+        emitLocalOutput({
+            exitCode: 1,
+            json: { ok: false, error: message },
+            text: `Fatal error: ${message}`,
+            stream: 'stderr',
+        }, json);
         process.exit(1);
     });
 }

package/dist/cli/localOutput.d.ts

@@ -0,0 +1,22 @@
+export interface LocalOutput {
+    exitCode: number;
+    json: unknown;
+    text: string;
+    stream?: 'stdout' | 'stderr';
+}
+export interface VersionInfo {
+    client: {
+        name: 'bunqueue';
+        version: string;
+    };
+    server: {
+        endpoint: string;
+        reachable: boolean;
+        version?: string;
+    };
+    mismatch: boolean;
+}
+/** The only writer used by local commands, keeping JSON to one stream and document. */
+export declare function emitLocalOutput(output: LocalOutput, json: boolean): void;
+export declare function collectVersionInfo(host: string, httpPort: number): Promise<VersionInfo>;
+export declare function formatVersionInfoText(info: VersionInfo): string;

package/dist/cli/localOutput.js

@@ -0,0 +1,45 @@
+import { VERSION } from '../shared/version';
+/** The only writer used by local commands, keeping JSON to one stream and document. */
+export function emitLocalOutput(output, json) {
+    const text = json ? JSON.stringify(output.json, null, 2) : output.text;
+    const writer = output.stream === 'stderr' ? console.error : console.log;
+    writer(text);
+}
+export async function collectVersionInfo(host, httpPort) {
+    const server = {
+        endpoint: `${host}:${httpPort}`,
+        reachable: false,
+    };
+    try {
+        const response = await fetch(`http://${server.endpoint}/health`, {
+            signal: AbortSignal.timeout(3000),
+        });
+        if (response.ok) {
+            const data = (await response.json());
+            server.reachable = true;
+            if (data.version)
+                server.version = data.version;
+        }
+    }
+    catch {
+        // Unreachable is part of the version result, not an exceptional path.
+    }
+    return {
+        client: { name: 'bunqueue', version: VERSION },
+        server,
+        mismatch: server.version !== undefined && server.version !== VERSION,
+    };
+}
+export function formatVersionInfoText(info) {
+    const lines = [`Client: bunqueue v${info.client.version}`];
+    if (!info.server.reachable) {
+        lines.push(`Server: not reachable (${info.server.endpoint})`);
+    }
+    else if (info.server.version) {
+        lines.push(`Server: bunqueue v${info.server.version}`);
+        if (info.mismatch) {
+            lines.push('', '⚠ Version mismatch! Update server or client to match.');
+        }
+    }
+    return lines.join('\n');
+}

package/dist/client/queue/dlqOps.js

@@ -9,9 +9,7 @@ import { getShard, getDlqContext, toDomainFilter, toDomainDlqConfig } from './he
 import * as dlqOps from '../../application/dlqManager';
 /** Set DLQ configuration (embedded only) */
 export function setDlqConfig(queue, config) {
-    const manager = getSharedManager();
-    const ctx = getDlqContext(manager);
-    dlqOps.configureDlq(queue, ctx, toDomainDlqConfig(config));
+    getSharedManager().setDlqConfig(queue, toDomainDlqConfig(config));
 }
 /** Get DLQ configuration (embedded only) */
 export function getDlqConfigEmbedded(queue) {

package/dist/client/tcp/client.js

@@ -8,8 +8,8 @@ import { DEFAULT_CONNECTION } from './types';
 import { HealthTracker } from './health';
 import { ReconnectManager } from './reconnect';
 import { createConnection, CommandQueue } from './connection';
-import { pack, unpack } from 'msgpackr';
 import { FrameParser } from '../../infrastructure/server/protocol';
+import { decodeMessagePack, encodeMessagePack } from '../../shared/msgpack';
 /**
  * Sentinel error class for the synthetic rejection issued by close()/rejectAll().
  * Using a dedicated subclass (instead of matching `error.message`) ensures the
@@ -55,11 +55,11 @@ function installClientClosedFilter() {
  * Supports pipelining for high-throughput operations
  */
 export class TcpClient extends EventEmitter {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    // biome-ignore lint/suspicious/noExplicitAny: EventEmitter's fallback overload requires any[]
     on(event, listener) {
         return super.on(event, listener);
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    // biome-ignore lint/suspicious/noExplicitAny: EventEmitter's fallback overload requires any[]
     once(event, listener) {
         return super.once(event, listener);
     }
@@ -174,7 +174,7 @@ export class TcpClient extends EventEmitter {
      */
     handleData(frame) {
         try {
-            const response = unpack(frame);
+            const response = decodeMessagePack(frame);
             const reqId = response.reqId;
             // Try pipelining mode first (reqId-based matching)
             if (reqId) {
@@ -352,7 +352,7 @@ export class TcpClient extends EventEmitter {
         pendingRef.promise = promise;
         this.commands.addInFlight(pendingRef);
         // Send immediately (this.socket null-checked at entry of sendDirect)
-        this.socket.write(FrameParser.frame(pack(commandWithReqId)));
+        this.socket.write(FrameParser.frame(encodeMessagePack(commandWithReqId)));
         return promise;
     }
     /**
@@ -381,14 +381,14 @@ export class TcpClient extends EventEmitter {
             next.timeout = newTimeout;
             // Add to in-flight tracking and send
             this.commands.addInFlight(next);
-            this.socket.write(FrameParser.frame(pack(next.command)));
+            this.socket.write(FrameParser.frame(encodeMessagePack(next.command)));
         }
     }
     /**
      * Send command and wait for response
      * Uses pipelining for high throughput
      */
-    async send(command) {
+    send(command) {
         const startTime = Date.now();
         this.health.recordCommandSent();
         const reqId = this.generateReqId();
@@ -435,7 +435,9 @@ export class TcpClient extends EventEmitter {
         // Connect if needed, then process queue
         if (!this.connected && !this.connecting) {
             // Connection errors during send are handled by command timeout/rejection
-            this.connect().catch(() => { });
+            this.connect().catch(() => {
+                // The queued command owns timeout and rejection reporting.
+            });
         }
         else if (this.connected) {
             this.processQueue();

package/dist/domain/queue/shard.d.ts

@@ -51,8 +51,8 @@ export declare class Shard {
     notify(queue?: string): void;
     notifyBatch(count: number): void;
     notifyBatch(queue: string, count: number): void;
-    waitForJob(timeoutMs: number): Promise<void>;
-    waitForJob(queue: string, timeoutMs: number): Promise<void>;
+    waitForJob(timeoutMs: number, signal?: AbortSignal): Promise<void>;
+    waitForJob(queue: string, timeoutMs: number, signal?: AbortSignal): Promise<void>;
     getQueue(name: string): IndexedPriorityQueue;
     getState(name: string): QueueState;
     isPaused(name: string): boolean;

package/dist/domain/queue/shard.js

@@ -69,11 +69,11 @@ export class Shard {
             this.waiterManager.notifyBatch(queueOrCount, maybeCount ?? 0);
         }
     }
-    waitForJob(queueOrTimeout, maybeTimeout) {
+    waitForJob(queueOrTimeout, maybeTimeoutOrSignal, maybeSignal) {
         if (typeof queueOrTimeout === 'number') {
-            return this.waiterManager.waitForJob(queueOrTimeout);
+            return this.waiterManager.waitForJob(queueOrTimeout, maybeTimeoutOrSignal);
         }
-        return this.waiterManager.waitForJob(queueOrTimeout, maybeTimeout ?? 0);
+        return this.waiterManager.waitForJob(queueOrTimeout, typeof maybeTimeoutOrSignal === 'number' ? maybeTimeoutOrSignal : 0, maybeSignal);
     }
     // ============ Queue Operations ============
     getQueue(name) {

package/dist/domain/queue/waiterManager.d.ts

@@ -8,8 +8,8 @@ export declare class WaiterManager {
     notify(queue?: string): void;
     notifyBatch(count: number): void;
     notifyBatch(queue: string, count: number): void;
-    waitForJob(timeoutMs: number): Promise<void>;
-    waitForJob(queue: string, timeoutMs: number): Promise<void>;
+    waitForJob(timeoutMs: number, signal?: AbortSignal): Promise<void>;
+    waitForJob(queue: string, timeoutMs: number, signal?: AbortSignal): Promise<void>;
     private notifyQueue;
     private createQueue;
     private compact;