@driftengine/network 3.61.0

package/dist/websocket.js

@@ -0,0 +1,105 @@
+/**
+ * `Transport` over a WebSocket, which is the browser default.
+ *
+ * **Ordered and reliable, which is the wrong guarantee for inputs and the right one for this
+ * topology.** A dropped input frame blocks the frames behind it while TCP retransmits, and by the
+ * time it arrives the tick it belonged to is usually past — so a lockstep peer waits for news it no
+ * longer needs. The unordered answer is `WebRtcTransport` beside this.
+ *
+ * It is the default anyway, for a reason outside the protocol: WebSocket and WebTransport are what
+ * a relay service realistically speaks, whatever language it is written in. A transport nothing can
+ * connect to is not a default.
+ *
+ * ---
+ *
+ * ## The socket is supplied and its type is declared structurally
+ *
+ * No `WebSocket` type is named. `@driftengine/network` imports `@driftengine/entities` and nothing
+ * else, and that is the property that lets an authoritative host run it — a package that named a
+ * DOM type would compile only where a DOM does. The shape below is what a browser `WebSocket` and
+ * a Node `ws` socket both satisfy, which is also what makes the tests possible.
+ *
+ * The socket is **supplied rather than constructed**, so a consumer owns the URL, the protocols,
+ * the credentials and the reconnection policy. A transport that opened its own connection would be
+ * making four decisions that belong to whoever is paying for the server.
+ */
+import { BROADCAST, } from './transport.js';
+/** The `readyState` values, which are the same three numbers everywhere. */
+const OPEN = 1;
+const CLOSED = 3;
+export class WebSocketTransport {
+    self;
+    socket;
+    maxQueued;
+    arrived = [];
+    closedByUs = false;
+    droppedCount = 0;
+    constructor(options) {
+        this.socket = options.socket;
+        this.self = options.self ?? -1;
+        this.maxQueued = Math.max(1, options.maxQueued ?? 1024);
+        /* Binary frames, or every message arrives as a string and every payload is corrupted by the
+           round trip through UTF-8. Set before any listener, because a frame can arrive immediately. */
+        if ('binaryType' in this.socket)
+            this.socket.binaryType = 'arraybuffer';
+        this.socket.addEventListener('message', (event) => {
+            const data = event.data;
+            const bytes = toBytes(data);
+            if (bytes === null)
+                return;
+            if (this.arrived.length >= this.maxQueued) {
+                this.arrived.shift();
+                this.droppedCount += 1;
+            }
+            this.arrived.push(bytes);
+        });
+    }
+    get state() {
+        if (this.closedByUs || this.socket.readyState === CLOSED)
+            return 'closed';
+        return this.socket.readyState === OPEN ? 'open' : 'connecting';
+    }
+    /** Messages dropped because nothing drained. A consumer watching for a stalled tab reads this. */
+    get dropped() {
+        return this.droppedCount;
+    }
+    /**
+     * Send, or do nothing if the socket is not open yet.
+     *
+     * **Nothing is queued while connecting, deliberately.** Every message this package sends is
+     * addressed to a tick, and a tick that has passed by the time the socket opens is a tick nobody
+     * can use. Flushing a backlog of stale inputs on connect is worse than having sent none.
+     */
+    send(_to, message) {
+        if (this.state !== 'open')
+            return;
+        this.socket.send(message);
+    }
+    drain(into) {
+        for (const message of this.arrived)
+            into(BROADCAST, message);
+        this.arrived.length = 0;
+    }
+    close() {
+        this.closedByUs = true;
+        this.arrived.length = 0;
+        this.socket.close();
+    }
+}
+/**
+ * A message's bytes, whatever the socket handed over, or null.
+ *
+ * Browsers deliver an `ArrayBuffer` when `binaryType` is set, `ws` under Node delivers a `Buffer`,
+ * and a socket left on its default delivers a string. The first two are usable and the third is
+ * not: a payload that has been through UTF-8 has had every byte above 0x7f replaced.
+ */
+function toBytes(data) {
+    if (data instanceof Uint8Array)
+        return data;
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (ArrayBuffer.isView(data)) {
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    }
+    return null;
+}

