bunqueue 2.8.6 → 2.8.8

package/dist/application/operations/ack.d.ts

@@ -57,7 +57,7 @@ export declare function ackJob(jobId: JobId, result: unknown, ctx: AckContext):
 /**
  * Mark job as failed
  */
-export declare function failJob(jobId: JobId, error: string | undefined, ctx: AckContext): Promise<void>;
+export declare function failJob(jobId: JobId, error: string | undefined, ctx: AckContext, unrecoverable?: boolean): Promise<void>;
 /**
  * Acknowledge multiple jobs - optimized batch processing
  * Groups jobs by shard to minimize lock acquisitions: O(shards) instead of O(n)

package/dist/application/operations/ack.js

@@ -112,7 +112,7 @@ function moveFailedJobToDlq(job, jobId, error, shard, ctx) {
 /**
  * Mark job as failed
  */
-export async function failJob(jobId, error, ctx) {
+export async function failJob(jobId, error, ctx, unrecoverable = false) {
     const procIdx = processingShardIndex(jobId);
     const job = await withWriteLock(ctx.processingLocks[procIdx], () => {
         const job = ctx.processingShards[procIdx].get(jobId);
@@ -134,7 +134,7 @@ export async function failJob(jobId, error, ctx) {
     await withWriteLock(ctx.shardLocks[idx], () => {
         const shard = ctx.shards[idx];
         shard.releaseJobResources(job.queue, job.uniqueKey, job.groupId);
-        if (canRetry(job)) {
+        if (!unrecoverable && canRetry(job)) {
             const now = Date.now();
             job.runAt = now + calculateBackoff(job);
             shard.getQueue(job.queue).push(job);

package/dist/application/queueManager.d.ts

@@ -79,7 +79,7 @@ export declare class QueueManager {
         result: unknown;
         token?: string;
     }>): Promise<void>;
-    fail(jobId: JobId, error?: string, token?: string): Promise<void>;
+    fail(jobId: JobId, error?: string, token?: string, unrecoverable?: boolean): Promise<void>;
     /**
      * Check if a failed lock verification is a genuine ownership conflict.
      * If the job is still in processing with a different lock, throw.

package/dist/application/queueManager.js

@@ -358,7 +358,7 @@ export class QueueManager {
             lockMgr.releaseLock(item.id, lockCtx, item.token);
         }
     }
-    async fail(jobId, error, token) {
+    async fail(jobId, error, token, unrecoverable = false) {
         const lockCtx = this.contextFactory.getLockContext();
         if (token && !lockMgr.verifyLock(jobId, token, lockCtx)) {
             this.throwIfOwnershipConflict(jobId, lockCtx);
@@ -367,7 +367,7 @@ export class QueueManager {
                 return;
         }
         try {
-            await failJob(jobId, error, this.contextFactory.getAckContext());
+            await failJob(jobId, error, this.contextFactory.getAckContext(), unrecoverable);
         }
         catch (err) {
             // Job removed from processing by stall detection. The stall retry

package/dist/application/statsManager.js

@@ -3,6 +3,16 @@
  * Provides system metrics and memory compaction utilities
  */
 import { SHARD_COUNT, shardIndex } from '../shared/hash';
+/** Count jobs belonging to `queueName` across one or more job iterables. */
+function countByQueue(sources, queueName) {
+    let count = 0;
+    for (const src of sources) {
+        for (const job of src)
+            if (job.queue === queueName)
+                count++;
+    }
+    return count;
+}
 /**
  * Get queue statistics - uses running counters + priority scan
  */
@@ -14,7 +24,10 @@ export function getStats(ctx, cronScheduler) {
         delayed += shardStats.delayedJobs;
         dlq += shardStats.dlqJobs;
         active += ctx.processingShards[i].size;
-        waitingChildren += ctx.shards[i].waitingChildren.size;
+        // getJobState reports BOTH waitingChildren (flow parents) and waitingDeps
+        // (jobs blocked on dependsOn) as state 'waiting-children', and getJobs lists
+        // both — so the count must include both or it undercounts vs state/list (#95 class).
+        waitingChildren += ctx.shards[i].waitingChildren.size + ctx.shards[i].waitingDeps.size;
         // Scan queues to split waiting vs prioritized (BullMQ v5 compat)
         for (const queue of ctx.shards[i].queues.values()) {
             for (const job of queue.values()) {
@@ -174,13 +187,10 @@ export function getQueueJobCounts(queueName, ctx) {
     }
     // Count failed (DLQ) jobs for this queue
     const failed = shard.getDlq(queueName).length;
-    // Count waiting-children jobs (parents waiting for child completion)
-    let waitingChildrenCount = 0;
-    for (const job of shard.waitingChildren.values()) {
-        if (job.queue === queueName) {
-            waitingChildrenCount++;
-        }
-    }
+    // Count waiting-children jobs. getJobState/getJobs treat BOTH waitingChildren
+    // (flow parents) and waitingDeps (jobs blocked on dependsOn) as 'waiting-children',
+    // so count both to stay consistent with state/list (#95 class).
+    const waitingChildrenCount = countByQueue([shard.waitingChildren.values(), shard.waitingDeps.values()], queueName);
     // Per-queue cumulative counters
     const perQueue = ctx.perQueueMetrics?.get(queueName);
     const totalCompleted = Number(perQueue?.totalCompleted ?? 0n);

package/dist/cli/client.d.ts

@@ -2,6 +2,7 @@
  * CLI TCP Client
  * Connects to bunQ server and executes commands (msgpack binary protocol)
  */
+import type { ClientTlsOptions } from '../client/tcp/types';
 /** Client options */
 export interface ClientOptions {
     /** Server host */
@@ -10,6 +11,8 @@ export interface ClientOptions {
     port: number;
     /** Auth token */
     token?: string;
+    /** TLS to the server (true = system CAs, object = custom CA / no-verify) */
+    tls?: boolean | ClientTlsOptions;
     /** Output as JSON */
     json: boolean;
 }

package/dist/cli/client.js

@@ -6,6 +6,7 @@ import { formatOutput, formatError } from './output';
 import { pack, unpack } from 'msgpackr';
 import { FrameParser, FrameSizeError } from '../infrastructure/server/protocol';
 import { CommandError } from './commands/types';
+import { buildClientTls } from '../client/tcp/connection';
 /** Send a command and wait for response */
 async function sendCommand(socket, command) {
     return new Promise((resolve, reject) => {
@@ -45,7 +46,10 @@ async function connect(options) {
                 catch (err) {
                     if (err instanceof FrameSizeError) {
                         if (socketData.reject) {
-                            socketData.reject(new Error(`Frame too large: ${err.requestedSize} bytes exceeds maximum ${err.maxSize}`));
+                            // A plaintext client reading a TLS handshake sees garbage that
+                            // parses as an absurd frame size — hint at the likely cause.
+                            socketData.reject(new Error(`Frame too large: ${err.requestedSize} bytes exceeds maximum ${err.maxSize}` +
+                                ' (is the server running with TLS? try --tls, --tls-ca or --tls-no-verify)'));
                             socketData.resolve = null;
                             socketData.reject = null;
                         }
@@ -95,11 +99,18 @@ async function connect(options) {
                 reject(new Error(`Failed to connect to ${targetDesc}: ${error.message}`));
             },
         };
-        // Connect via TCP
+        // Connect via TCP (optionally wrapped in TLS)
+        const tlsValue = buildClientTls(options.tls);
         void Bun.connect({
             hostname: options.host,
             port: options.port,
+            ...(tlsValue !== undefined && { tls: tlsValue }),
             socket: socketHandlers,
+        }).catch((err) => {
+            // Bun.connect can reject directly (e.g. TLS handshake refused) instead of
+            // firing connectError — surface it instead of waiting out the timeout.
+            const message = err instanceof Error ? err.message : String(err);
+            reject(new Error(`Failed to connect to ${targetDesc}: ${message}`));
         });
         // Handle connection timeout
         const connectionTimeoutId = setTimeout(() => {

package/dist/cli/commands/server.js

@@ -5,7 +5,7 @@
 import { parseArgs } from 'node:util';
 import { printServerHelp } from '../help';
 import { VERSION } from '../../shared/version';
-import { loadConfigFile, resolveServerConfig, resolveCloudConfig } from '../../config';
+import { loadConfigFile, resolveServerConfig, resolveCloudConfig, resolveTlsServerOptions, } from '../../config';
 /** Validate port number */
 function validatePort(value, name, defaultPort) {
     const port = parseInt(value, 10);
@@ -25,6 +25,8 @@ function parseCliFlags(args) {
             host: { type: 'string' },
             'data-path': { type: 'string' },
             'auth-tokens': { type: 'string' },
+            'tls-cert': { type: 'string' },
+            'tls-key': { type: 'string' },
             config: { type: 'string', short: 'c' },
         },
         allowPositionals: false,
@@ -46,6 +48,12 @@ function parseCliFlags(args) {
     if (values['auth-tokens']) {
         flags.authTokens = values['auth-tokens'].split(',').filter(Boolean);
     }
+    if (values['tls-cert']) {
+        flags.tlsCertFile = values['tls-cert'];
+    }
+    if (values['tls-key']) {
+        flags.tlsKeyFile = values['tls-key'];
+    }
     if (values.config) {
         flags.configPath = values.config;
     }
@@ -58,7 +66,9 @@ function applyCliFlags(fileConfig, flags) {
         flags.httpPort !== undefined ||
         flags.host !== undefined ||
         flags.dataPath !== undefined ||
-        flags.authTokens !== undefined;
+        flags.authTokens !== undefined ||
+        flags.tlsCertFile !== undefined ||
+        flags.tlsKeyFile !== undefined;
     if (!hasFlags && !fileConfig)
         return null;
     const base = fileConfig ?? {};
@@ -69,6 +79,8 @@ function applyCliFlags(fileConfig, flags) {
             ...(flags.tcpPort !== undefined && { tcpPort: flags.tcpPort }),
             ...(flags.httpPort !== undefined && { httpPort: flags.httpPort }),
             ...(flags.host !== undefined && { host: flags.host }),
+            ...(flags.tlsCertFile !== undefined && { tlsCertFile: flags.tlsCertFile }),
+            ...(flags.tlsKeyFile !== undefined && { tlsKeyFile: flags.tlsKeyFile }),
         },
         storage: {
             ...base.storage,
@@ -92,6 +104,15 @@ export async function runServer(args, showHelp) {
     const mergedConfig = applyCliFlags(fileConfig, flags);
     const config = resolveServerConfig(mergedConfig);
     const cloudConfig = resolveCloudConfig(mergedConfig, config.dataPath);
+    // Resolve TLS — fail fast on partial cert/key before binding anything
+    let tlsConfig;
+    try {
+        tlsConfig = resolveTlsServerOptions(config);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
     // Import and start the server components
     const { QueueManager } = await import('../../application/queueManager');
     const { createTcpServer } = await import('../../infrastructure/server/tcp');
@@ -110,11 +131,13 @@ export async function runServer(args, showHelp) {
             port: config.tcpPort,
             hostname: config.hostname,
             authTokens,
+            ...(tlsConfig && { tls: tlsConfig }),
         });
         httpServer = createHttpServer(qm, {
             port: config.httpPort,
             hostname: config.hostname,
             authTokens,
+            ...(tlsConfig && { tls: tlsConfig }),
         });
     }
     catch (err) {
@@ -159,6 +182,7 @@ ${dim}────────────────────────
   ${green}●${reset} TCP    ${tcpDisplay}
   ${green}●${reset} HTTP   ${httpDisplay}
   ${yellow}●${reset} Data   ${config.dataPath ?? 'in-memory'}
+  ${yellow}●${reset} TLS    ${tlsConfig ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
   ${yellow}●${reset} Auth   ${authTokens ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
   ${yellow}●${reset} Cloud  ${cloudConfig ? `${green}enabled${reset} ${dim}→ ${cloudConfig.url}${reset}` : `${dim}disabled${reset}`}
 

package/dist/cli/help.js

@@ -98,6 +98,9 @@ GLOBAL OPTIONS:
   -H, --host <host>               Server host (default: localhost)
   -p, --port <port>               TCP port (default: 6789)
   -t, --token <token>             Authentication token (env: BQ_TOKEN, BUNQUEUE_TOKEN)
+  --tls                           Connect with TLS (verify with system CAs)
+  --tls-ca <file>                 Trust a custom CA cert (implies --tls)
+  --tls-no-verify                 TLS without cert verification (self-signed, dev only)
   --json                          Output as JSON
   --help                          Show help
   --version                       Show version
@@ -125,6 +128,8 @@ Options:
   --host <host>           Bind address (default: 0.0.0.0, env: HOST)
   --data-path <path>      SQLite database path (env: DATA_PATH)
   --auth-tokens <list>    Comma-separated auth tokens (env: AUTH_TOKENS)
+  --tls-cert <file>       PEM certificate for native TLS (env: TLS_CERT_FILE)
+  --tls-key <file>        PEM private key for native TLS (env: TLS_KEY_FILE)
   --help                  Show this help
 
 Examples:

package/dist/cli/index.d.ts

@@ -8,6 +8,11 @@ interface GlobalOptions {
     host: string;
     port: number;
     token?: string;
+    /** TLS to the server: true = verify with system CAs, object = custom CA / no-verify */
+    tls?: boolean | {
+        rejectUnauthorized?: boolean;
+        caFile?: string;
+    };
     json: boolean;
     help: boolean;
     version: boolean;

package/dist/cli/index.js

@@ -35,6 +35,53 @@ function resolveEnvPort(currentPort) {
 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;
+}
 /** Parse global options from process.argv */
 export function parseGlobalOptions() {
     const allArgs = process.argv.slice(2);
@@ -47,6 +94,7 @@ export function parseGlobalOptions() {
     let version = false;
     let hostExplicit = false;
     let portExplicit = false;
+    const tlsState = { enabled: false, noVerify: false };
     const commandArgs = [];
     let i = 0;
     while (i < allArgs.length) {
@@ -76,6 +124,9 @@ export function parseGlobalOptions() {
                 token = allArgs[++i];
             }
         }
+        else if (arg.startsWith('--tls')) {
+            i = applyTlsFlag(arg, allArgs, i, tlsState, commandArgs);
+        }
         else if (arg === '--json') {
             json = true;
         }
@@ -137,7 +188,7 @@ export function parseGlobalOptions() {
     if (!hostExplicit)
         host = resolveEnvHost(host);
     return {
-        options: { host, port, token, json, help, version },
+        options: { host, port, token, tls: buildTlsOption(tlsState), json, help, version },
         commandArgs,
     };
 }
@@ -231,6 +282,7 @@ export async function main() {
             host: options.host,
             port: options.port,
             token: options.token,
+            tls: options.tls,
             json: options.json,
         });
     }

package/dist/client/queue/dlq.js

@@ -64,7 +64,7 @@ export function retryDlq(ctx, id) {
     if (ctx.embedded)
         return dlqOps.retryDlqEmbedded(ctx.name, id);
     if (ctx.tcp)
-        void ctx.tcp.send({ cmd: 'RetryDlq', queue: ctx.name, id });
+        void ctx.tcp.send({ cmd: 'RetryDlq', queue: ctx.name, jobId: id });
     return 0;
 }
 /** Retry DLQ entries by filter */

package/dist/client/queue/operations/management.js

@@ -77,7 +77,8 @@ export async function cleanAsync(ctx, grace, limit, type) {
         queue: ctx.name,
         grace,
         limit,
-        type,
+        // Handler reads `state`; sending `type` made the state filter a no-op.
+        state: type,
     });
     if (!response.ok)
         return [];
@@ -107,7 +108,8 @@ export async function promoteJobs(ctx, opts) {
     });
     if (!response.ok)
         return 0;
-    return (response.promoted ?? 0);
+    // Handler returns `count`; reading `promoted` always yielded 0.
+    return (response.count ?? 0);
 }
 /** Promote a single job */
 export async function promoteJob(ctx, id) {

package/dist/client/queue/queue.js

@@ -60,6 +60,7 @@ export class Queue {
                 this.tcpPool = getSharedPool({
                     host: connOpts.host,
                     port: connOpts.port,
+                    tls: connOpts.tls,
                     poolSize,
                     pingInterval: connOpts.pingInterval,
                     commandTimeout: connOpts.commandTimeout,
@@ -74,6 +75,7 @@ export class Queue {
                     host: connOpts.host ?? 'localhost',
                     port: connOpts.port ?? 6789,
                     token,
+                    tls: connOpts.tls,
                     poolSize,
                     pingInterval: connOpts.pingInterval,
                     commandTimeout: connOpts.commandTimeout,

package/dist/client/queue/scheduler.js

@@ -65,6 +65,9 @@ export async function upsertJobScheduler(ctx, schedulerId, repeatOpts, jobTempla
     const dedupFields = buildCronDedup(jobTemplate);
     const jobOptions = buildCronJobOptions(ctx.defaultJobOptions, jobTemplate);
     const cronName = toCronName(ctx, schedulerId);
+    // Priority of spawned jobs: carried on the top-level Cron field (the handler
+    // reads cmd.priority), which buildCronJobOptions does not cover.
+    const priority = jobTemplate?.opts?.priority ?? ctx.defaultJobOptions?.priority;
     if (ctx.embedded) {
         const manager = getSharedManager();
         manager.addCron({
@@ -73,6 +76,7 @@ export async function upsertJobScheduler(ctx, schedulerId, repeatOpts, jobTempla
             data,
             schedule: cronPattern,
             repeatEvery,
+            priority,
             timezone: repeatOpts.timezone ?? 'UTC',
             skipMissedOnRestart: repeatOpts.skipMissedOnRestart,
             immediately: repeatOpts.immediately,
@@ -94,6 +98,7 @@ export async function upsertJobScheduler(ctx, schedulerId, repeatOpts, jobTempla
         data,
         schedule: cronPattern,
         repeatEvery,
+        priority,
         timezone: repeatOpts.timezone,
         skipMissedOnRestart: repeatOpts.skipMissedOnRestart,
         immediately: repeatOpts.immediately,

package/dist/client/tcp/client.js

@@ -137,6 +137,7 @@ export class TcpClient extends EventEmitter {
         const { socket } = await createConnection({
             host: this.options.host,
             port: this.options.port,
+            tls: this.options.tls,
         }, this.options.connectTimeout, {
             onData: (frame) => {
                 this.handleData(frame);

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

@@ -2,7 +2,7 @@
  * TCP Connection Handler
  * Manages low-level socket connection and data handling (msgpack binary protocol)
  */
-import type { SocketWrapper, PendingCommand } from './types';
+import type { SocketWrapper, PendingCommand, ClientTlsOptions } from './types';
 /** Connection events */
 export interface ConnectionEvents {
     onData: (frame: Uint8Array) => void;
@@ -20,7 +20,14 @@ export interface ConnectionTarget {
     host?: string;
     /** TCP port */
     port?: number;
+    /** Enable TLS: true (system CAs) or per-connection TLS options */
+    tls?: boolean | ClientTlsOptions;
 }
+/**
+ * Map client TLS options to the `tls` value accepted by Bun.connect.
+ * Returns undefined when TLS is disabled (plaintext, the default).
+ */
+export declare function buildClientTls(tls: boolean | ClientTlsOptions | undefined): true | Record<string, unknown> | undefined;
 /**
  * Establish TCP connection to server
  */

package/dist/client/tcp/connection.js

@@ -3,6 +3,20 @@
  * Manages low-level socket connection and data handling (msgpack binary protocol)
  */
 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).
+ */
+export function buildClientTls(tls) {
+    if (!tls)
+        return undefined;
+    if (tls === true)
+        return true;
+    return {
+        ...(tls.rejectUnauthorized !== undefined && { rejectUnauthorized: tls.rejectUnauthorized }),
+        ...(tls.caFile !== undefined && { ca: Bun.file(tls.caFile) }),
+    };
+}
 /**
  * Establish TCP connection to server
  */
@@ -82,11 +96,23 @@ export async function createConnection(target, connectTimeout, events) {
                 }
             },
         };
-        // Connect via TCP
+        // Connect via TCP (optionally wrapped in TLS — protocol is unchanged)
+        const tlsValue = buildClientTls(target.tls);
         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) {

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

@@ -2,7 +2,7 @@
  * TCP Client Module
  * Re-exports all TCP client components
  */
-export type { ConnectionOptions, ConnectionHealth, PendingCommand, SocketWrapper } from './types';
+export type { ConnectionOptions, ConnectionHealth, PendingCommand, SocketWrapper, ClientTlsOptions, } from './types';
 export { DEFAULT_CONNECTION } from './types';
 export { HealthTracker, type HealthConfig } from './health';
 export { ReconnectManager, type ReconnectConfig } from './reconnect';

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

@@ -1,10 +1,12 @@
 /**
- * Shared TCP Client Instance
- * Singleton pattern for shared client management
+ * Shared TCP Client Instances
+ * One shared client per distinct connection target. Keyed by
+ * host/port/token/tls so callers with different configs (notably TLS vs
+ * plaintext to the same server) never receive each other's connection.
  */
 import type { ConnectionOptions } from './types';
 import { TcpClient } from './client';
-/** Get shared TCP client */
+/** Get shared TCP client for the given connection target */
 export declare function getSharedTcpClient(options?: Partial<ConnectionOptions>): TcpClient;
-/** Close shared client */
+/** Close all shared clients */
 export declare function closeSharedTcpClient(): void;

package/dist/client/tcp/shared.js

@@ -1,19 +1,35 @@
 /**
- * Shared TCP Client Instance
- * Singleton pattern for shared client management
+ * Shared TCP Client Instances
+ * One shared client per distinct connection target. Keyed by
+ * host/port/token/tls so callers with different configs (notably TLS vs
+ * plaintext to the same server) never receive each other's connection.
  */
 import { TcpClient } from './client';
-/** Shared client instance */
-let sharedClient = null;
-/** Get shared TCP client */
+/** Shared clients keyed by connection target */
+const sharedClients = new Map();
+/** Build the sharing key from the connection-identity options */
+function getClientKey(options) {
+    const host = options?.host ?? 'localhost';
+    const port = options?.port ?? 6789;
+    const token = options?.token ?? '';
+    const tokenHash = token ? String(Number(Bun.hash(token)) & 0xffff) : '0';
+    const tlsKey = options?.tls ? JSON.stringify(options.tls) : '0';
+    return `${host}:${port}:${tokenHash}:${tlsKey}`;
+}
+/** Get shared TCP client for the given connection target */
 export function getSharedTcpClient(options) {
-    sharedClient ??= new TcpClient(options);
-    return sharedClient;
+    const key = getClientKey(options);
+    let client = sharedClients.get(key);
+    if (!client) {
+        client = new TcpClient(options);
+        sharedClients.set(key, client);
+    }
+    return client;
 }
-/** Close shared client */
+/** Close all shared clients */
 export function closeSharedTcpClient() {
-    if (sharedClient) {
-        sharedClient.close();
-        sharedClient = null;
+    for (const client of sharedClients.values()) {
+        client.close();
     }
+    sharedClients.clear();
 }

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

@@ -2,6 +2,17 @@
  * 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 */
@@ -10,6 +21,8 @@ export interface ConnectionOptions {
     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) */

package/dist/client/tcp/types.js

@@ -7,6 +7,7 @@ export const DEFAULT_CONNECTION = {
     host: 'localhost',
     port: 6789,
     token: '',
+    tls: false,
     maxReconnectAttempts: Infinity,
     reconnectDelay: 100,
     maxReconnectDelay: 30000,