Adaptateurs de fournisseurs

L'adaptateur fournisseur est une couche d'intégration isolée (anti-corruption layer, ACL) qui transfère le contrat externe du fournisseur (fournisseur de jeux, passerelle de paiement, KYC/AML, risque-scoring, notations, etc.) dans le langage de domaine interne et inversement. Il protège le domaine contre les API instables, les anomalies de réseau, les évolutions des schémas et les politiques de sécurité.

1. Décuplage : aucun payload externe « brut » n'entre dans le noyau.

2. Fiabilité : gérer les pannes (timeouts, retries, DLQ, circuit breaker).

3. Cohérence : idempotence, ordre par clé, messagerie transactionnelle.

4. Exploitation : métriques, tracing, limites, isolation per-tenante et résidence.

1) Zone de responsabilité de l'adaptateur

Contrats : description des schémas/endpoints externes ; mapping → commandes/événements internes.
Transport : REST/gRPC/WebSocket/SQS/Kafka/SFTP ; pool de connexions, backpressure.
Sécurité : mTLS, OAuth2, HMAC, clés/certificats per tenant/region, rotation des secrets.
Fiabilité : Timeouts, retraits avec jitter, circuit breaker, déduplication.
Idempotence : 'Idempotency-Key '/' request _ id', stockage des réponses/états.
Observabilité : métriques SLO, logs structurels, traçage.
Versioning : prise en charge de plusieurs versions de schémas/endpoints.
Opérations : Ficheflags, sorties canaries, bac à sable, certification.

2) Où appliquer (exemples de contextes)

Jeu/RGS : début/clôture du tour, paris/gains, jetons de session, statuts du fournisseur.
Paiements/PSP : dépôts/retraits, webhooks des statuts, chargeback, 3-D Secure.
KYC/AML : vérifications, contrôles de sanctions/RER, suivi des transactions.
Risk/Fraud : scoring, déclencheurs, recommandations de verrouillage.
Comms : e-mail/SMS/push, limites de newsletter, modèles.

Chaque type a sa propre machine à événements et SLA - l'adaptateur doit normaliser.

3) Contrat et mapping (interne ↔ externe)

• Nous entrons Published Language à l'intérieur de l'adaptateur et ne poussons jamais le champ du fournisseur vers l'extérieur.
• Tous les messages portent 'tenant _ id', 'region', 'provider _ id', 'opération _ id', 'version _ ts'.
• Prise en charge de plusieurs versions de schémas externes via des 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 et ordre

Request de-dup : 'Idempotency-Key : <operation_id>' dans les requêtes ; storim '(op_id → statut final/réponse)' avec TTL.
Webhook de-dup : table 'inbox (fournisseur, event_id)' comme PK.
Ordre par clé : Sérialisons les appels et le traitement par 'aggregate _ id' (par exemple, 'round _ id' ou 'psp _ tx _ id').
Outbox/Inboxing : messagerie transactionnelle sur les deux bords de la chaîne.

5) Fiabilité : Timeouts, Retrai, circuit breaker

Temporisation : court client-side (p95-orienté), séparé pour connect/read.
Retrai : uniquement sur retryable (5xx/timeout/429), backoff exponentiel + full jitter, limite de tentative et dedline partagée.
Circuit Breaker : ouvrir lorsque les erreurs/latences augmentent ; graceful degradation (par exemple, désactiver les fiches secondaires RGS, mettre « en attente du résultat »).
DLQ : messages « toxiques » avec une riche méta-information, redrave sécurisé.

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) Limites de taux, quotas, concurrence

Respecter les restrictions du fournisseur (RPS, burst, concurrence).
Mettez en œuvre un WFQ/DRR per-tenant (fairness) afin que le client « bruyant » ne mange pas le budget.
Respectez les titres 'Retry-After '/' X-RateLimit'.
Files d'attente internes + backpressure sur le fournisseur.

7) Sécurité et conformité

Transport : mTLS, TLS 1. 2 +, suites cipher à jour, certificats pinning si possible.
Authenticité : OAuth2 client-credentials/MTLS, HMAC (hachage de corps signé + timestamp), clés API.
Minimisation des PII : uniquement les champs nécessaires ; déguisement/rédaction dans les loges et DLQ.
Secrets : KMS/HashiCorp Vault, rotation automatique, isolation par tenant/région.
Conformité : PCI DSS pour PSP, stockage de tokens au lieu de PAN, GDPR/lois de données locales.

8) Multi-tenant et multi-région

