Un utilisateur valide un paiement, l’écran tourne puis affiche une erreur réseau. Le paiement a-t-il échoué, réussi, ou réussi sans que la réponse soit revenue ? Cliquer une seconde fois peut débloquer le parcours comme créer un double débit. Cette incertitude est le vrai problème que l’idempotence doit résoudre.
Le même risque existe loin de l’interface : un worker termine son traitement puis s’arrête avant d’acquitter le message ; un webhook est livré deux fois ; un client HTTP retente après un timeout ; une tâche planifiée reprend un lot interrompu. Dans tous ces cas, « livré au moins une fois » oblige l’application à supporter plusieurs exécutions d’une même intention.
Le vrai enjeu n’est pas de supprimer les retries. Ils sont indispensables face aux incidents temporaires. Il faut rendre leur effet prévisible dans une application web métier fiable : identifier l’intention, empêcher la concurrence, conserver le résultat et distinguer une erreur transitoire d’un refus définitif.
Une reprise sûre se conçoit avant l’incident. Elle associe chaque commande à une clé stable, un état persistant, des contraintes de base, une politique de nouvelle tentative et un outil de réconciliation. Le support peut alors rejouer un dossier sans deviner si la première exécution a déjà modifié le monde.
Comprendre l’incertitude après une erreur
Une erreur de transport ne décrit pas le résultat métier. Le serveur peut ne jamais avoir reçu la requête, l’avoir refusée, l’avoir validée avant de perdre la connexion, ou être encore en train de la traiter. L’appelant ne peut pas trancher à partir d’un timeout seul.
Retenter est donc rationnel, mais seulement si le serveur reconnaît la même intention. Sans cette reconnaissance, chaque tentative ressemble à une nouvelle commande. Le client doit alors choisir entre abandonner une opération peut-être incomplète et risquer un double effet.
L’idempotence réduit ce dilemme : plusieurs demandes représentant la même intention produisent un seul effet observable. Elle ne garantit ni la disponibilité, ni l’ordre, ni la livraison exactement une fois. Elle rend simplement le rejeu compatible avec l’état déjà atteint.
Définir l’effet qui doit rester unique
Avant de choisir une clé, il faut nommer l’effet. « Traiter la requête » est trop vague. L’effet peut être créer une commande client, réserver une quantité, enregistrer un paiement ou envoyer une notification liée à une version précise du dossier.
Deux payloads identiques ne représentent pas toujours la même intention. Un client peut acheter deux fois le même article à quelques minutes d’intervalle. À l’inverse, deux payloads légèrement différents peuvent appartenir à la même commande corrigée. La déduplication par empreinte du JSON ne suffit donc pas à définir le métier.
La frontière d’idempotence s’écrit avec le propriétaire fonctionnel : « une confirmation par commande et par tentative autorisée », « une écriture de stock par mouvement source », « un e-mail de validation par transition de statut ». Cette phrase devient un invariant testé et une contrainte de données.
Choisir une clé d’idempotence stable
La clé doit être stable pour toutes les tentatives de la même intention. Une valeur aléatoire générée à chaque dispatch échoue précisément lors d’une double soumission : les deux messages reçoivent des identifiants différents et les deux passent. Une référence métier durable est préférable lorsqu’elle existe.
Une clé peut combiner organisation, type d’opération et identifiant fourni par le client. Son périmètre empêche une collision entre deux comptes ou deux endpoints. Le serveur conserve également une empreinte des paramètres pertinents : si la même clé revient avec un autre montant, il refuse la demande au lieu de retourner silencieusement le premier résultat.
La durée de conservation dépend du risque et de la possibilité de rejeu tardif. Un paiement peut nécessiter une trace beaucoup plus longue qu’une génération de prévisualisation. Purger trop tôt réautorise un double effet ; conserver sans limite augmente le volume et peut garder des données inutiles. La politique doit être explicite.
Stripe documente un modèle concret : la première réponse associée à une clé est conservée et les requêtes suivantes récupèrent le même résultat, avec contrôle des paramètres. Sa référence sur les requêtes idempotentes illustre utilement la différence entre clé, exécution et résultat mémorisé.
Conserver résultat et état de traitement
Une table d’idempotence ne contient pas seulement une clé. Elle associe l’intention à son empreinte, son statut, les dates, le résultat public et la référence de l’objet créé. Les états minimaux peuvent être en_cours, réussi, échec_rejouable et échec_final, représentés dans le code par des valeurs explicites.
Lorsqu’une clé déjà réussie revient, l’API restitue une réponse sémantiquement équivalente. Lorsqu’elle est encore en cours, elle renvoie un statut indiquant au client de consulter ou retenter plus tard. Un échec final retourne le même refus tant que l’intention n’a pas changé.
Le résultat mémorisé ne doit pas contenir aveuglément toute la réponse HTTP. Les en-têtes volatils, liens signés et données sensibles ont un cycle de vie propre. Il vaut mieux conserver la référence et reconstruire une représentation stable lorsque le contrat l’autorise.
Fermer la course entre deux requêtes
Le scénario dangereux n’est pas seulement le retry tardif. Deux requêtes peuvent arriver simultanément avec la même clé, lire toutes les deux « absent » et créer chacune un effet. Un test applicatif avant insertion ne ferme pas cette fenêtre.
Une contrainte unique en base sur le périmètre et la clé fournit l’arbitre final. L’application tente de réserver la clé dans une transaction ; une seule insertion gagne. L’autre requête relit ensuite l’état existant et retourne le résultat ou l’état en cours. La documentation PostgreSQL sur les contraintes uniques décrit cette garantie au niveau des données.
Le verrou doit rester court. Maintenir une transaction ouverte pendant un appel à un prestataire bloque inutilement les concurrents et complique les timeouts. La réservation de l’intention, l’appel externe et la finalisation forment des étapes distinctes dont les états sont observables.
Préférer l’idempotence naturelle
Certaines opérations sont naturellement sûres à répéter. « Fixer le stock à 42 pour la version 18 » converge vers le même état ; « retirer 3 unités » applique un nouvel effet à chaque exécution. Reformuler une commande en état cible simplifie parfois toute la reprise.
Une mise à jour conditionnelle peut aussi protéger la transition : passer de à_valider à validé seulement si la version attendue est encore présente. La seconde tentative observe que la transition est déjà effectuée et renvoie le même résultat métier.
Cette stratégie n’élimine pas toujours la clé. Un e-mail, un débit ou un appel externe reste un effet séparé. Chaque frontière doit décider si elle converge naturellement, s’appuie sur une contrainte ou conserve un journal des commandes traitées.
Protéger les appels vers des services externes
Le système local peut garantir l’unicité de sa commande sans maîtriser le prestataire. Si l’API externe accepte une clé d’idempotence, l’application transmet une clé dérivée de l’intention métier et la conserve avec la requête. Toutes les tentatives réutilisent exactement cette valeur.
Si le prestataire ne propose aucun mécanisme, il faut chercher une référence client unique, une opération de consultation ou une réconciliation. Après un timeout de paiement, l’application interroge le statut avec la référence avant de déclencher un second débit. Retenter à l’aveugle n’est pas une stratégie.
Les appels non idempotents impossibles à vérifier exigent une intervention bornée. Le dossier passe dans un état résultat_inconnu, bloque les effets suivants et présente au support les preuves disponibles. Cette prudence coûte moins cher qu’une automatisation qui amplifie une ambiguïté financière.
Distinguer retry, refus et abandon
Une nouvelle tentative convient à une panne temporaire : timeout, indisponibilité, limitation de débit ou verrou concurrent. Une erreur de validation, un droit absent ou une règle métier refusée ne disparaîtra pas en attendant. La classification des exceptions doit décider du chemin, au lieu de laisser tous les échecs épuiser la même politique.
Contre-intuitivement, augmenter le nombre de retries peut réduire la disponibilité : les tentatives occupent les workers, accentuent la pression sur une dépendance déjà dégradée et retardent les commandes saines. La temporisation et le plafond protègent donc aussi le système appelé.
Le délai augmente entre les tentatives et ajoute une part aléatoire pour éviter que tous les workers ne reviennent en même temps. Le nombre de retries, la durée maximale et le seuil d’arrêt dépendent du service appelé et de la promesse utilisateur. Une commande urgente n’attend pas comme une synchronisation nocturne.
Après le dernier essai, le message ne doit pas disparaître. Symfony Messenger permet de configurer stratégie de retry et transport d’échec ; sa documentation sur les messages, retries et échecs rappelle également qu’une livraison multiple reste normale et que le handler doit supporter ce cas.
Relier transaction locale et publication
Une autre fenêtre apparaît lorsqu’une transaction base réussit mais que la publication du message échoue. La commande existe, mais le traitement suivant ne démarre jamais. Inverser l’ordre crée le risque opposé : le consommateur agit alors que la transaction locale sera annulée.
L’outbox enregistre l’événement à publier dans la même transaction que la modification métier. Un relay lit ensuite cette table, publie et marque l’élément comme transmis. Une double publication reste possible ; le consommateur conserve donc son inbox ou son invariant idempotent.
Les responsabilités restent séparées : l’entrée est la commande validée, la sortie est l’événement persistant, et le module propriétaire assume la journalisation. Le contrat de publication nomme la dépendance, la file cible et le comportement de retry ; ces éléments rendent l’échec reproductible sans confondre transaction et transport.
Le pattern ne garantit pas une magie « exactement une fois ». Il transforme une fenêtre invisible en deux responsabilités observables : engagement local et livraison. Les éléments d’outbox trop anciens deviennent une alerte actionnable, et la publication peut être reprise sans reconstruire l’événement.
Traiter événements anciens et désordonnés
Dédupliquer ne suffit pas si les événements arrivent dans le mauvais ordre. Un webhook expédié peut précéder préparé, puis une ancienne livraison tente de faire régresser le statut. La clé reconnaît chaque événement, mais le modèle doit encore protéger sa chronologie.
Une version croissante, un numéro de séquence ou une date émise par la source permet de refuser les états anciens. La règle dépend du domaine : certains événements indépendants peuvent être appliqués dans n’importe quel ordre, d’autres exigent une transition précise.
Les arrivées tardives ne sont pas nécessairement des erreurs. Elles peuvent compléter l’historique sans modifier l’état courant. Séparer journal reçu et projection active offre cette finesse : la preuve reste disponible tandis que la vue métier ne régresse pas.
Accuser réception des webhooks sans perdre l’événement
Le endpoint vérifie d’abord signature, horodatage et taille, puis conserve l’identifiant du fournisseur et le payload brut autorisé. Il répond rapidement après cette persistance. Le traitement métier se fait ensuite dans un worker, ce qui évite qu’un fournisseur retente parce qu’une opération interne a pris trop de temps.
Une contrainte unique sur fournisseur et identifiant d’événement neutralise les doublons. Si le fournisseur ne donne aucun identifiant fiable, l’équipe définit une clé à partir de références métier stables ; une simple empreinte du corps reste fragile lorsque des champs sans importance changent.
Le payload brut facilite l’audit, mais sa rétention et son accès doivent respecter les données personnelles. Une version normalisée sert au traitement courant. Si le mapping évolue, le système sait avec quelle version l’événement a été interprété.
Bloquer les doubles actions côté interface
Désactiver un bouton après le premier clic améliore l’expérience, mais ne constitue pas une garantie. Un rechargement, deux onglets ou un client automatisé contourne ce garde-fou. Le serveur reste responsable de l’unicité.
Le formulaire reçoit une clé avant soumission et la renvoie à chaque tentative. Après un timeout, l’interface consulte le statut de cette intention au lieu de générer immédiatement une nouvelle clé. Le message utilisateur distingue « traitement en cours » de « action refusée ».
Pour une opération longue, l’API retourne une ressource de suivi. Le client peut rafraîchir sans relancer le travail. Ce contrat réduit les doubles soumissions et donne aussi au support une référence commune.
Réconcilier avant de rejouer
Une file d’échec ne doit pas être vidée en bloc après un correctif. Le support prévisualise chaque message : clé, effet attendu, état local, statut externe et dépendances suivantes. Le système classe le dossier en déjà convergé, rejouable, à corriger ou à arbitrer.
Le rejeu utilise la même commande et la même clé que l’exécution initiale. Changer la clé pour « forcer » masque l’historique et peut créer le double effet que le dispositif devait éviter. Si une nouvelle intention est réellement nécessaire, elle reçoit une décision métier explicite et une relation vers la précédente.
Les outils de reprise journalisent l’auteur, la date, le motif et le résultat. Une opération sensible propose un lot réduit, un seuil d’arrêt et un rapport avant/après. Le rollback porte sur les changements locaux ; un effet externe déjà confirmé demande une compensation métier distincte.
Le runbook attribue un owner, un seuil de reprise et une règle de rollback. Sa traçabilité relie la clé, le webhook ou la file concernés au résultat final ; aucune dépendance n’est relancée tant que cette lecture ne permet pas de distinguer un effet déjà produit d’une commande encore rejouable.
Rendre les reprises observables
Le tableau de bord suit le nombre d’intentions reçues, les clés répétées, les collisions de paramètres, les traitements en cours trop anciens, les retries par cause et les messages en échec. Ces indicateurs séparent un client insistant d’un service réellement instable.
Chaque journal porte clé d’idempotence, identifiant de corrélation, type de commande et référence métier, sans exposer le payload sensible. Une trace relie requête HTTP, transaction, publication et appel externe. Le support retrouve ainsi un parcours sans rechercher un montant ou une adresse dans les logs.
L’équipe backend PHP suit aussi la performance du worker Symfony, la dépendance API et la durée des transactions Doctrine. Ce monitoring accompagne chaque déploiement : si la file vieillit ou si le temps de convergence dépasse le seuil, le rollback applicatif n’est autorisé qu’après vérification des effets externes.
Les alertes visent une action. Une hausse des doublons neutralisés peut signaler un timeout côté client ; un âge d’outbox croissant indique un relay bloqué ; des messages en échec sur une validation indiquent une mauvaise classification. Chaque alerte nomme le runbook et le propriétaire.
Éprouver trois cas concrets
Paiement validé après un timeout
Cas concret. L’API locale réserve une clé liée à la tentative de paiement et la transmet au prestataire. La connexion tombe après l’appel. Au retry, la même clé récupère le résultat du prestataire ; l’application rattache l’identifiant externe et renvoie la confirmation déjà obtenue.
Si le prestataire ne répond toujours pas, le dossier reste résultat_inconnu. Aucun second paiement n’est lancé. Un job de réconciliation interroge la référence puis passe l’intention à réussi ou rejouable.
Worker arrêté après la décrémentation du stock
Le message de mouvement possède un identifiant métier unique. Dans la même transaction, le handler insère cet identifiant dans l’inbox et applique le mouvement. Si l’insertion viole la contrainte unique lors d’une nouvelle livraison, le stock n’est pas touché et le handler confirme le résultat précédent.
Si la logique peut exprimer un stock cible versionné, elle préfère cette convergence naturelle. Dans les deux modèles, les tests provoquent un arrêt entre effet et acquittement pour démontrer l’absence de double décrément.
Webhook d’expédition reçu dans le désordre
Le système conserve chaque événement avec son identifiant fournisseur et sa séquence. L’événement livré met la projection à jour ; l’événement expédié arrivé ensuite complète l’historique mais ne fait pas régresser la commande.
Un doublon exact retrouve l’événement déjà traité. Un événement portant la même clé et un contenu différent déclenche une alerte de contrat. Le support dispose du payload d’origine, de la normalisation et de la décision appliquée.
Éviter les fausses sécurités
La première erreur consiste à générer la clé trop tard ou à chaque retry. La deuxième stocke seulement les clés réussies : deux exécutions concurrentes peuvent alors commencer ensemble, et les échecs restent impossibles à distinguer des absences.
La troisième confond déduplication et idempotence. Ignorer deux messages au contenu identique peut supprimer deux intentions légitimes ; accepter deux contenus différents sous la même clé peut corrompre le résultat. Le métier doit définir l’identité de la commande et le serveur doit vérifier sa cohérence.
La quatrième retente toutes les exceptions. Un refus permanent sature la file et masque les incidents temporaires. La cinquième vide automatiquement la file d’échec après un déploiement sans vérifier les effets déjà appliqués.
Enfin, une table d’idempotence sans purge, index ni propriétaire devient elle-même un risque. Sa rétention, ses volumes, ses données sensibles et sa procédure de réparation font partie du contrat opérationnel.
Mesurer la qualité des reprises
Le taux de doublons neutralisés montre l’usage du mécanisme, mais pas seul sa qualité. Il faut le relier aux doubles effets constatés, aux intentions bloquées, au temps de convergence et aux collisions de paramètres. Le bon résultat est un effet unique et un état expliqué.
Le délai entre première tentative et résultat final mesure l’expérience réelle. L’âge du plus ancien message, de l’outbox et des états en_cours détecte les traitements abandonnés. La part de reprises manuelles révèle les trous du modèle ou de l’outillage.
Le seuil d’alerte part de la promesse du flux. Si une commande doit converger avant préparation, un dossier encore incertain à cette échéance bloque la suite et alerte l’équipe. Une synchronisation analytique peut accepter une durée différente. Le contexte métier décide.
Plan d’action : sécuriser un flux en six semaines
Semaines 1 et 2 : nommer les intentions et les fenêtres
L’équipe cartographie les entrées, sorties, effets externes, timeouts et retries d’un flux critique. Pour chaque commande, elle écrit l’effet qui doit rester unique, la clé stable, son périmètre et la durée de conservation. Deux scénarios sont joués : double soumission simultanée et perte de réponse après succès.
Elle classe les erreurs en rejouables, finales et inconnues. Le propriétaire métier décide des états qui bloquent la suite. Le contrat précise la réponse renvoyée pour une clé réussie, en cours ou réutilisée avec d’autres paramètres.
Semaines 3 et 4 : fermer la concurrence et les publications
Une contrainte unique réserve l’intention avant l’effet. Les dépendances externes reçoivent la même clé à chaque tentative. L’outbox relie transaction locale et publication ; l’inbox ou l’invariant du handler neutralise les redélivrances.
Les tests interrompent le processus avant l’effet, après l’effet, avant la réponse et avant l’acquittement. L’instrumentation conserve clé, corrélation, statut et cause d’échec. Le tableau de bord expose âges, retries et collisions.
Semaines 5 et 6 : exercer la reprise
Le support prévisualise un lot d’échec et classe les dossiers sans modifier la production. Il rejoue ensuite un échantillon borné avec un seuil d’arrêt. Chaque résultat est rapproché de la source externe et de l’état métier attendu.
La revue finale décide d’étendre, de limiter ou de corriger le mécanisme. Elle attribue la purge, les alertes et le runbook. Un flux n’est déclaré sûr que si une autre personne peut expliquer et reprendre l’incertitude sans consigne orale.
- Définir l’intention métier avant la clé technique.
- Réserver la clé avec une contrainte unique avant l’effet.
- Réutiliser la même clé sur tous les retries et appels externes.
- Conserver résultat, empreinte, statut et durée de rétention.
- Tester concurrence, timeout après succès et redélivrance.
- Réconcilier les états inconnus avant tout rejeu manuel.
Approfondir Messenger et les webhooks
La réception externe demande aussi une politique de signature, de réponse rapide et d’ordre. La sécurisation des webhooks fragiles détaille ces points.
Pour choisir les traitements à placer en file, l’usage de Messenger dans l’exploitation complète la démarche. Quand le diagnostic traverse plusieurs processus, les critères d’introduction du tracing distribué évitent une instrumentation disproportionnée.
Conclusion : rendre le rejeu banal
L’idempotence ne promet pas qu’un message sera livré une seule fois. Elle garantit que plusieurs livraisons de la même intention ne produisent qu’un effet métier. Cette nuance rend les retries utiles au lieu de les transformer en risque.
La clé stable n’est qu’un début. La contrainte unique ferme la concurrence, l’état persistant explique l’exécution, l’outbox protège la publication et la réconciliation traite les réponses inconnues. Chaque frontière externe conserve sa propre garantie.
Une reprise réussie est ennuyeuse : le support identifie l’intention, voit le résultat déjà obtenu ou rejoue la même commande, puis constate la convergence. Aucun script improvisé ni modification directe de données n’est nécessaire.
Dawap peut vous accompagner pour sécuriser vos commandes, webhooks et traitements asynchrones dans une application métier robuste et maintenable.
