Add TypeScript CultNet transport port
This commit is contained in:
parent
a2bc9aeab4
commit
48d2a0bc0d
6 changed files with 247 additions and 62 deletions
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
}
|
||||
|
|
|
|||
119
packages/cultnet-ts/src/transport.ts
Normal file
119
packages/cultnet-ts/src/transport.ts
Normal file
|
|
@ -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 extends keyof CultNetTransportConnectionEvents>(
|
||||
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();
|
||||
}
|
||||
}
|
||||
|
|
@ -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<ReturnType<typeof parseCultNetMessage>>((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",
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
};
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue