cultmesh-py: refuse options that could answer nothing, as Rust does

With one-byte fragments and a reliable queue of 16, even an empty snapshot
can never be queued: every reply vanished while rudp_send_failures
counted, and the peer timed out. Rust refuses such a configuration at
startup in validate_options; Python's __post_init__ accepted it.

__post_init__ now applies Rust's rules to every option the two servers
share, in Rust's order: max_snapshot_bytes, max_snapshot_documents,
rudp_resend_delay_ms, rudp_max_pending_reliable_packets and
rudp_max_fragment_bytes must be greater than zero (the first two when
set; zero was accepted before), max_snapshot_bytes must hold an empty
snapshot response, and an empty snapshot response in fragments of
rudp_max_fragment_bytes, counted rounding up, must fit the lesser of
65535 and the reliable queue. Rust's session, lifetime and payload-budget
rules have no Python option to apply to.

The test measures the empty snapshot the server actually sends, pins each
rule at its boundary, and shows the configuration at the bound does
answer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-09-30 17:41:19 +02:00
commit d04d71e898
2 changed files with 87 additions and 10 deletions

View file

@ -9,6 +9,7 @@ from typing import Any
import msgpack
from cultnet_py import (
CultNetRawSnapshotResponse,
CultNetSimulationObservationHub,
CultNetRudpPacket,
CultNetRudpPacketType,
@ -98,14 +99,38 @@ class CultMeshLocalServer:
return self._rudp_send_failures
def __post_init__(self) -> None:
if self.max_snapshot_documents is not None and self.max_snapshot_documents < 0:
raise ValueError("max_snapshot_documents must be non-negative")
if self.max_snapshot_bytes is not None and self.max_snapshot_bytes < 0:
raise ValueError("max_snapshot_bytes must be non-negative")
if self.rudp_max_fragment_bytes <= 0:
raise ValueError("rudp_max_fragment_bytes must be greater than zero")
# The Rust document server's option rules (validate_options), for each option this
# server shares with it: every limit is greater than zero, and the limits leave room for
# the smallest response the server sends, an empty snapshot. A server that could answer
# nothing is misconfigured.
if self.max_snapshot_bytes is not None and self.max_snapshot_bytes <= 0:
raise ValueError("max_snapshot_bytes must be greater than zero")
if self.max_snapshot_documents is not None and self.max_snapshot_documents <= 0:
raise ValueError("max_snapshot_documents must be greater than zero")
if self.rudp_resend_delay_ms <= 0:
raise ValueError("rudp_resend_delay_ms must be greater than zero")
if self.rudp_max_pending_reliable_packets is not None and self.rudp_max_pending_reliable_packets <= 0:
raise ValueError("rudp_max_pending_reliable_packets must be greater than zero")
if self.rudp_max_fragment_bytes <= 0:
raise ValueError("rudp_max_fragment_bytes must be greater than zero")
empty = _snapshot_response_bytes(
CultNetRawSnapshotResponse(message_id=_SHORTEST_SERVED_MESSAGE_ID, documents=()).to_wire()
)
if self.max_snapshot_bytes is not None and empty > self.max_snapshot_bytes:
raise ValueError("max_snapshot_bytes cannot hold an empty snapshot response")
if -(-empty // self.rudp_max_fragment_bytes) > self._max_rudp_reply_fragments():
raise ValueError(
"rudp_max_fragment_bytes and rudp_max_pending_reliable_packets cannot carry an empty "
"snapshot response"
)
def _max_rudp_reply_fragments(self) -> int:
"""The most fragments one RUDP reply can take: one message's fragment count, and the
peer's reliable queue it must fit into whole."""
return min(
_MAX_FRAGMENTS_PER_MESSAGE,
self.rudp_max_pending_reliable_packets or _MAX_FRAGMENTS_PER_MESSAGE,
)
def start(self) -> "CultMeshLocalServer":
if self._socket is not None:
@ -633,10 +658,7 @@ class CultMeshLocalServer:
limits = f"limit is {self.max_snapshot_bytes}"
if over_rudp:
fragment_count = max(1, -(-response_bytes // self.rudp_max_fragment_bytes))
max_fragment_count = min(
_MAX_FRAGMENTS_PER_MESSAGE,
self.rudp_max_pending_reliable_packets or _MAX_FRAGMENTS_PER_MESSAGE,
)
max_fragment_count = self._max_rudp_reply_fragments()
details |= {"fragmentCount": fragment_count, "maxFragmentCount": max_fragment_count}
fits = fits and fragment_count <= max_fragment_count
limits = (

View file

@ -4585,6 +4585,61 @@ class CultMeshTests(unittest.TestCase):
self.assertEqual(hello_reply["schemaVersion"], "cultnet.hello.v0")
self.assertTrue(alive)
def test_cultmesh_local_server_refuses_options_that_could_answer_nothing(self) -> None:
# The Rust document server's option rules: every limit is greater than zero, and the limits
# leave room for an empty snapshot, the smallest response the server sends. One-byte
# fragments and a queue of 16 could never carry one, so no reply would ever be sent.
node = CultMesh.create_node(runtime_id="mesh-rudp-options")
probe = CultMesh.serve_node(node)
try:
_, empty_payload = self._rudp_exchange(probe, snapshot_request(message_id="").to_wire())
finally:
probe.stop()
empty = len(empty_payload)
self.assertGreater(empty, 16, "fixture: an empty snapshot takes more than 16 one-byte fragments")
self.assertNotEqual(empty % (empty - 1), 0, "fixture: empty - 1 byte fragments leave a remainder")
def refused(**options: Any) -> str:
server = None
try:
with self.assertRaises(ValueError, msg=str(options)) as raised:
server = CultMesh.serve_node(node, **options)
finally:
if server is not None:
server.stop()
return str(raised.exception)
def accepted(**options: Any) -> None:
CultMesh.serve_node(node, **options).stop()
carry = "cannot carry an empty snapshot response"
self.assertIn(carry, refused(rudp_max_fragment_bytes=1, rudp_max_pending_reliable_packets=16))
self.assertIn(carry, refused(rudp_max_fragment_bytes=1, rudp_max_pending_reliable_packets=empty - 1))
accepted(rudp_max_fragment_bytes=1, rudp_max_pending_reliable_packets=empty)
# Fragments are counted rounding up: empty - 1 bytes a fragment takes two.
self.assertIn(carry, refused(rudp_max_fragment_bytes=empty - 1, rudp_max_pending_reliable_packets=1))
accepted(rudp_max_fragment_bytes=empty - 1, rudp_max_pending_reliable_packets=2)
self.assertIn("cannot hold an empty snapshot response", refused(max_snapshot_bytes=empty - 1))
accepted(max_snapshot_bytes=empty)
self.assertIn("greater than zero", refused(max_snapshot_bytes=0))
self.assertIn("greater than zero", refused(max_snapshot_documents=0))
accepted(max_snapshot_documents=1)
self.assertIn("greater than zero", refused(rudp_resend_delay_ms=0))
accepted(rudp_resend_delay_ms=1)
self.assertIn("greater than zero", refused(rudp_max_fragment_bytes=0))
self.assertIn("greater than zero", refused(rudp_max_pending_reliable_packets=0))
# The configuration at the bound does answer: an empty snapshot in one-byte fragments,
# exactly as many as the queue holds.
server = CultMesh.serve_node(node, rudp_max_fragment_bytes=1, rudp_max_pending_reliable_packets=empty)
try:
served, payload = self._rudp_exchange(server, snapshot_request(message_id="").to_wire())
finally:
server.stop()
self.assertEqual(served["documents"], [])
self.assertEqual(len(payload), empty)
self.assertEqual(server.rudp_send_failures, 0)
def test_cultmesh_local_server_returns_errors_for_bad_requests(self) -> None:
document = define_database_entry_type(
"mesh.error_note",