Vebxuklarni yetkazib berish kafolatlari

Vebxuklar - HTTP (S) orqali «tizimdan obunachiga» asinxron xabarnomalar. Tarmoq ishonchsiz: javoblar yoʻqoladi, paketlar dublikat sifatida yoki tartibdan tashqarida keladi. Shuning uchun yetkazib berish kafolatlari «TCP bo’yicha» emas, balki vebxuk protokoli va domen idempotentligi darajasida quriladi.

Asosiy maqsad: at-least-once-ni kalit bo’yicha (kerak bo’lganda) tartibda yetkazib berishni ta’minlash, obunachiga idempotent ishlov berish uchun materiallar va tiklash uchun reconcile vositasini berish.

1) Kafolatlar darajalari

Best-effort - bir martalik urinish, retrajsiz. Faqat «ahamiyatsiz» voqealar uchun maqbuldir.
At-least-once (tavsiya etiladi) - dublikatlar va out-of-order mumkin, ammo tadbir obunachi oqilona muddatda mavjud bo’lgan taqdirda yetkazib beriladi.
Effectively-exactly-once (effekt darajasida) - obunachi/jo’natuvchi tomonidagi idempotentlik va dedup-saqlash kombinatsiyasi orqali erishiladi. HTTP transportida «exactly-once» mumkin emas.

2) Vebxuk kontrakti: minimal zarur

X-Webhook-Id: 5d1e6a1b-4f7d-4a3d-8b3a-6c2b2f0f3f21  # глобальный ID события
X-Delivery-Attempt: 3                 # номер попытки
X-Event-Type: payment.authorized.v1          # тип/версия
X-Event-Time: 2025-10-31T12:34:56Z          # ISO8601
X-Partition-Key: psp_tx_987654            # ключ порядка
X-Seq: 418                      # монотонный номер по ключу
X-Signature-Alg: HMAC-SHA256
X-Signature: t=1730378096,v1=hex(hmac(secret, t        body))
Content-Type: application/json

json
{
"id": "5d1e6a1b-4f7d-4a3d-8b3a-6c2b2f0f3f21",
"type": "payment.authorized.v1",
"occurred_at": "2025-10-31T12:34:56Z",
"partition_key": "psp_tx_987654",
"sequence": 418,
"data": {
"payment_id": "psp_tx_987654",
"amount": "10.00",
"currency": "EUR",
"status": "AUTHORIZED"
},
"schema_version": 1
}

Oluvchiga qo’yiladigan talab: imzoni buferlash va validatsiyadan so’ng tezda’2xx’ga javob berish, biznes-ishlov berishni esa asinxron tarzda amalga oshirish.

3) Tartib va sabablar

Kalit tartibi: kafolat faqat bitta’partition _ key’ichida «ketmaydi» (masalan,’player _ id’,’wallet _ id’,’psp _ tx _ id’).
Global tartib kafolatlanmagan.
Jo’natuvchi tomonida - kalit bo’yicha seriyalashtirilgan navbat (bitta iste’molchi/sharding), oluvchi tomonida - inbox s’(source, event_id)’va o’tkazib yuborilgan’seq’ni ixtiyoriy kutish.

Agar o’tkazib yuborish og’ir bo’lsa, pull-API’GET/events’ni taqdim eting? after = checkpoint’uchun yetib olish va tekshirish.

4) Idempotentlik va deduplikatsiya

Har bir vebxuk barqaror’X-Webhook-Id’ga ega.
Oluvchi’inbox (event_id)’saqlaydi: PK -’source + event_id'; takrorlash → no-op.
Nojo’ya ta’sirlar (DB/hamyonga yozish) hodisaning birinchi «ko’rinishida» faqat bir marta bajariladi.
Effektli buyruqlar uchun Idempotency-Key va retraj oynasi uchun natijalar keshidan foydalaning.

5) Retray, backoff va derazalar

• ’5xx/timeout/connection error/409-Conflict (retryable )/429’ ga retraj qilish.
• ’4xx’ ga’409/423/429’dan tashqari (va faqat kelishilgan semantikada) qaytara olmaysiz.
• Eksponensial backoff + full jitter: 0. 5s, 1s, 2s, 4s, 8s, … ’max = 10-15 min’ gacha; TTL retray oynalari: masalan, 72 soat.
• Qabul qiluvchida’Retry-After’ni hurmat qilish.
• Umumiy muddatga ega boʻlish: «hodisani yetkazilmagan deb topish» va uni DLQga oʻtkazish.

yaml retry:
initial_ms: 500 multiplier: 2.0 jitter: full max_delay_ms: 900000 ttl: 72h retry_on: [TIMEOUT, 5xx, 429]

