Circuit Breaker e Failover

O Claudex inclui um circuit breaker integrado para cada profile de provedor, com failover automatico para provedores de backup quando falhas sao detectadas.

Estados do Circuit Breaker

         success
    ┌──────────────┐
    │              │
    ▼    failure   │
 Closed ────────► Open
    ▲              │
    │   timeout    │
    │   expired    ▼
    └─────────── HalfOpen
                   │
                failure → back to Open

Estado	Comportamento
Closed	Operacao normal. Requisicoes passam. Falhas sao contadas.
Open	Requisicoes sao bloqueadas. Aciona failover para provedores de backup.
HalfOpen	Apos o timeout de recuperacao, uma requisicao de sonda e permitida. Sucesso → Closed; Falha → volta para Open.

Parametros Padrao

Parametro	Valor
Limite de falhas	3 falhas consecutivas
Timeout de recuperacao	30 segundos

Configuracao de Failover

Defina provedores de backup no seu profile para habilitar failover automatico:

[[profiles]]
name = "grok"
provider_type = "OpenAICompatible"
base_url = "https://api.x.ai/v1"
api_key = "xai-..."
default_model = "grok-3-beta"
backup_providers = ["deepseek", "chatgpt"]   # cadeia de failover

Quando grok falha 3 vezes consecutivas:

1. O circuit breaker abre para grok
2. A requisicao e repetida com deepseek
3. Se deepseek tambem falhar, tenta chatgpt
4. Cada provedor de backup tem seu proprio circuit breaker independente

Retry OAuth 401

Para profiles OAuth, respostas HTTP 401 recebem tratamento especial:

1. O proxy invalida o token OAuth atual
2. Tenta carregar um token novo da cadeia de credenciais
3. Reenvia a requisicao com o novo token
4. So conta como falha do circuit breaker se o retry tambem falhar

Isso evita que a expiracao temporaria de tokens acione failovers desnecessarios.

Verificacao de Saude

Um verificador de saude em segundo plano executa a cada ~30 segundos, enviando requisicoes leves de sonda para todos os profiles habilitados. O status de saude e exibido no dashboard TUI com codificacao por cores:

• Verde: saudavel
• Amarelo: degradado (falhas recentes)
• Vermelho: circuit breaker aberto