Idempotence des mutations

stable@nodefony/frameworkmis à jour 2026-07-19

Ton client envoie POST /charge, le réseau coupe avant la réponse, il retente. Sans garde-fou, tu débites deux fois. L’idempotence garantit qu’une mutation rejouée à l’identique ne s’exécute qu’une fois — la seconde reçoit la réponse mémorisée de la première. Nodefony décide toute la sémantique (statuts, scope, empreinte) dans un helper pur partagé par HTTP et WebSocket, puis délègue le stockage à un store pluggable (mémoire, Redis, SQL).

📍 Documentation › Framework › Idempotence

🧠 Le modèle mental — un verrou par intention#

C’est LA chose à comprendre. store.begin(clé, empreinte) est atomique et rend l’un de quatre verdicts (IdempotencyOutcome, ^{src/nodefony/src/types/IIdempotencyStore.ts:34}) ; le helper les traduit en une décision neutre que le pipeline applique.

Les quatre verdicts du store et leur traduction, décidés par evaluateIdempotency() (^{idempotency.ts:142}) :

• fresh → tu détiens la réservation : exécute l’action, puis obligatoirement complete(clé, réponse) (succès) ou abort(clé) (échec). Verdict rendu : guarded.
• replayed → la réponse de la 1ʳᵉ exécution est renvoyée telle quelle, l’action n’est pas rejouée. Verdict rendu : replay.
• in-flight → une exécution identique est déjà en cours → 409 (le client réessaiera).
• mismatch → la clé a déjà servi pour un autre payload → 422 (^{idempotency.ts:189}).

S’il ne faut retenir qu’une image : begin est un verrou atomique par intention, et tout le reste du pipeline ne fait que traduire son verdict.

📖 Lexique#

Qu’est-ce que c’est ?#

Imagine un ticket de vestiaire. Tu déposes ton manteau, on te donne un numéro. Si tu présentes deux fois le même numéro, on ne te donne pas deux manteaux : on te rend le même. La clé d’idempotence est ce numéro — le client la choisit, le serveur s’engage à ne servir l’intention qu’une fois.

Sans ce ticket, trois choses cassent :

1. Double-effet sur rejeu — le cœur du problème. Un retry réseau, une reconnexion WebSocket, un double-clic : la même intention arrive deux fois et produit deux débits, deux commandes, deux e-mails. Le client ne peut pas distinguer « la requête a échoué » de « la réponse s’est perdue », donc il doit retenter ; c’est au serveur de rendre le retry inoffensif.
2. IDOR sur le cache — si la clé stockée était la clé brute du client, il suffirait de deviner order-42 pour lire la réponse mémorisée d’un autre utilisateur. Nodefony stocke JSON.stringify([identité, cléClient]) (^{idempotency.ts:182}) : l’anti-IDOR n’est pas un contrôle ajouté, il est structurel, encodé dans la clé de cache. Le JSON sert de frontière non ambiguë (aucun séparateur magique qui pourrait entrer en collision).
3. DoS du cache — une clé arbitrairement longue, ou un flot de clés uniques, remplirait la mémoire. Une clé > 255 octets est traitée comme absente plutôt que stockée (IDEMPOTENCY_KEY_MAX, ^{idempotency.ts:36}) et le cache mémoire est borné (DEFAULT_CAP, ^{IdempotencyStore.ts:18}).

❗ Important

L’idempotence n’est pas qu’une commodité de résilience : c’est une brique de sécurité. Une mutation rejouable sans garde-fou est un vecteur d’abus financier (double débit provoqué), et un cache mal scopé est une fuite de données entre comptes.

La vision Nodefony#

Le constat de conception qui compte : la sémantique IETF (quels statuts, quel scope, quelle empreinte) est décidée dans un helper pur, evaluateIdempotency() (^{idempotency.ts:142}), qui ne connaît aucun transport. Il rend un verdict neutre (IdempotencyVerdict, ^{idempotency.ts:50}) que deux appelants traduisent dans leur monde :

• le data plane admin — AdminApiController.idempotencyGate() (^{AdminApiController.ts:158}) → réponse {status, headers, body} ;
• les controllers userland décorés @Idempotent — seam Resolver._callWithIdempotency() (^{Resolver.ts:460}) → nodefonyError typée, ou réponse rejouée.

