Making Rork App API Calls Survive Failure — Timeouts, Exponential Backoff, and Circuit Breakers That Actually Hold

interface RetryOptions {
  maxRetries: number;
  baseDelayMs: number;
  maxDelayMs: number;
  jitter: number; // 0..1
  retryableStatus: number[];
}
 
const DEFAULT_RETRY: RetryOptions = {
  maxRetries: 3,
  baseDelayMs: 500,
  maxDelayMs: 15000,
  jitter: 0.3,
  retryableStatus: [408, 429, 500, 502, 503, 504],
};
 
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
export async function withRetry<T>(
  fn: () => Promise<T>,
  options: Partial<RetryOptions> = {},
): Promise<T> {
  const o = { ...DEFAULT_RETRY, ...options };
  let lastError: unknown;
 
  for (let attempt = 0; attempt <= o.maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      lastError = err;
 
      // Throw non-retryable statuses back immediately
      if (err instanceof ApiError && !o.retryableStatus.includes(err.statusCode)) {
        throw err;
      }
      if (attempt === o.maxRetries) break;
 
      // Honor Retry-After on 429, otherwise exponential backoff
      const retryAfter =
        err instanceof ApiError && err.statusCode === 429
          ? readRetryAfter(err)
          : undefined;
      const backoff = Math.min(o.baseDelayMs * 2 ** attempt, o.maxDelayMs);
      const jittered = backoff * (1 + o.jitter * (Math.random() * 2 - 1));
      const delay = retryAfter ?? Math.max(0, jittered);
 
      await sleep(delay);
    }
  }
  throw lastError ?? new Error("retry exhausted");
}
 
function readRetryAfter(err: ApiError): number | undefined {
  const header = (err.body as { retryAfter?: number })?.retryAfter;
  return typeof header === "number" ? header * 1000 : undefined;
}

type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
 
interface BreakerOptions {
  failureThreshold: number; // consecutive failures to OPEN
  recoveryMs: number;       // how long to stay OPEN
  successThreshold: number; // consecutive successes in HALF_OPEN to CLOSE
}
 
export class CircuitOpenError extends Error {
  constructor(public readonly retryInMs: number) {
    super(`circuit open, retry in ${Math.ceil(retryInMs / 1000)}s`);
    this.name = "CircuitOpenError";
  }
}
 
export class CircuitBreaker {
  private state: CircuitState = "CLOSED";
  private failures = 0;
  private successes = 0;
  private openedAt = 0;
 
  constructor(private readonly o: BreakerOptions) {}
 
  async execute<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === "OPEN") {
      const elapsed = Date.now() - this.openedAt;
      if (elapsed < this.o.recoveryMs) {
        throw new CircuitOpenError(this.o.recoveryMs - elapsed);
      }
      this.state = "HALF_OPEN";
      this.successes = 0;
    }
 
    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (err) {
      this.onFailure();
      throw err;
    }
  }
 
  private onSuccess() {
    if (this.state === "HALF_OPEN") {
      if (++this.successes >= this.o.successThreshold) this.reset();
    } else {
      this.failures = 0;
    }
  }
 
  private onFailure() {
    // A failure while probing snaps straight back to OPEN
    if (this.state === "HALF_OPEN") {
      this.trip();
      return;
    }
    if (++this.failures >= this.o.failureThreshold) this.trip();
  }
 
  private trip() {
    this.state = "OPEN";
    this.openedAt = Date.now();
    this.successes = 0;
  }
 
  private reset() {
    this.state = "CLOSED";
    this.failures = 0;
    this.successes = 0;
  }
 
  snapshot(): { state: CircuitState; failures: number } {
    return { state: this.state, failures: this.failures };
  }
}

interface ClientOptions {
  baseUrl: string;
  defaultTimeoutMs: number;
  breaker: BreakerOptions;
  retry?: Partial<RetryOptions>;
}
 
export class ResilientApiClient {
  private breakers = new Map<string, CircuitBreaker>();
 
  constructor(private readonly o: ClientOptions) {}
 
  private breakerFor(key: string): CircuitBreaker {
    let b = this.breakers.get(key);
    if (!b) {
      b = new CircuitBreaker(this.o.breaker);
      this.breakers.set(key, b);
    }
    return b;
  }
 
  async request<T>(
    path: string,
    init: Omit<TimedFetchOptions, "timeoutMs"> & { timeoutMs?: number } = {},
  ): Promise<T> {
    const url = `${this.o.baseUrl}${path}`;
    const timeoutMs = init.timeoutMs ?? this.o.defaultTimeoutMs;
    // Use the first path segment as the breaker key (/users/123 -> users)
    const key = path.split("/").filter(Boolean)[0] ?? path;
 
    // Order: Breaker -> Retry -> Timeout (lower layers nested inside)
    return this.breakerFor(key).execute(() =>
      withRetry(
        () => fetchWithTimeout(url, { ...init, timeoutMs }).then((r) => r.json() as Promise<T>),
        this.o.retry,
      ),
    );
  }
 
  states(): Record<string, ReturnType<CircuitBreaker["snapshot"]>> {
    const out: Record<string, ReturnType<CircuitBreaker["snapshot"]>> = {};
    this.breakers.forEach((b, key) => (out[key] = b.snapshot()));
    return out;
  }
}
 
// One shared instance for the whole app
export const apiClient = new ResilientApiClient({
  baseUrl: "https://api.yourapp.com",
  defaultTimeoutMs: 8000,
  breaker: { failureThreshold: 5, recoveryMs: 30000, successThreshold: 2 },
  retry: { maxRetries: 3, baseDelayMs: 500, maxDelayMs: 15000 },
});

import { useQuery } from "@tanstack/react-query";
 
export function useUser(userId: string) {
  return useQuery({
    queryKey: ["user", userId],
    queryFn: () => apiClient.request<User>(`/users/${userId}`),
    retry: (count, error) => {
      // Don't retry on the query side while the circuit is open
      if (error instanceof CircuitOpenError) return false;
      return count < 1;
    },
    staleTime: 5 * 60 * 1000,
    gcTime: 30 * 60 * 1000,
  });
}

// Thin wrapper that only reports transitions into Open
function reportIfOpened(prev: CircuitState, next: CircuitState, key: string) {
  if (prev !== "OPEN" && next === "OPEN") {
    // e.g. Sentry.captureMessage(`circuit opened: ${key}`, "warning")
    console.warn(`[circuit] ${key} opened`);
  }
}