Idempotence & Saga, ou concevoir pour « au moins une fois »Idempotency & Saga, or designing for 'at least once'

« Exactly-once » n'existe pas. On conçoit pour « au moins une fois ».'Exactly-once' doesn't exist. You design for 'at least once'.

Le #1 a installé le retry, le #2 le disjoncteur — et tous deux ont laissé une dette qu'ils nommaient sans la régler : « et si l'autre côté répond deux fois ? ». Cette dette a la même racine qu'un second problème, qu'on rencontre dès qu'une opération traverse plusieurs services : le réseau n'est pas fiable. Un message peut se perdre, arriver en double, ou tarder — donc « exactly-once » (l'illusion qu'une action s'exécute exactement une fois) est un mythe que rien ne garantit sur un réseau. On conçoit pour la réalité : « at-least-once », reçu au moins une fois. Deux réflexes en découlent. L'idempotence rend le rejeu inoffensif — une clé pour que le serveur reconnaisse « c'est la même demande » et ne l'exécute qu'une fois. La saga remplace la transaction unique impossible — une suite d'étapes locales, chacune avec une action qui la défait, pour rattraper un workflow qui a échoué à mi-chemin.Issue #1 installed the retry, #2 the breaker — and both left a debt they named without settling: 'what if the other side answers twice?'. That debt shares its root with a second problem, met the moment an operation crosses several services: the network isn't reliable. A message can be lost, arrive twice, or lag — so 'exactly-once' (the illusion that an action runs exactly one time) is a myth nothing guarantees on a network. You design for reality: 'at-least-once', received at least once. Two reflexes follow. Idempotency makes the replay harmless — a key so the server recognizes 'it's the same request' and runs it only once. The saga replaces the impossible single transaction — a sequence of local steps, each with an action that undoes it, to recover a workflow that failed midway.

# deux dettes laissées par les #1 et #2, qui ont la MÊME racine : le réseau n'est pas fiable.
@app.post("/charge")
def charge(amount):
    billing.debit(amount)          # 💥 aucune clé : si le client retente, on débite DEUX fois
    return {"status": "ok"}

def checkout(order):               # un workflow qui traverse trois services…
    reserve_stock(order)           # T1 ✓
    charge(order.total)            # T2 ✓  ← argent pris
    ship(order)                    # T3 💥 le transporteur renvoie 500
    # …pas de transaction qui englobe les trois : T3 échoue, mais T1 et T2 ont eu lieu.
    # résultat : stock réservé, client débité, RIEN d'expédié — et aucun rollback automatique.
# « exactly-once » sur un réseau est un mythe : un message peut se perdre, se dupliquer, tarder.

Le rejeu duplique, le workflow échoue à moitié, et la transaction distribuée verrouille tout.The replay duplicates, the workflow half-fails, and the distributed transaction locks everything.

Ignorer le « at-least-once » a trois coûts. D'abord, sans clé d'idempotence, chaque rejeu — et le retry du #1 en fabrique — ré-exécute l'effet : le client est débité deux fois, reçoit deux mails, voit deux commandes. Ensuite, un workflow qui traverse plusieurs services échoue à mi-chemin : le stock est réservé, l'argent pris, mais l'expédition rate — et comme aucune transaction n'englobe les trois services, rien ne défait automatiquement les étapes déjà faites. L'état reste durablement incohérent. Enfin, le remède naïf — une « transaction distribuée » (le commit en deux phases, 2PC) — est pire que le mal : il verrouille toutes les ressources le temps du vote, ne tient pas la charge, et si le coordinateur tombe pendant le vote, tout le monde reste bloqué. Trois manières de payer le fait qu'un réseau n'est ni fiable ni transactionnel.Ignoring 'at-least-once' has three costs. First, without an idempotency key, every replay — and #1's retry manufactures them — re-runs the effect: the customer is charged twice, gets two emails, sees two orders. Then, a workflow crossing several services fails midway: stock is reserved, money taken, but shipping fails — and since no transaction wraps the three services, nothing automatically undoes the already-done steps. The state stays durably inconsistent. Finally, the naive cure — a 'distributed transaction' (two-phase commit, 2PC) — is worse than the disease: it locks all resources during the vote, doesn't hold under load, and if the coordinator falls mid-vote, everyone stays blocked. Three ways to pay for the fact that a network is neither reliable nor transactional.

def checkout(order):
    reserve_stock(order)          # T1 commit chez l'inventaire ✓
    billing.debit(order.total)    # T2 commit chez billing ✓  — et SANS clé : un retry re-débite
    ship(order)                   # T3 💥 le transporteur renvoie 500
    # pas de "except" qui défasse T1 et T2 : ils sont commités, chez d'autres services.