Conséquence pratique : il est impossible que l’idempotence HTTP et l’idempotence WebSocket divergent — elles partagent la même fonction. C’est le différenciateur du framework (HTTP + WS co-citoyens dans le même contexte controller) appliqué à une brique de sécurité.

Second choix structurant : le stockage est pluggable. Le contrat IIdempotencyStore vit au CORE (^{src/nodefony/src/types/IIdempotencyStore.ts:106}), pas dans @nodefony/framework — pour que @nodefony/redis et @nodefony/drizzle, qui sont sous framework dans le graphe de dépendances, puissent l’implémenter sans créer de cycle.

🚀 Démarrage rapide#

Objectif : rendre POST /api/payments/charge rejouable sans double débit, dans une app générée par nodefony create app.

1. Le controller — une seule ligne à ajouter#

// nodefony/controllers/PaymentController.ts — complet, compile tel quel
import {
  controller,
  Controller,
  Post,
  Body,
  Idempotent,
} from "@nodefony/framework";

interface ChargeInput {
  amount: number;
}

@controller("/api/payments")
class PaymentController extends Controller {
  // STRICT par défaut : une mutation SANS `Idempotency-Key` est rejetée 400,
  // AVANT que ton code ne tourne. Le rejeu de la MÊME clé renvoie la réponse
  // mémorisée sans ré-exécuter l'action.
  @Idempotent()
  @Post("/charge")
  async charge(@Body() body: ChargeInput) {
    // ⚠️ Retourne le PAYLOAD BRUT (pas `this.renderJson(...)`) : c'est cette
    // valeur qui est mémorisée et rejouée telle quelle.
    return { chargeId: "ch_9F2a", amount: body.amount };
  }
}

export default PaymentController;

(Wiring : @controllers([PaymentController]) dans le module de l’app — nodefony create controller le fait pour toi.)

2. Le store — rien à écrire en dev, un mot en cluster#

Le store par défaut est posé automatiquement par le module framework (@services([… , MemoryIdempotencyStore]), src/packages/@nodefony/framework/index.ts:40). En mono-pod, tu n’as rien à configurer. Pour un cluster multi-pod, nomme un store distribué :

// nodefony.config.ts — extrait
use("@nodefony/framework", {
  idempotency: {
    // "auto" (défaut) suit l'infra déclarée. En cluster, nommer explicitement :
    // un nom distribué non câblé fait ÉCHOUER le boot en production (fail-loud)
    // plutôt que dédupliquer per-pod en silence.
    store: "redis",
    // Purge des clés expirées — utile UNIQUEMENT pour un store SQL (drizzle).
    gcIntervalS: 600,
  },
});

3. Ce qu’on observe#

# 1) Sans clé : rejet AVANT le controller (mode strict)
curl -si -X POST http://localhost:5151/api/payments/charge \
  -H 'Content-Type: application/json' -d '{"amount":4200}' | head -1
# HTTP/1.1 400 Bad Request        ← "Idempotency-Key required"

# 2) 1er envoi avec une clé → l'action s'exécute
curl -s -X POST http://localhost:5151/api/payments/charge \
  -H 'Idempotency-Key: 3f6a9c1e-2b7d-4a10-9d31-8e5c2f0a7b64' \
  -H 'Content-Type: application/json' -d '{"amount":4200}'
# {"chargeId":"ch_9F2a","amount":4200}

# 3) Retry — MÊME clé, MÊME corps → réponse MÉMORISÉE, 0 re-débit
curl -s -X POST http://localhost:5151/api/payments/charge \
  -H 'Idempotency-Key: 3f6a9c1e-2b7d-4a10-9d31-8e5c2f0a7b64' \
  -H 'Content-Type: application/json' -d '{"amount":4200}'
# {"chargeId":"ch_9F2a","amount":4200}     ← identique, l'action n'a PAS tourné

# 4) MÊME clé, corps DIFFÉRENT → 422 (une clé = une intention)
curl -si -X POST http://localhost:5151/api/payments/charge \
  -H 'Idempotency-Key: 3f6a9c1e-2b7d-4a10-9d31-8e5c2f0a7b64' \
  -H 'Content-Type: application/json' -d '{"amount":9900}' | head -1
# HTTP/1.1 422 Unprocessable Content

⚠️ Attention

Le piège n°1 : en verdict fresh, la réservation est in-flight tant que complete ou abort n’a pas été appelé. Le seam @Idempotent gère ce couple pour toi (try/catch, ^{Resolver.ts:539} et ^{Resolver.ts:563}). Si tu appelles le store à la main (cas avancé), c’est ta responsabilité : sans abort sur erreur, la clé reste bloquée jusqu’à l’expiration du bail (60 s), et tout rejeu identique reçoit 409 pendant ce temps.

Le mode souple — quand la clé est optionnelle#

@Idempotent({ required: false }) honore la clé si elle est présente et exécute sinon. Utile pour une route que d’anciens clients appellent déjà sans clé, le temps de la migration :

@Idempotent({ required: false })
@Post("/subscribe")
async subscribe(@Body() body: SubscribeInput) { /* … */ }

Précédence méthode > classe (computeIdempotent(), ^{routerDecorators.ts:1561}), comme @UseSession. Poser @Idempotent() sur la classe couvre toutes les mutations du controller ; une méthode peut resserrer ou relâcher le mode. Les méthodes sûres (GET…) restent des no-op même sous une classe décorée.

🔌 HTTP et WebSocket — la même porte#

Une socket reconnecte et rejoue par nature : muter sans clé y serait un piège à double-effet garanti. D’où la règle, dans le helper partagé : requiredEffective = required || isWs (^{idempotency.ts:160}). Une mutation par socket exige toujours une clé, même quand le mode HTTP est souple.

Deux mécanismes rendent ça possible côté socket :

• La clé voyage par l’ALS — le pont WS la pose dans RequestContext, et resolveIdempotencyKey() (^{idempotency.ts:68}) donne la priorité à l’ALS sur l’en-tête HTTP.
• La méthode logique voyage par methodOverride — sur une socket, context.method vaut WEBSOCKET, qui n’est pas une mutation. Sans override, la porte serait sautée et un rejeu de frame socket.mutate créerait un doublon. Le Resolver teste donc isMutationMethod(this.methodOverride ?? context.method) (^{Resolver.ts:473}).

Le pont utilise executeActionGuarded() (^{Resolver.ts:425}) : porte d’idempotence sans rendu HTTP — la valeur nue est enveloppée par le peer WS, jamais écrite sur un transport HTTP.

🏗️ Architecture interne#

Le parcours d’une mutation, étape par étape#

1. Court-circuit hot path. callController() (^{Resolver.ts:396}) lit meta.idempotent sur les métadonnées d’action figées par route. null sur la quasi-totalité des routes → une comparaison, flux normal, zéro lookup de store et zéro allocation.
2. No-op sur méthode sûre. Une action GET sous une classe @Idempotent repart directement en exécution (^{Resolver.ts:473}).
3. Empreinte du payload. computeFingerprint() (^{idempotency.ts:123}) hache [nom de route, params de route, corps] (^{Resolver.ts:497}). Le corps vient de l’ALS (pont WS) ou du body HTTP parsé.
4. Identité. resolveIdentity() (^{idempotency.ts:100}) dérive l’identité de request.user (username → identifier → id), avec repli sur l’userId de l’ALS. null = pas de cache : le verdict devient execute (^{idempotency.ts:176}) — jamais de partage cross-identité.
5. Réservation. store.begin() compose la clé scopée et tranche.
6. Mémorisation. En succès, complete(clé, {status, body}) où status est le code de réponse courant et body la valeur retournée par l’action (^{Resolver.ts:539}). En erreur, abort(clé) libère la clé : un échec ne se mémorise pas, il doit rester réessayable.

🛑 Prudence

La réponse mémorisée est la valeur RETOURNÉE, pas la réponse rendue. Une action qui pilote la response elle-même (this.renderJson(...), stream, send()) n’est pas rejouée fidèlement : le double-effet reste évité, mais le corps rejoué est vide. Pire, si le corps retourné n’est pas sérialisable (retour d’un objet Response circulaire), un store SQL/Redis lève au stringify. Le Resolver attrape ce cas : il journalise un WARNING explicite puis mémorise le statut avec un corps null (^{Resolver.ts:549}) — la dédup est préservée plutôt que perdue en silence.

