Sağlayıcı adaptörleri

Sağlayıcı bağdaştırıcısı - harici bir tedarikçi sözleşmesini (oyun sağlayıcısı, ödeme ağ geçidi, KYC/AML, risk puanlaması, bildirimler vb.) dahili bir alan diline çeviren izole bir entegrasyon katmanı (yolsuzlukla mücadele katmanı, ACL) ve bunun tersi. Etki alanını kararsız API'lerden, ağ anormalliklerinden, şema gelişmelerinden ve güvenlik politikalarından korur.

1. Ayırma: "Ham" harici yük çekirdeğe çarpmaz.

2. Güvenilirlik: Arızaları yönetin (zaman aşımları, yeniden denemeler, DLQ, devre kesici).

3. Tutarlılık: idempotency, anahtar sırası, işlemsel mesajlaşma.

4. Operasyon: metrikler, izleme, limitler, transfer izolasyonu ve ikamet.

1) Adaptör sorumluluk alanı

Sözleşmeler: Dış şemaların/uç noktaların tanımı; mapping - dahili komutlar/olaylar.
Taşıma: REST/gRPC/WebSocket/SQS/Kafka/SFTP; Bağlantı havuzu, geri basınç.
Güvenlik: mTLS, OAuth2, HMAC, kiracı/bölge başına anahtarlar/sertifikalar, sırların döndürülmesi.
Güvenilirlik: zaman aşımları, jitter ile geri alma, devre kesici, veri tekilleştirme.
Idempotency: 'Idempotency-Key'/' request _ id', yanıtları/durumları depolar.
Gözlemlenebilirlik: SLO metrikleri, yapısal günlükler, izleme.
Sürüm oluşturma: şemaların/uç noktaların birden çok sürümü için destek.
Operasyonlar: Ficheflags, kanarya bültenleri, kum havuzları, sertifikasyon.

2) Uygulanabilir olduğunda (örnek bağlamlar)

Oyun/RGS: başlangıç/kapanış turu, bahisler/kazançlar, oturum belirteçleri, sağlayıcı durumları.
Ödemeler/PSP: para yatırma/çekme, webhooks durumları, ters ibraz, 3-D Güvenli.
KYC/AML: doğrulama, yaptırım/POP kontrolleri, işlem izleme.
Risk/Dolandırıcılık: puanlama, tetikleyiciler, engelleme önerileri.
İletişim: e-posta/SMS/push, posta limitleri, şablonlar.

Her türün kendi olay durumu makinesi ve SLA'sı vardır - bağdaştırıcı bunu normalleştirmekle yükümlüdür.

3) Sözleşme ve haritalama (iç ↔ dış)

• Bağdaştırıcının içine Published Language giriyoruz ve hiçbir zaman sağlayıcının alanlarını dışarı sürüklemiyoruz.
• Tüm iletiler 'tenant _ id', 'region', 'provider _ id', 'operation _ id', 'version _ ts' taşır.
• Harici şemaların çeşitli versiyonlarını haritalayıcılar aracılığıyla destekliyoruz.

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) Idempotence ve düzen

Request de-dup: 'Idempotency-Key: <operation_id>' in requests; TTL ile hikaye '(op_id> son durum/yanıt)'.
Webhook de-dup: tablo 'gelen kutusu (sağlayıcı, event_id)' PK olarak.
Anahtara göre sırala: çağrıları ve işlemleri 'aggregate _ id' (örneğin, 'round _ id' veya 'psp _ tx _ id') ile seri hale getir.
Giden Kutusu/Gelen Kutusu: boru hattının her iki kenarında işlemsel mesajlaşma.

5) Güvenilirlik: zaman aşımları, geri çekilmeler, devre kesici

Zaman aşımları: kısa istemci tarafı (p95 odaklı), bağlantı/okuma için ayrı.
Retrays: Sadece geri alınabilir (5xx/timeout/429), üstel geri alma + tam jitter, girişim sınırı ve toplam son tarih.
Devre Kesici: hatalar/gecikme arttıkça açılır; Zarif bozulma (örneğin, ikincil RGS özelliklerini devre dışı bırakın, "sonucu bekleyin" ayarını yapın).
DLQ: Zengin meta-bilgi içeren "zehirli" mesajlar, güvenli 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) Oran limitleri, kotalar, rekabet gücü

Sağlayıcı kısıtlamalarına dikkat edin (RPS, patlama, eşzamanlılık).
Kiracı başına WFQ/DRR (adalet) uygulayın, böylece "gürültülü" müşteri bütçeyi yemez.
'Retry-After'/' X-RateLimit-' başlıklarına saygı gösterin.
Dahili kuyruklar + ürün üzerinde geri basınç.

7) Güvenlik ve uyumluluk

Taşıma: mTLS, TLS 1. 2 +, mevcut şifre süitleri, mümkünse sabitleme sertifikaları.
Kimlik doğrulama: OAuth2 istemci kimlik bilgileri/MTLS, HMAC (imzalı gövde karma + zaman damgası), API anahtarları.
PII minimizasyonu: sadece gerekli alanlar; Günlüklerde ve DLQ'da maskeleme/düzenleme.
Sırlar: KMS/HashiCorp Vault, otomatik rotasyon, kiracı/bölge başına izolasyon.
Uyumluluk: PSP için PCI DSS, PAN yerine belirteç depolama, GDPR/yerel veri yasaları.

8) Çok kiracı ve çok bölgeli

