Provayder adapterlari

Provayder adapteri - etkazib beruvchining tashqi kontraktini (o’yin provayderi, to’lov shlyuzi, KYC/AML, risk-skoring, notifikatsiyalar va boshqalar) ichki domen tiliga va orqaga o’tkazadigan izolyatsiya qilingan integratsiya qatlami (anti-corruption layer, ACL). U domenni beqaror API, tarmoq anomaliyalari, sxemalar evolyutsiyalari va xavfsizlik siyosatidan himoya qiladi.

1. Dekupling: hech qanday «xom» tashqi payload yadroga kirmaydi.

2. Ishonchlilik: xatolarni boshqarish (timeouts, retries, DLQ, circuit breaker).

3. Muvofiqlik: idempotentlik, kalit tartibi, tranzaksion mesejing.

4. Ekspluatatsiya: metrika, treysing, limitlar, per-tenant izolyatsiya va residency.

1) Adapterning javobgarlik zonasi

Kontraktlar: tashqi sxemalar/endpointlar tavsifi; mapping → ichki buyruqlar/voqealar.
Transport: REST/gRPC/WebSocket/SQS/Kafka/SFTP; ulanish puli, backpressure.
Xavfsizlik: mTLS, OAuth2, HMAC, kalitlar/sertifikatlar per tenant/region, sirlarni almashtirish.
Ishonchlilik: taymautlar, jitter retraalari, circuit breaker, deduplikatsiya.
Idempotentlik:’Idempotency-Key ’/’ request _ id’, javoblar/maqomlarni saqlash.
Kuzatilganlik: SLO metrikasi, strukturaviy loglar, trassirovkalar.
Versionlash: sxemalar/endpointlarning bir nechta versiyalarini qo’llab-quvvatlash.
Operatsiyalar: fizeflaglar, kanareya relizlari, qum qutilari, sertifikatlash.

2) Qayerda qo’llaniladi (kontekstlar misollari)

Game/RGS: raundni boshlash/yopish, stavkalar/yutuqlar, sessiya tokenlari, provayder maqomlari.
Payments/PSP: depozitlar/xulosalar, webhooks maqomlari, chargeback, 3-D Secure.
KYC/AML: verifikatsiya, sanksiya/PER-tekshiruvlar, tranzaksiyalar monitoringi.
Risk/Fraud: skoring, triggerlar, blokirovka tavsiyalari.
Comms: e-mail/SMS/push, tarqatish limitlari, shablonlar.

Har bir turning o’z steyt-mashinasi bor va SLA adapteri uni normallashtirishi shart.

3) Kontrakt va mapping (ichki tashqi)

• Published Language’ni adapter ichiga kiriting va hech qachon provayder maydonidan tashqariga chiqarmang.
• Barcha xabarlarni’tenant _ id’,’region’,’provider _ id’,’operation _ id’,’version _ ts’olib boradi.
• Mapperlar orqali tashqi sxemalarning bir nechta versiyalarini qoʻllab-quvvatlaymiz.

yaml mapping:
provider: "AcmeRGS"
version: "v3"
inbound:
SpinResultV3 -> Round. Resulted
BonusWinV3  -> Bonus. Wagered outbound:
StartRound  -> POST /v3/sessions/{id}/start
Stake    -> POST /v3/spins compat:
accepts: ["v2","v3"]
emits:  ["v3"]

4) Idempotentlik va tartib

Request de-dup:’Idempotency-Key: <operation_id>' so’rovlarda; storim’(op_id → yakuniy maqom/javob)’bilan TTL.
Webhook de-dup:’inbox (provider, event_id)’jadvali PK sifatida.
Kalit tartibi:’aggregate _ id’(masalan,’round _ id’yoki’psp _ tx _ id’) qoʻngʻiroqlari va ishlanmalarini seriyallashtiramiz.
Outbox/Inboxing: konveyerning ikkala chetida tranzaksion mesejing.

5) Ishonchlilik: taymautlar, retryalar, circuit breaker

