From 259ede745fca0e4949086c79cfe85d404c0e5a87 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 16 Jun 2026 06:28:22 +0100 Subject: [PATCH] Add Python RUDP reconnect loop --- docs/cultnet-transport-parity.md | 4 + docs/runtime-parity-scope.md | 6 +- packages/cultcache-py/PARITY.md | 11 ++- .../cultcache-py/src/cultnet_py/__init__.py | 2 + .../cultcache-py/src/cultnet_py/transport.py | 85 +++++++++++++++++++ packages/cultcache-py/tests/test_cultcache.py | 70 +++++++++++++++ 6 files changed, 172 insertions(+), 6 deletions(-) diff --git a/docs/cultnet-transport-parity.md b/docs/cultnet-transport-parity.md index b9fc4336..a52961de 100644 --- a/docs/cultnet-transport-parity.md +++ b/docs/cultnet-transport-parity.md @@ -243,6 +243,10 @@ Current progress: transport schedules the next attempt with the portable policy, opens a fresh caller-provided transport when the controller says it may retry, and resets attempt state when the caller marks the connection established. +- Python now has the same `CultNetRudpReconnectLoop` shape for synchronous + callers: the caller-owned receive loop reports closure, the shared controller + owns retry delay/exhaustion state, and the caller-provided factory opens the + next `CultNetRudpSocketTransportConnection`. - Kotlin now has the same RUDP reconnect-loop shape for JVM/Android callers: the app-owned receive loop reports closure, `CultNetRudpReconnectLoop` schedules retry through `CultNetReconnectController`, and the caller-provided diff --git a/docs/runtime-parity-scope.md b/docs/runtime-parity-scope.md index 037eed46..49df7c81 100644 --- a/docs/runtime-parity-scope.md +++ b/docs/runtime-parity-scope.md @@ -31,7 +31,7 @@ CultMesh. | Runtime | Role | Claimed parity | Not claimed | | --- | --- | --- | --- | | C# | Reference implementation and production game/server substrate | CultCache typed documents and SoA, CultNet schema-v0, LiteNetLib production path, shared transport profiles, shared RUDP socket transport, RUDP reconnect policy/controller, LiteNetLib client reconnect-controller adoption, CultMesh node/session/catalog/stream/simulation surfaces | No need to abandon LiteNetLib before the CultNet adapter fully owns production service adoption | -| Python | Package runtime, local daemon endpoint, raw interop peer, typed state participant | CultCache/CultNet/CultMesh package surface, schema catalogs, shard catalogs/logs, local TCP CultMesh server, session/prediction/simulation fact helpers, authority leases, streams, RUDP codec/session/socket transport, RUDP reconnect policy/controller, schema-v0 MessagePack over RUDP evidence, benchmark evidence against C# cache paths | Universal C# throughput, full C# daemon/server stack, and RUDP as the only public service pipe | +| Python | Package runtime, local daemon endpoint, raw interop peer, typed state participant | CultCache/CultNet/CultMesh package surface, schema catalogs, shard catalogs/logs, local TCP CultMesh server, session/prediction/simulation fact helpers, authority leases, streams, RUDP codec/session/socket transport, RUDP reconnect policy/controller and reconnect-loop helper, schema-v0 MessagePack over RUDP evidence, benchmark evidence against C# cache paths | Universal C# throughput, full C# daemon/server stack, and RUDP as the only public service pipe | | TypeScript | Node/browser-adjacent projection and interop runtime | CultCache parity tests, CultNet schema-v0 peer, transport profiles, TCP-framed transport port, shared RUDP socket transport, RUDP reconnect policy/controller, RUDP reconnect-loop helper, local CultMesh node/catalog/authority/stream ergonomics | Full C# game session/server stack | | Rust | Low-level cache/transport/runtime substrate | CultCache/CultNet interop lane, transport profiles, TCP-framed port, shared RUDP codec/session/socket transport, RUDP reconnect policy/controller, schema-v0 MessagePack over RUDP evidence, small CultMesh facade for peer cards, authority leases, RUDP endpoint parsing, and peer-card RUDP client construction | Full CultMesh game-session/server facade, stream catalog, or production game-session server | | Kotlin | JVM/Android client substrate | Typed MessagePack cache, schema/shard catalogs, authority leases, stream catalog, branded `CultMesh` facade, RUDP client/server sugar, RUDP reconnect policy/controller and reconnect-loop helper, schema-v0 MessagePack over RUDP evidence | C# SoA store, full C# server daemon, or Unity hot-loop memory layout | @@ -63,8 +63,8 @@ CultMesh. - Extend RUDP interop evidence through daemon/socket reconnect loops and the wider schema-message matrix. RUDP profiles now advertise the portable reconnect policy, runtime-local tests prove the shared controller across the - targeted runtimes, and the C# LiteNetLib client plus TypeScript/Kotlin RUDP - reconnect loops use that controller; broader service adoption remains a + targeted runtimes, and the C# LiteNetLib client plus TypeScript/Python/Kotlin + RUDP reconnect loops use that controller; broader service adoption remains a separate claim. - Keep Kotlin ergonomic parity moving with Android/JVM-shaped APIs instead of backfilling C# server responsibilities it should not own. diff --git a/packages/cultcache-py/PARITY.md b/packages/cultcache-py/PARITY.md index 474f79d2..d0c1a9e7 100644 --- a/packages/cultcache-py/PARITY.md +++ b/packages/cultcache-py/PARITY.md @@ -103,7 +103,10 @@ CultCache, CultNet, and CultMesh. It is evidence, not confetti. unreliable sequenced `latest`, unreliable unordered `realtime`, resend pressure, bounded reliable-send backpressure, and the portable `cultnet.reconnect_policy.v0` delay-policy helper plus reconnect controller - advertised through RUDP transport profiles. The TypeScript interop harness proves bidirectional Python/TypeScript RUDP socket exchange, + advertised through RUDP transport profiles. `CultNetRudpReconnectLoop` + consumes that controller for caller-owned RUDP transport factories, matching + the TypeScript/Kotlin reconnect-loop shape without making the socket factory + a hidden global. The TypeScript interop harness proves bidirectional Python/TypeScript RUDP socket exchange, packet-loss recovery, reordering recovery, fragmentation, ping/pong, and disconnect reason propagation through the shared wire language. - Python CultMesh discovery client: @@ -287,8 +290,10 @@ node --test packages\cultnet-ts\dist-test\test\interop\cultnet-interop.test.js service and harness flows, while `docs/cultnet-transport-parity.md` tracks the remaining work to put broader server-side bodies behind the shared transport port instead of cloning LiteNetLib. The reconnect policy/controller primitive - is portable and advertised by RUDP profiles; automatic reconnect use by - Python service bodies is not yet claimed. + is portable and advertised by RUDP profiles, and `CultNetRudpReconnectLoop` + gives Python callers the same RUDP retry-scheduling helper as + TypeScript/Kotlin. Automatic reconnect use by Python service bodies is not + yet claimed. - Python does not implement the full C# daemon/server stack. Its current role is package runtime, raw interop peer, launchable local CultMesh endpoint, local CultMesh session facade, and typed state participant. diff --git a/packages/cultcache-py/src/cultnet_py/__init__.py b/packages/cultcache-py/src/cultnet_py/__init__.py index 34ca6e03..db23a0d6 100644 --- a/packages/cultcache-py/src/cultnet_py/__init__.py +++ b/packages/cultcache-py/src/cultnet_py/__init__.py @@ -74,6 +74,7 @@ from .transport import ( CultNetRudpSession, CultNetRudpSessionOptions, CultNetRudpSocketMode, + CultNetRudpReconnectLoop, CultNetRudpSocketTransportConnection, CultNetRudpSocketTransportOptions, CultNetReconnectPolicy, @@ -144,6 +145,7 @@ __all__ = [ "CultNetRudpSession", "CultNetRudpSessionOptions", "CultNetRudpSocketMode", + "CultNetRudpReconnectLoop", "CultNetRudpSocketTransportConnection", "CultNetRudpSocketTransportOptions", "CultNetReconnectPolicy", diff --git a/packages/cultcache-py/src/cultnet_py/transport.py b/packages/cultcache-py/src/cultnet_py/transport.py index 113b0298..ccfd6549 100644 --- a/packages/cultcache-py/src/cultnet_py/transport.py +++ b/packages/cultcache-py/src/cultnet_py/transport.py @@ -1,7 +1,9 @@ from __future__ import annotations import socket +import threading import time +from collections.abc import Callable from collections import deque from dataclasses import dataclass, field from enum import Enum @@ -115,6 +117,89 @@ class CultNetReconnectController: ) +CultNetRudpReconnectScheduler = Callable[[int, Callable[[], None]], Callable[[], None]] + + +def _default_rudp_reconnect_scheduler(delay_ms: int, callback: Callable[[], None]) -> Callable[[], None]: + timer = threading.Timer(max(0, delay_ms) / 1000.0, callback) + timer.daemon = True + timer.start() + return timer.cancel + + +class CultNetRudpReconnectLoop: + def __init__( + self, + create_transport: Callable[[], CultNetRudpSocketTransportConnection], + *, + reconnect_policy: CultNetReconnectPolicy | None = None, + connect_payload: bytes = b"", + now_ms: Callable[[], int] | None = None, + jitter_ms: Callable[[], int] | None = None, + scheduler: CultNetRudpReconnectScheduler | None = None, + ) -> None: + self.reconnect_controller = CultNetReconnectController(reconnect_policy or create_reconnect_policy()) + self._create_transport = create_transport + self._connect_payload = bytes(connect_payload) + self._now_ms = now_ms or _now_ms + self._jitter_ms = jitter_ms or (lambda: 0) + self._scheduler = scheduler or _default_rudp_reconnect_scheduler + self._cancel_timer: Callable[[], None] | None = None + self._stopped = True + self.transport: CultNetRudpSocketTransportConnection | None = None + + def start(self) -> CultNetRudpSocketTransportConnection: + self._stopped = False + self.reconnect_controller.reset() + return self._open_transport() + + def stop(self) -> None: + self._stopped = True + if self._cancel_timer is not None: + self._cancel_timer() + self._cancel_timer = None + transport = self.transport + self.transport = None + if transport is not None: + transport.close() + self.reconnect_controller.reset() + + def mark_connected(self) -> None: + self.reconnect_controller.reset() + + def handle_closed(self) -> CultNetReconnectDecision | None: + self.transport = None + return self._schedule_reconnect() + + def _open_transport(self) -> CultNetRudpSocketTransportConnection: + transport = self._create_transport() + self.transport = transport + try: + transport.connect(self._connect_payload) + except Exception: + self.transport = None + transport.close() + self._schedule_reconnect() + raise + return transport + + def _schedule_reconnect(self) -> CultNetReconnectDecision | None: + if self._stopped or self._cancel_timer is not None: + return None + + decision = self.reconnect_controller.record_failure(self._now_ms(), self._jitter_ms()) + if not decision.should_retry: + return decision + + def reconnect() -> None: + self._cancel_timer = None + if not self._stopped and self.reconnect_controller.can_attempt(self._now_ms()): + self._open_transport() + + self._cancel_timer = self._scheduler(decision.delay_ms, reconnect) + return decision + + @dataclass(frozen=True) class CultNetTransportFrame: channel_id: str diff --git a/packages/cultcache-py/tests/test_cultcache.py b/packages/cultcache-py/tests/test_cultcache.py index a23273cb..9f9b8d7d 100644 --- a/packages/cultcache-py/tests/test_cultcache.py +++ b/packages/cultcache-py/tests/test_cultcache.py @@ -73,6 +73,7 @@ from cultnet_py import ( CultNetRudpSession, CultNetRudpSessionOptions, CultNetRudpSocketMode, + CultNetRudpReconnectLoop, CultNetRudpSocketTransportConnection, CultNetRudpSocketTransportOptions, TcpFramedTransportConnection, @@ -733,6 +734,75 @@ class CultCacheTests(unittest.TestCase): self.assertFalse(controller.exhausted) self.assertTrue(controller.can_attempt(99_000)) + def test_cultnet_rudp_reconnect_loop_consumes_shared_controller(self) -> None: + class FakeRudpReconnectTransport: + def __init__(self) -> None: + self.connect_calls = 0 + self.close_calls = 0 + self.last_payload: bytes | None = None + + def connect(self, payload: bytes = b"") -> None: + self.connect_calls += 1 + self.last_payload = bytes(payload) + + def close(self) -> None: + self.close_calls += 1 + + now_ms = 10_000 + captured_callback: list[Callable[[], None]] = [] + transports: list[FakeRudpReconnectTransport] = [] + + def create_transport() -> FakeRudpReconnectTransport: + transport = FakeRudpReconnectTransport() + transports.append(transport) + return transport + + def scheduler(delay_ms: int, callback: Callable[[], None]) -> Callable[[], None]: + self.assertEqual(delay_ms, 1_017) + captured_callback[:] = [callback] + + def cancel() -> None: + captured_callback.clear() + + return cancel + + loop = CultNetRudpReconnectLoop( + create_transport, + reconnect_policy=create_reconnect_policy(max_attempts=2), + connect_payload=b"join", + now_ms=lambda: now_ms, + jitter_ms=lambda: 17, + scheduler=scheduler, + ) + + first = loop.start() + self.assertEqual(first.connect_calls, 1) + self.assertEqual(first.last_payload, b"join") + self.assertIs(loop.transport, first) + + decision = loop.handle_closed() + self.assertIsNotNone(decision) + self.assertEqual(decision.attempt, 1) + self.assertTrue(decision.should_retry) + self.assertEqual(decision.delay_ms, 1_017) + self.assertEqual(decision.next_attempt_at_ms, 11_017) + self.assertEqual(loop.reconnect_controller.attempt, 1) + self.assertEqual(loop.reconnect_controller.next_attempt_at_ms, 11_017) + self.assertEqual(len(captured_callback), 1) + + now_ms = 11_017 + captured_callback[0]() + self.assertEqual(len(transports), 2) + self.assertEqual(transports[1].connect_calls, 1) + self.assertIs(loop.transport, transports[1]) + + loop.mark_connected() + self.assertEqual(loop.reconnect_controller.attempt, 0) + + loop.stop() + self.assertEqual(transports[1].close_calls, 1) + self.assertIsNone(loop.transport) + def test_cultnet_rudp_session_handshake_acks_reliable_connect_and_accept_packets(self) -> None: client = CultNetRudpSession( CultNetRudpSessionOptions(connection_id=0x0A0B0C0D, initial_sequence=1, resend_delay_ms=50)