idempotency

# Idempotency (Deep Workflow) Most distributed systems deliver work **at least once**. Idempotency makes **duplicate processing safe**—critical for payments, inventory, and message consumers. ## When to Offer This Workflow **Trigger conditions:** - Retries on HTTP, queues, or background jobs - Double charges, duplicate records, or “at-least-once” confusion - Product asks for “exactly-once” semantics **Initial offer:** Use **six stages**: (1) identify side effects, (2) choose keys, (3) storage & scope, (4) API patterns, (5) worker patterns, (6) testing). Confirm storage (Redis, SQL) and retention window. --- ## Stage 1: Identify Side Effects **Goal:** Classify operations: reads vs creates vs monetary transfers vs state transitions. **Exit condition:** List of mutations that must be idempotent under retries. --- ## Stage 2: Choose Keys **Goal:** Client-supplied `Idempotency-Key` header (Stripe-style) vs deterministic hash of normalized payload—trade UX vs collision risk. --- ## Stage 3: Storage & Scope **Goal:** Store key → outcome or result reference with TTL covering retry window; scope keys per tenant/user when needed. --- ## Stage 4: API Patterns **Goal:** Same key + same body → same outcome; reject or conflict if same key with different body. --- ## Stage 5: Worker Patterns **Goal:** Natural unique constraints in DB; dedupe table keyed by `event_id` or business idempotency key for consumers. --- ## Stage 6: Testing **Goal:** Chaos or integration tests that deliver duplicate messages; property tests for key behavior. --- ## Final Review Checklist - [ ] Mutating paths classified - [ ] Key strategy and scope documented - [ ] Storage, TTL, conflict rules defined - [ ] HTTP and async consumers aligned - [ ] Duplicate delivery tests ## Tips for Effective Guidance - True exactly-once end-to-end is rare—design for at-least-once + idempotent effects. - Pair with **message-queues** and **rest-best-practices** for HTTP idempotency keys. ## Handling Deviations - Financial flows: require stronger audit and longer key retention.