Idempotent Next.js route handlers that survive two instances and a crash

[violetta98]

A dropped connection on the way back from /api/charge means the browser retries, and your handler runs a second time. Route handlers are just Fetch handlers, so this wraps one.

import { InMemoryBackend, withIdempotency } from "idemkit";

export const POST = withIdempotency(
  async (request: Request) => {
    const { amount } = await request.json();
    return Response.json({ chargeId: await charge(amount) }, { status: 201 });
  },
  { backend: new InMemoryBackend() },
);

A retry carrying the same Idempotency-Key replays the first response and never reaches the handler. The claim is one atomic operation per backend, a Lua script on Redis, INSERT … ON CONFLICT on Postgres, so two instances racing resolve to a single run rather than both getting past a check. If the winner dies mid-charge its lease expires on the storage clock, and a fencing token stops its late write from overwriting the real result.

There's an InMemoryBackend for local dev. Production is Redis, Postgres, Mongo or DynamoDB.

Zero dependencies, Apache-2.0: https://github.com/idemkit/idemkit

If you find it useful, a star would be much appreciated.

[Mr-Nilarnab]

This is a useful abstraction, especially because idempotency is easy to get subtly wrong when implemented separately in every Route Handler.

The important production consideration is that InMemoryBackend should only be treated as a local/dev implementation. In a horizontally scaled Next.js deployment, two requests carrying the same Idempotency-Key can reach different instances, so process-local state cannot guarantee idempotency.

For production, the backend needs to provide an atomic “claim-or-replay” operation at the storage layer. Redis, Postgres, DynamoDB, etc. can work, but the critical part is that the check-and-create operation must be atomic rather than:

if (!exists(key)) {
  create(key);
  executeHandler();
}

Otherwise concurrent duplicate requests can both pass the check before either one records the key.

I’d also consider documenting a few semantics explicitly:

• Scope the idempotency key appropriately, ideally including the authenticated principal/account and endpoint, rather than treating the raw key as globally unique.
• Decide what happens when the same key is reused with a different request body. That should generally be rejected rather than replaying an unrelated response.
• Persist the final status, headers and response body so retries reproduce the original result consistently.
• Define what happens when the first execution crashes or times out after the backend has claimed the key.
• Be careful with streaming responses and non-replayable response bodies.
• Add TTL/retention semantics so an idempotency store doesn't grow indefinitely.
• Make the storage operation atomic under concurrent requests.

One other important distinction: idempotency protects against duplicate execution, but it doesn't automatically make the underlying charge() operation safe. Ideally the idempotency key should also be propagated to the downstream payment/provider operation when that provider supports idempotency.

The wrapper API is nice, though. Keeping it compatible with the standard (request: Request) => Response Route Handler contract means adoption can remain very low-friction.

A production-oriented example would therefore look conceptually like:

export const POST = withIdempotency(handler, {
  backend: redisBackend,
  ttl: 24 * 60 * 60,
});

The strongest part of this approach is that application code doesn't have to repeatedly implement the same retry/concurrency logic. If idemkit guarantees atomic claiming, request-fingerprint validation, response replay, and well-defined failure semantics across distributed instances, this could be a genuinely useful building block for Next.js Route Handlers.

[violetta98]

Thanks for taking the time on this!

Re: InMemoryBackend, you're right, it's only in there for the example. Production is Redis, Postgres, Mongo or DynamoDB.

Check-then-create is the pattern idemkit exists to avoid. There's no exists followed by create anywhere: Redis claims in a Lua script, Postgres with INSERT … ON CONFLICT DO NOTHING, Mongo with a pipeline update, DynamoDB with a conditional UpdateItem. Lease deadlines use the storage server's clock rather than the app's, so a drifting box can't expire a live claim. DynamoDB is the exception and it's documented.

These semantics be documented in TS readme but let me also go through them here:

• Scoping: scope is a function of the request, so you return the principal. The endpoint is automatic: the effective key hashes key + scope + method + path. scopeMode: "strict" makes a missing scope a startup error.
• Same key, different body: Rejected, 422 with urn:idemkit:payload-mismatch. The whole body is fingerprinted by default. If your clients send a timestamp or a nonce in the payload, bodyFingerprint lets you hash only the stable fields so an honest retry isn't read as a different request.
• Status, headers, body: All stored. cacheableStatus (default 200/201/202), headerAllow/headerDeny, and responseRedactor for PII.
• Crash after the claim: The lease expires, the next attempt reclaims it, and a fencing token bounces the dead worker's late write. You get a complete_failed decision, not silence.
• Streaming: maxBodyBytes and maxRequestBodyBytes cap what gets buffered, and anything larger streams straight through without being cached.
• TTL: expiresAfterSeconds, default 24h. Redis, Mongo and DynamoDB self-expire. Postgres needs npx idemkit pg-vacuum scheduled.
• Atomicity: Yes, as covered above.

Propagating the key downstream isn't supported yet. Fair ask, and it may come later.

On the wrapper contract - keeping it plain was deliberate, the same code runs on Bun, Deno and SvelteKit. Your example is right, the TTL just lives under config:

export const POST = withIdempotency(handler, {
  backend: redisBackend,
  config: {
    scope: (req) => req.headers.get("x-account-id"),
    expiresAfterSeconds: 24 * 60 * 60,
  },
});

Your four criteria: yes to all four. The same conformance vectors run against real Redis, Postgres, Mongo and DynamoDB, alongside property-based model checking and fault injection. The Limitations section is where the edges I can't close are written down.

[Mr-Nilarnab]

This is a pretty solid design. The part I’d be most interested in seeing next is the boundary between idemkit and the actual side effect.

The wrapper can guarantee that only one request execution owns a key, but once the handler calls something like:

await charge(amount)

there's still a distributed-systems edge case if the payment provider succeeds and the process dies before idemkit records the response.

For example:

1. Request acquires the idempotency claim.
2. charge() succeeds at the provider.
3. The instance crashes before complete() is persisted.
4. The lease expires.
5. A retry legitimately reclaims the key.
6. The handler calls charge() again.

The fencing token protects the idempotency record from a stale worker, but it can't undo an already-completed external side effect.

So I think the strongest production guidance would be to make this distinction very explicit in the docs:

idemkit provides idempotency for the Route Handler's execution/storage layer; external side effects still need their own idempotency or reconciliation mechanism.

If the payment provider supports an idempotency key, propagating the effective idemkit key downstream would make the whole chain considerably stronger. Otherwise, a recovery/reconciliation pattern becomes important for operations where “provider succeeded, local completion was lost” is possible.

Apart from that, the atomic claim + lease + fencing-token combination is much more convincing than the usual if (!exists) create() implementations. The backend-specific atomic primitives and fault-injection testing are especially good signs.

I'd be interested in seeing a failure matrix in the README covering:

claim → handler → side effect → complete

with crash points at each stage and the resulting retry behavior. That would make the guarantees very easy to reason about for anyone evaluating it for payments or other irreversible operations.

[MahmoudEsawi]

This looks incredibly useful, @violetta98! Handling idempotency in Serverless/Edge environments like Next.js route handlers is usually a headache, especially with client retries and race conditions between instances.

Relying on atomic operations per backend (like the Lua script for Redis or ON CONFLICT for Postgres) and using a fencing token is a super solid and resilient design choice.

Quick question regarding the storage: how does idemkit handle the cleanup of old idempotency keys? Is it purely reliant on the TTL of the underlying backend (like Redis expiry), or is there a built-in cleanup/garbage collection mechanism when using databases like Postgres or MongoDB?

Great work on keeping it zero-dependency too. Definitely starred! ⭐