@spec build_replica_map([
  {non_neg_integer(), non_neg_integer(), node_addr(), [node_addr()]}
]) :: [
  {non_neg_integer(), [node_addr()]}
]

Builds a replica map: {slot => [{replica_host, replica_port}]} from enriched topology.

@spec build_slot_map([
  {non_neg_integer(), non_neg_integer(), String.t(), non_neg_integer()}
]) :: [
  {non_neg_integer(), {String.t(), non_neg_integer()}}
]

Builds an ETS-friendly list of {slot, {host, port}} entries from parsed slot ranges.

@spec parse_shards(list()) :: [
  {non_neg_integer(), non_neg_integer(), String.t(), non_neg_integer()}
]

Parses the response from CLUSTER SHARDS into the same format as parse_slots/1.

CLUSTER SHARDS returns a list of shard maps:

[%{"slots" => [0, 5460], "nodes" => [%{"ip" => "127.0.0.1", "port" => 7000, "role" => "master", ...}]}]

@spec parse_shards_with_replicas(list()) :: [
  {non_neg_integer(), non_neg_integer(), node_addr(), [node_addr()]}
]

Parses CLUSTER SHARDS with replica info, same format as parse_slots_with_replicas/1.

@spec parse_slots(list()) :: [
  {non_neg_integer(), non_neg_integer(), String.t(), non_neg_integer()}
]

Parses the response from CLUSTER SLOTS into a list of {slot_start, slot_end, primary_host, primary_port} tuples.

@spec parse_slots_with_replicas(list()) :: [
  {non_neg_integer(), non_neg_integer(), node_addr(), [node_addr()]}
]

Parses CLUSTER SLOTS into a richer format that includes replicas. Returns [{slot_start, slot_end, {primary_host, primary_port}, [{replica_host, replica_port}]}]