टारगेट रेट-लिमिटिंग आउटबाउंड कतारें (Target Queues)

टारगेट रेट-लिमिटिंग आउटबाउंड क्यू सिस्टम (Target Rate-Limiting Outbound Queue System / Outbound Throttling Engine) एक गेटवे विश्वसनीयता मॉड्यूल है जिसे sudden high-concurrency रिक्वेस्ट स्पाइक्स से टारगेट CMS, ERP, ई-कॉमर्स (जैसे WooCommerce, Shopify, 1C ERP) और वित्तीय बैकएंड को क्रैश होने से बचाने के लिए डिज़ाइन किया गया है।

डाउनस्ट्रीम सिस्टम्स पर एक साथ सैकड़ों समवर्ती API कॉल करने के बजाय, गेटवे टारगेट डोमेन कतार से मेल खाने वाले गैर-GET अनुरोधों को इंटरसेप्ट करता है, तुरंत कॉलर को 202 Accepted प्रतिक्रिया देता है, और कतारबद्ध अनुरोधों को कड़ाई से नियंत्रित दर (RPS) पर डाउनस्ट्रीम पर भेजता है।

---

प्लान सीमाएं और पहुंच नियंत्रण

कतार उपलब्धता और सीमाएं आपके सक्रिय सब्सक्रिप्शन प्लान पर निर्भर करती हैं:

सब्सक्रिप्शन प्लान	अनुमत सक्रिय कतारें	कतार इंटरसेप्शन व्यवहार
Free	0	कतार निर्माण अवरुद्ध (403 Forbidden)। प्रॉक्सी कतार इंटरसेप्शन बायपास होता है; अनुरोध सीधे चलते हैं।
Developer	1	1 सक्रिय टारगेट रेट-लिमिटिंग कतार तक।
Business & Enterprise	5 तक	5 सक्रिय टारगेट रेट-लिमिटing कतारों तक।

---

कॉन्फ़िगरेशन पैरामीटर

क्लाइंट डैशबोर्ड UI के माध्यम से सीधे टारगेट कतारों को कॉन्फ़िगर और प्रबंधित कर सकते हैं।

पैरामीटर	प्रकार	सत्यापन / बाधाएं	विवरण
name	String	1–100 वर्ण	मानव-पठनीय कतार लेबल (उदा. ERP Orders Queue)
target_domain	String	मान्य डोमेन	मिलान करने के लिए टारगेट होस्ट डोमेन (उदा. api.mysite.com)
max_rate_rps	Integer	1 से 50 RPS	प्रति सेकंड अधिकतम आउटबाउंड प्रेषण दर सीमा।
max_queue_size	Integer	100 से 10,000	Redis बफर में अनुमत लंबित अनुरोधों की अधिकतम संख्या।
message_ttl_seconds	Integer	300s (5m) से 10,800s (3h)	अनहैंडल्ड जॉब्स की समय सीमा समाप्त होने से पहले होल्ड TTL।
notify_on_failure	Boolean	true / false	ड्रॉप/TTL/विफलता पर डेड-लेटर वेबहुक सूचनाएं सक्षम करें।
webhook_url	String	मान्य HTTP/HTTPS URL	डेड-लेटर क्यू (DLQ) ड्रॉप सूचनाओं के लिए कॉलबैक श्रोता URL।

---

अनुरोध प्रसंस्करण जीवन चक्र

[क्लाइंट अनुरोध]
       │
       ▼
┌───────────────────────────────┐
│ प्रमाणीकरण और योजना जांच     │
└──────────────┬────────────────┘
               │
       क्या पेड प्लान है (Dev/Biz)?
          ├── नहीं (Free) ──────► कतार बायपास करें (प्रत्यक्ष प्रॉक्सी निष्पादन)
          └── हां
               │
       क्या विधि != GET और टारगेट कतार सक्रिय है?
          ├── नहीं (GET / रोका गया) ──► कतार बायपास करें (प्रत्यक्ष प्रॉक्सी निष्पादन)
          └── हां
               │
┌──────────────▼────────────────┐
│ Redis बफ़र में कतारबद्ध करें  │
│ तत्काल 202 Accepted (<2ms)    │
└──────────────┬────────────────┘
               │
               ▼
┌───────────────────────────────┐
│ आउटबाउंड रेट लिमिटर कार्यकर्ता  │ (Atomic Redis SetNX Lock Window = 1000ms / RPS)
└──────────────┬────────────────┘
               │
               ▼
┌───────────────────────────────┐
│ डाउनस्ट्रीम प्रॉक्सी निष्पादन │ (X-Retry-Count, X-Proxy-Timeout आदि सुरक्षित रखता है)
└──────────────┬────────────────┘
               │
       ┌───────┴───────┐
       ▼               ▼
