Fetch, Retry e Timeout: O Código que Falta entre Sua API e a Realidade

// ❌ O código que estava em produção
const response = await fetch('https://frete-api.exemplo.com/calculate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload),
});
const data = await response.json();

// src/http/safe-fetch.ts
 
export class HttpError extends Error {
  constructor(
    public readonly status: number,
    public readonly statusText: string,
    public readonly body: unknown,
    public readonly url: string,
  ) {
    super(`HTTP ${status} ${statusText} at ${url}`);
    this.name = 'HttpError';
  }
}
 
export async function safeFetch<T>(
  url: string,
  init?: RequestInit,
): Promise<T> {
  const response = await fetch(url, init);
 
  if (!response.ok) {
    // Tenta parsear o body de erro para dar contexto ao chamador.
    // APIs bem feitas retornam JSON com detalhes mesmo em 4xx/5xx.
    let errorBody: unknown;
    try {
      errorBody = await response.json();
    } catch {
      errorBody = await response.text().catch(() => null);
    }
 
    throw new HttpError(
      response.status,
      response.statusText,
      errorBody,
      url,
    );
  }
 
  // Respostas 204 No Content não têm body
  if (response.status === 204) {
    return undefined as T;
  }
 
  return response.json() as Promise<T>;
}

// src/http/with-timeout.ts
 
export function fetchWithTimeout(
  url: string,
  init: RequestInit & { timeoutMs?: number } = {},
): Promise<Response> {
  const { timeoutMs = 5000, signal: externalSignal, ...rest } = init;
 
  // AbortSignal.timeout() cria um signal que aborta automaticamente
  // após N milissegundos. Disponível em Node 18.11+ e browsers modernos.
  const timeoutSignal = AbortSignal.timeout(timeoutMs);
 
  // Se o chamador já passou um signal (ex: para cancelamento manual),
  // combinamos os dois com AbortSignal.any(). O primeiro a disparar vence.
  const combinedSignal = externalSignal
    ? AbortSignal.any([timeoutSignal, externalSignal as AbortSignal])
    : timeoutSignal;
 
  return fetch(url, { ...rest, signal: combinedSignal });
}

// src/http/with-timeout-legacy.ts
// Para Node 18.x onde AbortSignal.any() não existe
 
export function fetchWithTimeoutLegacy(
  url: string,
  init: RequestInit & { timeoutMs?: number } = {},
): Promise<Response> {
  const { timeoutMs = 5000, ...rest } = init;
  const controller = new AbortController();
 
  // setTimeout retorna um Timeout no Node (não number como no browser).
  // Guardamos a referência para limpar depois e evitar leak.
  const timer = setTimeout(() => controller.abort(), timeoutMs);
 
  return fetch(url, { ...rest, signal: controller.signal }).finally(() => {
    clearTimeout(timer);
  });
}

// src/http/retry.ts
 
import { HttpError, safeFetch } from './safe-fetch';
 
interface RetryConfig {
  maxRetries: number;
  baseDelayMs: number;
  maxDelayMs: number;
  retryableStatuses: Set<number>;
}
 
const DEFAULT_RETRY_CONFIG: RetryConfig = {
  maxRetries: 3,
  baseDelayMs: 300,
  maxDelayMs: 10_000,
  // 429: rate limited. 502/503/504: problemas de infraestrutura upstream.
  retryableStatuses: new Set([429, 502, 503, 504]),
};
 
function calculateDelay(attempt: number, config: RetryConfig): number {
  // Exponential backoff: 300ms, 600ms, 1200ms, 2400ms...
  // O jitter evita que N clientes sincronizem retries no mesmo instante
  // (thundering herd). Sem jitter, um 503 que afeta 1000 clientes
  // gera 1000 retries simultâneos exatamente 300ms depois.
  const exponential = config.baseDelayMs * Math.pow(2, attempt);
  const capped = Math.min(exponential, config.maxDelayMs);
  const jitter = capped * (0.5 + Math.random() * 0.5);
  return Math.floor(jitter);
}
 
function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}
 
export async function fetchWithRetry<T>(
  url: string,
  init?: RequestInit & { timeoutMs?: number },
  config: Partial<RetryConfig> = {},
): Promise<T> {
  const mergedConfig = { ...DEFAULT_RETRY_CONFIG, ...config };
 
  let lastError: Error | undefined;
 
  for (let attempt = 0; attempt <= mergedConfig.maxRetries; attempt++) {
    try {
      return await safeFetch<T>(url, init);
    } catch (error) {
      lastError = error as Error;
 
      const isRetryable =
        error instanceof HttpError &&
        mergedConfig.retryableStatuses.has(error.status);
 
      // Erros de rede (DNS, conexão recusada) também são retryable.
      // O fetch lança TypeError para falhas de rede, não HttpError.
      const isNetworkError =
        error instanceof TypeError && error.message.includes('fetch');
 
      if ((!isRetryable && !isNetworkError) || attempt === mergedConfig.maxRetries) {
        throw error;
      }
 
      const delay = calculateDelay(attempt, mergedConfig);
      await sleep(delay);
    }
  }
 
  throw lastError;
}

// src/http/api-client.ts
 
import { fetchWithTimeout } from './with-timeout';
import { HttpError } from './safe-fetch';
 
type Interceptor = (url: string, init: RequestInit) => RequestInit | Promise<RequestInit>;
 