# → argent pris, stock bloqué, rien d'expédié. l'incohérence est PERMANENTE.
# et si checkout est retenté en entier : 2e réservation, 2e débit. on aggrave en réessayant.

Pas de rollback global — chaque pas en avant mémorise son pas en arrière.No global rollback — each step forward memorizes its step back.

La saga remplace la transaction unique impossible par une chorégraphie : des étapes locales qui avancent, chacune sachant comment se défaire. L'animation joue une commande qui traverse trois services — réserver, débiter, expédier —, puis fait échouer la dernière étape. Comme rien ne peut « rollback » ce qui est déjà commité ailleurs, la saga rejoue les compensations à rebours : rembourser, libérer. Suis le sens de la flèche — vers l'avant tant que tout va bien, vers l'arrière dès qu'une étape lâche — et regarde le système revenir, pas à pas, à un état cohérent.The saga replaces the impossible single transaction with a choreography: local steps that move forward, each knowing how to undo itself. The animation plays an order crossing three services — reserve, charge, ship —, then fails the last step. Since nothing can 'roll back' what's already committed elsewhere, the saga replays the compensations backward: refund, release. Follow the arrow's direction — forward while all is well, backward the moment a step fails — and watch the system return, step by step, to a consistent state.

def checkout_saga(order):
    done = []                                   # pile des étapes réussies, pour compenser
    steps = [
        (reserve_stock, release_stock),         # (action, compensation)
        (charge,        refund),                # charge porte une clé d'idempotence
        (ship,          None),
    ]
    try:
        for action, compensate in steps:
            action(order, key=order.id)         # transaction LOCALE, idempotente▸ à toiyour turn — une étape vient de réussir — que faut-il retenir pour pouvoir la défaire plus tard ?a step just succeeded — what must you record to be able to undo it later? · cliquer pour révélerclick to reveal    except StepFailed:▸ à toiyour turn — une étape a échoué — dans quel ordre rejoue-t-on les compensations des étapes déjà faites ?a step failed — in what order do you replay the compensations of the steps already done? · cliquer pour révélerclick to reveal        raise SagaAborted()

Nier le doublon, ou recoller une transaction qui verrouille tout.Denying the duplicate, or re-gluing a transaction that locks everything.

Deux pièges symétriques encadrent le bon usage. Le premier nie la réalité « at-least-once » : on expose une mutation sans clé d'idempotence, et le moindre rejeu — que le retry du #1 fabrique en routine — débite, crée ou notifie deux fois. Le second sur-réagit : effrayé par l'incohérence, on tente de recoller une transaction ACID par-dessus les services, via un commit en deux phases. Mais le 2PC verrouille toutes les ressources le temps du vote, s'effondre sous la charge, et gèle tout le monde si le coordinateur tombe au mauvais moment. Et entre les deux, le piège le plus courant : le workflow multi-services sans rien — ni clé, ni compensation, ni 2PC — où une étape ratée laisse une incohérence définitive. Bascule le toggle : repère le débit sans clé, et la transaction distribuée qui rigidifie ce qu'on avait découpé.Two symmetric traps frame correct use. The first denies the 'at-least-once' reality: you expose a mutation with no idempotency key, and the slightest replay — which #1's retry manufactures routinely — charges, creates or notifies twice. The second over-reacts: scared of inconsistency, you try to re-glue an ACID transaction over the services, via two-phase commit. But 2PC locks all resources during the vote, collapses under load, and freezes everyone if the coordinator falls at the wrong moment. And between the two, the commonest trap: the multi-service workflow with nothing — no key, no compensation, no 2PC — where a failed step leaves a permanent inconsistency. Flip the toggle: spot the keyless charge, and the distributed transaction that rigidifies what you'd split apart.

# at-least-once assumé : clé d'idempotence sur chaque mutation + saga avec compensations
@app.post("/charge")
def charge(amount, idempotency_key):
    if not store.insert_if_absent(idempotency_key, PENDING):  # réserve la clé ATOMIQUEMENT
        return store.await_result(idempotency_key)  # déjà vue (même en parallèle) : MÊME résultat,
                                                    #   sans ré-exécuter — le rejeu est inoffensif
    result = billing.debit(amount)
    store.put(idempotency_key, result)          # on mémorise (clé → résultat)
    return result

def checkout_saga(order):
    done = []
    for action, compensate in [(reserve, release), (charge, refund), (ship, None)]:
        action(order, key=order.id); done.append(compensate)   # étapes LOCALES idempotentes
    # échec en cours de route → on rejoue les compensations à rebours (cf. ch. 03)
# at-least-once : rejouer ne duplique rien (clé), et un workflow à demi ne reste pas incohérent.

