From d04d71e8988bce42f5f0e8049a5d2fc10b24e3c1 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Wed, 30 Sep 2026 17:41:19 +0200 Subject: [PATCH] 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 --- .../cultmesh-py/src/cultmesh_py/server.py | 42 ++++++++++---- packages/cultmesh-py/tests/test_cultmesh.py | 55 +++++++++++++++++++ 2 files changed, 87 insertions(+), 10 deletions(-) diff --git a/packages/cultmesh-py/src/cultmesh_py/server.py b/packages/cultmesh-py/src/cultmesh_py/server.py index daf0ed6c..4165577b 100644 --- a/packages/cultmesh-py/src/cultmesh_py/server.py +++ b/packages/cultmesh-py/src/cultmesh_py/server.py @@ -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 = ( diff --git a/packages/cultmesh-py/tests/test_cultmesh.py b/packages/cultmesh-py/tests/test_cultmesh.py index 29e2b201..52191292 100644 --- a/packages/cultmesh-py/tests/test_cultmesh.py +++ b/packages/cultmesh-py/tests/test_cultmesh.py @@ -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",