refactor(node_store): freeze NodeInfo and store nodes as a tuple

- Mark NodeInfo as frozen+slots so callers holding a reference from
  get_nodes() can't accidentally mutate store state, and so instances
  are hashable for set/dict-key dedup.
- Back MemoryNodeStore with a tuple rather than a list; get_nodes()
  can then return it directly (no defensive copy) without exposing
  mutable state. Concurrent get_nodes/set_nodes can never observe a
  torn view: attribute replacement is atomic.
- Widen the NodeStore ABC's get/set signatures to Sequence[NodeInfo]
  so future persistent backends can return tuples, frozensets, etc.
- Update test_node_store.py to match the new contract.

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

Author: antoineleclair

src/dqliteclient/node_store.py

@@ -1,12 +1,18 @@
 """Node store interfaces for cluster discovery."""
 
 from abc import ABC, abstractmethod
+from collections.abc import Sequence
 from dataclasses import dataclass
 
 
-@dataclass
+@dataclass(frozen=True, slots=True)
 class NodeInfo:
-    """Information about a cluster node."""
+    """Information about a cluster node.
+
+    Frozen so callers holding a reference from ``get_nodes()`` can't
+    accidentally mutate store state (and so instances are hashable
+    and usable as set/dict keys for deduplication).
+    """
 
     node_id: int
     address: str
@@ -17,29 +23,37 @@ class NodeStore(ABC):
     """Abstract interface for storing cluster node information."""
 
     @abstractmethod
-    async def get_nodes(self) -> list[NodeInfo]:
+    async def get_nodes(self) -> Sequence[NodeInfo]:
         """Get list of known nodes."""
         ...
 
     @abstractmethod
-    async def set_nodes(self, nodes: list[NodeInfo]) -> None:
+    async def set_nodes(self, nodes: Sequence[NodeInfo]) -> None:
         """Update list of known nodes."""
         ...
 
 
 class MemoryNodeStore(NodeStore):
-    """In-memory node store."""
+    """In-memory node store.
+
+    Backs storage with an immutable tuple so readers can safely be
+    handed a direct reference without defensive copies and so a
+    concurrent ``set_nodes()`` never produces a torn view.
+    """
 
     def __init__(self, initial_addresses: list[str] | None = None) -> None:
-        self._nodes: list[NodeInfo] = []
         if initial_addresses:
-            for i, addr in enumerate(initial_addresses):
-                self._nodes.append(NodeInfo(node_id=i + 1, address=addr, role=0))
-
-    async def get_nodes(self) -> list[NodeInfo]:
+            self._nodes: tuple[NodeInfo, ...] = tuple(
+                NodeInfo(node_id=i + 1, address=addr, role=0)
+                for i, addr in enumerate(initial_addresses)
+            )
+        else:
+            self._nodes = ()
+
+    async def get_nodes(self) -> Sequence[NodeInfo]:
         """Get list of known nodes."""
-        return list(self._nodes)
+        return self._nodes
 
-    async def set_nodes(self, nodes: list[NodeInfo]) -> None:
+    async def set_nodes(self, nodes: Sequence[NodeInfo]) -> None:
         """Update list of known nodes."""
-        self._nodes = list(nodes)
+        self._nodes = tuple(nodes)

tests/test_node_store.py

@@ -1,5 +1,7 @@
 """Tests for node store."""
 
+import pytest
+
 import dqliteclient
 from dqliteclient.node_store import MemoryNodeStore, NodeInfo
 
@@ -8,7 +10,7 @@ class TestMemoryNodeStore:
     async def test_empty_store(self) -> None:
         store = MemoryNodeStore()
         nodes = await store.get_nodes()
-        assert nodes == []
+        assert len(nodes) == 0
 
     async def test_initial_addresses(self) -> None:
         store = MemoryNodeStore(["localhost:9001", "localhost:9002"])
@@ -49,8 +51,29 @@ def test_nodeinfo_exported_from_package(self) -> None:
         assert hasattr(dqliteclient, "NodeInfo")
         assert dqliteclient.NodeInfo is NodeInfo
 
-    async def test_get_nodes_returns_copy(self) -> None:
+    async def test_get_nodes_returns_immutable_sequence(self) -> None:
+        """The store hands out an immutable tuple of frozen NodeInfo.
+
+        A caller therefore cannot corrupt store state by mutating the
+        returned sequence or its elements.
+        """
+        import dataclasses
+
         store = MemoryNodeStore(["localhost:9001"])
-        nodes1 = await store.get_nodes()
-        nodes2 = await store.get_nodes()
-        assert nodes1 is not nodes2
+        nodes = await store.get_nodes()
+        assert isinstance(nodes, tuple)
+        with pytest.raises(dataclasses.FrozenInstanceError):
+            nodes[0].address = "evil"  # type: ignore[misc]
+
+    async def test_node_info_is_frozen(self) -> None:
+        import dataclasses
+
+        info = NodeInfo(node_id=1, address="h:1", role=0)
+        with pytest.raises(dataclasses.FrozenInstanceError):
+            info.address = "other"  # type: ignore[misc]
+
+    async def test_node_info_is_hashable(self) -> None:
+        info1 = NodeInfo(node_id=1, address="h:1", role=0)
+        info2 = NodeInfo(node_id=1, address="h:1", role=0)
+        assert hash(info1) == hash(info2)
+        assert {info1, info2} == {info1}