Products / SaaS / Backend Infrastructure
IdemKey
HTTP Idempotency-Key middleware — safe POST/PATCH retries
Express middleware that fingerprints method+path+key+body hash, claims a Postgres row, runs the handler once, and replays the stored response on retries.
Value
Problem. Clients retry POST/PATCH. Without Idempotency-Key handling, flaky networks double-charge, double-book, or double-email.
How it helps. Express middleware that fingerprints method+path+key+body hash, claims a Postgres row, runs the handler once, and replays the stored response on retries.
Why buy. Stripe-style safe retries for your mutating endpoints — complements HookQueue (inbound webhooks) for your own API.
- Fingerprint + claim/replay with Idempotency-Replayed header
- 409 in-flight (or wait+poll); 422 on same key with different body
- Demo POST /v1/charges fake side effect + memory store for tests
How it works
flowchart LR
Client -->|"Idempotency-Key + body"| MW[IdemKey Middleware]
MW -->|fingerprint sha256| FP["method|path|key|bodyHash"]
MW -->|begin claim| Store[(Postgres)]
Store -->|first / expired| Exec[Run handler]
Store -->|completed| Replay["Replay status + body"]
Store -->|started / in-flight| C409["409 Conflict"]
Store -->|same key ≠ body| C422["422 Key reuse"]Mermaid flowchart (render in GitHub / VS Code / mermaid.live).
Use case
Mobile taps Pay twice with the same Idempotency-Key; first call creates one fake charge, second returns the same charge id with Idempotency-Replayed: true.
What you get
- Idempotency middleware + Postgres/memory stores
- Demo charges route
- docker-compose.yml (host 5436)
- scripts/demo-curl.sh
- 14 Vitest tests
- MIT license + HTTP guide on the site
Project structure
idemkey/
src/
middleware/ idempotency.ts
stores/ postgres, memory, types
routes/ charges, health
lib/ fingerprint, config, prisma
prisma/ tests/ scripts/demo-curl.sh docker-compose.ymlQuick start
docker compose up -d
cp .env.example .env
npm install && npm run prisma:generate && npm run prisma:migrate
npm run dev
./scripts/demo-curl.shExample
From src/middleware/idempotency.ts
// Idempotency-Key → fingerprint(method|path|key|bodyHash)
// first → status=started → run handler → store response → completed
// retry → replay body + Idempotency-Replayed: true
// concurrent → 409; same key ≠ body → 422Tested
14 Vitest tests — fingerprinting, memory store claim/replay, middleware first-call vs replay without second handler invoke.
npm test2026-09-20 — 14 passed; npm run build OK
Design decisions
- Body hash in fingerprint prevents key reuse with different payloads (422)
- IdempotencyStore interface allows Redis later
- Default in-flight = conflict (409) for predictable client behavior
Limitations
- Not a payment processor or Stripe Billing
- Response capture hooks res.json/send — exotic streaming responses need care
- TTL cleanup is SQL you schedule (pairs with CronLock)
- Safe retries assume handlers are side-effectful only after claim — design accordingly
Who it’s for
API authors shipping POST/PATCH that must survive mobile and gateway retries.
Not for: Teams that only need webhook-provider dedupe (use HookQueue) or Redis-only SETNX shops.
What you own
Full MIT-licensed TypeScript source via Gumroad ZIP. Fork it, ship it commercially, keep the license notice. You are responsible for secrets, hardening, and production ops.
Related
Demo
