Hoist raw_message to DqliteError base so all subclasses carry it

The cycle-21 invariant — "raw_message is the verbatim server text
preserved through layer wrapping" — was implemented on exactly one
of the eight client exception classes (OperationalError). The dbapi
compensated with ``getattr(e, "raw_message", None) or str(e)`` at
13+ catch arms; the comment at one of those arms documented the
fallback as "older client versions without the attribute" — fictional,
since the current client lacked it on every other class.

Move the attribute to the ``DqliteError`` base, defaulting to
``None``. Every subclass (DqliteConnectionError, ProtocolError,
InterfaceError, ClusterError, ClusterPolicyError, DataError) now
inherits the slot. OperationalError keeps its existing display-
truncation semantics (1 KiB cap on ``message``, unbounded
``raw_message``) and threads ``raw_message=`` to the base. Replace
the dbapi-side fictional comment with the real rationale and use
direct attribute access on the now-guaranteed slot. Pin the
hierarchy contract.

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

Author: antoineleclair

src/dqliteclient/exceptions.py

@@ -17,24 +17,41 @@
 
 
 class DqliteError(Exception):
-    """Base exception for dqlite client errors."""
+    """Base exception for dqlite client errors.
+
+    Carries an optional ``raw_message`` attribute — the verbatim
+    server-supplied diagnostic, un-truncated and un-suffixed — so
+    callers (the dbapi-layer classifier, SA's ``is_disconnect``)
+    can read forensic-grade text without falling back to
+    ``str(e)`` (which can be truncated by display caps or padded
+    by per-class wrap prefixes). Defaults to ``None`` for raises
+    that are purely client-side (no server text in scope).
+
+    The ``OperationalError`` subclass overrides ``__init__`` to keep
+    its existing display-truncation semantics (a 1 KiB cap on the
+    user-facing ``message`` field with the un-truncated text on
+    ``raw_message``); all other subclasses inherit this base
+    constructor unchanged.
+    """
+
+    raw_message: str | None
+
+    def __init__(self, *args: object, raw_message: str | None = None) -> None:
+        super().__init__(*args)
+        self.raw_message = raw_message
 
 
 class DqliteConnectionError(DqliteError):
     """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.
+    Optionally carries ``code`` so the wire-level signal survives a
+    connect-path rewrap of an upstream ``OperationalError`` (e.g. the
+    ``LEADER_ERROR_CODES`` branch in ``DqliteConnection.connect()``).
+    ``raw_message`` (the verbatim server text) is inherited from the
+    ``DqliteError`` base.
     """
 
     code: int | None
