openrtc-netcode 1.0.0 → 2.0.0-rc.1

package/README.md

@@ -6,23 +6,31 @@ and exposes reliable typed messages, lightweight replicated state, networked
 objects, and browser voice-chat signaling.
 
 Gameplay payloads are sent over OpenRTC peer data paths only: Iroh
-relay/direct, WebRTC DataChannel upgrades, and MoQ routes when enabled. Firebase
-and Firestore remain part of OpenRTC's control plane for identity, discovery,
-rooms, tickets, and browser signaling metadata; `openrtc-netcode` does not use
-Firestore as a state or message relay.
+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
-query; it does not request promotion. When netcode creates the runtime,
-`transports` and `transportPriority` are forwarded to `OpenRTC(...)` at
-construction. An injected runtime must be configured by its owner. OpenRTC owns
-optional transport promotion and recovery, while netcode only observes later
-route events and never requests or suppresses upgrades.
+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
+avenue.
 
 ```ts
+import { OpenRTC } from 'openrtc';
 import { createNetcode } from 'openrtc-netcode';
 
-const netcode = createNetcode({ apiKey: 'pk_live_...' });
-await netcode.createLobby({ id: 'duel-room' });
+const rtc = OpenRTC({
+  apiKey: 'pk_live_...',
+  transports: { webrtc: true },
+});
+const room = await rtc.rooms.join('duel-room', {
+  access: 'capability',
+  membership: 'ephemeral',
+  maxPeers: 4,
+});
+const netcode = createNetcode({ room });
+await netcode.joinLobby('duel-room');
 
 netcode.onMessage('chat', (message) => {
   console.log(message.from, message.payload);

package/dist/client.d.ts

@@ -5,7 +5,6 @@ import type { CreateLobbyOptions, JoinLobbyOptions, NetcodeClient as NetcodeClie
 export declare class OpenRtcNetcodeClient implements NetcodeClientInterface {
     private readonly options;
     private runtime;
-    private ownsRuntime;
     private localPeerId;
     private currentLobby;
     private currentRoomId;
@@ -32,6 +31,7 @@ export declare class OpenRtcNetcodeClient implements NetcodeClientInterface {
     private readonly introPeerIds;
     private readonly seenEnvelopeIds;
     private readonly seenEnvelopeOrder;
+    private readonly latestStateQueues;
     private readonly stateStore;
     private readonly objectStore;
     private readonly voiceController;
@@ -83,6 +83,7 @@ export declare class OpenRtcNetcodeClient implements NetcodeClientInterface {
     private refreshPeerPayloadState;
     private stopPeerPingLoop;
     private broadcastEnvelope;
+    private broadcastLatestState;
     private sendEnvelope;
     private sendDirectEnvelope;
     private warnDirectSendFailure;

package/dist/client.js

@@ -1,9 +1,10 @@
-import { OpenRTC } from 'openrtc';
 import { TypedEmitter } from './events.js';
 import { decodeEnvelope, encodeEnvelope, isRecord, NETCODE_PROTOCOL, NETCODE_PROTOCOL_VERSION, } from './protocol.js';
 import { isNetcodeObjectState, ReplicatedObjectStore } from './objects.js';
 import { ReplicatedState } from './state.js';
 import { NetcodeVoiceController } from './voice.js';
+import { runtimeFromRoom } from './roomRuntime.js';
+import { LatestStateQueue } from './latestState.js';
 const DEFAULT_MAX_PEERS = 8;
 const NETCODE_CHANNEL_ID = 'openrtc-netcode/v1';
 const PING_INTERVAL_MS = 2000;
@@ -16,7 +17,6 @@ export class OpenRtcNetcodeClient {
     constructor(options = {}) {
         this.options = options;
         this.runtime = null;
-        this.ownsRuntime = false;
         this.localPeerId = null;
         this.currentLobby = null;
         this.currentRoomId = null;
@@ -43,8 +43,9 @@ export class OpenRtcNetcodeClient {
         this.introPeerIds = new Set();
         this.seenEnvelopeIds = new Set();
         this.seenEnvelopeOrder = [];
-        this.stateStore = new ReplicatedState((options) => this.resolveStateOwner(options), (key, value, owner) => this.broadcastEnvelope('state.patch', { key, value, owner }));
-        this.objectStore = new ReplicatedObjectStore(() => this.localPeerId, (object) => this.broadcastEnvelope('object.upsert', { object }), (id) => this.broadcastEnvelope('object.remove', { id }));
+        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 }));
     }
     get peerId() {
@@ -74,23 +75,10 @@ export class OpenRtcNetcodeClient {
         }
         this.started = true;
         this.stopped = false;
-        this.runtime = this.options.runtime ?? OpenRTC({
-            apiKey: this.options.apiKey,
-            projectId: this.options.projectId,
-            authMode: this.options.authMode,
-            discoveryMode: this.options.discoveryMode,
-            allowAnonymousHostedDefaults: this.options.allowAnonymousHostedDefaults,
-            space: this.options.space,
-            spaceKey: this.options.spaceKey,
-            spaceTokenProvider: this.options.spaceTokenProvider,
-            storagePrefix: this.options.storagePrefix,
-            nodeIdPersistence: this.options.nodeIdPersistence,
-            transports: this.options.transports,
-            transportPriority: this.options.transportPriority,
-            strictMode: this.options.strictMode,
-            turnCredentialsProvider: this.options.turnCredentialsProvider,
-        });
-        this.ownsRuntime = !this.options.runtime;
+        if (!this.options.runtime && !this.options.room) {
+            throw new Error('openrtc-netcode requires an activated OpenRTC 2.0 room adapter or an explicit openrtc/runtime client.');
+        }
+        this.runtime = this.options.runtime ?? runtimeFromRoom(this.options.room);
         await callOptional(this.runtime, 'initialize');
         await callOptional(this.runtime, 'start');
         this.localPeerId = await this.runtime.getNodeId();
@@ -123,15 +111,13 @@ export class OpenRtcNetcodeClient {
         this.peerStatsById.clear();
         this.seenEnvelopeIds.clear();
         this.seenEnvelopeOrder.length = 0;
+        this.latestStateQueues.clear();
         this.stopPeerPingLoop();
         this.peersById.clear();
         this.objectStore.clear();
         await this.voiceController.stop();
         this.emitter.clear();
         this.messageListeners.clear();
-        if (this.ownsRuntime) {
-            await callOptional(this.runtime, 'stop');
-        }
         this.runtime = null;
         this.started = false;
     }
@@ -237,6 +223,7 @@ export class OpenRtcNetcodeClient {
         this.peerStatsById.clear();
         this.seenEnvelopeIds.clear();
         this.seenEnvelopeOrder.length = 0;
+        this.latestStateQueues.clear();
         this.objectStore.clear();
         await this.voiceController.stop();
         if (runtime && roomId) {
@@ -326,6 +313,14 @@ export class OpenRtcNetcodeClient {
         if (!this.runtime || !this.localPeerId) {
             return;
         }
+        // An OpenRTC 2.0 room capability is the sole owner of its peer
+        // lifecycle. Calling connectByTicket here races that owner and can
+        // 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) {
+            return;
+        }
         const maxPeers = this.options.maxPeers ?? DEFAULT_MAX_PEERS;
         for (const peer of this.peersById.values()) {
             if (this.connectionsByPeer.size >= maxPeers) {
@@ -684,6 +679,14 @@ export class OpenRtcNetcodeClient {
         const sends = Array.from(this.connectionsByPeer.keys()).map((peerId) => this.sendDirectEnvelope(peerId, envelope));
         await Promise.all(sends);
     }
+    broadcastLatestState(key, kind, body) {
+        let queue = this.latestStateQueues.get(key);
+        if (!queue) {
+            queue = new LatestStateQueue((state) => this.broadcastEnvelope(state.kind, state.body));
+            this.latestStateQueues.set(key, queue);
+        }
+        return queue.push({ kind, body });
+    }
     async sendEnvelope(peerId, kind, body) {
         const envelope = this.createEnvelope(kind, body, peerId);
         if (this.fallbackChannel) {
@@ -969,10 +972,7 @@ export class OpenRtcNetcodeClient {
         return this.connectionsByPeer.get(peerId) ?? null;
     }
     payloadReadinessOptions() {
-        const preferredTransports = this.options.preferredPayloadTransports
-            ?? (this.ownsRuntime
-                ? derivePreferredPayloadTransports(this.options.transports, this.options.transportPriority)
-                : []);
+        const preferredTransports = this.options.preferredPayloadTransports ?? [];
         if (preferredTransports.length === 0) {
             return {};
         }
@@ -1127,21 +1127,6 @@ function isRoomAdmissionTransientError(error) {
     return isRoomNotFoundError(error)
         || /permission[_ -]?denied|permission denied|forbidden|code["']?\s*:\s*403|status["']?\s*:\s*["']?permission_denied/i.test(text);
 }
-function derivePreferredPayloadTransports(transports, transportPriority) {
-    const configuredPriority = (transportPriority ?? [])
-        .filter((transport) => UPGRADED_PAYLOAD_TRANSPORTS.has(transport));
-    if (configuredPriority.length > 0) {
-        return [...new Set(configuredPriority)];
-    }
-    const preferred = [];
-    if (transports?.webrtc) {
-        preferred.push('webrtc-lan', 'webrtc');
-    }
-    if (transports?.moq) {
-        preferred.push('moq');
-    }
-    return preferred;
-}
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { OpenRtcNetcodeClient, createNetcode, shouldInitiateConnection, } 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 type { HelloBody, MetadataBody, NetcodeEnvelope, NetcodeEnvelopeKind, ObjectRemoveBody, ObjectSnapshotBody, ObjectUpsertBody, StatePatchBody, StateSnapshotBody, UserMessageBody, VoiceSignalBody, } from './protocol.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export { OpenRtcNetcodeClient, createNetcode, shouldInitiateConnection, } 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';

package/dist/latestState.d.ts

@@ -0,0 +1,9 @@
+/** Coalesces only queued values; the in-flight state is allowed to finish. */
+export declare class LatestStateQueue<T> {
+    private readonly transmit;
+    private pending;
+    private running;
+    constructor(transmit: (value: T) => Promise<void>);
+    push(value: T): Promise<void>;
+    private pump;
+}

package/dist/latestState.js

@@ -0,0 +1,44 @@
+/** Coalesces only queued values; the in-flight state is allowed to finish. */
+export class LatestStateQueue {
+    constructor(transmit) {
+        this.transmit = transmit;
+        this.pending = null;
+        this.running = false;
+    }
+    push(value) {
+        return new Promise((resolve, reject) => {
+            if (this.pending) {
+                this.pending.value = value;
+                this.pending.waiters.push({ resolve, reject });
+            }
+            else {
+                this.pending = { value, waiters: [{ resolve, reject }] };
+            }
+            this.pump();
+        });
+    }
+    pump() {
+        if (this.running)
+            return;
+        this.running = true;
+        void (async () => {
+            while (this.pending) {
+                const current = this.pending;
+                this.pending = null;
+                try {
+                    await this.transmit(current.value);
+                    for (const waiter of current.waiters)
+                        waiter.resolve();
+                }
+                catch (error) {
+                    for (const waiter of current.waiters)
+                        waiter.reject(error);
+                }
+            }
+        })().finally(() => {
+            this.running = false;
+            if (this.pending)
+                this.pump();
+        });
+    }
+}

package/dist/roomRuntime.d.ts

@@ -0,0 +1,7 @@
+import type { OpenRTCRoomHandle } 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;

package/dist/roomRuntime.js

@@ -0,0 +1,88 @@
+function normalized(value) {
+    return value.trim().toUpperCase();
+}
+function assertRoom(room, requested) {
+    if (normalized(room.id) !== normalized(requested)) {
+        throw new Error(`Activated OpenRTC room '${room.id}' cannot join '${requested}'.`);
+    }
+}
+function peerMember(peer) {
+    const peerId = String(peer.nodeId ?? peer.id ?? peer.deviceId ?? '');
+    return {
+        nodeId: peerId,
+        userId: typeof peer.userId === 'string' ? peer.userId : undefined,
+        ticket: typeof peer.ticket === 'string' ? peer.ticket : undefined,
+        joinedAt: typeof peer.connectedAt === 'number' ? peer.connectedAt : Date.now(),
+        lastSeenAt: Date.now(),
+    };
+}
+/**
+ * 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 function runtimeFromRoom(room) {
+    const connections = () => room.diagnostics.connections();
+    return {
+        managedConnectionLifecycle: true,
+        channels: room.channels,
+        initialize: async () => undefined,
+        start: async () => undefined,
+        stop: async () => undefined,
+        getNodeId: async () => {
+            const status = await room.diagnostics.status();
+            const nodeId = typeof status.localNodeId === 'string' ? status.localNodeId.trim() : '';
+            if (!nodeId)
+                throw new Error('The activated OpenRTC room has no local peer identity yet.');
+            return nodeId;
+        },
+        createRoom: async (roomId = room.id) => {
+            assertRoom(room, roomId);
+            return normalized(room.id);
+        },
+        joinRoom: async (roomId) => {
+            assertRoom(room, roomId);
+            return connections();
+        },
+        leaveRoom: async (roomId) => {
+            assertRoom(room, roomId);
+            await room.leave();
+        },
+        watchRoom: (roomId, callback) => {
+            assertRoom(room, roomId);
+            return room.peers.watch((peers) => callback(peers.map((peer) => peerMember(peer))));
+        },
+        getRoomMembers: async (roomId) => {
+            assertRoom(room, roomId);
+            return room.peers.listConnected()
+                .map((peer) => peerMember(peer));
+        },
+        onConnection: (callback) => {
+            const seen = new Set();
+            const publish = (connection) => {
+                const id = String(connection.id ?? connection.remoteNodeId ?? '');
+                if (!id || seen.has(id))
+                    return;
+                seen.add(id);
+                callback(connection);
+            };
+            connections().forEach(publish);
+            return room.diagnostics.onConnection((connection) => {
+                publish(connection);
+            });
+        },
+        getConnections: connections,
+        connectByTicket: ({ ticket, timeoutMs }) => room.peers.connect({ ticket, timeoutMs }),
+        // The room capability already authorized the peer route. A protocol
+        // channel is not another admission avenue and must not replace that
+        // lifecycle scope with the channel identifier (which would trigger a
+        // second scoped dial on every send while the new scope is absent).
+        connectScopedChannel: (options) => room.channels.connectScoped({
+            ...options,
+            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()),
+    };
+}

package/dist/types.d.ts

@@ -1,26 +1,41 @@
-import type { OpenRTC } from 'openrtc';
-import type { RuntimeApplicationPayloadReadinessOptions as OpenRtcApplicationPayloadReadinessOptions, RuntimeClient } from 'openrtc/runtime';
+import type { RuntimeApplicationPayloadReadinessOptions as OpenRtcApplicationPayloadReadinessOptions, RuntimeIncomingStream, RuntimeScopedChannelOptions, RuntimeScopedLogicalChannel } from 'openrtc/runtime';
+import type { OpenRTCRoomHandle } from 'openrtc';
 import type { MetadataBody, NetcodeEnvelope, ObjectRemoveBody, ObjectSnapshotBody, ObjectUpsertBody, StatePatchBody, StateSnapshotBody, UserMessageBody, VoiceSignalBody } from './protocol.js';
-type OpenrtcClientOptions = Parameters<typeof OpenRTC>[0];
-export type NetcodeRuntime = RuntimeClient;
+export interface NetcodeRuntime {
+    /**
+     * The activated capability owns discovery and physical peer lifecycle.
+     * Protocol layers must observe its connections instead of issuing a
+     * second ticket dial for the same avenue.
+     */
+    managedConnectionLifecycle?: boolean;
+    initialize?(): Promise<void> | void;
+    start?(): Promise<void> | void;
+    stop?(): Promise<void> | void;
+    getNodeId(): Promise<string>;
+    createRoom(roomId?: string): Promise<string>;
+    joinRoom(roomId: string, options?: {
+        bootstrapPeers?: boolean;
+    }): Promise<RuntimeConnectionLike[]>;
+    leaveRoom(roomId: string): Promise<void>;
+    watchRoom(roomId: string, callback: (members: RuntimeMemberLike[]) => void): () => void;
+    getRoomMembers(roomId: string): Promise<RuntimeMemberLike[]>;
+    onConnection(callback: (connection: RuntimeConnectionLike) => void): () => void;
+    getConnections(): RuntimeConnectionLike[];
+    connectByTicket(target: {
+        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'];
+}
 export type NetcodeReliability = 'reliable';
 export interface NetcodeOptions {
     runtime?: NetcodeRuntime;
-    apiKey?: OpenrtcClientOptions['apiKey'];
-    projectId?: OpenrtcClientOptions['projectId'];
-    authMode?: OpenrtcClientOptions['authMode'];
-    discoveryMode?: OpenrtcClientOptions['discoveryMode'];
-    allowAnonymousHostedDefaults?: OpenrtcClientOptions['allowAnonymousHostedDefaults'];
-    space?: OpenrtcClientOptions['space'];
-    spaceKey?: OpenrtcClientOptions['spaceKey'];
-    spaceTokenProvider?: NonNullable<OpenrtcClientOptions>['spaceTokenProvider'];
-    storagePrefix?: OpenrtcClientOptions['storagePrefix'];
-    nodeIdPersistence?: OpenrtcClientOptions['nodeIdPersistence'];
-    transports?: OpenrtcClientOptions['transports'];
-    transportPriority?: OpenrtcClientOptions['transportPriority'];
+    /** Preferred 2.0 path: one already-activated ephemeral match room. */
+    room?: OpenRTCRoomHandle;
     preferredPayloadTransports?: RuntimeApplicationPayloadReadinessOptions['preferredTransports'];
-    strictMode?: OpenrtcClientOptions['strictMode'];
-    turnCredentialsProvider?: NonNullable<OpenrtcClientOptions>['turnCredentialsProvider'];
     displayName?: string;
     maxPeers?: number;
     localFallback?: boolean;
@@ -235,6 +250,7 @@ export type RuntimeConnectionLike = {
         parallelTransport?: string | null;
     };
     getAvailableTransports?(): string[];
+    isReadyForApplicationPayload?(options?: RuntimeApplicationPayloadReadinessOptions): boolean;
     onUpgradeStateChange?(callback: (state: 'none' | 'upgrading' | 'upgraded' | 'failed') => void): void;
     requestWebRTCUpgrade?(reason?: string): void;
     send(message: unknown): Promise<void> | void;
@@ -253,4 +269,3 @@ export type RuntimeMemberLike = {
     metadata?: string | Record<string, unknown> | null;
 };
 export type RuntimeEnvelopeBody = UserMessageBody | StateSnapshotBody | StatePatchBody | ObjectSnapshotBody | ObjectUpsertBody | ObjectRemoveBody | MetadataBody | VoiceSignalBody | Record<string, unknown>;
-export {};

package/package.json

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