Adapter der Anbieter

Der Provider Adapter ist eine isolierte Integrationsschicht (Anti-Corruption Layer, ACL), die den externen Vertrag des Providers (Game Provider, Payment Gateway, KYC/AML, Risk Scoring, Notifications etc.) in die interne Domänensprache und zurück übersetzt. Es schützt die Domäne vor instabilen APIs, Netzwerkanomalien, Schaltungsentwicklungen und Sicherheitsrichtlinien.

1. Decoupling: Kein „roher“ externer Payload schafft es in den Kern.

2. Zuverlässigkeit: Verwalten Sie Fehler (Timeouts, Retries, DLQ, Circuit Breaker).

3. Konsistenz: Idempotenz, Reihenfolge nach Schlüssel, transaktionales Messaging.

4. Ausbeutung: Metriken, Tracing, Limits, per-tenante Isolation und Residency.

1) Zuständigkeitsbereich des Adapters

Verträge: Beschreibung der externen Systeme/Endpunkte; Mupping → Interne Teams/Events.
Transport: REST/gRPC/WebSocket/SQS/Kafka/SFTP; Verbindungspool, Backpress.
Sicherheit: mTLS, OAuth2, HMAC, Schlüssel/Zertifikate per tenant/region, Rotation der Geheimnisse.
Zuverlässigkeit: Timeouts, Retrays mit Jitter, Circuit Breaker, Deduplizierung.
Idempotenz: 'Idempotency-Key '/' request _ id', Speicherung von Antworten/Status.
Beobachtbarkeit: SLO-Metriken, Strukturprotokolle, Tracing.
Versionierung: Unterstützt mehrere Versionen von Schaltplänen/Endpunkten.
Operationen: Ficheflags, Kanarienfreigaben, Sandkästen, Zertifizierung.

2) Wo sie angewendet werden (Beispiele für Kontexte)

Spiel/RGS: Runde starten/schließen, Wetten/Gewinne, Session-Token, Anbieter-Status.
Zahlungen/PSP: Ein-/Auszahlungen, Status-Webhooks, Chargeback, 3-D Secure.
KYC/AML: Verifizierungen, Sanktions-/PEER-Prüfungen, Transaktionsüberwachung.
Risiko/Betrug: Scoring, Trigger, Empfehlungen für Sperren.
Komms: E-Mail/SMS/Push, Mailing-Limits, Templates.

Jeder Typ hat seine eigene State Event Machine und SLA - der Adapter ist verpflichtet, sie zu normalisieren.

3) Vertrag und Mupping (intern ↔ extern)

• Wir geben Published Language innerhalb des Adapters ein und ziehen niemals die Felder des Anbieters nach außen.
• Alle Nachrichten tragen 'tenant _ id', 'region', 'provider _ id', 'operation _ id', 'version _ ts'.
• Wir unterstützen mehrere Versionen externer Schaltungen über Mupper.

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) Idempotenz und Ordnung

Request de-dup: 'Idempotency-Key: <operation_id>' in Anfragen; storim'(op_id → letzten Status/Antwort) 'mit TTL.
Webhook de-dup: Tabelle' inbox (Provider, event_id) 'als PK.
Reihenfolge nach Schlüssel: Wir serialisieren Aufrufe und Verarbeitung mit 'aggregate _ id' (z.B. 'round _ id' oder 'psp _ tx _ id').
Outbox/Inboxing: Transaktionales Messaging an beiden Rändern der Pipeline.

5) Zuverlässigkeit: Timeouts, Retrays, Circuit Breaker

Timeouts: kurze Client-Seite (p95-orientiert), getrennt für connect/read.
Retrays: nur auf retryable (5xx/timeout/429), exponentieller Backoff + Full Jitter, Versuchsbegrenzung und Gesamttermin.
Circuit Breaker: öffnen, wenn Fehler/Latenz zunehmen; graceful degradation (z.B. sekundäre RGS-Fiches ausschalten, „Warten auf Ergebnis“ setzen).
DLQ: „giftige“ Nachrichten mit reichhaltigen Meta-Informationen, sicheres Redrive.

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) Preislimits, Quoten, Wettbewerb

Beachten Sie die Einschränkungen des Anbieters (RPS, Burst, Concurency).
Implementieren Sie ein per-tenantes WFQ/DRR (Fairness), damit der „laute“ Kunde das Budget nicht frisst.
Respektiere' Retry-After '/' X-RateLimit- 'Überschriften.
Interne Warteschlangen + Backpress auf dem Producer.

7) Sicherheit und Compliance

Transport: mTLS, TLS 1. 2 +, aktuelle cipher Suiten, pinning Zertifikate wenn möglich.
Authentifizierung: OAuth2 Client-Credentials/MTLS, HMAC (signierte Body-Hashes + Timestamp), API-Schlüssel.
PII-Minimierung: nur notwendige Felder; Maskierung/Revision in Logs und DLQ.
Geheimnisse: KMS/HashiCorp Vault, automatische Rotation, Isolierung per tenant/region.
Compliance: PCI DSS für PSP, Token-Speicherung statt PAN, DSGVO/lokale Datengesetze.

8) Multi-Tenant und Multi-Region