Exiger « une seule fois », ou concevoir pour « au moins une fois ».Demanding 'exactly once', or designing for 'at least once'.

Quand ne pas dégainer clé ou sagaWhen not to reach for a key or a saga

L'idempotence et la saga ont un loyer : un état à stocker pour dé-doublonner, des inverses à concevoir et à maintenir, une fenêtre d'incohérence visible à assumer. On s'en passe — et c'est correct — quand :Idempotency and the saga have rent: a state to store for de-duplication, inverses to design and maintain, a window of visible inconsistency to accept. You skip them — and that's fine — when:

• l'opération tient dans une seule transaction ACID locale : un monolithe, une base, un commit. Inutile de découper en saga ce que la base sait rendre atomique d'elle-même — c'est réintroduire à la main une garantie qu'on avait gratuitement (cf. Vol 6 #1 : la frontière logique avant la frontière réseau).the operation fits in a single local ACID transaction: one monolith, one database, one commit. No need to split into a saga what the database makes atomic on its own — that's hand-reintroducing a guarantee you had for free (cf. Vol 6 #1: the logical boundary before the network one).
• l'opération est naturellement idempotente : une lecture, un « mettre à tel état » (PUT), un calcul sans effet de bord. La rejouer donne déjà le même résultat ; une clé n'ajoute qu'un état inutile à maintenir.the operation is naturally idempotent: a read, a 'set to this state' (PUT), a side-effect-free computation. Replaying it already yields the same result; a key only adds useless state to maintain.
• le workflow n'a qu'une seule étape mutante : s'il n'y a rien à enchaîner ni à défaire après elle, il n'y a pas de saga à orchestrer — une clé d'idempotence sur cette étape suffit à couvrir le rejeu.the workflow has a single mutating step: if there's nothing to chain or undo after it, there's no saga to orchestrate — an idempotency key on that step is enough to cover the replay.

Le réflexe n'est donc pas « mets une clé et une saga partout » : c'est « cette opération franchit-elle une frontière réseau, et peut-elle être rejouée ou interrompue à mi-chemin ? Alors rends-la idempotente, et donne au workflow ses compensations. Sinon, une transaction locale fait déjà tout le travail. »So the reflex isn't 'put a key and a saga everywhere': it's 'does this operation cross a network boundary, and can it be replayed or interrupted midway? Then make it idempotent, and give the workflow its compensations. Otherwise, a local transaction already does all the work.'

Mot de l'éditeurFrom the editor

Ce numéro clôt le Vol 7 en répondant à la seconde moitié de sa question fondatrice. « Qu'est-ce qui se passe quand l'autre côté ne répond pas — ou répond deux fois ? » Les #1 et #2 ont traité le « ne répond pas » : le retry pour le hoquet, le disjoncteur pour la mort durable. Le #3 traite le « répond deux fois » : l'idempotence pour que le rejeu n'abîme rien, la saga pour qu'un workflow brisé se rattrape. Les trois numéros ne sont pas trois recettes indépendantes — c'est une seule conviction déclinée : sur un réseau, l'échec et la répétition ne sont pas des exceptions, ce sont des états normaux. Le réseau oublie (d'où le retry et la saga), il répète (d'où l'idempotence), il tarde (d'où le timeout et le disjoncteur). La résilience n'est pas une couche qu'on ajoute après : c'est ce qu'on admet d'emblée sur la nature du médium, et qu'on encode dans chaque appel qui franchit une frontière.This issue closes Vol 7 by answering the second half of its founding question. 'What happens when the other side doesn't answer — or answers twice?' Issues #1 and #2 handled the 'doesn't answer': the retry for the hiccup, the breaker for lasting death. Issue #3 handles the 'answers twice': idempotency so the replay harms nothing, the saga so a broken workflow recovers. The three issues aren't three independent recipes — they're a single conviction declined: on a network, failure and repetition aren't exceptions, they're normal states. The network forgets (hence the retry and the saga), it repeats (hence idempotency), it lags (hence the timeout and the breaker). Resilience isn't a layer you add afterward: it's what you admit from the start about the medium's nature, and encode into every call that crosses a boundary.

Deux fils se nouent ici. La saga prolonge directement le Vol 6 : une fois la frontière réseau tracée, la transaction qui tenait dans le monolithe ne tient plus, et il faut la remplacer par une chorégraphie — c'est le prix, longtemps différé, de la découpe. Et la « cohérence à terme » qu'on a touchée du doigt — un système qui n'est pas cohérent à chaque instant, mais qui le redevient — n'est pas un détail technique : c'est un théorème. Sous partition réseau, on ne peut pas avoir à la fois la cohérence parfaite et la disponibilité ; il faut choisir. C'est précisément le sujet du Vol 8, qui ferme la série par la scalabilité — le cache et son invalidation, le partitionnement de la donnée, et le théorème CAP qui formalise le renoncement qu'on vient d'apprendre à vivre. On y entrera par notre règle la plus stricte : jamais sans un chiffre.Two threads tie here. The saga directly extends Vol 6: once the network boundary is drawn, the transaction that held inside the monolith no longer holds, and must be replaced by a choreography — that's the long-deferred price of the split. And the 'eventual consistency' we touched — a system not consistent at every instant, but that becomes so again — isn't a technical detail: it's a theorem. Under network partition, you can't have both perfect consistency and availability; you must choose. That's precisely Vol 8's subject, which closes the series with scalability — the cache and its invalidation, data partitioning, and the CAP theorem that formalizes the renunciation we've just learned to live with. We'll enter it through our strictest rule: never without a number.

Les voisins que ce numéro débloqueThe neighbors this issue unlocks

• Idempotency key — l'identifiant unique de la demande, fourni par le client et porté par chaque rejeu. Le serveur l'enregistre avec son résultat ; à la même clé, il renvoie ce résultat sans ré-exécuter. C'est la brique concrète de l'idempotence — celle qui rend le retry du #1 enfin sûr, et sans laquelle « at-least-once » se traduit par « facturé plusieurs fois ».the request's unique identifier, supplied by the client and carried by every replay. The server records it with its result; on the same key, it returns that result without re-running. It's idempotency's concrete brick — the one that finally makes #1's retry safe, and without which 'at-least-once' translates to 'charged several times'.
• Compensating transaction — l'inverse métier d'une étape déjà commitée : rembourser annule débiter, libérer annule réserver. Ce n'est pas un rollback technique mais une nouvelle transaction qui défait l'effet visible de la précédente. C'est le cœur de la saga, et sa principale difficulté de conception : certaines actions n'ont pas d'inverse propre, et il faut alors un correctif plutôt qu'une annulation.the business inverse of an already-committed step: refund cancels charge, release cancels reserve. It's not a technical rollback but a new transaction that undoes the previous one's visible effect. It's the saga's core, and its main design difficulty: some actions have no clean inverse, and then you need a correction rather than a cancellation.
• Outbox — le motif qui fiabilise la publication d'événements. Écrire en base puis publier un message sont deux actions séparées : entre les deux, le process peut mourir, et l'événement se perd. L'outbox écrit l'événement dans la même transaction locale que la donnée, dans une table dédiée, qu'un relais lit et publie ensuite — au moins une fois. C'est ce qui garantit qu'une étape de saga commitée déclenche bien la suivante, sans message perdu : le pont entre la transaction locale et le monde des files (Vol 4 #2).the pattern that makes event publishing reliable. Writing to the database then publishing a message are two separate actions: between them, the process can die, and the event is lost. The outbox writes the event in the same local transaction as the data, into a dedicated table, which a relay then reads and publishes — at least once. It's what guarantees that a committed saga step actually triggers the next, with no lost message: the bridge between the local transaction and the world of queues (Vol 4 #2).

Le kata — écris-le, ne le relis pasThe kata — write it, don't reread it

# test_idempotence.py — la spec EST le harnais : fais-le passer au vert.
# une clé d'idempotence : la même demande, rejouée, ne s'exécute qu'une fois.

def test_premier_appel_execute():
    h = Idempotent(store={})
    sonde = compteur(lambda: debit(100))
    assert h.run("k1", sonde) == 100
    assert sonde.count == 1                       # exécuté une fois, résultat renvoyé

def test_rejeu_meme_cle_ne_reexecute_pas():
    h = Idempotent(store={})
    sonde = compteur(lambda: debit(100))
    h.run("k1", sonde)
    assert h.run("k1", sonde) == 100              # même clé → même résultat…
    assert sonde.count == 1                        # …SANS ré-exécuter : le rejeu est inoffensif

def test_cles_differentes_sont_independantes():
    h = Idempotent(store={})
    assert h.run("k1", lambda: debit(100)) == 100
    assert h.run("k2", lambda: debit(30)) == 30   # une clé par demande distincte

def test_renvoie_le_resultat_memorise():
    h = Idempotent(store={})
    monde = {"montant": 100}
    h.run("k1", lambda: debit(monde["montant"]))
    monde["montant"] = 999                          # le monde change sous nos pieds…
    assert h.run("k1", lambda: debit(monde["montant"])) == 100   # …le rejeu rend l'ANCIEN résultat

def test_l_echec_n_est_pas_memorise():
    h = Idempotent(store={})
    with raises(Transient): h.run("k1", dead)      # le 1er essai échoue…
    assert h.run("k1", lambda: "ok") == "ok"       # …la clé reste libre : on peut vraiment retenter