SHELF (Shared, Harmonized, Eventually, Ledger, Fault-tolerant) is a peer-to-peer distributed shopping list application, featuring conflict-free replication (CRDT), quorum-based consistency, and automatic bootstrap failover.
Key Features #
- Consistent Hashing Ring - Distributes lists across peers with 64 virtual nodes per peer
- Quorum-Based Replication - Configurable N/W/R parameters for consistency vs availability tradeoff
- Hinted Handoff - Stores failed writes and retries delivery every 10 seconds
- Active Sync - Automatically pushes pending changes and pulls latest state when peers join or go online
- Merkle Tree Optimization - Compares hashes before downloading full state to reduce network traffic
- Read Repair - Automatically fixes inconsistencies during quorum reads
- Delta-Based Writes - Sends only changes (not full state) for efficient replication
- CRDT-Based Merging - Conflict-free convergence using OR-Set (items), RGA (ordering), and LWW-Register (properties)
- Bootstrap Cluster - Automatic leader election and failover within ~5 seconds
- Time Security - Protected against timestamp-based attacks and clock skew
Bootstrap Cluster (High Availability) #
The system supports multiple bootstrap servers running simultaneously. Only one bootstrap acts as the leader at any given time, handling all peer registrations and heartbeats. The remaining bootstraps are standbys that automatically become leader if the current leader fails.
Leader Election #
- Election Interval: Every 5 seconds
- Leader Selection: First responsive bootstrap (lowest port wins in case of tie)
- Standby Role: Forwards requests to leader to ensure consistency
- Automatic Failover: When leader dies, next highest-priority bootstrap becomes leader within ~5 seconds
Security Features #
TimeService (Local Clock Protection) #
Ensures your machine’s clock stays synchronized and prevents “Ratchet” issues:
- Calculates offset from server time on sync
- Enforces monotonicity: even if local clock rewinds, returned timestamp always increases
- Allows backward correction when syncing with the bootstrap server to fix “future” clock errors (prevents nodes from getting stuck in the future)
DeltaSanitizer (Peer Validation) #
Strictly rejects suspicious timestamps from remote peers before merging:
- Allows ±1 hour tolerance from server time
- Timestamps beyond tolerance are reset to 0 (Unix Epoch)
- This ensures that “future” data always loses in Last-Writer-Wins merges against valid present data
See the code over at GitHub.