michaelschiemer/src/Framework/CircuitBreaker

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:

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:

$result = $databaseCircuitBreaker->execute($connection, function($conn) {
    return $conn->query('SELECT * FROM users');
});

HttpClientCircuitBreaker

Schutz für externe HTTP-Services:

$response = $httpCircuitBreaker->get('https://api.example.com/data', [], 'api_service');

CircuitBreakerMiddleware

HTTP-Middleware für automatischen Schutz von Routes:

// 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:

$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

$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

$config = new CircuitBreakerConfig(
    failureThreshold: 3,
    recoveryTimeoutSeconds: 30
);

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

Manuelle Überwachung

// 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

# 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

php console.php circuit-breaker health

Reset Circuit Breaker

# 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

# 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

$config = CircuitBreakerConfig::forDatabase(
    failureThreshold: 3,
    recoveryTimeoutSeconds: 30
);

Externe Services

$config = CircuitBreakerConfig::forExternalService(
    failureThreshold: 5,
    recoveryTimeoutSeconds: 300
);

Kritische Services

$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