feat(client): validate max_total_rows constructor argument

Add _validate_max_total_rows helper in protocol.py that rejects
non-int, bool, and non-positive values. Apply in DqliteConnection,
ConnectionPool, and DqliteProtocol constructors so typos fail fast
with a clear message instead of surfacing later as obscure
"Query exceeded max_total_rows cap (0)" errors at query time.

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

Author: antoineleclair

src/dqliteclient/connection.py

@@ -14,7 +14,7 @@
     OperationalError,
     ProtocolError,
 )
-from dqliteclient.protocol import DqliteProtocol
+from dqliteclient.protocol import DqliteProtocol, _validate_max_total_rows
 from dqlitewire.exceptions import EncodeError as _WireEncodeError
 
 # dqlite error codes that indicate a leader change (SQLite extended error codes)
@@ -93,7 +93,7 @@ def __init__(
         self._address = address
         self._database = database
         self._timeout = timeout
-        self._max_total_rows = max_total_rows
+        self._max_total_rows = _validate_max_total_rows(max_total_rows)
         self._protocol: DqliteProtocol | None = None
         self._db_id: int | None = None
         self._in_transaction = False

src/dqliteclient/pool.py

@@ -10,6 +10,7 @@
 from dqliteclient.connection import DqliteConnection
 from dqliteclient.exceptions import DqliteConnectionError
 from dqliteclient.node_store import NodeStore
+from dqliteclient.protocol import _validate_max_total_rows
 
 
 def _socket_looks_dead(conn: DqliteConnection) -> bool:
@@ -98,7 +99,7 @@ def __init__(
         self._min_size = min_size
         self._max_size = max_size
         self._timeout = timeout
-        self._max_total_rows = max_total_rows
+        self._max_total_rows = _validate_max_total_rows(max_total_rows)
 
         if cluster is not None:
             self._cluster = cluster

src/dqliteclient/protocol.py

@@ -32,6 +32,21 @@
 _READ_CHUNK_SIZE = 4096
 
 
+def _validate_max_total_rows(value: int | None) -> int | None:
+    """Validate the ``max_total_rows`` constructor argument.
+
+    ``None`` disables the cap. Otherwise the value must be a positive
+    ``int`` (``bool`` is rejected even though it's a subclass of int).
+    """
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"max_total_rows must be int or None, got {type(value).__name__}")
+    if value <= 0:
+        raise ValueError(f"max_total_rows must be > 0 or None, got {value}")
+    return value
+
+
 class DqliteProtocol:
     """Low-level protocol handler for a single dqlite connection."""
 
@@ -53,7 +68,7 @@ def __init__(
         # the per-operation deadline; without a cumulative cap, clients
         # could legitimately allocate hundreds of millions of rows over
         # the full deadline. None disables the cap.
-        self._max_total_rows = max_total_rows
+        self._max_total_rows = _validate_max_total_rows(max_total_rows)
 
     async def handshake(self, client_id: int | None = None) -> int:
         """Perform protocol handshake.

tests/test_max_total_rows_validation.py

@@ -0,0 +1,86 @@
+"""Validation of the ``max_total_rows`` constructor parameter."""
+
+import asyncio
+
+import pytest
+
+from dqliteclient.connection import DqliteConnection
+from dqliteclient.pool import ConnectionPool
+from dqliteclient.protocol import DqliteProtocol, _validate_max_total_rows
+
+
+class TestValidator:
+    def test_none_allowed(self) -> None:
+        assert _validate_max_total_rows(None) is None
+
+    def test_positive_int_allowed(self) -> None:
+        assert _validate_max_total_rows(1) == 1
+        assert _validate_max_total_rows(10_000_000) == 10_000_000
+
+    def test_zero_rejected(self) -> None:
+        with pytest.raises(ValueError, match="max_total_rows must be > 0"):
+            _validate_max_total_rows(0)
+
+    def test_negative_rejected(self) -> None:
+        with pytest.raises(ValueError, match="max_total_rows must be > 0"):
+            _validate_max_total_rows(-1)
+
+    def test_float_rejected(self) -> None:
+        with pytest.raises(TypeError, match="max_total_rows must be int or None"):
+            _validate_max_total_rows(1.5)  # type: ignore[arg-type]
+
+    def test_bool_rejected(self) -> None:
+        # True is technically int, but PEP-489-style APIs rightly reject it.
+        with pytest.raises(TypeError, match="max_total_rows must be int or None"):
+            _validate_max_total_rows(True)  # type: ignore[arg-type]
+
+    def test_string_rejected(self) -> None:
+        with pytest.raises(TypeError, match="max_total_rows must be int or None"):
+            _validate_max_total_rows("100")  # type: ignore[arg-type]
+
+
+class TestConstructorValidation:
+    def test_dqlite_connection_zero_rejected(self) -> None:
+        with pytest.raises(ValueError):
+            DqliteConnection("localhost:19001", max_total_rows=0)
+
+    def test_dqlite_connection_negative_rejected(self) -> None:
+        with pytest.raises(ValueError):
+            DqliteConnection("localhost:19001", max_total_rows=-5)
+
+    def test_dqlite_connection_bool_rejected(self) -> None:
+        with pytest.raises(TypeError):
+            DqliteConnection("localhost:19001", max_total_rows=True)  # type: ignore[arg-type]
+
+    def test_dqlite_connection_none_allowed(self) -> None:
+        conn = DqliteConnection("localhost:19001", max_total_rows=None)
+        assert conn._max_total_rows is None
+
+    def test_pool_zero_rejected(self) -> None:
+        with pytest.raises(ValueError):
+            ConnectionPool(addresses=["localhost:19001"], max_total_rows=0)
+
+    def test_pool_negative_rejected(self) -> None:
+        with pytest.raises(ValueError):
+            ConnectionPool(addresses=["localhost:19001"], max_total_rows=-1)
+
+    @pytest.mark.asyncio
+    async def test_protocol_zero_rejected(self) -> None:
+        reader = asyncio.StreamReader()
+        writer = _DummyWriter()
+        with pytest.raises(ValueError):
+            DqliteProtocol(reader, writer, max_total_rows=0)  # type: ignore[arg-type]
+
+
+class _DummyWriter:
+    def close(self) -> None:
+        pass
+
+    async def wait_closed(self) -> None:
+        pass
+
+    def write(self, data: bytes) -> None:
+        pass
+
+    async def drain(self) -> None:
+        pass