Prove Rust RUDP interop with TypeScript

This commit is contained in:
Meta Vens 2026-06-15 00:45:48 +01:00
commit ff356aa177
3 changed files with 258 additions and 12 deletions

View file

@ -172,14 +172,14 @@ Current progress:
Rust, Python, and Kotlin expose the same transport frame/stats shape through
synchronous socket polling.
- The TypeScript interop harness now proves bidirectional cross-runtime RUDP
socket exchange with Python: TypeScript can dial a Python UDP peer, Python can
dial a TypeScript UDP peer, and both sides exchange reliable ordered `schema`
frames through the shared handshake and packet language.
socket exchange with Python and Rust: TypeScript can dial those UDP peers,
Python and Rust can dial a TypeScript UDP peer, and all sides exchange
reliable ordered `schema` frames through the shared handshake and packet
language.
- The remaining parity work is to deepen Python's server-side use of its port
and move each runtime's existing TCP/LiteNetLib/WebSocket bodies behind those
ports, then broaden RUDP interop beyond the first TS/Python proof into the
full C#/TS/Rust/Python/Kotlin loss, reordering, fragmentation, reconnect, and
schema-message matrix.
ports, then broaden RUDP interop into the full C#/TS/Rust/Python/Kotlin loss,
reordering, fragmentation, reconnect, and schema-message matrix.
## RUDP Packet Contract V0

View file

