Idempotency

Deep idempotency workflow—identifying retry surfaces, idempotency keys, storage and TTL, exactly-once pitfalls, and testing duplicate delivery. Use when designing safe APIs, workers, and payment flows under at-least-once delivery.

codenova58@codenova58

Install

openclaw skills install @codenova58/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.