22.6 What is an idempotent consumer?

At the bank: If your token is called twice by mistake, the second clerk checks the stamp in your passbook: "already paid". They don't pay you twice.

In the system: With at-least-once delivery, every consumer will sometimes see the same message twice. An idempotent consumer produces the same result however many times it processes a message.

Some operations are naturally idempotent:

• "Set order 881's status to packed": doing it twice leaves it packed.
• "Upsert the search document for book 42."

Others aren't, and need protection:

• "Add 50 points to Asha": twice gives 100.
• "Send an SMS": twice annoys the customer.
• "Charge ₹499": twice is a real problem.

How to make them idempotent:

• Record what you've processed. Keep a table of processed message IDs, or better, a business key like (order_id, "loyalty_points"), with a unique constraint. Insert the record and apply the effect in the same transaction (Chapter 17); a duplicate fails the insert and is skipped.
• Use conditional updates: UPDATE orders SET status='packed' WHERE id=881 AND status='paid'.
• Pass idempotency keys downstream: when the worker calls the payment provider or SMS gateway, send the order ID as the idempotency key, so they de-duplicate too (Chapter 24).

In the chapter's code, order 881's points message is delivered twice. The naive worker gives Asha 100 points; the idempotent one gives 50.

Memory code: "Stamp the passbook, so a second call pays nothing."

---