diff --git a/docs/cultnet-transport-parity.md b/docs/cultnet-transport-parity.md index e178419a..6c2c5513 100644 --- a/docs/cultnet-transport-parity.md +++ b/docs/cultnet-transport-parity.md @@ -134,6 +134,18 @@ lets the runtimes stop guessing what kind of pipe a peer is offering. with C#/TS/Rust/Python ping, loss, reordering, fragmentation, reconnect, and schema-message tests. +Current progress: + +- Steps 1-3 are live in C#, TypeScript, Rust, and Python. +- TypeScript has the first narrow transport connection port: + `TcpFramedTransportConnection` owns length-prefixed frame delivery, exposes + frame/close/error events, `send(channel, payload)`, `close`, and transfer + stats, and `CultNetPeer` can now run over either the legacy `Duplex` stream + path or the transport connection path. +- The remaining parity work is to add equivalent ports to C#, Rust, Python, and + Kotlin, then move each runtime's existing TCP/LiteNetLib/WebSocket bodies + behind those ports before implementing `rudp`. + ## Reliable UDP Semantics To Lift From LiteNetLib The portable RUDP contract must cover at least: diff --git a/packages/cultnet-ts/src/index.ts b/packages/cultnet-ts/src/index.ts index 0b2b1700..e1ecf7a5 100644 --- a/packages/cultnet-ts/src/index.ts +++ b/packages/cultnet-ts/src/index.ts @@ -56,6 +56,15 @@ export { } from "./contracts"; export { encodeFrame, LengthPrefixedMessageFramer } from "./framing"; export { CultNetPeer, type CultNetPeerEvents } from "./peer"; +export { + TcpFramedTransportConnection, + createTcpFramedTransportProfile, + type CultNetTransportConnection, + type CultNetTransportConnectionEvents, + type CultNetTransportFrame, + type CultNetTransportStats, + type TcpFramedTransportProfileOptions, +} from "./transport"; export { defineJsonSchemaContract, type JsonSchemaContract, diff --git a/packages/cultnet-ts/src/peer.ts b/packages/cultnet-ts/src/peer.ts index 25b3db53..9f00a516 100644 --- a/packages/cultnet-ts/src/peer.ts +++ b/packages/cultnet-ts/src/peer.ts @@ -5,6 +5,7 @@ import { decode, encode } from "@msgpack/msgpack"; import { encodeCultNetMessageForWire, parseCultNetMessage, type CultNetDocumentDeleteMessage, type CultNetDocumentPutMessage, type CultNetErrorMessage, type CultNetHelloMessage, type CultNetLoginMessage, type CultNetLoginSuccessMessage, type CultNetMessage, type CultNetRegisterMessage, type CultNetSampleChangeNameMessage, type CultNetSampleChatMessage, type CultNetSchemaCatalogRequestMessage, type CultNetSchemaCatalogResponseMessage, type CultNetSnapshotRequestMessage, type CultNetSnapshotResponseMessage, type CultNetVerifyMessage, type CultNetWireContract } from "./contracts"; import { encodeFrame, LengthPrefixedMessageFramer } from "./framing"; +import type { CultNetTransportConnection } from "./transport"; export interface CultNetPeerEvents { message: (message: CultNetMessage) => void; @@ -18,36 +19,45 @@ export interface CultNetPeerOptions { } export class CultNetPeer extends EventEmitter { - readonly #stream: Duplex; - readonly #framer = new LengthPrefixedMessageFramer(); + readonly #stream?: Duplex; + readonly #transport?: CultNetTransportConnection; + readonly #framer?: LengthPrefixedMessageFramer; readonly #wireContract: CultNetWireContract; - constructor(stream: Duplex, options: CultNetPeerOptions) { + constructor(stream: Duplex | CultNetTransportConnection, options: CultNetPeerOptions) { super(); if (!options?.wireContract) { throw new Error("CultNetPeer requires an explicit wireContract."); } - this.#stream = stream; this.#wireContract = options.wireContract; - this.#stream.on("data", (chunk: Buffer) => { - for (const frame of this.#framer.push(chunk)) { - try { - const decoded = decode(frame); - const message = parseCultNetMessage(decoded, this.#wireContract); - this.emit("message", message); - } catch (error) { - this.emit("invalidMessage", error instanceof Error ? error : new Error(String(error))); + if (isCultNetTransportConnection(stream)) { + this.#transport = stream; + this.#transport.on("frame", (frame) => this.#handlePayload(frame.payload)); + this.#transport.on("close", () => this.emit("close")); + this.#transport.on("error", (error) => this.emit("error", error)); + } else { + this.#stream = stream; + this.#framer = new LengthPrefixedMessageFramer(); + this.#stream.on("data", (chunk: Buffer) => { + for (const frame of this.#framer?.push(chunk) ?? []) { + this.#handlePayload(frame); } - } - }); - this.#stream.on("close", () => this.emit("close")); - this.#stream.on("error", (error) => this.emit("error", error instanceof Error ? error : new Error(String(error)))); + }); + this.#stream.on("close", () => this.emit("close")); + this.#stream.on("error", (error) => this.emit("error", error instanceof Error ? error : new Error(String(error)))); + } } send(message: CultNetMessage): void { const wireValue = encodeCultNetMessageForWire(message, this.#wireContract); - this.#stream.write(encodeFrame(encode(wireValue))); + const payload = encode(wireValue); + if (this.#transport) { + this.#transport.send("schema", payload); + return; + } + + this.#stream?.write(encodeFrame(payload)); } sendHello(message: CultNetHelloMessage): void { @@ -107,6 +117,23 @@ export class CultNetPeer extends EventEmitter { } close(): void { - this.#stream.end(); + this.#transport?.close(); + this.#stream?.end(); + } + + #handlePayload(payload: Uint8Array): void { + try { + const decoded = decode(payload); + const message = parseCultNetMessage(decoded, this.#wireContract); + this.emit("message", message); + } catch (error) { + this.emit("invalidMessage", error instanceof Error ? error : new Error(String(error))); + } } } + +function isCultNetTransportConnection(value: Duplex | CultNetTransportConnection): value is CultNetTransportConnection { + return typeof (value as CultNetTransportConnection).send === "function" + && typeof (value as CultNetTransportConnection).close === "function" + && "profile" in value; +} diff --git a/packages/cultnet-ts/src/transport.ts b/packages/cultnet-ts/src/transport.ts new file mode 100644 index 00000000..b00fd507 --- /dev/null +++ b/packages/cultnet-ts/src/transport.ts @@ -0,0 +1,119 @@ +import { EventEmitter } from "node:events"; +import type { Duplex } from "node:stream"; + +import type { CultNetTransportProfile } from "./contracts"; +import { encodeFrame, LengthPrefixedMessageFramer } from "./framing"; + +export interface CultNetTransportFrame { + channelId: string; + payload: Uint8Array; +} + +export interface CultNetTransportStats { + bytesReceived: number; + bytesSent: number; + framesReceived: number; + framesSent: number; +} + +export interface CultNetTransportConnectionEvents { + frame: (frame: CultNetTransportFrame) => void; + close: () => void; + error: (error: Error) => void; +} + +export interface CultNetTransportConnection { + readonly profile: CultNetTransportProfile; + readonly stats: CultNetTransportStats; + send(channelId: string, payload: Uint8Array): void; + close(): void; + on( + eventName: EventName, + listener: CultNetTransportConnectionEvents[EventName], + ): this; +} + +export interface TcpFramedTransportProfileOptions { + transportId?: string; + host?: string; + port?: number; + maxPayloadBytes?: number; + maxFragmentBytes?: number; +} + +export function createTcpFramedTransportProfile( + runtimeId: string, + options: TcpFramedTransportProfileOptions = {}, +): CultNetTransportProfile { + return { + schemaVersion: "cultnet.transport_profile.v0", + runtimeId, + transports: [ + { + transportId: options.transportId ?? "tcp-framed", + protocol: "tcp_framed", + host: options.host, + port: options.port, + wireContracts: ["cultnet.schema.v0"], + channels: [ + { + channelId: "schema", + delivery: "reliable", + ordering: "ordered", + maxPayloadBytes: options.maxPayloadBytes, + maxFragmentBytes: options.maxFragmentBytes, + }, + ], + }, + ], + }; +} + +export class TcpFramedTransportConnection extends EventEmitter implements CultNetTransportConnection { + readonly profile: CultNetTransportProfile; + readonly #stream: Duplex; + readonly #framer = new LengthPrefixedMessageFramer(); + readonly #stats: CultNetTransportStats = { + bytesReceived: 0, + bytesSent: 0, + framesReceived: 0, + framesSent: 0, + }; + + constructor(stream: Duplex, profile: CultNetTransportProfile) { + super(); + this.#stream = stream; + this.profile = profile; + this.#stream.on("data", (chunk: Buffer) => { + this.#stats.bytesReceived += chunk.length; + for (const payload of this.#framer.push(chunk)) { + this.#stats.framesReceived += 1; + this.emit("frame", { + channelId: "schema", + payload, + }); + } + }); + this.#stream.on("close", () => this.emit("close")); + this.#stream.on("error", (error) => this.emit("error", error instanceof Error ? error : new Error(String(error)))); + } + + get stats(): CultNetTransportStats { + return { ...this.#stats }; + } + + send(channelId: string, payload: Uint8Array): void { + if (channelId !== "schema") { + throw new Error(`tcp_framed transport only supports the schema channel, got "${channelId}".`); + } + + const frame = encodeFrame(payload); + this.#stats.bytesSent += frame.length; + this.#stats.framesSent += 1; + this.#stream.write(frame); + } + + close(): void { + this.#stream.end(); + } +} diff --git a/packages/cultnet-ts/test/cultnet.test.ts b/packages/cultnet-ts/test/cultnet.test.ts index b478a17a..f31abe99 100644 --- a/packages/cultnet-ts/test/cultnet.test.ts +++ b/packages/cultnet-ts/test/cultnet.test.ts @@ -19,8 +19,10 @@ import { CultNetSchemaRegistry, CultNetSecret, CultNetServerSecurityOptions, + TcpFramedTransportConnection, cultNetSchemas, cultNetBuiltinSchemaRegistry, + createTcpFramedTransportProfile, defineCultNetDocumentBinding, encodeCultNetMessageForWire, ghostlightAgentStateGeneratedContract, @@ -167,6 +169,55 @@ test("CultNet peer frames and decodes typed messages over a direct pipe", async receiver.close(); }); +test("tcp_framed transport carries raw schema channel payloads with stats", async () => { + const { a, b } = createDuplexPair(); + const left = new TcpFramedTransportConnection(a, createTcpFramedTransportProfile("left")); + const right = new TcpFramedTransportConnection(b, createTcpFramedTransportProfile("right")); + + const frame = await new Promise<{ channelId: string; payload: Uint8Array }>((resolve, reject) => { + right.once("frame", resolve); + right.once("error", reject); + left.send("schema", Buffer.from("payload", "utf8")); + }); + + assert.equal(frame.channelId, "schema"); + assert.equal(Buffer.from(frame.payload).toString("utf8"), "payload"); + assert.equal(left.stats.framesSent, 1); + assert.equal(right.stats.framesReceived, 1); + assert.throws(() => left.send("unreliable", Buffer.alloc(0)), /only supports the schema channel/); + + left.close(); + right.close(); +}); + +test("CultNet peer can speak through a transport connection", async () => { + const { a, b } = createDuplexPair(); + const leftTransport = new TcpFramedTransportConnection(a, createTcpFramedTransportProfile("left")); + const rightTransport = new TcpFramedTransportConnection(b, createTcpFramedTransportProfile("right")); + const sender = new CultNetPeer(leftTransport, { wireContract: "cultnet.schema.v0" }); + const receiver = new CultNetPeer(rightTransport, { wireContract: "cultnet.schema.v0" }); + + const message = await new Promise>((resolve, reject) => { + receiver.once("message", resolve); + receiver.once("invalidMessage", reject); + sender.sendHello({ + schemaVersion: "cultnet.hello.v0", + runtimeId: "transport-sender", + runtimeKind: "node-worker", + }); + }); + + assert.equal(message.schemaVersion, "cultnet.hello.v0"); + if (message.schemaVersion === "cultnet.hello.v0") { + assert.equal(message.runtimeId, "transport-sender"); + } + assert.equal(leftTransport.stats.framesSent, 1); + assert.equal(rightTransport.stats.framesReceived, 1); + + sender.close(); + receiver.close(); +}); + test("CultNet can round-trip gamecult.networking.v0 auth messages through the explicit legacy contract", () => { const message: CultNetLoginMessage = { schemaVersion: "cultnet.login.v0", diff --git a/packages/cultnet-ts/test/interop/cultnet-interop-peer.ts b/packages/cultnet-ts/test/interop/cultnet-interop-peer.ts index 634cd4bf..0d9571cb 100644 --- a/packages/cultnet-ts/test/interop/cultnet-interop-peer.ts +++ b/packages/cultnet-ts/test/interop/cultnet-interop-peer.ts @@ -12,6 +12,7 @@ import { CultNetPeer, CultNetSchemaRegistry, cultNetBuiltinSchemaRegistry, + createTcpFramedTransportProfile, defineCultNetDocumentBinding, type CultNetDocumentBinding, type CultNetDocumentPutRawMessage, @@ -259,28 +260,11 @@ async function handleServerMessage(input: { receiptDocumentTypes: [INTEROP_MUTATION_RECEIPT_DOCUMENT_TYPE, INTEROP_FIRE_RECEIPT_DOCUMENT_TYPE], }], supportedMessageVersions: [INTEROP_SCHEMA_VERSION], - transportProfiles: [ - { - schemaVersion: "cultnet.transport_profile.v0", - runtimeId, - transports: [ - { - transportId: "interop-tcp", - protocol: "tcp_framed", - host: advertiseHost, - port: tcpPort, - wireContracts: [INTEROP_WIRE_CONTRACT], - channels: [ - { - channelId: "schema", - delivery: "reliable", - ordering: "ordered", - }, - ], - }, - ], - }, - ], + transportProfiles: [createTcpFramedTransportProfile(runtimeId, { + transportId: "interop-tcp", + host: advertiseHost, + port: tcpPort, + })], supportsSchemaCatalog: true, }); break; @@ -437,28 +421,11 @@ async function respondToProbe(input: { tcpPort, wireContract: INTEROP_WIRE_CONTRACT, supportedDocumentTypes: [INTEROP_DOCUMENT_TYPE], - transportProfiles: [ - { - schemaVersion: "cultnet.transport_profile.v0", - runtimeId, - transports: [ - { - transportId: "interop-tcp", - protocol: "tcp_framed", - host: advertiseHost, - port: tcpPort, - wireContracts: [INTEROP_WIRE_CONTRACT], - channels: [ - { - channelId: "schema", - delivery: "reliable", - ordering: "ordered", - }, - ], - }, - ], - }, - ], + transportProfiles: [createTcpFramedTransportProfile(runtimeId, { + transportId: "interop-tcp", + host: advertiseHost, + port: tcpPort, + })], supportsSchemaCatalog: true, };