package/dist/wire.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The framing, which is small on purpose.
+ *
+ * **An input payload is opaque bytes and this file never looks inside one.** `AGENTS.md`: engine
+ * APIs take positions, colours, sizes and time and never another game's noun. A wire format that
+ * knew a player had a throttle would be a racing engine's wire format.
+ *
+ * ---
+ *
+ * ## Fixed widths rather than varints
+ *
+ * A varint saves two bytes on a tick number and costs a branch per field and a length that cannot
+ * be known before encoding. At sixty inputs a second with a payload of a handful of bytes, the
+ * saving is under a kilobyte a minute and the cost is that nothing can be written into a
+ * preallocated buffer without measuring first. Fixed widths make an input frame a constant size,
+ * which is what lets a session own one buffer for the process.
+ *
+ * ## The widths, and what each one refuses
+ *
+ * - **Participant, one byte.** 255 participants in a session, and 255 is not a limit anybody is
+ *   near: lockstep stops being viable in single figures, and an authoritative host with 255
+ *   predicting clients has bandwidth problems long before it has an id problem.
+ * - **Tick, four bytes.** At 60 Hz an unsigned 32-bit tick counter is 2.2 years of continuous
+ *   simulation. A session that reaches it has a different problem.
+ * - **Payload length, two bytes.** 65,535 bytes, which is far more than an input and far less than
+ *   a full world. A state message that does not fit is a state message that should have been a
+ *   delta.
+ *
+ * ## The version is in every `join`, not in every message
+ *
+ * A byte per message to say what the protocol was is a byte per message spent on something that
+ * cannot change mid-session. The handshake carries it and a mismatch is refused there, which is the
+ * one place a peer can still be told why.
+ */
+export declare const PROTOCOL_VERSION = 1;
+export declare const MESSAGE_JOIN = 1;
+export declare const MESSAGE_WELCOME = 2;
+export declare const MESSAGE_INPUT = 3;
+export declare const MESSAGE_FINGERPRINT = 4;
+export declare const MESSAGE_STATE = 5;
+export declare const MESSAGE_ACK = 6;
+export declare const MESSAGE_PING = 7;
+/**
+ * Header bytes before an input run's payloads: kind, participant, first tick, count, stride.
+ *
+ * **An input message carries a *run* of consecutive ticks, and a run of one is the degenerate
+ * case.** That is not generality for its own sake — it is what makes lockstep survive a lossy link.
+ * An input is only useful for the tick it names, so retransmitting a lost one after a round trip
+ * delivers it too late to use; sending the last few inputs in *every* packet covers a loss before
+ * anybody notices, and costs a handful of bytes on a message that already has a header. A test at
+ * 15% loss is what turned this from a nicety into a requirement: without it a dropped input is lost
+ * for good and that peer's world is permanently wrong.
+ */
+export declare const INPUT_HEADER_BYTES: number;
+/** Header bytes before a state payload: kind, tick, length. */
+export declare const STATE_HEADER_BYTES: number;
+/** A fingerprint message is fixed: kind, participant, tick, and eight bytes of digest. */
+export declare const FINGERPRINT_BYTES: number;
+/** What a decoded message turned out to be. `kind` 0 means it did not decode. */
+export interface DecodedMessage {
+    kind: number;
+    participant: number;
+    tick: number;
+    /** Where the payloads start, and how long **each one** is. Zero when there is none. */
+    payloadAt: number;
+    payloadBytes: number;
+    /** How many consecutive ticks this message carries, starting at `tick`. One for everything else. */
+    count: number;
+    /** The sixteen-hex-character digest, for a fingerprint message; empty otherwise. */
+    digest: string;
+}
+export declare function createDecoded(): DecodedMessage;
+/**
+ * Write an input frame into `into`, answering how many bytes it used, or -1 when it does not fit.
+ *
+ * **-1 rather than a throw**, because the caller is a frame loop and `AGENTS.md` forbids throwing
+ * in one. A buffer too small is a caller's sizing bug and the honest report is a value they can
+ * branch on at the send site.
+ */
+export declare function encodeInput(into: Uint8Array, participant: number, firstTick: number, payloads: Uint8Array, stride?: number, count?: number): number;
+export declare function encodeState(into: Uint8Array, tick: number, payload: Uint8Array): number;
+export declare function encodeFingerprint(into: Uint8Array, participant: number, tick: number, digest: string): number;
+export declare function encodeJoin(into: Uint8Array): number;
+export declare function encodeWelcome(into: Uint8Array, participant: number, tick: number, participants: number): number;
+export declare function encodeAck(into: Uint8Array, participant: number, tick: number): number;
+/**
+ * Read a message's header into `out`. `false` when the bytes are not a message this version knows.
+ *
+ * **A payload is located rather than copied.** `payloadAt` and `payloadBytes` point into the buffer
+ * the caller was handed, which the transport may reuse the moment the sink returns — the same
+ * borrow `MessageSink` documents. A caller keeping a payload copies it, and one feeding it straight
+ * to `RewindLoop.supply` does not need to.
+ */
+export declare function decode(message: Uint8Array, out: DecodedMessage): boolean;

