Черги для контролю вихідного трафіку (Target Queues)

Система асинхронних вихідних черг захищає цільові системи (CMS, ERP, інтернет-магазини на кшталт Shopify, WooCommerce, 1C ERP та фінансові бекенди) від перевантажень і падінь під час пікових сплесків трафіку.

Як це працює

Замість того, щоб блокувати клієнтів або перевантажувати downstream-системи сотнями одночасних API-викликів, шлюз розподіляє процес на три етапи:

Миттєвий розвантажувальний response Шлюз перехоплює запити на зміну даних (усі мутаційні запити, крім GET), зберігає їх у чергу та одразу повертає клієнту статус відповіді:
```
HTTP/1.1 202 Accepted
Клієнт не чекає обробки та не отримує помилок за таймаутом.
```
Дозована передача (Throttling) Запити з черги надсилаються до цільової системи із суворо контрольованою швидкістю (RPS), яку здатен безперебійно витримати її бекенд.
Гарантія доставки Жоден запит не втрачається, навіть якщо цільова система тимчасово уповільнилась або недоступна.

Тарифні ліміти та контроль доступу

Доступність та ліміти черг залежать від вашого активного тарифного плану:

Тарифний план	Дозволені активні черги	Поведінка перехоплення черги
Free	0	Створення черги заблоковано (`403 Forbidden`). Перехоплення чергою пропускається; запити виконуються напряму.
Developer	1	До 1 активної черги обмеження вихідної швидкості.
Business & Enterprise	До 5	До 5 активних черг обмеження вихідної швидкості.

Параметри конфігурації

Клієнти можуть налаштовувати та керувати цільовими чергами безпосередньо через дашборд (Dashboard 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	від 300с (5хв) до 10,800с (3год)	Час життя (TTL) перед тим, як необроблені завдання закінчать термін дії.
`notify_on_failure`	Boolean	`true` / `false`	Увімкнути сповіщення Dead-Letter Webhook при скиданні/закінченні TTL/помилці.
`webhook_url`	String	Дійсний HTTP/HTTPS URL	URL-адреса слухача для сповіщень про скидання з черги Dead-Letter Queue (DLQ).

Життєвий цикл обробки запиту

[Запит клієнта]
       │
       ▼
┌───────────────────────────────┐
│ Перевірка аутентифікації/плану│
└──────────────┬────────────────┘
               │
       Платний план (Dev/Biz)?
          ├── Ні (Free) ───────► Обхід черги (Пряме виконання проксі)
          └── Так
               │
       Метод != GET та черга активна?
          ├── Ні (GET / Пауза) ──► Обхід черги (Пряме виконання проксі)
          └── Так
               │
┌──────────────▼────────────────┐
│ Додавання в Redis-буфер       │
│ Негайний 202 Accepted (<2ms)  │
└──────────────┬────────────────┘
               │
               ▼
┌───────────────────────────────┐
│ Outbound Rate Limiter Worker  │ (Atomic Redis SetNX Lock Window = 1000ms / RPS)
└──────────────┬────────────────┘
               │
               ▼
┌───────────────────────────────┐
│ Виконання downstream-проксі   │ (Зберігає X-Retry-Count, X-Proxy-Timeout тощо)
└──────────────┬────────────────┘
               │
       ┌───────┴───────┐
       ▼               ▼
[200 OK Відповідь] [5xx / TTL Завершено]
       │               │
 Запис метрики доступності   Виклик Dead-Letter Webhook (якщо увімкнено)

Ключові правила виконання

GET-запити: Завжди обходять цільові черги та виконуються напряму через стандартний пайплайн проксі.
Стан паузи (is_active = false): У стані паузи перехоплення чергою вимикається, і запити проходять напряму до цільових систем.
Збереження надійності: Завдання в черзі зберігають усі оригінальні заголовки надійності (X-Retry-Count, X-Proxy-Timeout, X-Smart-Cache, X-Failover-URL).
Dead-Letter Webhook: При переповненні черги, закінченні TTL або збої upstream надсилається POST-сповіщення на webhook_url, якщо notify_on_failure має значення true.

Приклади використання

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
  }'

Синхронна відповідь (< 2 мс):

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 Query Parameters (для Shopify / Сторонніх вебхуків)

Якщо ваш постачальник вебхуків не дозволяє налаштовувати кастомні HTTP-заголовки, передавайте прапорці оркестрації через URL query parameters:

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"}'

3. Пейлоад сповіщення Dead-Letter Queue (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"
}