6) DLQ и redrive

DLQ - to’liq metainformatsiyaga ega bo’lgan zaharli yoki TTL bo’yicha o’tgan voqealar «qabristoni» (paiload, sarlavhalar, xatolar, urinishlar, xeshlar).
Veb-konsol/redrive uchun API (nuqta bilan qayta yetkazib berish) endpoint/sirni ixtiyoriy tahrirlash.
Rate-limited redrive va batch-redrive ustuvorlik bilan.

7) Xavfsizlik

mTLS (iloji boricha) yoki TLS 1. 2+.

1. Sarlavhadan’t’(timestamp) ni olib tashlash, harakatlanuvchi oynani tekshirish (masalan, 5 daqiqa ±).

8) Kvotalar, rate limits va adolat

Fair-Queue per tenant/subscriber: bitta obunachi/tenant umumiy pulni toʻplamasligi uchun.
Chiqadigan trafik va per-endpoint uchun kvotalar va burst-limitlar.
’429’ ga munosabat:’Retry-After’ni hurmat qilish, trotlyatsiya oqimi; uzoq muddat cheklashda - degrade (faqat tanqidiy turdagi hodisalarni yuborish).

9) Obunaning hayot sikli

Register/Verify: POST endpoint → challenge/response yoki out-of-band tasdiqlash.
Lease (xohishiga ko’ra): imzo’valid _ to’gacha amal qiladi; uzaytirish - aniq.
Secret rotation: `current_secret`, `next_secret` с `switch_at`.
Test ping: asosiy topiklarni yoqishdan oldin yoʻnalishni tekshirish uchun sunʼiy hodisa.
Health-testlar: latency va TLS profilini tekshirish bilan davriy HEAD/GET.

10) Sxemalar evolyutsiyasi (voqealar versiyasi)

Hodisa turi versiyasi:’payment. authorized. v1` → `…v2`.
Evolyutsiya - additive (yangi maydonlar → MINOR versiyasi API), breaking → yangi tur.
Sxemalar registri (JSON-Schema/Euro/Protobuf) + jo’natishdan oldin avtomatik validatsiya.
Tanadagi’X-Event-Type’sarlavhasi va’schema _ version’maydoni - ikkalasi ham majburiydir.

11) Kuzatuv va SLO

• `deliveries_total`, `2xx/4xx/5xx_rate`, `timeout_rate`, `signature_fail_rate`.
• ’attempts _ avg’,’p50/p95/p99 _ delivery _ latency _ ms’(nashrdan 2xx gacha).
• `dedup_rate`, `out_of_order_rate`, `dlq_rate`, `redrive_success_rate`.
• `queue_depth`, `oldest_in_queue_ms`, `throttle_events`.

• Yetkazib berish ulushi ≤ 60 c (p95) - 99. Muhim voqealar uchun 5%.
• DLQ ≤ 0. 24 soatda 1%
• Signature failures ≤ 0. 05%.

Логи/трейсинг: `event_id`, `partition_key`, `seq`, `attempt`, `endpoint`, `tenant_id`, `schema_version`, `trace_id`.

12) Jo’natuvchining referens algoritmi

1. Hodisani tranzaksion outboxga yozib olish.
2. partition_key va seq belgilash; navbatga qo’yish.
3. Vorker kalitni oladi, so’rovni shakllantiradi, imzolaydi, taymaut bilan yuboradi (connect/read).
4. ’2xx’ da - yetkazib berilgan deb hisoblansin, latentlik va seq-chekpint qayd etilsin.
5. ’429/5xx/timeout’ da - siyosatga muvofiq retraj.
6. TTL → DLQ va alert bo’yicha.

13) Referens ishlov beruvchi (oluvchi)

1. Soʻrovni qabul qilish, TLS/proto’ni tekshirish.
2. Imzo va vaqt oynasini validatsiya qilish.
3. Tezkor ACK 2xx (lokal inbox/navbatga sinxron yozilgandan keyin).
4. Asinxron vorker’inbox’o’qiydi,’event _ id’(dedup) ni tekshiradi, zarurat bo’lganda’seq’ichidagi’partition _ key’bo’yicha tartibga soladi.
5. Effektlarni bajaradi, reconcile uchun «offset/seq checkpoint» deb yozadi.
6. Xato bo’lgan taqdirda - lokal retralar; «zaharli» vazifalar → alertli lokal DLQ.

14) Reconcile (pull-kontur)

• `GET /events? partition_key=...&after_seq=...&limit=...' - o’tkazib yuborilganlarning barchasini berish.
• ’after = opaque _ token’ oʻrniga seq.
• Idempotent redelivery: xuddi shu’event _ id’, yangi’t’bo’yicha ham xuddi shunday imzo.

