Provayder adapterləri

Provayder adapteri - təchizatçının xarici müqaviləsini (oyun provayderi, ödəniş şluzu, KYC/AML, risk-skor, notifikasiya və s.) daxili domen dilinə və əksinə çevirən təcrid olunmuş inteqrasiya qatıdır (anti-corruption layer, ACL). Qeyri-sabit API-lərdən, şəbəkə anomaliyalarından, sxemlərin təkamüllərindən və təhlükəsizlik siyasətlərindən domeni ekranlaşdırır.

1. Dekupling: heç bir «xam» xarici payload nüvəyə düşmür.

2. Etibarlılıq: uğursuzluqları idarə edin (timeouts, retries, DLQ, circuit breaker).

3. Uyğunluq: idempotentlik, açar qaydası, əməliyyat mesajlaşması.

4. Əməliyyat: metriklər, treysinq, limitlər, per-tenant izolyasiya və residency.

1) Adapter məsuliyyət sahəsi

Müqavilələr: xarici sxemlərin/end-pointlərin təsviri; mapping → daxili komandalar/hadisələr.
Nəqliyyat: REST/gRPC/WebSocket/SQS/Kafka/SFTP; bağlantı hovuzu, backpressure.
Təhlükəsizlik: mTLS, OAuth2, HMAC, açarlar/per tenant/region sertifikatları, sirlərin rotasiyası.
Etibarlılıq: taymaut, jitter retraisi, circuit breaker, deduplication.
İdempotentlik: 'Idempotency-Key '/' request _ id', cavabların/statusların saxlanması.
Müşahidə: SLO metrləri, struktur qeydləri, izləmə.
Version: sxemlərin/end-pointlərin bir neçə versiyasını dəstəkləyir.
Əməliyyatlar: ficheflages, kanar relizlər, qum qutuları, sertifikatlaşdırma.

2) Harada tətbiq olunur (kontekstlər nümunələri)

Game/RGS: raundun başlaması/bağlanması, bahislər/uduşlar, sessiya tokenləri, provayder statusları.
Payments/PSP: depozitlər/nəticələr, webhooks statusları, chargeback, 3-D Secure.
KYC/AML: yoxlamalar, sanksiya/RER-yoxlamalar, əməliyyatların monitorinqi.
Risk/Fraud: skoring, tetikleyicilər, kilidləmə tövsiyələri.
Comms: e-mail/SMS/push, poçt limitləri, şablonlar.

Hər bir növün öz steyt-maşın hadisələri və SLA var - adapter onu normallaşdırmağa borcludur.

3) Müqavilə və mapping (daxili xarici)

• Adapter daxilində Published Language daxil edin və heç vaxt provayder sahəsinə sürükləməyin.
• Bütün mesajlar 'tenant _ id', 'region', 'provider _ id', 'operation _ id', 'version _ ts' daşıyır.
• Mapperlər vasitəsilə xarici sxemlərin bir neçə versiyasını dəstəkləyirik.

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) İdempotentlik və nizam

Request de-dup: 'Idempotency-Key: <operation_id>' sorğu; storim '(op_id → son status/cavab)' TTL ilə.
Webhook de-dup: masa 'inbox (provider, event_id)' PK kimi.
Açar sırası: 'aggregate _ id' (məsələn, 'round _ id' və ya 'psp _ tx _ id') zəngləri və emalını seriallaşdırırıq.
Outbox/Inboxing: konveyerin hər iki kənarında əməliyyat mesajlaşması.

5) Etibarlılıq: Taymaut, retras, circuit breaker

Vaxt: connect/read üçün ayrı qısa client-side (p95-yönlü).
Retrailer: yalnız retryable (5xx/timeout/429), eksponent backoff + full jitter, cəhd limiti və ümumi son tarix.
Circuit Breaker: artan səhvlər/gecikmə ilə açmaq; graceful degradation (məsələn, ikinci dərəcəli RGS xüsusiyyətlərini söndürmək, «nəticə gözləmək» qoymaq).
DLQ: zəngin meta məlumat ilə «zəhərli» mesajlar, təhlükəsiz redrave.

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, rəqabət

Provayder məhdudiyyətlərinə riayət edin (RPS, burst, concurency).
«Səs-küylü» müştərinin büdcəni yeməməsi üçün per-tenant WFQ/DRR (fairness) həyata keçirin.
'Retry-After '/' X-RateLimit-' başlıqlarına hörmət edin.
Daxili növbələr + prodüserdə backpressure.

7) Təhlükəsizlik və uyğunluq

Nəqliyyat: mTLS, TLS 1. 2 +, aktual cipher suites, mümkün qədər sertifikatlar pinning.
Autentication: OAuth2 client-credentials/MTLS, HMAC (imzalı hash bədən + timestamp), API açarları.
PII-minimallaşdırma: yalnız lazımi sahələr; log və DLQ-də maskalanma/redaktə.
Secrets: KMS/HashiCorp Vault, avtomatik rotasiya, izolyasiya per tenant/region.
Komplayens: PSP üçün PCI DSS, PAN əvəzinə tokenlərin saxlanması, GDPR/yerli məlumat qanunları.

8) Multi-tenant və multi-region

