idempotent-endpoint

Idempotent Endpoint — Scaffold

Unsafe POSTs get retried — by clients, proxies, and message queues. Without idempotency a retry charges the card twice or creates two orders. This scaffolds a filter that makes a retry carrying the same Idempotency-Key replay the original response, so the side effect happens exactly once.

Step 1 — Detect conventions (do not assume)

Read before generating:

• Existing filter chain: look for OncePerRequestFilter / FilterRegistrationBean config and a …​.web / …​.config package; place the filter there and register it the same way the project registers other filters.
• Storage available: check for Redis (spring-data-redis) or a relational DB. The filter depends only on the IdempotencyStore SPI — pick the backing store that already exists; do not add a new datastore.
• Existing idempotency: if the project already keys retries somewhere, extend that instead of adding a parallel mechanism.

Step 2 — Render templates

From assets/, substitute {{PACKAGE}}:

• IdempotencyStore.java.tmpl → <pkg>/web/idempotency/IdempotencyStore.java (the SPI)
• IdempotencyKeyFilter.java.tmpl → <pkg>/web/idempotency/IdempotencyKeyFilter.java

The filter logic:

1. Only guards POST requests that carry an Idempotency-Key header; everything else passes straight through.
2. Computes a fingerprint = hash of method + URI + body.
3. store.find(key):
   • hit, same fingerprint → replay the stored status/body, skip the handler.
   • hit, different fingerprint → 422 (the key was reused for a different request).
   • miss → run the handler, then store.save(key, response).

Step 3 — Implement the store

Generate (or point the user to write) one IdempotencyStore implementation:

@Component
class RedisIdempotencyStore implements IdempotencyStore {
    // SET key <json> NX EX <ttl>; GET key. Use a short TTL (minutes–hours), not forever.
    // A DB variant: unique column on key + an inserted-at for expiry.
}

Register the filter (e.g. a FilterRegistrationBean<IdempotencyKeyFilter>) scoped to the POST routes that need it — not every endpoint.