Provider adapters

Provider adapter - an isolated integration layer (anti-corruption layer, ACL) that translates an external supplier contract (game provider, payment gateway, KYC/AML, risk scoring, notifications, etc.) into an internal domain language and vice versa. It shields the domain from unstable APIs, network anomalies, schema evolutions, and security policies.

1. Decoupling: No "raw" external payload hits the core.

2. Reliability: manage failures (timeouts, retries, DLQ, circuit breaker).

3. Consistency: idempotency, key order, transactional messaging.

4. Operation: metrics, tracing, limits, transfer isolation and residency.

1) Adapter area of responsibility

Contracts: description of external schemes/endpoints; mapping → internal commands/events.
Transport: REST/gRPC/WebSocket/SQS/Kafka/SFTP; connection pool, backpressure.
Security: mTLS, OAuth2, HMAC, keys/certificates per tenant/region, rotation of secrets.
Reliability: timeouts, retrays with jitter, circuit breaker, deduplication.
Idempotency: 'Idempotency-Key '/' request _ id', storing responses/statuses.
Observability: SLO metrics, structural logs, tracing.
Versioning: support for multiple versions of schemes/endpoints.
Operations: ficheflags, canary releases, sandboxes, certification.

2) Where applicable (example contexts)

Game/RGS: start/close round, bets/wins, session tokens, provider statuses.
Payments/PSP: deposits/withdrawals, webhooks statuses, chargeback, 3-D Secure.
KYC/AML: verification, sanction/POP checks, transaction monitoring.
Risk/Fraud: scoring, triggers, blocking recommendations.
Comms: e-mail/SMS/push, mailing limits, templates.

Each type has its own event state machine and SLA - the adapter is obliged to normalize it.

3) Contract and mapping (internal ↔ external)

• We enter Published Language inside the adapter and never drag the provider's fields out.
• All messages carry 'tenant _ id', 'region', 'provider _ id', 'operation _ id', 'version _ ts'.
• We support several versions of external schemes via mappers.

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 and order

Request de-dup: 'Idempotency-Key: <operation_id>' in requests; story '(op_id → final status/response)' with TTL.
Webhook de-dup: table 'inbox (provider, event_id)' as PK.
Order by key: serialize calls and processing by 'aggregate _ id' (for example, 'round _ id' or 'psp _ tx _ id').
Outbox/Inboxing: transactional messaging on both edges of the pipeline.

5) Reliability: timeouts, retreats, circuit breaker

Timeouts: short client-side (p95-oriented), separate for connect/read.
Retrays: retryable only (5xx/timeout/429), exponential backoff + full jitter, attempt limit and total deadline.
Circuit Breaker: open when errors/latency increase; graceful degradation (for example, disable secondary RGS features, set "wait for result").
DLQ: "poisonous" messages with rich meta-information, safe 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, quotas, competitiveness

Observe provider restrictions (RPS, burst, concurrency).
Implement per-tenant WFQ/DRR (fairness) so that the "noisy" client does not eat up the budget.
Respect the'Retry-After '/' X-RateLimit-' headers.
Internal queues + backpressure on the product.

7) Safety and compliance

Transport: mTLS, TLS 1. 2 +, current cipher suites, pinning certificates if possible.
Authentication: OAuth2 client-credentials/MTLS, HMAC (signed body hashes + timestamp), API keys.
PII minimization: only required fields; masking/editing in logs and DLQ.
Secrets: KMS/HashiCorp Vault, automatic rotation, isolation per tenant/region.
Compliance: PCI DSS for PSP, token storage instead of PAN, GDPR/local data laws.

8) Multi-tenant and multi-region

Configuration of keys/endpoints per tenant/region.
Data residency: calls are made from the "home" region; cross-region - aggregates only.
Isolation: own connection pools and 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) Observability: metrics, logs, tracing

• Successes/errors by class (2xx/4xx/5xx/timeout/429).
• p50/p95/p99 latency by method.
• Rate-limit actuation, opening/closing breaker, DLQ-rate, redrive-success.
• Structural logs: 'tenant _ id', 'provider _ id', 'operation _ id', 'endpoint', 'status', 'attempt', 'backoff _ ms'.
• Tracing: single 'trace _ id', spans "serialize → send → receive → map → publish," tags' schema _ version ',' region '.

10) Versioning and phicheflags

Support v1/v2 of the external contract in parallel; migration - canary/by tenants.
Any new provider feature is behind the flag; switching without release.
Evolution contract: additive-first, rigorous validation of schemes (JSON Schema/Proto).

11) Playbooks (runbooks)

1. Squall 429/limits: turn on global throttling, respect 'Retry-After', redistribute windows between tenants.
2. Timeout growth: reduce concurrency, increase timeouts carefully, open breaker, enable feature degradation.
3. Schema mismatch: freeze redrive, enable compatible mapper, backfill/reprocess.
4. Webhook flap: switch to pull/reconcile mode, apply inbox dedup.
5. Incident at the provider: switch to sandbox/backup DC (if any), activate "deferred" operations.

12) Testing

Contract tests: producer/consumer against fixed provider fixes.
Chaos tests: delays, drops, out-of-order, duplicates, partial response, disconnection.
Performance: stress on burst spikes; measurement p95/p99, breaker behavior.
Idempotency: repeating the same 'operation _ id' does not create additional effects.
Sandbox E2E: happy-path/chargeback/controversy/cancellation/recalc scripts.

13) Deployment patterns

Separate service adapter: + isolation, independent releases; − additional network.
Sidecar/plugin: + locality of calls; − more difficult to manage versions.
Library: + easy to embed; − high coupling and motley versions.

Recommendation: service adapter with a clear API and its release cycle.

14) Adapter API Example (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 with 'provider _ event _ id' → 'inbox' (PK on '(provider,event_id)') → mapping → domain event 'PaymentAuthorized'.

15) Typical errors

Pulling a "raw" external circuit into a domain → tight connectivity and expensive migrations.
Lack of idempotency and inbox/outbox → duplicate effects and phantom states.
Retrai without jitter/limits → storm and ban on rate limit.
The only global pool without fairness → one tenant "puts" everyone.
Logs without PII revision/ → identifiers cannot be investigated incidents and compliance risk.
There are no canaries/flags → the release breaks everyone at once.
Ignoring'Retry-After 'and provider maintenance schedules.

16) Pre-sale checklist

• Mapping external schemas → internal language; versions and backward compatibility.
• Identity of requests/webhooks ('operation _ id', 'inbox').
• Timeouts, retrays with full-jitter, circuit breaker, DLQ and safe redrive.
• Rate limits и fairness per tenant; respect for 'Retry-After'.
• mTLS/OAuth/HMAC, secret rotation, PII minimization, access audit.
• Regional isolation and data residency; configs per tenant/region.
• p95/p99 metrics, class error, breaker/429/DLQ-rate; tracing.
• Sandboxes and contract tests; canary rollout and phicheflags.
• Incident playbooks and on-call training.
• Documentation: SLAs, limits, schemas, evolution processes.

Conclusion

Provider adapters are a shield and translator between your domain and the outside world. A strong ACL with idempotency, error control and observability makes integrations predictable, reduces the cost of change at the provider, and protects against "chain failures." Design adapters as independent, manageable components - and your "outside world" will stop breaking the internal architecture.