idempotency-patterns

# Idempotency Patterns ## Spring Boot 4 baseline The examples use Java 17 and Jakarta APIs supported by this Boot version. Keep dependencies managed by the project's Boot BOM. ## Define the contract Identify the authenticated tenant/principal, operation, idempotency key, canonical request hash, retention window and replayable result. Scope uniqueness by principal/tenant and operation; a raw client key must never allow reading another user's result. Authenticate and authorize before both initial execution and replay. Bound key length and stored response size. Document what same-key/different-payload and still-in-progress requests return. ## Database-local effects For PostgreSQL, [the schema and claim example](examples/good-idempotency.sql) uses a composite primary key and INSERT ON CONFLICT DO NOTHING RETURNING. In a single database transaction: claim the key, apply the business write, store the resulting status/body/selected headers, then commit. Roll back the claim with the business mutation on failure. If the insert returns no row, load the existing result in a subsequent statement under READ COMMITTED, compare the canonical hash and replay only when it matches. A concurrent insert waits on the uniqueness constraint; bound lock waits and return a documented retryable outcome on timeout. With snapshot isolation, serialization failures require retrying the whole transaction. Do not catch a unique-constraint violation and continue in an already-aborted transaction. A r...