Où la porte est câblée#

⚙️ Configuration#

Source unique = schéma Zod idempotencySchema (src/packages/@nodefony/framework/nodefony/config/config.ts:42).

Comment store: "auto" se résout VRAIMENT#

Framework.onKernelBoot() (src/packages/@nodefony/framework/index.ts:189) délègue à resolveAutoStore("ephemeral", …) (^{src/nodefony/src/config/infra.ts:241}), borné aux backends réellement enregistrés (listIdempotencyBackends(), ^{idempotencyStoreRegistry.ts:81}). L’ordre réel est le suivant :

ℹ️ Note

L’étape 5 surprend souvent : dans une app dev qui charge @nodefony/drizzle sans déclarer NF_DATABASE_URL, auto ne résout pas vers memory mais vers drizzle (SQLite local) — pour que les données survivent au redémarrage. La résolution effective est toujours journalisée au boot (^index.ts:207) : lis cette ligne plutôt que de la déduire.

MongoDB mérite une mention : mongoose n’implémente pas encore de store d’idempotence. Déclarer NF_DATABASE_URL=mongodb://… fait donc tomber la résolution en étape 4 → repli memory avec la raison annoncée — et un repli memory en cluster ne déduplique plus rien entre pods : le rejeu que cette brique promet d’empêcher passe sur un autre pod. En attendant le store Mongo (objectif « full NoSQL », MIGRATION_STATUS.md P7.11), la dédup cross-pod passe par redis.

Le contrat de dégradation : fail-loud, jamais silencieux#

Quand un store explicitement nommé ne peut pas s’initialiser (nom inconnu, redis demandé sans le module @nodefony/redis chargé), la politique dépend de l’environnement (^index.ts:132) :

• production → boot avorté (^index.ts:281). En cluster multi-pod, dégrader vers un cache per-pod produirait du double-effet non dédupliqué : c’est un défaut de sécurité, pas une commodité.
• dev / test (mono-pod) → WARNING fort + repli sur le cache mémoire déjà en place. La dédup per-pod suffit hors cluster, et on ne casse pas le routeur pour une option d’infra absente en local.

Un garde-fou supplémentaire : store: "memory" en production émet un WARNING dédié (^index.ts:212) — la dédup n’y est que per-pod.

🧩 Les stores d’idempotence#

Tous respectent le même contrat IIdempotencyStore (^{src/nodefony/src/types/IIdempotencyStore.ts:106}) : begin / complete / abort obligatoires, gc optionnel, plus listPage et size pour l’introspection.

Choisir en 5 secondes#

Le GC — armé pour un seul store#

scheduleIdempotencyGc() (^{idempotencyGc.ts:32}) arme un GcScheduler uniquement si le store expose gc() (^{idempotencyGc.ts:37}). Un store à TTL natif (redis) ou à purge passive (memory) ne l’expose pas ; le brancher sur un timer serait un no-op coûteux. Le scheduler est armé au boot (^{nodefony/framework/index.ts:311}) et arrêté à onTerminate.

gcIntervalS: 0 désarme le timer — à réserver au cas où la purge est déléguée (cron, CronJob k8s).

🗄️ Entité de persistance (store SQL)#

Table idempotency_key, décrite par une spec colKit unique (^{idempotencyEntity.ts:66}) déclinée par dialecte via createIdempotencyTable(dialect) (^{idempotencyEntity.ts:85}).

Deux détails qui expliquent des surprises réelles :

• varchar(512) en MySQL n’est pas un caprice : un TEXT InnoDB n’est pas indexable sans préfixe, et 512 caractères couvrent JSON.stringify([identité, clé ≤ 255]).
• Aucun DEFAULT SQL : le DDL dérivé n’en émet pas (^{idempotencyEntity.ts:38}). Toutes les colonnes sont posées explicitement par le store — jamais d’INSERT cassé par un défaut manquant.

registerIdempotencyEntities(connector, dialect) (^{idempotencyEntity.ts:146}) doit être appelé avant orm.connect() (la table est créée au connect) — le module drizzle s’en charge tout seul.

ℹ️ Note

