linumiq_net-web_app/lib/admin/retry.ts

/**
 * Retry helper for GoTrue admin reads (`auth.admin.listUsers` /
 * `auth.admin.getUserById`).
 *
 * Under a rapid burst of admin mutations (bulk ban/unban/delete) immediately
 * followed by the auto list-refresh, GoTrue's admin endpoints intermittently
 * return an EMPTY or TRUNCATED HTTP body. supabase-js then fails to parse the
 * response and throws `Unexpected end of JSON input` (or returns an
 * empty/transient `error`). The underlying request actually succeeded a moment
 * later, so a small bounded retry turns these flaky failures into reliable
 * reads without changing happy-path behaviour.
 *
 * IMPORTANT: only TRANSIENT failures are retried. Legitimate not-found (404) and
 * validation (4xx) errors are returned immediately so genuine failures still
 * surface as proper 4xx/5xx responses upstream.
 */

// Up to 3 attempts total (1 initial + 2 retries). Delays are applied BEFORE the
// 2nd and 3rd attempts respectively, so worst-case added latency is ~350ms —
// kept well under a second to keep the admin surface snappy.
const MAX_ATTEMPTS = 3;
const RETRY_DELAYS_MS = [100, 250];

/** Loose shape that both `AuthError` and `PostgrestError` satisfy. */
type MaybeError =
  | { message?: string | null; status?: number | null; code?: string | number | null }
  | null
  | undefined;

export type RetryOptions = {
  /** Total attempts including the first. Defaults to {@link MAX_ATTEMPTS}. */
  attempts?: number;
  /** Backoff delays (ms) applied before each retry. Defaults to {@link RETRY_DELAYS_MS}. */
  delaysMs?: number[];
};

function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

/** True when a thrown/parse error looks like an empty/truncated-body failure. */
function isTransientMessage(message: string): boolean {
  const m = message.toLowerCase();
  return (
    m.includes('unexpected end of json input') ||
    m.includes('unexpected end of input') ||
    m.includes('unexpected end of data') ||
    // Some runtimes phrase the empty-body parse failure differently.
    (m.includes('json') && m.includes('parse') && m.includes('unexpected')) ||
    // Low-level network blips that also warrant a quick retry.
    m.includes('fetch failed') ||
    m.includes('network') ||
    m.includes('econnreset') ||
    m.includes('socket hang up') ||
    m.includes('terminated')
  );
}

/** True when a thrown value is a transient, retryable failure. */
function isTransientThrow(err: unknown): boolean {
  if (err instanceof Error) return isTransientMessage(err.message);
  if (typeof err === 'string') return isTransientMessage(err);
  return false;
}

/**
 * True when a returned supabase-js `error` is transient. We retry on 5xx and on
 * empty/parse-style messages, but NEVER on legitimate not-found/validation
 * (e.g. a 404 with a real "User not found" message).
 */
function isTransientError(error: MaybeError): boolean {
  if (!error) return false;
  const status = typeof error.status === 'number' ? error.status : undefined;
  // Explicit client/validation/not-found statuses are genuine — do not retry.
  if (status !== undefined && status >= 400 && status < 500) return false;
  if (status !== undefined && status >= 500) return true;
  const message = typeof error.message === 'string' ? error.message : '';
  if (message && isTransientMessage(message)) return true;
  // An error object with neither a usable status nor message is treated as an
  // opaque/empty transient failure worth one more try.
  if (!status && !message) return true;
  return false;
}

/**
 * Await an async supabase-js admin call that returns `{ data, error }` (or that
 * may throw), retrying only on transient empty-body / network failures.
 *
 * Returns the successful (or genuinely-failed, non-transient) result. After
 * exhausting all attempts it returns the last `{ data, error }` result or
 * re-throws the last thrown error, so persistent failures still surface.
 */
export async function withAdminRetry<R extends { error: MaybeError }>(
  fn: () => Promise<R>,
  opts?: RetryOptions,
): Promise<R> {
  const attempts = opts?.attempts ?? MAX_ATTEMPTS;
  const delays = opts?.delaysMs ?? RETRY_DELAYS_MS;

  let lastResult: R | undefined;
  let lastThrown: unknown;
  let threw = false;

  for (let attempt = 1; attempt <= attempts; attempt++) {
    try {
      const result = await fn();
      threw = false;
      lastResult = result;
      // Success, or a genuine (non-transient) error — return as-is.
      if (!isTransientError(result.error)) return result;
    } catch (err) {
      // A non-transient throw is a real failure: surface it immediately.
      if (!isTransientThrow(err)) throw err;
      threw = true;
      lastThrown = err;
    }

    if (attempt < attempts) {
      const delay = delays[attempt - 1] ?? delays[delays.length - 1] ?? 0;
      if (delay > 0) await sleep(delay);
    }
  }

  // Exhausted all attempts on transient failures: surface the last outcome so
  // the caller still sees a real error rather than a masked success.
  if (threw) throw lastThrown;
  return lastResult as R;
}

/**
 * Map over `items` running at most `concurrency` async tasks at a time, while
 * preserving result order.
 *
 * Firing every GoTrue admin lookup at once (e.g. one `getUserById` per tunnel
 * row) can self-inflict an upstream throttle: the proxy truncates the tail of a
 * large concurrent burst, producing the very empty-body responses we retry on —
 * and because the retries fire back into the same saturated window, a few rows
 * can still fail. Bounding the concurrency keeps each lookup inside the
 * throttle's allowance so {@link withAdminRetry} reliably resolves every row.
 */
export async function mapWithConcurrency<T, R>(
  items: readonly T[],
  concurrency: number,
  task: (item: T, index: number) => Promise<R>,
): Promise<R[]> {
  const results = new Array<R>(items.length);
  const limit = Math.max(1, Math.min(concurrency, items.length || 1));
  let next = 0;
  async function worker(): Promise<void> {
    for (;;) {
      const i = next++;
      if (i >= items.length) return;
      results[i] = await task(items[i], i);
    }
  }
  await Promise.all(Array.from({ length: limit }, () => worker()));
  return results;
}