मल्टी-टारगेट कैस्केड रूटिंग

कैस्केड रूटिंग आपको एक ही अनुरोध के लिए कई अपस्ट्रीम टारगेट परिभाषित करने देता है। MirApi उन्हें अनुक्रम (Priority) या एक साथ (Race) में आज़माएगा, और पहला सफल रिस्पॉन्स लौटाएगा।

कैस्केड रूट आपके डैशबोर्ड में कॉन्फ़िगर किए जाते हैं और X-Route-Key हेडर का उपयोग करके सक्रिय किए जाते हैं।

डैशबोर्ड में रूट कॉन्फ़िगर करें

कैस्केड रूटिंग का उपयोग करने से पहले, अपने MirApi डैशबोर्ड में एक रूट बनाएं:

1. Routes → Create Route खोलें
2. एक नाम सेट करें (उदा. ai-providers)
3. टारगेट जोड़ें (उदा. https://api.openai.com/v1/chat/completions, https://api.anthropic.com/v1/messages)
4. स्ट्रेटेजी चुनें: Priority या Race
5. प्रति-टारगेट टाइमआउट सेट करें (ms में)
6. वैकल्पिक रूप से बॉडी मैपिंग और रिस्पॉन्स एक्सट्रैक्शन नियम कॉन्फ़िगर करें

रूट सक्रिय करें

curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Route-Key: ai-providers" \
  -H "X-Identity-Key: Bearer $OPENAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

कैस्केड स्ट्रेटेजी (Cascade Strategies)

Priority (क्रमिक फ़ेलओवर)

टारगेट को क्रम से आज़माया जाता है। अगला टारगेट केवल तभी आज़माया जाता है जब पिछला टारगेट विफल हो जाता है (5xx, टाइमआउट, या कनेक्शन त्रुटि)।

टारगेट 1: https://api.openai.com/...  → विफल (503)
टारगेट 2: https://api.anthropic.com/... → विफल (टाइमआउट)
टारगेट 3: https://api.groq.com/...   → सफल ✓

प्रतिक्रिया: X-Rescued: cascade_fallback

Race (समानांतर)

सभी टारगेट को एक साथ कॉल किया जाता है। सबसे तेज़ सफल प्रतिक्रिया जीतती है; अन्य को रद्द कर दिया जाता है।

रूट टारगेट ऑथेंटिकेशन (Route Target Auth)

कैस्केड रूटिंग आपको एक ही रूट के भीतर प्रत्येक अलग अपस्ट्रीम सेवा (target_url) के लिए अद्वितीय प्रमाणीकरण (unique authorization) कॉन्फ़िगर करने की अनुमति देती है।

यह क्यों महत्वपूर्ण है?

पहले, जब कैस्केड (उदा. Stripe ➔ Adyen ➔ Custom Bank) के साथ किसी अनुरोध को अग्रेषित किया जाता था, तो प्रॉक्सी सभी सेवाओं के लिए एक साझा प्रमाणीकरण हेडर का उपयोग करने का प्रयास करता था। इसने कैस्केड की उपयोगिता को सीमित कर दिया था, क्योंकि विभिन्न भुगतान गेटवे और API को प्रमाणीकरण के विभिन्न प्रारूपों (formats of authentication) की आवश्यकता होती है।

अब, आप कैस्केड में प्रत्येक सेवा को डेटाबेस से अपने स्वयं के क्रेडेंशियल के साथ सुरक्षित रूप से जोड़ सकते हैं, जिसमें प्रत्येक टारगेट के लिए एक कस्टम HTTP हेडर नाम और कुंजी इंटरपोलेशन टेम्पलेट निर्दिष्ट किया जा सकता है।

---

कॉन्फ़िगर कैसे करें (उदाहरण)

एक कैस्केड रूट payment-cascade की कल्पना करें। यदि प्राथमिक गेटवे (Stripe) कोई त्रुटि लौटाता है, तो अनुरोध स्वचालित रूप से बैकअप गेटवे (Custom Bank API) पर रूट हो जाता है। दोनों का अपना प्रमाणीकरण प्रारूप है।

इस रूट को बनाने या अपडेट करने के लिए एक उदाहरण JSON पेलोड यहां दिया गया है:

{
  "route_key": "payment-cascade",
  "strategy": "priority",
  "targets": [
    {
      "priority": 1,
      "target_url": "https://api.stripe.com/v1/charges",
      "timeout_ms": 10000,
      "credential_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "auth_header": "Authorization",
      "auth_template": "Bearer {{secret}}"
    },
    {
      "priority": 2,
      "target_url": "https://api.custombank.com/v1/payments",
      "timeout_ms": 15000,
      "credential_id": "c3098522-8356-4c91-9e2c-29ad9c42c943",
      "auth_header": "X-Bank-Token",
      "auth_template": "{{secret}}"
    }
  ]
}

पैरामीटर विवरण (Parameter Details):

• credential_id (वैकल्पिक): आपके Credentials वॉल्ट में सुरक्षित एन्क्रिप्टेड क्रेडेंशियल की UUID। यदि खाली छोड़ दिया जाता है (null / ""), तो इस टारगेट को अनुरोध बिना प्रमाणीकरण (या क्लाइंट के मूल हेडर के साथ) भेजा जाता है।
• auth_header (डिफ़ॉल्ट: Authorization): उस HTTP हेडर का नाम जहां प्रॉक्सी कुंजी डालेगा।
• auth_template (डिफ़ॉल्ट: Bearer {{secret}}): फ़ॉर्मेटिंग टेम्पलेट। प्रॉक्सी आपके X-Proxy-Master-Key का उपयोग करके टोकन को स्वचालित रूप से डिक्रिप्ट करेगा और {{secret}} प्लेसहोल्डर को वास्तविक डिक्रिप्टेड कुंजी से बदल देगा।

एज-स्तरीय सुरक्षा (Edge-Level Security)

सभी क्रेडेंशियल्स (credential_id) डेटाबेस में AES-GCM एल्गोरिथ्म का उपयोग करके एन्क्रिप्ट करके संग्रहीत किए जाते हैं। डिक्रिप्शन अनुरोध निष्पादन के समय केवल मेमोरी में किया जाता है, जिसके लिए क्लाइंट द्वारा अनुरोध हेडर में प्रदान की गई X-Proxy-Master-Key का उपयोग किया जाता है। डिक्रिप्शन कुंजी कभी भी हमारे डिस्क पर संग्रहीत नहीं की जाती हैं।

---

टारगेट अनुरोध बॉडी मैपिंग (Target Request Body Mapping)

कैस्केड रूट में विभिन्न एंडपॉइंट अक्सर JSON अनुरोध बॉडी में अलग-अलग फ़ील्ड नामों की अपेक्षा करते हैं। अपने क्लाइंट कोड को बदले बिना इसे संभालने के लिए, प्रत्येक कैस्केड टारगेट डेटाबेस में एक body_map को परिभाषित कर सकता है।

मैपिंग नियम का प्रारूप अल्पविराम से अलग की गई सूची है: original_field=>new_field।

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

1. आपका क्लाइंट मूल JSON संरचना के साथ प्रॉक्सी गेटवे को अनुरोध भेजता है।
2. गेटवे बॉडी को इंटरसेप्ट करता है और उसे टारगेट पर फॉरवर्ड करने से पहले, उस टारगेट के body_map नियम के अनुसार मिलान की गई कुंजियों का नाम बदल देता है।

उदाहरण परिदृश्य: आपका एप्लिकेशन एक चार्ज अनुरोध भेजता है:

{
  "amount": 9900,
  "currency": "usd",
  "customer_id": "cus_123"
}

• टारगेट 1 (Stripe) amount और currency की अपेक्षा करता है। कोई मैपिंग परिभाषित नहीं है।
• टारगेट 2 (वैकल्पिक गेटवे) amount के स्थान पर sum और currency के स्थान पर cur की अपेक्षा करता है।
  • कॉन्फ़िगर किया गया body_map: amount=>sum, currency=>cur
  • अपस्ट्रीम को मिलता है: {"sum": 9900, "cur": "usd", "customer_id": "cus_123"}

---

कस्टम बॉडी फॉलबैक स्थितियां (Custom Body Fallback Conditions)

डिफ़ॉल्ट रूप से, कैस्केड रूटिंग अगले फॉलबैक को केवल तभी ट्रिगर करता है जब कोई टारगेट एंडपॉइंट 5xx स्टेटस कोड लौटाता है, टाइमआउट हो जाता है, या नेटवर्क त्रुटियों का सामना करता है।

हालाँकि, कई API (विशेष रूप से भुगतान गेटवे) लेन-देन अस्वीकृत या विफल होने पर भी 200 OK स्थिति लौटाते हैं। व्यावसायिक तर्क विफलताओं पर रूटिंग का समर्थन करने के लिए, प्रत्येक रूट टारगेट डैशबोर्ड/डेटाबेस में दो मापदंडों का उपयोग करके एक कस्टम फॉलबैक स्थिति परिभाषित कर सकता है:

• fallback_field: प्रतिक्रिया JSON में जांचे जाने वाले फ़ील्ड को इंगित करने वाला एक JSONPath अभिव्यक्ति (उदा. $.status, $.error.code)।
• fallback_value: मिलान करने के लिए एक स्ट्रिंग मान (केस-असंवेदनशील सबस्ट्रिंग जांच)।

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

1. टारगेट एंडपॉइंट सफल स्थिति कोड (500 से कम) के साथ प्रतिक्रिया करता है।
2. गेटवे प्रतिक्रिया बॉडी को पढ़ता है और JSONPath का उपयोग करके fallback_field से मान निकालता।
3. यदि निकाले गए मान में सबस्ट्रिंग के रूप में fallback_value शामिल है, तो गेटवे प्रतिक्रिया को विफलता के रूप में मानता है।
4. गेटवे प्रतिक्रिया को खारिज कर देता है, फॉलबैक ट्रिगर को लॉग करता है, और तुरंत कैस्केड श्रृंखला में अगले टारगेट पर वापस आ जाता है।

उदाहरण: भुगतान अस्वीकृत फ़ॉलबैक (Payment Declined Fallback)

एक अपस्ट्रीम भुगतान प्रोसेसर 200 OK लौटाता है लेकिन भुगतान अस्वीकृत कर देता है:

{
  "transaction_id": "tx_abc123",
  "status": "declined",
  "failure_reason": "insufficient_funds"
}

टारगेट को कॉन्फ़िगर करके:

• Fallback Field: $.status
• Fallback Value: declined

GateWay 200 OK को इंटरसेप्ट करता है, देखता है कि $.status "declined" के बराबर है, इसे एक विफलता के रूप में मानता है, और आपके कैस्केड में अगले बैकअप बैंक टारगेट पर भुगतान अनुरोध रूट करता है।

---

लूप रोकथाम रणनीति (Anti-Loop Protection)

गेटवे अपने स्वयं के IP पतों और होस्टनामों के विरुद्ध सभी टारगेट URL को मान्य करता है। कोई भी टारगेट URL जो प्रॉक्सी को ही संदर्भित करता है, अनंत अनुरोध लूप को रोकने के लिए 400 Bad Request के साथ खारिज कर दिया जाता है।

कैस्केड के लिए प्रतिक्रिया हेडर (Response Headers for Cascade)

जब एक गैर-प्राथमिक (non-primary) टारगेट का उपयोग किया जाता है, तो प्रतिक्रिया में शामिल होता है:

HTTP/1.1 200 OK
X-Rescued: cascade_fallback

यदि प्राथमिक टारगेट (सूची में पहला) सफल होता है, तो कोई X-Rescued हेडर नहीं जोड़ा जाता है।