openrtc-netcode 3.0.1 → 3.0.2

package/dist/objects.js

@@ -1,11 +1,27 @@
+import { boundedJson, cloneJson, freezeJson, isId, jsonByteLength } from './validation.js';
+// Reserve page/envelope overhead below the 8 MiB snapshot assembly budget.
+const MAX_STORE_BYTES = 7 * 1024 * 1024;
+const MAX_OBJECT_BYTES = 220 * 1024;
 export class ObjectStore {
-    constructor(localPeerId, publishUpsert, publishRemove) {
+    constructor(localPeerId, publishUpsert, publishRemove, capacity = 10000, incarnation = () => this.instanceId, tick = () => 0, canWrite = () => true) {
         this.localPeerId = localPeerId;
         this.publishUpsert = publishUpsert;
         this.publishRemove = publishRemove;
+        this.capacity = capacity;
+        this.incarnation = incarnation;
+        this.tick = tick;
+        this.canWrite = canWrite;
         this.objectsById = new Map();
+        this.removedById = new Map();
         this.listeners = new Set();
         this.nextObjectId = 0;
+        this.instanceId = crypto.randomUUID();
+        this.structureListeners = new Set();
+        this.idSnapshots = new Map();
+        this.entryBytes = new Map();
+        this.bytes = 0;
+        this.snapshotBatch = false;
+        this.structurePending = false;
     }
     list() {
         return Array.from(this.objectsById.values()).map(cloneObject);
@@ -14,8 +30,54 @@ export class ObjectStore {
         const object = this.objectsById.get(id);
         return object ? cloneObject(object) : undefined;
     }
+    /** Immutable, allocation-free read for render loops. */
+    read(id) {
+        return this.objectsById.get(id);
+    }
+    ids(kind) {
+        const key = kind ?? '';
+        let snapshot = this.idSnapshots.get(key);
+        if (!snapshot) {
+            snapshot = Object.freeze(Array.from(this.objectsById.values())
+                .filter((object) => !kind || object.kind === kind).map((object) => object.id));
+            this.idSnapshots.set(key, snapshot);
+        }
+        return snapshot;
+    }
+    onStructureChange(listener) {
+        this.structureListeners.add(listener);
+        return () => this.structureListeners.delete(listener);
+    }
+    removeOwner(ownerId, kinds) {
+        for (const [id, object] of this.objectsById) {
+            if (object.ownerId === ownerId && (!kinds || kinds.has(object.kind))) {
+                this.objectsById.delete(id);
+                this.releaseBytes(id);
+                this.emit({ type: 'remove', id, from: ownerId });
+            }
+        }
+        for (const [id, removal] of this.removedById)
+            if (!kinds && removal.ownerId === ownerId) {
+                this.removedById.delete(id);
+                this.releaseBytes(id);
+            }
+        this.structureChanged();
+    }
+    pruneOwner(ownerId, visible) {
+        let changed = false;
+        for (const [id, object] of this.objectsById) {
+            if (object.ownerId === ownerId && !visible.has(id)) {
+                this.objectsById.delete(id);
+                this.releaseBytes(id);
+                this.emit({ type: 'remove', id, from: ownerId });
+                changed = true;
+            }
+        }
+        if (changed)
+            this.structureChanged();
+    }
     snapshot() {
-        const snapshot = {};
+        const snapshot = Object.create(null);
         for (const [id, object] of this.objectsById) {
             snapshot[id] = cloneObject(object);
         }
@@ -30,12 +92,28 @@ export class ObjectStore {
     }
     async upsert(input) {
         const previous = input.id ? this.objectsById.get(input.id) : undefined;
+        const removed = input.id ? this.removedById.get(input.id) : undefined;
+        if (!previous && !removed && this.objectsById.size + this.removedById.size >= this.capacity) {
+            throw new Error('Netcode object lifetime capacity exceeded; begin a new match.');
+        }
+        const ownerId = this.localPeerId() ?? 'local';
+        const kind = input.kind ?? previous?.kind ?? 'object';
+        if (!this.canWrite(kind))
+            throw new Error('Object state requires host authority.');
+        if (input.id && !input.id.startsWith(`${ownerId}:`))
+            throw new Error('Object IDs must be namespaced by their owner.');
+        this.assertOwner(input.ownerId ?? previous?.ownerId ?? removed?.ownerId ?? ownerId);
+        this.assertOwner(previous?.ownerId ?? removed?.ownerId ?? ownerId);
         const object = normalizeObject({
             ...previous,
             ...input,
             id: input.id ?? previous?.id ?? this.createObjectId(input.kind),
-            kind: input.kind ?? previous?.kind ?? 'object',
-            ownerId: input.ownerId ?? previous?.ownerId ?? this.localPeerId() ?? 'local',
+            kind,
+            ownerId,
+            revision: nextRevision(previous?.revision ?? removed?.revision ?? 0),
+            incarnation: this.incarnation(kind),
+            tick: input.tick ?? this.tick(),
+            teleport: input.teleport ?? false,
             transform: {
                 ...(previous?.transform ?? {}),
                 ...(input.transform ?? {}),
@@ -50,7 +128,10 @@ export class ObjectStore {
             },
             updatedAt: input.updatedAt ?? Date.now(),
         });
-        this.applyObject(object, 'local');
+        if (!isNetcodeObjectState(object))
+            throw new Error('openrtc-netcode invalid local object');
+        if (!this.applyObject(object, ownerId, 'local'))
+            throw new Error('Netcode object byte capacity or version rejected.');
         await this.publishUpsert(object);
         return cloneObject(object);
     }
@@ -79,8 +160,16 @@ export class ObjectStore {
         });
     }
     async remove(id) {
-        this.applyRemove(id, 'local');
-        await this.publishRemove(id);
+        const previous = this.objectsById.get(id) ?? this.removedById.get(id);
+        if (!previous)
+            return;
+        if (!this.canWrite(this.objectsById.get(id)?.kind))
+            throw new Error('Object state requires host authority.');
+        this.assertOwner(previous.ownerId);
+        const removal = { id, ownerId: previous.ownerId, revision: nextRevision(previous.revision) };
+        if (!this.applyRemove(id, removal.ownerId, removal, 'local'))
+            throw new Error('Netcode object byte capacity or version rejected.');
+        await this.publishRemove(removal);
     }
     onChange(listener) {
         this.listeners.add(listener);
@@ -88,56 +177,179 @@ export class ObjectStore {
     }
     clear() {
         this.objectsById.clear();
+        this.removedById.clear();
+        this.entryBytes.clear();
+        this.bytes = 0;
+        this.structureChanged();
         this.emit({ type: 'snapshot', objects: [], from: 'local' });
     }
-    applySnapshot(objects, from) {
-        for (const object of Object.values(objects)) {
-            this.applyObject(object, from);
+    removalSnapshot() {
+        return Object.fromEntries(Array.from(this.removedById, ([id, removal]) => [id, { ...removal }]));
+    }
+    applySnapshot(objects, from, removed = {}) {
+        const acceptedObjects = Object.create(null);
+        const acceptedRemovals = Object.create(null);
+        this.snapshotBatch = true;
+        try {
+            for (const [id, removal] of Object.entries(removed)) {
+                if (id === removal.id && this.applyRemove(id, from, removal)) {
+                    acceptedRemovals[id] = { ...this.removedById.get(id) };
+                }
+            }
+            for (const [id, object] of Object.entries(objects)) {
+                if (id === object.id && this.applyObject(object, from)) {
+                    acceptedObjects[id] = this.get(id);
+                }
+            }
         }
-        this.emit({ type: 'snapshot', objects: this.list(), from });
+        finally {
+            this.snapshotBatch = false;
+            if (this.structurePending) {
+                this.structurePending = false;
+                this.structureChanged();
+            }
+        }
+        if (Object.keys(acceptedObjects).length || Object.keys(acceptedRemovals).length) {
+            this.emit({ type: 'snapshot', objects: this.list(), from });
+        }
+        return { objects: acceptedObjects, removed: acceptedRemovals };
     }
     applyUpsert(object, from) {
-        this.applyObject(object, from);
+        return this.applyObject(object, from);
     }
-    applyRemove(id, from) {
+    applyRemove(id, sender, removal, from = sender) {
+        if (!isObjectRemoval(removal) || removal.id !== id || removal.ownerId !== sender || !id.startsWith(`${sender}:`))
+            return false;
+        const previous = this.objectsById.get(id) ?? this.removedById.get(id);
+        if (previous && (previous.ownerId !== sender || previous.revision > removal.revision))
+            return false;
+        if (this.removedById.get(id)?.revision === removal.revision)
+            return false;
+        if (!previous && this.objectsById.size + this.removedById.size >= this.capacity)
+            return false;
+        const value = { id, ownerId: sender, revision: removal.revision };
+        const bytes = jsonByteLength([id, value], MAX_OBJECT_BYTES);
+        if (!this.fitsBytes(id, bytes))
+            return false;
+        this.setBytes(id, bytes);
+        this.removedById.set(id, value);
         const existed = this.objectsById.delete(id);
         if (existed) {
+            this.structureChanged();
             this.emit({ type: 'remove', id, from });
         }
+        return true;
     }
-    applyObject(input, from) {
-        const object = normalizeObject(input);
+    applyObject(input, sender, from = sender) {
+        if (!isNetcodeObjectState(input) || input.ownerId !== sender)
+            return false;
+        if (!input.id.startsWith(`${sender}:`))
+            return false;
+        const removed = this.removedById.get(input.id);
+        if (removed && (removed.ownerId !== sender || removed.revision >= input.revision))
+            return false;
+        let object, bytes;
+        try {
+            object = normalizeObject(input);
+            bytes = jsonByteLength([object.id, object], MAX_OBJECT_BYTES);
+        }
+        catch {
+            return false;
+        }
         const previous = this.objectsById.get(object.id);
-        if (previous && previous.updatedAt > object.updatedAt) {
-            return;
+        if (!previous && !removed && this.objectsById.size + this.removedById.size >= this.capacity)
+            return false;
+        if (previous && (previous.ownerId !== sender || previous.revision > object.revision))
+            return false;
+        // Canonical payload order makes conflicting same-owner versions converge
+        // independently of delivery order. Duplicate versions emit no change.
+        if (previous?.revision === object.revision && canonicalJson(previous) >= canonicalJson(object)) {
+            return false;
+        }
+        if (!this.fitsBytes(object.id, bytes))
+            return false;
+        this.setBytes(object.id, bytes);
+        this.removedById.delete(object.id);
+        this.objectsById.set(object.id, freezeJson(object));
+        if (!previous || previous.kind !== object.kind || canonicalJson(previous.metadata) !== canonicalJson(object.metadata))
+            this.structureChanged();
+        if (!this.snapshotBatch)
+            this.emit({ type: 'upsert', object: cloneObject(object), from });
+        return true;
+    }
+    assertOwner(ownerId) {
+        if (ownerId !== (this.localPeerId() ?? 'local')) {
+            throw new Error(`openrtc-netcode object writes require the local owner: ${ownerId}`);
         }
-        this.objectsById.set(object.id, object);
-        this.emit({ type: 'upsert', object: cloneObject(object), from });
     }
     createObjectId(kind = 'object') {
         const peerId = this.localPeerId() ?? 'local';
         this.nextObjectId += 1;
-        return `${peerId}:${kind}:${this.nextObjectId}`;
+        return `${peerId}:${this.instanceId}:${kind}:${this.nextObjectId}`;
+    }
+    structureChanged() {
+        if (this.snapshotBatch) {
+            this.structurePending = true;
+            return;
+        }
+        this.idSnapshots.clear();
+        for (const listener of this.structureListeners)
+            listener();
     }
     emit(change) {
+        if (this.snapshotBatch)
+            return;
         for (const listener of this.listeners) {
             listener(change);
         }
     }
+    fitsBytes(id, bytes) {
+        return this.bytes - (this.entryBytes.get(id) ?? 0) + bytes <= MAX_STORE_BYTES;
+    }
+    setBytes(id, bytes) {
+        this.bytes += bytes - (this.entryBytes.get(id) ?? 0);
+        this.entryBytes.set(id, bytes);
+    }
+    releaseBytes(id) {
+        this.bytes -= this.entryBytes.get(id) ?? 0;
+        this.entryBytes.delete(id);
+    }
 }
 export function isNetcodeObjectState(value) {
-    if (!isRecord(value)) {
+    if (!isRecord(value) || !boundedJson(value)) {
         return false;
     }
-    return typeof value.id === 'string'
-        && typeof value.kind === 'string'
-        && typeof value.ownerId === 'string'
+    return isId(value.id) && isId(value.kind) && isId(value.ownerId)
+        && typeof value.incarnation === 'string' && value.incarnation.length > 0 && value.incarnation.length <= 128
+        && typeof value.tick === 'number' && Number.isSafeInteger(value.tick) && value.tick >= 0
         && isRecord(value.transform)
         && isVector3(value.transform.position)
-        && typeof value.updatedAt === 'number';
+        && (value.transform.scale === undefined || isVector3(value.transform.scale))
+        && (value.transform.rotation === undefined || isQuaternion(value.transform.rotation))
+        && (value.physics === undefined || (isRecord(value.physics)
+            && (value.physics.linearVelocity === undefined || isVector3(value.physics.linearVelocity))
+            && (value.physics.angularVelocity === undefined || isVector3(value.physics.angularVelocity))
+            && (value.physics.sleeping === undefined || typeof value.physics.sleeping === 'boolean')))
+        && (value.metadata === undefined || isRecord(value.metadata))
+        && (value.teleport === undefined || typeof value.teleport === 'boolean')
+        && isRevision(value.revision)
+        && typeof value.updatedAt === 'number' && Number.isFinite(value.updatedAt);
+}
+export function isObjectRemoval(value) {
+    return isRecord(value) && isId(value.id) && isId(value.ownerId)
+        && isRevision(value.revision);
+}
+function isRevision(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+function nextRevision(previous) {
+    const revision = previous + 1;
+    if (!isRevision(revision))
+        throw new Error('openrtc-netcode object revision exhausted');
+    return revision;
 }
 function normalizeObject(input) {
-    return {
+    return cloneObject({
         id: input.id,
         kind: input.kind,
         ownerId: input.ownerId,
@@ -152,8 +364,12 @@ function normalizeObject(input) {
             sleeping: !!input.physics.sleeping,
         } : undefined,
         metadata: input.metadata ? { ...input.metadata } : {},
+        revision: input.revision,
+        incarnation: input.incarnation,
+        tick: input.tick,
+        teleport: input.teleport,
         updatedAt: input.updatedAt,
-    };
+    });
 }
 function normalizeVector3(value) {
     return {
@@ -163,25 +379,47 @@ function normalizeVector3(value) {
     };
 }
 function normalizeQuaternion(value) {
-    return {
-        x: finiteNumber(value?.x),
-        y: finiteNumber(value?.y),
-        z: finiteNumber(value?.z),
-        w: finiteNumber(value?.w, 1),
-    };
+    const result = { x: finiteNumber(value?.x), y: finiteNumber(value?.y), z: finiteNumber(value?.z), w: finiteNumber(value?.w, 1) };
+    const norm = Math.hypot(result.x, result.y, result.z, result.w);
+    if (!Number.isFinite(norm) || norm < 1e-8)
+        throw new Error('Invalid object quaternion.');
+    for (const axis of ['x', 'y', 'z', 'w'])
+        result[axis] /= norm;
+    return result;
 }
 function finiteNumber(value, fallback = 0) {
-    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        throw new Error('Invalid object number.');
+    return value;
+}
+function isQuaternion(value) {
+    if (!isRecord(value))
+        return false;
+    const components = ['x', 'y', 'z', 'w'].map((axis) => value[axis]);
+    if (!components.every((part) => typeof part === 'number' && Number.isFinite(part)))
+        return false;
+    const norm = Math.hypot(...components);
+    return Number.isFinite(norm) && norm > 1e-8;
 }
 function isVector3(value) {
     return isRecord(value)
-        && typeof value.x === 'number'
-        && typeof value.y === 'number'
-        && typeof value.z === 'number';
+        && typeof value.x === 'number' && Number.isFinite(value.x)
+        && typeof value.y === 'number' && Number.isFinite(value.y)
+        && typeof value.z === 'number' && Number.isFinite(value.z);
 }
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 function cloneObject(object) {
-    return JSON.parse(JSON.stringify(object));
+    return cloneJson(object, MAX_OBJECT_BYTES);
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (isRecord(value)) {
+        return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
 }

package/dist/protocol.d.ts

@@ -1,6 +1,6 @@
 export declare const NETCODE_PROTOCOL = "openrtc-netcode";
-export declare const PROTOCOL_VERSION = 1;
-export type NetcodeEnvelopeKind = 'hello' | 'peer' | 'user' | 'state.snapshot' | 'state.patch' | 'object.snapshot' | 'object.upsert' | 'object.remove' | 'lobby.meta' | 'member.meta' | 'ping' | 'pong';
+export declare const PROTOCOL_VERSION = 2;
+export type NetcodeEnvelopeKind = 'hello' | 'peer' | 'user' | 'state.snapshot' | 'state.patch' | 'object.snapshot' | 'object.upsert' | 'object.remove' | 'object.batch' | 'action' | 'action.receipt' | 'lobby.meta' | 'member.meta' | 'ping' | 'pong';
 export interface NetcodeEnvelope<TBody = unknown> {
     protocol: typeof NETCODE_PROTOCOL;
     v: typeof PROTOCOL_VERSION;
@@ -9,12 +9,17 @@ export interface NetcodeEnvelope<TBody = unknown> {
     from: string;
     seq: number;
     sentAt: number;
+    sessionId: string;
     target?: string;
+    targetSessionId?: string;
+    targetAuthorityEpoch?: string;
     body: TBody;
 }
 export interface HelloBody {
     peerId: string;
     displayName?: string;
+    version: typeof PROTOCOL_VERSION;
+    authorityEpoch: string;
 }
 export interface UserMessageBody {
     type: string;
@@ -23,20 +28,28 @@ export interface UserMessageBody {
 export interface StateSnapshotBody {
     values: Record<string, unknown>;
     owners: Record<string, string>;
+    revisions: Record<string, number>;
 }
 export interface StatePatchBody {
     key: string;
     value: unknown;
     owner: string;
+    revision: number;
 }
 export interface ObjectSnapshotBody {
     objects: Record<string, unknown>;
+    removed?: Record<string, ObjectRemoveBody>;
+    viewRevision?: number;
+    page?: number;
+    pages?: number;
 }
 export interface ObjectUpsertBody {
     object: unknown;
 }
 export interface ObjectRemoveBody {
     id: string;
+    ownerId: string;
+    revision: number;
 }
 export interface MetadataBody {
     values: Record<string, string>;

package/dist/protocol.js

@@ -1,11 +1,14 @@
+import { boundedJson, isId, MAX_FRAME_BYTES } from './validation.js';
 export const NETCODE_PROTOCOL = 'openrtc-netcode';
-export const PROTOCOL_VERSION = 1;
+export const PROTOCOL_VERSION = 2;
 export function encodeEnvelope(envelope) {
     return JSON.stringify(envelope);
 }
 export function decodeEnvelope(value) {
+    if (typeof value === 'string' && new TextEncoder().encode(value).byteLength > MAX_FRAME_BYTES)
+        return null;
     const candidate = typeof value === 'string' ? parseJson(value) : value;
-    if (!isRecord(candidate)) {
+    if (!isRecord(candidate) || !boundedJson(candidate, 25000, 28)) {
         return null;
     }
     if (candidate.protocol !== NETCODE_PROTOCOL || candidate.v !== PROTOCOL_VERSION) {
@@ -14,12 +17,21 @@ export function decodeEnvelope(value) {
     if (!isEnvelopeKind(candidate.kind)) {
         return null;
     }
-    if (typeof candidate.lobbyId !== 'string'
-        || typeof candidate.from !== 'string'
+    if (!isId(candidate.lobbyId)
+        || !isId(candidate.from)
         || typeof candidate.seq !== 'number'
-        || typeof candidate.sentAt !== 'number') {
+        || typeof candidate.sentAt !== 'number'
+        || typeof candidate.sessionId !== 'string' || candidate.sessionId.length === 0 || candidate.sessionId.length > 128
+        || !Number.isSafeInteger(candidate.seq) || candidate.seq < 1
+        || !Number.isFinite(candidate.sentAt)) {
         return null;
     }
+    if ('targetSessionId' in candidate && candidate.targetSessionId !== undefined
+        && (typeof candidate.targetSessionId !== 'string' || candidate.targetSessionId.length < 1 || candidate.targetSessionId.length > 128))
+        return null;
+    if ('targetAuthorityEpoch' in candidate && candidate.targetAuthorityEpoch !== undefined
+        && (typeof candidate.targetAuthorityEpoch !== 'string' || !candidate.targetAuthorityEpoch.length || candidate.targetAuthorityEpoch.length > 128))
+        return null;
     if ('target' in candidate && candidate.target !== undefined && typeof candidate.target !== 'string') {
         return null;
     }
@@ -34,6 +46,9 @@ export function isEnvelopeKind(value) {
         || value === 'object.snapshot'
         || value === 'object.upsert'
         || value === 'object.remove'
+        || value === 'object.batch'
+        || value === 'action'
+        || value === 'action.receipt'
         || value === 'lobby.meta'
         || value === 'member.meta'
         || value === 'ping'

package/dist/replication.d.ts

@@ -0,0 +1,31 @@
+export interface ReplicationOptions {
+    bytesPerSecond?: number;
+    burstBytes?: number;
+    maxPendingBytes?: number;
+    maxPendingObjects?: number;
+    maxStateAgeMs?: number;
+}
+export interface ReplicationStats {
+    queuedBytes: number;
+    oldestStateAgeMs: number;
+    sentBytes: number;
+    sentBatches: number;
+    superseded: number;
+    expired: number;
+    rejected: number;
+}
+/** Per-peer replacement, expiry and budgets. flush() is driven by the game tick. */
+export declare class ReplicationScheduler<T> {
+    private readonly transmit;
+    private readonly peers;
+    readonly options: Required<ReplicationOptions>;
+    constructor(transmit: (peerId: string, values: T[]) => Promise<void | number>, options?: ReplicationOptions);
+    enqueue(peerId: string, key: string, value: T, bytes: number, priority?: number): Promise<void>;
+    flush(now?: number): void;
+    cancel(peerId: string, key: string): void;
+    closePeer(peerId: string): void;
+    close(): void;
+    diagnostics(peerId: string): ReplicationStats;
+    private peer;
+    private pump;
+}