fix: chain invalidation cause into later 'Not connected' errors

After _run_protocol invalidated, the next caller's _ensure_connected
raised a bare DqliteConnectionError("Not connected") with no link to
the original failure. Cancel/peer reset/handshake failure/explicit
close all looked identical in logs.

Store the invalidating exception on the connection; surface it as
__cause__ on the subsequent "Not connected" so diagnostics follow the
chain to the original root cause.

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

Author: antoineleclair

src/dqliteclient/connection.py

@@ -94,6 +94,7 @@ def __init__(
         self._bound_loop: asyncio.AbstractEventLoop | None = None
         self._tx_owner: asyncio.Task[Any] | None = None
         self._pool_released = False
+        self._invalidation_cause: BaseException | None = None
 
     @property
     def address(self) -> str:
@@ -173,7 +174,7 @@ async def __aexit__(self, *args: Any) -> None:
     def _ensure_connected(self) -> tuple[DqliteProtocol, int]:
         """Ensure we're connected and return protocol and db_id."""
         if self._protocol is None or self._db_id is None:
-            raise DqliteConnectionError("Not connected")
+            raise DqliteConnectionError("Not connected") from self._invalidation_cause
         return self._protocol, self._db_id
 
     def _check_in_use(self) -> None:
@@ -214,14 +215,20 @@ def _check_in_use(self) -> None:
                     "the pool."
                 )
 
-    def _invalidate(self) -> None:
-        """Mark the connection as broken after an unrecoverable error."""
+    def _invalidate(self, cause: BaseException | None = None) -> None:
+        """Mark the connection as broken after an unrecoverable error.
+
+        If ``cause`` is provided, it is remembered so a later caller that
+        hits "Not connected" can chain it as ``__cause__`` for diagnostics.
+        """
         if self._protocol is not None:
             # Connection may already be broken; suppress close errors
             with contextlib.suppress(Exception):
                 self._protocol.close()
         self._protocol = None
         self._db_id = None
+        if cause is not None:
+            self._invalidation_cause = cause
 
     async def _run_protocol[T](self, fn: Callable[[DqliteProtocol, int], Awaitable[T]]) -> T:
         """Run a protocol operation with standard error handling.
@@ -234,18 +241,18 @@ async def _run_protocol[T](self, fn: Callable[[DqliteProtocol, int], Awaitable[T
         self._in_use = True
         try:
             return await fn(protocol, db_id)
-        except (DqliteConnectionError, ProtocolError):
-            self._invalidate()
+        except (DqliteConnectionError, ProtocolError) as e:
+            self._invalidate(e)
             raise
         except OperationalError as e:
             if e.code in _LEADER_ERROR_CODES:
-                self._invalidate()
+                self._invalidate(e)
             raise
-        except (asyncio.CancelledError, KeyboardInterrupt, SystemExit):
+        except (asyncio.CancelledError, KeyboardInterrupt, SystemExit) as e:
             # Interrupted mid-operation; we don't know how much of the
             # request/response round-trip completed, so the wire state is
             # unsafe to reuse. Invalidate and re-raise.
-            self._invalidate()
+            self._invalidate(e)
             raise
         finally:
             self._in_use = False

tests/test_connection.py

@@ -5,7 +5,7 @@
 import pytest
 
 from dqliteclient.connection import DqliteConnection
-from dqliteclient.exceptions import DqliteConnectionError
+from dqliteclient.exceptions import DqliteConnectionError, OperationalError
 
 
 class TestParseAddress:
@@ -778,6 +778,29 @@ async def raise_client_error(_db, _sql, _params=None):
 
         assert conn.is_connected, "client-side TypeError must not invalidate the connection"
 
+    async def test_not_connected_after_invalidation_chains_cause(
+        self, connected_connection
+    ) -> None:
+        """After invalidation, a subsequent operation's DqliteConnectionError
+        ('Not connected') must chain back to the original cause, so logs on
+        the second-use path still surface why the connection died.
+        """
+        conn, mock_reader, _ = connected_connection
+        from dqlitewire.messages import FailureResponse
+
+        # First call: server returns NOT_LEADER, connection is invalidated.
+        mock_reader.read.side_effect = [FailureResponse(code=10250, message="not leader").encode()]
+        with pytest.raises(OperationalError):
+            await conn.execute("SELECT 1")
+        assert not conn.is_connected
+
+        # Second call: should surface the original cause, not a bare
+        # "Not connected".
+        with pytest.raises(DqliteConnectionError) as exc_info:
+            await conn.execute("SELECT 2")
+        assert exc_info.value.__cause__ is not None
+        assert isinstance(exc_info.value.__cause__, OperationalError)
+
     async def test_cross_event_loop_raises_interface_error(self) -> None:
         """Using a connection from a different event loop must raise InterfaceError."""
         import asyncio