Circuit Breakers e Degradação Graciosa: Como Sobreviver a Falhas Externas

A Armadilha das Falhas em Cascata: Como uma API Externa Derruba o Teu Sistema

As aplicações web modernas não vivem isoladas. Um processo de checkout ou painel de clientes comunica habitualmente com vários serviços externos na cloud:

• Stripe ou Easypay para cobranças de cartões de crédito.
• OpenAI ou Anthropic para geração de resumos e apoio inteligente.
• SendGrid para envio de notificações por email.
• APIs de Transportadoras ou ERPs para cálculo de taxas e stock em tempo real.

Quando todos estes serviços respondem depressa, tudo parece perfeito.

Agora imagina o que acontece numa terça-feira à tarde se o serviço externo de cálculo de taxas de envio sofrer uma avaria mundial. A API da transportadora não devolve um erro imediato: fica simplesmente congelada, demorando 45 segundos até dar timeout.

Um cliente clica em “Ver Carrinho”. O pedido dele fica retido em memória à espera da resposta externa. Passados trinta segundos, outros duzentos clientes tentam fazer compras. Centenas de pedidos ficam pendurados em fila na memória do teu servidor.

A piscina de ligações da tua aplicação esgota-se. O Nginx atinge o limite de tempo e começa a cuspir erros 502 Bad Gateway e 504 Gateway Timeout. O teu site inteiro vai abaixo—não porque o teu código ou a base de dados em PostgreSQL tivessem problemas, mas porque uma dependência externa arrastou todo o teu servidor para um apagão em cascata.

O COLAPSO EM CASCATA POR FALTA DE PROTEÇÃO

• Utilizadores a Comprar → [O Teu Servidor Web]
• (Chama API de transportadora sem timeout)
• A API EXTERNA DE TRANSPORTES CONGELOU! (Demora 60 segundos…)
• 300 processos do Node.js ficam bloqueados à espera de resposta!
• O servidor esgota descritores de ficheiros e memória RAM!
• O Nginx acha que o teu backend morreu e desliga as ligações!
• O TEU SITE INTEIRO FICA EM BAIXO! APAGÃO TOTAL EM PRODUÇÃO!

Para desenhares web apps e websites de alta performance verdadeiramente robustos, tens de erguer barreiras de defesa: timeouts curtos, backoff exponencial com variação aleatória e o padrão Circuit Breaker.

O Padrão Circuit Breaker: Estados Fechado, Aberto e Semi-Aberto

Inspirado nos disjuntores elétricos que saltam no quadro de tua casa para evitar incêndios quando a corrente sobe em demasia, o Circuit Breaker envolve as chamadas a serviços externos numa máquina de estados:

MÁQUINA DE ESTADOS DO CIRCUIT BREAKER

• FECHADO (Normal)
• Pedidos passam para a API
• (Taxa de falhas superior a 50%)
• ABERTO (Disparado)
• REJEIÇÃO IMEDIATA (0.1ms)!
• Não faz chamadas de rede!
• Ativa resposta estimada
• (Passados 30 segundos de espera)
• SEMI-ABERTO (Teste)
• Deixa passar 3 testes
• (Testes funcionaram!) — (Algum teste falhou)
• Volta a FECHADO
• Volta a ABERTO

1. Fechado (Closed): Modo normal. Os pedidos seguem para o serviço externo. O disjuntor mede a percentagem de sucesso e de falhas numa janela recente (por exemplo, nos últimos 20 pedidos).
2. Aberto (Open): Quando a taxa de erros ultrapassa o limiar de alarme (por exemplo, 50% de falhas), o disjuntor dispara. Durante os 30 segundos seguintes, nenhuma chamada de rede é feita. Qualquer pedido para essa dependência falha de imediato em 0.1 milissegundos, devolvendo uma resposta de contingência. Isto poupa a memória do teu servidor e deixa o serviço externo recuperar em paz.
3. Semi-Aberto (Half-Open): Passados 30 segundos, o disjuntor deixa passar três pedidos de teste. Se funcionarem, volta ao estado Fechado. Se falharem, volta a Aberto durante mais meio minuto.

Como Implementar um Circuit Breaker em Node.js com Opossum

Vê como podes proteger uma rota crítica em Node.js utilizando a biblioteca de referência opossum:

// src/services/servicoPortes.ts
import CircuitBreaker from 'opossum';

interface PedidoPortes {
  codigoPostal: string;
  pesoKg: number;
}

// 1. Chamada de rede com limite rígido de 2 segundos de timeout
async function consultarTaxaExterna(pedido: PedidoPortes): Promise<number> {
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), 2000); // Máximo 2s!

  try {
    const resposta = await fetch('https://api.transportadora.pt/v1/cotacao', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(pedido),
      signal: controller.signal,
    });

    if (!resposta.ok) {
      throw new Error(`Erro na API externa: ${resposta.status}`);
    }

    const dados = await resposta.json();
    return dados.valorPortes;
  } finally {
    clearTimeout(timeoutId);
  }
}

// 2. Parâmetros do Circuit Breaker
const opcoes: CircuitBreaker.Options = {
  timeout: 2500,               // Dispara se a operação demorar mais de 2.5s
  errorThresholdPercentage: 50,// Abre o disjuntor se metade dos pedidos falhar
  resetTimeout: 30000,         // Espera 30s antes de testar em Semi-Aberto
  rollingCountTimeout: 10000,  // Janela estatística de 10 segundos
};