Kiracı/bölge başına anahtarların/uç noktaların yapılandırılması.
Veri ikametgahı: aramalar'ev "bölgesinden yapılır; çapraz bölge - yalnızca kümeler.
İzolasyon: kendi bağlantı havuzları ve kiracı başına limitler.

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) Gözlemlenebilirlik: metrikler, günlükler, izleme

• Sınıfa göre başarılar/hatalar (2xx/4xx/5xx/timeout/429).
• Yöntemle p50/p95/p99 gecikme.
• Hız limiti çalıştırma, açma/kapama kesici, DLQ oranı, redrive başarısı.
• Yapısal günlükler: 'tenant _ id', 'provider _ id', 'operation _ id', 'endpoint', 'status', 'entry', 'backoff _ ms'.
• Tracing: single 'trace _ id', sprans "serialize et, gönder, al, harita, yayınla", tags 'schema _ version', 'region'.

10) Sürüm ve phicheflags

Dış sözleşmenin v1/v2'sini paralel olarak destekleyin; göç - kanarya/kiracılar tarafından.
Herhangi bir yeni sağlayıcı özelliği bayrağın arkasındadır; Serbest bırakmadan geçiş.
Evrim sözleşmesi: Önce eklemeli, şemaların titiz bir şekilde doğrulanması (JSON Schema/Proto).

11) Playbook'lar (runbook'lar)

1. Squall 429/limits: küresel daraltmayı açın, 'Retry-After'a saygı gösterin, pencereleri kiracılar arasında yeniden dağıtın.
2. Zaman aşımı artışı: eşzamanlılığı azaltın, zaman aşımlarını dikkatlice artırın, kesiciyi açın, özellik bozulmasını etkinleştirin.
3. Şema uyumsuzluğu: redrive'ı dondur, uyumlu eşleyiciyi etkinleştir, geri doldur/yeniden işlet.
4. Webhook kapağı: çekme/uzlaştırma moduna geçin, gelen kutusu tekilleştirme uygulayın.
5. Sağlayıcıdaki olay: sandbox/backup DC'ye geçin (varsa), "ertelenmiş" işlemleri etkinleştirin.

12) Test etme

Sözleşme testleri: Üretici/tüketici sabit sağlayıcı düzeltmelerine karşı.
Kaos testleri: gecikmeler, düşüşler, sıra dışı, kopyalar, kısmi tepki, bağlantı kesilmesi.
Performans: patlama sivri üzerinde stres; Ölçüm p95/p99, kırıcı davranış.
Idempotency: Aynı 'operation _ id' tekrarlanması ek etkiler yaratmaz.
Sandbox E2E: happy-path/chargeback/controversy/cancellation/recalc scriptleri.

13) Dağıtım modelleri

Ayrı servis adaptörü: + izolasyon, bağımsız sürümler; − ek ağ.
Sidecar/plugin: + çağrıların yeri; − sürümleri yönetmek daha zor.
Kütüphane: + gömülmesi kolay; − yüksek kuplaj ve rengarenk versiyonlar.

Öneri: açık bir API ve serbest bırakma döngüsüne sahip servis adaptörü.

14) Adaptör API Örneği (Sözde)

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'ile Webhook _ Gelen Kutusu (PK on' (provider,event_id) ') - haritalama - Etki alanı olayı' PaymentAuthorized '.

15) Tipik hatalar

"Ham'bir harici devreyi bir alana çekmek - sıkı bağlantı ve pahalı geçişler.
Idempotency ve gelen kutusu/giden kutusu eksikliği - yinelenen efektler ve fantom durumları.
Jitter/limitsiz Retrai - fırtına ve oran sınırı yasağı.
Adil olmayan tek küresel havuz - bir kiracı herkesi "koyar".
PII revizyonu olmayan günlükler, olayları ve uyumluluk riskini araştırılamaz.
Kanarya/bayrak yok - serbest bırakma herkesi bir kerede kırar.
'Retry-After've sağlayıcı bakım programlarını göz ardı etme.

16) Satış öncesi kontrol listesi

• Dış şemaları haritalama - iç dil; sürümler ve geriye dönük uyumluluk.
• İsteklerin/webhookların kimliği ('operation _ id', 'gelen kutusu').
• Zaman aşımları, full-jitter, devre kesici, DLQ ve güvenli redrive ile retrays.
• Oran sınırları и kiracı başına adalet; 'Retry-After' için saygı.
• mTLS/OAuth/HMAC, gizli rotasyon, PII minimizasyonu, erişim denetimi.
• Bölgesel izolasyon ve veri ikametgahı; kiracı/bölge başına yapılandırır.
• p95/p99 metrikleri, sınıf hatası, breaker/429/DLQ-rate; İzleme.
• Kum havuzları ve sözleşme testleri; Kanarya çıkışı ve phicheflags.
• Olay oyun kitapları ve çağrı üzerine eğitim.
• Dokümantasyon: SLA'lar, limitler, şemalar, evrim süreçleri.

Sonuç

Sağlayıcı adaptörleri, etki alanınız ile dış dünya arasında bir kalkan ve çevirmendir. Idempotency, hata kontrolü ve gözlemlenebilirlik ile güçlü bir ACL, entegrasyonları öngörülebilir hale getirir, sağlayıcıdaki değişim maliyetini azaltır ve "zincir arızalarına" karşı korur. Bağımsız, yönetilebilir bileşenler olarak tasarım adaptörleri - ve "dış dünyanız" iç mimariyi kırmayı bırakacak.