fix: generate unique client_id per connection by default

handshake() previously defaulted to client_id=0, so every Python client
registered under the same id and the server's per-client logs, traces,
and metrics collapsed them into one. Generate a random non-zero 63-bit
id when the caller does not provide one.

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

Author: antoineleclair

src/dqliteclient/protocol.py

@@ -1,6 +1,7 @@
 """Low-level protocol handler for dqlite."""
 
 import asyncio
+import secrets
 from collections.abc import Sequence
 from typing import Any
 
@@ -42,11 +43,16 @@ def __init__(
         self._heartbeat_timeout = 0
         self._timeout = timeout
 
-    async def handshake(self, client_id: int = 0) -> int:
+    async def handshake(self, client_id: int | None = None) -> int:
         """Perform protocol handshake.
 
-        Returns the heartbeat timeout from server.
+        If ``client_id`` is not provided, a random non-zero 63-bit id is
+        generated so each connection is distinguishable in server logs,
+        traces, and per-client metrics. Returns the heartbeat timeout
+        from the server.
         """
+        if client_id is None:
+            client_id = secrets.randbits(63) or 1
         # Send protocol version + client registration together
         request = ClientRequest(client_id=client_id)
         self._writer.write(MessageEncoder().encode_handshake() + request.encode())

tests/test_protocol.py

@@ -28,6 +28,29 @@ async def test_handshake_success(
 
         assert timeout == 15000
 
+    async def test_handshake_generates_unique_client_id_when_unspecified(
+        self,
+        mock_reader: AsyncMock,
+        mock_writer: MagicMock,
+        welcome_response: bytes,
+    ) -> None:
+        """When no client_id is passed, handshake must generate a unique non-zero id.
+
+        Every connection defaulting to client_id=0 collapses all clients in
+        the server's per-client metrics and tracing. The client must opaquely
+        generate a random id per connection.
+        """
+        mock_reader.read.return_value = welcome_response
+
+        p1 = DqliteProtocol(mock_reader, mock_writer)
+        await p1.handshake()
+        p2 = DqliteProtocol(mock_reader, mock_writer)
+        await p2.handshake()
+
+        assert p1._client_id != 0
+        assert p2._client_id != 0
+        assert p1._client_id != p2._client_id
+
     async def test_handshake_caps_heartbeat_timeout(
         self,
         mock_reader: AsyncMock,