feat(send/frontend): handle 429 rate-limit responses gracefully (#1105)

When the backend returns HTTP 429, the app now reads the Retry-After hint,
waits that long (bounded to 10s), and retries the request once instead of
failing hard or retrying blindly. If it is still limited after the retry,
or there is no usable Retry-After, the call reports a distinct
rate_limited failure so callers can show a "please wait" message.

Pairs with the backend limits from the #1072 milestone.

Author: aaspinwall

packages/send/frontend/src/lib/api.ts

@@ -74,6 +74,44 @@ export function buildApiUrl(serverUrl: string, path: string): string {
   return url.toString();
 }
 
+// Upper bound on how long we will wait for a Retry-After before giving up on the
+// automatic retry. A server should never ask a browser to sit idle for minutes;
+// beyond this we surface the rate-limit to the caller instead of blocking.
+export const MAX_RETRY_AFTER_MS = 10_000;
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Parse an HTTP `Retry-After` header into milliseconds.
+ *
+ * Supports both forms the spec allows: a number of seconds (`"3"`) and an
+ * HTTP-date (`"Wed, 21 Oct 2026 07:28:00 GMT"`). Returns null when the header is
+ * absent or unparseable, and clamps negatives to 0 (a past date means "now").
+ */
+export function parseRetryAfterMs(
+  header: string | null | undefined
+): number | null {
+  if (!header) {
+    return null;
+  }
+  const trimmed = header.trim();
+
+  // delta-seconds form.
+  if (/^\d+$/.test(trimmed)) {
+    return Number(trimmed) * 1000;
+  }
+
+  // HTTP-date form.
+  const dateMs = Date.parse(trimmed);
+  if (!Number.isNaN(dateMs)) {
+    return Math.max(0, dateMs - Date.now());
+  }
+
+  return null;
+}
+
 export class ApiConnection {
   serverUrl: string;
 
@@ -246,6 +284,38 @@ export class ApiConnection {
       }
     }
 
+    // Rate limiting (429): the backend is asking us to slow down, not failing.
+    // Wait the server-suggested amount (Retry-After) and retry once, rather than
+    // hammering it or surfacing a hard error. This pairs with the backend limits
+    // added under the #1072 milestone.
+    if (resp.status === 429) {
+      const waitMs = parseRetryAfterMs(resp.headers?.get?.('retry-after'));
+      // Only back off for a sane, bounded wait. A missing/garbage or absurdly
+      // long Retry-After should not hang the request behind a multi-minute
+      // timer; in that case we skip the retry and report it to the caller.
+      if (waitMs !== null && waitMs <= MAX_RETRY_AFTER_MS) {
+        await delay(waitMs);
+        try {
+          resp = await fetch(url, opts);
+        } catch (error) {
+          options?.onFailure?.({ kind: 'network', status: null, error });
+          return null;
+        }
+      }
+
+      // Still limited after the single retry (or we chose not to wait): tell the
+      // caller explicitly so it can show a friendly "please wait" message rather
+      // than a generic failure.
+      if (resp.status === 429) {
+        options?.onFailure?.({
+          kind: 'rate_limited',
+          status: 429,
+          retryAfterMs: waitMs,
+        });
+        return null;
+      }
+    }
+
     if (!resp.ok) {
       // Surface the status/body for the caller's diagnostics before discarding
       // the response. Reading the body is safe here because we return null
@@ -281,7 +351,11 @@ export class ApiConnection {
  */
 export type ApiCallFailure =
   | { kind: 'network'; status: null; error: unknown }
-  | { kind: 'http'; status: number; statusText: string; body?: string };
+  | { kind: 'http'; status: number; statusText: string; body?: string }
+  // The request was rate-limited (HTTP 429). `retryAfterMs` is the wait the
+  // server suggested, if it sent a usable Retry-After (null otherwise). Callers
+  // can use it to show a "too many requests, please wait" message.
+  | { kind: 'rate_limited'; status: 429; retryAfterMs: number | null };
 
 type Options = {
   fullResponse?: boolean;

packages/send/frontend/src/test/lib/api.test.ts

@@ -8,6 +8,7 @@ import {
   ApiCallFailure,
   ApiConnection,
   buildApiUrl,
+  parseRetryAfterMs,
 } from '@send-frontend/lib/api';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
@@ -276,6 +277,128 @@ describe('ApiConnection.call — onFailure diagnostics', () => {
   });
 });
 
+describe('parseRetryAfterMs', () => {
+  it('parses delta-seconds into milliseconds', () => {
+    expect(parseRetryAfterMs('3')).toBe(3000);
+    expect(parseRetryAfterMs('0')).toBe(0);
+  });
+
+  it('parses an HTTP-date into a wait relative to now', () => {
+    const twoSecondsOut = new Date(Date.now() + 2000).toUTCString();
+    const ms = parseRetryAfterMs(twoSecondsOut);
+    // Allow a little slack for clock/rounding; UTCString drops sub-second parts.
+    expect(ms).toBeGreaterThanOrEqual(0);
+    expect(ms).toBeLessThanOrEqual(2000);
+  });
+
+  it('clamps a past date to 0', () => {
+    const past = new Date(Date.now() - 60_000).toUTCString();
+    expect(parseRetryAfterMs(past)).toBe(0);
+  });
+
+  it('returns null for missing or unparseable values', () => {
+    expect(parseRetryAfterMs(null)).toBeNull();
+    expect(parseRetryAfterMs(undefined)).toBeNull();
+    expect(parseRetryAfterMs('')).toBeNull();
+    expect(parseRetryAfterMs('soon')).toBeNull();
+  });
+});
+
+describe('ApiConnection.call — 429 rate limiting (#1105)', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('waits the Retry-After then retries once and returns the retry body', async () => {
+    let call = 0;
+    const fetchFn = mockFetch(() => {
+      call += 1;
+      if (call === 1) {
+        return {
+          ok: false,
+          status: 429,
+          headers: { get: (k: string) => (k === 'retry-after' ? '0' : null) },
+          json: async () => ({ limited: true }),
+        } as unknown as Response;
+      }
+      return {
+        ok: true,
+        status: 200,
+        headers: { get: () => null },
+        json: async () => ({ ok: true }),
+      } as unknown as Response;
+    });
+
+    const api = new ApiConnection(SERVER);
+    const result = await api.call('uploads', {}, 'POST');
+
+    expect(fetchFn).toHaveBeenCalledTimes(2); // retried once after backoff
+    expect(result).toEqual({ ok: true });
+  });
+
+  it('reports kind=rate_limited when still limited after the retry', async () => {
+    const fetchFn = mockFetch(
+      () =>
+        ({
+          ok: false,
+          status: 429,
+          headers: { get: (k: string) => (k === 'retry-after' ? '0' : null) },
+          json: async () => ({ limited: true }),
+        }) as unknown as Response
+    );
+
+    const api = new ApiConnection(SERVER);
+    let failure: ApiCallFailure | undefined;
+    const result = await api.call(
+      'uploads',
+      {},
+      'POST',
+      {},
+      { onFailure: (f) => (failure = f) }
+    );
+
+    expect(fetchFn).toHaveBeenCalledTimes(2); // original + one retry
+    expect(result).toBeNull();
+    expect(failure).toEqual({
+      kind: 'rate_limited',
+      status: 429,
+      retryAfterMs: 0,
+    });
+  });
+
+  it('does not retry when Retry-After is missing, and reports rate_limited', async () => {
+    const fetchFn = mockFetch(
+      () =>
+        ({
+          ok: false,
+          status: 429,
+          headers: { get: () => null },
+          json: async () => ({ limited: true }),
+        }) as unknown as Response
+    );
+
+    const api = new ApiConnection(SERVER);
+    let failure: ApiCallFailure | undefined;
+    const result = await api.call(
+      'uploads',
+      {},
+      'POST',
+      {},
+      { onFailure: (f) => (failure = f) }
+    );
+
+    // No usable Retry-After -> no automatic retry, just surface it.
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+    expect(result).toBeNull();
+    expect(failure).toEqual({
+      kind: 'rate_limited',
+      status: 429,
+      retryAfterMs: null,
+    });
+  });
+});
+
 describe('ApiConnection.call — x-logout session recovery (#960/#974)', () => {
   afterEach(() => {
     vi.unstubAllGlobals();