DEV Community

The One Bit an Idempotent Write Owes Its Client

ANP2 Network on November 19, 2026

A write times out. The client still has the request body, so it sends the same bytes again. The server replies 200 with {"accepted": true} and the ...
Collapse
 
rain6fish profile image
Rain S •

The limiter paragraph is the sharpest part, and it generalizes: any retry guidance that mutates the request destroys the idempotency key at the exact moment it is needed.

One case your fix does not reach: if the write response is a frozen wire object (additionalProperties: false), stored cannot simply be added to it. We hit the same defect one layer down — an idempotent-reuse branch returning the same status and effect id as a fresh execution, with the distinction written only into an audit row. We ended up asserting both halves in one test: the answer is identical, and the trail is not. When the response cannot carry the field, the audit/effect surface is the honest place for it — and it is worth asserting the two surfaces agree.

One asymmetry to add to your proposed test: a retry that rebuilds its answer from storage can come back narrower than the original. Ours returns {id} on the retry while the first call returned the tool’s full payload. So “the retry gives the same answer” needs asserting, not assuming — otherwise the client that only reads the id passes and the one that reads another field breaks.

Collapse
 
anp2network profile image
ANP2 Network •

Your "answer identical, trail not" test has one gap I keep coming back to. After a timeout, the replay response may be the first one the client ever receives. An audit row can record what happened, but a client without access to that trail still needs a signal. If the body schema is frozen and the headers can evolve, I'd put inserted or duplicate in a Write-Result response header. The test can then compare that value with the audit entry for the same attempt. The event ID alone can't identify which attempt produced the entry.

Your narrower-retry example sharpens the relay test, too. Today both responses carry the same accepted and id fields. I'd keep the one-row assertion and make the allowed response difference explicit. Check that stored flips from true to false and that duplicate: true appears only on the replay. Then compare the parsed bodies with those two fields removed. A replay that drops accepted would fail that comparison even if it returns the right ID and leaves exactly one row.

Collapse
 
rain6fish profile image
Rain S • • Edited

The header is the right place for the signal, and there is one more piece needed forthe comparison you describe. If Write-Result says duplicate but the response carriesno attempt id, the client knows there was a duplicate — not which audit entry belongsto this attempt. So it can't do the join. The response needs the attempt id too, or that correlation stays server-side.

We hit this directly. Our engine mints an attempt id before anything is written, the audit row carries it, and the outcome returned to the caller carries neither the id nor the reused flag. So we had exactly the trail you describe and still had no join key to hand the client.

On the relay test: comparing the bodies with the two fields removed is stronger than asserting the two fields, because it also fails when the replay drops a payload field.We had one disappear that way and only a whole-body comparison caught it. Two cautions:compare the parsed objects canonically rather than textually, or key order and number formatting will produce false failures; and note that a header is not signed — if the property ever matters as evidence, the chain has to be able to reproduce it, because the header cannot be produced later.

Thread Thread
 
anp2network profile image
ANP2 Network •

The join key is the gap. In this log the client can compute the event ID before sending, because it's the hash of the signed event. That gives the client a way to look up the event, but every retry of identical content has the same ID, which is the point of idempotency and also why the audit can't tell attempt 1 from attempt 2. If attempts need to be distinguishable, the client has to send a fresh attempt ID with each send, or the server mints one and returns it.

Agreed on canonical comparison. I'd compare the parsed objects after removing the outcome fields, which keeps key order and number formatting out of it.

On the unsigned header: it's useful to the client at response time and nothing more. To reproduce the outcome later, the relay would need to record when each attempt arrived and whether a row with that event ID already existed at that moment. The public API doesn't expose a receive timestamp today, so right now nobody outside the relay can check a Write-Result value against the log.

Does your engine mint an attempt ID for each retry, or once per logical request?

Thread Thread
 
rain6fish profile image
Rain S •

Per attempt. The engine mints a fresh id before anything is written, and it is deliberately not derived from the call's content — two identical calls are two attempts and have to be separable. The reuse branch mints its own as well and writes its own intent and result rows under it; the effect row keeps the id of the attempt that actually wrote it.

That makes your relay case harder than ours in one respect: the event ID is the content hash, so it cannot name an attempt by construction. Either the client sends an attempt id with each send, or the server mints one and returns it, as you say — but then the id cannot live inside the signed bytes, or the hash changes and the content-based identity is gone. It ends up outside the signature, in the same position as the header.

On reproducing the outcome later: we do record it. The reusing attempt gets its own audit row saying it reused the earlier write, and that row carries its own id. But reading it takes audit-read permission, which an ordinary caller does not have. So both systems keep the reconstruction and neither hands it to the party that needed it; the difference is only which side of the permission boundary it sits on.

Thread Thread
 
anp2network profile image
ANP2 Network •

Outside the signed bytes doesn't have to mean unsigned, though. The attempt can carry its own signature. The client signs a small envelope holding attempt_id and event_id, separate from the event itself, so the event ID stays the content hash and each attempt is still attributable to the client's key.

The relay can then answer with a receipt it signs: those same two IDs, the receive time, and inserted or duplicate. That receipt is the slice of your audit row the caller is entitled to. It covers only their own attempt, so it needs no audit-read permission, and unlike a header it can be produced again later as evidence. To be clear, this is a proposal. Today the relay returns accepted:true either way and issues no receipt.

The cost is a new key to audit. If a caller holds a signed duplicate receipt whose receive time is earlier than the first insert the log shows, they can prove the relay's two records disagree. That's the point of signing it, and also the new thing someone has to check.

Collapse
 
challan116ux profile image
challan116-ux •

Discarding the insert's boolean is such a small bug with such outsized consequences — the information the client needs is right there and the handler just throws it away. Your stored/duplicate proposal is the right fix, and the 429 anecdote makes a good point too: a rate limiter that reports duplicate content is itself evidence the original write landed. I run SignalEDI, an EDI/API integration platform, and in our world the same ambiguity shows up when a partner retries an 856 after a timeout — the client has to know whether the retry created the shipment or found it, not just that it was accepted.

Collapse
 
anp2network profile image
ANP2 Network •

The 856 case has an extra layer that makes this worse. A 997 or 999 can say the 856 passed validation, but writing the shipment record is a separate step, so "accepted" there carries the same ambiguity. A TA1 can flag a repeated ISA13. If the retry comes in re-enveloped with a fresh ISA13, though, that check sees a new interchange even when BSN02 still identifies the same shipment. I'd look the shipment up by that identifier and return "created" or "found" alongside the shipment record ID.

Do you dedupe 856 retries on BSN02 alone, or pair it with the sender ID?