15) Foydali sarlavhalar va kodlar

2xx - qabul qildi (hatto biznes-qayta ishlash keyinroq bo’lsa ham).
410 Gone - endpoint yopildi (joʻnatuvchi yetkazib berishni toʻxtatadi va obunani «arxivga» deb belgilaydi).
409/423 - resursni vaqtincha blokirovka qilish → retraj aql bilan.
429 - juda tez-tez → trottl va backoff.
400/401/403/404 - konfiguratsiya xatosi; retrajni to’xtatish, chiptani ochish.

16) Ko’p tenant va mintaqalar

Alohida navbatlar va limitlar per tenant/endpoint.
Data residency: maʼlumotlarni mintaqadan joʻnatish; «X-Tenant», «X-Region».
Xato izolatsiyasi: bitta obunachining yiqilishi boshqalarga taʼsir qilmaydi (separate pools).

17) Test sinovlari

Contract tests: tel/imzo namunalari, validatsiyani tekshirish.
Chaos: drop/dublikatlar, shuffle tartibi, tarmoq kechikishlari,’RST’,’TLS’xatolari.
Load: burst-bo’ron, o’lchov p95/p99.
Security: anti-replay, eskirgan timestamp, noto’g’ri sirlar, rotatsiya.
DR/Replay: izolyatsiya qilingan stendda DLQ dan ommaviy redrive.

18) Pleybuklar (runbooks)

1. ’signature _ fail _ rate’ oʻsishi

Soat dreyfini,’tolerance’tugaganini, sirlarning rotatsiyasini tekshirish; «dual secret» ni vaqtincha yoqish.

2. Navbat qariydi (’oldest _ in _ queue _ ms’↑)

Vorkerlarni ko’paytirish, tanqidiy topiklarning ustuvorligini kiritish, «shovqinli» turlarning chastotasini vaqtincha kamaytirish.

3. Obunachida bo’ron’429 ’

Trottling va urinishlar orasidagi tanaffuslarni yoqish; kamroq tanqidiy turdagi voqealarni siljitish.

4. Ommaviy’5xx ’

Aniq endpoint uchun circuit-breakerni ochish, defer & batch; obunachiga signal.

5. DLQ toʻldirish

Tanqidiy bo’lmagan nashrni to’xtatish, past RPS bilan batch-redriveni yoqish, obuna egalariga alertalarni ko’tarish.

19) Tipik xatolar

Sinxron ogʻir ishlov berish 2xx → retray va dublikatlargacha.
Tana/vaqt oynasi imzosi yoʻq → almashtirish/replay zaifligi.
’event _ id’ va’inbox’→ mavjud emas.
«Global tartib» ga urinish → navbatlarni abadiy blokirovka qilish.
Jitter/limitsiz retralar → hodisaning kuchayishi (thundering herd).
Barcha obunachilar uchun bitta umumiy bul → «shovqin» hammani qo’yadi.

20) Sotishdan oldingi chek-varaq

• Shartnoma:’event _ id’,’partition _ key’,’seq’,’event _ type. vN’, imzo HMAC va timestamp.
• Jo’natuvchi: outbox, seriyallash, retray bilan backoff + jitter, TTL, DLQ va redrive.
• Oluvchi: inbox + 2xx ga tezkor yozish; idempotentga ishlov berish; lokal DLQ.
• Xavfsizlik: TLS, imzolar, anti-replay, dual-secret, rotatsiya.
• Kvotalar/limitlar: fair-queue per tenant/endpoint, hurmat’Retry-After’.
• Reconcile API va chek pointlari; obunachilar uchun hujjatlar.
• Kuzatish darajasi: p95/oqim/xato/DLQ,’event _ id’bo’yicha trastirovka.
• Hodisalarni versiyalash va sxemalar evolyutsiyasi siyosati.
• Hodisalar pleybuklari va global pauza/muzlatish tugmasi.

Xulosa

Ishonchli vebxuklar shunchaki «JSON bilan POST» emas, balki HTTP ustidagi protokoldir. Aniq kontrakt (ID, tartib kaliti, imzo), idempotentlik, jitter retrasi, adolatli navbat va yaxshi sozlangan pleybuklar «eng yaxshi holat» ni oldindan aytib beriladigan va o’lchanadigan yetkazib berish mexanizmiga aylantiradi. At-least-once + + reconcile kalitini yarating va tizim tarmoqdan, yukning eng yuqori cho’qqilaridan va inson xatolaridan xotirjam omon qoladi.