nestonexStart a project Why does the same event arrive twice, and how should a handler deal with it?
Because exactly-once delivery is not something distributed systems actually provide. Retries, redeliveries and blockchain reorgs all replay messages, so a handler has to produce the same result whether it runs once or five times. That usually means recognising a repeat by key rather than trusting the broker.
A consumer processes a message and then acknowledges it. If it dies in between, the broker never hears the acknowledgement and redelivers. Acknowledge first instead and a crash loses the message entirely.
There is no ordering of those two steps that gives exactly-once, because they are separate operations over a network that can fail between them. Systems advertising exactly-once are providing at-least-once delivery plus deduplication, which is the same thing you can build yourself.
A key that identifies the operation, and a check against it. Sometimes the domain provides one naturally, such as a transaction hash or an order id. Where it does not, the producer generates an idempotency key and the consumer records which keys it has seen.
The cleanest implementations make the write itself conditional, so inserting a row with a unique constraint on the key either succeeds or conflicts. The duplicate is then rejected by the database rather than by logic you have to remember to run.
Side effects you cannot take back. Sending an email twice is visible to a customer, and charging a card twice is worse. For those, the dedupe check has to happen before the side effect rather than after, and the record of having done it has to be durable.
Which creates its own window: record first and crash before sending, and the email never goes. There is no perfect answer, only a choice about which failure you prefer. For money, not sending twice is almost always the right side to err on.
Wen runs an idempotent event pipeline behind a service that boots as API, worker or indexer from one codebase, so a replayed chain event settles to the same state instead of double-crediting a reward or double-processing a fill.
AgencyOS approaches it from the other end: a transactional outbox guarantees events are published at all, which by design gives at-least-once delivery and makes idempotent consumers a requirement rather than a nicety.
Not as a delivery guarantee. Acknowledgement and processing are separate operations and the network can fail between them, so you get at-least-once or at-most-once. What is called exactly-once is at-least-once delivery plus deduplication at the consumer.
Record the intent durably with a key before sending, and check that key first. This trades duplicate sends for the possibility of a missed send if you crash between recording and sending. For anything involving money, that is the right trade.
A caller-supplied identifier for a specific operation, so a retry of the same request is recognised as the same operation rather than a new one. Payment APIs use them heavily, because a retried charge request must not become a second charge.
Yes, routinely on chains with fast blocks. A block that appeared final can be discarded and its transactions reappear elsewhere, so an indexer will see the same event more than once. Handling it is the normal path, not an exception.