Build a hash ring that distributes keys across nodes uniformly and minimizes key migration when the cluster topology changes. Naive modulo hashing remaps almost every key on each change — consistent hashing limits disruption to only 1/N of keys.
1. The Ring. Hash both nodes and keys onto a circle (0 → 2³²). Each key walks clockwise to find its owner.
2. Virtual Nodes. Each physical node occupies 100–200 positions (e.g. node-A#42) to smooth distribution.
3. Minimal Disruption. Adding/removing a node only moves ~1/N of keys. Modulo hashing remaps almost everything.
Add a node with virtual node positions. Idempotent.
Remove node. Only its keys move clockwise. No-op for unknown nodes.
Return responsible node. Deterministic. None on empty ring.
Correctness is gated — below 50% skips all other phases. Rebalancing is hardest: <1% unnecessary remaps = 100/100.
| Metric | Yours | Ideal |
|---|
10 functional checks: CRUD, edge cases, determinism, and error handling.
| Test | Got | Expected |
|---|
10,000 keys distributed across 10 nodes. Lower CV = more uniform.
The hardest phase — how many keys move unnecessarily when the ring changes?
50 nodes, 20K lookups — does the ring hold up at scale?
3,000 get_node calls benchmarked with microsecond precision.