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

Упорядкована доставка показує отримувачу події ендпоінта в тому порядку, в якому їх створено. Типово її вимкнено; вона діє в межах одного ендпоінта й лише для вихідних доставок.

Як увімкнути

Задайте orderingEnabled у підписці:

curl -X POST "$RAILHOOK_URL/api/v1/projects/$PROJECT_ID/subscriptions" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"endpointId":"'"$ENDPOINT_ID"'","eventType":"order.*","orderingEnabled":true}'

Без упорядкування доставки на той самий ендпоінт можуть обганяти одна одну, і саме це дає більшу частину пропускної здатності.

Як це працює

Термін	Значення
Порядковий номер	Позиція кожної доставки на ендпоінт, за якою видно, яка з двох доставок була першою, хоч би коли воркер їх узяв. Надсилається в X-Sequence-Number; коли упорядкування вимкнено, дорівнює 0.
Буфер порядку	Тут доставка чекає, доки не завершаться доставки перед нею. Очікування є відкладенням: воно не витрачає спробу.
Розрив	Діапазон між останньою позицією, яку отримав ендпоінт, і доставкою, що чекає, де є принаймні одна незавершена доставка. Railhook перевіряє весь діапазон, а не лише попередню позицію.

Доставку надсилають лише тоді, коли всі доставки перед нею на цей ендпоінт пройшли успішно або їх полишено. Доставка, перенесена в «Недоставлені повідомлення», перестає блокувати наступні.

Коли розрив ніколи не закривається

Без обмеження одна доставка, яка ніколи не завершиться, назавжди заблокувала б ендпоінт. Тому щойно доставка, що чекає, вичекала тайм-аут розриву і в розриві вже ніщо не рухається, Railhook пропускає її поза порядком і рахує цю подію.

Важливі обидві умови. Доставка між двома повторними спробами є розривом, який ось-ось закриється, тож наступні доставки чекають на неї, скільки б уже не прочекали. Інакше перша ж звичайна повторна спроба ламала б порядок, бо перший інтервал повтору і тайм-аут розриву однакові: одна хвилина. Тайм-аут пропускає лише розрив, у якому нічого не виконується і нічого не заплановано.

Налаштування	Типово
ORDERING_GAP_TIMEOUT_SECONDS	60
Метрика	webhook_ordering_gap_timeout_total

Гарантія поступається, а не блокує

Ендпоінт, який не отримує нічого, є гіршим збоєм, тому порядок порушується навмисно. Поодиноке зростання webhook_ordering_gap_timeout_total нормальне. Стабільне зростання означає, що якась доставка попереду не завершується і ендпоінт насправді не отримує впорядкованої доставки.

Чого це коштує

Ціна	Чому
Пропускна здатність	Упорядкований ендпоінт фактично обробляє доставки по одній. Його час відповіді стає вашою стелею.
Блокування на початку черги (head-of-line blocking)	Одна повільна чи невдала доставка затримує всі наступні, доки не завершиться сама або не спрацює тайм-аут розриву.
Відтворення стає в кінець	Відтворення створює нові доставки з новими порядковими номерами, тож відтворена подія приходить після тих, що вже чекають, а не на своє початкове місце.

Що обіцяно, а що ні

• Порядок діє в межах ендпоінта, а не глобально. Два ендпоінти, підписані на ту саму подію, отримують її незалежно.
• Доставка, як і раніше, at-least-once (щонайменше один раз). Відкидайте дублікати за X-Delivery-Id або Idempotency-Key.
• Через тайм-аут розриву порядок гарантовано лише за можливості (best-effort). Якщо потрібен порядок, який ніколи не поступається, додайте у вміст власне поле з порядковим номером і перевіряйте його в отримувачі.
• Для вхідних вебхуків упорядкування немає: Railhook не може знати, який порядок мав на увазі провайдер. Скористайтеся полем порядкового номера провайдера, якщо воно є.