Does KrakenJS middleware guarantee idempotent writes when concurrent retries race during partial database timeouts?

Short answer

No. KrakenJS does not guarantee idempotent writes, and no single middleware hook can supply that guarantee by itself. KrakenJS is a configuration and plugin layer over Express: it decides how middleware is assembled and ordered, but persistence, retry policy and idempotency keys remain application responsibilities. Two concurrent retries are two independent HTTP requests with two independent middleware chains, so the framework has no built-in concept of one logical operation spanning them.

What is confirmed, and what depends on your stack

Confirmed behavior:

• The middleware chain is per-request and in-process. Retries arrive as new requests, so no lifecycle event fires strictly once across all attempts.
• Node's event loop is single-threaded per process, so a purely synchronous check-and-set cannot interleave. Any await on a cache or database call yields, which reopens the race window.
• Cluster workers, PM2 instances and containers remove even that accidental serialization. Module-level Maps and in-process mutexes will not coordinate across them.

Stack-dependent and worth confirming in your own code: the exact registration order of your plugins, and whether your database driver's timeout surfaces as a client-side error after the server may already have committed. Version-sensitive: KrakenJS plugin and middleware APIs track the Express major they target, and error-handling behavior differs between Express 4 and Express 5. Check your lockfile rather than assuming.

Safest insertion point for an atomic check-and-set

Register a dedicated idempotency middleware early, before body parsing and before any route handler that touches the database. The hook only decides when the check runs; the atomicity must come from the store itself, not from the middleware position.

# Atomic claim with expiry — the NX flag is what makes this safe
redis-cli SET idem:<key> pending NX EX 30
# Returns OK if claimed, nil if another attempt already holds it

Pair it with a database-side backstop so a cache miss cannot produce a duplicate row:

CREATE UNIQUE INDEX CONCURRENTLY idx_orders_idem_key ON orders (idempotency_key);

INSERT INTO orders (idempotency_key, payload)
VALUES ($1, $2)
ON CONFLICT (idempotency_key) DO NOTHING;

Claim, write, complete — never delete on timeout

1. Atomically claim the key in state pending with a TTL.
2. Perform the write, which should itself be an upsert or a unique-constrained insert.
3. On success, record the response and mark the key completed.
4. On timeout, leave the claim in place and treat the outcome as unknown.
5. Never delete the key because an attempt timed out — a partial timeout may mean the commit succeeded, and deleting reopens the duplicate-write window.

Verification you can run locally

• Send many concurrent identical requests with the same key while injecting latency or a forced driver timeout, then assert exactly one row exists.
• Confirm the idempotency middleware is registered before every database-touching handler in your KrakenJS config.
• Check that your store client exposes a genuinely atomic conditional operation (Redis SET with NX and expiry) rather than a read-then-write helper.
• Query for duplicate idempotency keys after the test; this catches races the cache layer misses.

The one detail that changes the recommendation

Do your retries carry the same client-supplied idempotency key? If they do not, no server-side pattern can help — the server cannot distinguish a retry from a new intent, and you must fix the client or the retry layer first. If they do, the claim/write/complete pattern above is the workable approach.

Review note

Marked for human review: the exact plugin registration semantics and error propagation differ across KrakenJS releases and their Express targets. The store-level atomicity and unique-index advice is stable; the middleware ordering claim should be re-checked against the version pinned in your project.