interface ApiClientConfig {
  baseUrl: string;
  timeoutMs: number;
  maxRetries: number;
  defaultHeaders: Record<string, string>;
  interceptors: Interceptor[];
  retryableStatuses: Set<number>;
}
 
export function createApiClient(config: Partial<ApiClientConfig> = {}) {
  const {
    baseUrl = '',
    timeoutMs = 5000,
    maxRetries = 3,
    defaultHeaders = { 'Content-Type': 'application/json' },
    interceptors = [],
    retryableStatuses = new Set([429, 502, 503, 504]),
  } = config;
 
  async function request<T>(
    path: string,
    init: RequestInit = {},
  ): Promise<T> {
    const url = `${baseUrl}${path}`;
 
    let finalInit: RequestInit = {
      ...init,
      headers: { ...defaultHeaders, ...init.headers },
    };
 
    // Interceptors rodam em sequência. Cada um pode modificar headers,
    // injetar tokens, adicionar tracing headers, etc.
    for (const interceptor of interceptors) {
      finalInit = await interceptor(url, finalInit);
    }
 
    let lastError: Error | undefined;
 
    for (let attempt = 0; attempt <= maxRetries; attempt++) {
      try {
        const response = await fetchWithTimeout(url, {
          ...finalInit,
          timeoutMs,
        });
 
        if (!response.ok) {
          let errorBody: unknown;
          try {
            errorBody = await response.json();
          } catch {
            errorBody = null;
          }
          throw new HttpError(response.status, response.statusText, errorBody, url);
        }
 
        if (response.status === 204) return undefined as T;
        return (await response.json()) as T;
      } catch (error) {
        lastError = error as Error;
 
        const isRetryable =
          error instanceof HttpError && retryableStatuses.has(error.status);
        const isNetworkError =
          error instanceof TypeError && error.message.includes('fetch');
        const isTimeout =
          error instanceof DOMException && error.name === 'TimeoutError';
 
        if (
          (!isRetryable && !isNetworkError && !isTimeout) ||
          attempt === maxRetries
        ) {
          throw error;
        }
 
        const delay = Math.min(300 * Math.pow(2, attempt), 10_000);
        const jitter = delay * (0.5 + Math.random() * 0.5);
        await new Promise((r) => setTimeout(r, jitter));
      }
    }
 
    throw lastError;
  }
 
  return {
    get: <T>(path: string, init?: RequestInit) =>
      request<T>(path, { ...init, method: 'GET' }),
    post: <T>(path: string, body: unknown, init?: RequestInit) =>
      request<T>(path, { ...init, method: 'POST', body: JSON.stringify(body) }),
    put: <T>(path: string, body: unknown, init?: RequestInit) =>
      request<T>(path, { ...init, method: 'PUT', body: JSON.stringify(body) }),
    delete: <T>(path: string, init?: RequestInit) =>
      request<T>(path, { ...init, method: 'DELETE' }),
  };
}

// src/services/freight.ts
 
import { createApiClient } from '../http/api-client';
 
interface FreightQuote {
  carrier: string;
  price: number;
  deliveryDays: number;
}
 
const freightApi = createApiClient({
  baseUrl: 'https://frete-api.exemplo.com',
  timeoutMs: 3000,
  maxRetries: 2,
  interceptors: [
    // Injeta o token de autenticação em toda request
    async (_url, init) => ({
      ...init,
      headers: {
        ...init.headers,
        Authorization: `Bearer ${process.env.FREIGHT_API_TOKEN}`,
      },
    }),
  ],
});
 
export async function getFreightQuote(
  zipFrom: string,
  zipTo: string,
  weightKg: number,
): Promise<FreightQuote[]> {
  return freightApi.post<FreightQuote[]>('/v2/calculate', {
    origin: zipFrom,
    destination: zipTo,
    weight: weightKg,
  });
}

// ❌ PERIGOSO: retry em POST que cria recursos
await fetchWithRetry<Order>('/api/orders', {
  method: 'POST',
  body: JSON.stringify({ items, total }),
});
// Se o primeiro request criou o pedido mas a resposta deu timeout,
// o retry cria um SEGUNDO pedido. Cobrança duplicada.

// ✅ Idempotency key impede duplicação no servidor
import { randomUUID } from 'node:crypto';
 
const idempotencyKey = randomUUID();
 
await fetchWithRetry<Order>('/api/orders', {
  method: 'POST',
  headers: { 'Idempotency-Key': idempotencyKey },
  body: JSON.stringify({ items, total }),
});
// O servidor reconhece a mesma key e retorna a resposta original
// sem criar um novo pedido.

// ❌ Engole o erro e retorna fallback sem logar nada
async function getUserProfile(id: string) {
  try {
    return await api.get(`/users/${id}`);
  } catch {
    return { name: 'Unknown', email: '' };
  }
}

// ✅ Loga, distingue erros transitórios de permanentes, e retorna fallback
// apenas quando o contexto permite (ex: exibição, não transação financeira)
async function getUserProfile(id: string): Promise<UserProfile | null> {
  try {
    return await api.get<UserProfile>(`/users/${id}`);
  } catch (error) {
    if (error instanceof HttpError && error.status === 404) {
      // 404 é esperado: usuário não existe. Não é um erro de infra.
      return null;
    }
    // Qualquer outro erro é inesperado e precisa de visibilidade.
    logger.error('Failed to fetch user profile', {
      userId: id,
      error: error instanceof HttpError ? error.status : String(error),
    });
    throw error;
  }
}