A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(net): a session can speak protobuf, with the JSON wire kept for debugging
yhhd8f295338e73
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 844c4afa8..fecbab43a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -17,7 +17,8 @@ published separately; it ships inside the editor.### Added- **Optional tools a project switches on, fetched and checked by the engine.** A project names a tool in `project.esproject` (`tools.luban.enabled`); until it does, the engine does not look for it, mention it or download it. Luban, the industry's configuration tool, turns the Excel tables a game's designers keep into JSON and the TypeScript that reads it, with references between tables checked (a site that produces an item that does not exist fails with the table, the record and the field). It is a .NET program, so the engine also fetches the .NET runtime it runs on. When either is missing, `estella tools install luban` shows exactly what it would download (name, version, licence, size, and where from) and asks before it does; `--yes` agrees in advance for CI. Each tool is pinned in `external-tools.manifest.json` to one vendor file, and a release publishes those files, repackaged as `.zip`, beside an index naming each one's size and SHA-256 and the vendor file it was made from: the engine takes them from the release mirror first and the release itself second, refuses a file that does not match, and refuses an index built from a different vendor file than it pins, so an engine version always runs the tool versions it was built against. There is no fallback to the vendor's own site. `estella luban gen` writes the tables (only the files that changed, and it removes what a deleted table used to produce), `estella luban check` fails when they are out of date, and an export of a project that has Luban on rebuilds them first. Windows, macOS (both architectures) and Linux (both architectures).-- **Protobuf, the second optional tool.** `tools.protobuf.enabled` in `project.esproject` (folders `proto` and `src/proto` unless the project says otherwise) makes the engine fetch the pinned `protoc` the same way it fetches Luban, asking first, and turn the project's `.proto` files into TypeScript: an interface and an `encode`/`decode` pair per message, written against one small `_runtime.ts` beside them, so the game carries no protobuf library. proto3 is supported, with scalars, enums, nested messages, `repeated`, `optional`, `oneof` and `map`; 64-bit integers are numbers and a value past 2^53 throws instead of rounding, and proto2 is refused by name. The output is checked against `protoc` itself, in both directions, byte for byte. `estella proto gen` writes only the files that changed, `estella proto check` fails when they are stale, and an export of a project with Protobuf on regenerates them first. The channel between a client and a server still carries JSON; this is the tool and the codec, not yet the transport.+- **Protobuf as a second optional tool: .proto files become TypeScript types and a binary codec.** `tools.protobuf.enabled` in `project.esproject` (folders `proto` and `src/proto` unless the project says otherwise) makes the engine fetch the pinned `protoc` the same way it fetches Luban, asking first, and turn the project's `.proto` files into TypeScript: an interface and an `encode`/`decode` pair per message, written against one small `_runtime.ts` beside them, so the game carries no protobuf library. proto3 is supported, with scalars, enums, nested messages, `repeated`, `optional`, `oneof` and `map`; 64-bit integers are numbers and a value past 2^53 throws instead of rounding, and proto2 is refused by name. The output is checked against `protoc` itself, in both directions, byte for byte. `estella proto gen` writes only the files that changed, `estella proto check` fails when they are stale, and an export of a project with Protobuf on regenerates them first. A session can carry it (next entry).+- **A session can speak protobuf, with the JSON wire kept for debugging.** `ClientSession({ wire: 'pb' })` asks for it in the hello and `SessionHost({ wire })` decides: `'json'` (the default, nothing changes), `'pb'` (a client that asks gets binary frames, and one that asks for JSON still gets text, which is how a session is read in a debugger) or `'pb-only'` (a client that asks for JSON is turned away and JSON frames are dropped afterwards). A message from a `.proto` file is a contract type with `proto(Order)`: the generated code brings its binary codec, a checked JSON form for the debugging wire, and a `shape` that goes into the contract fingerprint, so changing the `.proto` changes it. On the binary wire every control message is one fixed envelope on binary channel 255, which is now reserved (0-254 stay the game's); the frame limit, the rate limit and retry-safe requests apply to it as before, and a retried request is answered from its stored result on either wire. Types written with `s` keep working on both wires.- **A text field can accept only digits.** `TextInput.inputFilter` (`TextInputFilter.Digits`) keeps a field to 0-9 for a count or a price: a letter typed or pasted never reaches `value`, and the caret stays where the kept characters put it. A script that cleaned the value itself each frame lost to the field: while a field is being edited its own editor is the source of `value`, so the cleaned value was overwritten with what was typed and the screen kept showing the letters. The filter runs where the editor's text is read in, beside `maxLength`, so what is on screen and what a script reads are the same. Off by default; a `maxLength` still applies after it.- **A web build can say which servers its game connects to.** The exported page's Content-Security-Policy let a game talk only to the page it came from, so a game with a server of its own could not reach it: the browser refused the connection and said nothing the game could see. A project now lists the origins in `packaging.platforms.web.connect` (`wss://play.example.com`, `ws://127.0.0.1:*` for any port on a host, or a bare `wss:` for any secure WebSocket) and each becomes a `connect-src` source. An entry is checked rather than pasted in: a path, a wildcard host, a space, a semicolon or a quote fails the export and names the entry, so no entry can end the directive and start another. Web only; a mini-game's server addresses are the platform's own list.- **A session can be told to redial now, and says why its link ended.** `ClientSession.retryNow()` dials at once instead of waiting out the backoff, for a player who pressed "try again"; it does nothing when the session is ready, already dialling, or closed. `lastClose` is the WebSocket close code of the last link that ended (4003, `SessionCloseCode.unavailable`, is the server saying it is full or going away) until the next one is ready, and `attempts` counts dials since the session was last ready, so a screen can tell "reconnecting" from "the server is full" and say which attempt this is.diff --git a/pipeline/src/tools/protoGen.ts b/pipeline/src/tools/protoGen.tsindex 3cb148cb8..c8d0a8cfd 100644--- a/pipeline/src/tools/protoGen.ts+++ b/pipeline/src/tools/protoGen.ts@@ -239,22 +239,22 @@ function emitFile(file: FileInfo, registry: Map<string, Named>): string {for (const v of e.values) body.push(` ${/^[A-Za-z_]/.test(v.name) ? v.name : JSON.stringify(v.name)} = ${v.number},`);body.push('}', '');};- const emitMessage = (m: MessageInfo, ts: string): void => {+ const emitMessage = (m: MessageInfo, ts: string, where: string): void => {if (m.mapEntry) return;for (const e of m.enums) emitEnum(e, `${ts}_${e.name}`);- for (const n of m.nested) emitMessage(n, `${ts}_${n.name}`);- body.push(...message(m, ts, ref, registry));+ for (const n of m.nested) emitMessage(n, `${ts}_${n.name}`, `${where}.${n.name}`);+ body.push(...message(m, ts, `${prefixOf(file)}.${where}`, ref, registry));};for (const e of file.enums) emitEnum(e, e.name);- for (const m of file.messages) emitMessage(m, m.name);+ for (const m of file.messages) emitMessage(m, m.name, m.name);const head = ['// Generated by Estella from ' + file.name + '. Do not edit: it is rewritten on every run.', '/* eslint-disable */',- `import { Reader, Writer } from '${rel('_runtime')}';`];+ `import { Reader, Writer, b64, jArr, jBool, jBytes, jInt, jMapBool, jMapInt, jNum, jObj, jStr } from '${rel('_runtime')}';`];for (const [from, names] of [...used].sort((a, b) => (a[0] < b[0] ? -1 : 1))) head.push(`import { ${[...names].sort().join(', ')} } from '${rel(from)}';`);return [...head, '', ...body].join('\n').replace(/\n+$/, '\n');}-function message(m: MessageInfo, ts: string, ref: (t: string) => Named, registry: Map<string, Named>): string[] {+function message(m: MessageInfo, ts: string, fullName: string, ref: (t: string) => Named, registry: Map<string, Named>): string[] {const entryOf = (f: FieldInfo): MessageInfo | null => {if (!f.repeated || f.type !== T_MESSAGE) return null;const named = registry.get(f.typeName);@@ -350,6 +350,60 @@ function message(m: MessageInfo, ts: string, ref: (t: string) => Named, registryfor (const f of members) read.push(`case ${f.number}: if (wt === ${wireOf(f)}) m.${name} = { case: '${member(f.name)}', value: ${readOne(f)} }; else r.skip(wt); break;`);});+ const jsonOut: string[] = [];+ const jsonIn: string[] = [];+ const INT_RANGE: Record<number, [string, string]> = {+ 5: ['-2147483648', '2147483647'], 17: ['-2147483648', '2147483647'], 15: ['-2147483648', '2147483647'],+ 13: ['0', '4294967295'], 7: ['0', '4294967295'],+ 3: ['-9007199254740991', '9007199254740991'], 18: ['-9007199254740991', '9007199254740991'], 16: ['-9007199254740991', '9007199254740991'],+ 4: ['0', '9007199254740991'], 6: ['0', '9007199254740991'],+ };+ const jsonTo = (f: FieldInfo, v: string): string => (f.type === 12 ? `b64(${v})` : f.type === T_MESSAGE ? `${ref(f.typeName).ts}.toJSON(${v})` : v);+ const jsonFrom = (f: FieldInfo, v: string, path: string): string => {+ const q = JSON.stringify(path);+ if (f.type === T_MESSAGE) return `${ref(f.typeName).ts}.fromJSON(${v})`;+ if (f.type === T_ENUM) return `jInt(${v}, ${q}, -2147483648, 2147483647)`;+ if (f.type === 1 || f.type === 2) return `jNum(${v}, ${q})`;+ if (f.type === 8) return `jBool(${v}, ${q})`;+ if (f.type === 9) return `jStr(${v}, ${q})`;+ if (f.type === 12) return `jBytes(${v}, ${q})`;+ const [lo, hi] = INT_RANGE[f.type]!;+ return `jInt(${v}, ${q}, ${lo}, ${hi})`;+ };+ for (const f of m.fields) {+ if (f.oneof !== null && !f.optional) continue;+ const name = member(f.name);+ const path = `${ts}.${name}`;+ const entry = entryOf(f);+ if (entry) {+ const [k, v] = entry.fields;+ const key = k!.type === 9 ? 'k' : k!.type === 8 ? `jMapBool(k, ${JSON.stringify(path)})` : `jMapInt(k, ${JSON.stringify(path)}, ${INT_RANGE[k!.type]![0]}, ${INT_RANGE[k!.type]![1]})`;+ jsonOut.push(`{ const e: Record<string, unknown> = {}; for (const [k, v] of m.${name}) e[String(k)] = ${jsonTo(v!, 'v')}; o.${name} = e; }`);+ jsonIn.push(`if (o.${name} != null) { const e = jObj(o.${name}, ${JSON.stringify(path)}); for (const k of Object.keys(e)) m.${name}.set(${key}, ${jsonFrom(v!, 'e[k]', path)}); }`);+ } else if (f.repeated) {+ jsonOut.push(`o.${name} = m.${name}.map((v) => ${jsonTo(f, 'v')});`);+ jsonIn.push(`if (o.${name} != null) m.${name} = jArr(o.${name}, ${JSON.stringify(path)}).map((v) => ${jsonFrom(f, 'v', path)});`);+ } else if (f.type === T_MESSAGE || f.optional) {+ jsonOut.push(`if (m.${name} !== undefined) o.${name} = ${jsonTo(f, `m.${name}`)};`);+ jsonIn.push(`if (o.${name} != null) m.${name} = ${jsonFrom(f, `o.${name}`, path)};`);+ } else {+ jsonOut.push(`o.${name} = ${jsonTo(f, `m.${name}`)};`);+ jsonIn.push(`if (o.${name} != null) m.${name} = ${jsonFrom(f, `o.${name}`, path)};`);+ }+ }+ m.oneofs.forEach((oneofName, index) => {+ const members = m.fields.filter((f) => f.oneof === index && !f.optional);+ if (members.length === 0) return;+ const name = member(oneofName);+ const path = `${ts}.${name}`;+ jsonOut.push(`if (m.${name} !== undefined) { switch (m.${name}.case) {`);+ for (const f of members) jsonOut.push(` case '${member(f.name)}': o.${name} = { case: '${member(f.name)}', value: ${jsonTo(f, `m.${name}.value`)} }; break;`);+ jsonOut.push('} }');+ jsonIn.push(`if (o.${name} != null) { const p = jObj(o.${name}, ${JSON.stringify(path)}); switch (p.case) {`);+ for (const f of members) jsonIn.push(` case '${member(f.name)}': m.${name} = { case: '${member(f.name)}', value: ${jsonFrom(f, 'p.value', path)} }; break;`);+ jsonIn.push(` default: throw new RangeError(${JSON.stringify(path + ': unknown case ')} + String(p.case));`, '} }');+ });+lines.push(`export interface ${ts} {`, ...iface, '}', '');lines.push(`export const ${ts} = {`);lines.push(` create(init: Partial<${ts}> = {}): ${ts} {`,@@ -358,7 +412,48 @@ function message(m: MessageInfo, ts: string, ref: (t: string) => Named, registrylines.push(` read(r: Reader, end: number): ${ts} {`, ` const m = ${ts}.create();`,' while (r.pos < end) {', ' const t = r.tag(); const wt = t & 7;', ' switch (t >>> 3) {',...read.map((l) => ` ${l}`), ' default: r.skip(wt);', ' }', ' }', ' return m;', ' },');+ lines.push(` toJSON(m: ${ts}): unknown {`, ' const o: Record<string, unknown> = {};', ...jsonOut.map((l) => ` ${l}`), ' return o;', ' },');+ lines.push(` fromJSON(j: unknown): ${ts} {`, ` const o = jObj(j, ${JSON.stringify(ts)});`, ` const m = ${ts}.create();`, ...jsonIn.map((l) => ` ${l}`), ' return m;', ' },');+ lines.push(` shape: ${JSON.stringify(shapeOf(fullName, registry))},`);lines.push(` encode(m: ${ts}): Uint8Array { const w = new Writer(); ${ts}.write(m, w); return w.finish(); },`,` decode(bytes: Uint8Array): ${ts} { return ${ts}.read(new Reader(bytes), bytes.length); },`, '};', '');return lines;}++const prefixOf = (file: FileInfo): string => (file.package ? file.package : '');++const TYPE_NAMES: Record<number, string> = {+ 1: 'double', 2: 'float', 3: 'int64', 4: 'uint64', 5: 'int32', 6: 'fixed64', 7: 'fixed32', 8: 'bool', 9: 'string',+ 12: 'bytes', 13: 'uint32', 15: 'sfixed32', 16: 'sfixed64', 17: 'sint32', 18: 'sint64',+};++/**+ * A text naming a message's fields and, behind them, every message and enum it reaches, so two builds+ * can tell whether they agree on the shape of what is sent. `fullName` is `package.Outer.Inner`.+ */+function shapeOf(fullName: string, registry: Map<string, Named>): string {+ const seen = new Set<string>();+ const parts: string[] = [];+ const visit = (name: string): void => {+ if (seen.has(name)) return;+ seen.add(name);+ const named = registry.get(name);+ if (!named) return;+ if (named.kind === 'enum') {+ const e = named.info as EnumInfo;+ parts.push(`enum ${named.ts}{${e.values.map((v) => `${v.name}=${v.number}`).join(',')}}`);+ return;+ }+ const msg = named.info as MessageInfo;+ const fieldText = msg.fields.map((f) => {+ const kind = f.type === T_MESSAGE || f.type === T_ENUM ? (registry.get(f.typeName)?.ts ?? f.typeName) : TYPE_NAMES[f.type] ?? String(f.type);+ const label = f.repeated ? 'repeated ' : f.optional ? 'optional ' : '';+ const oneof = f.oneof !== null && !f.optional ? `@${msg.oneofs[f.oneof]}` : '';+ return `${f.number}:${label}${kind}${oneof} ${f.name}`;+ });+ parts.push(`${named.ts}{${fieldText.join(',')}}`);+ for (const f of msg.fields) if (f.type === T_MESSAGE || f.type === T_ENUM) visit(f.typeName);+ };+ visit(`.${fullName}`.replace(/^\.\./, '.'));+ return parts.join(';');+}diff --git a/pipeline/src/tools/protoRuntime.ts b/pipeline/src/tools/protoRuntime.tsindex ad9f69cde..215f237c5 100644--- a/pipeline/src/tools/protoRuntime.ts+++ b/pipeline/src/tools/protoRuntime.ts@@ -17,6 +17,65 @@ const MAX_SAFE = Number.MAX_SAFE_INTEGER;const utf8Encoder = new TextEncoder();const utf8Decoder = new TextDecoder('utf-8', { fatal: true });+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';++/** The JSON form of the debugging wire: bytes are base64 text. */+export function b64(bytes: Uint8Array): string {+ let out = '';+ for (let i = 0; i < bytes.length; i += 3) {+ const n = (bytes[i]! << 16) | ((bytes[i + 1] ?? 0) << 8) | (bytes[i + 2] ?? 0);+ out += B64[(n >> 18) & 63]! + B64[(n >> 12) & 63]! + (i + 1 < bytes.length ? B64[(n >> 6) & 63]! : '=') + (i + 2 < bytes.length ? B64[n & 63]! : '=');+ }+ return out;+}++export function jObj(v: unknown, path: string): Record<string, unknown> {+ if (typeof v !== 'object' || v === null || Array.isArray(v)) throw new TypeError(path + ': expected an object');+ return v as Record<string, unknown>;+}+export function jArr(v: unknown, path: string): unknown[] {+ if (!Array.isArray(v)) throw new TypeError(path + ': expected a list');+ return v;+}+export function jStr(v: unknown, path: string): string {+ if (typeof v !== 'string') throw new TypeError(path + ': expected text');+ return v;+}+export function jBool(v: unknown, path: string): boolean {+ if (typeof v !== 'boolean') throw new TypeError(path + ': expected true or false');+ return v;+}+export function jNum(v: unknown, path: string): number {+ if (typeof v !== 'number') throw new TypeError(path + ': expected a number');+ return v;+}+export function jInt(v: unknown, path: string, min: number, max: number): number {+ if (typeof v !== 'number' || !Number.isInteger(v)) throw new TypeError(path + ': expected an integer');+ if (v < min || v > max) throw new RangeError(path + ': outside ' + min + '..' + max);+ return v;+}+export function jBytes(v: unknown, path: string): Uint8Array {+ const text = jStr(v, path);+ if (text.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(text)) throw new TypeError(path + ': expected base64 text');+ const pad = text.endsWith('==') ? 2 : text.endsWith('=') ? 1 : 0;+ const out = new Uint8Array((text.length / 4) * 3 - pad);+ let o = 0;+ for (let i = 0; i < text.length; i += 4) {+ const n = (B64.indexOf(text[i]!) << 18) | (B64.indexOf(text[i + 1]!) << 12) | ((text[i + 2] === '=' ? 0 : B64.indexOf(text[i + 2]!)) << 6) | (text[i + 3] === '=' ? 0 : B64.indexOf(text[i + 3]!));+ if (o < out.length) out[o++] = (n >> 16) & 255;+ if (o < out.length) out[o++] = (n >> 8) & 255;+ if (o < out.length) out[o++] = n & 255;+ }+ return out;+}+export function jMapInt(key: string, path: string, min: number, max: number): number {+ return jInt(/^-?\d+$/.test(key) ? Number(key) : NaN, path + '[' + key + ']', min, max);+}+export function jMapBool(key: string, path: string): boolean {+ if (key !== 'true' && key !== 'false') throw new TypeError(path + '[' + key + ']: expected true or false');+ return key === 'true';+}+export class Writer {private buf = new Uint8Array(64);private len = 0;diff --git a/pipeline/tests/protobuf-run.test.ts b/pipeline/tests/protobuf-run.test.tsindex 38da590a2..f7a180d61 100644--- a/pipeline/tests/protobuf-run.test.ts+++ b/pipeline/tests/protobuf-run.test.ts@@ -128,6 +128,63 @@ message Order {expect(viaProtoc('--encode', viaProtoc('--decode', ours).toString()).equals(theirs)).toBe(true);}, 60_000);+ const sample = () => ({+ id: 'o1', stamp: -5, delta: -3, counts: [1, -2, 300], tags: ['a', 'b'], stock: new Map([['w', 3]]), season: 3, note: 7,+ inner: { depth: 2, mode: 1 }, payload: { case: 'text', value: 'hi' }, blob: new Uint8Array([1, 2, 3, 4]), flag: true,+ ref: { id: 'r' }, ratio: 1.5, big: -9007199254740991, f32: 4000000000, zig: -77,+ trail: [{ depth: 1, mode: 0 }, { depth: 3, mode: 1 }],+ });++ it('has a JSON form that survives JSON.stringify and comes back the same', async () => {+ const Order = await load();+ const json = JSON.parse(JSON.stringify(Order.toJSON(sample())));+ expect(json.blob).toBe('AQIDBA==');+ expect(json.stock).toEqual({ w: 3 });+ expect(json.payload).toEqual({ case: 'text', value: 'hi' });+ expect(Order.fromJSON(json)).toEqual(sample());+ // and the binary form of what came back is the binary form of what went in+ expect(Buffer.from(Order.encode(Order.fromJSON(json))).equals(Buffer.from(Order.encode(sample())))).toBe(true);+ }, 60_000);++ it('refuses JSON that is not the message, naming the field', async () => {+ const Order = await load();+ const bad = (patch: Record<string, unknown>) => () => Order.fromJSON({ ...Order.toJSON(sample()), ...patch });+ expect(bad({ stamp: 'x' })).toThrow(/Order\.stamp: expected an integer/);+ expect(bad({ delta: 2 ** 31 })).toThrow(/Order\.delta: outside/);+ expect(bad({ note: -1 })).toThrow(/Order\.note: outside 0\.\.4294967295/);+ expect(bad({ tags: 'a' })).toThrow(/Order\.tags: expected a list/);+ expect(bad({ tags: ['a', 3] })).toThrow(/Order\.tags: expected text/);+ expect(bad({ blob: 'not base64!' })).toThrow(/Order\.blob: expected base64 text/);+ expect(bad({ payload: { case: 'nope', value: 1 } })).toThrow(/Order\.payload: unknown case nope/);+ expect(bad({ inner: 5 })).toThrow(/Order_Inner: expected an object/);+ expect(bad({ stock: { w: 'x' } })).toThrow(/Order\.stock: expected an integer/);+ expect(() => Order.fromJSON(null)).toThrow(/Order: expected an object/);+ expect(Order.fromJSON({}).id).toBe('');+ }, 60_000);++ it('names every message and enum a message reaches, so a change anywhere behind it changes the shape', async () => {+ const Order = await load();+ expect(Order.shape).toContain('Order{1:string id');+ expect(Order.shape).toContain('Ref{1:string id}');+ expect(Order.shape).toContain('enum Season{SPRING=0,SUMMER=1,AUTUMN=2,WINTER=3}');+ expect(Order.shape).toContain('Order_Inner{1:int32 depth,2:Order_Inner_Mode mode}');+ expect(Order.shape).toContain('payload');+ }, 60_000);++ it('travels a session channel on either wire as itself', async () => {+ const Order = await load();+ const { NetChannel } = await import('../../sdk/src/net/NetChannel');+ const { MemoryTransport } = await import('../../sdk/src/net/MemoryTransport');+ for (const wire of ['pb', 'json'] as const) {+ const [ta, tb] = MemoryTransport.pair();+ const a = new NetChannel(ta);+ const b = new NetChannel(tb);+ a.setWire(wire);+ b.handle('place', (o: unknown) => o, { req: Order, res: Order });+ expect(await a.request('place', sample(), { codec: { req: Order, res: Order } })).toEqual(sample());+ }+ }, 60_000);+it('leaves defaults off the wire, keeps an unset optional unset, and skips fields it does not know', async () => {const Order = await load();const empty = Order.encode(Order.create());diff --git a/sdk/etc/replication.api.md b/sdk/etc/replication.api.mdindex 70a49ad4e..2d876e47f 100644--- a/sdk/etc/replication.api.md+++ b/sdk/etc/replication.api.md@@ -165,13 +165,15 @@ ResourceDef<NetSession>## NetChannel — class @experimental```dispose: (reason?: string) => void-handle: <Req = unknown, Res = unknown>(type: string, handler: RequestHandler<Req, Res>) => () => void-on: <T = unknown>(type: string, handler: MessageHandler<T>) => () => void+handle: <Req = unknown, Res = unknown>(type: string, handler: RequestHandler<Req, Res>, codec?: RequestCodec<Req, Res>) => () => void+on: <T = unknown>(type: string, handler: MessageHandler<T>, codec?: PayloadCodec<T>) => () => voidonBinary: (channel: number, handler: BinaryHandler) => () => voidrequest: <Res = unknown, Req = unknown>(type: string, payload: Req, options?: number | RequestOptions) => Promise<Res>-send: <T = unknown>(type: string, payload: T) => void+send: <T = unknown>(type: string, payload: T, codec?: PayloadCodec<T>) => voidsendBinary: (channel: number, payload: Uint8Array) => voidsetIdempotencyScope: (scope: string) => void+setWire: (format: WireFormat, options?: { acceptJson?: boolean; }) => void+wire: WireFormatstatic new (transport: NetTransport, opts?: NetChannelOptions): NetChannelstatic prototype: NetChannel```diff --git a/sdk/etc/session.api.md b/sdk/etc/session.api.mdindex ca812ea8f..68422eebd 100644--- a/sdk/etc/session.api.md+++ b/sdk/etc/session.api.md@@ -1,7 +1,7 @@# API surface — esengine/session<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 0 public · 0 beta · 49 experimental · 0 deprecated+Symbols: 0 public · 0 beta · 56 experimental · 0 deprecated## AcceptWebSocketOptions — interface @experimental```@@ -20,11 +20,11 @@ transport: NetTransportattempts: numberclose: () => voidlastClose: { code: number; } | null-on: <T = unknown>(type: string, handler: MessageHandler<T>) => () => void+on: <T = unknown>(type: string, handler: MessageHandler<T>, codec?: PayloadCodec<T>) => () => voidonState: (handler: StateHandler) => () => voidrequest: <Res = unknown, Req = unknown>(type: string, payload: Req, options?: SessionRequestOptions) => Promise<Res>retryNow: () => void-send: (type: string, payload: unknown) => void+send: (type: string, payload: unknown, codec?: PayloadCodec<never>) => voidserverNow: () => numberstart: () => Promise<SessionWelcome>state: SessionState@@ -45,6 +45,7 @@ readyTimeoutMs: number | undefinedrequestTimeoutMs: number | undefinedretries: number | undefinedretryDelayMs: number | undefined+wire: WireFormat | undefined```## Contract — interface @experimental@@ -132,13 +133,15 @@ static prototype: MemoryIdempotencyStore## NetChannel — class @experimental```dispose: (reason?: string) => void-handle: <Req = unknown, Res = unknown>(type: string, handler: RequestHandler<Req, Res>) => () => void-on: <T = unknown>(type: string, handler: MessageHandler<T>) => () => void+handle: <Req = unknown, Res = unknown>(type: string, handler: RequestHandler<Req, Res>, codec?: RequestCodec<Req, Res>) => () => void+on: <T = unknown>(type: string, handler: MessageHandler<T>, codec?: PayloadCodec<T>) => () => voidonBinary: (channel: number, handler: BinaryHandler) => () => voidrequest: <Res = unknown, Req = unknown>(type: string, payload: Req, options?: number | RequestOptions) => Promise<Res>-send: <T = unknown>(type: string, payload: T) => void+send: <T = unknown>(type: string, payload: T, codec?: PayloadCodec<T>) => voidsendBinary: (channel: number, payload: Uint8Array) => voidsetIdempotencyScope: (scope: string) => void+setWire: (format: WireFormat, options?: { acceptJson?: boolean; }) => void+wire: WireFormatstatic new (transport: NetTransport, opts?: NetChannelOptions): NetChannelstatic prototype: NetChannel```@@ -188,7 +191,31 @@ send: (data: string | ArrayBuffer) => void## NetViolation — type @experimental```-'frame-size' | 'rate'+'frame-size' | 'rate' | 'wire'+```++## PayloadCodec — interface @experimental+```+decode: (bytes: Uint8Array) => T+encode: (value: T) => Uint8Array+fromJSON: (json: unknown) => T+toJSON: (value: T) => unknown+```++## ProtoMessage — interface @experimental+```+decode: (bytes: Uint8Array) => T+encode: (value: T) => Uint8Array+fromJSON: (json: unknown) => T+shape: string+toJSON: (value: T) => unknown+```++## ProtoSchema — interface @experimental+```+codec: PayloadCodec<T>+describe: () => string+parse: (value: unknown, path?: string) => T```## ReliableOrderedTransport — interface @experimental@@ -198,6 +225,12 @@ on: (event: "message", handler: (data: string | ArrayBuffer) => void) => () => vsend: (data: string | ArrayBuffer) => void```+## RequestCodec — interface @experimental+```+req: PayloadCodec<Req>+res: PayloadCodec<Res>+```+## RequestDef — interface @experimental```req: Schema<Req>@@ -211,6 +244,7 @@ res: Schema<Res>## RequestOptions — interface @experimental```+codec: RequestCodec<any, any> | undefinedidempotencyKey: string | undefinedtimeoutMs: number | undefined```@@ -242,7 +276,7 @@ static prototype: SchemaError```close: (code?: number, reason?: string) => voidctx: Ctx-push: (type: string, payload: unknown) => void+push: (type: string, payload: unknown, codec?: PayloadCodec<never>) => void```## SessionBackoff — interface @experimental@@ -272,6 +306,7 @@ playerId: string```credentials: unknownversion: number+wire: "json" | "pb" | undefined```## SessionHelloResponse — type @experimental@@ -281,6 +316,8 @@ version: numberplayerId: string;/** The server's clock at the moment it answered, in epoch milliseconds. */serverTimeMs: number;+ /** The encoding both ends write from now on. Absent means JSON. */+ wire?: 'json' | 'pb';/** Anything the game wants the client to have at once (a renewed token). */data?: unknown;}@@ -290,12 +327,12 @@ version: number## SessionHost — class @experimental```accept: (connection: AcceptedConnection) => void-broadcast: (type: string, payload: unknown, filter?: (ctx: Ctx) => boolean) => number+broadcast: (type: string, payload: unknown, filter?: (ctx: Ctx) => boolean, codec?: PayloadCodec<never>) => numberclose: (code?: number, reason?: string) => voidconnectionCount: number-handle: <Req = unknown, Res = unknown>(type: string, handler: SessionHandler<Ctx, Req, Res>) => () => void+handle: <Req = unknown, Res = unknown>(type: string, handler: SessionHandler<Ctx, Req, Res>, codec?: RequestCodec<Req, Res>) => () => voidplayerCount: number-push: (playerId: string, type: string, payload: unknown) => boolean+push: (playerId: string, type: string, payload: unknown, codec?: PayloadCodec<never>) => booleanstatic new <Ctx extends SessionContext = SessionContext>(options: SessionHostOptions<Ctx>): SessionHost<Ctx>static prototype: SessionHost<any>```@@ -310,6 +347,7 @@ limits: Pick<NetLimitOptions, "maxFrameBytes" | "messagesPerSecond" | "burst"> |maxSessions: number | undefinedmaxViolationsPerMinute: number | undefinedrequestTimeoutMs: number | undefined+wire: "json" | "pb" | "pb-only" | undefined```## SessionRejected — class @experimental@@ -321,6 +359,7 @@ static prototype: SessionRejected## SessionRequestOptions — interface @experimental```+codec: RequestCodec<any, any> | undefinedidempotencyKey: string | undefinedretries: number | undefinedtimeoutMs: number | undefined@@ -346,6 +385,11 @@ send: (data: string | ArrayBufferLike | ArrayBufferView) => voidterminate: (() => void) | undefined```+## WireFormat — type @experimental+```+'json' | 'pb'+```+## acceptWebSocket — function @experimental```<Ctx extends SessionContext>(host: SessionHost<Ctx>, socket: WebSocketLike, options?: AcceptWebSocketOptions): void@@ -356,6 +400,16 @@ terminate: (() => void) | undefined<R extends RequestDefs, E extends EventDefs = Record<never, never>>(def: { requests: R; events?: E; }): Contract<R, E>```+## jsonCodec — const @experimental+```+PayloadCodec<unknown>+```++## proto — function @experimental+```+<T>(message: ProtoMessage<T>, check?: (value: T) => void): ProtoSchema<T>+```+## s — const @experimental```{ string(opts?: { min?: number; max?: number; pattern?: RegExp; }): Schema<string>; int(opts?: { min?: number; max?: number; }): Schema<number>; number(opts?: { min?: number; max?: number; }): Schema<number>; boolean(): Schema<boolean>; literal<const T extends string | number | boolean | null>(value: T): Schema<T>; enum<const T extends readonly [string, ...string[]]>(values: T): Schema<T[number]>; array<T>(item: Schema<T>, opts?: { max?: number; }): Schema<T[]>; object<S extends Shape>(shape: S): Schema<ObjectOf<S>>; record<T>(value: Schema<T>, opts?: { maxKeys?: number; }): Schema<Record<string, T>>; optional<T>(inner: Schema<T>): Schema<T | undefined>; nullable<T>(inner: Schema<T>): Schema<T | null>; unknown(): Schema<unknown>; }diff --git a/sdk/src/net/NetChannel.ts b/sdk/src/net/NetChannel.tsindex 198e1a666..3f1b96951 100644--- a/sdk/src/net/NetChannel.ts+++ b/sdk/src/net/NetChannel.ts@@ -9,6 +9,15 @@* agnostic — anything that can `send` and surface `message` events works.*/import type { IdempotencyStore } from './IdempotencyStore';+import { CONTROL_CHANNEL, decodeEnvelope, encodeEnvelope, type Envelope, type PayloadCodec, type WireFormat } from './wire';++export type { PayloadCodec, WireFormat } from './wire';++/** The codecs of one request: how its payload and its answer travel. */+export interface RequestCodec<Req = unknown, Res = unknown> {+ req: PayloadCodec<Req>;+ res: PayloadCodec<Res>;+}/** The minimal socket surface NetChannel drives (GameSocket / WeChatSocket fit). */export interface NetTransport {@@ -59,7 +68,7 @@ export class NetRequestError extends Error {}/** Why a channel dropped or refused something the peer sent. */-export type NetViolation = 'frame-size' | 'rate';+export type NetViolation = 'frame-size' | 'rate' | 'wire';export interface NetHeartbeatOptions {/** How often to ping the peer. */@@ -105,6 +114,8 @@ export interface RequestOptions {* click), not per attempt.*/idempotencyKey?: string;+ /** How the payload and the answer travel on the protobuf wire; the JSON wire carries their JSON form. */+ codec?: RequestCodec<any, any>;}interface WireEvent { k: 'event'; t: string; d: unknown; }@@ -118,8 +129,24 @@ interface Pending {resolve: (value: unknown) => void;reject: (err: Error) => void;timer: ReturnType<typeof setTimeout> | null;+ codec: PayloadCodec | undefined;}+/** A control message as it arrived, whichever wire it came on; `payload` reads the value with the codec the handler knows. */+interface Incoming {+ k: Wire['k'];+ t?: string;+ id?: number;+ ik?: string;+ e?: string;+ n?: number;+ hasPayload: boolean;+ payload(codec: PayloadCodec | undefined): unknown;+}++const utf8 = new TextEncoder();+const utf8Back = new TextDecoder();+/*** Typed messaging over a {@link NetTransport}. Subscribes to the transport's* `message` events (it is the message router). Events are fire-and-forget;@@ -134,7 +161,10 @@ interface Pending {export class NetChannel {private readonly transport: NetTransport;private readonly handlers = new Map<string, Set<MessageHandler>>();- private readonly requestHandlers = new Map<string, RequestHandler>();+ private readonly requestHandlers = new Map<string, { handler: RequestHandler; codec: RequestCodec<any, any> | undefined }>();+ private readonly eventCodecs = new Map<string, PayloadCodec>();+ private wire_: WireFormat = 'json';+ private jsonAllowed_ = true;private readonly binaryHandlers = new Map<number, BinaryHandler>();private readonly pending = new Map<number, Pending>();private readonly defaultTimeout: number;@@ -164,7 +194,8 @@ export class NetChannel {}/** Subscribe to a typed event. Returns an unsubscribe function. */- on<T = unknown>(type: string, handler: MessageHandler<T>): () => void {+ on<T = unknown>(type: string, handler: MessageHandler<T>, codec?: PayloadCodec<T>): () => void {+ if (codec) this.eventCodecs.set(type, codec as PayloadCodec);let set = this.handlers.get(type);if (!set) { set = new Set(); this.handlers.set(type, set); }set.add(handler as MessageHandler);@@ -175,16 +206,31 @@ export class NetChannel {}/** Fire-and-forget a typed event to the peer. */- send<T = unknown>(type: string, payload: T): void {- this.send_({ k: 'event', t: type, d: payload });+ send<T = unknown>(type: string, payload: T, codec?: PayloadCodec<T>): void {+ this.send_({ k: 'event', t: type, d: payload }, codec as PayloadCodec | undefined);+ }++ /** The encoding this channel writes. It reads both. */+ get wire(): WireFormat {+ return this.wire_;+ }++ /**+ * Choose what this channel writes from now on. `acceptJson: false` makes it refuse JSON frames+ * from the peer (counted as a `wire` violation), for a server that has agreed on protobuf.+ */+ setWire(format: WireFormat, options: { acceptJson?: boolean } = {}): void {+ this.wire_ = format;+ this.jsonAllowed_ = options.acceptJson ?? true;}/** Register the single handler that answers `request(type, …)` from the peer.* Returns an unregister function. */- handle<Req = unknown, Res = unknown>(type: string, handler: RequestHandler<Req, Res>): () => void {- this.requestHandlers.set(type, handler as RequestHandler);+ handle<Req = unknown, Res = unknown>(type: string, handler: RequestHandler<Req, Res>, codec?: RequestCodec<Req, Res>): () => void {+ const entry = { handler: handler as RequestHandler, codec: codec as RequestCodec<any, any> | undefined };+ this.requestHandlers.set(type, entry);return () => {- if (this.requestHandlers.get(type) === (handler as RequestHandler)) {+ if (this.requestHandlers.get(type) === entry) {this.requestHandlers.delete(type);}};@@ -206,16 +252,17 @@ export class NetChannel {reject(new NetRequestError(`net request "${type}" timed out after ${limit}ms`, 'timeout'));}, limit): null;- this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject, timer });+ this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject, timer, codec: opts.codec?.res });const wire: WireReq = { k: 'req', t: type, id, d: payload };if (opts.idempotencyKey !== undefined) wire.ik = opts.idempotencyKey;- this.send_(wire);+ this.send_(wire, opts.codec?.req);});}- /** Register the single handler for a binary channel id (0-255). Returns an+ /** Register the single handler for a binary channel id (0-254; 255 carries control messages on the protobuf wire). Returns an* unregister function. */onBinary(channel: number, handler: BinaryHandler): () => void {+ if (channel === CONTROL_CHANNEL) throw new RangeError(`[net] binary channel ${CONTROL_CHANNEL} is reserved for control messages`);this.binaryHandlers.set(channel, handler);return () => {if (this.binaryHandlers.get(channel) === handler) {@@ -224,8 +271,9 @@ export class NetChannel {};}- /** Fire-and-forget a binary payload on a channel id (0-255). */+ /** Fire-and-forget a binary payload on a channel id (0-254; 255 carries control messages on the protobuf wire). */sendBinary(channel: number, payload: Uint8Array): void {+ if (channel === CONTROL_CHANNEL) throw new RangeError(`[net] binary channel ${CONTROL_CHANNEL} is reserved for control messages`);const frame = new Uint8Array(1 + payload.byteLength);frame[0] = channel;frame.set(payload, 1);@@ -256,8 +304,22 @@ export class NetChannel {// -- internals ------------------------------------------------------------- private send_(wire: Wire): void {- this.transport.send(JSON.stringify(wire));+ /** Write one control message in this channel's wire; `codec` is how its payload travels. */+ private send_(wire: Wire, codec?: PayloadCodec): void {+ const value = 'd' in wire ? wire.d : undefined;+ if (this.wire_ === 'json') {+ if (codec && value !== undefined) (wire as { d?: unknown }).d = codec.toJSON(value);+ this.transport.send(JSON.stringify(wire));+ return;+ }+ const e: Envelope = { kind: wire.k };+ if ('t' in wire) e.type = wire.t;+ if (wire.k === 'req' || wire.k === 'res') e.id = wire.id;+ if (wire.k === 'ping' || wire.k === 'pong') e.id = wire.n;+ if (wire.k === 'req' && wire.ik !== undefined) e.key = wire.ik;+ if (wire.k === 'res' && wire.e !== undefined) e.error = wire.e;+ if (value !== undefined) e.payload = codec ? codec.encode(value) : utf8.encode(JSON.stringify(value));+ this.transport.send(encodeEnvelope(e));}private startHeartbeat_(beat: NetHeartbeatOptions): void {@@ -296,26 +358,31 @@ export class NetChannel {const size = typeof data === 'string' ? data.length : data.byteLength;if (size > max) { this.limits_.onViolation?.('frame-size'); return; }}+ let msg: Incoming | null;if (typeof data !== 'string') {const view = new Uint8Array(data);if (view.byteLength === 0) return;- this.binaryHandlers.get(view[0])?.(view.subarray(1));- return;+ if (view[0] !== CONTROL_CHANNEL) {+ this.binaryHandlers.get(view[0]!)?.(view.subarray(1));+ return;+ }+ msg = incomingFromEnvelope(decodeEnvelope(view.subarray(1)));+ } else {+ if (!this.jsonAllowed_) { this.limits_.onViolation?.('wire'); return; }+ msg = incomingFromJson(data);}- let msg: Wire;- try { msg = JSON.parse(data) as Wire; } catch { return; }- if (!msg || typeof (msg as { k?: unknown }).k !== 'string') return;+ if (!msg) return;switch (msg.k) {- case 'ping': this.send_({ k: 'pong', n: msg.n }); break;+ case 'ping': this.send_({ k: 'pong', n: msg.n ?? 0 }); break;case 'pong': break;case 'event':if (!this.admit_()) { this.limits_.onViolation?.('rate'); break; }- this.dispatchEvent_(msg.t, msg.d);+ this.dispatchEvent_(msg);break;case 'req':if (!this.admit_()) {this.limits_.onViolation?.('rate');- this.send_({ k: 'res', id: msg.id, e: NET_RATE_LIMITED });+ this.send_({ k: 'res', id: msg.id ?? 0, e: NET_RATE_LIMITED });break;}this.handleRequest_(msg);@@ -324,28 +391,38 @@ export class NetChannel {}}- private dispatchEvent_(type: string, payload: unknown): void {+ private dispatchEvent_(msg: Incoming): void {+ const type = msg.t ?? '';const set = this.handlers.get(type);if (!set) return;+ let payload: unknown;+ try { payload = msg.payload(this.eventCodecs.get(type)); } catch { return; }for (const h of [...set]) h(payload);}- private handleRequest_(msg: WireReq): void {- const handler = this.requestHandlers.get(msg.t);- if (!handler) {- this.send_({ k: 'res', id: msg.id, e: `no request handler for "${msg.t}"` });+ private handleRequest_(msg: Incoming): void {+ const type = msg.t ?? '';+ const id = msg.id ?? 0;+ const entry = this.requestHandlers.get(type);+ if (!entry) {+ this.send_({ k: 'res', id, e: `no request handler for "${type}"` });+ return;+ }+ let payload: unknown;+ try { payload = msg.payload(entry.codec?.req); } catch (err) {+ this.send_({ k: 'res', id, e: `invalid ${type} request: ${errorText(err)}` });return;}const store = this.idempotency_;if (store && typeof msg.ik === 'string') {- void this.handleIdempotent_(store, `${this.scope_}\u0000${msg.t}\u0000${msg.ik}`, handler, msg);+ void this.handleIdempotent_(store, `${this.scope_}\u0000${type}\u0000${msg.ik}`, entry, id, payload);return;}Promise.resolve()- .then(() => handler(msg.d))+ .then(() => entry.handler(payload)).then(- (result) => this.send_({ k: 'res', id: msg.id, d: result }),- (err) => this.send_({ k: 'res', id: msg.id, e: errorText(err) }),+ (result) => this.send_({ k: 'res', id, d: result }, entry.codec?.res),+ (err) => this.send_({ k: 'res', id, e: errorText(err) }),);}@@ -353,45 +430,86 @@ export class NetChannel {* Run a keyed request at most once to completion. A handler that returns has* its answer kept, so a retry replays it; one that throws frees the key and* the retry runs again — a business refusal belongs in the return value.+ * The answer is kept in its JSON form, which any store can hold and either wire can rebuild.*/- private async handleIdempotent_(store: IdempotencyStore, key: string, handler: RequestHandler, msg: WireReq): Promise<void> {+ private async handleIdempotent_(+ store: IdempotencyStore, key: string, entry: { handler: RequestHandler; codec: RequestCodec<any, any> | undefined }, id: number, payload: unknown,+ ): Promise<void> {+ const res = entry.codec?.res;+ const replay = (stored: unknown): void => {+ let value: unknown = stored;+ if (res && stored !== undefined) {+ try { value = res.fromJSON(stored); } catch (err) { this.send_({ k: 'res', id, e: errorText(err) }); return; }+ }+ this.send_({ k: 'res', id, d: value }, res);+ };try {const begin = await store.begin(key);if (begin.state === 'done') {- this.send_({ k: 'res', id: msg.id, d: begin.outcome.d });+ replay(begin.outcome.d);return;}if (begin.state === 'busy') {const outcome = await begin.outcome;- if (outcome) this.send_({ k: 'res', id: msg.id, d: outcome.d });- else this.send_({ k: 'res', id: msg.id, e: NET_ATTEMPT_FAILED });+ if (outcome) replay(outcome.d);+ else this.send_({ k: 'res', id, e: NET_ATTEMPT_FAILED });return;}let result: unknown;try {- result = await handler(msg.d);+ result = await entry.handler(payload);} catch (err) {await store.abandon(key);- this.send_({ k: 'res', id: msg.id, e: errorText(err) });+ this.send_({ k: 'res', id, e: errorText(err) });return;}- await store.finish(key, { d: result });- this.send_({ k: 'res', id: msg.id, d: result });+ await store.finish(key, { d: res && result !== undefined ? res.toJSON(result) : result });+ this.send_({ k: 'res', id, d: result }, res);} catch (err) {- this.send_({ k: 'res', id: msg.id, e: errorText(err) });+ this.send_({ k: 'res', id, e: errorText(err) });}}- private resolvePending_(msg: WireRes): void {- const p = this.pending.get(msg.id);+ private resolvePending_(msg: Incoming): void {+ const p = this.pending.get(msg.id ?? 0);if (!p) return;- this.pending.delete(msg.id);+ this.pending.delete(msg.id ?? 0);if (p.timer) clearTimeout(p.timer);- if (msg.e !== undefined) p.reject(new NetRequestError(msg.e, remoteCode(msg.e)));- else p.resolve(msg.d);+ if (msg.e !== undefined) { p.reject(new NetRequestError(msg.e, remoteCode(msg.e))); return; }+ try { p.resolve(msg.payload(p.codec)); } catch (err) { p.reject(new NetRequestError(`the reply could not be read: ${errorText(err)}`, 'remote')); }}}+function incomingFromJson(data: string): Incoming | null {+ let msg: Wire;+ try { msg = JSON.parse(data) as Wire; } catch { return null; }+ if (!msg || typeof (msg as { k?: unknown }).k !== 'string') return null;+ const any = msg as unknown as Record<string, unknown>;+ return {+ k: msg.k,+ t: typeof any.t === 'string' ? any.t : undefined,+ id: typeof any.id === 'number' ? any.id : undefined,+ ik: typeof any.ik === 'string' ? any.ik : undefined,+ e: typeof any.e === 'string' ? any.e : undefined,+ n: typeof any.n === 'number' ? any.n : undefined,+ hasPayload: 'd' in any,+ payload: (codec) => (codec && any.d !== undefined ? codec.fromJSON(any.d) : any.d),+ };+}++function incomingFromEnvelope(e: Envelope | null): Incoming | null {+ if (!e) return null;+ const bytes = e.payload;+ return {+ k: e.kind, t: e.type, id: e.id, ik: e.key, e: e.error, n: e.id,+ hasPayload: bytes !== undefined,+ payload: (codec) => {+ if (bytes === undefined) return undefined;+ return codec ? codec.decode(bytes) : JSON.parse(utf8Back.decode(bytes));+ },+ };+}+function remoteCode(message: string): NetRequestErrorCode {if (message === NET_RATE_LIMITED) return 'rate-limited';if (message === NET_ATTEMPT_FAILED) return 'retry';diff --git a/sdk/src/net/session/ClientSession.ts b/sdk/src/net/session/ClientSession.tsindex 2d16b104b..66ec83f2e 100644--- a/sdk/src/net/session/ClientSession.ts+++ b/sdk/src/net/session/ClientSession.ts@@ -8,7 +8,7 @@* request under a key so a retry after a lost reply never runs twice.* Subscriptions made on the session survive every reconnect.*/-import { NetChannel, NetRequestError, type MessageHandler } from '../NetChannel';+import { NetChannel, NetRequestError, type MessageHandler, type PayloadCodec, type RequestCodec, type WireFormat } from '../NetChannel';import type { PlatformSocket } from '../../platform/types';import {SESSION_HELLO,@@ -31,6 +31,8 @@ export interface SessionBackoff {export interface ClientSessionOptions {/** A fresh, unopened socket each call (`() => createSocket({ url })`). */connect: () => PlatformSocket;+ /** The encoding to ask the server for. Default JSON; the server may not grant protobuf, and the session then speaks JSON. */+ wire?: WireFormat;/** Sent in every hello, first dial and redial alike. */credentials: () => unknown | Promise<unknown>;/** Ping the server; `false` turns it off. Default 15 s interval, 45 s timeout. */@@ -56,6 +58,8 @@ export interface SessionRequestOptions {timeoutMs?: number;/** Overrides the session's retry count for this call. 0 sends once. */retries?: number;+ /** How the payload and the reply travel on the protobuf wire. */+ codec?: RequestCodec<any, any>;}export interface SessionWelcome {@@ -68,6 +72,7 @@ type StateHandler = (state: SessionState, reason?: string) => void;export class ClientSession {private readonly options_: ClientSessionOptions;private readonly listeners_ = new Map<string, Set<MessageHandler>>();+ private readonly eventCodecs_ = new Map<string, PayloadCodec>();private readonly stateHandlers_ = new Set<StateHandler>();private readonly readyWaiters_: { resolve: () => void; reject: (e: Error) => void }[] = [];private state_: SessionState = 'idle';@@ -123,7 +128,8 @@ export class ClientSession {}/** Subscribe to a server-pushed event. Survives reconnects. */- on<T = unknown>(type: string, handler: MessageHandler<T>): () => void {+ on<T = unknown>(type: string, handler: MessageHandler<T>, codec?: PayloadCodec<T>): () => void {+ if (codec) this.eventCodecs_.set(type, codec as PayloadCodec);let set = this.listeners_.get(type);if (!set) { set = new Set(); this.listeners_.set(type, set); }set.add(handler as MessageHandler);@@ -147,8 +153,8 @@ export class ClientSession {}/** Fire-and-forget to the server. Dropped while the link is down. */- send(type: string, payload: unknown): void {- if (this.state_ === 'ready') this.channel_?.send(type, payload);+ send(type: string, payload: unknown, codec?: PayloadCodec<never>): void {+ if (this.state_ === 'ready') this.channel_?.send(type, payload, codec as PayloadCodec | undefined);}/**@@ -165,6 +171,7 @@ export class ClientSession {try {return await this.channel_!.request<Res, Req>(type, payload, {idempotencyKey: key,+ codec: options.codec,timeoutMs: options.timeoutMs ?? this.options_.requestTimeoutMs,});} catch (err) {@@ -207,7 +214,7 @@ export class ClientSession {this.attached_.add(type);channel.on(type, (payload) => {for (const h of [...(this.listeners_.get(type) ?? [])]) h(payload);- });+ }, this.eventCodecs_.get(type));}private dial_(): void {@@ -250,7 +257,7 @@ export class ClientSession {const credentials = await o.credentials();const sent = Date.now();const res = await channel.request<SessionHelloResponse, SessionHelloRequest>(- SESSION_HELLO, { version: SESSION_PROTOCOL_VERSION, credentials }, o.requestTimeoutMs,+ SESSION_HELLO, { version: SESSION_PROTOCOL_VERSION, wire: o.wire ?? 'json', credentials }, o.requestTimeoutMs,);if (this.channel_ !== channel) return;if (!res.ok) {@@ -258,6 +265,7 @@ export class ClientSession {else socket.close(1000, 'hello refused');return;}+ channel.setWire(res.wire ?? 'json');const received = Date.now();this.offsetMs_ = res.serverTimeMs + (received - sent) / 2 - received;this.welcome_ = { playerId: res.playerId, data: res.data };diff --git a/sdk/src/net/session/SessionHost.ts b/sdk/src/net/session/SessionHost.tsindex 6bb400bc5..1eb4045ce 100644--- a/sdk/src/net/session/SessionHost.ts+++ b/sdk/src/net/session/SessionHost.ts@@ -11,6 +11,8 @@*/import {NetChannel,+ type PayloadCodec,+ type RequestCodec,type NetHeartbeatOptions,type NetLimitOptions,type NetTransport,@@ -64,6 +66,12 @@ export interface SessionHostOptions<Ctx extends SessionContext> {helloTimeoutMs?: number;/** Most connections at once; the next is refused. Default unlimited. */maxSessions?: number;+ /**+ * The encoding players speak after the hello. `'json'` (default) keeps text frames. `'pb'` gives protobuf to every+ * client that asks for it and still lets one ask for JSON, which is how a session is read in a debugger.+ * `'pb-only'` refuses a client that asks for JSON and drops JSON frames afterwards.+ */+ wire?: 'json' | 'pb' | 'pb-only';/** Request timeout the channels use for the host's own calls. Default 10 s. */requestTimeoutMs?: number;}@@ -75,7 +83,7 @@ export type SessionHandler<Ctx extends SessionContext, Req, Res> =export interface ServerSession<Ctx extends SessionContext> {readonly ctx: Ctx;/** Fire-and-forget an event to this player. */- push(type: string, payload: unknown): void;+ push(type: string, payload: unknown, codec?: PayloadCodec<never>): void;close(code?: number, reason?: string): void;}@@ -86,7 +94,7 @@ interface Live<Ctx extends SessionContext> extends ServerSession<Ctx> {export class SessionHost<Ctx extends SessionContext = SessionContext> {private readonly options_: SessionHostOptions<Ctx>;private readonly store_: IdempotencyStore;- private readonly handlers_ = new Map<string, SessionHandler<Ctx, never, unknown>>();+ private readonly handlers_ = new Map<string, { handler: SessionHandler<Ctx, never, unknown>; codec: RequestCodec<any, any> | undefined }>();private readonly byPlayer_ = new Map<string, Live<Ctx>>();private readonly connections_ = new Set<AcceptedConnection>();private closed_ = false;@@ -111,19 +119,20 @@ export class SessionHost<Ctx extends SessionContext = SessionContext> {* after connections arrive; a connection sees the handlers present when its* hello succeeded.*/- handle<Req = unknown, Res = unknown>(type: string, handler: SessionHandler<Ctx, Req, Res>): () => void {+ handle<Req = unknown, Res = unknown>(type: string, handler: SessionHandler<Ctx, Req, Res>, codec?: RequestCodec<Req, Res>): () => void {if (type === SESSION_HELLO) throw new Error(`[net] "${SESSION_HELLO}" is the handshake and cannot be handled`);- this.handlers_.set(type, handler as SessionHandler<Ctx, never, unknown>);+ const entry = { handler: handler as SessionHandler<Ctx, never, unknown>, codec: codec as RequestCodec<any, any> | undefined };+ this.handlers_.set(type, entry);return () => {- if (this.handlers_.get(type) === (handler as unknown)) this.handlers_.delete(type);+ if (this.handlers_.get(type) === entry) this.handlers_.delete(type);};}/** Send an event to one player if they are connected to this host. */- push(playerId: string, type: string, payload: unknown): boolean {+ push(playerId: string, type: string, payload: unknown, codec?: PayloadCodec<never>): boolean {const live = this.byPlayer_.get(playerId);if (!live) return false;- live.push(type, payload);+ live.push(type, payload, codec);return true;}@@ -132,11 +141,11 @@ export class SessionHost<Ctx extends SessionContext = SessionContext> {* hosts, fan out through a shared bus and call this on each; a host does not* know about the others.*/- broadcast(type: string, payload: unknown, filter?: (ctx: Ctx) => boolean): number {+ broadcast(type: string, payload: unknown, filter?: (ctx: Ctx) => boolean, codec?: PayloadCodec<never>): number {let sent = 0;for (const live of this.byPlayer_.values()) {if (filter && !filter(live.ctx)) continue;- live.push(type, payload);+ live.push(type, payload, codec);sent++;}return sent;@@ -172,6 +181,12 @@ export class SessionHost<Ctx extends SessionContext = SessionContext> {if (!hello || hello.version !== SESSION_PROTOCOL_VERSION) {return { ok: false, error: `session protocol v${hello?.version}, server runs v${SESSION_PROTOCOL_VERSION}`, fatal: true };}+ const policy = this.options_.wire ?? 'json';+ const asked = hello.wire === 'pb' ? 'pb' : 'json';+ if (policy === 'pb-only' && asked !== 'pb') {+ return { ok: false, error: 'this server speaks protobuf only; the client asked for JSON', fatal: true };+ }+ const granted = policy !== 'json' && asked === 'pb' ? 'pb' : 'json';authenticating = true;try {const ctx = await this.options_.authenticate(hello.credentials, connection);@@ -181,7 +196,8 @@ export class SessionHost<Ctx extends SessionContext = SessionContext> {if (!this.connections_.has(connection)) return { ok: false, error: 'connection closed', fatal: false };clearTimeout(helloTimer);live = this.admit_(connection, channel, ctx);- return { ok: true, playerId: ctx.playerId, serverTimeMs: Date.now() };+ channel.setWire(granted, { acceptJson: policy !== 'pb-only' });+ return { ok: true, playerId: ctx.playerId, serverTimeMs: Date.now(), wire: granted };} catch (err) {if (err instanceof SessionRejected) return { ok: false, error: err.message, fatal: err.fatal };return { ok: false, error: 'authentication unavailable', fatal: false };@@ -231,7 +247,7 @@ export class SessionHost<Ctx extends SessionContext = SessionContext> {const live: Live<Ctx> = {ctx,channel,- push: (type, payload) => channel.send(type, payload),+ push: (type, payload, codec) => channel.send(type, payload, codec as PayloadCodec | undefined),close: (code, reason) => connection.close(code, reason),};this.byPlayer_.set(ctx.playerId, live);@@ -239,8 +255,8 @@ export class SessionHost<Ctx extends SessionContext = SessionContext> {previous?.close(SessionCloseCode.replaced, 'replaced by a newer connection');channel.setIdempotencyScope(ctx.playerId);- for (const [type, handler] of this.handlers_) {- channel.handle(type, (payload) => (handler as SessionHandler<Ctx, unknown, unknown>)(payload, ctx, live));+ for (const [type, { handler, codec }] of this.handlers_) {+ channel.handle(type, (payload) => (handler as SessionHandler<Ctx, unknown, unknown>)(payload, ctx, live), codec);}return live;}diff --git a/sdk/src/net/session/contract.ts b/sdk/src/net/session/contract.tsindex d62f07380..e2a42fa2c 100644--- a/sdk/src/net/session/contract.ts+++ b/sdk/src/net/session/contract.ts@@ -8,11 +8,12 @@* receipt — so a client built before a change cannot half-understand a* server built after it.*/-import type { MessageHandler } from '../NetChannel';+import type { MessageHandler, PayloadCodec, RequestCodec } from '../NetChannel';import { hashSeed } from '../../math/random';import type { ClientSession, SessionRequestOptions } from './ClientSession';import type { ServerSession, SessionContext, SessionHost } from './SessionHost';import { SchemaError, type Infer, type Schema } from './schema';+import { codecOf, jsonCodec } from './proto';export interface RequestDef<Req = unknown, Res = unknown> {req: Schema<Req>;@@ -58,6 +59,14 @@ export interface Contract<R extends RequestDefs, E extends EventDefs> {on<K extends keyof E & string>(session: ClientSession, type: K, handler: MessageHandler<Infer<E[K]>>): () => void;}+/** How a request travels on the protobuf wire: the codecs its schemas bring, JSON for a side that has none, nothing when neither has. */+function requestCodec(entry: RequestDef<any, any>): RequestCodec<any, any> | undefined {+ const req = codecOf(entry.req);+ const res = codecOf(entry.res);+ if (!req && !res) return undefined;+ return { req: req ?? jsonCodec, res: res ?? jsonCodec };+}+export function defineContract<R extends RequestDefs, E extends EventDefs = Record<never, never>>(def: { requests: R; events?: E },): Contract<R, E> {@@ -95,7 +104,7 @@ export function defineContract<R extends RequestDefs, E extends EventDefs = Recoif (err instanceof SchemaError) throw new Error(`server bug: ${name} replied with ${err.message}`);throw err;}- });+ }, requestCodec(entry));});const unknown = Object.keys(impl).filter((k) => !requestNames.includes(k));if (unknown.length > 0) {@@ -111,7 +120,7 @@ export function defineContract<R extends RequestDefs, E extends EventDefs = Recoconst entry = def.requests[name]!;out[name] = async (payload: unknown, options?: SessionRequestOptions) => {const checked = (entry.req as Schema<unknown>).parse(payload);- const reply = await session.request(name, checked, options);+ const reply = await session.request(name, checked, { ...options, codec: requestCodec(entry) });return entry.res.parse(reply);};}@@ -119,11 +128,11 @@ export function defineContract<R extends RequestDefs, E extends EventDefs = Reco},push(host, playerId, type, payload) {- return host.push(playerId, type, events[type]!.parse(payload));+ return host.push(playerId, type, events[type]!.parse(payload), codecOf(events[type]!) as PayloadCodec<never> | undefined);},broadcast(host, type, payload, filter) {- return host.broadcast(type, events[type]!.parse(payload), filter);+ return host.broadcast(type, events[type]!.parse(payload), filter, codecOf(events[type]!) as PayloadCodec<never> | undefined);},on(session, type, handler) {@@ -133,7 +142,7 @@ export function defineContract<R extends RequestDefs, E extends EventDefs = Recolet payload: Infer<E[typeof type]>;try { payload = schema.parse(raw) as Infer<E[typeof type]>; } catch { return; }handler(payload);- });+ }, codecOf(schema));},};}diff --git a/sdk/src/net/session/index.ts b/sdk/src/net/session/index.tsindex 49eb62ba2..235b83e35 100644--- a/sdk/src/net/session/index.ts+++ b/sdk/src/net/session/index.ts@@ -19,6 +19,9 @@ export {type NetHeartbeatOptions,type NetLimitOptions,type NetViolation,+ type PayloadCodec,+ type RequestCodec,+ type WireFormat,type NetRequestErrorCode,type RequestOptions,type MessageHandler,@@ -57,6 +60,7 @@ export {} from './ClientSession';export { acceptWebSocket, type WebSocketLike, type AcceptWebSocketOptions } from './acceptWebSocket';export { s, SchemaError, type Schema, type Infer } from './schema';+export { proto, jsonCodec, type ProtoMessage, type ProtoSchema } from './proto';export {defineContract,type Contract,diff --git a/sdk/src/net/session/proto.ts b/sdk/src/net/session/proto.tsnew file mode 100644index 000000000..f3ed24914--- /dev/null+++ b/sdk/src/net/session/proto.ts@@ -0,0 +1,52 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file proto.ts+ * @brief A protobuf message as a contract schema. The `.proto` file is the definition: the+ * generated message (estella proto gen) brings its codec and its shape, and the+ * contract takes both from it instead of repeating the fields in a second place.+ */+import type { PayloadCodec } from '../wire';+import type { Schema } from './schema';++/** What the generator writes for each message: a codec, plus a text naming its fields. */+export interface ProtoMessage<T> extends PayloadCodec<T> {+ /** The message's fields written as text, so two builds can tell whether they agree. */+ readonly shape: string;+}++export interface ProtoSchema<T> extends Schema<T> {+ readonly codec: PayloadCodec<T>;+}++/**+ * Use a generated message as a request, reply or event type. A value that reaches the contract has+ * already been read and checked by the message's own codec, so `check` is for what a `.proto` cannot say:+ * ranges, lengths, relations between fields. Throw from it to refuse.+ */+export function proto<T>(message: ProtoMessage<T>, check?: (value: T) => void): ProtoSchema<T> {+ return {+ codec: message,+ parse(value) {+ check?.(value as T);+ return value as T;+ },+ describe: () => `proto(${message.shape})`,+ };+}++const utf8 = new TextEncoder();+const utf8Back = new TextDecoder();++/** Plain JSON in both directions: stands in for the side of a request that is not a `proto`. */+export const jsonCodec: PayloadCodec = {+ encode: (value) => utf8.encode(JSON.stringify(value)),+ decode: (bytes) => JSON.parse(utf8Back.decode(bytes)),+ toJSON: (value) => value,+ fromJSON: (json) => json,+};++/** The codec a schema brings, if it is a {@link proto}. */+export function codecOf<T>(schema: Schema<T>): PayloadCodec<T> | undefined {+ return (schema as Partial<ProtoSchema<T>>).codec;+}diff --git a/sdk/src/net/session/protocol.ts b/sdk/src/net/session/protocol.tsindex 5d50a1a3f..085452589 100644--- a/sdk/src/net/session/protocol.ts+++ b/sdk/src/net/session/protocol.ts@@ -26,6 +26,8 @@ export const SessionCloseCode = {export interface SessionHelloRequest {version: number;+ /** The encoding the client wants to speak after the hello. Absent means JSON. */+ wire?: 'json' | 'pb';/** Whatever the game's `authenticate` understands: a token, a device id. */credentials: unknown;}@@ -36,6 +38,8 @@ export type SessionHelloResponse =playerId: string;/** The server's clock at the moment it answered, in epoch milliseconds. */serverTimeMs: number;+ /** The encoding both ends write from now on. Absent means JSON. */+ wire?: 'json' | 'pb';/** Anything the game wants the client to have at once (a renewed token). */data?: unknown;}diff --git a/sdk/src/net/wire.ts b/sdk/src/net/wire.tsnew file mode 100644index 000000000..a230965db--- /dev/null+++ b/sdk/src/net/wire.ts@@ -0,0 +1,143 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file wire.ts+ * @brief The two ways a NetChannel's control messages travel — the JSON text+ * envelope and the protobuf binary envelope — and the codec a payload+ * brings so it can travel either way.+ *+ * The binary envelope is one fixed message, so the channel never needs to know a+ * game's types: it moves `payload` bytes the contract's codec made.+ *+ * message Envelope {+ * uint32 kind = 1; // 1 event, 2 request, 3 response, 4 ping, 5 pong+ * string type = 2; // the event or request name+ * uint32 id = 3; // request id, or the ping number+ * string key = 4; // idempotency key+ * string error = 5; // a failed response's message+ * bytes payload = 6; // present when there is a value+ * }+ *+ * A binary frame is one byte of channel number, then its body. Channel 255 is this+ * envelope; the other numbers stay with the game and with replication.+ */++/** The channel number of binary frames that carry a control message. */+export const CONTROL_CHANNEL = 255;++/** Which encoding a channel writes. It reads both. */+export type WireFormat = 'json' | 'pb';++/**+ * How one message type's payload becomes bytes (protobuf wire) or JSON (the debugging wire).+ * A generated protobuf message is one, as it stands.+ */+export interface PayloadCodec<T = unknown> {+ encode(value: T): Uint8Array;+ decode(bytes: Uint8Array): T;+ /** The value as JSON-safe data; the debugging wire carries this. */+ toJSON(value: T): unknown;+ /** Check JSON-safe data and rebuild the value; throws on anything that is not the message. */+ fromJSON(json: unknown): T;+}++export type EnvelopeKind = 'event' | 'req' | 'res' | 'ping' | 'pong';++/** One control message, whichever way it travelled. `payload` is a protobuf-wire value as bytes. */+export interface Envelope {+ kind: EnvelopeKind;+ type?: string;+ id?: number;+ key?: string;+ error?: string;+ payload?: Uint8Array;+}++const KINDS: EnvelopeKind[] = ['event', 'req', 'res', 'ping', 'pong'];+const encoder = new TextEncoder();+const decoder = new TextDecoder('utf-8', { fatal: true });++function varint(out: number[], value: number): void {+ let v = value >>> 0;+ while (v >= 128) { out.push((v & 127) | 128); v >>>= 7; }+ out.push(v);+}++function field(out: number[], number: number, wireType: number): void {+ varint(out, (number << 3) | wireType);+}++function text(out: number[], number: number, value: string): void {+ const bytes = encoder.encode(value);+ field(out, number, 2);+ varint(out, bytes.length);+ for (const b of bytes) out.push(b);+}++/** A binary frame: the control channel byte, then the envelope. */+export function encodeEnvelope(e: Envelope): ArrayBuffer {+ const head: number[] = [CONTROL_CHANNEL];+ field(head, 1, 0); varint(head, KINDS.indexOf(e.kind) + 1);+ if (e.type !== undefined) text(head, 2, e.type);+ if (e.id !== undefined) { field(head, 3, 0); varint(head, e.id); }+ if (e.key !== undefined) text(head, 4, e.key);+ if (e.error !== undefined) text(head, 5, e.error);+ const payload = e.payload;+ if (payload !== undefined) { field(head, 6, 2); varint(head, payload.length); }+ const frame = new Uint8Array(head.length + (payload?.length ?? 0));+ frame.set(head);+ if (payload) frame.set(payload, head.length);+ return frame.buffer;+}++/**+ * Read a control frame's body (the bytes after the channel byte). Returns null for anything+ * that is not a well-formed envelope: a peer's mistake is never an exception here.+ */+export function decodeEnvelope(body: Uint8Array): Envelope | null {+ let pos = 0;+ const read = (): number => {+ let result = 0;+ let mul = 1;+ for (let i = 0; i < 5; i++) {+ const b = body[pos++];+ if (b === undefined) throw new RangeError('truncated');+ result += (b & 127) * mul;+ if (!(b & 128)) return result;+ mul *= 128;+ }+ throw new RangeError('varint too long');+ };+ const take = (): Uint8Array => {+ const n = read();+ if (pos + n > body.length) throw new RangeError('truncated');+ const out = body.subarray(pos, pos + n);+ pos += n;+ return out;+ };+ try {+ const e: Envelope = { kind: 'event' };+ let kind = 0;+ while (pos < body.length) {+ const tag = read();+ const number = Math.floor(tag / 8);+ const wire = tag & 7;+ if (number === 1 && wire === 0) kind = read();+ else if (number === 2 && wire === 2) e.type = decoder.decode(take());+ else if (number === 3 && wire === 0) e.id = read();+ else if (number === 4 && wire === 2) e.key = decoder.decode(take());+ else if (number === 5 && wire === 2) e.error = decoder.decode(take());+ else if (number === 6 && wire === 2) e.payload = take();+ else if (wire === 0) read();+ else if (wire === 2) take();+ else if (wire === 1) pos += 8;+ else if (wire === 5) pos += 4;+ else return null;+ }+ if (kind < 1 || kind > KINDS.length || pos > body.length) return null;+ e.kind = KINDS[kind - 1]!;+ return e;+ } catch {+ return null;+ }+}diff --git a/sdk/tests/net-wire-pb.test.ts b/sdk/tests/net-wire-pb.test.tsnew file mode 100644index 000000000..6599a80c5--- /dev/null+++ b/sdk/tests/net-wire-pb.test.ts@@ -0,0 +1,320 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, it, expect } from 'vitest';+import { NetChannel, type PayloadCodec } from '../src/net/NetChannel';+import { MemoryIdempotencyStore } from '../src/net/IdempotencyStore';+import { MemoryTransport } from '../src/net/MemoryTransport';+import { CONTROL_CHANNEL, decodeEnvelope, encodeEnvelope } from '../src/net/wire';+import { ClientSession } from '../src/net/session/ClientSession';+import { SessionHost, type AcceptedConnection, type SessionContext } from '../src/net/session/SessionHost';+import { defineContract } from '../src/net/session/contract';+import { proto, type ProtoMessage } from '../src/net/session/proto';+import { s } from '../src/net/session/schema';+import type { PlatformSocket, PlatformSocketEvents } from '../src/platform/types';++interface Item { n: number; name: string }++/** A message written by hand: one byte for `n`, then the name. Stands for a generated one. */+const item: ProtoMessage<Item> = {+ shape: 'Item{1:uint32 n,2:string name}',+ encode: (v) => Uint8Array.from([v.n, ...new TextEncoder().encode(v.name)]),+ decode: (b) => {+ if (b.length < 1) throw new Error('Item is empty');+ return { n: b[0]!, name: new TextDecoder().decode(b.subarray(1)) };+ },+ toJSON: (v) => ({ n: v.n, name: v.name }),+ fromJSON: (j) => {+ const o = j as Partial<Item> | null;+ if (!o || typeof o.n !== 'number' || typeof o.name !== 'string') throw new Error('not an Item');+ return { n: o.n, name: o.name };+ },+};++type Frame = string | ArrayBuffer;++/** Two channels over a pipe that records every frame. */+function pair(opts: ConstructorParameters<typeof NetChannel>[1] = {}) {+ const [ta, tb] = MemoryTransport.pair();+ const frames: Frame[] = [];+ const tap = (t: MemoryTransport) => {+ const send = t.send.bind(t);+ t.send = (d: Frame) => { frames.push(d); send(d); };+ };+ tap(ta);+ const a = new NetChannel(ta);+ const b = new NetChannel(tb, opts);+ return { a, b, frames };+}++describe('the binary envelope', () => {+ it('round-trips every field', () => {+ const frame = new Uint8Array(encodeEnvelope({ kind: 'req', type: 'order:place', id: 7, key: 'k-1', payload: Uint8Array.from([1, 2, 3]) }));+ expect(frame[0]).toBe(CONTROL_CHANNEL);+ expect(decodeEnvelope(frame.subarray(1))).toEqual({ kind: 'req', type: 'order:place', id: 7, key: 'k-1', payload: Uint8Array.from([1, 2, 3]) });+ const failed = new Uint8Array(encodeEnvelope({ kind: 'res', id: 7, error: 'boom' }));+ expect(decodeEnvelope(failed.subarray(1))).toEqual({ kind: 'res', id: 7, error: 'boom' });+ });++ it('keeps "no value" apart from "an empty value"', () => {+ const none = decodeEnvelope(new Uint8Array(encodeEnvelope({ kind: 'res', id: 1 })).subarray(1))!;+ const empty = decodeEnvelope(new Uint8Array(encodeEnvelope({ kind: 'res', id: 1, payload: new Uint8Array(0) })).subarray(1))!;+ expect(none.payload).toBeUndefined();+ expect(empty.payload).toEqual(new Uint8Array(0));+ });++ it('is null for anything that is not an envelope, and never throws', () => {+ for (const bad of [[], [0x08], [0x08, 0x09], [0x12, 0x40, 0x41], [0x08, 0x01, 0x80], [0x0f], [0x08, 0xff, 0xff, 0xff, 0xff, 0xff, 0x7f]]) {+ expect(decodeEnvelope(Uint8Array.from(bad)), JSON.stringify(bad)).toBeNull();+ }+ // text that is not UTF-8 in the type+ expect(decodeEnvelope(Uint8Array.from([0x08, 0x01, 0x12, 0x01, 0xff]))).toBeNull();+ });++ it('skips fields it does not know', () => {+ const base = new Uint8Array(encodeEnvelope({ kind: 'event', type: 'x' })).subarray(1);+ const withExtra = Uint8Array.from([...base, 0x98, 0x06, 0x05, 0xa2, 0x06, 0x01, 0x41]);+ expect(decodeEnvelope(withExtra)).toEqual({ kind: 'event', type: 'x' });+ });+});++describe('a channel on the protobuf wire', () => {+ it('writes binary frames on the control channel and reads them back', async () => {+ const { a, b, frames } = pair();+ a.setWire('pb');+ b.handle<Item, Item>('echo', (v) => ({ n: v.n + 1, name: v.name.toUpperCase() }), { req: item, res: item });+ const got = await a.request<Item, Item>('echo', { n: 4, name: 'abc' }, { codec: { req: item, res: item } });+ expect(got).toEqual({ n: 5, name: 'ABC' });+ const first = frames[0] as ArrayBuffer;+ expect(first).toBeInstanceOf(ArrayBuffer);+ expect(new Uint8Array(first)[0]).toBe(CONTROL_CHANNEL);+ // the payload on the wire is the codec's bytes, not JSON text+ expect(Buffer.from(first).includes(Buffer.from([4, 0x61, 0x62, 0x63]))).toBe(true);+ });++ it('answers in the wire the request came on: each side reads both', async () => {+ const { a, b } = pair();+ a.setWire('pb');+ b.setWire('json');+ b.handle<Item, Item>('echo', (v) => v, { req: item, res: item });+ expect(await a.request('echo', { n: 1, name: 'x' }, { codec: { req: item, res: item } })).toEqual({ n: 1, name: 'x' });+ });++ it('carries events, with a codec and without one', () => {+ const { a, b } = pair();+ a.setWire('pb');+ const seen: unknown[] = [];+ b.on<Item>('item', (v) => seen.push(v), item);+ b.on('plain', (v) => seen.push(v));+ a.send('item', { n: 9, name: 'z' }, item);+ a.send('plain', { any: ['thing', 1, null] });+ expect(seen).toEqual([{ n: 9, name: 'z' }, { any: ['thing', 1, null] }]);+ });++ it('uses the JSON form of a codec on the JSON wire, and checks it', async () => {+ const { a, b, frames } = pair();+ b.handle<Item, Item>('echo', (v) => v, { req: item, res: item });+ expect(await a.request('echo', { n: 2, name: 'q' }, { codec: { req: item, res: item } })).toEqual({ n: 2, name: 'q' });+ expect(typeof frames[0]).toBe('string');+ // a request that is not an Item is refused before the handler sees it+ await expect(a.request('echo', { n: 'two' }, { codec: { req: { ...item, toJSON: (v) => v }, res: item } })).rejects.toThrow(/invalid echo request: not an Item/);+ });++ it('refuses a payload the codec cannot read, as an answer to that request', async () => {+ const { a, b } = pair();+ a.setWire('pb');+ b.handle<Item, Item>('echo', (v) => v, { req: item, res: item });+ const empty: PayloadCodec<Item> = { ...item, encode: () => new Uint8Array(0) };+ await expect(a.request('echo', { n: 1, name: 'x' }, { codec: { req: empty, res: item } })).rejects.toThrow(/invalid echo request: Item is empty/);+ });++ it('answers a retried request from memory, in either wire, running the handler once', async () => {+ const store = new MemoryIdempotencyStore();+ const { a, b } = pair({ idempotency: store });+ let runs = 0;+ b.handle<Item, Item>('place', (v) => { runs++; return { n: runs, name: v.name }; }, { req: item, res: item });+ const codec = { req: item, res: item };+ a.setWire('pb');+ const first = await a.request<Item, Item>('place', { n: 1, name: 'o' }, { codec, idempotencyKey: 'k' });+ a.setWire('json');+ const again = await a.request<Item, Item>('place', { n: 1, name: 'o' }, { codec, idempotencyKey: 'k' });+ expect(runs).toBe(1);+ expect(again).toEqual(first);+ });++ it('keeps a retried answer in JSON form, so a store that serialises it can still replay it', async () => {+ interface Blob { blob: Uint8Array }+ const blobCodec: PayloadCodec<Blob> = {+ encode: (v) => v.blob,+ decode: (b) => ({ blob: b }),+ toJSON: (v) => ({ blob: Array.from(v.blob) }),+ fromJSON: (j) => ({ blob: Uint8Array.from((j as { blob: number[] }).blob) }),+ };+ // what a database does to a value on its way in and out+ class Serialising extends MemoryIdempotencyStore {+ override finish(key: string, outcome: { d?: unknown }) { return super.finish(key, JSON.parse(JSON.stringify(outcome))); }+ }+ const { a, b } = pair({ idempotency: new Serialising() });+ let runs = 0;+ b.handle<Blob, Blob>('get', () => { runs++; return { blob: Uint8Array.from([7, 8, 9]) }; }, { req: blobCodec, res: blobCodec });+ const codec = { req: blobCodec, res: blobCodec };+ a.setWire('pb');+ const first = await a.request<Blob, Blob>('get', { blob: new Uint8Array(0) }, { codec, idempotencyKey: 'k' });+ const again = await a.request<Blob, Blob>('get', { blob: new Uint8Array(0) }, { codec, idempotencyKey: 'k' });+ expect(runs).toBe(1);+ expect(Array.from(first.blob)).toEqual([7, 8, 9]);+ expect(Array.from(again.blob)).toEqual([7, 8, 9]);+ });++ it('limits control messages whichever wire they came on', () => {+ const violations: string[] = [];+ const { a, b } = pair({ limits: { messagesPerSecond: 1, burst: 2, onViolation: (k) => violations.push(k) } });+ a.setWire('pb');+ let seen = 0;+ b.on('e', () => seen++);+ for (let i = 0; i < 5; i++) a.send('e', i);+ expect(seen).toBe(2);+ expect(violations).toEqual(['rate', 'rate', 'rate']);+ });++ it('drops JSON frames once the peer has agreed to protobuf, and says so', () => {+ const violations: string[] = [];+ const { a, b } = pair({ limits: { onViolation: (k) => violations.push(k) } });+ b.setWire('pb', { acceptJson: false });+ let seen = 0;+ b.on('e', () => seen++);+ a.send('e', 1);+ a.setWire('pb');+ a.send('e', 2);+ expect(seen).toBe(1);+ expect(violations).toEqual(['wire']);+ });++ it('keeps channel 255 for itself', () => {+ const { a } = pair();+ expect(() => a.sendBinary(CONTROL_CHANNEL, new Uint8Array(1))).toThrow(/reserved/);+ expect(() => a.onBinary(CONTROL_CHANNEL, () => undefined)).toThrow(/reserved/);+ expect(() => a.onBinary(254, () => undefined)).not.toThrow();+ });++ it('ignores a malformed control frame', () => {+ const { b } = pair();+ let seen = 0;+ b.on('e', () => seen++);+ (b as unknown as { handleIncoming_(d: ArrayBuffer): void }).handleIncoming_(Uint8Array.from([CONTROL_CHANNEL, 0x08, 0x63]).buffer);+ expect(seen).toBe(0);+ });+});++// ── a whole session ─────────────────────────────────────────────────────────────────────────────++interface Ctx extends SessionContext { name: string }++function network(host: SessionHost<Ctx>) {+ const frames: Frame[] = [];+ const socket = (): PlatformSocket => {+ const events = new Map<string, Set<(...a: never[]) => void>>();+ const emit = <K extends keyof PlatformSocketEvents>(e: K, ...a: PlatformSocketEvents[K]) =>+ events.get(e)?.forEach((f) => (f as (...x: PlatformSocketEvents[K]) => void)(...a));+ const toServer = new Set<(d: Frame) => void>();+ const closing = new Set<() => void>();+ let open = false;+ const shutdown = (code: number, reason: string) => {+ if (!open) return;+ open = false;+ client.readyState = 'closed';+ queueMicrotask(() => { emit('close', code, reason); closing.forEach((h) => h()); });+ };+ const client: PlatformSocket = {+ delivery: 'reliable-ordered',+ readyState: 'closed',+ on: (e, h) => { let set = events.get(e); if (!set) { set = new Set(); events.set(e, set); } set.add(h as never); return () => set!.delete(h as never); },+ connect: () => {+ client.readyState = 'connecting';+ queueMicrotask(() => { open = true; client.readyState = 'open'; host.accept(conn); emit('open'); });+ },+ send: (d) => { frames.push(d); if (open) queueMicrotask(() => { if (open) toServer.forEach((h) => h(d)); }); },+ close: (code = 1000, reason = '') => shutdown(code, reason),+ };+ const conn: AcceptedConnection = {+ transport: {+ send: (d) => { frames.push(d); if (open) queueMicrotask(() => { if (open) emit('message', d); }); },+ on: (_e, h) => { toServer.add(h); return () => toServer.delete(h); },+ },+ close: (code = 1000, reason = '') => shutdown(code, reason),+ onClose: (h) => { closing.add(h); return () => closing.delete(h); },+ };+ return client;+ };+ return { socket, frames };+}++const contract = defineContract({+ requests: {+ place: { req: proto(item, (v) => { if (v.n > 200) throw new Error('n is over 200'); }), res: proto(item) },+ legacy: { req: s.object({ a: s.int() }), res: s.object({ a: s.int() }) },+ },+ events: { tick: proto(item) },+});++function session(hostWire: 'json' | 'pb' | 'pb-only', clientWire: 'json' | 'pb') {+ const host = new SessionHost<Ctx>({ authenticate: (c) => ({ playerId: String(c), name: 'p' }), wire: hostWire, heartbeat: false });+ contract.serve(host, {+ place: (v) => ({ n: v.n + 1, name: `${v.name}!` }),+ legacy: (v) => ({ a: v.a * 2 }),+ });+ const net = network(host);+ const client = new ClientSession({ connect: net.socket, credentials: () => 'ann', wire: clientWire, heartbeat: false, retries: 0 });+ return { host, net, client, calls: contract.client(client) };+}++const kinds = (frames: Frame[]) => frames.map((f) => (typeof f === 'string' ? 'text' : 'binary'));++describe('a session choosing its wire', () => {+ for (const [hostWire, clientWire, spoken] of [+ ['pb', 'pb', 'pb'], ['pb', 'json', 'json'], ['json', 'pb', 'json'], ['json', 'json', 'json'], ['pb-only', 'pb', 'pb'],+ ] as const) {+ it(`host ${hostWire}, client ${clientWire}: speaks ${spoken}, and the contract works`, async () => {+ const { net, client, calls } = session(hostWire, clientWire);+ await client.start();+ net.frames.length = 0;+ expect(await calls.place({ n: 4, name: 'a' })).toEqual({ n: 5, name: 'a!' });+ // a request that is not a proto still works, whatever the wire+ expect(await calls.legacy({ a: 21 })).toEqual({ a: 42 });+ expect(new Set(kinds(net.frames))).toEqual(new Set([spoken === 'pb' ? 'binary' : 'text']));+ client.close();+ });+ }++ it('pushes a proto event, decoded and checked', async () => {+ const { host, client } = session('pb', 'pb');+ const seen: Item[] = [];+ contract.on(client, 'tick', (v) => seen.push(v));+ await client.start();+ contract.push(host as unknown as SessionHost<never>, 'ann', 'tick', { n: 3, name: 'now' });+ await new Promise((r) => setTimeout(r, 5));+ expect(seen).toEqual([{ n: 3, name: 'now' }]);+ client.close();+ });++ it('turns a client away that asks for JSON from a protobuf-only server, for good', async () => {+ const { client } = session('pb-only', 'json');+ await expect(client.start()).rejects.toThrow(/protobuf only/);+ });++ it('runs the contract\'s own check on a request, on either wire', async () => {+ for (const wire of ['json', 'pb'] as const) {+ const { client, calls } = session('pb', wire);+ await client.start();+ await expect(calls.place({ n: 201, name: 'x' })).rejects.toThrow(/n is over 200/);+ client.close();+ }+ });++ it('changes the contract fingerprint when a message\'s shape changes', () => {+ const other = defineContract({ requests: { place: { req: proto({ ...item, shape: 'Item{1:uint32 n}' }), res: proto(item) } } });+ const same = defineContract({ requests: { place: { req: proto(item), res: proto(item) } } });+ const base = defineContract({ requests: { place: { req: proto(item), res: proto(item) } } });+ expect(same.fingerprint).toBe(base.fingerprint);+ expect(other.fingerprint).not.toBe(base.fingerprint);+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex efc661fe9..a47b0fc98 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -3026,6 +3026,8 @@ export const NOTED = {{"note":"Optional tools a project switches on, fetched and checked by the engine."},'feat(tools): Protobuf, with .proto files turned into TypeScript types and a binary codec':{"note":"Protobuf as a second optional tool: .proto files become TypeScript types and a binary codec."},+ 'feat(net): a session can speak protobuf, with the JSON wire kept for debugging':+ {"note":"A session can speak protobuf, with the JSON wire kept for debugging."},'fix(tools): a host that cannot read the engine version says so instead of asking the mirror for v0.0.0':{"internal":"A fix inside the optional tools feature, which has not shipped yet."},"perf(sdk): a blank mini-game package no longer carries terrain and water":