-    raw_message: str | None
 
     def __init__(
         self,
@@ -44,8 +61,7 @@ def __init__(
         raw_message: str | None = None,
     ) -> None:
         self.code = code
-        self.raw_message = raw_message
-        super().__init__(message)
+        super().__init__(message, raw_message=raw_message)
 
 
 class ProtocolError(DqliteError, _WireProtocolError):
@@ -129,7 +145,7 @@ def __init__(
         # preserved through the dbapi-layer plumbing. Old call sites
         # that omit the kwarg still get the previous behaviour
         # (``raw_message`` defaults to ``message``).
-        self.raw_message = message if raw_message is None else raw_message
+        resolved_raw_message = message if raw_message is None else raw_message
         if len(message) > self._MAX_DISPLAY_MESSAGE:
             # ``len(message)`` and the slice cap count Python codepoints,
             # not UTF-8 bytes. Match the unit in the marker so an
@@ -143,11 +159,11 @@ def __init__(
             self.message = message
         # Pass ``code`` and the display ``message`` through as separate
         # args so ``self.args == (code, message)``; pickle / deepcopy
-        # reconstruct via ``OperationalError(*args)``. The
-        # ``raw_message`` kwarg is keyword-only and lossy on pickle —
-        # but the dbapi layer is the consumer and reconstructs from
-        # ``e.raw_message`` directly, not from ``args``.
-        super().__init__(code, message)
+        # reconstruct via ``OperationalError(*args)``. Pass
+        # ``raw_message=`` through to the base so the ``DqliteError``
+        # ``raw_message`` slot is set there (keeps a single source of
+        # truth across the hierarchy).
+        super().__init__(code, message, raw_message=resolved_raw_message)
 
     def __str__(self) -> str:
         return f"[{self.code}] {self.message}"

tests/test_dqlite_error_hierarchy_carries_raw_message.py

@@ -0,0 +1,92 @@
+"""Pin: every client exception class carries the ``raw_message``
+attribute (defaulting to ``None``), so the cycle-21 invariant — the
+verbatim server text survives layer wrapping — applies symmetrically
+across the hierarchy and not only to ``OperationalError``.
+
+The dbapi-layer ``getattr(e, "raw_message", None) or str(e)`` idiom
+previously documented its fallback as "older client versions without
+the attribute"; that rationale was a fiction (the current client
+lacked the attribute too). After hoisting ``raw_message`` to the
+``DqliteError`` base, every subclass exposes the attribute as a
+property and downstream consumers can read it without ``getattr``.
+"""
+
+from __future__ import annotations
+
+from dqliteclient.exceptions import (
+    ClusterError,
+    ClusterPolicyError,
+    DataError,
+    DqliteConnectionError,
+    DqliteError,
+    InterfaceError,
+    OperationalError,
+    ProtocolError,
+)
+
+
+def test_base_dqlite_error_has_raw_message_attribute() -> None:
+    e = DqliteError("oops")
+    assert e.raw_message is None
+
+
+def test_base_dqlite_error_accepts_raw_message_kwarg() -> None:
+    e = DqliteError("oops", raw_message="server text")
+    assert e.raw_message == "server text"
+
+
+def test_dqlite_connection_error_inherits_raw_message_from_base() -> None:
+    e = DqliteConnectionError("Connection refused", raw_message="ECONNREFUSED")
+    assert e.raw_message == "ECONNREFUSED"
+
+
+def test_protocol_error_carries_raw_message() -> None:
+    e = ProtocolError("Wire decode failed", raw_message="malformed frame")
+    assert e.raw_message == "malformed frame"
+
+
+def test_interface_error_carries_raw_message() -> None:
+    e = InterfaceError("Connection is closed", raw_message="closed by peer")
+    assert e.raw_message == "closed by peer"
+
+
+def test_cluster_error_carries_raw_message() -> None:
+    e = ClusterError("Could not find leader", raw_message="errors: ...")
+    assert e.raw_message == "errors: ..."
+
+
+def test_cluster_policy_error_carries_raw_message() -> None:
+    e = ClusterPolicyError("rejected", raw_message="policy says no")
+    assert e.raw_message == "policy says no"
+
+
+def test_data_error_carries_raw_message() -> None:
+    e = DataError("encode failed", raw_message="value too large")
+    assert e.raw_message == "value too large"
+
+
+def test_operational_error_keeps_existing_raw_message_truncation_invariant() -> None:
+    """OperationalError still truncates ``message`` for display while
+    keeping the unbounded server text on ``raw_message`` — the
+    original cycle-21 contract is not broken by the hoist."""
+    long = "X" * 5000
+    e = OperationalError(1, long, raw_message=long)
+    assert "[truncated," in e.message
+    assert e.raw_message == long  # untruncated
+
+
+def test_operational_error_default_raw_message_is_message() -> None:
+    """Backwards-compat: if ``raw_message=`` is omitted, OperationalError
+    derives it from ``message`` per the existing contract."""
+    e = OperationalError(1, "boom")
+    assert e.raw_message == "boom"
+
+
+def test_default_raw_message_is_none_for_other_classes() -> None:
+    """Sibling classes default ``raw_message`` to ``None`` (no
+    server text in scope on a purely client-side raise)."""
+    assert DqliteConnectionError("x").raw_message is None
+    assert ProtocolError("x").raw_message is None
+    assert InterfaceError("x").raw_message is None
+    assert ClusterError("x").raw_message is None
+    assert DataError("x").raw_message is None