Implement a persisted idempotent POST with Spring and JPA

Implement an idempotent order creation service. The key is scoped by authenticated actor and operation. The first request atomically stores both the order and a completed idempotency record. A repeat with the same payload replays the original response; the same key with a different payload returns 409. Concurrent duplicates must not create two orders.

key K + payload A -> 201, order 42
key K + payload A -> replay order 42
key K + payload B -> 409 Idempotency key reused with different request

• Require a client-generated UUID idempotency key.
• Scope uniqueness by actor, operation, and key.
• Hash a canonical representation of the owned request fields.
• Write business data and the completed idempotency record in one transaction.
• Rely on a database unique constraint for the concurrency race.

1. Look up an existing record and compare its request hash before doing business work.
2. If absent, execute order creation and idempotency persistence in one transaction.
3. Flush before returning so the unique-key race is observed inside the method.
4. If the unique constraint loses a race, start a new read and replay the winner.
5. Keep the original status and response body required for deterministic replay.

@org.springframework.stereotype.Service
class IdempotentOrderService {
    private static final String OPERATION = "create-order";
    private final IdempotencyRepository keys;
    private final OrderRepository orders;
    private final org.springframework.transaction.support.TransactionTemplate tx;

    CreateOrderResult create(java.util.UUID actorId, java.util.UUID key, CreateOrder command) {
        String hash = RequestHash.sha256(command.productId() + ":" + command.quantity());
        var existing = keys.findByActorIdAndOperationAndKey(actorId, OPERATION, key);
        if (existing.isPresent()) return replay(existing.get(), hash);

        try {
            return tx.execute(status -> {
                var order = orders.save(new Order(actorId, command.productId(), command.quantity()));
                var result = new CreateOrderResult(order.getId(), 201);
                keys.saveAndFlush(IdempotencyRecord.completed(
                        actorId, OPERATION, key, hash, result.orderId(), result.status()));
                return result;
            });
        } catch (org.springframework.dao.DataIntegrityViolationException race) {
            if (!DatabaseErrors.isConstraint(race, "ux_idempotency_scope_key")) {
                throw race;
            }
            var winner = keys.findByActorIdAndOperationAndKey(actorId, OPERATION, key)
                    .orElseThrow(() -> race);
            return replay(winner, hash);
        }
    }

    private CreateOrderResult replay(IdempotencyRecord record, String hash) {
        if (!record.requestHash().equals(hash)) throw new IdempotencyConflict();
        return new CreateOrderResult(record.orderId(), record.status());
    }
}

// Database migration:
// unique (actor_id, operation, idempotency_key)

The application performs indexed O(log n) idempotency lookups plus one bounded transaction. Storage grows with retained keys, so production design also needs an expiry policy longer than the advertised retry window.

• A timeout after commit is safely resolved by replaying the stored result.
• A timeout before commit leaves neither order nor completed key.
• Canonical hashing must not change when irrelevant JSON whitespace or property order changes.
• Database availability failures are ambiguous to the client and should invite retry with the same key.

• Run two transactions concurrently with the same key and assert one order and one idempotency record.
• Retry after simulated response loss and verify the original order ID is returned.
• Reuse the key with a changed quantity and assert 409 without modifying the order.
• Force rollback after order save and assert neither row commits.

• A check-then-insert without a unique constraint races under concurrency.
• Storing the key in a separate transaction can preserve the wrong half of the operation.
• Catching every integrity violation as a duplicate hides unrelated database defects.
• An in-memory map fails across replicas, restarts, and deployments.