@net-mesh/browser 0.37.0

package/dist/netcode/wire.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Netcode frames and the transport they ride.
+ *
+ * Every frame is small JSON tagged with the netcode instance's label
+ * (`n`), so several netcode instances — and the store — can share one
+ * node: a frame for another label is not this instance's. All frames ride
+ * a fire-and-forget **lossy** stream (`openStream({ lossy: true })`): the
+ * protocol is built for loss (inputs are sent redundantly, snapshots
+ * supersede each other, pings are repeated).
+ */
+/** The structural transport netcode uses: `BrowserNode`, the local mesh,
+ * `meshStoreTransport` on a native host. */
+export interface NetcodeTransport {
+    nodeIdHex(): string | null;
+    openStream(options: {
+        reliability: 'reliable' | 'fireAndForget';
+        peer?: string;
+        label?: string;
+        lossy?: boolean;
+    }): NetcodeStream | Promise<NetcodeStream>;
+    onEvent(handler: (event: {
+        readonly type: string;
+        readonly streamId?: string;
+        readonly peerNode?: string | null;
+        readonly payload?: Uint8Array;
+    }) => void): () => void;
+    connectPeer?(peerHex: string): Promise<unknown>;
+}
+/** A stream the netcode sends on. */
+export interface NetcodeStream {
+    send(payload: Uint8Array): unknown;
+    close(): unknown;
+}
+/** One player input as it travels: `seq` counts from 1 per player. */
+export interface WireInput<I> {
+    readonly seq: number;
+    /** The host time the player was RENDERING when it issued this input —
+     * what lag compensation rewinds to. */
+    readonly seen: number;
+    readonly data: I;
+}
+export type Frame<E, I> = 
+/** Player → host: join (repeated until the first snapshot). */
+{
+    readonly n: string;
+    readonly k: 'h';
+}
+/** Player → host: the newest inputs, the unacknowledged ones repeated. */
+ | {
+    readonly n: string;
+    readonly k: 'i';
+    readonly i: readonly WireInput<I>[];
+}
+/** Player → host: clock ping. */
+ | {
+    readonly n: string;
+    readonly k: 'p';
+    readonly t0: number;
+}
+/**
+ * Player → host: the interest keys it wants, version `v` (repeated until a
+ * snapshot echoes `v` back as `iv`; the host keeps the highest version).
+ */
+ | {
+    readonly n: string;
+    readonly k: 'w';
+    readonly v: number;
+    readonly w: readonly string[];
+}
+/** Host → player: clock pong. */
+ | {
+    readonly n: string;
+    readonly k: 'q';
+    readonly t0: number;
+    readonly t1: number;
+    readonly t2: number;
+}
+/**
+ * Host → player: a snapshot, and the last input seq applied for them.
+ *
+ * A snapshot too large for one frame is sent as `of` chunks, chunk `c`
+ * carrying the entities {@link chunkOf} assigns to it — each chunk
+ * usable on its own, so a lost one costs part of a snapshot, not all.
+ */
+ | {
+    readonly n: string;
+    readonly k: 's';
+    readonly tick: number;
+    readonly t: number;
+    readonly ack: number;
+    readonly e: Readonly<Record<string, E>>;
+    readonly c?: number;
+    readonly of?: number;
+    /** The interest version this snapshot was filtered by, if any. */
+    readonly iv?: number;
+};
+/** Interest keys a player may name, and the longest key, in UTF-16 units. */
+export declare const MAX_NETCODE_INTEREST_KEYS = 256;
+export declare const MAX_NETCODE_INTEREST_KEY_LENGTH = 64;
+/** Chunks a snapshot may be split into, at most. */
+export declare const MAX_SNAPSHOT_CHUNKS = 256;
+/**
+ * The chunk (of `of`) entity `id` travels in: FNV-1a of the id. Stable, so
+ * a player missing a chunk knows which entities it would have carried.
+ */
+export declare function chunkOf(id: string, of: number): number;
+export declare function encodeFrame<E, I>(frame: Frame<E, I>): Uint8Array;
+/** A frame for `label`, or `null` for anything else (another label, not a
+ * netcode frame, malformed). */
+export declare function decodeFrame<E, I>(payload: Uint8Array | undefined, label: string): Frame<E, I> | null;
+/**
+ * A node id the CALLER supplied (`host`, from `nodeIdHex()`): hex only, 16
+ * lowercase digits out, or `null`.
+ */
+export declare function peerHex(peer: string | null | undefined): string | null;
+/**
+ * The authenticated sender of a transport event, 16 lowercase hex. The
+ * browser node reports it as a DECIMAL u64, `meshStoreTransport` as hex —
+ * read exactly the way the store reads it (`peerHexOf`), so netcode and the
+ * store never disagree about who a peer is.
+ */
+export declare function eventPeer(peer: string | null | undefined): string | null;
+/** The time source: `performance.now()` unless a test injects one. */
+export type Now = () => number;
+export declare const defaultNow: Now;