@ -11,6 +11,8 @@ use cultnet_rs::CultNetDocumentPutOptions;
use cultnet_rs::CultNetDocumentRegistry;
use cultnet_rs::CultNetMessage;
use cultnet_rs::CultNetMutationAuthority;
use cultnet_rs::CultNetRudpSocketTransportConnection;
use cultnet_rs::CultNetRudpSocketTransportOptions;
use cultnet_rs::CultNetSchemaKind;
use cultnet_rs::CultNetSchemaRegistration;
use cultnet_rs::CultNetSchemaRegistry;
@ -40,6 +42,7 @@ use std::sync::Arc;
use std::sync::Mutex;
use std::thread;
use std::time::Duration;
use std::time::Instant;
const INTEROP_DOCUMENT_TYPE: &str = "cultnet.interop-note";
const INTEROP_SCHEMA_VERSION: &str = "cultnet.interop_note.v0";
@ -202,15 +205,17 @@ struct DialConfig {
fn main() -> Result<()> {
let mut args = std::env::args().skip(1);
let mode = args
.next()
.ok_or_else(|| anyhow!("expected mode: serve | probe | dial"))?;
let mode = args.next().ok_or_else(|| {
anyhow!("expected mode: serve | probe | dial | rudp-serve-once | rudp-dial-once")
})?;
let options = parse_args(args.collect());
match mode.as_str() {
"serve" => serve(parse_peer_config(&options)?)?,
"probe" => probe(&options)?,
"dial" => dial(parse_dial_config(&options)?)?,
"rudp-serve-once" => rudp_serve_once(&options)?,
"rudp-dial-once" => rudp_dial_once(&options)?,
_ => return Err(anyhow!("unknown mode {mode}")),
}
@ -442,6 +447,98 @@ fn dial(config: DialConfig) -> Result<()> {
Ok(())
}
fn rudp_serve_once(options: &BTreeMap<String, String>) -> Result<()> {
let bind_host = options
.get("bind-host")
.cloned()
.unwrap_or_else(|| "127.0.0.1".to_string());
let bind_port = options
.get("bind-port")
.map(|value| value.parse::<u16>())
.transpose()
.with_context(|| "argument --bind-port must be a u16")?
.unwrap_or(0);
let socket = UdpSocket::bind((bind_host.as_str(), bind_port))
.with_context(|| format!("failed to bind RUDP server on {bind_host}:{bind_port}"))?;
socket.set_read_timeout(Some(Duration::from_millis(20)))?;
let local_port = socket.local_addr()?.port();
let mut transport_options =
CultNetRudpSocketTransportOptions::server("rust-rudp-interop", socket, 0x22446688);
transport_options.initial_sequence = 100;
transport_options.resend_delay_ms = 25;
let mut transport = CultNetRudpSocketTransportConnection::new(transport_options)?;
print_json(&serde_json::json!({
"status": "ready",
"port": local_port,
}))?;
let deadline = Instant::now() + Duration::from_secs(5);
while Instant::now() < deadline {
if let Some(frame) = transport.receive_once()? {
if frame.channel_id != "schema" || frame.payload != b"ts-rust-client-state" {
return Err(anyhow!(
"unexpected RUDP frame: channel={} payload={:?}",
frame.channel_id,
frame.payload
));
}
transport.send("schema", b"rust-server-state".to_vec())?;
print_json(&serde_json::json!({ "status": "ok" }))?;
return Ok(());
}
transport.poll_resends()?;
thread::sleep(Duration::from_millis(5));
}
Err(anyhow!("timed out waiting for TypeScript RUDP frame"))
}
fn rudp_dial_once(options: &BTreeMap<String, String>) -> Result<()> {
let target_host = require_arg(options, "target-host")?;
let target_port = parse_u16_arg(options, "target-port")?;
let remote_addr: SocketAddr = format!("{target_host}:{target_port}")
.parse()
.with_context(|| {
format!("failed to parse RUDP remote endpoint {target_host}:{target_port}")
})?;
let socket = UdpSocket::bind(("127.0.0.1", 0))?;
socket.set_read_timeout(Some(Duration::from_millis(20)))?;
let mut transport_options = CultNetRudpSocketTransportOptions::client(
"rust-rudp-client-interop",
socket,
remote_addr,
0x88664422,
);
transport_options.resend_delay_ms = 25;
let mut transport = CultNetRudpSocketTransportConnection::new(transport_options)?;
transport.connect(b"rust-join".to_vec())?;
let mut sent = false;
let deadline = Instant::now() + Duration::from_secs(5);
while Instant::now() < deadline {
if let Some(frame) = transport.receive_once()? {
if frame.channel_id != "schema" || frame.payload != b"ts-rust-server-state" {
return Err(anyhow!(
"unexpected RUDP frame: channel={} payload={:?}",
frame.channel_id,
frame.payload
));
}
print_json(&serde_json::json!({ "status": "ok" }))?;
return Ok(());
}
transport.poll_resends()?;
if transport.connected() && !sent {
transport.send("schema", b"rust-client-state".to_vec())?;
sent = true;
}
thread::sleep(Duration::from_millis(5));
}
Err(anyhow!("timed out waiting for TypeScript RUDP response"))
}
fn mutate_remote_note(
transport: &mut TcpFramedTransportConnection<TcpStream>,
cache: &mut CultCache,

View file

@ -750,15 +750,95 @@ test("CultNet Python and TypeScript exchange schema frames when Python dials a T
}
});
async function buildInteropPeers(): Promise<void> {
await execFileAsync(cargoCommand, ["build", "--quiet", "--example", "cultnet_interop_peer"], {
cwd: cultnetRsRoot,
test("CultNet TypeScript and Rust exchange schema frames over the shared RUDP socket transport", async () => {
await buildRustInteropPeer();
const rustPeer = spawnRustRudpServer();
const clientSocket = await bindUdpSocket();
let client: CultNetRudpSocketTransportConnection | undefined;
try {
const rustPort = await rustPeer.ready;
client = new CultNetRudpSocketTransportConnection({
runtimeId: "ts-rust-rudp-interop",
socket: clientSocket,
mode: "client",
remoteHost: "127.0.0.1",
remotePort: rustPort,
connectionId: 0x22446688,
initialSequence: 1,
resendDelayMs: 25,
resendPollMs: 5,
});
const receivedFrame = once(client, "frame");
client.connect(Buffer.from("ts-rust-join"));
await waitFor(() => client?.connected === true, "TypeScript RUDP client to complete Rust handshake");
client.send("schema", Buffer.from("ts-rust-client-state"));
const [frame] = await withTimeout(receivedFrame, 2_000, "Rust RUDP response frame");
assert.equal(frame.channelId, "schema");
assert.deepEqual(Buffer.from(frame.payload), Buffer.from("rust-server-state"));
const [exitCode] = await withTimeout(once(rustPeer.child, "exit"), 2_000, "Rust RUDP peer exit");
assert.equal(exitCode, 0, rustPeer.stderr.join(""));
} finally {
if (client) {
client.close();
} else {
clientSocket.close();
}
if (rustPeer.child.exitCode === null && !rustPeer.child.killed) {
rustPeer.child.kill("SIGTERM");
await once(rustPeer.child, "exit").catch(() => undefined);
}
}
});
test("CultNet Rust and TypeScript exchange schema frames when Rust dials a TypeScript RUDP server", async () => {
await buildRustInteropPeer();
const serverSocket = await bindUdpSocket();
const server = new CultNetRudpSocketTransportConnection({
runtimeId: "ts-rust-rudp-server-interop",
socket: serverSocket,
mode: "server",
connectionId: 0x88664422,
initialSequence: 100,
resendDelayMs: 25,
resendPollMs: 5,
});
const rustClient = spawnRustRudpClient(udpSocketPort(serverSocket));
try {
const receivedFrame = once(server, "frame");
const [frame] = await withTimeout(receivedFrame, 2_000, "Rust RUDP client frame");
assert.equal(frame.channelId, "schema");
assert.deepEqual(Buffer.from(frame.payload), Buffer.from("rust-client-state"));
server.send("schema", Buffer.from("ts-rust-server-state"));
const [exitCode] = await withTimeout(once(rustClient.child, "exit"), 2_000, "Rust RUDP client exit");
assert.equal(exitCode, 0, rustClient.stderr.join(""));
} finally {
server.close();
if (rustClient.child.exitCode === null && !rustClient.child.killed) {
rustClient.child.kill("SIGTERM");
await once(rustClient.child, "exit").catch(() => undefined);
}
}
});
async function buildInteropPeers(): Promise<void> {
await buildRustInteropPeer();
await execFileAsync(dotnetCommand, ["build", csharpProjectPath, "-nologo"], {
cwd: cultLibRoot,
});
}
async function buildRustInteropPeer(): Promise<void> {
await execFileAsync(cargoCommand, ["build", "--quiet", "--example", "cultnet_interop_peer"], {
cwd: cultnetRsRoot,
});
}
function cleanInteropStores(runtimeIds: readonly string[]): void {
for (const runtimeId of runtimeIds) {
rmSync(join(tmpdir(), `cultnet-rs-interop-${runtimeId}.msgpack`), { force: true });
@ -928,6 +1008,56 @@ function spawnPythonRudpPeer(): RunningPythonRudpPeer {
return { child, ready, stderr };
}
function spawnRustRudpServer(): RunningPythonRudpPeer {
const child = spawn(rustBinaryPath, ["rudp-serve-once", "--bind-host", "127.0.0.1"], {
cwd: cultnetRsRoot,
env: process.env,
stdio: ["ignore", "pipe", "pipe"],
});
const stderr: string[] = [];
let stdoutBuffer = "";
const ready = new Promise<number>((resolveReady, rejectReady) => {
child.stdout.setEncoding("utf8");
child.stdout.on("data", (chunk: string) => {
stdoutBuffer += chunk;
while (true) {
const newline = stdoutBuffer.indexOf("\n");
if (newline === -1) {
break;
}
const line = stdoutBuffer.slice(0, newline).trim();
stdoutBuffer = stdoutBuffer.slice(newline + 1);
if (!line) {
continue;
}
try {
const parsed = JSON.parse(line) as { status?: string; port?: number };
if (parsed.status === "ready" && typeof parsed.port === "number") {
resolveReady(parsed.port);
} else if (parsed.status !== "ok") {
rejectReady(new Error(`Rust RUDP peer emitted unexpected stdout: ${line}`));
}
} catch (error) {
rejectReady(new Error(`Rust RUDP peer emitted non-JSON stdout: ${line}`));
}
}
});
child.stderr.setEncoding("utf8");
child.stderr.on("data", (chunk: string) => {
stderr.push(chunk);
});
child.once("exit", (code, signal) => {
rejectReady(new Error(`Rust RUDP peer exited before publishing a port (code=${code}, signal=${signal}).\n${stderr.join("")}`));
});
child.once("error", rejectReady);
});
return { child, ready, stderr };
}
function spawnPythonRudpClient(remotePort: number): Omit<RunningPythonRudpPeer, "ready"> {
const child = spawn(pythonCommand, ["-c", pythonRudpClientScript, String(remotePort)], {
cwd: cultcachePyRoot,
@ -943,6 +1073,25 @@ function spawnPythonRudpClient(remotePort: number): Omit<RunningPythonRudpPeer,
return { child, stderr };
}
function spawnRustRudpClient(remotePort: number): Omit<RunningPythonRudpPeer, "ready"> {
const child = spawn(rustBinaryPath, [
"rudp-dial-once",
"--target-host", "127.0.0.1",
"--target-port", String(remotePort),
], {
cwd: cultnetRsRoot,
env: process.env,
stdio: ["ignore", "pipe", "pipe"],
});
const stderr: string[] = [];
child.stderr.setEncoding("utf8");
child.stderr.on("data", (chunk: string) => {
stderr.push(chunk);
});
return { child, stderr };
}
async function bindUdpSocket(): Promise<Socket> {
const socket = dgram.createSocket("udp4");
await new Promise<void>((resolveBind, rejectBind) => {