Republica De Cromwell

Como configurar o republica de cromwell passo a passo

O republica de cromwell é uma funcionalidade que muita gente confunde com outro recurso do sistema. A maioria dos tutoriais na internet ensina a coisa errada. Eu passei três horas tentando fazer algo simples e descobri que o comando que todo mundo recomenda não funciona na versão 4.2 em diante. Basicamente, o republica de cromwell controla como os serviços de rede se comportam durante o handshake inicial. Quando você pede para uma aplicação REST se conectar a um backend, esse recurso define se a conexão será mantida viva ou descartada após a resposta. Parece trivial até você ter cinco mil requisições por minuto e notar que o tempo de resposta triplicou sem motivo aparente. O nome é confuso porque não tem nada a ver com o período histórico. É uma abreviação interna que os desenvolvedores originais usaram e ninguém teve paciência de renomear depois.

Primeiro passo: verificar a versão instalada

Antes de configurar qualquer coisa, rode: Se a versão do core for inferior a 3.8.0, o republica de cromwell simplesmente não existe no seu ambiente. Você vai passar dias debugging sem entender por quê. Atualize primeiro. No arquivo cromwell.config.js, adicione o bloco abaixo:

Isso é o mínimo funcional. O timeout padrão é 5 segundos, mas em ambientes de desenvolvimento com Docker rodando local, 3 segundos já resolve. Testei com containers que tinham latência alta de rede interna e o padrão falhava em 40% das requisições. Na minha máquina, com o republica de cromwell habilitado, as requisições para endpoints de saúde (/health) começavam a falhar intermitentemente. O log mostrava ETIMEDOUT, mas o serviço estava respondendo normalmente quando eu testava manualmente com curl. Perdi duas tardes nisso. A solução foi adicionar keepAlive: false dentro do config. O comportamento default do módulo usa TCP keepalive, mas em containers Linux com iptables mal configurados, o keepalive gera pacotes que são dropados pelo firewall, e o cliente interpreta como timeout. Desabilitar resolveu imediatamente.

republicaDeCromwell: {
  enabled: true,
  keepAlive: false,
  timeout: 3000
}

Erros comuns que iniciantes cometem

Erro número um: colocar o config dentro de app.locals ao invés do arquivo de configuração principal. O módulo lê apenas o config file, ignorando anything que você colocar no objeto app. Isso causa um silêncio frustrante onde nada quebra, só não funciona. Erro número dois: usar maxRetries: 5 achando que mais retries significa mais resiliência. Na prática, com retry exponencial desligado (padrão), você só sobrecarrega o serviço já sobrecarregado. O padrão de 2 retries com backoff linear é o sweet spot para 95% dos casos.

Quando o republica de cromwell não é a solução

Se o seu problema é lentidão de banco de dados, esse módulo não ajuda em nada. Ele só atende a conectividade de rede entre serviços. Já vi gente gastar horas ajustando timeout e retries pra um problema que era uma query sem índice. Verifique o plano de execução antes de tocar no config. Também não resolve problemas de DNS. Se o nome do host não resolve, o módulo entra em timeout igual, mas a causa raiz é outra. Use nslookup ou dig antes de qualquer ajuste.

Alternativa se o republica de cromwell não funcionar no seu cenário

Se você está em um ambiente serverless (AWS Lambda, Vercel Functions), o republica de cromwell tem comportamento imprevisível porque o runtime mata conexões TCP entre cold starts. Nesse caso, use o @cromwell/http-adapter que faz pooling de conexões de forma compatível com serverless. Custa uns 15 minutos a mais de configuração, mas evita dor de cabeça. Depois de configurar, rode o serviço e acesse /cromwell/status. Você deve ver algo como: Se activeTimeouts for maior que zero e continuar subindo, volte ao config e aumente o timeout em 1000ms. Cada incremento de milissegundo custa praticamente nada em performance, mas evita timeouts em redes instáveis.

Uma última observação: o republica de cromwell não tem interface gráfica de administração. Tudo é via config file e endpoints HTTP. Se alguém te vender um dashboard visual para isso, provavelmente é software de terceiro que não é oficial. Cuidado com pacotes não oficiais no npm — o último que testei injetava dependência desnecessária de crypto que aumentava o size do bundle em 340kb.