openrtc-netcode 2.0.1 → 2.1.0

package/README.md

@@ -10,7 +10,7 @@ relay/direct, WebRTC DataChannel upgrades, and MoQ routes when enabled. Live
 membership and signaling use the OpenRTC coordination gateway; neither core
 netcode nor its payload path uses Firebase, Firestore, or RTDB.
 
-`preferredPayloadTransports` filters OpenRTC's typed application-readiness
+`preferredTransports` filters OpenRTC's typed application-readiness
 query; it does not request promotion. OpenRTC owns optional transport promotion
 and recovery, while netcode only observes route events. Netcode consumes one
 already-activated room handle, so it never retains an unused user or space

package/dist/client.d.ts

@@ -1,112 +1,3 @@
-import { ReplicatedObjectStore } from './objects.js';
-import { ReplicatedState } from './state.js';
-import { NetcodeVoiceController } from './voice.js';
-import type { CreateLobbyOptions, JoinLobbyOptions, NetcodeClient as NetcodeClientInterface, NetcodeEventHandler, NetcodeEventName, NetcodeLobby, NetcodeMessageHandler, NetcodeOptions, NetcodePeer, NetcodePeerStats, SendOptions } from './types.js';
-export declare class OpenRtcNetcodeClient implements NetcodeClientInterface {
-    private readonly options;
-    private runtime;
-    private localPeerId;
-    private currentLobby;
-    private currentRoomId;
-    private fallbackChannel;
-    private lobbyMetadata;
-    private memberMetadata;
-    private seq;
-    private started;
-    private stopped;
-    private stopWatchingRoom;
-    private stopRuntimeConnections;
-    private stopIncomingNetcodeChannel;
-    private peerPingTimer;
-    private readonly emitter;
-    private readonly messageListeners;
-    private readonly peersById;
-    private readonly peerStatsById;
-    private readonly connectionsByPeer;
-    private readonly channelsByPeer;
-    private readonly pendingChannelsByPeer;
-    private readonly connectionIds;
-    private readonly pendingPeerIds;
-    private readonly directSendWarnings;
-    private readonly introPeerIds;
-    private readonly seenEnvelopeIds;
-    private readonly seenEnvelopeOrder;
-    private readonly latestStateQueues;
-    private readonly stateStore;
-    private readonly objectStore;
-    private readonly voiceController;
-    constructor(options?: NetcodeOptions);
-    get peerId(): string | null;
-    get lobby(): NetcodeLobby | null;
-    get peers(): NetcodePeer[];
-    get peerStats(): NetcodePeerStats[];
-    get state(): ReplicatedState;
-    get objects(): ReplicatedObjectStore;
-    get voice(): NetcodeVoiceController;
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    createLobby(options?: CreateLobbyOptions): Promise<NetcodeLobby>;
-    joinLobby(lobbyId: string, options?: JoinLobbyOptions): Promise<NetcodeLobby>;
-    joinOrCreateLobby(lobbyId: string, options?: JoinLobbyOptions): Promise<NetcodeLobby>;
-    private activateLobby;
-    private joinLobbyWithRetry;
-    private getRoomMembersWithRetry;
-    leaveLobby(): Promise<void>;
-    send(peerId: string, type: string, payload: unknown, options?: SendOptions): Promise<void>;
-    broadcast(type: string, payload: unknown, options?: SendOptions): Promise<void>;
-    on<K extends NetcodeEventName>(event: K, handler: NetcodeEventHandler<K>): () => void;
-    onMessage<T = unknown>(type: string, handler: NetcodeMessageHandler<T>): () => void;
-    setLobbyData(key: string, value: string): Promise<void>;
-    setMemberData(key: string, value: string): Promise<void>;
-    private handleRoomMembers;
-    private reconcileMesh;
-    private attachConnection;
-    private sendPeerIntro;
-    private queuePeerIntro;
-    private handleConnectionMessage;
-    private markEnvelopeSeen;
-    private handleHello;
-    private handleUserMessage;
-    private handleStateSnapshot;
-    private handleStatePatch;
-    private handleObjectSnapshot;
-    private handleObjectUpsert;
-    private handleObjectRemove;
-    private handleLobbyMetadata;
-    private handleMemberMetadata;
-    private handleVoiceSignal;
-    private handlePong;
-    private sendStateSnapshot;
-    private sendObjectSnapshot;
-    private broadcastMemberMetadata;
-    private startPeerPingLoop;
-    private refreshPeerPayloadState;
-    private stopPeerPingLoop;
-    private broadcastEnvelope;
-    private broadcastLatestState;
-    private sendEnvelope;
-    private sendDirectEnvelope;
-    private warnDirectSendFailure;
-    private openFallbackChannel;
-    private closeFallbackChannel;
-    private resolveNetcodeChannel;
-    private resolvePeerTicket;
-    private attachNetcodeChannel;
-    private registerIncomingNetcodeChannel;
-    private readIncomingNetcodeStream;
-    private closeNetcodeChannels;
-    private createEnvelope;
-    private resolveStateOwner;
-    private upsertPeer;
-    private updatePeerStats;
-    private resolvePeerTransport;
-    private isPeerPayloadReady;
-    private resolvePayloadConnection;
-    private payloadReadinessOptions;
-    private refreshLobby;
-    private requireRuntime;
-    private requireLobby;
-    private registerNetcodeChannel;
-}
-export declare function createNetcode(options?: NetcodeOptions): OpenRtcNetcodeClient;
-export declare function shouldInitiateConnection(localPeerId: string, remotePeerId: string): boolean;
+import type { NetcodeClient as NetcodeClientInterface, NetcodeOptions } from './types.js';
+export declare function createNetcode(options?: NetcodeOptions): NetcodeClientInterface;
+export declare function shouldInitiate(localPeerId: string, remotePeerId: string): boolean;