[200 OK प्रतिक्रिया] [5xx / TTL समाप्त]
       │               │
 लॉग एक्सेस मीट्रिक      डेड-लेटर वेबहुक ट्रिगर करें (यदि सक्षम हो)

मुख्य निष्पादन नियम

1. GET अनुरोध: हमेशा टारगेट कतारों को बायपास करते हैं और सीधे मानक प्रॉक्सी पाइपलाइन के माध्यम से चलते हैं।
2. रोकें स्थिति (is_active = false): रोके जाने पर, कतार इंटरसेप्शन बायपास हो जाता है और अनुरोध सीधे डाउनस्ट्रीम लक्ष्यों पर पास होते हैं।
3. लचीलापन संरक्षण: कतारबद्ध कार्य सभी मूल लचीलापन हेडर (X-Retry-Count, X-Proxy-Timeout, X-Smart-Cache, X-Failover-URL) को बनाए रखते हैं।
4. डेड-लेटर वेबहुक: कतार अतिप्रवाह, TTL समाप्ति, या अपस्ट्रीम विफलता पर, यदि notify_on_failure true है तो webhook_url पर एक POST अधिसूचना भेजी जाती है।

---

क्लाइंट उपयोग के उदाहरण

1. हाई-कनकसी POST अनुरोध को कतारबद्ध करना

अनुरोध:

curl --location 'https://proxy.mirapi.io/' \
  --header 'X-MirApi-Key: your_api_key_here' \
  --header 'X-Target-URL: https://api.mysite.com/v1/orders' \
  --header 'X-Retry-Count: 3' \
  --header 'X-Proxy-Timeout: 15s' \
  --header 'Content-Type: application/json' \
  --data '{
    "order_id": "ORD-99214",
    "customer": "John Doe",
    "amount": 149.99
  }'

तुल्यकालिक प्रतिक्रिया (< 2ms):

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "status": "queued",
  "job_id": "1c7f8499-66dc-4689-99ff-f74837afa5ee",
  "queue_id": "52f00232-78b0-465b-a6ec-5103459b8a16",
  "target_domain": "api.mysite.com",
  "message": "Request queued for rate-throttled outbound execution"
}

---

2. URL क्वेरी पैरामीटर फ़ॉलबैक (Shopify / थर्ड-पार्टी वेबहुक)

यदि आपका वेबहुक निर्माता कस्टम HTTP हेडर कॉन्फ़िगर करने की अनुमति नहीं देता है, तो URL क्वेरी पैरामीटर के माध्यम से ऑर्केस्ट्रेशन फ़्लैग पास करें:

curl --location 'https://proxy.mirapi.io/?apiKey=your_api_key_here&target=https://api.mysite.com/v1/orders&retry_count=3&timeout=15s' \
  --header 'Content-Type: application/json' \
  --data '{"order_id": "ORD-1002"}'

संकेत

Shopify या GitHub जैसे तीसरे पक्ष के एकीकरण के लिए जहां कस्टम हेडर निर्दिष्ट नहीं किए जा सकते हैं, क्वेरी पैरामीटर अलियास सटीक समान कार्यक्षमता प्रदान करते हैं। URL क्वेरी पैरामीटर कॉन्फ़िगरेशन संदर्भ देखें।

---

3. डेड-लेटर क्यू (DLQ) नोटिफिकेशन पेलोड

जब कोई कतारबद्ध कार्य पुनः प्रयासों के बाद विफल हो जाता है या कतार (TTL) में समाप्त हो जाता है, तो गेटवे आपके कॉन्फ़िगर किए गए webhook_url पर एक अधिसूचना पोस्ट करता है:

POST /webhooks/dlq HTTP/1.1
Host: mycrm.com
Content-Type: application/json

{
  "job_id": "1c7f8499-66dc-4689-99ff-f74837afa5ee",
  "queue_id": "52f00232-78b0-465b-a6ec-5103459b8a16",
  "user_id": "8a852528-d79d-4da5-8e12-89b9fbde8554",
  "target_url": "https://api.mysite.com/v1/orders",
  "target_domain": "api.mysite.com",
  "reason": "upstream_failure",
  "error_message": "upstream returned status code: 500",
  "created_at": "2026-08-02T21:08:35Z",
  "failed_at": "2026-08-02T21:08:37Z"
}

सावधानी

उत्पादन कतारों पर हमेशा webhook_url कॉन्फ़िगर करें और notify_on_failure को true पर सेट करें ताकि डाउनस्ट्रीम एपीआई अनुरोधों को छोड़ने या TTL सीमाओं से अधिक होने पर आपका सिस्टम तुरंत सूचित हो सके।