@series-inc/rundot-syncplay 5.23.0-beta.7

package/dist/ws-frame.js

@@ -0,0 +1,247 @@
+import { createHash } from 'node:crypto';
+import { createServer } from 'node:http';
+import { decodeUtf8, encodeUtf8 } from './canonical.js';
+/**
+ * Minimal RFC 6455 text-frame codec plus a connection-oriented server/client.
+ *
+ * The engine ships with zero runtime dependencies, so this hand-rolls just enough of the
+ * WebSocket wire format to carry small JSON control messages over a real socket. It supports
+ * unfragmented text frames up to 65535 bytes — sufficient for input/confirmed-input traffic.
+ * `local-ws-adapter.ts` and the M0 networked-authority spike share this codec.
+ */
+const webSocketGuid = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+export function webSocketAcceptKey(secWebSocketKey) {
+    return createHash('sha1').update(`${secWebSocketKey}${webSocketGuid}`).digest('base64');
+}
+export function encodeWebSocketTextFrame(text) {
+    const payload = encodeUtf8(text);
+    if (payload.byteLength > 65535) {
+        throw new Error('WebSocket text frame exceeds the 65535-byte codec limit');
+    }
+    const headerLength = payload.byteLength < 126 ? 2 : 4;
+    const frame = new Uint8Array(headerLength + payload.byteLength);
+    frame[0] = 0x81;
+    if (payload.byteLength < 126) {
+        frame[1] = payload.byteLength;
+    }
+    else {
+        frame[1] = 126;
+        frame[2] = Math.floor(payload.byteLength / 256);
+        frame[3] = payload.byteLength % 256;
+    }
+    frame.set(payload, headerLength);
+    return frame;
+}
+/** A minimal, bodyless close frame (opcode 0x8, FIN set). */
+export function encodeWebSocketCloseFrame() {
+    return new Uint8Array([0x88, 0x00]);
+}
+/**
+ * NEVER throws: this runs inside raw `socket.on('data')` handlers, where an
+ * uncaught throw is not routed to the 'error' listener and takes the process
+ * down — a handful of malformed bytes from any client would be an
+ * unauthenticated crash. Malformed input is reported as `kind: 'invalid'` so
+ * the receive loop can close the connection instead.
+ */
+export function readWebSocketFrame(bytes) {
+    if (bytes.byteLength < 2) {
+        return { kind: 'incomplete' };
+    }
+    const opcode = bytes[0] & 0x0f;
+    const masked = (bytes[1] & 0x80) !== 0;
+    // Capture the 7-bit tag BEFORE the 126 branch reassigns `length`: a 127-byte
+    // payload arrives in the 16-bit form and must not trip the 64-bit guard.
+    const lengthTag = bytes[1] & 0x7f;
+    let length = lengthTag;
+    let offset = 2;
+    if (lengthTag === 127) {
+        return { kind: 'invalid', reason: 'unsupported-64-bit-frame-length' };
+    }
+    if (lengthTag === 126) {
+        if (bytes.byteLength < 4) {
+            return { kind: 'incomplete' };
+        }
+        length = bytes[2] * 256 + bytes[3];
+        offset = 4;
+    }
+    const maskBytes = masked ? bytes.slice(offset, offset + 4) : undefined;
+    offset += masked ? 4 : 0;
+    if (bytes.byteLength < offset + length) {
+        return { kind: 'incomplete' };
+    }
+    const payload = bytes.slice(offset, offset + length);
+    if (maskBytes !== undefined) {
+        for (let index = 0; index < payload.byteLength; index += 1) {
+            payload[index] ^= maskBytes[index % 4];
+        }
+    }
+    let text;
+    try {
+        text = decodeUtf8(payload);
+    }
+    catch {
+        return { kind: 'invalid', reason: 'malformed-utf8-payload' };
+    }
+    return { kind: 'frame', frame: { opcode, text, bytesRead: offset + length } };
+}
+export async function startWebSocketServer(options) {
+    const path = options.path ?? '/';
+    const server = createServer((request, response) => {
+        if (request.url === '/health') {
+            response.statusCode = 200;
+            response.setHeader('content-type', 'text/plain');
+            response.end('ok');
+            return;
+        }
+        response.statusCode = 404;
+        response.end('not found');
+    });
+    server.on('upgrade', (request, socket, head) => {
+        if (new URL(request.url ?? '/', 'http://127.0.0.1').pathname !== path) {
+            socket.end('HTTP/1.1 404 Not Found\r\n\r\n');
+            return;
+        }
+        const key = request.headers['sec-websocket-key'];
+        if (typeof key !== 'string') {
+            socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
+            return;
+        }
+        socket.write([
+            'HTTP/1.1 101 Switching Protocols',
+            'Upgrade: websocket',
+            'Connection: Upgrade',
+            `Sec-WebSocket-Accept: ${webSocketAcceptKey(key)}`,
+            '\r\n',
+        ].join('\r\n'));
+        // The upgraded socket is a net.Socket at runtime; @types/node's upgrade signature omits a
+        // 'close' overload, so narrow it to the small surface this codec actually uses.
+        const connection = createServerConnection(socket);
+        options.onConnection(connection.handle, request);
+        if (head.byteLength > 0) {
+            connection.receive(head);
+        }
+    });
+    await new Promise((resolveListen) => {
+        server.listen(options.port ?? 0, '127.0.0.1', resolveListen);
+    });
+    const address = server.address();
+    if (address === null || typeof address === 'string') {
+        throw new Error('Could not determine WebSocket server port');
+    }
+    const port = address.port;
+    return {
+        port,
+        url: `ws://127.0.0.1:${port}${path}`,
+        close() {
+            return new Promise((resolveClose, rejectClose) => {
+                server.close((error) => (error === undefined ? resolveClose() : rejectClose(error)));
+            });
+        },
+    };
+}
+function createServerConnection(socket) {
+    let pending = new Uint8Array();
+    const messageHandlers = [];
+    const closeHandlers = [];
+    let closed = false;
+    function emitClose() {
+        if (closed) {
+            return;
+        }
+        closed = true;
+        for (const handler of closeHandlers) {
+            handler();
+        }
+    }
+    function receive(chunk) {
+        pending = concatBytes(pending, chunk);
+        let result = readWebSocketFrame(pending);
+        while (result.kind === 'frame') {
+            const frame = result.frame;
+            pending = pending.slice(frame.bytesRead);
+            if (frame.opcode === 0x8) {
+                socket.end(encodeWebSocketCloseFrame());
+                emitClose();
+                return;
+            }
+            if (frame.opcode === 0x1) {
+                const text = frame.text;
+                for (const handler of messageHandlers) {
+                    handler(text);
+                }
+            }
+            result = readWebSocketFrame(pending);
+        }
+        if (result.kind === 'invalid') {
+            // Malformed frame: close the connection instead of crashing the process.
+            socket.end(encodeWebSocketCloseFrame());
+            emitClose();
+        }
+    }
+    socket.on('data', (chunk) => receive(chunk));
+    socket.on('error', () => {
+        socket.destroy();
+        emitClose();
+    });
+    socket.on('close', emitClose);
+    const handle = {
+        send(text) {
+            if (!closed) {
+                socket.write(encodeWebSocketTextFrame(text));
+            }
+        },
+        onMessage(handler) {
+            messageHandlers.push(handler);
+        },
+        onClose(handler) {
+            closeHandlers.push(handler);
+        },
+        close() {
+            if (!closed) {
+                socket.end(encodeWebSocketCloseFrame());
+                emitClose();
+            }
+        },
+    };
+    return { handle, receive };
+}
+export async function connectWebSocketClient(url) {
+    const socket = new WebSocket(url);
+    const messageHandlers = [];
+    const closeHandlers = [];
+    socket.addEventListener('message', (event) => {
+        const text = String(event.data);
+        for (const handler of messageHandlers) {
+            handler(text);
+        }
+    });
+    socket.addEventListener('close', () => {
+        for (const handler of closeHandlers) {
+            handler();
+        }
+    });
+    await new Promise((resolveOpen, rejectOpen) => {
+        socket.addEventListener('open', () => resolveOpen(), { once: true });
+        socket.addEventListener('error', () => rejectOpen(new Error(`Could not connect to ${url}`)), { once: true });
+    });
+    return {
+        send(text) {
+            socket.send(text);
+        },
+        onMessage(handler) {
+            messageHandlers.push(handler);
+        },
+        onClose(handler) {
+            closeHandlers.push(handler);
+        },
+        close() {
+            socket.close();
+        },
+    };
+}
+function concatBytes(left, right) {
+    const output = new Uint8Array(left.byteLength + right.byteLength);
+    output.set(left, 0);
+    output.set(right, left.byteLength);
+    return output;
+}

