How to Use Hash-Based Routing

Copy Markdown View Source

This guide shows you how to route requests to consistent nodes using the HashRing algorithm, so that the same key always lands on the same node — even when the cluster topology changes.

Start a balancer with HashRing

alias RpcLoadBalancer.LoadBalancer.SelectionAlgorithm

{:ok, _pid} =
  RpcLoadBalancer.start_link(
    name: :hash_balancer,
    selection_algorithm: SelectionAlgorithm.HashRing
  )

Route by key

Pass a :key option when selecting a node or making an RPC call:

{:ok, node} =
  RpcLoadBalancer.select_node(:hash_balancer, key: "user:123")

The same key will always resolve to the same node. This is useful for session affinity, caching, and sharding workloads.

Use with the convenience API

The :key option works with call/5 and cast/5 too:

{:ok, result} =
  RpcLoadBalancer.call(
    node(),
    MyCache,
    :get,
    ["user:123"],
    load_balancer: :hash_balancer,
    key: "user:123"
  )

Fallback behaviour

When no :key is provided, select_node/2 falls back to random selection. This means you can use the same balancer for both keyed and unkeyed requests.

Configure weight (virtual nodes)

Each physical node is placed on the ring multiple times as virtual nodes (shards). More shards means better key distribution uniformity at the cost of slightly more memory. The default weight is 128 shards per physical node.

Override it via algorithm_opts:

{:ok, _pid} =
  RpcLoadBalancer.start_link(
    name: :hash_balancer,
    selection_algorithm: SelectionAlgorithm.HashRing,
    algorithm_opts: [weight: 256]
  )

Topology stability

When nodes join or leave the cluster, only a minimal number of keys get redistributed. The majority of keys stay assigned to the same physical node.

For example, adding a 5th node to a 4-node cluster redistributes roughly 1/5 of keys (the ideal minimum), rather than reshuffling everything. Removing a node only moves the keys that were assigned to that node — keys on other nodes are unaffected.

How the hash ring works

The HashRing algorithm is powered by libring:

  1. Each physical node is sharded into weight points (default 128) distributed across a 2^32 continuum using SHA-256
  2. The ring is stored in a PersistentTerm-backed cache for fast lookups
  3. To look up a key, the key is hashed to a point on the ring, then the next highest shard clockwise determines the owning node
  4. key_to_nodes/3 walks the ring from that point to find N distinct physical nodes for replica selection
  5. When topology changes, the ring is invalidated and lazily rebuilt on the next lookup