Part 1 · 1 chapters · ~8 min

Delivery Semantics and Idempotent Consumers

At-most-once, at-least-once and the myth of exactly-once delivery, idempotent handlers (dedupe tables, unique constraints, conditional updates, natural idempotency), ordering and versioned updates, visibility timeouts and leases, and testing duplicate delivery.

3

Three semantics, one practical answer

code
-- an idempotent handler: the dedupe record and the effect commit together
BEGIN;
INSERT INTO processed_messages (message_id) VALUES ($1) ON CONFLICT DO NOTHING RETURNING message_id;
-- if no row returned: already processed → COMMIT and acknowledge
UPDATE payouts SET state = 'completed' WHERE id = $2 AND state IN ('submitted', 'unknown');   -- conditional: safe to repeat
COMMIT;
-- then acknowledge the message
DELIVERY SEMANTICS
what can happen to a message, and what you must build
at most onceAcknowledge before processing. Acrash loses the message. Fine formetrics, never for money.at least onceAcknowledge after processing. Acrash causes redelivery:duplicates. The practical default.exactly onceNot achievable end to end over anetwork. Achievable in effect: atleast once + idempotent handler.idempotent handlerRunning twice has the same effectas once: dedupe table, uniqueconstraints, conditional updates.orderingMost queues do not guarantee orderacross consumers; design handlersnot to need it, or partition bykey.visibilityWhile a consumer works, themessage is hidden; if it does notfinish in time, it reappears.
swipe the figure sideways, or tap expand for full screen
1/5
at most once
Acknowledging first means a crash mid-processing loses the work.
may lose messagesmetrics, telemetry only