Thread code and raw_message through leader-change connect rewrap

A leader-change OperationalError(code=10250 / 10506, raw_message=...)
that the OPEN step of DqliteConnection.connect() catches was rewrapped
into a bare DqliteConnectionError, dropping both code and raw_message.
The dbapi's connect-path classifier comment advertises preservation of
the server-supplied code "matching the query path" — but the
OperationalError arm was unreachable for leader-change codes because
the client's connect() rewrap got there first. SA's is_disconnect
code-based classifier could only fall back to the substring branch
(works today, breaks on a future message rewording), and forensic
consumers had to walk __cause__ to recover the verbatim server text.

Extend DqliteConnectionError.__init__ with optional keyword-only
``code`` and ``raw_message`` (defaulting None for backwards-compat),
thread both through the leader-change rewrap, and propagate them on
the dbapi side via the DqliteConnectionError catch arm in
_build_and_connect. Pin the new shape and the no-arg / message-only
backwards-compat construction.

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

Author: antoineleclair

src/dqliteclient/connection.py

@@ -1118,9 +1118,19 @@ async def _connect_impl(self) -> None:
             if e.code in LEADER_ERROR_CODES:
                 # Leader-change errors during OPEN are transport-level
                 # problems — the caller needs to reconnect elsewhere, not
-                # treat this as a SQL error.
+                # treat this as a SQL error. Thread ``code`` and
+                # ``raw_message`` through the rewrap so the dbapi /
+                # SA-dialect classifiers see the same code-bearing
+                # signal they would on the query path: without this
+                # the leader-change SQLITE_IOERR_NOT_LEADER /
+                # SQLITE_IOERR_LEADERSHIP_LOST code is dropped on the
+                # floor and SA's is_disconnect can only fall back to
+                # the substring branch (which works today but would
+                # break on a future message rewording).
                 raise DqliteConnectionError(
-                    f"Node {self._address} is no longer leader: {e.message}"
+                    f"Node {self._address} is no longer leader: {e.message}",
+                    code=e.code,
+                    raw_message=e.raw_message,
                 ) from e
             raise
         except BaseException:

src/dqliteclient/exceptions.py

@@ -21,7 +21,31 @@ class DqliteError(Exception):
 
 
 class DqliteConnectionError(DqliteError):
-    """Error establishing or maintaining connection."""
+    """Error establishing or maintaining connection.
+
+    Optionally carries ``code`` and ``raw_message`` so the verbatim
+    server-supplied diagnostic survives a connect-path rewrap of an
+    upstream ``OperationalError`` (e.g. the ``LEADER_ERROR_CODES``
+    branch in ``DqliteConnection.connect()``). Both attributes are
+    ``None`` for the canonical TCP / handshake / cluster-level
+    failures; callers that want the verbatim server text fall back to
+    ``str(exc)`` when ``raw_message`` is None — matching the dbapi-
+    side ``getattr(e, "raw_message", None) or str(e)`` idiom.
+    """
+
+    code: int | None
+    raw_message: str | None
+
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        code: int | None = None,
+        raw_message: str | None = None,
+    ) -> None:
+        self.code = code
+        self.raw_message = raw_message
+        super().__init__(message)
 
 
 class ProtocolError(DqliteError, _WireProtocolError):

tests/test_dqlite_connection_error_carries_leader_code.py

@@ -0,0 +1,50 @@
+"""Pin: ``DqliteConnectionError`` accepts and preserves ``code`` and
+``raw_message`` so a leader-change rewrap on the connect path
+surfaces the wire-level signal that downstream classifiers expect.
+
+When ``DqliteConnection.connect()`` catches a leader-change
+``OperationalError(code=10250 / 10506, raw_message=...)`` from the
+OPEN step, it rewraps the failure into ``DqliteConnectionError`` so
+the dbapi-side classifier maps it to a transport-class error rather
+than a SQL error. Without threading ``code`` and ``raw_message``
+through the rewrap, both fields are dropped on the floor — SA's
+``is_disconnect`` code-based branch can never fire on the connect
+path, and any forensic reader who wants the verbatim server text
+has to walk ``__cause__``.
+"""
+
+from __future__ import annotations
+
+from dqliteclient.exceptions import DqliteConnectionError, DqliteError
+
+
+def test_dqlite_connection_error_default_construction_works() -> None:
+    """Backwards-compat: positional message still constructs an
+    instance with code=None / raw_message=None."""
+    e = DqliteConnectionError("Connection refused")
+    assert str(e) == "Connection refused"
+    assert e.code is None
+    assert e.raw_message is None
+
+
+def test_dqlite_connection_error_carries_code_and_raw_message() -> None:
+    """A leader-change rewrap threads the wire-level diagnostic."""
+    e = DqliteConnectionError(
+        "Node leader-a:9001 is no longer leader: not leader",
+        code=10250,
+        raw_message="not leader",
+    )
+    assert e.code == 10250
+    assert e.raw_message == "not leader"
+
+
+def test_dqlite_connection_error_is_dqlite_error_subclass() -> None:
+    """Defence pin against re-parenting."""
+    assert issubclass(DqliteConnectionError, DqliteError)
+
+
+def test_no_args_construction_works() -> None:
+    """Some call sites raise with no message."""
+    e = DqliteConnectionError()
+    assert e.code is None
+    assert e.raw_message is None