Konfiguration der Schlüssel/Endpunkte pro Tenant/Region.
Datenresidenz: Anrufe werden aus der „heimischen“ Region gemacht; Cross-Region - nur Aggregate.
Isolation: Eigene Verbindungspools und Limits per tenant.

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) Beobachtbarkeit: Metriken, Protokolle, Tracing

• Erfolge/Fehler nach Klassen (2xx/4xx/5xx/timeout/429).
• p50/p95/p99 Latenz nach Methode.
• Auslöserate, Breaker öffnen/schließen, DLQ-Rate, Redrive-Erfolg.
• Strukturprotokolle: 'tenant _ id', 'provider _ id', 'operation _ id', 'endpoint', 'status', 'attempt', 'backoff _ ms'.
• Tracing: eine einzelne „trace _ id“, Spans von „serialize → send → receive → map → publish“, Tags von „schema _ version“, „region“.

10) Versionierung und Ficheflage

Stützen Sie parallel v1/v2 des externen Vertrags; Migration - Kanarienwanderung/nach Tenanten.
Jede neue Ficha des Anbieters - hinter der Flagge; Schalten ohne Freigabe.
Evolutionsvertrag: additive-first, strikte Validierung von Schemata (JSON Schema/Proto).

11) Playbooks (Runbooks)

1. Flaute 429/Limits: Globales Trotten ermöglichen, 'Retry-After' respektieren, Fenster zwischen Tenanten neu verteilen.
2. Timeout-Wachstum: Reduzieren Sie die Concurrency, erhöhen Sie die Timeouts vorsichtig, öffnen Sie den Breaker, aktivieren Sie die Degradation von Fich.
3. Schema mismatch: freeze redrive, enable compatible mapper, backfill/reprozessing.
4. Flap Webhooks: Wechseln Sie zu Pull/Reconcile-Modus, gelten Inbox-Dedup.
5. Vorfall beim Anbieter: auf Sandbox/redundante DC umschalten (falls vorhanden), „verzögerte“ Operationen aktivieren.

12) Testen

Vertragstests: Produzent/Konsument gegen Fixturen des Anbieters.
Chaos-Tests: Verzögerungen, Drops, Out-of-Order, Duplikate, partielle Reaktion, Unterbrechung der Verbindung.
Performance: Stress auf Burst-Spikes; Messung p95/p99, Breaker-Verhalten.
Idempotenz: Die Wiederholung der gleichen 'operation _ id' erzeugt keine zusätzlichen Effekte.
E2E in Sandboxes: Happy-Path/Chargeback/Dispute/Cancel/Recalk-Szenarien.

13) Implementierungsmöglichkeiten (Deployment Patterns)

Separater Service-Adapter: + Isolierung, unabhängige Freigaben; − zusätzliches Netzwerk.
Sidecar/Plugin: + Ortsanrufe; − schwieriger zu verwalten Versionen.
Bibliothek: + einfach einzubetten; − hohe Paarung und bunte Versionen.

Empfehlung: Service-Adapter mit klarer API und eigenem Release-Zyklus.

14) Adapter API Beispiel (Pseudo)

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"
}

• Webhook mit 'provider _ event _ id' → 'inbox' (PK auf'(provider,event_id)') → Mapping → Domain-Event 'PaymentAuthorized'.

15) Typische Fehler

Das Ziehen des „rohen“ externen Schemas in die Domäne → eine starre Konnektivität und teure Migrationen.
Keine Idempotenz und Inbox/Outbox → doppelte Effekte und Phantomzustände.
Retrays ohne Jitter/Limits → Sturm und Verbot durch Rate Limit.
Der einzige globale Pool ohne Fairness → ein Tenant „setzt“ alle.
Logs ohne PII-Revision/IDs können → Vorfälle und Compliance-Risiken nicht untersucht werden.
Es gibt keine Kanarienvögel/Flaggen → die Veröffentlichung bricht alle auf einmal.
'Retry-After' und Dienstpläne des Anbieters ignorieren.

16) Checkliste vor dem Verkauf

Mapping externer Schemata → interne Sprache; Versionen und Abwärtskompatibilität.

• Idempotenz von Anfragen/Webhooks ('operation _ id', 'inbox').
• Timeouts, Retrays mit Full-Jitter, Circuit Breaker, DLQ und Safe Redrive.
• Rate limits и fairness per tenant; Respekt für „Retry-After“.
• mTLS/OAuth/HMAC, Secret Rotation, PII-Minimierung, Access Audit.
• Regionale Isolation und Datenresidenz; configi per tenant/region.
• Metriken p95/p99, Fehler nach Klasse, breaker/429/DLQ-rate; Tracing.
• Sandboxes und Vertragstests; Kanarienrollout und Ficheflage.
• Incident Playbooks und On-Call-Training.
• Dokumentation: SLAs, Limits, Schemata, Evolutionsprozesse.

Schlussfolgerung

Provider-Adapter sind ein Schild und ein Übersetzer zwischen Ihrer Domain und der Außenwelt. Eine starke ACL mit Idempotenz, Fehlerkontrolle und Beobachtbarkeit macht Integrationen vorhersehbar, reduziert die Kosten für Änderungen beim Anbieter und schützt vor „Kettenfehlern“. Entwerfen Sie Adapter als eigenständige, überschaubare Komponenten - und Ihre „Außenwelt“ hört auf, die Innenarchitektur zu durchbrechen.