Offline clients should not replay unsafe mutations

I’m building a local-first app, and my current rule is blunt: an offline client should never replay a queued mutation after reconnecting unless the server contract explicitly makes that safe. Seamless UX is attractive, but a replayed command is not the same thing as synchronizing state. It could charge a payment twice, resend an invitation, or provision another resource.

SDKs should require an idempotency key for replayable writes, expose a durable queue that users and developers can inspect, and leave conflict policy to the application. Automatic retries are reasonable only when the API promises deduplication or equivalent acknowledgement semantics; HTTP method names are not enough. A pending or indeterminate operation is sometimes safer than pretending success.

Would you trust a framework to retry writes automatically? I’d especially like counterexamples from production systems where that tradeoff worked safely.

Strongly agree on the method-name point. POST does not tell the client whether the server sent an email, allocated capacity, or recorded a charge before the connection vanished. The only honest retry decision comes from the operation contract, not the verb.

The product objection is that “pending” is a terrible experience when the user just wants to invite someone and move on. I’d still rather show uncertainty than silently create two invitations. The UI can be smooth without making the transport optimistic about side effects.

The HTTP guidance is notably cautious here: clients should not automatically retry non-idempotent requests unless they know the operation is safe or can establish that the first attempt did not apply. That supports a default-deny replay policy, though not necessarily one universal queue design.

I’d make the queue API boring and explicit: operation payload, idempotency key, attempt count, last error, and “acknowledgement unknown.” Developers can build a better review screen than an SDK vendor can guess at. The hard part is making those records durable without turning every client into a workflow engine.

I’m less absolute about “never.” A queued mutation that sets a local preference or replaces a document can be replayed safely under a declared last-write-wins policy. Your actual boundary is external side effects and undefined semantics, not mutations as a category.

That’s fair, and I mean “never” specifically for mutations whose safety has not been established. State synchronization can have a documented merge rule; a command that triggers money movement or provisioning needs a much stronger contract.

Idempotency keys also need scope and parameter binding. A key that can be reused with different payloads is not much protection. The server should reject mismatched parameters rather than treating the key as a magical universal duplicate shield.

Please include operational visibility, not just a client-side queue. Support needs to know whether an operation is pending, rejected, or possibly applied. “Tap retry” is a dangerous instruction when the original request might have succeeded and only the response disappeared.

Automatic retry libraries tend to hide the exact failure mode that matters: timeout after server receipt. Backoff solves load; it does not solve duplicate effects. I’d prefer an SDK that makes unsafe replay annoying at compile time or at least impossible without an explicit opt-in.

From the customer side, a duplicate invitation is irritating; a duplicate charge is a support incident. The interface should distinguish “not sent” from “sent but not confirmed,” even if that means asking someone to resolve it manually.

There is also a privacy angle to a reviewable queue. Pending payloads may contain personal data or secrets, so inspection must not mean casually exposing raw request bodies to every screen or log sink. Durable does not have to mean indiscriminate.

This is exactly the kind of capability procurement teams will ask to see: documented replay semantics, auditability, and a way to disable automatic retries by operation class. “The SDK usually handles it” will not satisfy a risk review after an ambiguous write.

A queue with a giant retry button is just a more attractive duplicate-action machine. Give me an explicit contract, a boring status page, and fewer promises. Offline magic is usually where the interesting bugs go to hide.

There’s a cost to all this ceremony, especially for small teams. But idempotency keys are cheaper than reconstructing what happened after a customer reports two charges or two provisioning events. I’d make the safe path the easy path and leave exceptions visible.