Add raw_message kwarg to client OperationalError; preserve verbatim server text through dbapi plumbing

The cycle-21 contract said ``raw_message`` is the verbatim
server text — un-truncated, un-suffixed. ``protocol.py``
violated that by composing the peer-address suffix into
the display message BEFORE constructing
``OperationalError``; the constructor then copied the
suffix-contaminated text into ``raw_message``. The dbapi
cursor classifier (which reads ``e.raw_message`` and
plumbs it through to its layer's exceptions) propagated
the contamination verbatim.

Add a keyword-only ``raw_message=`` argument to the
client ``OperationalError.__init__``. When provided, it
is stored verbatim; when omitted, the previous
back-compat behaviour applies (``raw_message`` defaults
to the display ``message``).

Update all 9 ``OperationalError`` raise sites in
``protocol.py`` (8 ``FailureResponse``-driven + the
mid-stream ``_WireServerFailure`` translation) to pass
``raw_message=response.message`` separate from the addr-
suffixed display text. The dbapi-layer plumbing in
``cursor.py:228`` keeps reading ``e.raw_message`` and now
sees clean text.

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

Author: antoineleclair

src/dqliteclient/exceptions.py

@@ -89,9 +89,23 @@ class OperationalError(DqliteError):
     message: str
     raw_message: str
 
-    def __init__(self, code: int, message: str) -> None:
+    def __init__(
+        self,
+        code: int,
+        message: str,
+        *,
+        raw_message: str | None = None,
+    ) -> None:
         self.code = code
-        self.raw_message = message
+        # ``raw_message`` is the verbatim server text (un-truncated,
+        # un-suffixed). Callers compose the display ``message`` with
+        # peer-address suffix / "Failed to connect:" prefix etc. and
+        # pass the unadorned server text as ``raw_message=`` so the
+        # cycle-21 "raw_message is the bytes the server actually sent"
+        # contract is 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
         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
@@ -103,10 +117,12 @@ def __init__(self, code: int, message: str) -> None:
             )
         else:
             self.message = message
-        # Pass ``code`` and the RAW message through as separate args so
-        # ``self.args == (code, raw_message)``; pickle / deepcopy
-        # reconstruct via ``OperationalError(*args)`` and re-run the
-        # truncation, preserving both fields losslessly.
+        # 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)
 
     def __str__(self) -> str:

src/dqliteclient/protocol.py

@@ -296,7 +296,9 @@ async def get_leader(self) -> tuple[int, str]:
         response = await self._read_response()
 
         if isinstance(response, FailureResponse):