Taymautlar: qisqa client-side (p95-yoʻnaltirilgan), connect/read uchun alohida.
Retrai: faqat retryable (5xx/timeout/429), eksponensial backoff + full jitter, urinishlar limiti va umumiy muddat.
Circuit Breaker: xato/latentlik koʻpayganda ochish; graceful degradation (masalan, ikkinchi darajali RGS fichlarini o’chirib qo’yish, natijani kutish).
DLQ: meta axborotga boy «zaharli» xabarlar, xavfsiz redrayv.

yaml reliability:
timeout_ms:
connect: 1000 read:  1500 retry:
max_attempts: 6 initial_backoff_ms: 200 max_backoff_ms: 8000 jitter: full retry_on: [TIMEOUT, 5xx, 429]
circuit_breaker:
failure_rate_threshold: 20%   # за окно slow_call_threshold_ms: 1500 half_open_max_calls: 10

6) Rate limits, kvotalar, raqobatbardoshlik

Provayder cheklovlariga (RPS, burst, concurency) rioya qiling.
Shovqinli mijoz byudjetni yemasligi uchun per-tenant WFQ/DRR (fairness) ni amalga oshiring.
’Retry-After ’/’ X-RateLimit-’ sarlavhalarini hurmat qiling.
Ichki navbatlar + prodyuserda backpressure.

7) Xavfsizlik va muvofiqlik

Transport: mTLS, TLS 1. 2 +, dolzarb cipher suites, pinning sertifikatlar iloji boricha.
Autentikatsiya: OAuth2 client-credentials/MTLS, HMAC (imzolangan tana xeshlari + timestamp), API-kalitlar.
PII-minimallashtirish: faqat zarur maydonlar; daftarlarda va DLQda yashirish/tahrirlash.
Sirlar: KMS/HashiCorp Vault, avtomatik rotatsiya, izolyatsiya per tenant/region.
Komplayens: PSP uchun PCI DSS, PAN, GDPR o’rniga tokenlarni saqlash/ma’lumotlar to’g’risidagi mahalliy qonunlar.

8) Ko’p tenant va ko’p mintaqa

Tenant/mintaqa uchun kalitlar/endpointlar moslamalari.
Data residency: qoʻngʻiroqlar «uy» hududidan amalga oshiriladi; kross-mintaqa - faqat agregatlar.
Izolyatsiya: birikmalarning o’z pullari va per tenant limitlari.

yaml tenants:
T1:
region: eu-central provider_keys:
acme_rgs: { client_id: "...", cert_ref: "vault://..." }
psp_foo: { hmac_key_ref: "kms://..." }
endpoints:
acme_rgs: "https://eu. api. acme-rgs. com"
psp_foo: "https://eu. api. psp-foo. com"
T2:
region: sa-east
...

9) Kuzatish darajasi: metrika, loglar, treysing

• Sinf muvaffaqiyatlari/xatolari (2xx/4xx/5xx/timeout/429).
• usuli bo’yicha p50/p95/p99 latency.
• Rate-limit ishga tushirish, breaker, DLQ-rate, redrive-success ochish/yopish.
• Tarkibiy loglar:’tenant _ id’,’provider _ id’,’operation _ id’,’endpoint’,’status’,’attempt’,’backoff _ ms’.
• Treysing: yagona’trace _ id’, «serialize → send → receive → map → publish», teglar’schema _ version’,’region’.

10) Versiyalash va fizeflaglar

Tashqi shartnomaning v1/v2 qismini parallel ravishda qoʻllab-quvvatlang; migratsiya - kanareyka/tenantlar bo’yicha.
Provayderning har qanday yangi fichi - bayroq ortida; relizsiz almashtirish.
Evolyutsiya to’g "risidagi shartnoma: additive-first, sxemalarni qat’iy validatsiya qilish (JSON Schema/Proto).

11) Pleybuklar (runbooks)

1. Shkval 429/limitlar: global trottling,’Retry-After’ni hurmat qilish, oynalarni tenantlar o’rtasida qayta taqsimlash.
2. Vaqtni o’stirish: concurrency’ni kamaytirish, vaqtni ehtiyotkorlik bilan ko’paytirish, breaker’ni ochish, tanaffusni yoqish.
3. Schema mismatch: redrayvni muzlatish, mos keladigan mapperni yoqish, backfill/reprocessing qilish.
4. Vebxuk flap: pull/reconcile rejimiga oʻtish, inbox-dedupni qoʻllash.
5. Provayderning hodisasi: qum qutisiga/zaxira DC (agar mavjud boʻlsa) ga oʻtish, «kechiktirilgan» operatsiyalarni faollashtirish.

