Add Python RUDP socket transport

This commit is contained in:
Meta Vens 2026-06-14 23:18:08 +01:00
commit d8de83b26c
4 changed files with 239 additions and 7 deletions

View file

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

View file

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

View file

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

View file

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