docs(wire): pin Python-only divergences and clarify ClusterRequest V0

Post-audit doc pass. A cross-package audit against upstream dqlite C
(dqlite-upstream/src/) and go-dqlite confirmed no wire-level drift and
no unfounded claims about upstream, but flagged two documentation gaps:

- README had no consolidated list of the Python-specific caps and
  validations that diverge from C/Go (max_rows/max_message_size caps,
  full-8-byte row-marker check, BOOLEAN strict encode, FilesResponse
  alignment, UNIXTIME outbound rejection, StmtResponse short-body
  rejection, ClusterRequest V0 skip). Add a "Deliberate divergences
  from upstream" section listing each item and what it protects
  against.

- ClusterRequest.format=0 rejection said "not supported" which reads
  like upstream removed it. The V0 format is still a valid upstream
  wire format — we just chose not to implement the ServersResponse
  decoder for it. Sharpen the docstring and the error messages to
  make the self-imposed limitation explicit, and update the two
  tests that matched the old wording.

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

Author: antoineleclair

README.md

@@ -44,6 +44,43 @@ socket and decoder.
 
 Based on the [dqlite wire protocol specification](https://canonical.com/dqlite/docs/reference/wire-protocol).
 
+## Deliberate divergences from upstream
+
+This library implements the dqlite wire protocol faithfully but adds a
+handful of defensive guards that the upstream C server and the
+canonical [go-dqlite](https://github.com/canonical/go-dqlite) client do
+not. They protect a Python client running in potentially adversarial
+network contexts and are all opt-out-able.
+
+**Python-specific caps** (not present in C or Go; `None` disables):
+
+- `DEFAULT_MAX_ROWS` (`MessageDecoder(max_rows=...)`, default 1,000,000)
+  — per-query row cap.
+- `DEFAULT_MAX_MESSAGE_SIZE` (`ReadBuffer(max_message_size=...)`, default
+  64 MiB) — envelope cap on a single frame.
+- `_MAX_PARAM_COUNT` (100,000), `_MAX_COLUMN_COUNT` (10,000),
+  `_MAX_FILE_COUNT` (100), `_MAX_NODE_COUNT` (10,000) — internal
+  sanity bounds on decoded tuple / response sizes.
+
+**Stricter-than-Go validations** (match the C server's intent):
+
+- `decode_row_header` requires the full 8-byte marker (C defines
+  `DQLITE_RESPONSE_ROWS_DONE = 0xff..ff` / `_PART = 0xee..ee`;
+  go-dqlite checks only the first byte).
+- `encode_value(value, ValueType.BOOLEAN)` rejects arbitrary ints
+  (accepts only `bool` or exactly `0`/`1`).
+- `FilesResponse.encode_body` rejects non-8-aligned file content (C's
+  `dumpFile` asserts `len % 8 == 0`).
+- `encode_params_tuple` rejects `ValueType.UNIXTIME` outbound (C's
+  `tuple_decoder__next` cannot decode it on the server side).
+- `StmtResponse` rejects a 16-byte body when `schema=1` (C's V1
+  response is 24 bytes).
+
+**Not implemented** (valid upstream formats this library chose to skip):
+
+- `ClusterRequest` `format=0` — V0 response with id+address only. We
+  only decode the V1 variant that includes node role.
+
 ## Development
 
 See [DEVELOPMENT.md](DEVELOPMENT.md) for setup and contribution guidelines.

src/dqlitewire/messages/requests.py

@@ -514,6 +514,12 @@ class ClusterRequest(Message):
     """Request cluster information.
 
     Body: uint64 format
+
+    Note: format=0 (V0: id+address only, no role) IS a valid upstream
+    dqlite wire format. This Python library chooses not to implement it
+    because :class:`ServersResponse` only decodes V1 (id+address+role).
+    Callers that need V0 compatibility should decode :class:`ServersResponse`
+    themselves. Use ``format=1`` for the default path.
     """
 
     MSG_TYPE: ClassVar[int] = RequestType.CLUSTER
@@ -524,9 +530,9 @@ def __post_init__(self) -> None:
         _check_uint64("format", self.format)
         if self.format == 0:
             raise ValueError(
-                "ClusterRequest format=0 (V0) is not supported. "
-                "ServersResponse only decodes V1 format (with node role fields). "
-                "Use format=1."
+                "ClusterRequest format=0 (V0) is valid in upstream dqlite but "
+                "not implemented in this Python library: ServersResponse only "
+                "decodes V1 (with node role fields). Use format=1."
             )
 
     def encode_body(self) -> bytes:
@@ -537,8 +543,9 @@ def decode_body(cls, data: bytes, schema: int = 0) -> "ClusterRequest":
         format_val = decode_uint64(data)
         if format_val == 0:
             raise DecodeError(
-                "ClusterRequest format=0 (V0) is not supported. "
-                "ServersResponse only decodes V1 format (with node role fields)."
+                "ClusterRequest format=0 (V0) is valid in upstream dqlite but "
+                "not implemented in this Python library: ServersResponse only "
+                "decodes V1 (with node role fields)."
             )
         return cls(format_val)
 

tests/test_messages_requests.py

@@ -442,8 +442,8 @@ def test_default_format_is_v1(self) -> None:
         assert msg.format == 1
 
     def test_format_v0_rejected(self) -> None:
-        """120: V0 cluster format not supported by ServersResponse decoder."""
-        with pytest.raises(ValueError, match="format=0.*not supported"):
+        """120: V0 cluster format not implemented by ServersResponse decoder."""
+        with pytest.raises(ValueError, match="format=0.*not implemented"):
             ClusterRequest(format=0)
 
     def test_decode_format_v0_raises_decode_error(self) -> None:
@@ -452,7 +452,7 @@ def test_decode_format_v0_raises_decode_error(self) -> None:
         from dqlitewire.types import encode_uint64
 
         body = encode_uint64(0)  # format=0
-        with pytest.raises(DecodeError, match="format=0.*not supported"):
+        with pytest.raises(DecodeError, match="format=0.*not implemented"):
             ClusterRequest.decode_body(body)