SQLite = banc de test de la sémantique. Un fichier SQLite est mono-machine (verrou d’écriture) → aucun intérêt multi-pod (^{idempotencyEntity.ts:26}). La cible réelle est PostgreSQL ou MySQL/MariaDB, où l’atomicité de l’instruction tient sous concurrence inter-pods.

🗃️ Dialectes et bases pris en charge#

🛑 Prudence

MongoDB (@nodefony/mongoose) n’implémente PAS de store d’idempotence. Sélectionner store: "mongoose" échoue à la résolution (fail-loud) ; laisser auto avec une infra Mongo replie sur memory avec une raison annoncée. En cluster Mongo, la dédup passe par redis.

🧰 API publique#

Signatures complètes : .ai/symbols.json. Ce qui compte à l’usage :

Le décorateur#

@Idempotent(options?) (^{routerDecorators.ts:1103}) — dual classe + méthode. N’écrit que des métadonnées (IdempotentMeta, ^{routerDecorators.ts:443}), zéro import de @nodefony/security, zéro cycle. La porte est appliquée par le Resolver.

Le contrat de store#

Les helpers du seam sont exportés et réutilisables : isMutationMethod() (^{idempotency.ts:28}), resolveIdempotencyKey() (^{idempotency.ts:68}), resolveIdentity() (^{idempotency.ts:100}), computeFingerprint() (^{idempotency.ts:123}), evaluateIdempotency() (^{idempotency.ts:142}).

🧩 Extension — brancher son propre store#

Le registre (idempotencyStoreRegistry.ts) ne porte que les overrides distribués opt-in : le défaut mémoire est posé par @services, jamais par le registre.

import { registerIdempotencyStore } from "@nodefony/framework";
import type { IIdempotencyStore } from "nodefony";

registerIdempotencyStore("mon-backend", (ctx) => {
  // ctx.module → container kernel (résoudre un service par NOM, jamais d'import direct)
  // ctx.config → config framework validée + gelée
  return new MonStore(/* … */) satisfies IIdempotencyStore;
});

Trois règles héritées du code existant, à respecter sous peine de double-effet :

1. begin doit être atomique côté backend. Un GET puis SET séparés laissent deux retries concurrents obtenir fresh — précisément ce que l’idempotence doit empêcher.
2. Ne jamais rendre fresh hors réservation gagnée. En cas de doute (course, état illisible), rendre in-flight : le client réessaiera, c’est sans danger.
3. complete doit préserver l’empreinte de l’entrée in-flight, sinon un rejeu avec un autre payload après complétion ne produit plus de 422.

Fonctions du registre : registerIdempotencyStore() (^{idempotencyStoreRegistry.ts:48}), getIdempotencyStoreFactory() (^{idempotencyStoreRegistry.ts:56}), listIdempotencyStores() (distribués seuls, ^{idempotencyStoreRegistry.ts:67}), listIdempotencyBackends() (avec memory, pour l’affichage Studio, ^{idempotencyStoreRegistry.ts:81}).

📜 Normes appliquées#

<!-- prettier-ignore -->

⚡ Performance et mémoire#

Le coût est nul hors mutations décorées. Sans @Idempotent, RouteActionMeta.idempotent vaut null (^{routerDecorators.ts:1103}) : callController() fait une comparaison et repart en flux normal — zéro lookup de container, zéro await supplémentaire, zéro allocation (^{Resolver.ts:396}). La métadonnée est figée par route et mémoïsée : aucune lecture Reflect par requête.

Sur le chemin décoré :

• Le store mémoire n’alloue sa Map qu’au 1ᵉʳ begin, ne pose aucun timer ni listener, et purge en passif (^{IdempotencyStore.ts:164}).
• L’empreinte est un hash SHA-256 court → comparaison O(1), et le payload n’est jamais conservé en clair.
• Le GC est hors hot-path et armé pour un seul store (SQL) ; le jitter évite que N pods purgent au même instant.
• Un store distribué ajoute un aller-retour réseau par mutation (begin), plus un au complete. C’est le prix de la dédup cross-pod, payé uniquement sur les routes décorées.

Constat honnête : il n’existe pas de banc de charge dédié à l’idempotence. La porte est un chemin froid par construction ; si ton profil de trafic la place sur un chemin chaud, mesure-la avec le skill nodefony-load-test.