Configuration des clés/endpoints par tenant/région.
Résidence de données : les appels sont faits à partir de la région « maison » ; la région croisée n'est que des agrégats.
Isolation : propres pools de connexion et limites 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) Observabilité : métriques, logs, tracing

• Succès/erreurs par classe (2xx/4xx/5xx/timeout/429).
• p50/p95/p99 latitude selon la méthode.
• Déclenchement de rate-limit, ouverture/fermeture breaker, DLQ-rate, redrive-success.
• Logs de structure : 'tenant _ id', 'provider _ id', 'operation _ id', 'endpoint', 'status', 'attempt', 'backoff _ ms'.
• Tracing : un seul 'trace _ id', les spans' serialize → send → receive → map → publish ', les balises' schema _ version ',' region '.

10) Versioning et ficheflags

Maintenir en parallèle v1/v2 le contrat externe ; les migrations sont canaries/par tenants.
Toute nouvelle fiche fournisseur - derrière le drapeau ; commutation sans sortie.
Traité d'évolution : additive-first, validation rigoureuse des schémas (JSON Schema/Proto).

11) Pleybooks (runbooks)

1. Vague 429/limites : inclure la trottinette globale, respecter « Retry-After », redistribuer les fenêtres entre les tenants.
2. Croissance des temporisateurs : réduire la concurrence, augmenter les temporisateurs avec soin, ouvrir le breaker, activer la dégradation des fiches.
3. Schema mismatch : geler le redrive, activer le mapper compatible, effectuer le backfill/recasing.
4. Flap webhooks : passer en mode pull/reconcile, appliquer inbox-dedup.
5. Incident chez le fournisseur : passer au bac à sable/DC de secours (le cas échéant), activer les opérations « différées ».

12) Tests

Tests contractuels : producteur/consommateur contre les fiches fixes du fournisseur.
Tests de chaos : retards, drops, out-of-order, doublons, réponse partielle, rupture de connexion.
Performance : stress sur les épices burst ; mesure p95/p99, comportement breaker.
Idempotence : la répétition des mêmes 'opération _ id' ne crée pas d'effets supplémentaires.
E2E dans les bac à sable : scripts happy-path/chargeback/spores/annulation/recalk.

13) Options de mise en œuvre (deployment patterns)

Adaptateur de service séparé : + isolation, versions indépendantes, réseau −.
Sidecar/plugin : + localisation des appels, − plus difficile de gérer les versions.
Bibliothèque : + simple à intégrer, − haute coupling et versions variées.

Recommandation : un adaptateur de service avec une API claire et son cycle de sortie.

14) Exemple d'API adaptateur (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 avec 'provider _ event _ id' → 'inbox' (PK sur '(provider,event_id)') → mapping → l'événement de domaine 'PaymentAuth....'.

15) Erreurs typiques

Le déplacement du schéma externe « brut » dans le domaine → une connectivité rigide et des migrations coûteuses.
Manque d'idempotence et inbox/outbox → prises d'effets et états fantômes.
Retrai sans jitter/limites → tempête et ban par rate limit.
Le seul pool mondial sans fairness → un seul tenant « met » tout le monde.
Les logs sans ID/ID PII ne peuvent → enquêter sur les incidents et les risques de complication.
Il n'y a pas de canaries/drapeaux → la sortie brise tout le monde à la fois.
Ignorer 'Retry-After' et les horaires de service du fournisseur.

16) Chèque-liste avant la vente

• Mapping de schémas externes → langage interne ; versions et rétrocompatibilité.
• Idempotence des requêtes/webhooks ('opération _ id', 'inbox').
• Taimauts, retraits avec full-jitter, circuit breaker, DLQ et sécurité redrive.
• Rate limits и fairness per tenant; respect de « Retry-After ».
• mTLS/OAuth/HMAC, rotation des secrets, minimisation PII, audit d'accès.
• Isolement régional et résidence de données ; configi per tenant/region.
• Métriques p95/p99, erreur par classe, breaker/429/DLQ-rate ; tracing.
• Bac à sable et tests contractuels ; rollout canarien et ficheflagi.
• Pleybooks d'incidents et formation sur appel.
• Documentation : SLA, limites, schémas, processus d'évolution.

Conclusion

Les adaptateurs de fournisseurs sont un bouclier et un traducteur entre votre domaine et le monde extérieur. Une ACL forte avec idempotence, contrôle des erreurs et observabilité rend les intégrations prévisibles, réduit le coût des changements chez le fournisseur et protège contre les « pannes de chaîne ». Concevez les adaptateurs comme des composants autonomes et contrôlables - et votre « monde extérieur » cessera de briser l'architecture interne.