In today’s collaborative software, users expect their changes to appear instantly and never be lost, even when network connections are flaky. Achieving that reliability in a local‑first architecture—where each client works offline and later syncs with the server—requires a disciplined approach.
Exactly‑once synchronization is defined as the guarantee that every user edit is applied on the server a single time, no more and no less, regardless of connection interruptions.
How Local‑First Architecture Works
Each workspace lives in a Durable Object on the server, while browsers keep a copy in IndexedDB. The UI shows edits immediately, and a WebSocket streams changes to the server. The server, not the client, decides the final state.
Rule 1: Server‑Authoritative Sequencing
The server assigns a monotonically increasing sequence number to every incoming operation. Clients treat this number as the single source of truth.
- When a client sends an edit, it tags the request with a temporary local ID.
- The server validates, persists, and returns the official sequence number.
- The client replaces the temporary ID with the server‑provided one, discarding any duplicate submissions.
Result: Even if the same edit is retransmitted after a reconnect, the server recognises the duplicate sequence and ignores it.
Rule 2: Idempotent Client Acknowledgment
Clients must only consider an edit committed after receiving the server’s acknowledgment containing the definitive sequence number.
- Send the edit over the WebSocket.
- Store the edit locally with a pending flag.
- On acknowledgment, clear the flag and update the local log.
If the connection drops before the acknowledgment arrives, the client retries the operation. Because the server’s sequencing is idempotent, the retry does not create a second entry.
Handling Network Interruptions Gracefully
When a tunnel cuts the WebSocket, the client enters a reconnection loop. During this period:
- All pending edits remain in IndexedDB with their temporary IDs.
- The client buffers new edits locally, preserving user experience.
- Upon reconnection, the client re‑sends only the pending edits, relying on Rule 1 to filter duplicates.
This approach ensures that the comment typed on a moving train will appear exactly once on the server, no matter how long the outage lasts.
Implementing the Rules with Modern Stack
Developers can leverage Cloudflare Durable Objects for server‑side state, IndexedDB for offline storage, and standard WebSocket APIs for real‑time transport. The logic for sequencing and acknowledgment is lightweight and can be encapsulated in a reusable library, making it easy to adopt across mobile (iOS, Android, Flutter) and web projects.
Frequently Asked Questions
What if two users edit the same record simultaneously?
The server’s sequence numbers impose a total order. Conflicts are resolved on the server side, and each client receives the authoritative version in the acknowledgment.
Do I need a custom backend for this pattern?
No. The pattern works with any backend that can assign monotonic IDs and acknowledge receipts—Durable Objects, traditional servers, or serverless functions all qualify.
How does this differ from optimistic UI updates?
Optimistic updates let the UI assume success, but they still rely on server acknowledgment to finalize the state. Our two‑rule system formalises that acknowledgment and guarantees exactly‑once persistence.
Can this be used with GraphQL subscriptions?
Yes. The subscription channel can deliver the server‑assigned sequence numbers, allowing the client to reconcile local edits with the authoritative order.
What performance impact does sequencing have?
Assigning a sequential ID is O(1) and adds negligible latency. The real cost is network round‑trip, which is already required for acknowledgment.
Neptune Infotech can help you integrate exactly‑once sync into your local‑first applications, ensuring reliable collaboration across any device.