export const disjuntorPortes = new CircuitBreaker(consultarTaxaExterna, opcoes);

// 3. Resposta de Contingência (Degradação Graciosa)
disjuntorPortes.fallback((pedido: PedidoPortes) => {
  console.warn(`[Disjuntor] API de transportes em baixo! A aplicar taxa estimada.`);
  // O cliente não é bloqueado: aplicamos uma taxa fixa de contingência de 4.50€
  return 4.50;
});

disjuntorPortes.on('open', () => console.error('[Alerta] Disjuntor de portes DISPAROU!'));
disjuntorPortes.on('close', () => console.log('[Info] Disjuntor de portes RECUPEROU.'));

Repara na inteligência deste desenho: mesmo que a transportadora esteja completamente offline, o teu cliente final nunca vê uma mensagem de erro. O sistema aplica uma taxa fixa de contingência e permite fechar a venda, cumprindo o princípio de anti-over-engineering.

Backoff Exponencial com Jitter: Como Evitar a Manada Furiosa

Quando um serviço externo começa a falhar, muitas pessoas programam retentativas cegas (while(falhou) { tentar(); }). Isto provoca o fenómeno da Manada Furiosa (Thundering Herd).

Se milhares de clientes repetirem pedidos no mesmo segundo, bombardeiam o serviço debilitado com uma avalanche simultânea de requisições, impedindo-o de recuperar.

A solução matemática é o Backoff Exponencial com Variação Aleatória (Full Jitter):

// src/utils/backoff.ts
export async function tentarComJitter<T>(
  operacao: () => Promise<T>,
  tentativas = 3,
  esperaBaseMs = 200,
  esperaMaximaMs = 3000
): Promise<T> {
  let contador = 0;

  while (contador < tentativas) {
    try {
      return await operacao();
    } catch (erro) {
      contador++;
      if (contador >= tentativas) throw erro;

      // Cálculo exponencial: base * 2^tentativa
      const atrasoExponencial = Math.min(esperaMaximaMs, esperaBaseMs * Math.pow(2, contador));

      // Jitter aleatório: espalha a espera de forma uniforme
      const esperaReal = Math.random() * atrasoExponencial;

      console.warn(`[Retry] Tentativa ${contador} falhou. A aguardar ${Math.round(esperaReal)}ms`);
      await new Promise((resolve) => setTimeout(resolve, esperaReal));
    }
  }

  throw new Error('Todas as tentativas esgotadas');
}

• REPETIÇÕES SÍNCRONAS vs VARIAÇÃO ALEATÓRIA (JITTER)
• RETENTATIVAS SEM JITTER: Falhou → Todos esperam exatamente 1 segundo → 2.000 pedidos colidem juntos! (Derruba a API de novo e prolonga a paragem indefinidamente!)
• BACKOFF EXPONENCIAL COM JITTER: Cliente A espera: 240ms → Distribuído suavemente pelo tempo!
• Cliente B espera: 710ms → Distribuído suavemente pelo tempo!
• Cliente C espera: 1.150ms → Distribuído suavemente pelo tempo! (Permite ao serviço externo processar a fila com calma e recuperar!)

Este intervalo aleatório suaviza os picos de tráfego e permite que os servidores em recuperação regressem à estabilidade.

Estratégias de Degradação Graciosa no Teu Negócio

Resiliência significa desenhar cada funcionalidade com um plano de contingência:

PLANO DE DEGRADAÇÃO GRACIOSA

Testar estes cenários em contentores com o Docker garante que a tua infraestrutura não guarda surpresas desagradáveis. Encontras mais exemplos no repositório de suporte no GitHub.

Boas Práticas Operacionais: Isolamento de Piscinas e Métricas

Seguindo as normas técnicas consolidadas na WebXtek, deves aplicar estas três recomendações de arquitetura:

1. Separa as Piscinas de Conexões (Bulkheading): Nunca uses a mesma reserva de conexões HTTP para todos os serviços externos. Aloca limites separados para o Stripe e para serviços secundários. Se a OpenAI congelar, o processo de pagamentos continua com todas as conexões intactas.
2. Exporta Métricas do Disjuntor para Alertas: O teu sistema deve emitir um alerta no canal de emergência no segundo exato em que um disjuntor disparar para o estado Open.
3. Aplica Sempre Timeouts Rigorosos em Chamadas de Rede: Nunca deixes um pedido HTTP sem um cancelador AbortController. No código de produção, nenhuma chamada externa de frontend deve esperar mais do que 3 segundos.

Ao envolveres dependências externas frágeis em Circuit Breakers e implementares degradações graciosas com backoff inteligente, constróis software que nunca vai abaixo e manténs os teus utilizadores a navegar com total tranquilidade mesmo perante avarias globais na cloud.

Na prática, aplicas exatamente estes padrões operacionais em setores exigentes como saas empresarial b2b e especialistas em devops e arquitetura cloud. Quando alinhas a tua estrutura através de web apps e websites de alta performance, transformas boas práticas técnicas numa vantagem competitiva real e mensurável para o teu negócio.