📡 Observabilité — Studio#

Trois surfaces existent aujourd’hui :

• Playground (/nodefony/playground) — chaque mutation protégée porte un badge @Idempotent (strict ou souple) (^{playground/PlaygroundFormat.tsx:69}). L’écran génère une clé par exécution et propose « Rejouer même clé » dès que action.guards.idempotent est posé (^{playground/ActionPanel.tsx:516}) : c’est la façon la plus rapide de voir un rejeu, un 409 ou un 422 en vrai.
• Stores — la brique idempotency y apparaît avec sa nature éphémère, le backend configuré, le backend résolu, la liste des backends disponibles et la raison de la résolution — brique idempotency (^{stores/storesModel.ts:150}). C’est là qu’on vérifie qu’auto a choisi ce qu’on croyait.
• ERD — la table idempotency_key est regroupée sous @nodefony/framework (^{idempotencyEntity.ts:133}), pas sous l’ORM qui l’héberge.

ℹ️ Note

Il n’existe pas encore d’écran ni d’endpoint admin listant les clés d’idempotence vivantes : listPage est implémenté par les trois stores et couvert par un banc de contrat, mais aucun producteur /nodefony/<ns>/api/* ne l’expose. Pour inspecter le parc en attendant : redis-cli --scan --pattern 'nf:idem:*', ou un SELECT sur idempotency_key.

⚠️ Pièges#

🧪 Tests et couverture#

Les chiffres exacts vivent dans la carte régénérée depuis vitest — jamais figés ici. Le répertoire des familles couvertes :

• Unitaires (@nodefony/framework) : idempotency.test.ts (les verdicts, la résolution de clé, l’identité, l’empreinte) · IdempotencyStore.test.ts (store mémoire : réservation, empreinte, isolation des identités, expiration, borne mémoire) · RedisIdempotencyStore.test.ts (réservation atomique, rejeu, libération, TTL natif, course SET NX puis GET vide) · idempotencyStoreRegistry.test.ts (registre) · idempotencyGc.test.ts (armement conditionnel du GC) · resolverIdempotency.test.ts (le seam Resolver : rejeu sans ré-exécution, scope d’identité).
• Intégration (@nodefony/drizzle) : idempotency-store.test.ts (sémantique séquentielle SQLite) et idempotency-pagination.test.ts (listing déroulé sur les trois dialectes depuis un seul fichier).
• E2E base réelle : idempotency-mysql.e2e.test.ts (verdicts, vol d’entrée expirée, concurrence deux pods), gaté par NF_MYSQL_URL.
• Banc de contrat : idempotencyPaginationContract.ts (core) — une suite backend-agnostique branchée sur mémoire, Redis et Drizzle × 3 dialectes. Elle porte une exigence de sécurité autant que de pagination : un backend qui laisserait remonter la réponse mémorisée fait échouer le test marqué 🔒.

Ce qui manque, dit franchement :

• Aucun test de charge dédié à la porte d’idempotence.
• Le mode curseur de Redis n’est prouvé que contre un double déterministe (FakeRedis), pas contre un serveur Redis réel — alors que le curseur composite existe justement à cause d’un comportement (SCAN COUNT n’est pas un plafond) observé sur un serveur réel.
• L’atomicité cross-pod est prouvée sur PostgreSQL et MySQL/MariaDB ; SQLite ne valide que la sémantique séquentielle (mono-fichier).

Couverture : npm run coverage dans @nodefony/framework et @nodefony/drizzle. Skills utiles : nodefony-load-test (charge), nodefony-check-memory-health (mémoire), nodefony-security-review (revue sécurité).

🔗 Pour aller plus loin#

• ⬆️ Retour au hub : @nodefony/framework — vue du module · Toute la documentation
• 🧭 Pages sœurs : Pipeline de requête · Firewall (l’identité qui scope la clé)
• 🗄️ Stores distribués : @nodefony/redis · @nodefony/drizzle
• 📖 Contrat de pagination partagé par tous les stores : IPage / IPageQuery (^{src/nodefony/src/types/IPage.ts:18})
• 🧠 Contexte de requête (ALS : identité, clé WS, corps) → request-context