package/package.json

@@ -0,0 +1,169 @@
+{
+  "name": "@series-inc/rundot-syncplay",
+  "version": "5.23.0-beta.7",
+  "description": "Offline-first deterministic multiplayer core for RUN.game",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/index.js"
+    },
+    "./creator": {
+      "types": "./dist/creator.d.ts",
+      "import": "./dist/creator.js",
+      "require": "./dist/cjs/creator.js",
+      "default": "./dist/creator.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js",
+      "require": "./dist/cjs/node.js",
+      "default": "./dist/node.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js",
+      "require": "./dist/cjs/browser.js",
+      "default": "./dist/browser.js"
+    },
+    "./tools": {
+      "types": "./dist/tools/index.d.ts",
+      "import": "./dist/tools/index.js",
+      "default": "./dist/tools/index.js"
+    }
+  },
+  "bin": {
+    "rundot-syncplay": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node -e \"require('node:fs').writeFileSync('dist/cjs/package.json', JSON.stringify({type:'commonjs'}))\"",
+    "test": "tsx --test tests/**/*.test.ts",
+    "test:ci": "tsx --test tests/canonical.test.ts tests/entrypoints.test.ts && npm run static:determinism -- --paths tests/fixtures/pass/simulation.ts --source-only --json artifacts/certification/static-ci-smoke.json",
+    "test:core": "tsx --test tests/canonical.test.ts tests/offline-session.test.ts tests/input-authority.test.ts tests/session-wire.test.ts tests/session-snapshot.test.ts tests/authority-room.test.ts tests/networked-client-snapshot.test.ts tests/local-authority-wire.test.ts tests/replay-scoring.test.ts tests/bot-backfill.test.ts tests/latency-simulation.test.ts tests/time-sync.test.ts tests/match-log.test.ts tests/spectator.test.ts tests/synctest.test.ts tests/instant-replay.test.ts tests/session-promotion.test.ts tests/pause-resume.test.ts",
+    "test:certification": "npm run test:core && tsx --test tests/entrypoints.test.ts tests/multiplayer-service.test.ts tests/deterministic-session.test.ts tests/multiclient-authority.test.ts tests/networked-input-authority.test.ts tests/rollback-history.test.ts",
+    "pack:dry-run": "npm pack --dry-run",
+    "lab:offline-replay": "tsx src/cli.ts lab:offline-replay",
+    "lab:replay-verify": "tsx src/cli.ts lab:replay-verify",
+    "lab:replay-inspect": "tsx src/cli.ts lab:replay-inspect",
+    "lab:replay-diff": "tsx src/cli.ts lab:replay-diff",
+    "lab:replay-verify-browser": "tsx src/cli.ts lab:replay-verify-browser",
+    "lab:buffer-bench": "tsx src/cli.ts lab:buffer-bench",
+    "lab:protocol-rollback": "tsx src/cli.ts lab:protocol-rollback",
+    "lab:netcode": "tsx src/cli.ts lab:netcode",
+    "lab:prediction-culling": "tsx src/cli.ts lab:prediction-culling",
+    "lab:local-ws-server": "tsx src/cli.ts lab:local-ws-server",
+    "lab:local-authority-server": "tsx src/cli.ts lab:local-authority-server",
+    "lab:networked-authority": "tsx src/cli.ts lab:networked-authority",
+    "lab:wait-for-url": "tsx src/cli.ts lab:wait-for-url",
+    "lab:ws-adapter-test": "tsx src/cli.ts lab:ws-adapter-test",
+    "lab:r3f-render-adapter": "tsx src/cli.ts lab:r3f-render-adapter",
+    "lab:venus-mp-budget": "tsx src/cli.ts lab:venus-mp-budget",
+    "lab:physics-cert": "tsx src/cli.ts lab:physics-cert",
+    "lab:physics3d": "tsx src/cli.ts lab:physics3d",
+    "lab:kcc3d": "tsx src/cli.ts lab:kcc3d",
+    "lab:lag-compensation3d": "tsx src/cli.ts lab:lag-compensation3d",
+    "lab:input-timeline": "tsx src/cli.ts lab:input-timeline",
+    "lab:command-timeline": "tsx src/cli.ts lab:command-timeline",
+    "lab:number": "tsx src/cli.ts lab:number",
+    "lab:number-browser": "tsx src/cli.ts lab:number-browser",
+    "lab:engine-core-browser": "tsx src/cli.ts lab:engine-core-browser",
+    "certify:v1": "tsx src/cli.ts certify",
+    "certify:v2": "tsx src/cli.ts certify:v2",
+    "certify:chaos": "tsx src/cli.ts certify:v2 --profile chaos",
+    "certify:engine-parity": "tsx src/cli.ts certify:engine-parity",
+    "benchmark:engine-parity": "tsx src/cli.ts benchmark:engine-parity",
+    "certify:engine-complete": "tsx src/cli.ts certify:engine-complete",
+    "benchmark:engine-complete": "tsx src/cli.ts benchmark:engine-complete",
+    "certify:deterministic-stress": "npm run benchmark:engine-complete -- --players 128 --frames 100000 --seed 71 --enforce-thresholds --json artifacts/certification/engine-complete-stress.json --junit artifacts/certification/engine-complete-stress.xml && npm run benchmark:engine-parity -- --profile stress --players 128 --frames 100000 --seed 71 --json artifacts/certification/engine-parity-stress-100k.json --junit artifacts/certification/engine-parity-stress-100k.xml",
+    "certify:standalone-complete": "npm run certify:engine-complete -- --players 128 --frames 5000 --seed 71 --json artifacts/certification/engine-complete.json --junit artifacts/certification/engine-complete.xml && npm run benchmark:engine-complete -- --players 128 --frames 100000 --seed 71 --enforce-thresholds --json artifacts/certification/engine-complete-stress.json --junit artifacts/certification/engine-complete-stress.xml && npm run certify:v2 -- --profile required-full --players 128 --frames 1000 --seed 71 --json artifacts/certification/engine-parity-required-full.json --junit artifacts/certification/engine-parity-required-full.xml && npm run benchmark:engine-parity -- --profile stress --players 128 --frames 100000 --seed 71 --json artifacts/certification/engine-parity-stress-100k.json --junit artifacts/certification/engine-parity-stress-100k.xml && npm run lab:local-authority-server -- --players 128 --frames 1000 --seed 71 --json artifacts/certification/local-authority-server-p128.json && npm run lab:offline-replay -- --players 4 --frames 120 --seed 17 --out artifacts/replays/browser-proof-current.json && npm run lab:replay-verify-browser -- artifacts/replays/browser-proof-current.json --runtime chromium --json artifacts/certification/browser-replay-chromium-current.json && npm run lab:engine-core-browser -- --runtime chromium --players 128 --frames 1000 --seed 71 --json artifacts/certification/engine-core-numeric-chromium-current.json && SDK_TEST_APP_PROOF=\"$PWD/artifacts/certification/sdk-test-app-current.json\" && cd ../sdk && npm run build && npm run build:test-app && npm run verify:syncplay-test-app -- --json \"$SDK_TEST_APP_PROOF\" && cd ../syncplay && npm run report:engine-parity-matrix:certified && npm run static:determinism -- --json artifacts/certification/static-engine-complete.json",
+    "report:diff": "tsx src/cli.ts report:diff",
+    "report:engine-parity-matrix": "tsx src/cli.ts report:engine-parity-matrix",
+    "report:engine-parity-matrix:certified": "tsx src/cli.ts report:engine-parity-matrix --artifact-root artifacts/certification --enforce --json artifacts/certification/engine-parity-matrix.json",
+    "replay:verify": "tsx src/cli.ts replay:verify",
+    "replay-bundle:verify": "tsx src/cli.ts replay-bundle:verify",
+    "replay-bundle:verify-runtime": "tsx src/cli.ts replay-bundle:verify-runtime",
+    "replay-bundle:slice": "tsx src/cli.ts replay-bundle:slice",
+    "replay-bundle:debug-tables": "tsx src/cli.ts replay-bundle:debug-tables",
+    "replay-bundle:diff": "tsx src/cli.ts replay-bundle:diff",
+    "static:determinism": "tsx src/cli.ts static:determinism",
+    "cook:syncplay-assets": "tsx src/cli.ts cook:syncplay-assets",
+    "config:bundle": "tsx src/cli.ts config:bundle",
+    "config:verify": "tsx src/cli.ts config:verify",
+    "navmesh:cook": "tsx src/cli.ts navmesh:cook",
+    "navmesh:validate": "tsx src/cli.ts navmesh:validate",
+    "navmesh:trace": "tsx src/cli.ts navmesh:trace",
+    "animation:compile": "tsx src/cli.ts animation:compile",
+    "animation:trace": "tsx src/cli.ts animation:trace",
+    "bot:compile": "tsx src/cli.ts bot:compile",
+    "bot:trace": "tsx src/cli.ts bot:trace",
+    "project:scaffold": "tsx src/cli.ts project:scaffold",
+    "project:certify": "tsx src/cli.ts project:certify",
+    "project:summary": "tsx src/cli.ts project:summary",
+    "project:preflight": "tsx src/cli.ts project:preflight",
+    "project:check": "tsx src/cli.ts project:check",
+    "project:release-verify": "tsx src/cli.ts project:release-verify",
+    "project:release-bundle": "tsx src/cli.ts project:release-bundle",
+    "project:release-bundle-verify": "tsx src/cli.ts project:release-bundle-verify",
+    "project:release-bundle-schema": "tsx src/cli.ts project:release-bundle-schema",
+    "project:doctor": "tsx src/cli.ts project:doctor",
+    "project:deploy-check": "tsx src/cli.ts project:deploy-check",
+    "project:deploy-check-verify": "tsx src/cli.ts project:deploy-check-verify",
+    "project:ci-workflow": "tsx src/cli.ts project:ci-workflow",
+    "example:counter-duel": "tsx src/cli.ts example:counter-duel",
+    "example:fixed-arena": "tsx src/cli.ts example:fixed-arena",
+    "schema:validate": "tsx src/cli.ts schema:validate",
+    "schema:dump": "tsx src/cli.ts schema:dump",
+    "schema:types": "tsx src/cli.ts schema:types",
+    "schema:runtime": "tsx src/cli.ts schema:runtime",
+    "schema:binary": "tsx src/cli.ts schema:binary",
+    "check": "tsx src/cli.ts check",
+    "coverage:package:core-fast": "node scripts/run-package-istanbul-coverage-shard.mjs --id core-fast --include src/collision.ts --include src/deterministic-primitives.ts --include src/index.ts --include src/math.ts --include src/random.ts --test tests/canonical.test.ts --test tests/collision.test.ts --test tests/deterministic-primitives.test.ts --test tests/math.test.ts --test tests/random.test.ts",
+    "coverage:package:commands": "node scripts/run-package-source-istanbul-coverage-shard.mjs --id commands --include src/commands.ts --test tests/command-timeline.test.ts",
+    "coverage:package:input-timeline": "node scripts/run-package-source-istanbul-coverage-shard.mjs --id input-timeline --include src/input-timeline.ts --test tests/input-timeline.test.ts",
+    "coverage:package:multiclient-authority": "node scripts/run-package-istanbul-coverage-shard.mjs --id multiclient-authority --include src/multiclient-authority.ts --test tests/multiclient-authority.test.ts",
+    "coverage:package:local-authority": "node scripts/run-package-source-istanbul-coverage-shard.mjs --id local-authority --include src/local-authority.ts --test tests/local-authority.test.ts",
+    "coverage:package:local-authority-wire": "node scripts/run-package-istanbul-coverage-shard.mjs --id local-authority-wire --include src/local-authority-wire.ts --test tests/local-authority-wire.test.ts",
+    "coverage:package:input-button": "node scripts/run-package-istanbul-coverage-shard.mjs --id input-button --include src/input-button.ts --test tests/input-button.test.ts",
+    "coverage:package:ecs-lite": "node scripts/run-package-istanbul-coverage-shard.mjs --id ecs-lite --include src/ecs-lite.ts --test tests/ecs-lite.test.ts",
+    "coverage:package:collision": "node scripts/run-package-istanbul-coverage-shard.mjs --id collision --include src/collision.ts --test tests/collision.test.ts",
+    "coverage:package:random": "node scripts/run-package-istanbul-coverage-shard.mjs --id random --include src/random.ts --test tests/random.test.ts",
+    "coverage:package:deterministic-primitives": "node scripts/run-package-istanbul-coverage-shard.mjs --id deterministic-primitives --include src/deterministic-primitives.ts --test tests/deterministic-primitives.test.ts",
+    "coverage:package:deterministic-session": "node scripts/run-package-istanbul-coverage-shard.mjs --id deterministic-session --include src/deterministic-session.ts --test tests/deterministic-session.test.ts",
+    "coverage:package:canonical": "node scripts/run-package-istanbul-coverage-shard.mjs --id canonical --include src/canonical.ts --test tests/canonical.test.ts",
+    "coverage:package:math": "node scripts/run-package-istanbul-coverage-shard.mjs --id math --include src/math.ts --test tests/math.test.ts",
+    "coverage:package:errors": "node scripts/run-package-istanbul-coverage-shard.mjs --id errors --include src/errors.ts --test tests/errors.test.ts",
+    "coverage:package:entrypoints": "node scripts/run-package-istanbul-coverage-shard.mjs --id entrypoints --include src/browser.ts --include src/node.ts --include src/creator.ts --include src/tools/index.ts --test tests/entrypoints.test.ts",
+    "coverage:package:multiplayer-service": "node scripts/run-package-istanbul-coverage-shard.mjs --id multiplayer-service --include src/multiplayer-service.ts --test tests/multiplayer-service.test.ts",
+    "coverage:package:prediction-culling": "node scripts/run-package-istanbul-coverage-shard.mjs --id prediction-culling --include src/prediction-culling.ts --test tests/prediction-culling.test.ts",
+    "coverage:package:rollback-history": "node scripts/run-package-istanbul-coverage-shard.mjs --id rollback-history --include src/rollback-history.ts --test tests/rollback-history.test.ts",
+    "coverage:package:sparse-set": "node scripts/run-package-istanbul-coverage-shard.mjs --id sparse-set --include src/sparse-set.ts --test tests/sparse-set.test.ts",
+    "coverage:package:offline-session": "node scripts/run-package-istanbul-coverage-shard.mjs --id offline-session --include src/offline-session.ts --test tests/offline-session.test.ts",
+    "coverage:package:schema-dsl-binary": "node scripts/run-package-istanbul-coverage-shard.mjs --id schema-dsl-binary --include src/schema-dsl-binary.ts --test tests/schema-dsl-binary.test.ts",
+    "coverage:deterministic:strict": "node --import tsx --test --experimental-test-coverage --test-coverage-include='src/**/*.ts' --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100 tests/**/*.test.ts"
+  },
+  "license": "MIT",
+  "keywords": [
+    "RUN.game",
+    "deterministic",
+    "multiplayer",
+    "rollback",
+    "replay"
+  ],
+  "devDependencies": {
+    "@dimforge/rapier2d-compat": "0.19.3",
+    "@types/node": "^22.0.0",
+    "istanbul-lib-coverage": "^3.2.2",
+    "istanbul-lib-instrument": "^6.0.3",
+    "playwright": "^1.60.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.9.2"
+  }
+}