Warn on WelcomeResponse heartbeat_timeout=0 instead of silent accept

The WelcomeResponse docstring explicitly calls heartbeat_timeout=0
"semantically ambiguous" / "misconfigured peer or non-conforming
server" — upstream config.c defaults to 15000ms and never emits 0,
so a 0 from the wire indicates a peer bug. But the diagnostic content
lived only in source comments; decode_body silently accepted the
value, so operators running a dqlite cluster with a misconfigured
peer got no signal to investigate.

Emit a single logger.warning at decode time when heartbeat_timeout==0,
naming the upstream default (15000ms) and the downstream consumer
fallback ("falls back to static read_timeout floor"). Aligns with the
in-tree ServersResponse.decode_body unknown_role_policy="warn"
precedent. The permissive-accept contract is preserved — no
DecodeError raised, the docstring's "is accepted (the wire layer does
not enforce a minimum)" framing still holds.

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

Author: antoineleclair

src/dqlitewire/messages/responses.py

@@ -609,6 +609,22 @@ def decode_body(cls, data: bytes, schema: int = 0) -> "WelcomeResponse":
         if len(data) != 8:
             raise DecodeError(f"WelcomeResponse body must be exactly 8 bytes, got {len(data)}")
         heartbeat_timeout = decode_uint64(data)
+        if heartbeat_timeout == 0:
+            # Surface the docstring's "misconfigured peer or non-
+            # conforming server" diagnostic content into the log
+            # stream. Upstream ``config.c`` defaults to 15000 and
+            # never emits 0, so a 0 from the wire indicates a peer
+            # bug; downstream consumers (``trust_server_heartbeat``)
+            # fall back to the static read_timeout floor. Aligns
+            # with the ``ServersResponse.decode_body`` warn-mode
+            # precedent below. The permissive-accept contract is
+            # preserved — no DecodeError raised.
+            logger.warning(
+                "WelcomeResponse: heartbeat_timeout=0 — peer is "
+                "misconfigured or non-conforming (upstream config.c "
+                "defaults to 15000ms and never emits 0); downstream "
+                "consumers fall back to the static read_timeout floor"
+            )
         return cls(heartbeat_timeout)
 
 

tests/test_welcome_response_zero_heartbeat_warning.py

@@ -0,0 +1,63 @@
+"""Pin: ``WelcomeResponse.decode_body`` emits a ``logger.warning``
+when ``heartbeat_timeout == 0``.
+
+The docstring explicitly calls a zero heartbeat "semantically
+ambiguous" / "misconfigured peer or non-conforming server" — that
+diagnostic content used to live only in source comments, so operators
+running a dqlite cluster with a misconfigured peer got no log signal.
+
+The wire layer keeps its permissive-accept contract (the decoder
+still returns the response; no DecodeError raised) but emits a
+single warning that surfaces the docstring's diagnostic content into
+the log stream. Aligns with the in-tree ``ServersResponse.decode_body``
+``unknown_role_policy="warn"`` precedent.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import pytest
+
+from dqlitewire.messages.responses import WelcomeResponse
+from dqlitewire.types import encode_uint64
+
+
+def test_decode_body_zero_heartbeat_emits_warning(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """A zero heartbeat is accepted but produces a single
+    logger.warning at decode time."""
+    body = encode_uint64(0)
+    with caplog.at_level(logging.WARNING, logger="dqlitewire.messages.responses"):
+        resp = WelcomeResponse.decode_body(body)
+    assert resp.heartbeat_timeout == 0
+    # Single warning emitted.
+    warnings = [r for r in caplog.records if r.levelno == logging.WARNING]
+    assert len(warnings) == 1
+    msg = warnings[0].message
+    # Diagnostic content from the docstring surfaces in the log line.
+    assert "heartbeat_timeout=0" in msg or "heartbeat" in msg.lower()
+    assert "15000" in msg or "non-conforming" in msg.lower() or "misconfig" in msg.lower()
+
+
+def test_decode_body_default_heartbeat_no_warning(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """A legitimate heartbeat (e.g. 15000ms upstream default) does
+    NOT trigger the warning."""
+    body = encode_uint64(15000)
+    with caplog.at_level(logging.WARNING, logger="dqlitewire.messages.responses"):
+        resp = WelcomeResponse.decode_body(body)
+    assert resp.heartbeat_timeout == 15000
+    assert not [r for r in caplog.records if r.levelno == logging.WARNING]
+
+
+def test_decode_body_zero_heartbeat_is_still_accepted() -> None:
+    """The warning is observability-only — the decoder still returns
+    a valid WelcomeResponse with heartbeat_timeout=0 (preserves the
+    documented permissive-accept contract)."""
+    body = encode_uint64(0)
+    resp = WelcomeResponse.decode_body(body)
+    assert resp.heartbeat_timeout == 0
+    assert resp.heartbeat_timeout_seconds == 0.0