Aller au contenu
Krizaka Java
Skip to Content
Krizaka Java

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êteRé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êtela réponse stockée, avec Idempotent-Replayed: true — l'action ne s'exécute pas
même clé, autre requête422 Problem Details, code idempotency-key-reused
deux à la fois, même cléla seconde attend la clé, puis rejoue la première
l'action échouerien n'est enregistré : la reprise s'exécute pour de vrai
sans clél'action s'exécute, à chaque fois
une clé malformée400 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 1hDelay between two purges of the keys older than the time-to-live.
krizaka.idempotency.storeStorepas de défautWhere 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_keysTable the keys are kept in when the store is 'jdbc'.
krizaka.idempotency.ttlDurationdéfaut 24hHow long a key replays its response; after it, the same key runs the action again.

Sur cette page