# Load Balancer Reference

Complete API reference for all public modules in `rpc_load_balancer`.

## RpcLoadBalancer

Top-level module and per-instance Supervisor. Provides the public API for node selection, RPC calls/casts, random-node helpers, and low-level `:erpc` wrappers.

### Types

```elixir
@type name :: atom()
```

### Functions

#### `start_link(opts)`

Starts a load balancer Supervisor that manages the caches and GenServer for a single balancer instance.

**Options:**
- `:name` (required) — registered name for the balancer
- `:selection_algorithm` — module implementing `SelectionAlgorithm` (default: `SelectionAlgorithm.Random`)
- `:algorithm_opts` — keyword list forwarded to the algorithm's `init/2` callback (default: `[]`)
- `:node_match_list` — controls which nodes join the `:pg` group (default: `:all`)
  - `:all` — every node joins
  - `[String.t() | Regex.t()]` — only nodes matching at least one entry join
- `:drain_timeout` — maximum time in milliseconds to wait for in-flight calls to complete during shutdown (default: `15_000`)

**Returns:** `Supervisor.on_start()`

#### `get_members(load_balancer_name)`

Returns the deduplicated list of nodes registered in the `:pg` group for this balancer.

**Returns:**
- `{:ok, [node()]}` when members exist
- `{:error, %ErrorMessage{code: :service_unavailable}}` when the group is empty

#### `select_node(load_balancer_name, opts \\ [])`

Selects a node from the balancer's registered members using the configured algorithm.

**Options:** forwarded to the algorithm's `choose_from_nodes/3` (e.g., `key: "user:123"` for HashRing)

**Returns:**
- `{:ok, node()}` on success
- `{:error, %ErrorMessage{code: :service_unavailable}}` when no nodes are registered

#### `call(node, module, fun, args, opts \\ [])`

Executes a synchronous RPC call. When the `:load_balancer` option is present, the call is routed through the named balancer (the `node` argument is ignored). Otherwise, the call goes directly to the specified node via `:erpc.call/5`.

**Options:**
- `:timeout` — call timeout in milliseconds (default: `10_000`)
- `:load_balancer` — name of a running load balancer to route through
- `:key` — forwarded to the selection algorithm (used by HashRing)
- `:call_directly?` — when `true`, executes locally via `apply/3` regardless of balancer (default: from config)

**Returns:**
- `{:ok, result}` on success
- `{:error, %ErrorMessage{code: :request_timeout}}` on timeout
- `{:error, %ErrorMessage{code: :service_unavailable}}` on connection failure or no members
- `{:error, %ErrorMessage{code: :bad_request}}` on bad arguments

#### `cast(node, module, fun, args, opts \\ [])`

Executes an asynchronous RPC cast. When the `:load_balancer` option is present, the cast is routed through the named balancer (the `node` argument is ignored). Otherwise, the cast goes directly to the specified node via `:erpc.cast/4`.

**Options:**
- `:load_balancer` — name of a running load balancer to route through
- `:key` — forwarded to the selection algorithm (used by HashRing)
- `:call_directly?` — when `true`, executes locally via `spawn/3` regardless of balancer (default: from config)

**Returns:**
- `:ok` on success
- `{:error, %ErrorMessage{}}` on failure

#### `call_on_random_node(node_filter, module, fun, args, opts \\ [])`

Selects a random node from `Node.list/0` whose name contains `node_filter` (substring match), then executes an RPC call on it. If the current node matches the filter or `:call_directly?` is `true`, executes locally.

Retries automatically when no matching nodes are found (configurable via `:retry?`, `:retry_count`, `:retry_sleep`).

**Options:**
- `:timeout` — call timeout in milliseconds
- `:load_balancer` — optional balancer name for connection draining
- `:call_directly?` — execute locally (default: from config)
- `:retry?` — enable retry on no nodes (default: from config, `true`)
- `:retry_count` — max retries (default: from config, `5`)
- `:retry_sleep` — sleep between retries in milliseconds (default: `5_000`)

**Returns:**
- `{:ok, result}` on success
- `{:error, %ErrorMessage{code: :service_unavailable}}` when no nodes match

#### `cast_on_random_node(node_filter, module, fun, args, opts \\ [])`

Same as `call_on_random_node/5` but uses `cast/5` instead of `call/5`.

**Returns:**
- `:ok` on success
- `{:error, %ErrorMessage{code: :service_unavailable}}` when no nodes match

---

## RpcLoadBalancer.Config

Configuration defaults. All values can be overridden via application config:

