Fastify request lifecycle and Redis idempotency store: duplicate POST handling at integration boundary

Answer

In-flight duplicates: do not allow them to proceed and do not hard-reject them. Claim the key with an atomic Redis SET NX PX in-flight marker and, if the claim fails, wait for completion and replay the stored response. Replaying matches Stripe-style idempotency and avoids 409s for legitimate retries. Hard rejection loses the client outcome; allowing proceed defeats deduplication.

Shared dedup store visibility: register the Redis idempotency plugin at root scope or with fastify-plugin so the decorator is visible to all prefixes. A plugin registered inside one prefixed context is not visible to sibling prefixes due to Fastify encapsulation.

Hook placement for key read: onRequest runs before body parsing. preHandler runs after body parsing. If Idempotency-Key is header-only, onRequest is earliest safe. If the key can be in the body, you must read it in preValidation or preHandler.

Confirmed Fastify facts

• Fastify has no built-in idempotency or request-coalescing primitive. Deduplication is application code.
• Hook order: onRequest → preParsing → preValidation → preHandler → handler → preSerialization → onSend → onResponse. Body is parsed before preValidation/preHandler.
• Encapsulation scopes decorators and hooks to the registration context. Sibling prefixes do not share plugins registered inside one of them unless the plugin is exported with fastify-plugin or registered at root.

Likely design choices

• Concurrent duplicate policy is a design decision. Wait-and-replay is generally safer than 409 Conflict because retries typically want the original outcome, not an error.
• Store a response fingerprint with the key to detect key reuse with a different payload and reject with 422 instead of returning a wrong cached response.

Steps for this case

1. Register a single idempotency plugin at root with fastify-plugin so fastify.redis and fastify.idempotency are visible across all route prefixes.
2. Read Idempotency-Key in onRequest if header-only, else in preHandler. Validate presence for POST.
3. In preHandler, atomically claim: SET key NX PX ttl. If key exists with status=completed, replay stored status/body and return early. If key exists with status=in-flight, wait with a short poll or Pub/Sub until completed or TTL expires, then replay.
4. On first claim success, store in-flight marker with request fingerprint. After handler succeeds, write final response to Redis with completed status and a TTL longer than max client retry window.
5. Clean up in-flight marker on error so retries can proceed after TTL.

One diagnostic that changes the recommendation: is the Idempotency-Key guaranteed to be in the header, or can it also be carried in the parsed body? If body-carried, the check must move from onRequest to preHandler/preValidation.