openrtc-netcode 3.0.1 → 3.0.2

package/dist/state.d.ts

@@ -1,16 +1,29 @@
+import type { StateSnapshotBody } from './protocol.js';
 import type { NetVar, NetVarOptions, NetcodeState } from './types.js';
 export declare class ReplicatedState implements NetcodeState {
     private readonly resolveOwner;
     private readonly publishPatch;
+    private readonly capacity;
+    private readonly canWrite;
+    private readonly awaitsInitialHost;
     private readonly entries;
-    constructor(resolveOwner: (options?: NetVarOptions) => string, publishPatch: (key: string, value: unknown, owner: string) => Promise<void>);
+    private readonly subscriptions;
+    private bytes;
+    constructor(resolveOwner: (options?: NetVarOptions) => string, publishPatch: (key: string, value: unknown, owner: string, revision: number) => Promise<void>, capacity?: number, canWrite?: (owner: string) => boolean, awaitsInitialHost?: (options?: NetVarOptions) => boolean);
     define<T>(key: string, initial: T, options?: NetVarOptions): NetVar<T>;
     get<T = unknown>(key: string): T | undefined;
     snapshot(): Record<string, unknown>;
     owners(): Record<string, string>;
+    revisions(): Record<string, number>;
+    /** Watches a key across match resets and replacement owner incarnations. */
+    subscribe(key: string, listener: () => void): () => void;
+    clear(): void;
+    removeOwner(owner: string): void;
     replaceOwner(previousOwner: string, nextOwner: string): void;
-    applySnapshot(values: Record<string, unknown>, owners: Record<string, string>): void;
-    applyPatch(key: string, value: unknown, owner: string): void;
-    private applyRemoteValue;
+    /** Bind only declarations made before the first authoritative room roster. */
+    bindInitialHost(owner: string, localPeerId: string): void;
+    applySnapshot(values: Record<string, unknown>, owners: Record<string, string>, revisions: Record<string, number>, from: string): StateSnapshotBody;
+    applyPatch(key: string, value: unknown, owner: string, revision: number, from: string): boolean;
+    private notify;
     private createNetVar;
 }

package/dist/state.js

