Documentation
¶
Overview ¶
Package ring implements rendezvous (highest-random-weight, HRW) hashing — the L0 sharding primitive (DESIGN.md §11). Each key is placed on the nodes that score highest for it, where a node's score for a key is a hash of the key seeded by the node's identity. This gives:
- Deterministic placement: every node computes the same owners for a key with no shared state beyond the membership list, so routing needs no coordinator on the hot path.
- Minimal movement (~1/N) on membership change: adding a node only ever steals keys *to itself*, and removing a node only redistributes *its* keys — existing assignments between other nodes never reshuffle. This is the property that makes rebalancing move the minimal set of parts.
The ring is immutable; membership changes (Ring.With / Ring.Without) return a new ring.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Node ¶
Node is a cluster member. ID is its stable, unique identity (the only thing that affects placement). Zone is an optional failure domain for zone-aware replica spreading (carried now, used by the replication layer later).
type Ring ¶
type Ring struct {
// contains filtered or unexported fields
}
Ring is an immutable set of nodes over which keys are placed by HRW hashing. The zero value is an empty ring; construct one with New. Safe for concurrent use (read-only).
func New ¶
New returns a ring over nodes. Nodes with an empty or duplicate ID are dropped (ID is the identity), so membership is a well-formed set.
func (*Ring) Lookup ¶
Lookup returns up to rf nodes responsible for key, ordered by descending HRW score — the first is the primary, the rest are replicas. It returns fewer than rf nodes only when the ring has fewer than rf members, and nil for an empty ring or rf ≤ 0. Ties (equal scores) break by node ID, so the result is fully deterministic.
func (*Ring) Primary ¶
Primary returns the single owner of key (the highest-scoring node) and true, or a zero Node and false for an empty ring.
Source Files