> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payven.com.tr/llms.txt
> Use this file to discover all available pages before exploring further.

# Circuit Breaker

> Sağlıksız bankanın yönlendirme havuzundan otomatik çıkarılması.

Circuit Breaker, bir bankanın **istikrarsız** olduğunu tespit ettiğinde o bankayı **geçici olarak** yönlendirme havuzundan çıkarır. Banka düzelene kadar işlemler diğer konnektörlere yönlendirilir.

## Neden gerekli?

Akıllı Yönlendirme her isteği gerçek zamanlı değerlendirir. Ama bir banka **sürekli** hata veriyorsa her seferinde yeniden denemek:

* Müşteri için gecikme yaratır (5 sn timeout sonrası fallback)
* Toplam başarı oranını düşürür
* Hatalı bankayı meşgul eder

Circuit Breaker bu döngüyü kırar — hatalı banka belirli bir süre **devre dışı bırakılır**.

## Üç hal

```mermaid theme={null}
stateDiagram-v2
    [*] --> Closed: Banka sağlıklı
    Closed --> Open: Hata eşiği aşıldı
    Open --> HalfOpen: Bekleme süresi doldu
    HalfOpen --> Closed: Test isteği başarılı
    HalfOpen --> Open: Test isteği başarısız
```

| Hal          | Davranış                                                 |
| ------------ | -------------------------------------------------------- |
| **Closed**   | Banka sağlıklı, normal yönlendirme                       |
| **Open**     | Banka devre dışı, hiçbir istek atılmaz                   |
| **HalfOpen** | Bekleme süresi sonunda küçük bir test trafiği gönderilir |

## Konfigürasyon

Circuit Breaker, konnektör HTTP istemcisi üzerinde **Polly** kütüphanesi ile uygulanmıştır (`Infrastructure/Http/PollyPolicies.cs`). Mevcut varsayılanlar:

| Parametre                         | Varsayılan | Açıklama                                      |
| --------------------------------- | ---------- | --------------------------------------------- |
| `exceptionsAllowedBeforeBreaking` | 3          | Bu sayıda ardışık geçici HTTP hatası → Open   |
| `durationOfBreakInSeconds`        | 30 sn      | Open kalma süresi (sonra HalfOpen'a geçer)    |
| HalfOpen test trafiği             | 1 istek    | Tek başarılı istek → Closed; başarısız → Open |
| Retry policy (ayrı)               | 3 deneme   | Exponential backoff (`2^attempt` saniye)      |
| Timeout                           | 30 sn      | İstek başına                                  |

<Note>
  Implementasyon Polly'nin **basit `CircuitBreakerAsync`** policy'sidir — exception **count** tabanlı (oran tabanlı değil). "Rolling pencere içinde %50 hata" gibi gelişmiş ölçümler `AdvancedCircuitBreakerAsync`'a geçişle yol haritasında.
</Note>

Konnektör başına özelleştirme için: **Konsol → Konnektörler → \[Konfigürasyon]** ekranı veya `PUT /api/v1/connector-configurations/{id}` endpoint'i.

## Açılma kriteri

Bir konnektör HTTP istemcisi **3 ardışık geçici hata** (5xx, timeout, network) verdiğinde Open'a geçer. 30 saniye boyunca o konnektöre çağrı yapılmaz; süre sonunda HalfOpen'a geçilir ve tek bir test isteği denenir.

## Yarı-açık hal (HalfOpen)

Bekleme süresi dolunca breaker "HalfOpen" haline geçer. Sonraki birkaç istek **test trafiği** olarak banka ile yeniden denenir:

* Test başarılı → Closed haline döner, normal çalışmaya devam eder.
* Test başarısız → tekrar Open haline döner.

## İstek üzerindeki etkisi

Banka Open haldeyken o bankaya yönlendirilecek istekler:

* Routing kuralında **`fallback_connector_config_id`** tanımlanmışsa → doğrudan fallback konnektöre gider, birinci konnektör hiç denenmez (timeout süresi kaybedilmez)
* Fallback yoksa → işlem `connector_unavailable` koduyla reddedilir
* Karşılayan başka kural varsa engine onu değerlendirmeye devam eder

## Sağlık endpoint'i

Konnektörün anlık sağlık durumunu API üzerinden kontrol edebilirsiniz:

```bash theme={null}
curl https://vpos.payven.com.tr/api/v1/connector-configurations/{id}/health \
  -H "Authorization: Bearer $PAYVEN_TOKEN"
```

Yanıt; mevcut hali (`closed`/`open`/`half_open`), son rolling penceredeki başarı/hata oranını, ortalama yanıt süresini ve son durum değişiklik zamanını döner.

## İzleme

Breaker durumunu konsoldaki **Konnektör Sağlık Paneli** ekranından takip edebilirsiniz:

* Mevcut hali (Closed / Open / HalfOpen)
* Son rolling window'daki başarı/hata oranı
* Ortalama yanıt süresi
* Hangi tarihte Open'a düştüğü
* Spark-line trend grafikleri

## Yol haritası

* **Connector health webhook event'leri** (`connector.circuit.opened` / `closed`) — şu an public webhook event listesinde yok, planlamada
* **Konnektör başına özel circuit breaker konfig UI'ı** (varsayılan ayarlar yerine merchant-spesifik)
* **Manuel devreden çıkarma** — bakım pencereleri için konnektörü manuel Open'a alma
* **Bağlantı testleri** — konfigürasyon sırasında **Test Et** ile sağlık doğrulama