@matter-server/ws-controller 0.7.0-alpha.0-20260512-b404bea → 0.7.0

package/src/controller/Nodes.ts

@@ -22,36 +22,24 @@ import { AttributeDataCache } from "./AttributeDataCache.js";
 export class Nodes {
     #nodes = new Map<NodeId, PairedNode>();
     #attributeCache = new AttributeDataCache();
-    /** Track previous connection state for availability debouncing */
-    #previousStates = new Map<NodeId, NodeStates>();
-    /** Cached availability so serialization and event paths always agree */
+    /** Cached so serialization and event paths always agree on availability. */
     #lastAvailability = new Map<NodeId, boolean>();
     /**
-     * Endpoint additions queued until the next nodeStructureChanged for that node.
-     * Preserves the wire contract used by python-matter-server: endpoint_added must
-     * arrive AFTER a node_updated that already carries the new endpoint, so consumers
-     * (e.g., Home Assistant) can resolve node.endpoints[endpoint_id] in their callback.
+     * Buffered endpoint_added events. python-matter-server wire contract requires
+     * node_updated (carrying the new endpoint) to arrive before endpoint_added,
+     * so HA can resolve node.endpoints[endpoint_id] in its callback.
      */
     #pendingEndpointAdds = new Map<NodeId, EndpointNumber[]>();
 
-    /**
-     * Get the attribute cache instance.
-     */
     get attributeCache(): AttributeDataCache {
         return this.#attributeCache;
     }
 
-    /**
-     * Get all node IDs.
-     */
     getIds(): NodeId[] {
         return Array.from(this.#nodes.keys());
     }
 
-    /**
-     * Get a node by ID.
-     * @throws ServerError if node not found
-     */
+    /** @throws ServerError if node not found */
     get(nodeId: NodeId): PairedNode {
         const node = this.#nodes.get(nodeId);
         if (node === undefined) {
@@ -60,34 +48,21 @@ export class Nodes {
         return node;
     }
 
-    /**
-     * Check if a node exists.
-     */
     has(nodeId: NodeId): boolean {
         return this.#nodes.has(nodeId);
     }
 
-    /**
-     * Add or update a node in storage.
-     */
     set(nodeId: NodeId, node: PairedNode): void {
         this.#nodes.set(nodeId, node);
     }
 
-    /**
-     * Remove a node from storage and clear its attribute cache and state tracking.
-     */
     delete(nodeId: NodeId): void {
         this.#nodes.delete(nodeId);
         this.#attributeCache.delete(nodeId);
-        this.#previousStates.delete(nodeId);
         this.#lastAvailability.delete(nodeId);
         this.#pendingEndpointAdds.delete(nodeId);
     }
 
-    /**
-     * Buffer an endpoint_added until the next nodeStructureChanged for that node.
-     */
     queueEndpointAdded(nodeId: NodeId, endpointId: EndpointNumber): void {
         let queue = this.#pendingEndpointAdds.get(nodeId);
         if (queue === undefined) {
@@ -97,10 +72,7 @@ export class Nodes {
         queue.push(endpointId);
     }
 
-    /**
-     * Take ownership of buffered endpoint additions for a node and clear the queue.
-     * Returned array is in insertion order; an empty array is returned if nothing is queued.
-     */
+    /** Returns insertion-ordered queue; empty if nothing pending. */
     drainPendingEndpointAdds(nodeId: NodeId): EndpointNumber[] {
         const queue = this.#pendingEndpointAdds.get(nodeId);
         if (queue === undefined || queue.length === 0) {
@@ -110,30 +82,19 @@ export class Nodes {
         return queue;
     }
 
-    /**
-     * Initialize state tracking for a newly paired/discovered node.
-     * Sets previous state and initial availability so the first stateChanged event
-     * has a real previous state instead of undefined.
-     */
     seedState(nodeId: NodeId, initialState: NodeStates): void {
-        this.#previousStates.set(nodeId, initialState);
         this.#lastAvailability.set(nodeId, initialState === NodeStates.Connected);
     }
 
-    /**
-     * Process a state change for a node. Reads previous state BEFORE updating,
-     * computes new availability, and updates both tracking maps atomically.
-     * Returns whether availability changed and the new value.
-     */
+    /** `debouncePending` = reconnect timer armed by caller; keeps non-Connected states available. */
     processStateChange(
         nodeId: NodeId,
         newState: NodeStates,
+        debouncePending: boolean,
     ): { availabilityChanged: true; available: boolean } | { availabilityChanged: false } {
-        const previousState = this.#previousStates.get(nodeId);
         const wasAvailable = this.#lastAvailability.get(nodeId) ?? false;
-        const available = this.isNodeAvailable(newState, previousState);
+        const available = this.isNodeAvailable(newState, debouncePending);
 
-        this.#previousStates.set(nodeId, newState);
         this.#lastAvailability.set(nodeId, available);
 
         if (wasAvailable !== available) {
@@ -142,47 +103,21 @@ export class Nodes {
         return { availabilityChanged: false };
     }
 
-    /**
-     * Force a node to unavailable state. Used by reconnect timeout
-     * when debounce period expires without reconnection.
-     * Only updates #lastAvailability — #previousStates is left as-is because
-     * processStateChange() will overwrite it on the next real state transition.
-     * Returns true if the node was previously considered available.
-     */
+    /** Returns true if the node was previously considered available. */
     forceUnavailable(nodeId: NodeId): boolean {
         const wasAvailable = this.#lastAvailability.get(nodeId) ?? false;
         this.#lastAvailability.set(nodeId, false);
         return wasAvailable;
     }
 
-    /**
-     * Determine if a node should be considered available based on its connection state.
-     * Uses debouncing logic similar to Python Matter Server:
-     * - Connected: available
-     * - Reconnecting when previously Connected: still available (debouncing)
-     * - WaitingForDeviceDiscovery or Disconnected: unavailable
-     *
-     * @param currentState Current connection state
-     * @param previousState Previous connection state (undefined if first state change)
-     * @returns true if node should be considered available
-     */
-    isNodeAvailable(currentState: NodeStates, previousState?: NodeStates): boolean {
+    isNodeAvailable(currentState: NodeStates, debouncePending = false): boolean {
         if (currentState === NodeStates.Connected) {
             return true;
         }
-        // Debounce: if transitioning from Connected to Reconnecting, still consider available
-        if (currentState === NodeStates.Reconnecting && previousState === NodeStates.Connected) {
-            return true;
-        }
-        // WaitingForDeviceDiscovery, Disconnected, or Reconnecting from non-connected state
-        return false;
+        return debouncePending;
     }
 
-    /**
-     * Check if a node is available. Returns the cached availability value set by
-     * seedState/processStateChange/forceUnavailable, avoiding the race where
-     * recomputing from live state disagrees with the event path's determination.
-     */
+    /** Returns the cached value, not a recomputation — avoids disagreement with the event path. */
     isAvailable(nodeId: NodeId): boolean {
         return this.#lastAvailability.get(nodeId) ?? false;
     }

package/src/controller/WebRtcCallbackBridge.ts

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { WebRtcCallbackData } from "@matter-server/ws-client";
+import { Logger } from "@matter/main";
+import type { WebRtcTransportRequestorServer } from "./behaviors/WebRtcTransportRequestorServer.js";
+
+const logger = Logger.get("WebRtcCallbackBridge");
+
+export function attachWebRtcCallbackBridge(
+    events: WebRtcTransportRequestorServer.Events,
+    emit: (data: WebRtcCallbackData) => void,
+): void {
+    events.offer.on((session, request) => {
+        logger.info(
+            `offer from peer node=${session.peerNodeId} ep=${session.peerEndpointId} session=${session.id} sdpLen=${request.sdp.length}`,
+        );
+        emit({
+            event_type: "offer",
+            webrtc_session_id: session.id,
+            node_id: session.peerNodeId,
+            endpoint_id: session.peerEndpointId,
+            fabric_index: session.fabricIndex,
+            data: {
+                sdp: request.sdp,
+                ice_servers: request.iceServers,
+                ice_transport_policy: request.iceTransportPolicy,
+            },
+        });
+    });
+    events.answer.on((session, sdp) => {
+        logger.info(
+            `answer from peer node=${session.peerNodeId} ep=${session.peerEndpointId} session=${session.id} sdpLen=${sdp.length}`,
+        );
+        emit({
+            event_type: "answer",
+            webrtc_session_id: session.id,
+            node_id: session.peerNodeId,
+            endpoint_id: session.peerEndpointId,
+            fabric_index: session.fabricIndex,
+            data: { sdp },
+        });
+    });
+    events.iceCandidates.on((session, candidates) => {
+        logger.info(
+            `ice_candidates from peer node=${session.peerNodeId} ep=${session.peerEndpointId} session=${session.id} count=${candidates.length}`,
+        );
+        emit({
+            event_type: "ice_candidates",
+            webrtc_session_id: session.id,
+            node_id: session.peerNodeId,
+            endpoint_id: session.peerEndpointId,
+            fabric_index: session.fabricIndex,
+            data: {
+                ice_candidates: candidates.map(c => ({
+                    candidate: c.candidate,
+                    sdpMid: c.sdpMid ?? null,
+                    sdpMLineIndex: c.sdpmLineIndex ?? null,
+                })),
+            },
+        });
+    });
+    events.end.on((session, reason) => {
+        logger.info(
+            `end from peer node=${session.peerNodeId} ep=${session.peerEndpointId} session=${session.id} reason=${reason}`,
+        );
+        emit({
+            event_type: "end",
+            webrtc_session_id: session.id,
+            node_id: session.peerNodeId,
+            endpoint_id: session.peerEndpointId,
+            fabric_index: session.fabricIndex,
+            data: { reason },
+        });
+    });
+}

package/src/controller/behaviors/WebRtcTransportRequestorServer.ts

@@ -0,0 +1,149 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Observable } from "@matter/general";
+import { Logger, Node } from "@matter/main";
+import type { ServerNode } from "@matter/main";
+import { AccessControlServer } from "@matter/node/behaviors/access-control";
+import { WebRtcTransportRequestorBehavior } from "@matter/node/behaviors/web-rtc-transport-requestor";
+import { assertRemoteActor, FabricAuthority, NodeSession } from "@matter/protocol";
+import { Status, StatusResponseError } from "@matter/types";
+import { AccessControl } from "@matter/types/clusters/access-control";
+import { WebRtcTransportDefinitions } from "@matter/types/clusters/web-rtc-transport-definitions";
+import { WebRtcTransportRequestor } from "@matter/types/clusters/web-rtc-transport-requestor";
+
+type WebRtcSession = WebRtcTransportDefinitions.WebRtcSession;
+
+const logger = Logger.get("WebRtcTransportRequestorServer");
+
+export class WebRtcTransportRequestorServer extends WebRtcTransportRequestorBehavior {
+    declare state: WebRtcTransportRequestorServer.State;
+    declare events: WebRtcTransportRequestorServer.Events;
+
+    upsertSession(session: WebRtcSession): void {
+        const enriched: WebRtcSession = {
+            ...session,
+            videoStreamId: session.videoStreams?.[0] ?? null,
+            audioStreamId: session.audioStreams?.[0] ?? null,
+        };
+        const sessions = this.state.currentSessions;
+        const idx = sessions.findIndex(s => s.id === session.id);
+        if (idx === -1) {
+            this.state.currentSessions = [...sessions, enriched];
+        } else {
+            this.state.currentSessions = sessions.map((s, i) => (i === idx ? enriched : s));
+        }
+    }
+
+    removeSession(id: number): void {
+        this.state.currentSessions = this.state.currentSessions.filter(s => s.id !== id);
+    }
+
+    override async offer(request: WebRtcTransportRequestor.OfferRequest): Promise<void> {
+        logger.info(`incoming Offer webRtcSessionId=${request.webRtcSessionId} sdpLen=${request.sdp.length}`);
+        const session = this.#findSessionStrict(request.webRtcSessionId);
+        this.events.offer.emit(session, request);
+    }
+
+    override async answer(request: WebRtcTransportRequestor.AnswerRequest): Promise<void> {
+        logger.info(`incoming Answer webRtcSessionId=${request.webRtcSessionId} sdpLen=${request.sdp.length}`);
+        const session = this.#findSessionStrict(request.webRtcSessionId);
+        this.events.answer.emit(session, request.sdp);
+    }
+
+    override async iceCandidates(request: WebRtcTransportRequestor.IceCandidatesRequest): Promise<void> {
+        logger.info(
+            `incoming ICECandidates webRtcSessionId=${request.webRtcSessionId} count=${request.iceCandidates.length}`,
+        );
+        if (request.iceCandidates.length === 0) {
+            throw new StatusResponseError("ICE candidates list must not be empty", Status.InvalidCommand);
+        }
+        const session = this.#findSessionStrict(request.webRtcSessionId);
+        this.events.iceCandidates.emit(session, request.iceCandidates);
+    }
+
+    override async end(request: WebRtcTransportRequestor.EndRequest): Promise<void> {
+        logger.info(`incoming End webRtcSessionId=${request.webRtcSessionId} reason=${request.reason}`);
+        const session = this.#findSessionStrict(request.webRtcSessionId);
+        this.removeSession(request.webRtcSessionId);
+        this.events.end.emit(session, request.reason);
+    }
+
+    override async initialize() {
+        const node = Node.forEndpoint(this.endpoint) as ServerNode;
+        logger.info(
+            `initialized on endpoint=${this.endpoint.number} (id="${this.endpoint.id}") cluster=0x${WebRtcTransportRequestor.id.toString(16)}`,
+        );
+        this.reactTo(node.lifecycle.online, this.#nodeOnline);
+        if (node.lifecycle.isOnline) {
+            await this.#nodeOnline();
+        }
+    }
+
+    async #nodeOnline() {
+        const fabricAuthority = this.env.get(FabricAuthority);
+        const ownFabric = fabricAuthority.fabrics[0];
+        if (!ownFabric) {
+            // void: fabricAdded is a synchronous observable; awaiting #nodeOnline here deadlocks setStateOf.
+            fabricAuthority.fabricAdded.once(() => void this.#nodeOnline());
+            return;
+        }
+
+        const node = Node.forEndpoint(this.endpoint) as ServerNode;
+        await node.act(agent => agent.load(AccessControlServer));
+        if (node.behaviors.has(AccessControlServer)) {
+            if (
+                !node
+                    .stateOf(AccessControlServer)
+                    .acl.some(
+                        ({ fabricIndex, privilege, authMode, subjects, targets }) =>
+                            fabricIndex === ownFabric.fabricIndex &&
+                            privilege === AccessControl.AccessControlEntryPrivilege.Operate &&
+                            authMode === AccessControl.AccessControlEntryAuthMode.Case &&
+                            subjects?.length === 0 &&
+                            targets?.length === 1 &&
+                            targets[0].endpoint === this.endpoint.number &&
+                            targets[0].cluster === WebRtcTransportRequestor.id,
+                    )
+            ) {
+                const acl = [
+                    ...node.stateOf(AccessControlServer).acl,
+                    {
+                        fabricIndex: ownFabric.fabricIndex,
+                        privilege: AccessControl.AccessControlEntryPrivilege.Operate,
+                        authMode: AccessControl.AccessControlEntryAuthMode.Case,
+                        subjects: [],
+                        targets: [{ endpoint: this.endpoint.number, cluster: WebRtcTransportRequestor.id }],
+                    },
+                ];
+                await node.setStateOf(AccessControlServer, { acl });
+            }
+        }
+    }
+
+    #findSessionStrict(id: number): WebRtcSession {
+        assertRemoteActor(this.context);
+        NodeSession.assert(this.context.session);
+        const peer = this.context.session.peerAddress;
+        const session = this.state.currentSessions.find(s => s.id === id);
+        if (session === undefined || session.fabricIndex !== peer.fabricIndex || session.peerNodeId !== peer.nodeId) {
+            throw new StatusResponseError(`WebRTC session ${id} not found`, Status.NotFound);
+        }
+        return session;
+    }
+}
+
+export namespace WebRtcTransportRequestorServer {
+    export class State extends WebRtcTransportRequestorBehavior.State {
+        override currentSessions: WebRtcSession[] = new Array<WebRtcSession>();
+    }
+    export class Events extends WebRtcTransportRequestorBehavior.Events {
+        offer = Observable<[session: WebRtcSession, args: WebRtcTransportRequestor.OfferRequest]>();
+        answer = Observable<[session: WebRtcSession, sdp: string]>();
+        iceCandidates = Observable<[session: WebRtcSession, candidates: WebRtcTransportDefinitions.IceCandidate[]]>();
+        end = Observable<[session: WebRtcSession, reason: WebRtcTransportDefinitions.WebRtcEndReason]>();
+    }
+}

package/src/index.ts

@@ -9,6 +9,7 @@
  */
 
 // Export controller components
+export * from "./controller/behaviors/WebRtcTransportRequestorServer.js";
 export * from "./controller/ControllerCommandHandler.js";
 export * from "./controller/LegacyDataInjector.js";
 export * from "./controller/MatterController.js";
@@ -32,4 +33,4 @@ export { formatNodeId } from "./util/formatNodeId.js";
 export * from "./util/matterVersion.js";
 
 // Re-Export classes from matter.js
-export { Crypto, Environment, LogDestination, LogFormat, LogLevel, Logger } from "@matter/main";
+export { Crypto, Environment, LogDestination, LogFormat, LogLevel, Logger, StorageService } from "@matter/main";

package/src/server/WebSocketControllerHandler.ts

@@ -84,6 +84,7 @@ export class WebSocketControllerHandler implements WebServerHandler {
     #wss?: WebSocketServer;
     #closed = false;
     #shuttingDown = false;
+    #serverObservers = new ObserverGroup();
     /** Circular buffer for recent node events (max 25) */
     #eventHistory: MatterNodeEvent[] = [];
     /** Track when each node was last interviewed (connected) - keyed by nodeId */
@@ -142,6 +143,13 @@ export class WebSocketControllerHandler implements WebServerHandler {
     async register(server: HttpServer) {
         logger.info(`Starting server: matter-server/${this.#serverVersion} (matter.js/${MATTER_VERSION})`);
         const wss = (this.#wss = new WebSocketServer({ server: server, path: "/ws" }));
+
+        // WebRTC callbacks fan out to every connected client, so subscribe once at the server
+        // level rather than per-connection.
+        this.#serverObservers.on(this.#commandHandler.events.webRtcCallback, data => {
+            this.#broadcastEvent("webrtc_callback", data);
+        });
+
         wss.on("connection", ws => {
             if (this.#closed || this.#shuttingDown) {
                 try {
@@ -372,6 +380,7 @@ export class WebSocketControllerHandler implements WebServerHandler {
         }
 
         this.#closed = true;
+        this.#serverObservers.close();
         // Send server_shutdown event to all connected clients before closing
         const shutdownMessage = toBigIntAwareJson({ event: "server_shutdown", data: {} });
         this.#wss.clients.forEach(client => {
@@ -445,6 +454,9 @@ export class WebSocketControllerHandler implements WebServerHandler {
                 case "device_command":
                     result = await this.#handleDeviceCommand(args);
                     break;
+                case "send_webrtc_provider_command":
+                    result = await this.#handleSendWebRtcProviderCommand(args);
+                    break;
                 case "write_attribute":
                     result = await this.#handleWriteAttribute(args);
                     break;
@@ -866,6 +878,18 @@ export class WebSocketControllerHandler implements WebServerHandler {
         return cmdResult;
     }
 
+    async #handleSendWebRtcProviderCommand(
+        args: ArgsOf<"send_webrtc_provider_command">,
+    ): Promise<ResponseOf<"send_webrtc_provider_command">> {
+        const { node_id, endpoint_id, command_name, payload } = args;
+        return this.#commandHandler.sendWebRtcProviderCommand({
+            nodeId: NodeId(node_id),
+            endpointId: EndpointNumber(endpoint_id),
+            commandName: command_name,
+            payload,
+        });
+    }
+
     async #handleInterviewNode(args: ArgsOf<"interview_node">): Promise<ResponseOf<"interview_node">> {
         const { node_id } = args;
         const nodeId = NodeId(node_id);