Kraken.js POST handlers: choosing the layer that owns retry deduplication

Answer

In a Kraken/Express stack the conventional place for cross‑cutting idempotency/retry deduplication is a piece of Express middleware that runs after the body‑parser and before Kraken‑generated route handlers.

Why middleware is the preferred layer

• It can inspect the request (headers or body) for an idempotency key and return a cached response without invoking controllers or touching the database.
• It keeps domain services free of infrastructural concerns and lets a database unique constraint act only as a safety net for races that bypass the middleware.
• Because Kraken’s configuration‑driven middleware list is deterministic, you can declare the middleware once and have it apply to all mutating routes.

Steps to add the middleware in Kraken

1. Create a small module, e.g. idempotency-middleware.js, that:
   • Extracts the idempotency key from a header (e.g. Idempotency-Key) or from the JSON body.
   • Looks up the key in a fast store (in‑memory for a single process, Redis or similar for multiple instances).
   • If found, returns the stored status code, headers and body.
   • If not found, calls next() and, after the downstream handler finishes, caches the outcome keyed by the idempotency key.
2. Register the middleware in Kraken’s middleware.json (or programmatic middleware array) after the body‑parser entry (e.g. bodyParser.json()) and before the router or controllers section that Kraken injects for routes.
3. Example snippet:

{
  "middleware": {
    "init": {
      "bodyParserJson": { "module": "body-parser", "method": "json" }
    },
    "idempotency": {
      "module": "./idempotency-middleware",
      "method": "",
      "args": [ { "store": "redis" } ]
    },
    "router": { "module": "./router", "method": "" }
  }
}

This order guarantees the key is available from the parsed payload before any controller runs.

Fallback safety net

Add a unique constraint on a column that stores the idempotency key (or a composite key that includes the resource type) in your data store. In the service layer catch the constraint‑violation error and map it to the same successful response you would have returned for the first request. This protects against the rare case where two requests slip past the middleware simultaneously.

When to require the key

Apply the requirement on every mutating endpoint (POST, PUT, PATCH) where duplicate side‑effects are undesirable. GET/HEAD/OPTIONS can omit it, but enforcing it uniformly simplifies reasoning and avoids per‑route decisions.

Missing diagnostic detail

If your deployment runs more than one Node process (cluster, multiple containers, or horizontal scaling), the idempotency store must be shared across instances. Let me know whether you need a recommendation for a distributed store (e.g., Redis) or if a single‑process in‑memory cache is sufficient.