Circuit Breaker e failover

Claudex include un circuit breaker integrato per ogni profilo fornitore, con failover automatico verso fornitori di backup quando vengono rilevati guasti.

Stati del circuit breaker

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

Stato	Comportamento
Closed	Funzionamento normale. Le richieste passano. I guasti vengono contati.
Open	Le richieste vengono bloccate. Attiva il failover verso i fornitori di backup.
HalfOpen	Dopo il timeout di recupero, viene consentita una richiesta sonda. Successo -> Closed; Guasto -> torna a Open.

Parametri predefiniti

Parametro	Valore
Soglia di guasto	3 guasti consecutivi
Timeout di recupero	30 secondi

Configurazione del failover

Definisci fornitori di backup nel tuo profilo per abilitare il 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"]   # catena di failover

Quando grok fallisce 3 volte consecutivamente:

1. Il circuit breaker si apre per grok
2. La richiesta viene riprovata con deepseek
3. Se anche deepseek fallisce, si prova chatgpt
4. Ogni fornitore di backup ha il proprio circuit breaker indipendente

Retry OAuth 401

Per i profili OAuth, le risposte HTTP 401 ricevono un trattamento speciale:

1. Il proxy invalida il token OAuth corrente
2. Tenta un caricamento fresco del token dalla catena di credenziali
3. Riprova la richiesta con il nuovo token
4. Conta come guasto per il circuit breaker solo se anche il retry fallisce

Questo impedisce che la scadenza temporanea dei token attivi failover non necessari.

Controllo dello stato

Un controllo dello stato in background viene eseguito ogni ~30 secondi, inviando richieste sonda leggere a tutti i profili abilitati. Lo stato viene visualizzato nella dashboard TUI con codifica a colori:

• Verde: sano
• Giallo: degradato (guasti recenti)
• Rosso: circuit breaker aperto