package/dist/netcode/wire.js

@@ -0,0 +1,117 @@
+/**
+ * Netcode frames and the transport they ride.
+ *
+ * Every frame is small JSON tagged with the netcode instance's label
+ * (`n`), so several netcode instances — and the store — can share one
+ * node: a frame for another label is not this instance's. All frames ride
+ * a fire-and-forget **lossy** stream (`openStream({ lossy: true })`): the
+ * protocol is built for loss (inputs are sent redundantly, snapshots
+ * supersede each other, pings are repeated).
+ */
+/** Interest keys a player may name, and the longest key, in UTF-16 units. */
+export const MAX_NETCODE_INTEREST_KEYS = 256;
+export const MAX_NETCODE_INTEREST_KEY_LENGTH = 64;
+/** Chunks a snapshot may be split into, at most. */
+export const MAX_SNAPSHOT_CHUNKS = 256;
+/**
+ * The chunk (of `of`) entity `id` travels in: FNV-1a of the id. Stable, so
+ * a player missing a chunk knows which entities it would have carried.
+ */
+export function chunkOf(id, of) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < id.length; i += 1) {
+        hash ^= id.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0) % of;
+}
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true });
+export function encodeFrame(frame) {
+    return encoder.encode(JSON.stringify(frame));
+}
+/** A frame for `label`, or `null` for anything else (another label, not a
+ * netcode frame, malformed). */
+export function decodeFrame(payload, label) {
+    if (payload === undefined)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(decoder.decode(payload));
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const frame = value;
+    if (frame.n !== label || typeof frame.k !== 'string')
+        return null;
+    switch (frame.k) {
+        case 'h':
+            return frame;
+        case 'i':
+            return Array.isArray(frame.i) ? frame : null;
+        case 'p':
+            return typeof frame.t0 === 'number' ? frame : null;
+        case 'w': {
+            const w = frame;
+            return Number.isSafeInteger(w.v) &&
+                w.v >= 1 &&
+                Array.isArray(w.w) &&
+                w.w.length <= MAX_NETCODE_INTEREST_KEYS &&
+                w.w.every(key => typeof key === 'string' && key.length <= MAX_NETCODE_INTEREST_KEY_LENGTH)
+                ? frame
+                : null;
+        }
+        case 'q': {
+            const q = frame;
+            return typeof q.t0 === 'number' && typeof q.t1 === 'number' && typeof q.t2 === 'number'
+                ? frame
+                : null;
+        }
+        case 's': {
+            const s = frame;
+            if ((s.iv !== undefined && !Number.isSafeInteger(s.iv)) ||
+                typeof s.tick !== 'number' ||
+                typeof s.t !== 'number' ||
+                typeof s.ack !== 'number' ||
+                typeof s.e !== 'object' ||
+                s.e === null) {
+                return null;
+            }
+            if (s.c === undefined && s.of === undefined)
+                return frame;
+            const chunked = Number.isInteger(s.c) &&
+                Number.isInteger(s.of) &&
+                s.of >= 1 &&
+                s.of <= MAX_SNAPSHOT_CHUNKS &&
+                s.c >= 0 &&
+                s.c < s.of;
+            return chunked ? frame : null;
+        }
+        default:
+            return null;
+    }
+}
+import { peerHexOf } from '../store/host.js';
+/**
+ * A node id the CALLER supplied (`host`, from `nodeIdHex()`): hex only, 16
+ * lowercase digits out, or `null`.
+ */
+export function peerHex(peer) {
+    if (typeof peer !== 'string')
+        return null;
+    const raw = peer.startsWith('0x') ? peer.slice(2) : peer;
+    return /^[0-9a-fA-F]{1,16}$/.test(raw) ? raw.toLowerCase().padStart(16, '0') : null;
+}
+/**
+ * The authenticated sender of a transport event, 16 lowercase hex. The
+ * browser node reports it as a DECIMAL u64, `meshStoreTransport` as hex —
+ * read exactly the way the store reads it (`peerHexOf`), so netcode and the
+ * store never disagree about who a peer is.
+ */
+export function eventPeer(peer) {
+    return typeof peer === 'string' && peer.length > 0 ? peerHexOf(peer) : null;
+}
+export const defaultNow = () => globalThis.performance?.now() ?? Date.now();