Add max_blob_size caller hook to encode_blob / decode_blob

The 16 MiB ``_MAX_BLOB_SIZE`` was a module-level constant with no
override path. A deployment with a larger
``raft.log.entry_size_max`` (rare but legitimate) had no way to
read or write blobs above the cap short of monkey-patching the
module. Add an optional ``max_blob_size`` kwarg to both
``encode_blob`` and ``decode_blob``, defaulting to the module
constant so existing callers see no behaviour change. Advanced
callers (mock servers, bespoke decode pipelines) can now raise or
lower the cap explicitly.

End-to-end plumbing through ``decode_value`` /
``decode_params_tuple`` / ``MessageDecoder`` / ``DqliteConnection``
is deferred — adds ~30 call-sites for a feature whose caller demand
is currently zero. The wire-layer hook is the minimum change that
unblocks the "caller cannot override the cap" complaint; future
end-to-end plumbing builds on it without re-litigating the API.

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

Author: antoineleclair

src/dqlitewire/types.py

@@ -309,30 +309,42 @@ def decode_text(
     return text, total_size
 
 
-def encode_blob(value: bytes) -> bytes:
+def encode_blob(value: bytes, *, max_blob_size: int = _MAX_BLOB_SIZE) -> bytes:
     """Encode a blob (length-prefixed binary data, padded to 8-byte boundary).
 
     Format: uint64 length + data + padding
+
+    ``max_blob_size`` is the per-blob cap. Defaults to
+    ``_MAX_BLOB_SIZE`` (16 MiB) — a defense-in-depth ceiling matching
+    the decode-side cap. Callers handling larger BLOBs (per their
+    deployment's actual ``raft.log.entry_size_max``) can raise this
+    explicitly. The outer ``max_message_size`` cap on the codec
+    always wins regardless.
     """
     length = len(value)
-    if length > _MAX_BLOB_SIZE:
-        raise EncodeError(f"Blob length {length} exceeds maximum ({_MAX_BLOB_SIZE})")
+    if length > max_blob_size:
+        raise EncodeError(f"Blob length {length} exceeds maximum ({max_blob_size})")
     padding = pad_to_word(length)
     return encode_uint64(length) + value + (b"\x00" * padding)
 
 
-def decode_blob(data: bytes | memoryview) -> tuple[bytes, int]:
+def decode_blob(
+    data: bytes | memoryview, *, max_blob_size: int = _MAX_BLOB_SIZE
+) -> tuple[bytes, int]:
     """Decode a blob.
 
     Accepts either ``bytes`` or ``memoryview``. Returns the blob data
     (always as ``bytes``) and the number of bytes consumed.
+
+    ``max_blob_size`` mirrors the ``encode_blob`` parameter — see that
+    docstring for the rationale.
     """
     if len(data) < 8:
         raise DecodeError("Not enough data for blob length")
 
     length = decode_uint64(data[:8])
-    if length > _MAX_BLOB_SIZE:
-        raise DecodeError(f"Blob length {length} exceeds maximum ({_MAX_BLOB_SIZE})")
+    if length > max_blob_size:
+        raise DecodeError(f"Blob length {length} exceeds maximum ({max_blob_size})")
     total_size = 8 + length + pad_to_word(length)
 
     if len(data) < total_size:

tests/test_blob_max_size_kwarg.py

@@ -0,0 +1,44 @@
+"""``encode_blob`` and ``decode_blob`` accept an optional
+``max_blob_size`` kwarg so callers handling deployments with larger
+``raft.log.entry_size_max`` can override the defense-in-depth
+default (16 MiB) without monkey-patching the module constant.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from dqlitewire.exceptions import DecodeError, EncodeError
+from dqlitewire.types import _MAX_BLOB_SIZE, decode_blob, encode_blob
+
+
+def test_default_max_blob_size_unchanged() -> None:
+    """Default cap is the module-level ``_MAX_BLOB_SIZE`` so existing
+    callers see no behavior change."""
+    oversize = b"\x00" * (_MAX_BLOB_SIZE + 1)
+    with pytest.raises(EncodeError, match="exceeds maximum"):
+        encode_blob(oversize)
+
+
+def test_caller_can_lower_encode_cap() -> None:
+    """A caller can tighten the cap below the default to reject blobs
+    earlier on a constrained deployment."""
+    with pytest.raises(EncodeError, match="exceeds maximum"):
+        encode_blob(b"\x00" * 100, max_blob_size=99)
+
+
+def test_caller_can_raise_encode_cap() -> None:
+    """A caller with a larger ``raft.log.entry_size_max`` can raise the
+    cap to send blobs above the default 16 MiB."""
+    big = b"\x00" * (_MAX_BLOB_SIZE + 16)
+    encoded = encode_blob(big, max_blob_size=_MAX_BLOB_SIZE * 2)
+    decoded, _ = decode_blob(encoded, max_blob_size=_MAX_BLOB_SIZE * 2)
+    assert decoded == big
+
+
+def test_caller_can_lower_decode_cap() -> None:
+    """A caller decoding from an untrusted peer can tighten the cap to
+    reject anything above their own per-deployment ceiling."""
+    payload = encode_blob(b"\x00" * 100)
+    with pytest.raises(DecodeError, match="exceeds maximum"):
+        decode_blob(payload, max_blob_size=50)