@@ -1,89 +1,200 @@
+import { canonicalJson, cloneJson, isCounter, isId, jsonByteLength, MAX_VALUE_BYTES } from './validation.js';
+const MAX_STATE_BYTES = 4 * 1024 * 1024;
 export class ReplicatedState {
-    constructor(resolveOwner, publishPatch) {
+    constructor(resolveOwner, publishPatch, capacity = 4096, canWrite = (owner) => owner === this.resolveOwner(), awaitsInitialHost = () => false) {
         this.resolveOwner = resolveOwner;
         this.publishPatch = publishPatch;
+        this.capacity = capacity;
+        this.canWrite = canWrite;
+        this.awaitsInitialHost = awaitsInitialHost;
         this.entries = new Map();
+        this.subscriptions = new Map();
+        this.bytes = 0;
     }
     define(key, initial, options) {
+        if (!isId(key))
+            throw new Error('Invalid NetVar key.');
         const existing = this.entries.get(key);
-        if (existing) {
+        if (existing)
             return this.createNetVar(existing);
-        }
+        if (this.entries.size >= this.capacity)
+            throw new Error('NetVar capacity exceeded.');
+        const owner = this.resolveOwner(options);
+        if (!isId(owner))
+            throw new Error('Invalid NetVar owner.');
+        const value = cloneJson(initial, MAX_VALUE_BYTES);
+        const revision = owner === 'local' || this.canWrite(owner) ? 1 : 0;
+        const bytes = jsonByteLength([key, value, owner, revision]);
+        if (this.bytes + bytes > MAX_STATE_BYTES)
+            throw new Error('NetVar byte capacity exceeded.');
         const entry = {
-            key,
-            value: initial,
-            owner: this.resolveOwner(options),
-            listeners: new Set(),
+            key, value, owner, bytes,
+            // A remote declaration is a display placeholder until its owner
+            // publishes. It must not compete with that owner's first version.
+            revision, awaitingHost: this.awaitsInitialHost(options), listeners: new Set(),
         };
+        this.bytes += bytes;
         this.entries.set(key, entry);
+        this.notify(key);
         return this.createNetVar(entry);
     }
     get(key) {
-        return this.entries.get(key)?.value;
+        const entry = this.entries.get(key);
+        return entry ? cloneJson(entry.value) : undefined;
     }
     snapshot() {
-        const values = {};
-        for (const [key, entry] of this.entries) {
-            values[key] = entry.value;
-        }
-        return values;
+        return Object.fromEntries(Array.from(this.entries, ([key, entry]) => [key, cloneJson(entry.value)]));
     }
     owners() {
-        const values = {};
-        for (const [key, entry] of this.entries) {
-            values[key] = entry.owner;
-        }
-        return values;
+        return Object.fromEntries(Array.from(this.entries, ([key, entry]) => [key, entry.owner]));
     }
-    replaceOwner(previousOwner, nextOwner) {
-        for (const entry of this.entries.values()) {
-            if (entry.owner === previousOwner) {
-                entry.owner = nextOwner;
+    revisions() {
+        return Object.fromEntries(Array.from(this.entries, ([key, entry]) => [key, entry.revision]));
+    }
+    /** Watches a key across match resets and replacement owner incarnations. */
+    subscribe(key, listener) {
+        if (!isId(key))
+            throw new Error('Invalid NetVar key.');
+        const listeners = this.subscriptions.get(key) ?? new Set();
+        listeners.add(listener);
+        this.subscriptions.set(key, listeners);
+        return () => {
+            listeners.delete(listener);
+            if (!listeners.size)
+                this.subscriptions.delete(key);
+        };
+    }
+    clear() {
+        const keys = [...this.entries.keys()];
+        this.entries.clear();
+        this.bytes = 0;
+        for (const key of keys)
+            this.notify(key);
+    }
+    removeOwner(owner) {
+        for (const [key, entry] of this.entries)
+            if (entry.owner === owner) {
+                this.entries.delete(key);
+                this.bytes -= entry.bytes;
+                this.notify(key);
             }
+    }
+    replaceOwner(previousOwner, nextOwner) {
+        if (!isId(nextOwner))
+            throw new Error('Invalid NetVar owner.');
+        const replacements = Array.from(this.entries.values()).filter((entry) => entry.owner === previousOwner)
+            .map((entry) => ({ entry, bytes: jsonByteLength([entry.key, entry.value, nextOwner, entry.revision]) }));
+        const total = replacements.reduce((sum, replacement) => sum + replacement.bytes - replacement.entry.bytes, this.bytes);
+        if (total > MAX_STATE_BYTES)
+            throw new Error('NetVar byte capacity exceeded.');
+        for (const { entry, bytes } of replacements) {
+            entry.owner = nextOwner;
+            entry.bytes = bytes;
         }
+        this.bytes = total;
     }
-    applySnapshot(values, owners) {
-        for (const [key, value] of Object.entries(values)) {
-            this.applyRemoteValue(key, value, owners[key] ?? this.resolveOwner());
+    /** Bind only declarations made before the first authoritative room roster. */
+    bindInitialHost(owner, localPeerId) {
+        if (!isId(owner) || !isId(localPeerId))
+            throw new Error('Invalid NetVar owner.');
+        const replacements = Array.from(this.entries.values()).filter((entry) => entry.awaitingHost)
+            .map((entry) => {
+            const revision = owner === localPeerId ? Math.max(1, entry.revision) : 0;
+            return { entry, revision, bytes: jsonByteLength([entry.key, entry.value, owner, revision]) };
+        });
+        const total = replacements.reduce((sum, replacement) => sum + replacement.bytes - replacement.entry.bytes, this.bytes);
+        if (total > MAX_STATE_BYTES)
+            throw new Error('NetVar byte capacity exceeded.');
+        for (const { entry, revision, bytes } of replacements) {
+            entry.owner = owner;
+            entry.revision = revision;
+            entry.bytes = bytes;
+            entry.awaitingHost = false;
         }
+        this.bytes = total;
+        for (const { entry } of replacements)
+            this.notify(entry.key);
     }
-    applyPatch(key, value, owner) {
-        this.applyRemoteValue(key, value, owner);
+    applySnapshot(values, owners, revisions, from) {
+        const accepted = { values: Object.create(null), owners: Object.create(null), revisions: Object.create(null) };
+        for (const [key, value] of Object.entries(values))
+            if (this.applyPatch(key, value, owners[key], revisions[key], from)) {
+                accepted.values[key] = this.get(key);
+                accepted.owners[key] = owners[key];
+                accepted.revisions[key] = revisions[key];
+            }
+        return accepted;
     }
-    applyRemoteValue(key, value, owner) {
+    applyPatch(key, value, owner, revision, from) {
+        if (!isId(key) || !isId(owner) || owner !== from || !isCounter(revision) || revision === 0)
+            return false;
         const existing = this.entries.get(key);
+        if (existing && (existing.owner !== from || existing.revision > revision))
+            return false;
+        if (!existing && this.entries.size >= this.capacity)
+            return false;
+        let next;
+        try {
+            next = cloneJson(value, MAX_VALUE_BYTES);
+        }
+        catch {
+            return false;
+        }
+        if (existing?.revision === revision && canonicalJson(existing.value) >= canonicalJson(next))
+            return false;
+        let bytes;
+        try {
+            bytes = jsonByteLength([key, next, owner, revision]);
+        }
+        catch {
+            return false;
+        }
+        if (this.bytes - (existing?.bytes ?? 0) + bytes > MAX_STATE_BYTES)
+            return false;
+        this.bytes += bytes - (existing?.bytes ?? 0);
         if (!existing) {
-            this.entries.set(key, {
-                key,
-                value,
-                owner,
-                listeners: new Set(),
-            });
-            return;
+            this.entries.set(key, { key, value: next, owner, revision, bytes, listeners: new Set() });
         }
-        const previous = existing.value;
-        existing.value = value;
-        existing.owner = owner;
-        for (const listener of existing.listeners) {
-            listener(value, previous);
+        else {
+            const previous = existing.value;
+            existing.value = next;
+            existing.revision = revision;
+            existing.bytes = bytes;
+            for (const listener of existing.listeners)
+                listener(cloneJson(next), cloneJson(previous));
         }
+        this.notify(key);
+        return true;
+    }
+    notify(key) {
+        for (const listener of this.subscriptions.get(key) ?? [])
+            listener();
     }
     createNetVar(entry) {
         return {
             key: entry.key,
-            get owner() {
-                return entry.owner;
-            },
-            get value() {
-                return entry.value;
-            },
+            get owner() { return entry.owner; },
+            get value() { return cloneJson(entry.value); },
             set: async (value) => {
+                if (this.entries.get(entry.key) !== entry)
+                    throw new Error('NetVar belongs to a retired match.');
+                if (!this.canWrite(entry.owner))
+                    throw new Error('NetVar writes require the local owner.');
+                if (!isCounter(entry.revision + 1))
+                    throw new Error('NetVar revision exhausted.');
+                const next = cloneJson(value, MAX_VALUE_BYTES);
+                const bytes = jsonByteLength([entry.key, next, entry.owner, entry.revision + 1]);
+                if (this.bytes - entry.bytes + bytes > MAX_STATE_BYTES)
+                    throw new Error('NetVar byte capacity exceeded.');
                 const previous = entry.value;
-                entry.value = value;
-                for (const listener of entry.listeners) {
-                    listener(value, previous);
-                }
-                await this.publishPatch(entry.key, value, entry.owner);
+                this.bytes += bytes - entry.bytes;
+                entry.value = next;
+                entry.bytes = bytes;
+                entry.revision++;
+                for (const listener of entry.listeners)
+                    listener(cloneJson(entry.value), cloneJson(previous));
+                this.notify(entry.key);
+                await this.publishPatch(entry.key, cloneJson(entry.value), entry.owner, entry.revision);
             },
             onChange: (callback) => {
                 entry.listeners.add(callback);

package/dist/types.d.ts

@@ -1,5 +1,9 @@
 import type { ReadinessOptions as OpenRtcApplicationPayloadReadinessOptions, IncomingStream, ScopedChannelOptions, ScopedLogicalChannel } from 'openrtc/runtime';
 import type { Room } from 'openrtc';
+import type { ActionHandler } from './actions.js';
+import type { SimulationClock } from './simulation.js';
+import type { MotionThresholds } from './motion.js';
+import type { ReplicationOptions, ReplicationStats } from './replication.js';
 import type { MetadataBody, NetcodeEnvelope, ObjectRemoveBody, ObjectSnapshotBody, ObjectUpsertBody, StatePatchBody, StateSnapshotBody, UserMessageBody } from './protocol.js';
 export interface NetcodeRuntime {
     /**
@@ -16,7 +20,11 @@ export interface NetcodeRuntime {
     initialize?(): Promise<void> | void;
     start?(): Promise<void> | void;
     stop?(): Promise<void> | void;
+    /** Releases only adapter-owned observers; never stops a borrowed runtime. */
+    dispose?(): Promise<void> | void;
     getNodeId(): Promise<string>;
+    /** Synchronous capability fence for a borrowed activated room. */
+    isRoomActive?(roomId: string): boolean;
     createRoom(roomId?: string): Promise<string>;
     joinRoom(roomId: string, options?: {
         bootstrapPeers?: boolean;
@@ -38,7 +46,17 @@ export interface NetcodeOptions {
     room?: Room;
     preferredTransports?: ReadinessOptions['preferredTransports'];
     displayName?: string;
-    localFallback?: boolean;
+    authority?: {
+        mode: 'owner' | 'host';
+        hostId?: string;
+        hostOwnedKinds?: readonly string[];
+    };
+    tickRate?: number;
+    replication?: ReplicationOptions;
+    codec?: 'json' | 'quantized';
+    motionThresholds?: MotionThresholds;
+    interest?: (peerId: string, object: Readonly<NetcodeObjectState>) => boolean;
+    priority?: (peerId: string, object: Readonly<NetcodeObjectState>) => number;
 }
 export interface CreateLobbyOptions {
     id?: string;
@@ -87,6 +105,8 @@ export interface NetcodeState {
     define<T>(key: string, initial: T, options?: NetVarOptions): NetVar<T>;
     get<T = unknown>(key: string): T | undefined;
     snapshot(): Record<string, unknown>;
+    /** Observe the current key, including removal and recreation in a later match. */
+    subscribe(key: string, listener: () => void): () => void;
 }
 export interface NetcodeVector3 {
     x: number;
@@ -116,9 +136,15 @@ export interface NetcodeObjectState<TMetadata extends Record<string, unknown> =
     transform: NetcodeTransform;
     physics?: NetcodePhysicsState;
     metadata?: TMetadata;
+    /** Owner-issued monotonic version. Wall clocks do not determine ordering. */
+    revision: number;
+    incarnation: string;
+    tick: number;
+    teleport?: boolean;
+    /** Informational sender wall-clock time only. */
     updatedAt: number;
 }
-export type NetcodeObjectUpsert<TMetadata extends Record<string, unknown> = Record<string, unknown>> = Partial<Omit<NetcodeObjectState<TMetadata>, 'transform'>> & {
+export type NetcodeObjectUpsert<TMetadata extends Record<string, unknown> = Record<string, unknown>> = Partial<Omit<NetcodeObjectState<TMetadata>, 'transform' | 'revision' | 'incarnation'>> & {
     kind?: string;
     transform: Partial<NetcodeTransform> & {
         position: NetcodeVector3;
@@ -138,12 +164,15 @@ export type NetcodeObjectChange = {
     from: string;
 };
 export interface NetcodeObjectStore {
+    read(id: string): Readonly<NetcodeObjectState> | undefined;
+    ids(kind?: string): readonly string[];
+    onStructureChange(listener: () => void): () => void;
     list(): NetcodeObjectState[];
     get(id: string): NetcodeObjectState | undefined;
     snapshot(): Record<string, NetcodeObjectState>;
     spawn(input: NetcodeObjectUpsert): Promise<NetcodeObjectState>;
     upsert(input: NetcodeObjectUpsert): Promise<NetcodeObjectState>;
-    update(id: string, patch: Partial<Omit<NetcodeObjectState, 'id'>>): Promise<NetcodeObjectState>;
+    update(id: string, patch: Partial<Omit<NetcodeObjectState, 'id' | 'revision' | 'incarnation'>>): Promise<NetcodeObjectState>;
     remove(id: string): Promise<void>;
     onChange(listener: (change: NetcodeObjectChange) => void): () => void;
 }
@@ -181,6 +210,10 @@ export interface NetcodeVoice {
     on<K extends keyof NetcodeVoiceEvents>(event: K, handler: (payload: NetcodeVoiceEvents[K]) => void): () => void;
 }
 export interface NetcodeEvents {
+    'protocol:error': {
+        peerId: string;
+        reason: string;
+    };
     lobby: NetcodeLobby | null;
     'peer:joined': NetcodePeer;
     'peer:left': NetcodePeer;
@@ -217,6 +250,16 @@ export interface NetcodeClient {
     readonly state: NetcodeState;
     readonly objects: NetcodeObjectStore;
     readonly voice: NetcodeVoice;
+    readonly clock: SimulationClock;
+    handleAction(type: string, handler: ActionHandler): () => void;
+    request(peerId: string, type: string, payload: unknown, options?: {
+        id?: string;
+        timeoutMs?: number;
+    }): Promise<unknown>;
+    waitForPeer(peerId: string, timeoutMs?: number): Promise<void>;
+    refreshInterest(): Promise<void>;
+    flushReplication(): void;
+    replicationStats(peerId: string): ReplicationStats;
     start(): Promise<void>;
     stop(): Promise<void>;
     createLobby(options?: CreateLobbyOptions): Promise<NetcodeLobby>;
@@ -256,6 +299,10 @@ export type RuntimeMediaTrackEventLike = {
     readonly streams: readonly MediaStream[];
 };
 export type RuntimeMediaConnectionLike = {
+    /** Current receiver tracks, supplied by the public OpenRTC media owner. */
+    receivers?(): readonly {
+        readonly track: MediaStreamTrack;
+    }[];
     addTrack(track: MediaStreamTrack, options?: {
         streams?: readonly MediaStream[];
         codec?: string;

package/dist/validation.d.ts

@@ -0,0 +1,10 @@
+export declare const MAX_FRAME_BYTES: number;
+export declare const MAX_VALUE_BYTES: number;
+export declare function isCounter(value: unknown): value is number;
+export declare function isId(value: unknown): value is string;
+export declare function boundedJson(value: unknown, maxNodes?: number, maxDepth?: number): boolean;
+/** Check aggregate encoded size before allocating a complete JSON string. */
+export declare function jsonByteLength(value: unknown, limit?: number, maxNodes?: number, maxDepth?: number): number;
+export declare function cloneJson<T>(value: T, limit?: number, maxNodes?: number, maxDepth?: number): T;
+export declare function canonicalJson(value: unknown): string;
+export declare function freezeJson<T>(value: T): T;

package/dist/validation.js

@@ -0,0 +1,88 @@
+export const MAX_FRAME_BYTES = 256 * 1024;
+export const MAX_VALUE_BYTES = 240 * 1024;
+const encoder = new TextEncoder();
+export function isCounter(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+export function isId(value) {
+    return typeof value === 'string' && value.length > 0 && value.length <= 256;
+}
+export function boundedJson(value, maxNodes = 20000, maxDepth = 24) {
+    let nodes = 0;
+    const visit = (item, depth) => {
+        if (++nodes > maxNodes || depth > maxDepth)
+            return false;
+        if (item === null || typeof item === 'boolean')
+            return true;
+        if (typeof item === 'number')
+            return Number.isFinite(item);
+        if (typeof item === 'string')
+            return item.length <= MAX_FRAME_BYTES;
+        if (Array.isArray(item)) {
+            for (let index = 0; index < item.length; index++)
+                if (!(index in item) || !visit(item[index], depth + 1))
+                    return false;
+            return true;
+        }
+        if (typeof item !== 'object' || !item)
+            return false;
+        return Object.entries(item).every(([key, entry]) => key.length <= 256 && (entry === undefined || visit(entry, depth + 1)));
+    };
+    return visit(value, 0);
+}
+/** Check aggregate encoded size before allocating a complete JSON string. */
+export function jsonByteLength(value, limit = MAX_FRAME_BYTES, maxNodes = 20000, maxDepth = 24) {
+    if (!boundedJson(value, maxNodes, maxDepth))
+        throw new Error('Netcode value exceeds the JSON schema or resource limits.');
+    let bytes = 0;
+    const add = (count) => {
+        bytes += count;
+        if (bytes > limit)
+            throw new Error('Netcode value exceeds the byte limit.');
+    };
+    const visit = (item) => {
+        if (Array.isArray(item)) {
+            add(2 + Math.max(0, item.length - 1));
+            for (const entry of item)
+                visit(entry);
+        }
+        else if (item && typeof item === 'object') {
+            add(2);
+            let count = 0;
+            for (const [key, entry] of Object.entries(item)) {
+                if (entry === undefined)
+                    continue;
+                add((count++ ? 1 : 0) + encoder.encode(JSON.stringify(key)).byteLength + 1);
+                visit(entry);
+            }
+        }
+        else
+            add(encoder.encode(JSON.stringify(item)).byteLength);
+    };
+    visit(value);
+    return bytes;
+}
+export function cloneJson(value, limit = MAX_FRAME_BYTES, maxNodes = 20000, maxDepth = 24) {
+    jsonByteLength(value, limit, maxNodes, maxDepth);
+    const encoded = JSON.stringify(value);
+    if (encoder.encode(encoded).byteLength > limit)
+        throw new Error('Netcode value exceeds the byte limit.');
+    return JSON.parse(encoded);
+}
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+export function freezeJson(value) {
+    if (value && typeof value === 'object') {
+        for (const item of Object.values(value))
+            freezeJson(item);
+        Object.freeze(value);
+    }
+    return value;
+}

package/dist/voice.d.ts

@@ -10,6 +10,8 @@ export declare class NetcodeVoiceController implements NetcodeVoice {
     private localMediaStream;
     private options;
     private active;
+    private generation;
+    private starting;
     private muted;
     constructor(localPeerId: () => string | null, peers: () => NetcodePeer[], connectionForPeer: (peerId: string) => RuntimeConnectionLike | null);
     get enabled(): boolean;