# CLAUDE.md — Circuit Breaker en Go
> Contexte spécialisé pour Claude Code. Coller ce fichier à la racine du projet pour implémenter un circuit breaker résilient en Go pour la consommation d'APIs externes (exchanges crypto, services tiers instables).
---
## Section 1 : Les trois états du circuit breaker
Le circuit breaker est une machine à trois états. Analogie exacte avec un disjoncteur électrique : trop d'erreurs → le circuit s'ouvre et coupe le flux.
```text
CLOSED ──(5 échecs en 10s)──► OPEN
▲ │
│ (timeout 30s)
│ ▼
└──(sonde réussie)────── HALF-OPEN
```
**Closed (état normal)** : les requêtes passent, les erreurs sont comptabilisées. Tant que le seuil n'est pas atteint, tout continue.
**Open (circuit déclenché)** : les requêtes échouent immédiatement, sans appel réseau. Aucune connexion établie. L'état reste ouvert pendant un timeout configurable.
**Half-open (tentative de récupération)** : après le timeout, une seule requête "sonde" est autorisée.
- Sonde réussie → retour à Closed, compteurs remis à zéro
- Sonde échoue → retour à Open, timeout repart
L'état Half-open est ce qui distingue un circuit breaker d'un simple "disable" : la récupération est automatique, sans intervention manuelle.
---
## Section 2 : Implémentation Go — moins de 60 lignes
Thread-safe avec `sync.Mutex`, zéro dépendance externe.
```go
package circuit
import (
"errors"
"sync"
"time"
)
var ErrCircuitOpen = errors.New("circuit breaker open")
type State int
const (
StateClosed State = iota
StateOpen
StateHalfOpen
)
type CircuitBreaker struct {
mu sync.Mutex
state State
failures int
lastFailure time.Time
threshold int // échecs avant ouverture
timeout time.Duration // durée de l'état Open
}
func New(threshold int, timeout time.Duration) *CircuitBreaker {
return &CircuitBreaker{
threshold: threshold,
timeout: timeout,
}
}
func (cb *CircuitBreaker) Call(fn func() error) error {
cb.mu.Lock()
switch cb.state {
case StateOpen:
if time.Since(cb.lastFailure) > cb.timeout {
cb.state = StateHalfOpen
} else {
cb.mu.Unlock()
return ErrCircuitOpen
}
}
cb.mu.Unlock()
err := fn()
cb.mu.Lock()
defer cb.mu.Unlock()
if err != nil {
cb.failures++
cb.lastFailure = time.Now()
if cb.failures >= cb.threshold || cb.state == StateHalfOpen {
cb.state = StateOpen
}
return err
}
// succès : réinitialisation
cb.failures = 0
cb.state = StateClosed
return nil
}
```
**Points critiques de l'implémentation :**
- Le mutex est relâché **avant** l'appel à `fn()` — le garder acquis bloquerait toutes les goroutines pendant la durée de la requête réseau
- La transition Open → HalfOpen se fait à la réception de la prochaine requête, pas via une goroutine en arrière-plan (pas de goroutine leak si le circuit breaker est abandonné)
- En HalfOpen, toute erreur repousse directement en Open — la tolérance est nulle sur la sonde
---
## Section 3 : Retry avec backoff exponentiel
Le circuit breaker gère les pannes prolongées. Le retry gère les erreurs transitoires (paquet perdu, connexion TCP coupée, 429 passager). Les deux sont complémentaires.
```go
func withRetry(ctx context.Context, maxAttempts int, fn func() error) error {
var err error
for i := 0; i < maxAttempts; i++ {
err = fn()
if err == nil {
return nil
}
// Circuit ouvert = panne structurelle, pas une erreur transitoire
// Retenter immédiatement ne servirait à rien
if errors.Is(err, ErrCircuitOpen) {
return err
}
wait := time.Duration(math.Pow(2, float64(i))) * 100 * time.Millisecond
select {
case <-time.After(wait):
case <-ctx.Done():
return ctx.Err()
}
}
return fmt.Errorf("after %d attempts: %w", maxAttempts, err)
}
```
**Règle clé :** `errors.Is(err, ErrCircuitOpen)` interrompt les retries immédiatement. Quand le circuit est ouvert, la prochaine tentative retournera la même erreur dans la microseconde — le backoff exponentiel ne s'applique qu'aux vraies erreurs réseau.
Le `select` sur `ctx.Done()` garantit l'arrêt des retries si le contexte parent est annulé.
---
## Section 4 : Intégration avec timeout et context
Sans timeout par requête, une connexion peut bloquer indéfiniment si le serveur accepte la TCP mais ne répond jamais. Le circuit breaker ne se déclenche pas — les appels n'échouent pas, ils attendent. Les goroutines s'accumulent.
```go
type ExchangeService struct {
binance *BinanceClient
cb *CircuitBreaker
}
func (s *ExchangeService) GetOrderBook(ctx context.Context, pair string) (*OrderBook, error) {
// Timeout par requête, indépendant du contexte parent
callCtx, cancel := context.WithTimeout(ctx, 2*time.Second)
defer cancel()
var result *OrderBook
err := s.cb.Call(func() error {
var err error
result, err = s.binance.GetOrderBook(callCtx, pair)
return err
})
if err != nil {
if errors.Is(err, ErrCircuitOpen) {
// Circuit ouvert : servir le fallback plutôt qu'une erreur 500
return s.getFallbackOrderBook(pair)
}
return nil, err
}
return result, nil
}
```
**Les trois couches de protection :**
1. Timeout (`2s`) : un appel lent échoue vite et incrémente le compteur d'échecs
2. Circuit breaker : ouvre après plusieurs échecs, évite d'appeler un exchange down
3. Fallback : sert des données dégradées quand le circuit est ouvert
---
## Section 5 : Fallback et dégradation gracieuse
La stratégie de fallback dépend du type de donnée — c'est une décision **métier**, pas technique.
### Donnée stale acceptable (order book, prix)
```go
type CachedOrderBook struct {
Data *OrderBook
FetchedAt time.Time
}
func (s *ExchangeService) getFallbackOrderBook(pair string) (*OrderBook, error) {
s.cacheMu.RLock()
cached, ok := s.cache[pair]
s.cacheMu.RUnlock()
if !ok {
return nil, fmt.Errorf("circuit open and no cached data for %s", pair)
}
// Avertir si la donnée est trop vieille
if time.Since(cached.FetchedAt) > 10*time.Minute {
slog.Warn("serving stale order book", "pair", pair,
"age", time.Since(cached.FetchedAt))
}
return cached.Data, nil
}
```
### Donnée stale dangereuse (soldes de compte)
```go
func (s *ExchangeService) GetBalance(ctx context.Context) (*Balance, error) {
callCtx, cancel := context.WithTimeout(ctx, 3*time.Second)
defer cancel()
var result *Balance
err := s.cb.Call(func() error {
var err error
result, err = s.binance.GetBalance(callCtx)
return err
})
if err != nil {
// Pas de fallback pour les soldes — une donnée stale est pire qu'une erreur
return nil, fmt.Errorf("balance unavailable: %w", err)
}
return result, nil
}
```
**Règle :** documenter explicitement dans le code pourquoi une donnée est fallbackable ou non. Ne jamais ajouter un fallback "pour que ça marche" sans décision explicite.
---
## Section 6 : sony/gobreaker vs implémentation maison
```go
import "github.com/sony/gobreaker"
cb := gobreaker.NewCircuitBreaker(gobreaker.Settings{
Name: "binance-orderbook",
MaxRequests: 1, // sondes en HalfOpen
Interval: 10 * time.Second, // fenêtre de comptage
Timeout: 30 * time.Second, // durée état Open
ReadyToTrip: func(counts gobreaker.Counts) bool {
return counts.ConsecutiveFailures >= 5
},
OnStateChange: func(name string, from, to gobreaker.State) {
slog.Info("circuit breaker state change",
"name", name, "from", from, "to", to)
},
})
```
| Critère | Implémentation maison | gobreaker |
|---------|----------------------|-----------|
| Dépendances | Zéro | 1 |
| Fenêtre glissante | Non | Oui |
| Callbacks état | Non | Oui (`OnStateChange`) |
| Métriques Prometheus | À implémenter | Via callbacks |
| Lisibilité pour 2-3 exchanges | Meilleure | Correcte |
| Plateforme 20+ exchanges | Insuffisante | Recommandée |
**Règle :** implémentation maison si 2-3 exchanges avec patterns d'erreurs prévisibles. `gobreaker` si besoin de fenêtre glissante ou callbacks Prometheus.
---
## Section 7 : Monitoring et alerting
Les changements d'état du circuit breaker sont des signaux critiques à exposer.
```go
// Wrapper avec logging structuré sur les transitions d'état
type InstrumentedCircuitBreaker struct {
cb *CircuitBreaker
name string
}
func (icb *InstrumentedCircuitBreaker) Call(fn func() error) error {
prevState := icb.cb.state
err := icb.cb.Call(fn)
newState := icb.cb.state
if prevState != newState {
slog.Warn("circuit breaker state changed",
"name", icb.name,
"from", prevState,
"to", newState,
)
}
if errors.Is(err, ErrCircuitOpen) {
slog.Warn("circuit breaker rejected call",
"name", icb.name,
"state", icb.cb.state,
)
}
return err
}
```
**Métriques à exposer (Prometheus) :**
- `circuit_breaker_state` (gauge : 0=closed, 1=open, 2=half-open)
- `circuit_breaker_calls_total` (counter par état et résultat)
- `circuit_breaker_open_duration_seconds` (histogram)