Circuit Breakers

सर्किट ब्रेकर पैटर्न आपके एप्लिकेशन को किसी विफल हो रहे अपस्ट्रीम API पर बार-बार अनुरोध भेजने से रोकता है, जिससे वह API रिकवर हो सके और आपका अनुरोध बजट तथा रिस्पॉन्स समय सुरक्षित रहे।

यह कैसे काम करता है

MirApi Redis में प्रत्येक टार्गेट host की विफलताओं को ट्रैक करता है। सर्किट तीन अवस्थाओं में रहता है:

CLOSED -> (60s में 5 विफलताएं) -> OPEN -> (15s कूलडाउन) -> probe request
                                                              |
                                                       सफलता -> CLOSED
                                                       विफलता -> फिर OPEN

CLOSED: सामान्य संचालन। सभी अनुरोध पास-थ्रू होते हैं।
OPEN: पिछले एक मिनट में अपस्ट्रीम 5+ बार विफल हो चुका है। नए अनुरोध तुरंत ब्लॉक हो जाते हैं — कोई अपस्ट्रीम कॉल नहीं की जाती। यदि Smart Cache सक्रिय है तो कैश्ड रिस्पॉन्स दिया जाता है, अन्यथा एरर लौटाया जाता है।
HALF-OPEN (अंतर्निहित): OPEN अवस्था में 15 सेकंड बाद सर्किट Redis से स्वतः समाप्त हो जाता है और अगला अनुरोध अपस्ट्रीम को probe करता है। यदि probe सफल हो तो सर्किट 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`	टार्गेट host के लिए सर्किट ब्रेकर सक्षम करें

सर्किट ब्रेकर पैरामीटर (स्थिर)

सर्किट ब्रेकर स्थिर पैरामीटर का उपयोग करता है — इन्हें फिलहाल प्रति-अनुरोध बदला नहीं जा सकता:

पैरामीटर	मान	विवरण
विफलता सीमा	5	सर्किट खोलने के लिए आवश्यक विफलताओं की संख्या
विंडो	60 सेकंड	Redis में विफलता गणना की समय-सीमा
Open TTL	15 सेकंड	probe से पहले सर्किट कितनी देर OPEN रहता है
स्कोप	प्रति host	विफलताएं प्रत्येक टार्गेट hostname के अनुसार ट्रैक की जाती हैं

उपयोग के मामले

1. पेमेंट API के लिए बेसिक सर्किट ब्रेकर

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-Identity-Key: Bearer sk_live_..." \
  -H "X-Circuit-Breaker: on" \
  -H "Content-Type: application/json" \
  -d '{"amount": 9900, "currency": "usd", "source": "tok_visa"}'
# यदि Stripe पिछले 60s में 5+ बार लगातार विफल हो चुका है:
# -> अनुरोध तुरंत ब्लॉक हो जाता है (कोई अपस्ट्रीम कॉल नहीं)
# -> 503 Service Unavailable लौटाता है (जब तक Smart Cache सक्रिय न हो)

2. सर्किट ब्रेकर + Smart Cache (अनुशंसित)

जब सर्किट OPEN हो, तो एरर लौटाने की बजाय अंतिम कैश्ड रिस्पॉन्स दिया जाए। यह सबसे सामान्य प्रोडक्शन पैटर्न है:

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"
# सामान्य: अपस्ट्रीम से रेट्स लेकर 10 मिनट के लिए Redis में कैश करता है
# यदि सर्किट खुलता है (अपस्ट्रीम डाउन है):
# -> Redis से कैश्ड रेट्स देता है
# -> रिस्पॉन्स में शामिल होता है: X-Rescued: cache
# -> कोई अपस्ट्रीम कॉल नहीं -> समय/पैसे की बर्बादी नहीं

3. सर्किट ब्रेकर + Failover URL

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" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "currency": "usd"}'
# primary-bank.com का सर्किट OPEN है -> तुरंत backup-bank.com आज़माता है
# रिस्पॉन्स में शामिल होता है: X-Rescued: failover

4. सर्किट ब्रेकर + Retry + Cache (पूर्ण रेज़िलिएंस स्टैक)

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" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'
# OpenAI आउटेज पर प्रवाह:
# 1. सर्किट जांच -> CLOSED -> आगे बढ़ता है
# 2. प्रयास 1 -> 503 -> 500ms + jitter प्रतीक्षा
# 3. प्रयास 2 -> 503 -> 1s + jitter प्रतीक्षा
# 4. प्रयास 3 -> 503 -> 2s + jitter प्रतीक्षा
# 5. सभी retry विफल -> Smart Cache जांच -> अंतिम रिस्पॉन्स दिया जाता है
# 6. कुल 5 विफलताओं के बाद -> सर्किट खुलता है -> अगले 15s: कोई अपस्ट्रीम कॉल नहीं

5. Async मोड में सर्किट ब्रेकर

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 "X-Webhook-Callback: https://your-app.com/webhook" \
  -H "X-Retry-Count: 5" \
  -H "Content-Type: application/json" \
  -d '{"amount": 9900, "currency": "usd"}'
# Worker प्रत्येक retry प्रयास से पहले सर्किट की अवस्था जांचता है
# जब सर्किट खुलता है: retry से पहले उसके रीसेट होने की प्रतीक्षा करता है

सर्किट अवस्था संक्रमण को समझना

अनुरोध आता है -> Redis key "cb:state:{host}" जांचें
     |
     +- नहीं मिला (CLOSED) -> अपस्ट्रीम का प्रयास
     |        |
     |        +- सफलता -> "cb:fails:{host}" हटाएं -> CLOSED
     |        +- विफलता -> INCR "cb:fails:{host}" TTL=60s
     |                        +- fails >= 5 -> SET "cb:state:{host}" "OPEN" TTL=15s
     |
     +- "OPEN" मिला -> अनुरोध ब्लॉक
               +- 15s TTL समाप्त -> key हट जाता है -> CLOSED (अगला अनुरोध probe करता है)