```elixir
config :rpc_load_balancer,
  call_directly?: false,
  retry?: true,
  retry_count: 5
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `:call_directly?` | `boolean()` | `false` | When `true`, all load-balanced calls execute locally via `apply/3` |
| `:retry?` | `boolean()` | `true` | Enable automatic retry when no nodes are available |
| `:retry_count` | `non_neg_integer()` | `5` | Maximum number of retries |

---

## RpcLoadBalancer.LoadBalancer

GenServer that joins the `:pg` group, monitors membership changes, and performs graceful connection draining on shutdown. Started internally by `RpcLoadBalancer.start_link/1` — you don't typically interact with this module directly.

---

## RpcLoadBalancer.LoadBalancer.SelectionAlgorithm

Behaviour definition and dispatch layer for selection algorithms.

### Callbacks

#### Required

```elixir
@callback choose_from_nodes(load_balancer_name(), [node()], opts :: keyword()) :: node()
```

Called to pick one node from the available list. Receives the balancer name, the current node list, and any caller-provided options.

#### Optional

```elixir
@callback init(load_balancer_name(), opts :: keyword()) :: :ok
```

Called once during balancer startup. Receives `algorithm_opts` from `start_link/1`.

```elixir
@callback choose_nodes(load_balancer_name(), [node()], pos_integer(), opts :: keyword()) :: [node()]
```

Called to pick multiple distinct nodes. Used internally by the `SelectionAlgorithm` dispatch layer. Algorithms that don't implement this fall back to returning randomly shuffled nodes.

```elixir
@callback on_node_change(load_balancer_name(), {:joined | :left, [node()]}) :: :ok
```

Called when the `:pg` group membership changes.

```elixir
@callback release_node(load_balancer_name(), node()) :: :ok
```

Called after an RPC call completes to clean up per-node state (e.g., decrement connection counters).

```elixir
@callback local?() :: boolean()
```

When `true`, the load balancer bypasses `:erpc` and executes calls locally via `apply/3` and casts via `spawn/3`. Used by `CallDirect`.

---

## Built-in Algorithms

All algorithms live under `RpcLoadBalancer.LoadBalancer.SelectionAlgorithm.*`.

### Random

Picks a random node using `Enum.random/1`. No state, no configuration.

### RoundRobin

Cycles through nodes using an atomic counter (`CounterCache`). The counter auto-resets after 10,000,000 to prevent overflow.

### LeastConnections

Tracks active connections per node with atomic counters. Always picks the node with the lowest count. Increments on selection, decrements on `release_node/2`.

Implements: `init/2`, `choose_from_nodes/3`, `on_node_change/2`, `release_node/2`

### PowerOfTwo

Samples two random nodes and picks the one with fewer active connections. Same counter infrastructure as LeastConnections but with O(1) selection cost instead of O(n).

Implements: `init/2`, `choose_from_nodes/3`, `on_node_change/2`, `release_node/2`

### HashRing

Consistent hash ring powered by [`libring`](https://hex.pm/packages/libring). Each physical node is sharded into `weight` points (default: 128) distributed across a `2^32` continuum using SHA-256. Key lookup finds the next highest shard on the ring via `gb_tree`. Falls back to random selection when no key is given. The ring is stored in a `PersistentTerm`-backed cache and lazily rebuilt when topology changes.

Supports replica selection via `choose_nodes/4` using `HashRing.key_to_nodes/3` — returns multiple distinct nodes for a given key, walking the ring from the primary shard.

**Algorithm options:**
- `:weight` — number of shards per physical node (default: `128`)

Implements: `init/2`, `choose_from_nodes/3`, `choose_nodes/4`, `on_node_change/2`

### WeightedRoundRobin

Expands the node list by duplicating each node according to its weight, then cycles through with an atomic counter. Weights are passed via `algorithm_opts: [weights: %{node => integer}]`. Nodes without an explicit weight default to 1.

Implements: `init/2`, `choose_from_nodes/3`

### CallDirect

Executes calls directly on the local node via `apply/3` instead of going through `:erpc`. `call/5` with `load_balancer:` returns `{:ok, apply(module, fun, args)}` and `cast/5` with `load_balancer:` uses `spawn/3` and returns `:ok`. No remote nodes are contacted.

Designed for testing and single-node deployments where RPC overhead is unnecessary. Should always be used as the selection algorithm in test environments.

Implements: `local?/0`, `choose_from_nodes/3`

---

## RpcLoadBalancer.Retry

Retry logic for RPC operations that may fail when no nodes are available. Used internally by `call_on_random_node/5` and `cast_on_random_node/5`.

#### `with_retry(opts \\ [], fun)`

Calls `fun` repeatedly when it returns `:retry`, up to `:retry_count` times with `:retry_sleep` between attempts.

**Options:**
- `:retry?` — enable retrying (default: from config)
- `:retry_count` — max retries (default: from config)
- `:retry_sleep` — sleep between retries in milliseconds (default: `5_000`)

---

## RpcLoadBalancer.LoadBalancer.Drainer

Tracks in-flight RPC calls and provides graceful connection draining. Uses atomic counters to track the number of active calls per load balancer. During shutdown, the GenServer leaves its `:pg` group and calls `drain/2` to wait for existing calls to complete before the process terminates.

#### `track_call(load_balancer_name)`

Increments the in-flight counter.

#### `release_call(load_balancer_name)`

Decrements the in-flight counter.

#### `in_flight_count(load_balancer_name)`

Returns the current number of in-flight calls.

#### `drain(load_balancer_name, timeout \\ 15_000)`

Blocks until all in-flight calls complete or the timeout expires. Returns `:ok` or `{:error, :timeout}`.

---

## Internal Modules

These modules are not part of the public API but are documented here for contributors.

### `RpcLoadBalancer.LoadBalancer.Pg`

Starts and wraps the `:pg` scope (`:rpc_load_balancer`). Started as a child of the application supervisor.

### `RpcLoadBalancer.LoadBalancer.AlgorithmCache`

`PersistentTerm`-backed cache (via `elixir_cache`) that maps `load_balancer_name -> algorithm_module`.

### `RpcLoadBalancer.LoadBalancer.ValueCache`

`PersistentTerm`-backed cache (via `elixir_cache`) used for general-purpose storage (hash ring data, weight maps).

### `RpcLoadBalancer.LoadBalancer.CounterCache`

Atomic counter cache (via `elixir_cache` `Cache.Counter`) used for round robin indices and per-node connection counts.

### `RpcLoadBalancer.LoadBalancer.DrainerCache`

Atomic counter cache (via `elixir_cache` `Cache.Counter`) used for tracking in-flight calls per load balancer.