Add Python RUDP socket transport
This commit is contained in:
parent
41bc58a3f6
commit
d8de83b26c
4 changed files with 239 additions and 7 deletions
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
Loading…
Reference in a new issue