Qu’est-ce qu’une clé d’idempotence ?
Une clé d’idempotence est un nom unique envoyé avec une requête, pour que le destinataire n’agisse qu’une fois, quel que soit le nombre d’envois. Elle ferme la dernière brèche d’un journal d’étapes : un plantage après un effet, mais avant sa ligne.
Les prestataires de paiement, les services d’e-mail et les files de messages acceptent ces clés pour cette raison précise. Avec un journal et une clé, un effet a lieu une seule fois.
À la fin de cette leçon
Remarque
Je peux rendre une étape répétée sans danger grâce à une clé d’idempotence.
Mots clés
| Mot | Ce que ça veut dire |
|---|---|
| Idempotent | qui a le même effet, fait une fois ou plusieurs |
| Clé d’idempotence | un nom pour une requête, pour reconnaître ses répétitions |
| Au moins une fois | la promesse qu’une chose a lieu, peut-être plusieurs fois |
| Exactement une fois | un effet qui a lieu une fois, jamais zéro ni deux |
| Contrainte d’unicité | une règle de la base qui refuse une deuxième ligne de même valeur |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Un plantage entre l’effet et la ligne
Le moteur exécute le travail d’une étape, puis écrit sa ligne de journal. Entre ces deux moments, il y a une brèche. Si le processus meurt dans cette brèche, l’effet a eu lieu mais le journal l’ignore.
À la reprise, cette étape n’a pas de ligne, alors le moteur l’exécute de nouveau. Le journal donne au moins une fois, pas exactement une fois. L’option --crash-inside du labo plante juste dans cette brèche.
Planter dans le débit, sans clé
docker exec worker python3 order.py order-8 --fresh --crash-inside charge_cardAffichée ici, non exécutée. Appuyez sur Démarrer le labo pour la saisir dans le terminal de votre propre labo.
Reprendre order-8
docker exec worker python3 order.py order-8Affichée ici, non exécutée. Appuyez sur Démarrer le labo pour la saisir dans le terminal de votre propre labo.
Compter les paiements de order-8
docker exec db psql -U durable -c "SELECT workflow, amount FROM payments WHERE workflow = 'order-8'"Affichée ici, non exécutée. Appuyez sur Démarrer le labo pour la saisir dans le terminal de votre propre labo.
La clé change une répétition en réponse
Avec --keyed, le débit porte la clé order-9:charge_card. Le prestataire du labo garde les paiements dans une table où la clé est unique, et insère avec ON CONFLICT DO NOTHING.
Le premier débit ajoute une ligne. La répétition trouve la clé déjà là, n’ajoute rien et répond avec "repeat": true. Le workflow continue avec le même résultat dans les deux cas.
Planter dans le débit, avec une clé
docker exec worker python3 order.py order-9 --fresh --keyed --crash-inside charge_cardAffichée ici, non exécutée. Appuyez sur Démarrer le labo pour la saisir dans le terminal de votre propre labo.
Reprendre order-9 avec sa clé
docker exec worker python3 order.py order-9 --keyedAffichée ici, non exécutée. Appuyez sur Démarrer le labo pour la saisir dans le terminal de votre propre labo.
Compter les paiements de order-9
docker exec db psql -U durable -c "SELECT workflow, idem_key, amount FROM payments WHERE workflow = 'order-9'"Affichée ici, non exécutée. Appuyez sur Démarrer le labo pour la saisir dans le terminal de votre propre labo.
Exemple guidé : le même plantage, deux fois
| Commande | Clé envoyée | Ce qu’a obtenu la reprise | Paiements |
|---|---|---|---|
| order-8 | aucune | un deuxième débit | 2 |
| order-9 | order-9:charge_card | une réponse marquée repeat | 1 |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Une erreur fréquente
Attention
Beaucoup fabriquent une nouvelle clé aléatoire à chaque appel. La reprise envoie alors une nouvelle clé, et le prestataire débite de nouveau. Une clé doit être la même à chaque reprise : construisez-la à partir du workflow et de l’étape, ou gardez-la dans le journal.
À vous : une clé qui change
import uuid
pris = {} # le prestataire de paiement : un paiement par clé
def debiter(cle, centimes):
if cle in pris:
return "répétition, rien de pris"
pris[cle] = centimes
return "débité " + str(centimes)
def fabriquer_cle(commande):
return commande + ":charge_card" # la même à chaque reprise
# Le workflow envoie le débit, plante, et le renvoie.
for essai in [1, 2]:
print("essai", essai, debiter(fabriquer_cle("order-3"), 2500))
print("paiements pris :", len(pris))
# Faites renvoyer commande + str(uuid.uuid4()) à fabriquer_cle et relancez.