Retry com backoff, jitter e circuit breaker em TypeScript

export type Veredito = { repetir: boolean; esperarMs?: number };

const STATUS_REPETIVEL = new Set([408, 425, 429, 500, 502, 503, 504]);

export function classificarResposta(res: Response): Veredito {
  if (res.ok) return { repetir: false };
  if (!STATUS_REPETIVEL.has(res.status)) return { repetir: false };

  // Quando o serviço diz quando voltar, obedecer é melhor que adivinhar.
  const retryAfter = res.headers.get('retry-after');
  if (retryAfter) {
    const segundos = Number(retryAfter);
    const esperarMs = Number.isFinite(segundos)
      ? segundos * 1000
      : Math.max(0, new Date(retryAfter).getTime() - Date.now());
    return { repetir: true, esperarMs };
  }

  return { repetir: true };
}

export function classificarErro(err: unknown): Veredito {
  // AbortError vindo do nosso próprio prazo não deve virar nova tentativa.
  if (err instanceof DOMException && err.name === 'AbortError') {
    return { repetir: false };
  }
  // Falha de rede: o fetch rejeita com TypeError.
  return { repetir: err instanceof TypeError };
}

/**
 * Full jitter: sorteia entre zero e o teto exponencial.
 * Distribui as tentativas em vez de concentrá-las num instante.
 */
export function calcularEspera(tentativa: number, baseMs = 300, tetoMs = 20_000) {
  const teto = Math.min(tetoMs, baseMs * 2 ** tentativa);
  return Math.random() * teto;
}

export const dormir = (ms: number, signal?: AbortSignal) =>
  new Promise<void>((resolve, reject) => {
    const id = setTimeout(resolve, ms);
    signal?.addEventListener('abort', () => {
      clearTimeout(id);
      reject(new DOMException('prazo esgotado', 'AbortError'));
    }, { once: true });
  });

import { classificarResposta, classificarErro } from './classificar';
import { calcularEspera, dormir } from './espera';

interface Opcoes {
  tentativasMax?: number;
  prazoTotalMs?: number;
  timeoutPorTentativaMs?: number;
}

export async function fetchResiliente(
  url: string,
  init: RequestInit = {},
  { tentativasMax = 4, prazoTotalMs = 12_000, timeoutPorTentativaMs = 4_000 }: Opcoes = {},
): Promise<Response> {
  const limite = AbortSignal.timeout(prazoTotalMs);
  let ultimoErro: unknown;

  for (let tentativa = 0; tentativa < tentativasMax; tentativa++) {
    try {
      const res = await fetch(url, {
        ...init,
        // Cada tentativa tem o próprio timeout, e o prazo total corta tudo.
        signal: AbortSignal.any([limite, AbortSignal.timeout(timeoutPorTentativaMs)]),
      });

      const veredito = classificarResposta(res);
      if (!veredito.repetir) return res;

      ultimoErro = new Error(`HTTP ${res.status}`);
      // Corpo não lido mantém a conexão presa até o coletor de lixo passar.
      await res.body?.cancel();

      const espera = veredito.esperarMs ?? calcularEspera(tentativa);
      await dormir(espera, limite);
    } catch (err) {
      if (limite.aborted) throw new Error('prazo total esgotado', { cause: ultimoErro ?? err });
      if (!classificarErro(err).repetir) throw err;

      ultimoErro = err;
      await dormir(calcularEspera(tentativa), limite);
    }
  }

  throw new Error(`falhou após ${tentativasMax} tentativas`, { cause: ultimoErro });
}

type Estado = 'fechado' | 'aberto' | 'meio-aberto';

export class Circuito {
  private estado: Estado = 'fechado';
  private falhas = 0;
  private abertoAte = 0;

  constructor(
    private readonly limiteFalhas = 5,
    private readonly resfriamentoMs = 30_000,
  ) {}

  async executar<T>(fn: () => Promise<T>): Promise<T> {
    if (this.estado === 'aberto') {
      if (Date.now() < this.abertoAte) {
        // Falha imediata: não gasta o prazo do usuário numa causa perdida.
        throw new Error('circuito aberto: serviço indisponível');
      }
      this.estado = 'meio-aberto';
    }

    try {
      const resultado = await fn();
      this.falhas = 0;
      this.estado = 'fechado';
      return resultado;
    } catch (err) {
      this.falhas++;
      // Em meio-aberto, uma única falha basta para reabrir: a sondagem disse
      // que ainda não voltou.
      if (this.estado === 'meio-aberto' || this.falhas >= this.limiteFalhas) {
        this.estado = 'aberto';
        this.abertoAte = Date.now() + this.resfriamentoMs;
      }
      throw err;
    }
  }
}

import { Circuito } from './resiliencia/circuito';
import { fetchResiliente } from './resiliencia/fetch-resiliente';

const circuito = new Circuito();

export async function cotarFrete(cep: string, pesoGramas: number) {
  try {
    const res = await circuito.executar(() =>
      fetchResiliente('https://api.parceiro.com/v1/cotacao', {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({ cep, pesoGramas }),
      }),
    );
    return await res.json();
  } catch (err) {
    // Degradar é melhor que quebrar: a tabela fixa permite fechar a compra.
    console.error('cotação indisponível, usando tabela fixa', err);
    return tabelaFixa(cep, pesoGramas);
  }
}