diff --git a/docs/cultnet-transport-parity.md b/docs/cultnet-transport-parity.md index 4813a83a..d9248f13 100644 --- a/docs/cultnet-transport-parity.md +++ b/docs/cultnet-transport-parity.md @@ -28,7 +28,7 @@ CultNet owns cross-runtime transport semantics: | C# interop peer | TCP stream with 4-byte length-prefixed MessagePack frames | UDP multicast probe/announce | Test harness only | | TypeScript `cultnet-ts` | `CultNetPeer` over any Node `Duplex`, TCP-framed transport, or single-peer RUDP socket transport; interop uses TCP | UDP multicast probe/announce in the interop peer | First UDP socket binding for the shared RUDP reliability owner | | Rust `cultnet-rs` | Interop example uses TCP length-prefixed MessagePack frames; single-peer RUDP socket transport exists in the library | UDP multicast probe/announce | UDP socket binding for the shared RUDP reliability owner | -| Python `cultcache-py` | TCP sockets with 4-byte length-prefixed MessagePack frames for local CultMesh/CultNet server and client | Endpoint lists and CultMesh peer/Verse catalogs | Local framed service body plus socket-free RUDP reliability owner; no UDP socket binding yet | +| Python `cultcache-py` | TCP sockets with 4-byte length-prefixed MessagePack frames for local CultMesh/CultNet server and client; single-peer RUDP socket transport exists in the library | Endpoint lists and CultMesh peer/Verse catalogs | UDP socket binding for the shared RUDP reliability owner | | Kotlin `cultmesh-kotlin` | Minimal WebSocket-like lane over TCP socket | None found in the live package | Thin client surface | The live split is therefore: payload language is converging, transport language @@ -165,15 +165,16 @@ Current progress: ack/ack-mask accounting, reliable resend scheduling, duplicate suppression, and reliable ordered channel delivery. It is in-memory and socket-free so the behavior can be tested before any runtime binds it to UDP I/O. -- TypeScript and Rust now have socket-backed RUDP transport connections that - bind a single UDP peer to the shared RUDP session. TypeScript emits the same - `frame` events as the TCP-framed transport and can carry `CultNetPeer` schema - messages over reliable ordered `schema` frames; Rust exposes the same - transport frame/stats shape through synchronous socket polling. +- TypeScript, Rust, and Python now have socket-backed RUDP transport + connections that bind a single UDP peer to the shared RUDP session. TypeScript + emits the same `frame` events as the TCP-framed transport and can carry + `CultNetPeer` schema messages over reliable ordered `schema` frames; Rust and + Python expose the same transport frame/stats shape through synchronous socket + polling. - The remaining parity work is to add the equivalent port to Kotlin, deepen Python's server-side use of its port, and move each runtime's existing TCP/LiteNetLib/WebSocket bodies behind those ports, then bind the shared RUDP - reliability state machine to UDP sockets in C# and Python. + reliability state machine to UDP sockets in C#. ## RUDP Packet Contract V0 diff --git a/packages/cultcache-py/src/cultnet_py/__init__.py b/packages/cultcache-py/src/cultnet_py/__init__.py index e96f50da..1eb467d6 100644 --- a/packages/cultcache-py/src/cultnet_py/__init__.py +++ b/packages/cultcache-py/src/cultnet_py/__init__.py @@ -73,6 +73,9 @@ from .transport import ( CultNetRudpSendOptions, CultNetRudpSession, CultNetRudpSessionOptions, + CultNetRudpSocketMode, + CultNetRudpSocketTransportConnection, + CultNetRudpSocketTransportOptions, CultNetTransportFrame, CultNetTransportStats, TcpFramedTransportConnection, @@ -135,6 +138,9 @@ __all__ = [ "CultNetRudpSendOptions", "CultNetRudpSession", "CultNetRudpSessionOptions", + "CultNetRudpSocketMode", + "CultNetRudpSocketTransportConnection", + "CultNetRudpSocketTransportOptions", "CultNetTransportFrame", "CultNetTransportStats", "TcpFramedTransportConnection", diff --git a/packages/cultcache-py/src/cultnet_py/transport.py b/packages/cultcache-py/src/cultnet_py/transport.py index 2c77176b..18240b69 100644 --- a/packages/cultcache-py/src/cultnet_py/transport.py +++ b/packages/cultcache-py/src/cultnet_py/transport.py @@ -1,5 +1,8 @@ from __future__ import annotations +import socket +import time +from collections import deque from dataclasses import dataclass, field from enum import Enum from typing import Any, BinaryIO @@ -118,6 +121,25 @@ class CultNetRudpSendOptions: now_ms: int = 0 +class CultNetRudpSocketMode(str, Enum): + CLIENT = "client" + SERVER = "server" + + +@dataclass(frozen=True) +class CultNetRudpSocketTransportOptions: + runtime_id: str + socket: socket.socket + mode: CultNetRudpSocketMode + connection_id: int + remote_addr: tuple[str, int] | None = None + initial_sequence: int = 1 + resend_delay_ms: int = 250 + transport_id: str = "rudp" + max_payload_bytes: int | None = None + max_fragment_bytes: int | None = None + + @dataclass class _PendingReliablePacket: packet: CultNetRudpPacket @@ -403,6 +425,116 @@ class CultNetRudpSession: ) +class CultNetRudpSocketTransportConnection: + def __init__(self, options: CultNetRudpSocketTransportOptions) -> None: + self.socket = options.socket + self.mode = CultNetRudpSocketMode(options.mode) + self.remote_addr = options.remote_addr + self.session = CultNetRudpSession( + CultNetRudpSessionOptions( + connection_id=options.connection_id, + initial_sequence=options.initial_sequence, + resend_delay_ms=options.resend_delay_ms, + ) + ) + host, port = self.socket.getsockname()[:2] + self.profile = create_rudp_transport_profile( + options.runtime_id, + transport_id=options.transport_id, + host=host, + port=port, + max_payload_bytes=options.max_payload_bytes, + max_fragment_bytes=options.max_fragment_bytes, + ) + self._bytes_received = 0 + self._bytes_sent = 0 + self._frames_received = 0 + self._frames_sent = 0 + self._delivered_frames: deque[CultNetTransportFrame] = deque() + self._closed = False + + @property + def connected(self) -> bool: + return self.session.connected + + @property + def stats(self) -> CultNetTransportStats: + return CultNetTransportStats( + bytes_received=self._bytes_received, + bytes_sent=self._bytes_sent, + frames_received=self._frames_received, + frames_sent=self._frames_sent, + ) + + def connect(self, payload: bytes = b"") -> None: + if self.mode != CultNetRudpSocketMode.CLIENT: + raise ValueError("Only a client RUDP socket transport can initiate connect") + self._send_packet(self.session.create_connect(_now_ms(), payload)) + + def send(self, channel_id: str, payload: bytes) -> None: + packet = self.session.send( + channel_id, + payload, + _channel_send_options(channel_id, _now_ms()), + ) + self._send_packet(packet) + self._frames_sent += 1 + + def receive_once(self) -> CultNetTransportFrame | None: + if self._delivered_frames: + return self._delivered_frames.popleft() + + try: + wire, remote_addr = self.socket.recvfrom(65535) + except TimeoutError: + return None + except BlockingIOError: + return None + self._bytes_received += len(wire) + + if self.remote_addr is None: + self.remote_addr = remote_addr + elif remote_addr != self.remote_addr: + return None + + packet = decode_rudp_packet(wire) + if self.mode == CultNetRudpSocketMode.SERVER and packet.packet_type == CultNetRudpPacketType.CONNECT: + self._send_packet(self.session.accept_connect(packet, _now_ms())) + return None + + result = self.session.receive(packet, _now_ms()) + if result.reply is not None: + self._send_packet(result.reply) + + for frame in result.delivered: + self._delivered_frames.append( + CultNetTransportFrame(channel_id=frame.channel_id, payload=frame.payload) + ) + self._frames_received += 1 + + frame = self._delivered_frames.popleft() if self._delivered_frames else None + if packet.packet_type == CultNetRudpPacketType.ACCEPT or frame is not None: + self._send_packet(self.session.create_ack()) + return frame + + def poll_resends(self) -> None: + for packet in self.session.due_resends(_now_ms()): + self._send_packet(packet) + + def close(self) -> None: + if self._closed: + return + self._closed = True + self.socket.close() + + def _send_packet(self, packet: CultNetRudpPacket) -> None: + if self.remote_addr is None: + raise ValueError("RUDP socket transport does not have a remote endpoint") + wire = encode_rudp_packet(packet) + sent = self.socket.sendto(wire, self.remote_addr) + self._bytes_sent += sent + + def encode_rudp_packet(packet: CultNetRudpPacket) -> bytes: channel_id = packet.channel_id.encode("utf-8") if len(channel_id) > MAX_RUDP_CHANNEL_ID_BYTES: @@ -491,6 +623,18 @@ def _uint16(value: int, field_name: str) -> int: return value +def _channel_send_options(channel_id: str, now_ms: int) -> CultNetRudpSendOptions: + if channel_id == "schema": + return CultNetRudpSendOptions(reliable=True, ordered=True, sequenced=False, now_ms=now_ms) + if channel_id == "latest": + return CultNetRudpSendOptions(reliable=False, ordered=False, sequenced=True, now_ms=now_ms) + return CultNetRudpSendOptions(reliable=False, ordered=False, sequenced=False, now_ms=now_ms) + + +def _now_ms() -> int: + return int(time.time() * 1000) + + class TcpFramedTransportConnection: def __init__(self, stream: BinaryIO, *, profile: dict[str, Any]) -> None: self.stream = stream diff --git a/packages/cultcache-py/tests/test_cultcache.py b/packages/cultcache-py/tests/test_cultcache.py index c13660dc..00dd95c8 100644 --- a/packages/cultcache-py/tests/test_cultcache.py +++ b/packages/cultcache-py/tests/test_cultcache.py @@ -72,6 +72,9 @@ from cultnet_py import ( CultNetRudpSendOptions, CultNetRudpSession, CultNetRudpSessionOptions, + CultNetRudpSocketMode, + CultNetRudpSocketTransportConnection, + CultNetRudpSocketTransportOptions, TcpFramedTransportConnection, CultNetWitnessArtifactBundle, apply_raw_document_record, @@ -138,6 +141,36 @@ from cultmesh_py import ( ) +def bind_udp_socket() -> socket.socket: + sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) + sock.bind(("127.0.0.1", 0)) + sock.settimeout(0.02) + return sock + + +def pump_rudp_handshake( + client: CultNetRudpSocketTransportConnection, + server: CultNetRudpSocketTransportConnection, +) -> None: + for _ in range(20): + server.receive_once() + client.receive_once() + server.receive_once() + if client.connected and server.connected: + return + time.sleep(0.005) + raise AssertionError("RUDP socket handshake did not complete") + + +def receive_rudp_frame(transport: CultNetRudpSocketTransportConnection): + for _ in range(20): + frame = transport.receive_once() + if frame is not None: + return frame + time.sleep(0.005) + raise AssertionError("RUDP socket frame was not delivered") + + @dataclass class Item: name: str @@ -764,6 +797,54 @@ class CultCacheTests(unittest.TestCase): ["second", "third"], ) + def test_cultnet_rudp_socket_transport_handshakes_and_carries_reliable_ordered_schema_frames(self) -> None: + server_socket = bind_udp_socket() + client_socket = bind_udp_socket() + connection_id = 0x10203040 + server = CultNetRudpSocketTransportConnection( + CultNetRudpSocketTransportOptions( + runtime_id="python-rudp-server", + socket=server_socket, + mode=CultNetRudpSocketMode.SERVER, + connection_id=connection_id, + initial_sequence=100, + resend_delay_ms=25, + ) + ) + client = CultNetRudpSocketTransportConnection( + CultNetRudpSocketTransportOptions( + runtime_id="python-rudp-client", + socket=client_socket, + mode=CultNetRudpSocketMode.CLIENT, + remote_addr=server_socket.getsockname(), + connection_id=connection_id, + initial_sequence=1, + resend_delay_ms=25, + ) + ) + + try: + client.connect(b"join") + pump_rudp_handshake(client, server) + self.assertTrue(client.connected) + self.assertTrue(server.connected) + + client.send("schema", b"client-state") + server_frame = receive_rudp_frame(server) + self.assertEqual(server_frame.channel_id, "schema") + self.assertEqual(server_frame.payload, b"client-state") + + server.send("schema", b"server-state") + client_frame = receive_rudp_frame(client) + self.assertEqual(client_frame.channel_id, "schema") + self.assertEqual(client_frame.payload, b"server-state") + self.assertEqual(server.profile["transports"][0]["protocol"], "rudp") + self.assertEqual(client.stats.frames_sent, 1) + self.assertEqual(server.stats.frames_received, 1) + finally: + client.close() + server.close() + def test_cultnet_database_subscription_helpers_match_schema_v0_shape(self) -> None: subscribe = database_subscribe( message_id="sub-message",