Si une opération peut être rejouée sans changer le résultat, les retries deviennent sûrs — et la plupart des problèmes de livraison disparaissent.
⏱️ Durée : environ 105 minutes · 🎓 Niveau : avancé · 🏅 Badge : Rejoueur sans danger
🎬 L'histoire
Léo clique deux fois sur « Payer » parce que la page tarde. Son navigateur envoie deux requêtes. Le paiement passe deux fois. Un autre jour, le service de paiement répond lentement ; l'inscription relance ; la carte est débitée deux fois. Un troisième jour, un message de la file est livré en double après un redémarrage, et un cours est facturé deux fois à un formateur.
« Trois causes différentes, une seule cure, dit Sam : rendre l'opération idempotente. Une opération idempotente, tu peux la jouer une fois ou dix fois, l'état final est le même. Alors les doublons ne font plus peur. »
Tu apprends à reconnaître les opérations naturellement idempotentes, à créer des clés d'idempotence, à implémenter une déduplication atomique avec une base de données, et à gérer les cas difficiles : requêtes concurrentes, réutilisation de clé, panne entre l'effet et l'enregistrement.
🎯 Ta mission
À la fin, je serai capable de :
- définir l'idempotence et distinguer opérations naturellement idempotentes ou non
- implémenter une clé d'idempotence avec un stockage atomique (contrainte d'unicité)
- gérer les requêtes concurrentes portant la même clé et la réutilisation d'une clé avec une autre charge
- rendre un consommateur de messages idempotent en rendant atomique effet et enregistrement
- décrire la durée de conservation des clés et ses compromis
🧩 Défi d'échauffement (5 XP)
Un interrupteur « allumer » est-il idempotent ? Et un bouton « changer l'état de la lampe » (bascule) ? Si tu appuies par erreur deux fois sur chacun, quel est l'état final ? Donne trois exemples d'actions de la vie quotidienne qui sont idempotentes, et trois qui ne le sont pas.
💡 Le concept
Définition
Une opération f est idempotente si l'appliquer plusieurs fois donne le même état que l'appliquer une fois : f(f(x)) = f(x).
| Idempotente | Non idempotente |
|---|---|
PUT /membres/42 {nom: "Ada"} (remplace) | POST /paiements (crée) |
DELETE /cours/7 | incrementer(compteur) |
solde = 60 (affectation) | solde -= 40 |
| « marquer comme lu » | « envoyer un e-mail » |
INSERT ... ON CONFLICT DO NOTHING | INSERT ordinaire |
(Le résultat de DELETE répété peut changer — 200 puis 404 — mais l'état final est le même.)
Pourquoi c'est vital en distribué
Les retries, les doublons de messages, les rejeux après panne sont inévitables (missions 2 et 3). Au moins une fois + idempotence = effet exactement une fois.
Rendre naturellement idempotent
Transformer une opération relative en opération absolue :
| Au lieu de | Utiliser |
|---|---|
solde -= 40 | solde = 60 (avec contrôle de version) ou un enregistrement debit(id=…, 40) unique |
| « ajouter l'élément à la liste » | ensemble (set) ou « ajouter s'il n'existe pas » |
compteur += 1 | compteur dérivé du nombre d'événements distincts |
La clé d'idempotence
Quand l'opération est intrinsèquement non idempotente (créer un paiement), le client génère une clé unique (UUID) pour chaque intention et la joint à la requête. Le serveur :
- regarde si la clé a déjà été vue ;
- si oui : renvoie la réponse mémorisée sans ré-exécuter ;
- si non : exécute, enregistre résultat et clé, répond.
Règles :
- la clé identifie une intention, pas une tentative : toutes les relances d'une même intention portent la même clé ;
- vérifier la charge : la même clé avec un corps différent est une erreur (422/409) ;
- atomicité : l'enregistrement de la clé et de l'effet doivent se faire dans la même transaction, sinon une panne entre les deux crée un doublon ou une perte ;
- concurrence : deux requêtes simultanées avec la même clé ne doivent pas toutes les deux exécuter : contrainte d'unicité en base ou verrou ;
- durée de conservation : assez longue pour couvrir les relances (24 h typiquement), assez courte pour limiter l'espace.
États d'une clé
inconnue → en_cours → terminée (avec réponse)
↘ échec définitif (réponse d'erreur mémorisée, ou clé libérée si échec transitoire)
Une requête qui arrive pendant l'état en_cours reçoit 409 « en cours » (ou attend).
Le piège de la panne au mauvais moment
1. débiter la carte ← l'effet est fait
2. [panne]
3. enregistrer la clé ← jamais exécuté
→ au rejeu, la clé est inconnue : on débite de nouveau
Remèdes : (a) effet et clé dans une transaction locale quand le système de stockage est le même ; (b) quand l'effet est externe (API d'un prestataire), transmettre la clé au prestataire (qui déduplique de son côté) ; (c) sinon, un protocole de réconciliation.
Consommateurs de messages idempotents
Une file livre au moins une fois. Le consommateur garde une table messages_traités(id) et, dans la même transaction que l'effet, insère l'identifiant : un message rejoué est ignoré. C'est le patron « boîte de réception » (inbox, mission 8).
Ordre et commutativité
L'idempotence ne suffit pas si les messages arrivent dans un ordre différent. Solutions : numéros de version (n'appliquer que si plus récent), opérations commutatives (ensembles, compteurs CRDT — mission 5).
🧠 Astuce : pour chaque endpoint ou consommateur, demande : « que se passe-t-il si cette requête arrive deux fois, en même temps, ou après une panne ? » Si la réponse est « un problème », ajoute une clé.
🔍 Exemple pas à pas
Problème : implémenter une API de paiement avec clé d'idempotence adossée à une base SQL (unicité atomique), gérer le doublon, la requête concurrente, la clé réutilisée avec une autre charge, et la panne entre effet et enregistrement ; puis rendre idempotent un consommateur de messages.
import hashlib, json, sqlite3, threading
class ErreurApi(Exception):
def __init__(self, statut, message): super().__init__(f"{statut} {message}"); self.statut = statut
class ServicePaiement:
def __init__(self, panne_apres_effet=False):
self.bd = sqlite3.connect(":memory:", check_same_thread=False, isolation_level=None)
self.bd.executescript('''
CREATE TABLE soldes (membre TEXT PRIMARY KEY, solde INTEGER);
CREATE TABLE cles (cle TEXT PRIMARY KEY, empreinte TEXT, etat TEXT, reponse TEXT);
CREATE TABLE paiements (id INTEGER PRIMARY KEY, membre TEXT, montant INTEGER, cle TEXT);
INSERT INTO soldes VALUES ('ada', 100);
''')
self.verrou, self.panne_apres_effet = threading.Lock(), panne_apres_effet
def payer(self, cle, membre, montant):
empreinte = hashlib.sha256(json.dumps([membre, montant]).encode()).hexdigest()
with self.verrou: # sérialise les accès à la connexion partagée
self.bd.execute("BEGIN IMMEDIATE")
try:
ligne = self.bd.execute("SELECT empreinte, etat, reponse FROM cles WHERE cle = ?", (cle,)).fetchone()
ligne:
.bd.execute()
ligne[] != empreinte: ErreurApi(, )
ligne[] == : ErreurApi(, )
json.loads(ligne[]),
solde = .bd.execute(, (membre,)).fetchone()[]
solde < montant:
reponse = {: , : }
:
.bd.execute(, (montant, membre))
.bd.execute(, (membre, montant, cle))
reponse = {: , : solde - montant}
.bd.execute(, (cle, empreinte, json.dumps(reponse)))
.panne_apres_effet:
.panne_apres_effet =
RuntimeError()
.bd.execute()
reponse,
RuntimeError:
.bd.execute();
(): .bd.execute(, (membre,)).fetchone()[]
(): .bd.execute().fetchone()[]
s = ServicePaiement()
reponses = [s.payer(, , ) _ ()]
(, [(r[], doublon) r, doublon reponses], , s.solde())
s.solde() == s.nb_paiements() ==
[d _, d reponses] == [, , , , ] (r == reponses[][] r, _ reponses)
: s.payer(, , ); AssertionError
ErreurApi e: (, e); e.statut ==
s = ServicePaiement(); sorties, barriere = [], threading.Barrier()
():
barriere.wait()
: sorties.append(s.payer(, , ))
ErreurApi e: sorties.append(e)
ts = [threading.Thread(target=requete) _ ()]; [t.start() t ts]; [t.join() t ts]
s.nb_paiements() == s.solde() ==
(, s.nb_paiements())
s = ServicePaiement(panne_apres_effet=)
: s.payer(, , ); AssertionError
RuntimeError e: (, e)
s.solde() == s.nb_paiements() ==
r, doublon = s.payer(, , )
r[] == doublon s.solde() == s.nb_paiements() ==
()
:
():
.bd = sqlite3.connect(, isolation_level=)
.bd.executescript()
():
.bd.execute()
:
.bd.execute(, (message[],))
.bd.execute(, (message[], message[]))
.bd.execute();
sqlite3.IntegrityError:
.bd.execute();
c = Consommateur()
livraisons = [{: , : , : }, {: , : , : }, {: , : , : }, {: , : , : }]
([c.traiter(m) m livraisons])
c.bd.execute().fetchone() == (, )
Lecture :
- Cinq envois de la même intention (même clé) produisent un débit ; les réponses sont identiques, marquées comme doublons.
- La même clé avec une autre charge (99 au lieu de 40) est refusée (422) : la clé identifie une intention précise.
- Huit requêtes simultanées avec la même clé ne créent qu'un paiement (l'unicité est garantie par la base).
- L'effet et l'enregistrement de la clé sont dans la même transaction : une panne les annule ensemble ; le rejeu avec la même clé s'exécute normalement, sans doublon ni perte.
- Le consommateur de messages enregistre l'identifiant du message dans la transaction de l'effet : les doublons sont ignorés, le total facturé est correct (70).
✍️ À toi, avec aide (10 XP)
Un compteur de vues reçoit des événements {"id": ..., "page": ...} livrés au moins une fois (certains en double). La version actuelle fait vues[page] += 1.
- Montre que le résultat est faux avec des doublons.
- Réécris
enregistrer(evenement)pour qu'il soit idempotent (avec une mémoire des identifiants vus, bornée par une fenêtre de 1000 identifiants récents — explique le risque de cette borne). - Propose une alternative qui ne nécessite aucune mémoire des identifiants (indice : conserver l'ensemble des identifiants par page ou utiliser une structure approximative). Quel est son coût ?
💡 Indice 1
Utilise un collections.OrderedDict ou deque + set pour la fenêtre.
💡 Indice 2
Si un doublon arrive après que son identifiant est sorti de la fenêtre, il sera recompté.
💡 Indice 3
Un ensemble par page rend le comptage idempotent et commutatif.
✅ Réponse
from collections import OrderedDict, defaultdict
EVENEMENTS = [{"id": i % 7, "page": "/cours"} for i in range(10)] + [{"id": 100, "page": "/prix"}] * 3
naif = defaultdict(int)
for e in EVENEMENTS: naif[e["page"]] += 1
print("naïf :", dict(naif)) # compte les doublons
class CompteurFenetre:
def __init__(self, fenetre=1000):
self.vus, self.fenetre, self.vues = OrderedDict(), fenetre, defaultdict(int)
def enregistrer(self, e):
if e["id"] in self.vus: return False
self.vus[e["id"]] = True
(.vus) > .fenetre: .vus.popitem(last=)
.vues[e[]] += ;
:
(): .ids = defaultdict()
(): .ids[e[]].add(e[])
(): (.ids[page])
f, a = CompteurFenetre(), CompteurEnsemble()
e EVENEMENTS:
f.enregistrer(e); a.enregistrer(e)
(f.vues) == {: , : } a.vues() == a.vues() ==
f2 = CompteurFenetre(fenetre=)
i (): f2.enregistrer({: i, : })
f2.enregistrer({: , : })
f2.vues[] ==
()
🚀 À toi, en solo (20 XP)
Saga de réservation idempotente. Une réservation enchaîne trois étapes sur trois services : reserver_place(cours), debiter(membre, montant), envoyer_confirmation(membre). Chaque service peut échouer ou répondre en double.
- donne à chaque étape sa propre clé dérivée de la clé de la réservation (
f"{cle}:place", etc.) ; - écris l'orchestrateur avec reprise : un journal enregistre l'étape atteinte ; si le processus plante au milieu, la relance reprend où on en était sans refaire ce qui est fait ;
- écris les trois services avec leur propre déduplication ;
- simule des pannes à chaque point (avant/après chaque appel, avant/après l'écriture du journal) avec une injection exhaustive : pour chaque point de panne possible, rejoue jusqu'au succès ; vérifie que le résultat final est toujours : 1 place, 1 débit, 1 confirmation.
✅ Pistes de correction
class Plantage(Exception): pass
class Service: # chaque service déduplique par clé et compte ses effets
def __init__(self, nom): self.nom, self.vus, self.effets = nom, {}, 0
def appeler(self, cle, charge):
if cle in self.vus: return self.vus[cle]
self.effets += 1; self.vus[cle] = f"{self.nom}:ok"; return self.vus[cle]
class Orchestrateur:
def __init__(self, services, journal, points_de_panne):
self.services, self.journal, self.pannes = services, journal, points_de_panne # journal : dictionnaire durable
self.compteur_points = 0
def point():
.compteur_points +=
.compteur_points .pannes: .pannes.discard(.compteur_points); Plantage()
():
etape (, , ):
.journal.get((cle, etape)):
.point()
.services[etape].appeler(, {})
.point()
.journal[(cle, etape)] =
.point()
():
services = {e: Service(e) e (, , )}
journal, essais = {},
pannes = (points)
:
essais +=
orch = Orchestrateur(services, journal, pannes)
: orch.executer();
Plantage:
{e: s.effets e, s services.items()}, essais
attendu = {: , : , : }
p (, ):
effets, essais = rejouer({p}); effets == attendu, (p, effets)
p (, ):
q (p + , ):
effets, essais = rejouer({p, q}); effets == attendu, (p, q, effets)
()
⚠️ Pièges classiques
| Piège | Pourquoi c'est un problème | Comment l'éviter |
|---|---|---|
| Clé d'idempotence générée à chaque tentative | Chaque relance est une nouvelle intention : doublons | Une clé par intention, réutilisée par les relances |
| Enregistrer la clé et l'effet séparément | Panne entre les deux : doublon ou perte | Même transaction, ou transmettre la clé au prestataire |
| Ne pas vérifier la charge associée à la clé | Une clé réutilisée par erreur renvoie une réponse sans rapport | Empreinte de la requête et erreur 422 |
| Clés conservées trop peu de temps | Un rejeu tardif crée un doublon | Durée supérieure à la fenêtre de relance maximale |
🐉 Mini-boss (40 XP)
API de paiement de HashBox, version industrielle. Écris un service avec :
- création de paiement avec clé d'idempotence (en-tête
Idempotency-Key), empreinte de la requête, réponses mémorisées, expiration à 24 h (horloge simulée) ; - états
en_cours/termineavec réponse 409 pour une requête concurrente ; - remboursement idempotent (un remboursement ne peut dépasser le paiement, même avec des clés différentes pour la même demande métier — précise comment tu le détectes) ;
- consommateur de messages
paiement.confirmeavec boîte de réception atomique ; - test d'injection exhaustive de pannes (avant/après chaque écriture) et de rejeux aléatoires (500 graines : doublons, réordonnancements, pertes de réponse) avec invariants : somme des soldes conservée, un paiement par intention, jamais de solde négatif ;
- rapport : tableau des scénarios de panne et de ce qui garantit chaque invariant.
✅ Pistes de correction
Un bon travail : tables cles(cle, empreinte, etat, reponse, expire), paiements, remboursements, traites; transaction unique pour effet + clé; expiration vérifiée avec horloge injectée; injection de panne par compteur de points; rejeux aléatoires avec invariants vérifiés; tableau où chaque invariant renvoie à un mécanisme (unicité SQL, transaction, empreinte, contraintes CHECK). La réponse au point 3 : une clé métier unique (par exemple remboursement:{paiement_id}:{motif_id}) ou une contrainte SUM(rembourse) <= montant appliquée dans la transaction.
⚡ Quiz éclair (15 XP si 4/5 ou plus)
1. Une opération idempotente est une opération qui :
- A. donne le même état final qu'on l'applique une fois ou plusieurs fois
- B. s'exécute toujours instantanément
- C. ne peut pas échouer
2. Une clé d'idempotence doit être :
- A. nouvelle à chaque tentative
- B. la même pour toutes les relances d'une même intention
- C. secrète et chiffrée
3. Pour qu'un consommateur de messages soit idempotent, on enregistre l'identifiant du message :
- A. dans un journal séparé, plus tard
- B. jamais
- C. dans la même transaction que l'effet
4. 🔁 Révision mission 03 : Avec 3 couches qui réessaient chacune 3 fois, une dépendance en panne totale reçoit :
- A. 27 fois la charge normale
- B. 3 fois la charge
- C. aucune charge
5. 🔁 Révision mission 03 : Un budget de retries sert à :
- A. augmenter le nombre de relances
- B. plafonner les relances à une fraction du trafic pour éviter l'avalanche
- C. supprimer les délais d'attente
✅ Réponses
- A.
- B.
- C.
- A.
- B.
🪞 Je réfléchis (10 XP)
- Quelle opération de ton système, rejouée deux fois, causerait un dommage réel ?
- À quel endroit génères-tu aujourd'hui des identifiants : à chaque tentative, ou par intention ?
🎒 À retenir
- Idempotent : f(f(x)) = f(x) ; relatif → absolu.
- Clé d'idempotence = identifiant d'intention, jamais de tentative.
- Unicité atomique en base ; empreinte de la charge ; états en_cours / terminé.
- Effet et clé dans la même transaction ; sinon transmettre la clé au prestataire.
- Consommateur : boîte de réception atomique ; tester les pannes de façon exhaustive.
flowchart LR
T(["Idempotence"])
T --> R1["1. Idempotent : ffx = fx ; relatif → absolu."]
T --> R2["2. Clé d'idempotence = identifiant d'intention, jamais de tentative."]
T --> R3["3. Unicité atomique en base ; empreinte de la charge ; états encours /…"]
T --> R4["4. Effet et clé dans la même transaction ; sinon transmettre la clé au…"]
T --> R5["5. Consommateur : boîte de réception atomique ; tester les pannes de…"]
Description du schéma : la mission au centre, reliée aux cinq idées à retenir.
🏅 Récompenses
Total possible : 100 XP · 🏅 Badge Rejoueur sans danger
← Mission 03 — Latence, timeout et retry · Mission 05 — Réplication →
HEF-140 — Systèmes distribués

