04. Idempotence et reprises après incident

Comprendre le mécanisme

Une méthode idempotente possède un effet intentionnel équivalent lorsqu’elle est répétée selon son contrat. Cela ne promet pas des codes de réponse identiques : une suppression répétée peut constater un état déjà absent. Un timeout crée souvent une incertitude, car le serveur peut avoir appliqué la modification avant que la réponse ne se perde. Le client ne peut pas conclure à un échec métier uniquement à partir du silence du réseau.

Raisonner et vérifier

Pour une création sensible, définissez un identifiant de demande et un stockage durable du résultat associé. La même clé avec un contenu différent doit être traitée selon une politique explicite, souvent comme un conflit. Une variable PHP en mémoire ne protège pas plusieurs instances ni une reprise après redémarrage. Testez le point où l’effet est validé mais où la réponse est perdue : c’est là que l’idempotence devient observable.

Issue incertaine

Un timeout peut suivre un commit réussi. La réponse peut se perdre après validation de l’effet. Un serveur peut commettre l’écriture puis perdre la réponse. Le timeout décrit l’observation du client, pas l’absence de résultat ; une reprise aveugle peut donc créer un doublon.

Identité stable

Une clé peut relier demande et résultat durable. La durée de vie mémoire ne fournit pas cette persistance. Une clé de demande identifie une intention métier et son résultat durable. Réutilisez-la lors d’une reprise de cette même intention, dans le délai et le périmètre définis par le contrat.

Contenu lié

La même clé doit suivre un contrat de contenu. La réutilisation contradictoire doit être définie et contrôlée. Associez clé et empreinte ou représentation canonique du contenu pertinent. Une même clé avec un montant différent doit être refusée ou traitée selon une politique explicite, jamais assimilée silencieusement à la première opération.

Périmètre acteur

L’acteur fait partie du périmètre de déduplication. Un identifiant de demande n’accorde pas d’autorisation. Incluez tenant ou acteur dans l’unicité lorsque le contrat l’exige. Une clé choisie par un client ne doit pas lui permettre d’obtenir le résultat ou le statut d’une opération appartenant à un autre.

Concurrence

Une contrainte unique aide contre la concurrence. Des demandes concurrentes peuvent passer le même précontrôle. Une lecture suivie d’une insertion sans contrainte peut laisser deux demandes concurrentes gagner. Utilisez une unicité durable et traitez son conflit, avec un état en cours défini pour les traitements longs.

Restitution

Le résultat connu peut être restitué à la reprise. La restitution évite un second effet pour la même demande. Après succès déjà connu, retournez le résultat enregistré sans répéter l’effet. Définissez ce qui est conservé et pendant combien de temps, notamment pour les données sensibles ou les réponses devenues volumineuses.

Nouvelle clé

Une nouvelle clé peut représenter une autre demande. La déduplication dépend de l’identité conservée. Changer la clé après un timeout peut annoncer une nouvelle opération au fournisseur. Gardez la référence initiale et recherchez son état plutôt que contourner la déduplication pour obtenir rapidement une réponse.

Atomicité locale

Effet et enregistrement du résultat doivent être cohérents. Une panne entre les deux peut laisser un état ambigu. L’effet SQL et son enregistrement de déduplication doivent être cohérents. Pour une frontière externe, utilisez états durables et réconciliation ; une transaction locale ne peut pas annuler magiquement un effet prestataire.

Effet intentionnel

L’idempotence concerne l’effet intentionnel. Les métadonnées peuvent changer sans nouvel effet métier. Une reprise peut ajouter un log technique tout en conservant un seul débit. Définissez précisément l’effet métier qui doit rester unique, au lieu d’exiger que tout octet de toutes les réponses soit identique.

Panne critique

Le test important inclut la perte après commit. Ce cas ne couvre pas l’effet réussi dont la réponse est perdue. Simulez un succès durable puis une réponse perdue, et reprenez avec la même clé. Vérifiez nombre d’effets et résultat retrouvé ; un échec avant traitement ne couvre pas cette fenêtre.

Atelier guidé : lire, expliquer et vérifier le code

Envoi 1 : key=lab-1, amount=100 ; résultat durable connu
Envoi 2 : key=lab-1, amount=200
Politique : une même clé ne peut pas représenter deux contenus différents.

Les deux envois utilisent lab-1 mais présentent des montants différents. Le contrat interdit cette réutilisation incompatible : il faut refuser sans second effet. Ajoutez un troisième envoi identique au premier pour démontrer la reprise légitime et la restitution du résultat déjà durable.

Aucune annulation n’est montrée. La même identité de demande est présentée avec un contenu incompatible. Cela violerait la règle donnée. Le résultat existant concerne 100, pas 200.

Travail pratique : Simulez une perte de réponse après commit, puis rejouez la demande. Ajoutez un essai avec la même clé mais une autre quantité.

Critères de correction : Utilisez une contrainte unique et enregistrez résultat et effet de façon cohérente. Vérifiez une seule réservation, la restitution du résultat connu et le refus documenté de la réutilisation contradictoire.

PSP sans réponse : conserver l’incertitude et la référence

Un timeout peut survenir après que le prestataire a accepté le débit. Le client ne sait alors pas si l’effet a eu lieu ; le classer automatiquement en échec puis émettre un autre débit crée un risque de double effet.

Conservez un état inconnu ou en attente avec la référence et la clé initiales. Consultez l’état distant lorsque le contrat le permet. Si une reprise est autorisée, réutilisez la même opération avec la même clé et les mêmes paramètres, dans la portée et la durée d’idempotence documentées. Une nouvelle clé n’est pas un simple détail de transport : elle peut désigner une nouvelle intention.

Testez réponse perdue après succès et traitement encore en cours avec le simulateur PSP. Vérifiez un seul effet et une convergence d’état après rapprochement. Bornez les tentatives et prévoyez une intervention pour l’incertitude persistante ; la politique doit éviter aussi bien le double débit que l’oubli silencieux d’un débit réellement effectué.

Points de vigilance : La reprise doit respecter la portée, la durée et les conditions d’idempotence du PSP ; l’état distant doit être clarifié. Un nouvel identifiant peut être interprété comme une nouvelle opération alors que la première a réussi. Un rollback local ne commande pas le système distant. Le premier acquéreur peut avoir accepté : un basculement aveugle crée un risque de double débit.