Add Python RUDP reconnect loop

This commit is contained in:
Meta Vens 2026-06-16 06:28:22 +01:00
commit 259ede745f
6 changed files with 172 additions and 6 deletions

View file

@ -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

View file

@ -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.

View file

@ -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.

View file

@ -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",

View file

@ -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

View file

@ -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)