CRDTs & Hybrid Logical Clocks
How TopGun manages state consistency and time across distributed, offline-first clients without a central coordinator.
Optimistic UI & Consistency
TopGun uses Optimistic Updates by default. When a user performs an action, it is applied immediately to the local state.
- Immediate Feedback: The UI updates instantly (0ms latency).
- Background Sync: Behind the scenes, an Operation Log (OpLog) queues the mutation.
- Convergence: The Sync Engine uploads changes when the network is available.
Data Flow
- User clicks “Save”
map.set(key, val)→ Local State Updated- UI Refreshes (Frame 1)
- OpLog entry created
- Sync Engine pushes to Server (Async)
Hybrid Logical Clocks (HLC)
In distributed systems, you cannot rely on physical time (wall clock) because device clocks drift or can be manually changed. TopGun solves this with Hybrid Logical Clocks.
How it works
Every event in TopGun is tagged with an HLC timestamp. This timestamp combines:
- Physical Time: The wall clock time (e.g., from
Date.now()). - Logical Counter: A counter that increments if multiple events happen within the same millisecond or if the physical clock regresses.
- Node ID: A unique identifier for the device/client, used as a tie-breaker when timestamps are equal.
interface Timestamp {
millis: number; // Physical wall clock (ms since epoch)
counter: number; // Logical counter for same-ms events
nodeId: string; // Unique node identifier (tie-breaker)
}
// Example: "1701234567890:0:client-abc123"
// Serialized format: "<millis>:<counter>:<nodeId>"Why is this important?
It allows TopGun to correctly order events across devices even if their clocks are slightly off. “Last-Write-Wins” is determined by comparing HLCs, not unreliable system time.
Clock Drift Tolerance
TopGun tolerates clock drift of up to 60 seconds between devices. If a remote timestamp is more than 60 seconds ahead of local time, the event is still accepted (to maintain availability), but a warning is logged. This ensures the system remains functional even with misconfigured device clocks.
Conflict-Free Replicated Data Types (CRDTs)
TopGun guarantees that all clients eventually converge to the same state without manual conflict resolution code. It uses a Last-Write-Wins (LWW) Map CRDT structure.
function merge(localState, remoteState) {
// Simplified LWW Logic
if (remoteState.hlc > localState.hlc) {
return remoteState; // Remote is newer, overwrite local
} else if (remoteState.hlc < localState.hlc) {
return localState; // Local is newer, ignore remote
} else {
// Timestamps equal? Compare node IDs deterministically
return remoteState.nodeId > localState.nodeId ? remoteState : localState;
}
}