@paradigma-inc/flywheel 0.2.28 → 0.2.31

package/src/setup-auth.mjs

@@ -7,11 +7,25 @@ import { isatty } from "node:tty";
 import { setTimeout as delay } from "node:timers/promises";
 
 import { SetupInputUsageError } from "./setup/mode.mjs";
+import {
+  isRetryableNetworkError,
+  isRetryableStatus,
+  parseRetryAfterMs,
+  withRetry,
+} from "./runtime/vendor/flywheel-cli-dist/http/retry.js";
 
 const DEFAULT_AUTH_TIMEOUT_MS = 5 * 60 * 1000;
 const MIN_POLL_DELAY_MS = 1000;
 const MAX_POLL_DELAY_MS = 10_000;
 const SETUP_DEVICE_API_PREFIX = "/api/v1/auth/mcp-api-keys/setup-device";
+// FLY-1112: the setup-device start request is retried through the bundled
+// helper. One logical request (body, idempotency key, request ID) is reused
+// across at most three attempts; each attempt gets a fresh signal of at most
+// 15s, and the whole recovery sequence is bounded by 49s so a temporary
+// routing failure fails fast instead of pinning the spinner for two minutes.
+const START_ATTEMPT_TIMEOUT_MS = 15_000;
+const START_RECOVERY_BUDGET_MS = 49_000;
+const START_MAX_ATTEMPTS = 3;
 const readDescriptor = promisify(readFd);
 
 async function readStdin(fd, buffer, offset, length, position) {
@@ -211,77 +225,246 @@ export function normalizeSetupAuthMode(value) {
 //   return { apiKey: key };
 // }
 
+export function formatStartRetryMessage({ nextAttempt, maxAttempts }) {
+  return `Flywheel is taking longer than expected; retrying (${nextAttempt} of ${maxAttempts})...`;
+}
+
+// A retryable-class start failure: local attempt timeout, recognized
+// temporary network error, or accepted HTTP status. Carries the structured
+// summary used for progress callbacks and the exhausted-attempts error, plus
+// the original error so non-retried failures retain their existing detail.
+class StartAttemptFailure extends Error {
+  constructor(failure, cause, { retryAfter = null, returnAsIs = false } = {}) {
+    super(cause.message);
+    this.failure = failure;
+    this.cause = cause;
+    this.retryAfter = retryAfter;
+    this.returnAsIs = returnAsIs;
+  }
+}
+
+// Internal sentinels: the sleep gate raises these when the next attempt can
+// no longer fit inside a deadline; the outer catch maps them to the exact
+// public error messages.
+class StartRecoveryExhausted extends Error {
+  constructor(failure) {
+    super("start recovery budget exhausted");
+    this.failure = failure;
+  }
+}
+class StartAuthorizationDeadline extends Error {}
+
+function startFailureDescription(failure) {
+  return failure.kind === "http" ? `HTTP ${failure.status}` : failure.kind;
+}
+
 async function startSetupDeviceSession({
   baseUrl,
   keyName,
   verificationBaseUrl,
-  remainingMs,
+  authorizationDeadlineMs,
+  now = Date.now,
+  fetchFn = fetch,
+  sleep = defaultSleep,
+  random = Math.random,
+  createTimeoutSignal = AbortSignal.timeout,
+  onStartRetry,
 }) {
   const startUrl = new URL(`${SETUP_DEVICE_API_PREFIX}/start`, baseUrl);
-  const startTimeoutSignal = AbortSignal.timeout(remainingMs);
-  let response;
-  let payload;
+  // One logical request: serialized body, idempotency key, and request ID are
+  // created once before attempt 1 and reused unchanged on every attempt so the
+  // server can replay the first unexpired session instead of duplicating it.
+  const body = JSON.stringify({
+    name: keyName,
+    verification_base_url: verificationBaseUrl,
+  });
+  const idempotencyKey = `setup-device-start:${crypto.randomUUID()}`;
+  const requestId = crypto.randomUUID();
+  const recoveryDeadlineMs = Math.min(
+    authorizationDeadlineMs,
+    now() + START_RECOVERY_BUDGET_MS,
+  );
+  // Tracks the most recently classified retryable failure so a budget
+  // guard reached at the top of a later attempt (see attemptStart below)
+  // can still attribute exhaustion to the retry sequence instead of the
+  // generic authorization timeout, matching gatedSleep's own attribution.
+  let lastFailure = null;
+
+  const attemptStart = async () => {
+    const signalBudgetMs = Math.min(
+      START_ATTEMPT_TIMEOUT_MS,
+      authorizationDeadlineMs - now(),
+      recoveryDeadlineMs - now(),
+    );
+    if (signalBudgetMs <= 0) {
+      // Ordinarily unreachable: the caller guards the authorization deadline
+      // before the first attempt, and gatedSleep already re-checks this same
+      // budget before scheduling any later attempt's sleep. Kept as a
+      // defensive fallback for real-world sleep/timer overrun (the actual
+      // wait exceeding the requested delay) between gatedSleep's check and
+      // this attempt actually starting.
+      if (recoveryDeadlineMs < authorizationDeadlineMs && lastFailure) {
+        throw new StartRecoveryExhausted(lastFailure);
+      }
+      throw new StartAuthorizationDeadline();
+    }
+    const signal = createTimeoutSignal(signalBudgetMs);
+    let response;
+    let payload;
+    try {
+      response = await fetchFn(startUrl, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "Idempotency-Key": idempotencyKey,
+          "X-Flywheel-Surface": "cli",
+          "X-Flywheel-Request-Id": requestId,
+          "X-Request-ID": requestId,
+        },
+        body,
+        signal,
+      });
+      payload = await parseJsonResponse(response, { signal });
+    } catch (error) {
+      // Only an abort of this attempt's own signal is a local timeout.
+      if (signal.aborted) {
+        throw new StartAttemptFailure({ kind: "timeout" }, error);
+      }
+      if (isRetryableNetworkError(error)) {
+        throw new StartAttemptFailure({ kind: "network" }, error);
+      }
+      throw error;
+    }
+    if (!response.ok) {
+      const detail = resolveErrorMessage(payload, "Failed to start setup device flow.");
+      throw new StartAttemptFailure(
+        { kind: "http", status: response.status },
+        new Error(detail),
+        { retryAfter: response.headers?.get?.("retry-after") ?? null },
+      );
+    }
+
+    const deviceCode = nonEmptyString(payload.device_code);
+    const userCode = nonEmptyString(payload.user_code);
+    const verificationUri = nonEmptyString(payload.verification_uri);
+    const verificationUriComplete = nonEmptyString(payload.verification_uri_complete);
+    const pollIntervalSeconds = Number(payload.poll_interval_seconds);
+    const expiresInSeconds = Number(payload.expires_in_seconds);
+
+    if (!deviceCode || !userCode || !verificationUri || !verificationUriComplete) {
+      throw new Error("Setup device session response missing required fields.");
+    }
+    if (
+      !Number.isFinite(pollIntervalSeconds) ||
+      pollIntervalSeconds <= 0 ||
+      !Number.isFinite(expiresInSeconds) ||
+      expiresInSeconds <= 0
+    ) {
+      throw new Error("Setup device session response contained invalid timing values.");
+    }
+
+    return {
+      deviceCode,
+      userCode,
+      verificationUri,
+      verificationUriComplete,
+      pollIntervalSeconds: Math.floor(pollIntervalSeconds),
+      expiresInSeconds: Math.floor(expiresInSeconds),
+    };
+  };
+
+  let pendingRetry = null;
+  // A retry is scheduled only when the delay plus a full 15s next attempt still
+  // fits inside the recovery budget. The gate runs before the progress
+  // callback so "retrying" is announced only when another attempt will happen.
+  const gatedSleep = async (delayMs) => {
+    const { nextAttempt, failure } = pendingRetry;
+    pendingRetry = null;
+    if (now() + delayMs + START_ATTEMPT_TIMEOUT_MS > recoveryDeadlineMs) {
+      if (recoveryDeadlineMs === authorizationDeadlineMs) {
+        throw new StartAuthorizationDeadline();
+      }
+      throw new StartRecoveryExhausted(failure);
+    }
+    try {
+      onStartRetry?.({
+        nextAttempt,
+        maxAttempts: START_MAX_ATTEMPTS,
+        delayMs,
+        requestId,
+        failure,
+      });
+    } catch {
+      // Presentation is best-effort and must not change retry behavior.
+    }
+    await sleep(delayMs);
+  };
+
   try {
-    response = await fetch(startUrl, {
-      method: "POST",
-      headers: {
-        "content-type": "application/json",
-        "Idempotency-Key": `setup-device-start:${crypto.randomUUID()}`,
+    return await withRetry(attemptStart, {
+      maxAttempts: START_MAX_ATTEMPTS,
+      sleep: gatedSleep,
+      random,
+      shouldRetry: (error, attempt) => {
+        if (!(error instanceof StartAttemptFailure) || error.returnAsIs) {
+          return { retry: false };
+        }
+        const { failure } = error;
+        if (failure.kind === "http") {
+          if (!isRetryableStatus(failure.status)) {
+            return { retry: false };
+          }
+          const retryAfterMs = parseRetryAfterMs(error.retryAfter);
+          if (retryAfterMs !== null) {
+            // A valid Retry-After replaces the helper's delay only when it
+            // leaves room for the remaining 15s attempts; otherwise the
+            // current HTTP failure is returned unchanged.
+            if (now() + retryAfterMs + START_ATTEMPT_TIMEOUT_MS <= recoveryDeadlineMs) {
+              pendingRetry = { nextAttempt: attempt + 1, failure };
+              lastFailure = failure;
+              return { retry: true, delayMs: retryAfterMs };
+            }
+            error.returnAsIs = true;
+            return { retry: false };
+          }
+        }
+        pendingRetry = { nextAttempt: attempt + 1, failure };
+        lastFailure = failure;
+        return { retry: true };
       },
-      body: JSON.stringify({
-        name: keyName,
-        verification_base_url: verificationBaseUrl,
-      }),
-      signal: startTimeoutSignal,
     });
-    payload = await parseJsonResponse(response, { signal: startTimeoutSignal });
   } catch (error) {
-    if (startTimeoutSignal.aborted) {
+    if (error instanceof StartAuthorizationDeadline) {
       throw new Error("Timed out waiting for device authorization.");
     }
+    if (error instanceof StartRecoveryExhausted) {
+      throw new Error(
+        `Failed to start device authorization after ${START_MAX_ATTEMPTS} attempts (last failure: ${startFailureDescription(error.failure)}; request ID: ${requestId}). Run the same setup command again.`,
+      );
+    }
+    if (error instanceof StartAttemptFailure) {
+      const retryableClass =
+        error.failure.kind !== "http" || isRetryableStatus(error.failure.status);
+      if (retryableClass && !error.returnAsIs) {
+        // A retryable failure escaping withRetry means the final attempt
+        // failed; report the exhausted sequence with request correlation.
+        throw new Error(
+          `Failed to start device authorization after ${START_MAX_ATTEMPTS} attempts (last failure: ${startFailureDescription(error.failure)}; request ID: ${requestId}). Run the same setup command again.`,
+        );
+      }
+      throw error.cause;
+    }
     throw error;
   }
-  if (!response.ok) {
-    const detail = resolveErrorMessage(payload, "Failed to start setup device flow.");
-    throw new Error(detail);
-  }
-
-  const deviceCode = nonEmptyString(payload.device_code);
-  const userCode = nonEmptyString(payload.user_code);
-  const verificationUri = nonEmptyString(payload.verification_uri);
-  const verificationUriComplete = nonEmptyString(payload.verification_uri_complete);
-  const pollIntervalSeconds = Number(payload.poll_interval_seconds);
-  const expiresInSeconds = Number(payload.expires_in_seconds);
-
-  if (!deviceCode || !userCode || !verificationUri || !verificationUriComplete) {
-    throw new Error("Setup device session response missing required fields.");
-  }
-  if (
-    !Number.isFinite(pollIntervalSeconds) ||
-    pollIntervalSeconds <= 0 ||
-    !Number.isFinite(expiresInSeconds) ||
-    expiresInSeconds <= 0
-  ) {
-    throw new Error("Setup device session response contained invalid timing values.");
-  }
-
-  return {
-    deviceCode,
-    userCode,
-    verificationUri,
-    verificationUriComplete,
-    pollIntervalSeconds: Math.floor(pollIntervalSeconds),
-    expiresInSeconds: Math.floor(expiresInSeconds),
-  };
 }
 
-async function pollSetupDeviceSession({ baseUrl, userCode, deviceCode }) {
+async function pollSetupDeviceSession({ baseUrl, userCode, deviceCode, fetchFn = fetch, now = Date.now }) {
   const pollUrl = new URL(`${SETUP_DEVICE_API_PREFIX}/poll`, baseUrl);
-  const response = await fetch(pollUrl, {
+  const response = await fetchFn(pollUrl, {
     method: "POST",
     headers: {
       "content-type": "application/json",
-      "Idempotency-Key": `setup-device-poll:${deviceCode}:${Date.now()}`,
+      "Idempotency-Key": `setup-device-poll:${deviceCode}:${now()}`,
     },
     body: JSON.stringify({
       user_code: userCode,
@@ -377,6 +560,12 @@ export async function resolveSetupApiKey({
   acquireDeviceFlow = acquireApiKeyViaDeviceFlow,
   acquireBrowserBridge = acquireApiKeyViaBrowserBridge,
   keyNameFactory = () => `flywheel-setup-${crypto.randomBytes(3).toString("hex")}`,
+  fetchFn,
+  now,
+  sleep,
+  random,
+  createTimeoutSignal,
+  onStartRetry,
 } = {}) {
   // Check the value, not just property presence: callers like runCliSetupMode
   // always forward `{apiKey, authMode}` to share one helper shape, so the
@@ -410,6 +599,12 @@ export async function resolveSetupApiKey({
         baseUrl,
         keyName,
         verificationBaseUrl: baseUrl,
+        fetchFn,
+        now,
+        sleep,
+        random,
+        createTimeoutSignal,
+        onStartRetry,
       })
       : await acquireBrowserBridge({
         baseUrl,
@@ -594,17 +789,28 @@ export async function acquireApiKeyViaDeviceFlow({
   timeoutMs = DEFAULT_AUTH_TIMEOUT_MS,
   openUrl = openUrlInBrowser,
   sleep = defaultSleep,
+  fetchFn = fetch,
+  now = Date.now,
+  random = Math.random,
+  createTimeoutSignal = AbortSignal.timeout,
+  onStartRetry,
 }) {
-  const startedAt = Date.now();
-  const remainingMs = timeoutMs - (Date.now() - startedAt);
-  if (remainingMs <= 0) {
+  const startedAt = now();
+  const authorizationDeadlineMs = startedAt + timeoutMs;
+  if (authorizationDeadlineMs - now() <= 0) {
     throw new Error("Timed out waiting for device authorization.");
   }
   const session = await startSetupDeviceSession({
     baseUrl,
     keyName,
     verificationBaseUrl,
-    remainingMs,
+    authorizationDeadlineMs,
+    now,
+    fetchFn,
+    sleep,
+    random,
+    createTimeoutSignal,
+    onStartRetry,
   });
 
   console.log("Opening browser for Flywheel device authorization...");
@@ -617,12 +823,14 @@ export async function acquireApiKeyViaDeviceFlow({
   launchBrowser(openUrl, session.verificationUriComplete);
 
   let attempt = 0;
-  while (Date.now() - startedAt < timeoutMs) {
+  while (now() - startedAt < timeoutMs) {
     // eslint-disable-next-line no-await-in-loop
     const pollResult = await pollSetupDeviceSession({
       baseUrl,
       userCode: session.userCode,
       deviceCode: session.deviceCode,
+      fetchFn,
+      now,
     });
     if (pollResult.status === "approved") {
       return { apiKey: pollResult.apiKey };