Circuit Breakers

Патерн circuit breaker запобігає тому, щоб ваш додаток бомбардував запитами upstream API що відмовив — дозволяючи йому відновитися, поки обслуговуються fallback відповіді.

Як це працює

MirApi відстежує збої на цільовий хост у Redis. Контур має три стани:

CLOSED → (5 збоїв за 60с) → OPEN → (15с cooldown) → probe запит
                                                           ↓
                                            успіх → CLOSED
                                            збій  → OPEN знову

CLOSED: Нормальна робота. Всі запити проходять.
OPEN: Upstream мав 5+ збоїв за останню хвилину. Нові запити блокуються негайно. Якщо активний Smart Cache — кешована відповідь повертається. Інакше — помилка.
HALF-OPEN (неявний): Через 15 секунд ключ в Redis спливає і наступний запит зондує upstream. При успіху — CLOSED. При збої — OPEN знову.

Увімкнення

curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/charges" \
  -H "X-Circuit-Breaker: on" \
  -H "Content-Type: application/json" \
  -d '{"amount": 2000, "currency": "usd", "source": "tok_visa"}'

Заголовок	Значення	Опис
`X-Circuit-Breaker`	`on` або `true`	Увімкнути circuit breaker для цільового хоста

Фіксовані параметри

Параметр	Значення	Опис
Поріг збоїв	5	Кількість збоїв для відкриття контуру
Вікно	60 секунд	Вікно підрахунку збоїв у Redis
TTL відкритого стану	15 секунд	Час у стані OPEN перед зондуванням
Область	Per host	Збої відстежуються на цільовий хостнейм

Варіанти використання

1. Circuit Breaker + Smart Cache (Рекомендовано)

При відкритому контурі — повертати кешовану відповідь замість помилки:

curl https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.exchangerate.host/latest" \
  -H "X-Circuit-Breaker: on" \
  -H "X-Smart-Cache: 600s"
# Нормально: отримує курси від upstream, кешує в Redis
# Контур OPEN (upstream відмовив):
# → Відразу повертає кешовані курси з Redis
# → Відповідь: X-Rescued: cache
# → Жодного виклику upstream

2. Circuit Breaker + Failover URL

При відкритому контурі — автоматично переключитись на backup провайдера:

curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://primary-bank.com/api/charge" \
  -H "X-Failover-URL: https://backup-bank.com/api/charge" \
  -H "X-Circuit-Breaker: on" \
  -H "X-Retry-Count: 2" \
  -d '{"amount": 5000, "currency": "usd"}'
# Контур primary-bank.com OPEN → одразу пробує backup-bank.com
# → X-Rescued: failover

3. Повний стек надійності

curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.openai.com/v1/chat/completions" \
  -H "X-Identity-Key: Bearer sk-proj-..." \
  -H "X-Circuit-Breaker: on" \
  -H "X-Retry-Count: 3" \
  -H "X-Retry-Delay: 500ms" \
  -H "X-Smart-Cache: 3600s" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Привіт"}]}'
# При збої OpenAI:
# 1. Контур CLOSED → продовжує
# 2. Спроба 1 → 503 → чекаємо ~500ms
# 3. Спроба 2 → 503 → чекаємо ~1s
# 4. Спроба 3 → 503 → чекаємо ~2s
# 5. Всі провалились → Smart Cache → X-Rescued: cache
# 6. Після 5 збоїв → контур відкривається на 15с

Перехід станів контуру

Запит → перевіряємо Redis ключ "cb:state:{host}"
    │
    ├─ Не знайдено (CLOSED) → спроба upstream
    │        │
    │        ├─ Успіх → del "cb:fails:{host}" → CLOSED
    │        └─ Збій → INCR "cb:fails:{host}" TTL=60s
    │                     └─ fails >= 5 → SET "cb:state:{host}" "OPEN" TTL=15s
    │
    └─ Знайдено "OPEN" → блокуємо запит
             └─ Після 15s TTL expires → ключ зник → CLOSED (наступний запит зондує)