12) Test sinovi

Kontrakt testlari: provayderning qayd etilgan fiksturalariga qarshi producer/consumer.
Xaos-testlar: kechikishlar, droplar, out-of-order, dublikatlar, qisman javob berish, uzilish.
Performance: burst-paykalarda stress; o’lchov p95/p99, breaker xatti-harakati.
Idempotentlik: bir xil’operation _ id’ning takrorlanishi qoʻshimcha effektlar yaratmaydi.
Qum qutisidagi E2E: happy-path/chargeback/sporlar/bekor qilish/rekalk.

13) Amalga oshirish variantlari (deployment patterns)

Alohida servis-adapter: + izolyatsiya, mustaqil relizlar; − qo’shimcha tarmoq.
Sidecar/plagin: + qoʻngʻiroqlar lokalligi; − versiyalarni boshqarish qiyinroq.
Kutubxona: + shunchaki joylashtirish; − yuqori coupling va turli xil versiyalar.

Tavsiya: aniq API va o’zining reliz sikliga ega servis-adapter.

14) API adapter misoli (psevdo)

http
POST /adapters/psp/authorize
Headers:
X-Tenant: T1
Idempotency-Key: op-uuid
Body:
{ "amount":"10. 00","currency":"EUR","method":"card","card_token":"tok_..." }

→ 202 Accepted
{
"operation_id":"op-uuid",
"status":"PENDING",
"as_of":"2025-10-31T12:00:00Z"
}

• ’provider _ event _ id’ →’inbox’(PK na’(provider,event_id)’) → mapping → domen hodisasi’PaymentAuthorized’.

15) Tipik xatolar

«Xom» tashqi sxemani domenga olib kirish → qattiq bog’liqlik va qimmat migratsiyalar.
Idempotentlik va inbox/outbox → ikki xil effektlar va fantom holatlar mavjud emas.
Jitter/limitsiz retraylar → rate limit bo’roni va bani.
Fairness bo’lmagan yagona global hovuz → bitta tenant hammani «qo’yadi».
PII tahriri/identifikatorlari bo’lmagan loglar → hodisalar va komplayens xavfini tekshirish mumkin emas.
Kanareya/bayroqlar yoʻq → reliz barchani birdaniga buzadi.
’Retry-After’ va provayderga xizmat ko’rsatish jadvallarini e’tiborsiz qoldirish.

16) Sotishdan oldingi chek-varaq

• Tashqi sxemalar mapping → ichki til; versiyalar va teskari muvofiqlik.
• So’rovlar/vebxuklarning idempotentligi (’operation _ id’,’inbox’).
• Taymautlar, full-jitter retraylari, circuit breaker, DLQ va xavfsiz redraylar.
• Rate limits и fairness per tenant; hurmat’Retry-After’.
• mTLS/OAuth/HMAC, sirlarni almashtirish, PII minimallashtirish, kirish auditi.
• Mintaqaviy izolyatsiya va data residency; konfigi per tenant/region.
• Metrika p95/p99, sinf xatosi, breaker/429/DLQ-rate; treysing.
• Qum qutilari va kontrakt testlari; kanar rollout va ficheflaglar.
• Voqealar pleybuklari va on-call treninglari.
• Hujjatlar: SLA, limitlar, sxemalar, evolyutsiya jarayonlari.

Xulosa

Provayder adapterlari - bu domen va tashqi dunyo o’rtasidagi qalqon va tarjimon. Idempotentlik, xatolarni nazorat qilish va kuzatish qobiliyatiga ega kuchli ACL integratsiyani oldindan aytib bo’lmaydigan qiladi, provayderdagi o’zgarishlar narxini pasaytiradi va «zanjirdagi nosozliklardan» himoya qiladi. Adapterlarni mustaqil, boshqariladigan komponentlar sifatida loyihalashtiring va «tashqi dunyo» ichki arxitekturani buzishni to’xtatadi.