fix: find_leader prefers voter nodes

Standby and spare nodes never return a non-empty leader from the
LEADER request (gateway.c CHECK_LEADER path returns (0, "") for
non-voters). Probing them first wasted RTTs on every find_leader call.
Sort nodes so voters come first; preserve the prior shuffle-within-
voters for load balancing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: antoineleclair

src/dqliteclient/cluster.py

@@ -51,11 +51,13 @@ async def find_leader(self) -> str:
         if not nodes:
             raise ClusterError("No nodes configured")
 
-        # Shuffle so repeated callers don't all stampede the first-listed
-        # node. A stable first probe concentrates leader-discovery load on
-        # one seed and biases toward its (possibly stale) leader view.
+        # Shuffle first so repeated callers don't stampede the same node;
+        # then stable-sort by role so voters come before non-voters.
+        # Standby/spare nodes can never become leader (their LEADER
+        # response is always (0, "")), so probing them first wastes RTTs.
         nodes = list(nodes)
         random.shuffle(nodes)
+        nodes.sort(key=lambda n: 0 if n.role == 0 else 1)
 
         errors: list[str] = []
         last_exc: BaseException | None = None

tests/test_cluster.py

@@ -290,6 +290,45 @@ async def track(address: str) -> str | None:
         counts = Counter(firsts)
         assert len(counts) >= 2, f"find_leader always probed the same node first: {counts}"
 
+    async def test_find_leader_probes_voters_before_non_voters(self) -> None:
+        """Non-voter nodes (standby/spare) cannot become leader; probing them
+        first wastes an RTT. find_leader must prefer voters.
+        """
+        store = MemoryNodeStore()
+        # Seed with a non-voter first, then a voter.
+        await store.set_nodes(
+            [
+                NodeInfo(node_id=2, address="spare:9002", role=2),  # spare
+                NodeInfo(node_id=1, address="standby:9003", role=1),  # standby
+                NodeInfo(node_id=3, address="voter1:9001", role=0),
+                NodeInfo(node_id=4, address="voter2:9004", role=0),
+            ]
+        )
+        client = ClusterClient(store, timeout=0.2)
+
+        order: list[str] = []
+
+        async def track(address: str) -> str | None:
+            order.append(address)
+            return None  # no leader known — keep probing
+
+        from contextlib import suppress
+
+        with (
+            patch.object(client, "_query_leader", side_effect=track),
+            suppress(ClusterError),
+        ):
+            await client.find_leader()
+
+        # Both voters must be probed before the spare.
+        voter_positions = [i for i, a in enumerate(order) if a.startswith("voter")]
+        non_voter_positions = [i for i, a in enumerate(order) if not a.startswith("voter")]
+        assert voter_positions, "no voters were probed"
+        assert non_voter_positions, "test setup broken — no non-voters"
+        assert max(voter_positions) < min(non_voter_positions), (
+            f"voters should be probed first; order={order}"
+        )
+
     async def test_update_nodes(self) -> None:
         store = MemoryNodeStore()
         client = ClusterClient(store)