# `Aerospike.Cluster`
[🔗](https://github.com/luisgabrielroldan/aerospike_driver/blob/v0.3.1/lib/aerospike/cluster.ex#L1)

Read-side helpers over published cluster state.

`ready?/1`, routing, retry policy, and active-node helpers read the
cluster's ETS tables directly when the caller passes the cluster atom
or a pid registered under that atom. Transport sockets, tend-cycle state,
and node handles remain implementation details. `warm_up/2` is the one
explicit operator helper this module aggregates over the published
active-node view.

# `cluster`

```elixir
@type cluster() :: atom() | pid()
```

Cluster identity accepted by read-side helpers.

Pass the cluster registration atom used at startup, or the pid of a
process registered under that atom. Unregistered pids raise
`ArgumentError`.

# `node_info`

```elixir
@type node_info() :: %{name: String.t(), host: String.t(), port: :inet.port_number()}
```

Active node metadata returned by `nodes/1`.

The host and port are the direct-connect endpoint captured from the
Tender's current node handle. Unknown handles are represented with an
empty host and port `0`.

# `replica_policy`

```elixir
@type replica_policy() :: :master | :sequence
```

Replica selection policy used by read routing.

`:master` always routes to the partition master. `:sequence` walks the
available replica list using the retry attempt index.

# `route_result`

```elixir
@type route_result() :: {:ok, String.t()} | {:error, :cluster_not_ready | :no_master}
```

Result returned by cluster routing helpers.

Successful routes return the selected node name. `:cluster_not_ready`
means the namespace has no complete partition map yet; `:no_master`
means the map is present but the target partition has no eligible owner.

# `tables`

```elixir
@type tables() :: %{
  owners: atom(),
  node_gens: atom(),
  meta: atom(),
  txn_tracking: atom()
}
```

ETS table names published for one cluster runtime.

These names are derived from the cluster identity and are used by the
read-side helpers to inspect partition ownership, node generation,
runtime metadata, and transaction tracking state.

# `warm_up_node_result`

```elixir
@type warm_up_node_result() :: %{
  host: String.t(),
  port: :inet.port_number() | 0,
  status: :ok | :partial | :error,
  requested: non_neg_integer(),
  warmed: non_neg_integer(),
  error: Aerospike.Error.t() | nil
}
```

Per-node warm-up result returned inside `t:warm_up_result/0`.

`:status` is `:ok`, `:partial`, or `:error`. `:requested` is the capped
per-node target and `:warmed` is the number of successful checkouts.
`:error` is `nil` on full success or the checkout failure returned by
the pool.

# `warm_up_option`

```elixir
@type warm_up_option() ::
  {:count, non_neg_integer()} | {:pool_checkout_timeout, non_neg_integer()}
```

Warm-up option accepted by `warm_up/2`.

  * `:count` — number of connections to check out per active node.
    `0` or omitted means the configured pool size. Values above the
    pool size are capped to the pool size.
  * `:pool_checkout_timeout` — timeout in milliseconds for each
    individual pool checkout. Defaults to `5_000`.

# `warm_up_result`

```elixir
@type warm_up_result() :: %{
  status: :ok | :partial | :error,
  requested_per_node: non_neg_integer(),
  total_requested: non_neg_integer(),
  total_warmed: non_neg_integer(),
  nodes_total: non_neg_integer(),
  nodes_ok: non_neg_integer(),
  nodes_partial: non_neg_integer(),
  nodes_error: non_neg_integer(),
  nodes: %{required(String.t()) => warm_up_node_result()}
}
```

Aggregate warm-up report returned by `warm_up/2`.

The `:nodes` map is keyed by node name and contains one
`t:warm_up_node_result/0` per active node.

# `active_node?`

```elixir
@spec active_node?(cluster(), String.t()) :: boolean()
```

Returns whether `node_name` appears in the published active-node snapshot.

# `active_nodes`

```elixir
@spec active_nodes(cluster()) :: [String.t()]
```

Returns the published active node-name snapshot.

# `node_names`

```elixir
@spec node_names(cluster()) :: [String.t()]
```

Returns the published active node-name snapshot.

# `nodes`

```elixir
@spec nodes(cluster()) :: [node_info()]
```

Returns the published active nodes with their direct-connect host and port.

# `ready?`

```elixir
@spec ready?(cluster()) :: boolean()
```

Returns whether every configured namespace has a complete partition map.

# `retry_policy`

```elixir
@spec retry_policy(cluster()) :: Aerospike.RetryPolicy.t()
```

Returns the cluster-default retry policy published in `meta.:retry_opts`.

# `route_for_read`

```elixir
@spec route_for_read(
  cluster(),
  Aerospike.Key.t(),
  replica_policy(),
  non_neg_integer()
) ::
  route_result()
```

Routes a read for `key` under `policy` and `attempt`.

# `route_for_write`

```elixir
@spec route_for_write(cluster(), Aerospike.Key.t()) :: route_result()
```

Routes a write for `key` to its master node.

# `tables`

```elixir
@spec tables(cluster()) :: tables()
```

Returns the published ETS tables for `cluster`.

# `warm_up`

```elixir
@spec warm_up(cluster(), [warm_up_option()]) ::
  {:ok, warm_up_result()} | {:error, Aerospike.Error.t()}
```

Verifies that the active node pools can serve checkouts through the normal path.

`:count` defaults to the configured pool size for the cluster and is capped
at that size. `:pool_checkout_timeout` controls each checkout attempt.

---

*Consult [api-reference.md](api-reference.md) for complete listing*