fix: make ReadBuffer.has_message() total (non-raising)

has_message() is a predicate and must not raise — the documented
`while decoder.has_message(): decode()` pattern required callers to
wrap the check itself in try/except to handle oversized headers.

Move the max_message_size check into read_message() so the error
surfaces at consume time. has_message() now returns True when a
header claims an oversized body, signalling "there is something to
consume; the consume call will tell you whether it's valid."

skip_message() is unchanged — it already handles the oversized path
as the documented recovery mechanism.

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

Author: antoineleclair

src/dqlitewire/buffer.py

@@ -67,7 +67,14 @@ def feed(self, data: bytes) -> None:
         self._data.extend(data)
 
     def has_message(self) -> bool:
-        """Check if a complete message is available."""
+        """Check if a complete message is available.
+
+        This predicate is total: it never raises. An oversized header
+        (claiming a body larger than ``max_message_size``) is reported as
+        ``True`` so that the caller's ``while decoder.has_message(): ...``
+        loop proceeds to the consume call, where the error actually surfaces.
+        The raise lives in ``read_message()`` / ``skip_message()``, not here.
+        """
         available = len(self._data) - self._pos
 
         if available < HEADER_SIZE:
@@ -78,9 +85,8 @@ def has_message(self) -> bool:
         total_size = HEADER_SIZE + (size_words * WORD_SIZE)
 
         if total_size > self._max_message_size:
-            raise DecodeError(
-                f"Message size {total_size} bytes exceeds maximum {self._max_message_size}"
-            )
+            # Report "something to consume" — the consume call will raise.
+            return True
 
         return available >= total_size
 
@@ -104,13 +110,24 @@ def read_message(self) -> bytes | None:
         """Read a complete message from the buffer.
 
         Returns the message data (including header) or None if not enough data.
+        Raises ``DecodeError`` if the next buffered header claims a message
+        larger than ``max_message_size``. Use ``skip_message()`` to recover.
         """
-        if not self.has_message():
+        available = len(self._data) - self._pos
+        if available < HEADER_SIZE:
             return None
 
         size_words = int.from_bytes(self._data[self._pos : self._pos + 4], "little")
         total_size = HEADER_SIZE + (size_words * WORD_SIZE)
 
+        if total_size > self._max_message_size:
+            raise DecodeError(
+                f"Message size {total_size} bytes exceeds maximum {self._max_message_size}"
+            )
+
+        if available < total_size:
+            return None
+
         message = bytes(self._data[self._pos : self._pos + total_size])
         self._pos += total_size
         self._maybe_compact()

tests/test_buffer.py

@@ -142,8 +142,34 @@ def test_clear(self) -> None:
         buf.clear()
         assert buf.available() == 0
 
+    def test_has_message_is_total_on_oversized(self) -> None:
+        """has_message() must not raise — oversized headers surface at consume time.
+
+        Callers using the documented `while decoder.has_message(): decode()` pattern
+        must not have to wrap the check itself in try/except. The raise belongs at
+        read_message() / skip_message() / decode(), not at the predicate.
+        """
+        import struct
+
+        import pytest
+
+        from dqlitewire.exceptions import DecodeError
+
+        buf = ReadBuffer(max_message_size=1024)
+        # Header claiming a huge body: size_words=1000 (8000 bytes > 1024 limit)
+        header = struct.pack("<IBBH", 1000, 0, 0, 0)
+        buf.feed(header)
+
+        # The predicate is total: it returns True to signal "something is there
+        # to consume" and never raises.
+        assert buf.has_message() is True
+
+        # The raise happens at consume time.
+        with pytest.raises(DecodeError, match="exceeds maximum"):
+            buf.read_message()
+
     def test_rejects_oversized_message(self) -> None:
-        """Messages exceeding max size should raise DecodeError."""
+        """Oversized messages surface at read_message(), not has_message()."""
         import struct
 
         import pytest
@@ -154,8 +180,10 @@ def test_rejects_oversized_message(self) -> None:
         # Header claiming a huge body: size_words=1000 (8000 bytes > 1024 limit)
         header = struct.pack("<IBBH", 1000, 0, 0, 0)
         buf.feed(header)
+        # has_message() is non-raising; consume-side surfaces the error.
+        assert buf.has_message() is True
         with pytest.raises(DecodeError, match="exceeds maximum"):
-            buf.has_message()
+            buf.read_message()
 
     def test_skip_message_recovers_from_oversized(self) -> None:
         """After skipping an oversized message, stream should not be corrupted.
@@ -179,9 +207,10 @@ def test_skip_message_recovers_from_oversized(self) -> None:
         # Feed header + first chunk
         buf.feed(oversized_header + b"\xab" * 500)
 
-        # has_message should raise for oversized
+        # has_message() is total; the raise happens on the consume call.
+        assert buf.has_message() is True
         with pytest.raises(DecodeError, match="exceeds maximum"):
-            buf.has_message()
+            buf.read_message()
 
         # skip_message should return False — partial skip
         assert buf.skip_message() is False
@@ -218,8 +247,9 @@ def test_skip_oversized_across_multiple_feeds(self) -> None:
 
         # Feed just the header
         buf.feed(oversized_header)
+        assert buf.has_message() is True
         with pytest.raises(DecodeError, match="exceeds maximum"):
-            buf.has_message()
+            buf.read_message()
         assert buf.skip_message() is False
 
         # Feed capped body in chunks (max_message_size=64, header was 8 bytes,
@@ -251,8 +281,9 @@ def test_is_skipping_property(self) -> None:
         # Feed an oversized header (200 words = 1600 bytes > 64 limit)
         header = struct.pack("<IBBH", 200, 0, 0, 0)
         buf.feed(header)
+        assert buf.has_message() is True
         with pytest.raises(DecodeError):
-            buf.has_message()
+            buf.read_message()
 
         # Partial skip — is_skipping should be True
         assert buf.skip_message() is False
@@ -274,8 +305,9 @@ def test_clear_resets_skip_state(self) -> None:
         buf = ReadBuffer(max_message_size=64)
         header = struct.pack("<IBBH", 200, 0, 0, 0)
         buf.feed(header)
+        assert buf.has_message() is True
         with pytest.raises(DecodeError):
-            buf.has_message()
+            buf.read_message()
         buf.skip_message()
         assert buf.is_skipping is True
 

tests/test_codec.py

@@ -862,9 +862,10 @@ def test_skip_oversized_and_recover(self) -> None:
         # Feed just the oversized header
         decoder.feed(oversized_header)
 
-        # has_message() should raise for oversized
+        # has_message() is total; the raise surfaces from decode() / read_message().
+        assert decoder.has_message() is True
         with pytest.raises(DecodeError, match="exceeds maximum"):
-            decoder.has_message()
+            decoder.decode()
 
         # skip_message() should handle the oversized message
         result = decoder.skip_message()