Idempotent

Run once. Same result on every retry. A lightweight Spring Java library that makes any method or service safe to retry — not just HTTP APIs. Duplicate calls return the cached result; concurrent callers wait for the first run instead of racing.

Annotate a controller, a @Service, or a batch job. Or call IdempotentService directly. Pick Redis, DynamoDB, NATS KV, or JDBC — or start with the built-in in-memory store.

@Idempotent(key = "#order.id", duration = "30m")
@PostMapping("/orders")
public Receipt place(@RequestBody Order order) {
  return paymentGateway.charge(order);    // runs once, even on a retry storm
}

No bespoke locks. No “did this already happen?” checks. No duplicate work.

Why your service needs Idempotent

In a distributed system, the same request can arrive twice — or twenty times. Networks time out, clients retry, load balancers replay, queues redeliver. Without idempotency, you ship the order twice, charge the card again, or corrupt state.

Idempotent ties every retry to one logical operation: same key → same outcome. It claims the key atomically, runs your code once, caches the result, and coordinates any concurrent callers — across Redis, DynamoDB, NATS KV, or your SQL database.

You add a dependency and an annotation. The library handles the hard parts.

What you get

How it works

Client sends the same request twice (timeout, retry, replay):

POST /orders        X-Idempotency-Key: 1f3c1a93-…-3bd4
POST /orders        X-Idempotency-Key: 1f3c1a93-…-3bd4   ← duplicate

Set duration longer than your slowest operation, so an entry is never evicted mid-flight.

Without AOP

Same engine from any code — useful in @Service classes, consumers, or jobs:

return idempotentService.execute(
    "ord_42", "create-order", Order.class,
    () -> orderService.create(request),
    Duration.ofMinutes(30));

Choose your storage

In-memory is the default. Pick a persistent backend for production:

All four share the same serialization, expiry, and state machine — swap backends without changing behavior.

Install

Add a storage module (it pulls in idempotent-core):

<dependency>
  <groupId>io.github.arun0009</groupId>
  <artifactId>idempotent-redis</artifactId> 
  <version>${idempotent.version}</version>
</dependency>

For @Idempotent, also add spring-boot-starter-aop. IdempotentService works without it.

API reference, configuration, and custom stores: idempotent-core.

Contributing

Issues and pull requests welcome at github.com/arun0009/idempotent. Released under the MIT License.