@yawlabs/ssh-mcp 0.16.0 → 0.17.0

package/dist/ops.d.ts

@@ -1,5 +1,5 @@
 import type { Client } from "ssh2";
-import type { ConnectionPool } from "./pool.js";
+import { type ConnectionPool } from "./pool.js";
 export declare function shellQuote(s: string): string;
 export interface MultiExecResult {
     host: string;

package/dist/pool.d.ts

@@ -4,14 +4,49 @@ export interface PoolOptions {
     /** Milliseconds before an idle connection is closed. Default: 60000 (60s) */
     idleTtlMs?: number;
     /**
-     * Maximum number of connections in the pool. Default: 100, overridable via the
+     * Maximum number of connections in the pool, counting dials still in flight.
+     * Default: 100, overridable via the
      * `SSH_MCP_MAX_POOL_SIZE` env var. When at capacity, the pool first tries to evict
-     * an idle entry; if every entry is in use, `acquire()` rejects with
-     * "Connection pool is full". Bump this for fan-out workloads against many distinct
-     * hosts (e.g. `ssh_multi_exec` across a large fleet).
+     * an idle entry; if no idle entry can be evicted (every slot is in use or dialing),
+     * `acquire()` rejects with a {@link PoolFullError} ("Connection pool is full") -- at once
+     * by default, or once `waitForCapacityMs` (see {@link AcquireOptions}) passes without winning a slot.
+     * Bump this for fan-out workloads against many distinct hosts (e.g. `ssh_multi_exec`
+     * across a large fleet, which runs at most this many hosts at once).
      */
     maxPoolSize?: number;
 }
+export interface AcquireOptions {
+    /**
+     * How long `acquire()` / `withConnection()` may wait for a slot when the pool is full,
+     * in milliseconds. Default 0: reject at once with a {@link PoolFullError}. With a budget,
+     * the caller parks (see `waitForCapacity`) and retries on every capacity signal until a
+     * slot is won or the budget is spent, then rejects with a {@link PoolFullError} whose
+     * message says "no slot became available to this call within <budget>ms". Only a capacity rejection is
+     * waited out; connect failures and a drained pool reject at once as before.
+     */
+    waitForCapacityMs?: number;
+}
+/** `code` of the error `acquire()` throws when no slot is free. Match on this, not on the message. */
+export declare const POOL_FULL_ERROR_CODE = "ERR_SSH_MCP_POOL_FULL";
+/**
+ * Thrown by `acquire()` when a new connection is needed and no slot is free: every slot is
+ * held by an in-use entry or an in-flight dial, and no idle entry can be evicted. Distinct
+ * from connect and exec failures so a caller that can wait (see `waitForCapacity`) retries
+ * only on this. `waitedMs` is set when the caller asked to wait and the budget ran out; the
+ * message then carries the "no slot became available to this call within <n>ms" suffix and a
+ * remedy sentence -- appended here, once, so no caller has to add it.
+ */
+export declare class PoolFullError extends Error {
+    readonly code = "ERR_SSH_MCP_POOL_FULL";
+    readonly maxPoolSize: number;
+    readonly waitedMs?: number;
+    constructor(maxPoolSize: number, waitedMs?: number);
+}
+/**
+ * True for the pool's capacity rejection. Checks `code` rather than `instanceof`, so it still
+ * holds when two copies of this module are loaded (the CLI and library bundles are separate).
+ */
+export declare function isPoolFullError(err: unknown): err is PoolFullError;
 export declare class ConnectionPool {
     private entries;
     private pending;
@@ -19,12 +54,46 @@ export declare class ConnectionPool {
     private maxPoolSize;
     private _connectCount;
     private drained;
+    private capacityWaiters;
     constructor(options?: PoolOptions);
-    acquire(config: SSHConfig): Promise<Client>;
+    /**
+     * Checks out a connection for `config`, dialing one if needed. Fails fast on a full pool
+     * unless `options.waitForCapacityMs` is set, in which case the caller parks and retries on
+     * every capacity signal until it wins a slot or the budget is spent. The wait is bounded,
+     * never a reservation: a woken caller can lose the slot to another and simply parks again
+     * for whatever budget is left. The final rejection carries the budget in its message.
+     */
+    acquire(config: SSHConfig, options?: AcquireOptions): Promise<Client>;
+    private acquireNow;
     release(client: Client): void;
-    withConnection<T>(config: SSHConfig, fn: (client: Client) => Promise<T>): Promise<T>;
+    /** `acquire()` + `fn` + `release()`, with the same optional bounded wait for a slot. */
+    withConnection<T>(config: SSHConfig, fn: (client: Client) => Promise<T>, options?: AcquireOptions): Promise<T>;
     drain(): void;
+    /**
+     * Parks until the pool's capacity may have changed, for a caller whose `acquire()` just
+     * rejected with a {@link PoolFullError} and that would rather wait than fail. This is the
+     * primitive behind `acquire()`'s `waitForCapacityMs` option; a bare `acquire()` never waits.
+     *
+     * Resolves `true` when a slot may be free (woken by a release, an entry closing or expiring,
+     * a failed dial, or `drain()`), or at once if a new host would fit right now or the pool is
+     * already drained. Resolves `false` after `timeoutMs` with nothing having changed. Never
+     * rejects. A `true` is a hint, not a reservation: another caller can take the slot first,
+     * so retry `acquire()` and wait again on another `PoolFullError`. The timer is cleared on
+     * wake and unref'd, so a parked caller never holds the process open.
+     *
+     * Aborting `signal` ends the park early with `false`, as if the timer had run out; an
+     * already-aborted signal resolves `false` without parking, unless the pool is drained or a
+     * new host would fit right now. A wake that lands first still resolves `true`. A caller that
+     * gives up on its own (`ssh_multi_exec` declaring the call starved) aborts rather than racing
+     * this promise against another: the race would add a promise hop to every wake.
+     */
+    waitForCapacity(timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
+    private hasCapacity;
+    private findEvictable;
+    private notifyCapacity;
     get size(): number;
+    /** The connection cap (`maxPoolSize`), counting pooled entries plus in-flight dials. */
+    get maxSize(): number;
     get stats(): {
         active: number;
         idle: number;

package/dist/server.d.ts

@@ -10,8 +10,8 @@ export type { FindOptions, MultiExecHost, MultiExecResult, ServiceStatus } from
 export { find, multiExec, serviceStatus, tail } from "./ops.js";
 export type { PolicyContext } from "./policy.js";
 export { enforcePolicy, isPolicyConfigured } from "./policy.js";
-export type { PoolOptions } from "./pool.js";
-export { ConnectionPool } from "./pool.js";
+export type { AcquireOptions, PoolOptions } from "./pool.js";
+export { ConnectionPool, isPoolFullError, POOL_FULL_ERROR_CODE, PoolFullError } from "./pool.js";
 export type { ExecResult, FileStats, HostKeyRejection, HostKeyRejectionReason, ResolvedConfig, SSHConfig, } from "./ssh.js";
 export { connect, connectRaw, connectWithProxy, deleteFile, downloadFile, exec, formatDiagnostics, listDir, makeDir, readFile, readKnownHostsKeys, resolveConfig, statFile, uploadFile, writeFile, } from "./ssh.js";
 export { registerTools } from "./tools.js";