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.