# Circuit Breaker Pattern Implementation

Die Circuit Breaker Implementierung schützt das System vor wiederholten Fehlern durch temporäres Blockieren von Requests nach einer bestimmten Anzahl von Fehlern.

## Komponenten

### CircuitState Enum
- `CLOSED`: Normal operation, alle Requests werden durchgelassen
- `OPEN`: Service ist als fehlerhaft markiert, alle Requests werden abgelehnt
- `HALF_OPEN`: Test-Phase, limitierte Requests werden durchgelassen

### CircuitBreaker (Hauptklasse)
Zentrale Circuit Breaker Implementierung mit:
- Automatische State-Übergänge basierend auf Fehlern/Erfolgen
- Konfigurierbare Schwellenwerte und Timeouts
- Cache-basierte Persistierung des Zustands
- Retry-Logic mit exponential backoff

### CircuitBreakerConfig
Konfiguration für Circuit Breaker:
```php
new CircuitBreakerConfig(
    failureThreshold: 5,           // Fehler bis Circuit öffnet
    recoveryTimeoutSeconds: 60,    // Zeit bis HALF_OPEN Test
    halfOpenMaxAttempts: 3,        // Max Versuche im HALF_OPEN
    successThreshold: 3            // Erfolge bis Circuit schließt
);
```

### Spezialisierte Circuit Breaker

#### DatabaseCircuitBreaker
Schutz für Datenbankoperationen:
```php
$result = $databaseCircuitBreaker->execute($connection, function($conn) {
    return $conn->query('SELECT * FROM users');
});
```

#### HttpClientCircuitBreaker
Schutz für externe HTTP-Services:
```php
$response = $httpCircuitBreaker->get('https://api.example.com/data', [], 'api_service');
```

### CircuitBreakerMiddleware
HTTP-Middleware für automatischen Schutz von Routes:
```php
// Automatischer API-Schutz
$middleware = CircuitBreakerMiddleware::forApi($circuitBreaker);

// Custom Service-Mapping
$middleware = new CircuitBreakerMiddleware($circuitBreaker, [
    'payment_api' => CircuitBreakerConfig::strict(),
    'notification_service' => CircuitBreakerConfig::forExternalService()
]);
```

### CircuitBreakerManager
Zentrale Verwaltung und Monitoring:
```php
$manager = CircuitBreakerManager::withDefaults($cache, $clock, $logger);

// Status aller Services
$status = $manager->getAllServicesStatus();

// Globale Statistiken
$stats = $manager->getGlobalStatistics();

// Health Checks
$health = $manager->performHealthChecks();
```

## Verwendung

### Grundlegende Verwendung
```php
$circuitBreaker = new CircuitBreaker($cache, $clock, $logger);

// Operation ausführen
try {
    $result = $circuitBreaker->execute('my_service', function() {
        // Potentiell fehlerhafte Operation
        return $externalService->getData();
    });
} catch (CircuitBreakerException $e) {
    // Circuit ist offen, Service nicht verfügbar
    return $fallbackData;
}
```

### Mit Konfiguration
```php
$config = new CircuitBreakerConfig(
    failureThreshold: 3,
    recoveryTimeoutSeconds: 30
);

$circuitBreaker->execute('critical_service', $operation, $config);
```

### Manuelle Überwachung
```php
// Status prüfen
$state = $circuitBreaker->getState('my_service');

// Metriken abrufen
$metrics = $circuitBreaker->getMetrics('my_service');

// Circuit zurücksetzen
$circuitBreaker->reset('my_service');
```

## Console Commands

### Status anzeigen
```bash
# Alle Services
php console.php circuit-breaker status

# Spezifischer Service
php console.php circuit-breaker status database

# Globale Statistiken
php console.php circuit-breaker stats
```

### Health Checks
```bash
php console.php circuit-breaker health
```

### Reset Circuit Breaker
```bash
# Spezifischer Service
php console.php circuit-breaker reset database

# Alle Services (mit Bestätigung)
php console.php circuit-breaker reset

# Alle Services (ohne Bestätigung)
php console.php circuit-breaker reset --force
```

### Konfiguration
```bash
# Aktuelle Konfiguration anzeigen
php console.php circuit-breaker config

# Konfiguration exportieren
php console.php circuit-breaker export
php console.php circuit-breaker export --output=my-config.json
```

## Vorkonfigurierte Service-Typen

### Datenbank Services
```php
$config = CircuitBreakerConfig::forDatabase(
    failureThreshold: 3,
    recoveryTimeoutSeconds: 30
);
```

### Externe Services
```php
$config = CircuitBreakerConfig::forExternalService(
    failureThreshold: 5,
    recoveryTimeoutSeconds: 300
);
```

### Kritische Services
```php
$config = CircuitBreakerConfig::strict(
    failureThreshold: 3,
    recoveryTimeoutSeconds: 600
);
```

## Error Codes

Circuit Breaker Exceptions verwenden dedizierte Error Codes:
- `SVC001`: Circuit Breaker ist offen
- `SVC002`: Circuit Breaker ist half-open
- `SVC003`: Service Health Check fehlgeschlagen
- `SVC004`: Service ist degradiert

## Integration mit Error Handling

Circuit Breaker Exceptions werden automatisch in das Framework Error Handling integriert:
- OWASP-konforme Logging
- Structured Error Context
- HTTP 503 Responses mit Retry-After Header
- Security Event Tracking bei kritischen Services

## Best Practices

1. **Service-spezifische Konfiguration**: Verschiedene Services benötigen unterschiedliche Schwellenwerte
2. **Monitoring**: Überwachen Sie Circuit Breaker Status und Metriken
3. **Fallback-Strategien**: Implementieren Sie Fallback-Logic für geöffnete Circuits
4. **Graceful Degradation**: Reduzieren Sie Funktionalität anstatt kompletten Ausfall
5. **Health Checks**: Implementieren Sie aktive Health Checks für bessere Recovery

## Performance

- Cache-basierte State-Persistierung für minimalen Overhead
- Efficient key-based service separation
- Configurable TTL für automatische Cleanup
- Batch operations für bulk resets
- Lock-free state transitions für high concurrency