Validate role against NodeRole when decoding ServersResponse

The wire-layer NodeInfo.role was a raw uint64 round-tripped without
validation — a misbehaving or tampered server could plant arbitrary
integers in the cluster-topology response and every downstream caller
had to remember to wrap with NodeRole(...). Tighten the type
annotation to NodeRole and raise DecodeError (chained from
ValueError) at the wire seam when the value is outside
{VOTER, STANDBY, SPARE}.

The error message lists the offending value and the valid set so the
failure is actionable in logs. NodeRole is an IntEnum subclass of int,
so encode output is byte-identical and downstream ``role == 0``
comparisons continue to work.

Three new tests pin the rejection path, the round-trip type, and the
int-equality guarantee.

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

Author: antoineleclair

src/dqlitewire/messages/responses.py

@@ -7,6 +7,7 @@
     ROW_DONE_MARKER,
     ROW_PART_MARKER,
     WORD_SIZE,
+    NodeRole,
     ResponseType,
     ValueType,
 )
@@ -559,7 +560,7 @@ class NodeInfo:
 
     node_id: int
     address: str
-    role: int
+    role: NodeRole
 
 
 @dataclass
@@ -603,8 +604,15 @@ def decode_body(cls, data: bytes, schema: int = 0) -> "ServersResponse":
             offset += 8
             address, consumed = decode_text(view[offset:])
             offset += consumed
-            role = decode_uint64(view[offset:])
+            raw_role = decode_uint64(view[offset:])
             offset += 8
+            try:
+                role = NodeRole(raw_role)
+            except ValueError as exc:
+                valid = sorted(r.value for r in NodeRole)
+                raise DecodeError(
+                    f"Invalid node role {raw_role} at offset {offset - 8}; expected one of {valid}"
+                ) from exc
             nodes.append(NodeInfo(node_id, address, role))
         return cls(nodes)
 

tests/test_messages_responses.py

@@ -1221,6 +1221,53 @@ def test_node_count_exceeds_hard_limit(self) -> None:
         with pytest.raises(DecodeError, match="Node count.*exceeds maximum"):
             ServersResponse.decode_body(body)
 
+    def test_decode_rejects_unknown_role(self) -> None:
+        """An unknown ``role`` value must raise DecodeError at the wire seam.
+
+        Upstream C (``src/roles.c``) only ever emits VOTER/STANDBY/SPARE
+        (0/1/2). A server that sends anything else is either buggy or
+        hostile; either way we refuse to build a NodeInfo with an
+        unvalidated enum value — the failure must surface at the wire
+        boundary, not silently propagate.
+        """
+        import pytest
+
+        from dqlitewire.exceptions import DecodeError
+        from dqlitewire.types import encode_text, encode_uint64
+
+        body = (
+            encode_uint64(1)  # count = 1
+            + encode_uint64(7)  # node_id
+            + encode_text("n1:9001")
+            + encode_uint64(999)  # role = invalid
+        )
+        with pytest.raises(DecodeError, match="Invalid node role 999"):
+            ServersResponse.decode_body(body)
+
+    def test_roundtrip_preserves_noderole_type(self) -> None:
+        """Decoded role must be a NodeRole member, not a bare int."""
+        from dqlitewire.constants import NodeRole
+
+        nodes = [
+            NodeInfo(node_id=1, address="n1:9001", role=NodeRole.VOTER),
+            NodeInfo(node_id=2, address="n2:9002", role=NodeRole.STANDBY),
+        ]
+        encoded = ServersResponse(nodes=nodes).encode()
+        decoded = ServersResponse.decode_body(encoded[HEADER_SIZE:])
+        assert [n.role for n in decoded.nodes] == [NodeRole.VOTER, NodeRole.STANDBY]
+        assert all(isinstance(n.role, NodeRole) for n in decoded.nodes)
+
+    def test_int_equality_survives_enum_typing(self) -> None:
+        """Downstream code compares ``role == 0`` / ``== 1``; IntEnum
+        subclassing of int must keep those comparisons true even after
+        we tightened the type annotation.
+        """
+        from dqlitewire.constants import NodeRole
+
+        info = NodeInfo(node_id=1, address="n1:9001", role=NodeRole.VOTER)
+        assert info.role == 0
+        assert info.role == NodeRole.VOTER
+
 
 class TestMetadataResponse:
     def test_roundtrip(self) -> None: