Patterns
Cursor-Based Sync
Let clients recover missed updates by asking for durable records after their last known position instead of trusting live delivery alone.
Concepts Covered
- Sync cursors
- Durable message logs
- Offline recovery
- Per-device progress
- Pagination
- Gap detection
- Reconnect sync
- Retention windows
1. Intent
Cursor-Based Sync lets a client recover missed updates by asking the server for records after its last known position.
Realtime push is fast, but it is not enough. Connections drop. Devices sleep. Apps restart. A gateway can push an event while the client is changing networks.
Cursor-based sync gives the client a reliable recovery path:
Give me messages after sequence 84211.
This pattern turns reconnection from guesswork into a repeatable query.
2. The Problem Without This Pattern
If a system relies only on realtime delivery, it has no clean answer when a client disconnects.
The server may not know exactly what the client received. The client may not know whether it missed events. The gateway may have crashed. Delivery workers may have retried. Without a cursor, the system often falls into fragile behavior:
- resend too much
- miss messages
- depend on in-memory queues
- ask the client to trust local state blindly
- mark messages delivered before durable receipt
A durable cursor gives both sides a shared reference point.
3. How The Pattern Works
The server assigns ordered positions inside a stream or conversation:
conversation_id = c_10
message m_1 -> sequence 101
message m_2 -> sequence 102
message m_3 -> sequence 103
Each device stores its progress:
device_id + conversation_id -> last_received_sequence
d_phone + c_10 -> 102
When the device reconnects, it asks:
GET /conversations/c_10/messages?after=102
The server returns messages after that sequence, respecting membership, retention, deletes, and pagination.
The client should advance its cursor only after it has safely stored or applied the returned records. Advancing too early can create permanent gaps.
4. When To Use It
Use cursor-based sync when:
- clients can go offline
- realtime delivery can be interrupted
- clients need deterministic recovery
- message history is stored durably
- devices may sync at different speeds
- ordered updates matter
- the product supports multi-device usage
This pattern is common in messaging, notification feeds, collaborative systems, activity logs, and mobile-first applications.
5. When Not To Use It
It may not fit when:
- the data has no natural ordering
- missed events do not matter
- the server cannot retain enough history
- clients only need the latest snapshot
- rebuilding from a snapshot is cheaper than replaying changes
Even then, a snapshot often has a hidden cursor, timestamp, or version behind it.
6. Data And Operational Model
A cursor model needs:
message_log
- conversation_id
- sequence
- message_id
- created_at
device_sync_state
- device_id
- conversation_id
- last_received_sequence
- updated_at
Operators should monitor:
- sync request rate
- average cursor lag
- oldest unsynced device cursor
- pagination depth
- sync error rate
- devices syncing after long offline periods
- cursor gaps
- history-retention misses
The API should paginate results and support resume. A device offline for months should not receive every missed record in one giant response.
7. Failure Modes
- The cursor advances before the client safely stores messages.
- The server deletes history before offline devices sync.
- Membership changes are not applied relative to the cursor.
- A client sends an old cursor and receives too much data.
- A client sends a future cursor because of a local bug.
- Cursor state is per user when it needed to be per device.
- Retention policy makes recovery impossible for old devices.
8. Tradeoffs
| Benefit | Cost |
|---|---|
| Makes offline recovery deterministic | Requires ordered durable history |
| Reduces dependence on live gateways | Needs cursor storage and pagination |
| Works well for multi-device sync | Membership and retention logic get harder |
| Helps clients detect gaps | Long offline periods can create heavy sync |
| Supports reconnect recovery | Cursor advancement must be careful |
Cursor-based sync is one of the main reasons mobile messaging can survive unreliable networks without losing accepted messages.
9. Related Systems And Concepts
Knowledge links
Use these links to understand what to know first, where this idea appears, and what to study next.
Prerequisites
Read these first if this topic feels unfamiliar.
Used In Systems
System studies where this idea appears in context.
Related Concepts
Core ideas that connect to this topic.