Class SSHConnectionPool

src/node/runtime/sshConnectionPool.ts:178–614

 * 3. Enforcing backoff after failures
 */
export class SSHConnectionPool {
  private health = new Map<string, ConnectionHealth>();
  private readyControlPaths = new Map<string, Set<string>>();
  private inflight = new Map<string, Promise<void>>();

  /**
   * Ensure connection is healthy before proceeding.
   *
   * By default, acquireConnection waits through backoff (bounded) so user-facing
   * actions don’t immediately fail during transient SSH outages.
   *
   * Callers can opt into fail-fast behavior by passing `{ maxWaitMs: 0 }`.
   */
  async acquireConnection(config: SSHConnectionConfig, timeoutMs?: number): Promise<void>;
  async acquireConnection(
    config: SSHConnectionConfig,
    options?: AcquireConnectionOptions
  ): Promise<void>;
  async acquireConnection(
    config: SSHConnectionConfig,
    timeoutMsOrOptions: number | AcquireConnectionOptions = DEFAULT_PROBE_TIMEOUT_MS
  ): Promise<void> {
    const options: AcquireConnectionOptions =
      typeof timeoutMsOrOptions === "number"
        ? { timeoutMs: timeoutMsOrOptions }
        : (timeoutMsOrOptions ?? {});

    const timeoutMs = options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
    const sleep = options.sleep ?? sleepWithAbort;

    const maxWaitMs = options.maxWaitMs ?? DEFAULT_SSH_MAX_WAIT_MS;
    const shouldWait = maxWaitMs > 0;

    const key = makeConnectionKey(config);
    const requestedControlPath = options.controlPath ?? getControlPath(config);
    const startTime = Date.now();
    const getRemainingWaitBudgetMs = (): number =>
      Math.max(0, maxWaitMs - (Date.now() - startTime));
    const createWaitBudgetExceededError = (lastError?: string): Error =>
      new Error(
        `SSH connection to ${config.host} did not become healthy within ${maxWaitMs}ms. ` +
          `Last error: ${lastError ?? "unknown"}`
      );

    while (true) {
      if (options.abortSignal?.aborted) {
        throw new Error(SSH_OPERATION_ABORTED_ERROR);
      }

      const health = this.health.get(key);

      // If in backoff: either fail fast or wait (bounded).
      if (health?.backoffUntil && health.backoffUntil > new Date()) {
        const remainingMs = health.backoffUntil.getTime() - Date.now();
        const remainingSecs = Math.ceil(remainingMs / 1000);

        if (!shouldWait) {
          throw new Error(