Tenant/region üçün açar/end nöqtələrinin konfiqurasiyası.
Data residency: çağırışlar «ev» bölgəsindən edilir; cross-region - yalnız aqreqatlar.
İzolyasiya: öz birləşmə hovuzları və per tenant limitləri.

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) Müşahidə: Metriklər, Logi, Trace

• Uğurlar/səhvlər (2xx/4xx/5xx/timeout/429).
• p50/p95/p99 latency metodu ilə.
• Rate-limiti, breaker açma/bağlama, DLQ-rate, redrive-success.
• Struktur loqları: 'tenant _ id', 'provider _ id', 'operation _ id', 'endpoint', 'status', 'attempt', 'backoff _ ms'.
• Treysinq: vahid 'trace _ id', yuxular 'serialize → send → receive → map → publish', etiketlər 'schema _ version', 'region'.

10) Version və ficheflages

Xarici müqavilənin v1/v2 paralel saxlanılması; miqrasiya - kanareya/tenantlar üzrə.
Provayderin hər hansı yeni fişi - bayrağın arxasında; buraxılışsız keçid.
Təkamül müqaviləsi: additive-first, sxemlərin ciddi validasiyası (JSON Schema/Proto).

11) Playbooks (runbooks)

1. Scroll 429/limitləri: qlobal trottling daxil, hörmət 'Retry-After', tenants arasında pəncərələri yenidən bölüşdürün.
2. Zaman artımı: concurrency azaltmaq, zaman artımı ehtiyatla artırmaq, breaker açmaq, fich deqradasiya yandırmaq.
3. Schema mismatch: redrave dondurmaq, uyğun mapper yandırmaq, backfill/reprocessing yerinə yetirmək.
4. Flap webhook: pull/reconcile rejimi keçid, inbox deadup tətbiq.
5. Provayderdə hadisə: qum qutusuna/ehtiyat DC-yə keçin (varsa), «gecikmiş» əməliyyatları aktivləşdirin.

12) Test

Müqavilə testləri: producer/consumer vs sabit fikstura provayder.
Xaos testləri: gecikmələr, dumps, out-of-order, təkrarlanan, qismən cavab, bağlantı qırılması.
Performance: burst spikes stress; ölçü p95/p99, davranış breaker.
İdempotentlik: eyni 'operation _ id' təkrar əlavə effekt yaratmır.
Qum qutularında E2E: happy-path/chargeback/mübahisələr/ləğv/rekalk ssenariləri.

13) Satış variantları (deployment patterns)

Ayrıca xidmət adapteri: + izolyasiya, müstəqil buraxılışlar; − əlavə şəbəkə.
Sidecar/plugin: + zənglərin lokallığı; − versiyaları idarə etmək daha çətindir.
Kitabxana: + sadə inteqrasiya; − yüksək coupling və rəngarəng versiyalar.

Tövsiyə: aydın API və buraxılış dövrü ilə xidmət adapteri.

14) API adapter nümunəsi (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 on '(provider,event_id)') → mapping → domen hadisəsi 'PaymentAuthorized'.

15) Tipik səhvlər

«Xam» xarici sxemi domenə sürükləmək → sərt əlaqə və bahalı miqrasiyalar.
Heç bir idempotentlik və inbox/outbox → ikiqat effektlər və fantom hallar.
Jitter/limitsiz retrains → fırtına və rate limit.
fairness olmadan yeganə qlobal hovuz → bir tenant hamını «qoyur».
PII redaktəsi/identifikatorları olmayan qeydlər → hadisələri və uyğunluq riskini araşdıra bilməz.
Kanaryalar/bayraqlar yoxdur → bir anda hamını qırır.
«Retry-After» və provayder xidmət cədvəllərinə məhəl qoymamaq.

16) Satış öncəsi yoxlama siyahısı

• Mapping xarici sxemlər → daxili dil; versiyalar və əks uyğunluq.
• Sorğuların/vebhukların idempotentliyi ('operation _ id', 'inbox').
• full-jitter, circuit breaker, DLQ və təhlükəsiz redrave ilə vaxt, retrains.
• Rate limits и fairness per tenant; hörmət 'Retry-After'.
• mTLS/OAuth/HMAC, sirlərin rotasiyası, PII minimallaşdırılması, giriş auditi.
• Regional izolyasiya və data residency; konfigi per tenant/region.
• p95/p99 metrika, sinif xətası, breaker/429/DLQ-rate; Trace.
• Qum qutuları və müqavilə testləri; kanar rollout və phicheflages.
• Hadisə playbook və on-call təlim.
• Sənədləşmə: SLA, limitlər, sxemlər, təkamül prosesləri.

Nəticə

Provayder adapterləri domeniniz və xarici dünya arasında bir qalxan və tərcüməçidir. İdempotentlik, səhv nəzarəti və müşahidə qabiliyyəti ilə güclü ACL inteqrasiyanı proqnozlaşdırıla bilən edir, provayderdə dəyişikliklərin dəyərini azaldır və «zəncirdəki uğursuzluqlardan» qoruyur. Adapterləri müstəqil, idarə olunan komponentlər kimi dizayn edin və «xarici dünyanız» daxili arxitekturanı pozmağı dayandıracaq.