# How to Use Hash-Based Routing

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

```elixir
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:

```elixir
{: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:

```elixir
{: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`:

```elixir
{: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`](https://hex.pm/packages/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