Method acquireConnection

src/node/runtime/sshConnectionPool.ts:196–346

(
    config: SSHConnectionConfig,
    timeoutMsOrOptions: number | AcquireConnectionOptions = DEFAULT_PROBE_TIMEOUT_MS
  )

    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(
            `SSH connection to ${config.host} is in backoff for ${remainingSecs}s. ` +
              `Last error: ${health.lastError ?? "unknown"}`
          );
        }

        const budgetMs = getRemainingWaitBudgetMs();
        if (budgetMs <= 0) {
          throw createWaitBudgetExceededError(health.lastError);
        }

        const waitMs = Math.min(remainingMs, budgetMs);
        options.onWait?.(waitMs);
        await sleep(waitMs, options.abortSignal);
        continue;
      }

      // Return immediately if known healthy and not stale.
      if (health?.status === "healthy") {