Circuit Breaker verstehen

Einrichtung

Über die UI

Der Toggle sitzt im Route-Wizard in Step 5 — Reliability (zusammen mit Retry und Request Mirroring). Uptime Monitoring steuerst du in Step 4 — Access.

1. Route erstellen oder bearbeiten
2. Uptime Monitoring aktivieren (Voraussetzung, Step 4)
3. In Step 5 Circuit Breaker Toggle aktivieren
4. Threshold einstellen (Default 5 aufeinanderfolgende Fehler)
5. Timeout einstellen (Default 30 Sekunden)
6. Speichern

Die Route-Karte zeigt ein Badge: CB: Closed (grün), CB: Open (rot), CB: Half-Open (amber).

Über die API

# Circuit Breaker aktivieren
curl -X PUT https://gatecontrol.example.com/api/v1/routes/1 \
  -H "Authorization: Bearer gc_..." \
  -H "Content-Type: application/json" \
  -d '{
    "monitoring_enabled": true,
    "circuit_breaker_enabled": true,
    "circuit_breaker_threshold": 5,
    "circuit_breaker_timeout": 30
  }'

# Circuit Breaker manuell zurücksetzen (seit v1.50.4)
curl -X POST https://gatecontrol.example.com/api/v1/routes/1/circuit-breaker/reset \
  -H "Authorization: Bearer gc_..."

Wichtige Hinweise

• Monitoring ist Pflicht. Ohne aktiviertes Uptime Monitoring hat der Circuit Breaker keine Datenquelle und bleibt immer im Closed-Status.
• Failure-Counter und Open-Timestamp werden in der Datenbank persistiert (cb_failure_count, cb_opened_at). Offene Circuits überleben Neustarts; fehlt der Timestamp nach einem Neustart, wird er beim ersten Check-Durchlauf neu gesetzt.
• Der Circuit Breaker arbeitet pro Route, nicht pro Backend. Bei Load Balancing mit mehreren Backends öffnet der Circuit wenn das Monitoring-Ziel nicht erreichbar ist.
• Im Open-Status werden keine Anfragen ans Backend weitergeleitet — Caddy antwortet mit 503 Service Unavailable + Retry-After-Header. Kein Bypass per API oder einzelnem Request.
• Manueller Reset (seit v1.50.4): POST /api/v1/routes/:id/circuit-breaker/reset oder der Button Circuit-Breaker zurücksetzen im Route-Edit-Modal (nur sichtbar wenn Status ≠ closed). Setzt cb_failure_count = 0, cb_opened_at = NULL, Status auf closed, und re-rendert die Caddy-Config sofort. Ohne diesen Reset wartet ein offener Breaker auf den nächsten Monitoring-Zyklus und durchläuft den normalen open → half-open → closed-Pfad.
• Circuit Breaker ist nur für HTTP-Routen verfügbar, nicht für L4 (TCP/UDP).

Siehe auch

• RETRY-ON-ERROR.md — Retries innerhalb des Closed-Status
• UPTIME-MONITORING.md — Datenquelle für die State Machine
• concepts/routing.md — Einordnung in den Request-Flow