Clés d'idempotence
krizaka-idempotency — une action HTTP s'exécute au plus une fois par Idempotency-Key ; une reprise rejoue sa réponse.
<dependency>
<groupId>com.krizaka</groupId>
<artifactId>krizaka-spring-boot-starter-idempotency</artifactId>
</dependency>Un client dont la connexion a coupé après que ton service a accepté une requête ne peut pas savoir si elle a abouti.
Réessayer à l'aveugle fait payer deux fois, ne pas réessayer perd la commande. Avec un en-tête Idempotency-Key, la
reprise est sûre — promu depuis Sovkora, où chaque lancement payant fonctionne ainsi.
krizaka:
idempotency.store: jdbc
spring.sql.init.schema-locations: classpath:com/krizaka/idempotency/schema-postgresql.sql@PostMapping("/api/v1/orders")
ResponseEntity<Order> create(@RequestBody NewOrder order, @AuthenticationPrincipal Jwt caller,
@RequestHeader(value = IdempotencyKeys.KEY_HEADER, required = false) String key) {
return idempotency
.execute(new IdempotentRequest("orders.create", caller.getSubject(), key, order),
Order.class, () -> orders.create(order))
.toResponse(HttpStatus.CREATED);
}Le contrat
| Requête | Réponse |
|---|---|
| première, avec une clé | l'action s'exécute ; sa réponse est stockée dans la transaction de l'action |
| reprise, même clé, même requête | la réponse stockée, avec Idempotent-Replayed: true — l'action ne s'exécute pas |
| même clé, autre requête | 422 Problem Details, code idempotency-key-reused |
| deux à la fois, même clé | la seconde attend la clé, puis rejoue la première |
| l'action échoue | rien n'est enregistré : la reprise s'exécute pour de vrai |
| sans clé | l'action s'exécute, à chaque fois |
| une clé malformée | 400 Problem Details, code invalid-idempotency-key (1 à 255 caractères ASCII visibles) |
Une clé appartient à un scope et à un sujet : la clé d'un client ne rejoue jamais celle d'un autre. La requête est
empreinte par le SHA-256 de son JSON canonique : l'ordre de ses champs n'est pas une différence. Les clés sont gardées
krizaka.idempotency.ttl (24 heures) et purgées à intervalle.
Prouvé
JdbcIdempotencyIT l'exécute sur PostgreSQL — rejeu, réutilisation, annulation, deux requêtes simultanées sur une clé,
purge — et l'application d'exemple
le prouve en HTTP. Chaque exécution est observée en krizaka.idempotency (voir Observabilité).
Configuration
| Propriété | Description |
|---|---|
krizaka.idempotency.purge-intervalDurationdéfaut 1h | Delay between two purges of the keys older than the time-to-live. |
krizaka.idempotency.storeStorepas de défaut | Where keys and their responses are kept: 'jdbc' (PostgreSQL, in the action's transaction, shared by every instance) or 'memory' (one instance). Required to get the Idempotency bean; never inferred from the classpath.jdbcmemory |
krizaka.idempotency.tableStringdéfaut idempotency_keys | Table the keys are kept in when the store is 'jdbc'. |
krizaka.idempotency.ttlDurationdéfaut 24h | How long a key replays its response; after it, the same key runs the action again. |
App config
krizaka-app-config — compatibilité de version des apps — un endpoint app-config public, 426 Upgrade Required et contrats N-1, depuis des paramètres en base.
Persistance
krizaka-persistence — les tables des stockages JDBC du kit créées et migrées au démarrage, dans leur propre historique Flyway.