package/dist/client.js

@@ -1,6 +1,6 @@
 import { TypedEmitter } from './events.js';
-import { decodeEnvelope, encodeEnvelope, isRecord, NETCODE_PROTOCOL, NETCODE_PROTOCOL_VERSION, } from './protocol.js';
-import { isNetcodeObjectState, ReplicatedObjectStore } from './objects.js';
+import { decodeEnvelope, encodeEnvelope, isRecord, NETCODE_PROTOCOL, PROTOCOL_VERSION, } from './protocol.js';
+import { isNetcodeObjectState, ObjectStore } from './objects.js';
 import { ReplicatedState } from './state.js';
 import { NetcodeVoiceController } from './voice.js';
 import { runtimeFromRoom } from './roomRuntime.js';
@@ -13,7 +13,7 @@ const CHANNEL_OPEN_TIMEOUT_MS = 15000;
 const UPGRADED_PAYLOAD_TRANSPORTS = new Set(['webrtc', 'webrtc-lan', 'moq']);
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
-export class OpenRtcNetcodeClient {
+class ClientImpl {
     constructor(options = {}) {
         this.options = options;
         this.runtime = null;
@@ -45,8 +45,8 @@ export class OpenRtcNetcodeClient {
         this.seenEnvelopeOrder = [];
         this.latestStateQueues = new Map();
         this.stateStore = new ReplicatedState((options) => this.resolveStateOwner(options), (key, value, owner) => this.broadcastLatestState(`state:${key}`, 'state.patch', { key, value, owner }));
-        this.objectStore = new ReplicatedObjectStore(() => this.localPeerId, (object) => this.broadcastLatestState(`object:${object.id}`, 'object.upsert', { object }), (id) => this.broadcastEnvelope('object.remove', { id }));
-        this.voiceController = new NetcodeVoiceController(() => this.localPeerId, () => this.peers, shouldInitiateConnection, (peerId, signal) => this.sendEnvelope(peerId, 'voice.signal', { signal }));
+        this.objectStore = new ObjectStore(() => this.localPeerId, (object) => this.broadcastLatestState(`object:${object.id}`, 'object.upsert', { object }), (id) => this.broadcastEnvelope('object.remove', { id }));
+        this.voiceController = new NetcodeVoiceController(() => this.localPeerId, () => this.peers, shouldInitiate, (peerId, signal) => this.sendEnvelope(peerId, 'voice.signal', { signal }));
     }
     get peerId() {
         return this.localPeerId;
@@ -318,7 +318,7 @@ export class OpenRtcNetcodeClient {
         // restart reciprocal application-key agreement on an already-admitted
         // physical connection. Explicit legacy/test runtimes retain the
         // deterministic mesh dial below.
-        if (this.runtime.managedConnectionLifecycle) {
+        if (this.runtime.lifecycle) {
             return;
         }
         const maxPeers = this.options.maxPeers ?? DEFAULT_MAX_PEERS;
@@ -326,7 +326,7 @@ export class OpenRtcNetcodeClient {
             if (this.connectionsByPeer.size >= maxPeers) {
                 return;
             }
-            if (!peer.ticket || !shouldInitiateConnection(this.localPeerId, peer.id)) {
+            if (!peer.ticket || !shouldInitiate(this.localPeerId, peer.id)) {
                 continue;
             }
             if (this.connectionsByPeer.has(peer.id) || this.pendingPeerIds.has(peer.id)) {
@@ -827,11 +827,11 @@ export class OpenRtcNetcodeClient {
     }
     registerIncomingNetcodeChannel() {
         const runtime = this.runtime;
-        if (typeof runtime?.onIncomingChannelStream !== 'function') {
+        if (typeof runtime?.onChannelStream !== 'function') {
             return;
         }
         this.stopIncomingNetcodeChannel?.();
-        this.stopIncomingNetcodeChannel = runtime.onIncomingChannelStream(NETCODE_CHANNEL_ID, (incoming) => {
+        this.stopIncomingNetcodeChannel = runtime.onChannelStream(NETCODE_CHANNEL_ID, (incoming) => {
             if (incoming.type !== 'bi' || !incoming.remoteNodeId || !incoming.stream) {
                 return false;
             }
@@ -885,7 +885,7 @@ export class OpenRtcNetcodeClient {
         }
         return {
             protocol: NETCODE_PROTOCOL,
-            v: NETCODE_PROTOCOL_VERSION,
+            v: PROTOCOL_VERSION,
             kind,
             lobbyId: this.currentRoomId,
             from: this.localPeerId,
@@ -964,21 +964,21 @@ export class OpenRtcNetcodeClient {
             return channel.connection;
         }
         const runtime = this.runtime;
-        if (typeof runtime?.getApplicationReadyConnections === 'function') {
-            return runtime.getApplicationReadyConnections(this.payloadReadinessOptions())
+        if (typeof runtime?.readyConnections === 'function') {
+            return runtime.readyConnections(this.payloadReadinessOptions())
                 .find((connection) => connection.remoteNodeId === peerId || connection.deviceId === peerId)
                 ?? null;
         }
         return this.connectionsByPeer.get(peerId) ?? null;
     }
     payloadReadinessOptions() {
-        const preferredTransports = this.options.preferredPayloadTransports ?? [];
+        const preferredTransports = this.options.preferredTransports ?? [];
         if (preferredTransports.length === 0) {
             return {};
         }
         return {
             preferredTransports,
-            allowFallbackAfterPreferredTransportFailure: true,
+            allowFallback: true,
         };
     }
     refreshLobby(members) {
@@ -1028,9 +1028,9 @@ export class OpenRtcNetcodeClient {
     }
 }
 export function createNetcode(options = {}) {
-    return new OpenRtcNetcodeClient(options);
+    return new ClientImpl(options);
 }
-export function shouldInitiateConnection(localPeerId, remotePeerId) {
+export function shouldInitiate(localPeerId, remotePeerId) {
     return localPeerId.localeCompare(remotePeerId) < 0;
 }
 function normalizeLobbyId(lobbyId) {

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { OpenRtcNetcodeClient, createNetcode, shouldInitiateConnection, } from './client.js';
+export { createNetcode, shouldInitiate, } from './client.js';
 export { runtimeFromRoom } from './roomRuntime.js';
-export { ReplicatedObjectStore } from './objects.js';
-export { NETCODE_PROTOCOL, NETCODE_PROTOCOL_VERSION, decodeEnvelope, encodeEnvelope, isEnvelopeKind, } from './protocol.js';
+export { ObjectStore } from './objects.js';
+export { NETCODE_PROTOCOL, PROTOCOL_VERSION, decodeEnvelope, encodeEnvelope, isEnvelopeKind, } from './protocol.js';
 export type { HelloBody, MetadataBody, NetcodeEnvelope, NetcodeEnvelopeKind, ObjectRemoveBody, ObjectSnapshotBody, ObjectUpsertBody, StatePatchBody, StateSnapshotBody, UserMessageBody, VoiceSignalBody, } from './protocol.js';
-export type { CreateLobbyOptions, JoinLobbyOptions, NetVar, NetVarOptions, NetcodeClient, NetcodeEventHandler, NetcodeEventName, NetcodeEvents, NetcodeLobby, NetcodeMessage, NetcodeMessageHandler, NetcodeObjectChange, NetcodeObjectState, NetcodeObjectStore, NetcodeObjectUpsert, NetcodeOptions, NetcodePeer, NetcodePeerStats, NetcodePhysicsState, NetcodeQuaternion, NetcodeReliability, NetcodeRuntime, NetcodeState, NetcodeTransform, NetcodeVector3, NetcodeVoice, NetcodeVoiceEvents, NetcodeVoiceOptions, NetcodeVoicePeer, NetcodeVoiceSignal, SendOptions, } from './types.js';
+export type { CreateLobbyOptions, JoinLobbyOptions, NetVar, NetVarOptions, NetcodeClient, NetcodeEventHandler, NetcodeEventName, NetcodeEvents, NetcodeLobby, NetcodeMessage, MessageHandler, NetcodeObjectChange, NetcodeObjectState, NetcodeObjectStore, NetcodeObjectUpsert, NetcodeOptions, NetcodePeer, NetcodePeerStats, NetcodePhysicsState, NetcodeQuaternion, NetcodeReliability, NetcodeRuntime, NetcodeState, NetcodeTransform, NetcodeVector3, NetcodeVoice, NetcodeVoiceEvents, NetcodeVoiceOptions, NetcodeVoicePeer, NetcodeVoiceSignal, SendOptions, } from './types.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { OpenRtcNetcodeClient, createNetcode, shouldInitiateConnection, } from './client.js';
+export { createNetcode, shouldInitiate, } from './client.js';
 export { runtimeFromRoom } from './roomRuntime.js';
-export { ReplicatedObjectStore } from './objects.js';
-export { NETCODE_PROTOCOL, NETCODE_PROTOCOL_VERSION, decodeEnvelope, encodeEnvelope, isEnvelopeKind, } from './protocol.js';
+export { ObjectStore } from './objects.js';
+export { NETCODE_PROTOCOL, PROTOCOL_VERSION, decodeEnvelope, encodeEnvelope, isEnvelopeKind, } from './protocol.js';

package/dist/objects.d.ts

@@ -1,6 +1,6 @@
 import type { NetcodeObjectChange, NetcodeObjectStore, NetcodeObjectState, NetcodeObjectUpsert } from './types.js';
 type ObjectListener = (change: NetcodeObjectChange) => void;
-export declare class ReplicatedObjectStore implements NetcodeObjectStore {
+export declare class ObjectStore implements NetcodeObjectStore {
     private readonly localPeerId;
     private readonly publishUpsert;
     private readonly publishRemove;

package/dist/objects.js

@@ -1,4 +1,4 @@
-export class ReplicatedObjectStore {
+export class ObjectStore {
     constructor(localPeerId, publishUpsert, publishRemove) {
         this.localPeerId = localPeerId;
         this.publishUpsert = publishUpsert;

package/dist/protocol.d.ts

@@ -1,9 +1,9 @@
 export declare const NETCODE_PROTOCOL = "openrtc-netcode";
-export declare const NETCODE_PROTOCOL_VERSION = 1;
+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' | 'voice.signal' | 'ping' | 'pong';
 export interface NetcodeEnvelope<TBody = unknown> {
     protocol: typeof NETCODE_PROTOCOL;
-    v: typeof NETCODE_PROTOCOL_VERSION;
+    v: typeof PROTOCOL_VERSION;
     kind: NetcodeEnvelopeKind;
     lobbyId: string;
     from: string;

package/dist/protocol.js

@@ -1,5 +1,5 @@
 export const NETCODE_PROTOCOL = 'openrtc-netcode';
-export const NETCODE_PROTOCOL_VERSION = 1;
+export const PROTOCOL_VERSION = 1;
 export function encodeEnvelope(envelope) {
     return JSON.stringify(envelope);
 }
@@ -8,7 +8,7 @@ export function decodeEnvelope(value) {
     if (!isRecord(candidate)) {
         return null;
     }
-    if (candidate.protocol !== NETCODE_PROTOCOL || candidate.v !== NETCODE_PROTOCOL_VERSION) {
+    if (candidate.protocol !== NETCODE_PROTOCOL || candidate.v !== PROTOCOL_VERSION) {
         return null;
     }
     if (!isEnvelopeKind(candidate.kind)) {

package/dist/roomRuntime.d.ts

@@ -1,7 +1,7 @@
-import type { OpenRTCRoomHandle } from 'openrtc';
+import type { Room } from 'openrtc';
 import type { NetcodeRuntime } from './types.js';
 /**
  * Adapts one OpenRTC 2.0 capability handle to netcode's transport-only runtime
  * contract. It never creates a second room, user scope, or base space.
  */
-export declare function runtimeFromRoom(room: OpenRTCRoomHandle): NetcodeRuntime;
+export declare function runtimeFromRoom(room: Room): NetcodeRuntime;

package/dist/roomRuntime.js

@@ -23,7 +23,7 @@ function peerMember(peer) {
 export function runtimeFromRoom(room) {
     const connections = () => room.diagnostics.connections();
     return {
-        managedConnectionLifecycle: true,
+        lifecycle: true,
         channels: room.channels,
         initialize: async () => undefined,
         start: async () => undefined,
@@ -81,8 +81,8 @@ export function runtimeFromRoom(room) {
             scope: `v2:room:${room.id}`,
             existingRouteOnly: true,
         }),
-        onIncomingChannelStream: (channelId, callback) => room.channels.onIncomingChannel(channelId, callback),
-        getApplicationReadyConnections: () => connections().filter((connection) => typeof connection.isReadyForApplicationPayload !== 'function'
-            || connection.isReadyForApplicationPayload()),
+        onChannelStream: (channelId, callback) => room.channels.onIncomingChannel(channelId, callback),
+        readyConnections: () => connections().filter((connection) => typeof connection.isPayloadReady !== 'function'
+            || connection.isPayloadReady()),
     };
 }

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-import type { RuntimeApplicationPayloadReadinessOptions as OpenRtcApplicationPayloadReadinessOptions, RuntimeIncomingStream, RuntimeScopedChannelOptions, RuntimeScopedLogicalChannel } from 'openrtc/runtime';
-import type { OpenRTCRoomHandle } from 'openrtc';
+import type { ReadinessOptions as OpenRtcApplicationPayloadReadinessOptions, IncomingStream, ScopedChannelOptions, ScopedLogicalChannel } from 'openrtc/runtime';
+import type { Room } from 'openrtc';
 import type { MetadataBody, NetcodeEnvelope, ObjectRemoveBody, ObjectSnapshotBody, ObjectUpsertBody, StatePatchBody, StateSnapshotBody, UserMessageBody, VoiceSignalBody } from './protocol.js';
 export interface NetcodeRuntime {
     /**
@@ -7,7 +7,7 @@ export interface NetcodeRuntime {
      * Protocol layers must observe its connections instead of issuing a
      * second ticket dial for the same avenue.
      */
-    managedConnectionLifecycle?: boolean;
+    lifecycle?: boolean;
     initialize?(): Promise<void> | void;
     start?(): Promise<void> | void;
     stop?(): Promise<void> | void;
@@ -25,17 +25,17 @@ export interface NetcodeRuntime {
         ticket: string;
         timeoutMs?: number;
     }): Promise<RuntimeConnectionLike>;
-    connectScopedChannel(options: RuntimeScopedChannelOptions): Promise<RuntimeScopedLogicalChannel>;
-    onIncomingChannelStream(channelId: string, callback: (stream: RuntimeIncomingStream) => boolean | void): () => void;
-    getApplicationReadyConnections(options?: RuntimeApplicationPayloadReadinessOptions): RuntimeConnectionLike[];
-    channels?: OpenRTCRoomHandle['channels'];
+    connectScopedChannel(options: ScopedChannelOptions): Promise<ScopedLogicalChannel>;
+    onChannelStream(channelId: string, callback: (stream: IncomingStream) => boolean | void): () => void;
+    readyConnections(options?: ReadinessOptions): RuntimeConnectionLike[];
+    channels?: Room['channels'];
 }
 export type NetcodeReliability = 'reliable';
 export interface NetcodeOptions {
     runtime?: NetcodeRuntime;
     /** Preferred 2.0 path: one already-activated ephemeral match room. */
-    room?: OpenRTCRoomHandle;
-    preferredPayloadTransports?: RuntimeApplicationPayloadReadinessOptions['preferredTransports'];
+    room?: Room;
+    preferredTransports?: ReadinessOptions['preferredTransports'];
     displayName?: string;
     maxPeers?: number;
     localFallback?: boolean;
@@ -211,7 +211,7 @@ export interface NetcodeEvents {
 }
 export type NetcodeEventName = keyof NetcodeEvents;
 export type NetcodeEventHandler<K extends NetcodeEventName> = (payload: NetcodeEvents[K]) => void;
-export type NetcodeMessageHandler<T = unknown> = (message: NetcodeMessage<T>) => void;
+export type MessageHandler<T = unknown> = (message: NetcodeMessage<T>) => void;
 export interface NetcodeMessage<T = unknown> {
     type: string;
     payload: T;
@@ -236,7 +236,7 @@ export interface NetcodeClient {
     send(peerId: string, type: string, payload: unknown, options?: SendOptions): Promise<void>;
     broadcast(type: string, payload: unknown, options?: SendOptions): Promise<void>;
     on<K extends NetcodeEventName>(event: K, handler: NetcodeEventHandler<K>): () => void;
-    onMessage<T = unknown>(type: string, handler: NetcodeMessageHandler<T>): () => void;
+    onMessage<T = unknown>(type: string, handler: MessageHandler<T>): () => void;
     setLobbyData(key: string, value: string): Promise<void>;
     setMemberData(key: string, value: string): Promise<void>;
 }
@@ -250,7 +250,7 @@ export type RuntimeConnectionLike = {
         parallelTransport?: string | null;
     };
     getAvailableTransports?(): string[];
-    isReadyForApplicationPayload?(options?: RuntimeApplicationPayloadReadinessOptions): boolean;
+    isPayloadReady?(options?: ReadinessOptions): boolean;
     onUpgradeStateChange?(callback: (state: 'none' | 'upgrading' | 'upgraded' | 'failed') => void): void;
     requestWebRTCUpgrade?(reason?: string): void;
     send(message: unknown): Promise<void> | void;
@@ -258,7 +258,7 @@ export type RuntimeConnectionLike = {
     onDisconnect(callback: () => void): void | (() => void);
     disconnect?(): Promise<void> | void;
 };
-export type RuntimeApplicationPayloadReadinessOptions = OpenRtcApplicationPayloadReadinessOptions;
+export type ReadinessOptions = OpenRtcApplicationPayloadReadinessOptions;
 export type RuntimeMemberLike = {
     nodeId?: string;
     userId?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openrtc-netcode",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -42,7 +42,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "openrtc": "^2.0.1"
+    "openrtc": "^2.1.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.1",