-            raise OperationalError(response.code, self._failure_text(response))
+            raise OperationalError(
+                response.code, self._failure_text(response), raw_message=response.message
+            )
 
         if not isinstance(response, LeaderResponse):
             raise ProtocolError(
@@ -317,7 +319,9 @@ async def open_database(self, name: str, flags: int = 0, vfs: str = "") -> int:
         response = await self._read_response()
 
         if isinstance(response, FailureResponse):
-            raise OperationalError(response.code, self._failure_text(response))
+            raise OperationalError(
+                response.code, self._failure_text(response), raw_message=response.message
+            )
 
         if not isinstance(response, DbResponse):
             raise ProtocolError(
@@ -338,7 +342,9 @@ async def prepare(self, db_id: int, sql: str) -> tuple[int, int]:
         response = await self._read_response()
 
         if isinstance(response, FailureResponse):
-            raise OperationalError(response.code, self._failure_text(response))
+            raise OperationalError(
+                response.code, self._failure_text(response), raw_message=response.message
+            )
 
         if not isinstance(response, StmtResponse):
             raise ProtocolError(
@@ -378,7 +384,9 @@ async def finalize(self, db_id: int, stmt_id: int) -> None:
         response = await self._read_response()
 
         if isinstance(response, FailureResponse):
-            raise OperationalError(response.code, self._failure_text(response))
+            raise OperationalError(
+                response.code, self._failure_text(response), raw_message=response.message
+            )
 
         if not isinstance(response, EmptyResponse):
             raise ProtocolError(
@@ -462,7 +470,9 @@ async def interrupt(self, db_id: int) -> None:
             if isinstance(response, ResultResponse):
                 return
             if isinstance(response, FailureResponse):
-                raise OperationalError(response.code, self._failure_text(response))
+                raise OperationalError(
+                    response.code, self._failure_text(response), raw_message=response.message
+                )
             # RowsResponse mid-drain is expected: the server's in-flight
             # continuation may land before the interrupt takes effect.
             # Other message types indicate stream desync.
@@ -510,7 +520,9 @@ async def exec_sql(
         response = await self._read_response()
 
         if isinstance(response, FailureResponse):
-            raise OperationalError(response.code, self._failure_text(response))
+            raise OperationalError(
+                response.code, self._failure_text(response), raw_message=response.message
+            )
 
         if not isinstance(response, ResultResponse):
             raise ProtocolError(
@@ -534,7 +546,9 @@ async def _send_query(
         deadline = self._operation_deadline()
         response = await self._read_response(deadline=deadline)
         if isinstance(response, FailureResponse):
-            raise OperationalError(response.code, self._failure_text(response))
+            raise OperationalError(
+                response.code, self._failure_text(response), raw_message=response.message
+            )
         if not isinstance(response, RowsResponse):
             raise ProtocolError(
                 f"Expected RowsResponse, got {type(response).__name__}{self._addr_suffix()}"
@@ -810,7 +824,9 @@ async def _read_continuation(self, deadline: float | None = None) -> RowsRespons
             # Append the addr suffix so the operator log shows which
             # peer emitted the failure — matching the eight sibling
             # ``raise OperationalError`` sites in this module.
-            raise OperationalError(e.code, f"{e.message}{self._addr_suffix()}") from e
+            raise OperationalError(
+                e.code, f"{e.message}{self._addr_suffix()}", raw_message=e.message
+            ) from e
         except _WireProtocolError as e:
             raise ProtocolError(f"Wire decode failed{self._addr_suffix()}: {e}") from e
 

tests/test_operationalerror_raw_message_clean.py

@@ -0,0 +1,50 @@
+"""Pin: client ``OperationalError`` carries the verbatim
+server text in ``raw_message`` (un-suffixed) — the cycle-21
+contract that the dbapi layer plumbs through to its own
+exceptions.
+
+Pre-fix, ``protocol.py`` composed the addr-suffix into the
+display message before calling ``OperationalError(code,
+suffixed_message)``; the constructor copied the suffix-
+contaminated text into ``raw_message``. The dbapi cursor
+classifier then propagated the contamination verbatim,
+breaking the "raw_message is the bytes the server actually
+sent" invariant.
+"""
+
+from __future__ import annotations
+
+from dqliteclient.exceptions import OperationalError
+
+
+def test_operational_error_raw_message_keyword_preserves_server_text() -> None:
+    """When the constructor is called with an explicit
+    ``raw_message=`` kwarg, the verbatim server text is
+    preserved while the display ``message`` carries the
+    composed addr suffix."""
+    err = OperationalError(
+        5,
+        "database is locked to localhost:9001",
+        raw_message="database is locked",
+    )
+    assert err.message == "database is locked to localhost:9001"
+    assert err.raw_message == "database is locked"
+    assert "to localhost:9001" not in err.raw_message
+
+
+def test_operational_error_default_raw_message_back_compat() -> None:
+    """Old call sites that omit ``raw_message=`` still get the
+    previous behaviour (``raw_message`` defaults to the
+    display ``message``) so external callers do not break."""
+    err = OperationalError(5, "database is locked")
+    assert err.raw_message == "database is locked"
+
+
+def test_operational_error_truncation_preserves_raw_message_full_length() -> None:
+    """Display ``message`` is truncated at
+    ``_MAX_DISPLAY_MESSAGE`` codepoints; ``raw_message``
+    stays un-truncated for forensic / log-aggregator views."""
+    long_text = "x" * 4096
+    err = OperationalError(1, long_text, raw_message=long_text)
+    assert len(err.raw_message) == 4096
+    assert "[truncated," in err.message