package/dist/wire.js

@@ -0,0 +1,238 @@
+/**
+ * The framing, which is small on purpose.
+ *
+ * **An input payload is opaque bytes and this file never looks inside one.** `AGENTS.md`: engine
+ * APIs take positions, colours, sizes and time and never another game's noun. A wire format that
+ * knew a player had a throttle would be a racing engine's wire format.
+ *
+ * ---
+ *
+ * ## Fixed widths rather than varints
+ *
+ * A varint saves two bytes on a tick number and costs a branch per field and a length that cannot
+ * be known before encoding. At sixty inputs a second with a payload of a handful of bytes, the
+ * saving is under a kilobyte a minute and the cost is that nothing can be written into a
+ * preallocated buffer without measuring first. Fixed widths make an input frame a constant size,
+ * which is what lets a session own one buffer for the process.
+ *
+ * ## The widths, and what each one refuses
+ *
+ * - **Participant, one byte.** 255 participants in a session, and 255 is not a limit anybody is
+ *   near: lockstep stops being viable in single figures, and an authoritative host with 255
+ *   predicting clients has bandwidth problems long before it has an id problem.
+ * - **Tick, four bytes.** At 60 Hz an unsigned 32-bit tick counter is 2.2 years of continuous
+ *   simulation. A session that reaches it has a different problem.
+ * - **Payload length, two bytes.** 65,535 bytes, which is far more than an input and far less than
+ *   a full world. A state message that does not fit is a state message that should have been a
+ *   delta.
+ *
+ * ## The version is in every `join`, not in every message
+ *
+ * A byte per message to say what the protocol was is a byte per message spent on something that
+ * cannot change mid-session. The handshake carries it and a mismatch is refused there, which is the
+ * one place a peer can still be told why.
+ */
+export const PROTOCOL_VERSION = 1;
+export const MESSAGE_JOIN = 1;
+export const MESSAGE_WELCOME = 2;
+export const MESSAGE_INPUT = 3;
+export const MESSAGE_FINGERPRINT = 4;
+export const MESSAGE_STATE = 5;
+export const MESSAGE_ACK = 6;
+export const MESSAGE_PING = 7;
+/**
+ * Header bytes before an input run's payloads: kind, participant, first tick, count, stride.
+ *
+ * **An input message carries a *run* of consecutive ticks, and a run of one is the degenerate
+ * case.** That is not generality for its own sake — it is what makes lockstep survive a lossy link.
+ * An input is only useful for the tick it names, so retransmitting a lost one after a round trip
+ * delivers it too late to use; sending the last few inputs in *every* packet covers a loss before
+ * anybody notices, and costs a handful of bytes on a message that already has a header. A test at
+ * 15% loss is what turned this from a nicety into a requirement: without it a dropped input is lost
+ * for good and that peer's world is permanently wrong.
+ */
+export const INPUT_HEADER_BYTES = 1 + 1 + 4 + 1 + 2;
+/** Header bytes before a state payload: kind, tick, length. */
+export const STATE_HEADER_BYTES = 1 + 4 + 2;
+/** A fingerprint message is fixed: kind, participant, tick, and eight bytes of digest. */
+export const FINGERPRINT_BYTES = 1 + 1 + 4 + 8;
+function writeU32(into, at, value) {
+    const v = value >>> 0;
+    into[at] = v & 0xff;
+    into[at + 1] = (v >>> 8) & 0xff;
+    into[at + 2] = (v >>> 16) & 0xff;
+    into[at + 3] = (v >>> 24) & 0xff;
+}
+function readU32(from, at) {
+    return ((from[at] |
+        (from[at + 1] << 8) |
+        (from[at + 2] << 16) |
+        (from[at + 3] << 24)) >>>
+        0);
+}
+export function createDecoded() {
+    return { kind: 0, participant: 0, tick: 0, payloadAt: 0, payloadBytes: 0, count: 0, digest: '' };
+}
+/**
+ * Write an input frame into `into`, answering how many bytes it used, or -1 when it does not fit.
+ *
+ * **-1 rather than a throw**, because the caller is a frame loop and `AGENTS.md` forbids throwing
+ * in one. A buffer too small is a caller's sizing bug and the honest report is a value they can
+ * branch on at the send site.
+ */
+export function encodeInput(into, participant, firstTick, payloads, stride = payloads.length, count = 1) {
+    const total = INPUT_HEADER_BYTES + stride * count;
+    if (into.length < total || stride > 0xffff || count > 0xff || count < 1)
+        return -1;
+    if (payloads.length < stride * count)
+        return -1;
+    into[0] = MESSAGE_INPUT;
+    into[1] = participant & 0xff;
+    writeU32(into, 2, firstTick);
+    into[6] = count & 0xff;
+    into[7] = stride & 0xff;
+    into[8] = (stride >>> 8) & 0xff;
+    into.set(payloads.subarray(0, stride * count), INPUT_HEADER_BYTES);
+    return total;
+}
+export function encodeState(into, tick, payload) {
+    const total = STATE_HEADER_BYTES + payload.length;
+    if (into.length < total || payload.length > 0xffff)
+        return -1;
+    into[0] = MESSAGE_STATE;
+    writeU32(into, 1, tick);
+    into[5] = payload.length & 0xff;
+    into[6] = (payload.length >>> 8) & 0xff;
+    into.set(payload, STATE_HEADER_BYTES);
+    return total;
+}
+export function encodeFingerprint(into, participant, tick, digest) {
+    if (into.length < FINGERPRINT_BYTES || digest.length !== 16)
+        return -1;
+    into[0] = MESSAGE_FINGERPRINT;
+    into[1] = participant & 0xff;
+    writeU32(into, 2, tick);
+    for (let i = 0; i < 8; i++) {
+        into[6 + i] = Number.parseInt(digest.slice(i * 2, i * 2 + 2), 16) & 0xff;
+    }
+    return FINGERPRINT_BYTES;
+}
+export function encodeJoin(into) {
+    if (into.length < 3)
+        return -1;
+    into[0] = MESSAGE_JOIN;
+    into[1] = PROTOCOL_VERSION & 0xff;
+    into[2] = (PROTOCOL_VERSION >>> 8) & 0xff;
+    return 3;
+}
+export function encodeWelcome(into, participant, tick, participants) {
+    if (into.length < 7)
+        return -1;
+    into[0] = MESSAGE_WELCOME;
+    into[1] = participant & 0xff;
+    writeU32(into, 2, tick);
+    into[6] = participants & 0xff;
+    return 7;
+}
+export function encodeAck(into, participant, tick) {
+    if (into.length < 6)
+        return -1;
+    into[0] = MESSAGE_ACK;
+    into[1] = participant & 0xff;
+    writeU32(into, 2, tick);
+    return 6;
+}
+const HEX = '0123456789abcdef';
+/**
+ * Read a message's header into `out`. `false` when the bytes are not a message this version knows.
+ *
+ * **A payload is located rather than copied.** `payloadAt` and `payloadBytes` point into the buffer
+ * the caller was handed, which the transport may reuse the moment the sink returns — the same
+ * borrow `MessageSink` documents. A caller keeping a payload copies it, and one feeding it straight
+ * to `RewindLoop.supply` does not need to.
+ */
+export function decode(message, out) {
+    out.kind = 0;
+    out.participant = 0;
+    out.tick = 0;
+    out.payloadAt = 0;
+    out.payloadBytes = 0;
+    out.count = 0;
+    out.digest = '';
+    if (message.length < 1)
+        return false;
+    const kind = message[0];
+    switch (kind) {
+        case MESSAGE_INPUT: {
+            if (message.length < INPUT_HEADER_BYTES)
+                return false;
+            const count = message[6];
+            const stride = message[7] | (message[8] << 8);
+            if (count < 1 || stride < 1)
+                return false;
+            if (message.length < INPUT_HEADER_BYTES + stride * count)
+                return false;
+            out.kind = kind;
+            out.participant = message[1];
+            out.tick = readU32(message, 2);
+            out.payloadAt = INPUT_HEADER_BYTES;
+            out.payloadBytes = stride;
+            out.count = count;
+            return true;
+        }
+        case MESSAGE_STATE: {
+            if (message.length < STATE_HEADER_BYTES)
+                return false;
+            const length = message[5] | (message[6] << 8);
+            if (message.length < STATE_HEADER_BYTES + length)
+                return false;
+            out.kind = kind;
+            out.tick = readU32(message, 1);
+            out.payloadAt = STATE_HEADER_BYTES;
+            out.payloadBytes = length;
+            return true;
+        }
+        case MESSAGE_FINGERPRINT: {
+            if (message.length < FINGERPRINT_BYTES)
+                return false;
+            out.kind = kind;
+            out.participant = message[1];
+            out.tick = readU32(message, 2);
+            let digest = '';
+            for (let i = 0; i < 8; i++) {
+                const byte = message[6 + i];
+                digest += HEX[(byte >>> 4) & 0xf] + HEX[byte & 0xf];
+            }
+            out.digest = digest;
+            return true;
+        }
+        case MESSAGE_JOIN: {
+            if (message.length < 3)
+                return false;
+            out.kind = kind;
+            /* The version rides in `tick`, which is the only numeric field a join has. */
+            out.tick = message[1] | (message[2] << 8);
+            return true;
+        }
+        case MESSAGE_WELCOME: {
+            if (message.length < 7)
+                return false;
+            out.kind = kind;
+            out.participant = message[1];
+            out.tick = readU32(message, 2);
+            out.payloadBytes = message[6];
+            return true;
+        }
+        case MESSAGE_ACK:
+        case MESSAGE_PING: {
+            if (message.length < 6)
+                return false;
+            out.kind = kind;
+            out.participant = message[1];
+            out.tick = readU32(message, 2);
+            return true;
+        }
+        default:
+            return false;
+    }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@driftengine/network",
+  "version": "3.61.0",
+  "description": "A transport seam, rewind and replay, lockstep and an authoritative host, on the fixed-step loop",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "drift-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.mjs",
+    "!src/**/__snapshots__",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@driftengine/entities": "3.61.0"
+  },
+  "devDependencies": {
+    "@driftengine/core": "3.61.0"
+  },
+  "author": "Drift Technologies",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drftrun/driftengine.git",
+    "directory": "packages/network"
+  },
+  "homepage": "https://github.com/drftrun/driftengine#readme",
+  "bugs": "https://github.com/drftrun/driftengine/issues",
+  "keywords": [
+    "driftengine",
+    "3d",
+    "webgl",
+    "webgpu",
+    "typescript",
+    "netcode",
+    "rollback",
+    "lockstep",
+    "prediction",
+    "multiplayer"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}