@matter-server/ws-controller 0.6.2 → 0.6.3

package/src/controller/ControllerCommandHandler.ts

@@ -110,10 +110,7 @@ const RECONNECT_TIMEOUT = Minutes(3);
  * BasicInformation (0x28) covers firmware version, product name, etc.
  * BridgedDeviceBasicInformation (0x39) covers the same for bridged child nodes.
  */
-const FULL_UPDATE_CLUSTER_IDS = new Set<ClusterId>([
-    BasicInformation.Cluster.id,
-    BridgedDeviceBasicInformation.Cluster.id,
-]);
+const FULL_UPDATE_CLUSTER_IDS = new Set<ClusterId>([BasicInformation.id, BridgedDeviceBasicInformation.id]);
 
 /**
  * Determine the Matter specification version from cached attributes.
@@ -151,8 +148,8 @@ export class ControllerCommandHandler {
     #controller: CommissioningController;
     #started = false;
     #connected = false;
-    #bleEnabled = false;
-    #otaEnabled = false;
+    readonly #bleEnabled: boolean;
+    readonly #otaEnabled: boolean;
     /** Node management and attribute cache */
     #nodes = new Nodes();
     /** Cache of available updates keyed by nodeId */
@@ -188,12 +185,27 @@ export class ControllerCommandHandler {
         // Initialize custom cluster poller for Eve energy attributes etc.
         // Reads automatically trigger change events through the normal attribute flow
         this.#customClusterPoller = new CustomClusterPoller({
-            nodeConnected: nodeId => !!(this.#nodes.has(nodeId) && this.#nodes.get(nodeId).isConnected),
-            handleReadAttributes: (nodeId, paths, fabricFiltered) =>
-                this.handleReadAttributes(nodeId, paths, fabricFiltered),
+            nodeConnected: peer => !!(this.#nodes.has(peer.nodeId) && this.#nodes.get(peer.nodeId).isConnected),
+            handleReadAttributes: (peer, paths, fabricFiltered) =>
+                this.handleReadAttributes(peer.nodeId, paths, fabricFiltered),
         });
     }
 
+    /**
+     * Build the canonical PeerAddress for the given node on this controller's fabric.
+     *
+     * Throws if the controller's fabric is not yet resolved. Callers must run after
+     * controller start; a silent fallback would intern PeerAddressMap entries under the
+     * wrong fabric index and leak poller registrations.
+     */
+    #peerOf(nodeId: NodeId): PeerAddress {
+        const fabric = this.#controller.fabric;
+        if (fabric === undefined) {
+            throw new Error(`Cannot resolve PeerAddress for node ${nodeId}: controller fabric is not initialized`);
+        }
+        return PeerAddress({ fabricIndex: fabric.fabricIndex, nodeId });
+    }
+
     /**
      * Format a NodeId as a PeerAddress string for logging.
      * Uses the controller's fabric index when available, otherwise "?" is used.
@@ -254,14 +266,14 @@ export class ControllerCommandHandler {
             // Handle updateAvailable events - cache the update info
             softwareUpdateManagerEvents.updateAvailable.on(
                 (peerAddress: PeerAddress, updateDetails: SoftwareUpdateInfo) => {
-                    logger.info(`Update available for node ${peerAddress.nodeId}:`, updateDetails);
+                    logger.info(`Update available for node ${this.formatNode(peerAddress.nodeId)}:`, updateDetails);
                     this.#availableUpdates.set(peerAddress.nodeId, updateDetails);
                 },
             );
 
             // Handle updateDone events - clear the cached update info
             softwareUpdateManagerEvents.updateDone.on((peerAddress: PeerAddress) => {
-                logger.info(`Update done for node ${peerAddress.nodeId}`);
+                logger.info(`Update done for node ${this.formatNode(peerAddress.nodeId)}`);
                 this.#availableUpdates.delete(peerAddress.nodeId);
             });
 
@@ -315,7 +327,7 @@ export class ControllerCommandHandler {
                 attributeCache.update(node);
                 const attributes = attributeCache.get(nodeId);
                 if (attributes) {
-                    this.#customClusterPoller.registerNode(nodeId, attributes);
+                    this.#customClusterPoller.registerNode(this.#peerOf(nodeId), attributes);
                 }
             }
 
@@ -381,7 +393,7 @@ export class ControllerCommandHandler {
             // Register for custom cluster polling (e.g., Eve energy)
             const attributes = attributeCache.get(nodeId);
             if (attributes) {
-                this.#customClusterPoller.registerNode(nodeId, attributes);
+                this.#customClusterPoller.registerNode(this.#peerOf(nodeId), attributes);
             }
         }
 
@@ -615,10 +627,6 @@ export class ControllerCommandHandler {
         await this.#controller.updateFabricLabel(label);
     }
 
-    disconnectNode(nodeId: NodeId) {
-        return this.#controller.disconnectNode(nodeId, true);
-    }
-
     async handleWriteAttribute(data: WriteAttributeRequest): Promise<AttributeResponseStatus> {
         const { nodeId, endpointId, clusterId, attributeId } = data;
         let { value } = data;
@@ -792,7 +800,7 @@ export class ControllerCommandHandler {
         }
 
         const { onNetworkOnly, wifiCredentials: wifiNetwork, threadCredentials: threadNetwork } = data;
-        const options = {
+        return {
             commissioning: {
                 nodeId: data.nodeId,
                 regulatoryLocation: GeneralCommissioning.RegulatoryLocationType.IndoorOutdoor,
@@ -817,7 +825,6 @@ export class ControllerCommandHandler {
             },
             passcode,
         };
-        return options;
     }
 
     async commissionNode(data: CommissioningRequest): Promise<CommissioningResponse> {
@@ -1040,7 +1047,7 @@ export class ControllerCommandHandler {
         this.#reconnectTimers.get(nodeId)?.stop();
         this.#reconnectTimers.delete(nodeId);
         this.#nodes.delete(nodeId);
-        this.#customClusterPoller.unregisterNode(nodeId);
+        this.#customClusterPoller.unregisterNode(this.#peerOf(nodeId));
         this.#availableUpdates.delete(nodeId);
     }
 
@@ -1061,7 +1068,7 @@ export class ControllerCommandHandler {
                 },
                 Read.Attribute({
                     endpoint: EndpointNumber(0),
-                    cluster: OperationalCredentials.Complete,
+                    cluster: OperationalCredentials,
                     attributes: "fabrics",
                 }),
             ),
@@ -1110,16 +1117,10 @@ export class ControllerCommandHandler {
 
         logger.info("Setting ACL entries", aclEntries);
 
-        const { status } = await this.#writeAttribute(
-            nodeId,
-            EndpointNumber(0),
-            AccessControl.Cluster.id,
-            "acl",
-            aclEntries,
-        );
+        const { status } = await this.#writeAttribute(nodeId, EndpointNumber(0), AccessControl.id, "acl", aclEntries);
         return [
             {
-                path: { endpoint_id: 0, cluster_id: AccessControl.Cluster.id, attribute_id: 0 },
+                path: { endpoint_id: 0, cluster_id: AccessControl.id, attribute_id: 0 },
                 status,
             },
         ];
@@ -1144,16 +1145,10 @@ export class ControllerCommandHandler {
 
         logger.info("Setting bindings on endpoint", endpointId, bindingEntries);
 
-        const { status } = await this.#writeAttribute(
-            nodeId,
-            endpointId,
-            Binding.Cluster.id,
-            "binding",
-            bindingEntries,
-        );
+        const { status } = await this.#writeAttribute(nodeId, endpointId, Binding.id, "binding", bindingEntries);
         return [
             {
-                path: { endpoint_id: endpointId, cluster_id: Binding.Cluster.id, attribute_id: 0 },
+                path: { endpoint_id: endpointId, cluster_id: Binding.id, attribute_id: 0 },
                 status,
             },
         ];

package/src/controller/CustomClusterPoller.ts

@@ -10,8 +10,10 @@
  * a custom cluster without standard Matter subscription support.
  */
 
-import { CancelablePromise, Duration, Logger, Millis, NodeId, Time, Timer } from "@matter/main";
+import { CancelablePromise, Duration, Logger, Millis, Time, Timer } from "@matter/main";
+import { PeerAddress, PeerAddressMap } from "@matter/main/protocol";
 import { AttributesData } from "../types/CommandHandler.js";
+import { formatNodeId } from "../util/formatNodeId.js";
 
 const logger = Logger.get("CustomClusterPoller");
 
@@ -42,8 +44,12 @@ const MAX_INITIAL_DELAY_MS = 30_000;
 type AttributePath = string;
 
 export interface NodeAttributeReader {
-    handleReadAttributes(nodeId: NodeId, attributePaths: string[], fabricFiltered?: boolean): Promise<AttributesData>;
-    nodeConnected(nodeId: NodeId): boolean;
+    handleReadAttributes(
+        peer: PeerAddress,
+        attributePaths: string[],
+        fabricFiltered?: boolean,
+    ): Promise<AttributesData>;
+    nodeConnected(peer: PeerAddress): boolean;
 }
 
 /**
@@ -112,7 +118,7 @@ export function checkPolledAttributes(attributes: AttributesData): Set<Attribute
  * Manages polling of custom cluster attributes for multiple nodes.
  */
 export class CustomClusterPoller {
-    #polledAttributes = new Map<NodeId, Set<AttributePath>>();
+    #polledAttributes = new PeerAddressMap<Set<AttributePath>>();
     #pollerTimer: Timer;
     #attributeReader: NodeAttributeReader;
     #isPolling = false;
@@ -130,18 +136,18 @@ export class CustomClusterPoller {
      * Register a node for polling if it has custom attributes that need polling.
      * Call this after a node is connected and its attributes are available.
      */
-    registerNode(nodeId: NodeId, attributes: AttributesData): void {
+    registerNode(peer: PeerAddress, attributes: AttributesData): void {
         const attributesToPoll = checkPolledAttributes(attributes);
 
         if (attributesToPoll.size === 0) {
             // Remove from polling if it was previously registered
-            this.unregisterNode(nodeId);
+            this.unregisterNode(peer);
             return;
         }
 
-        this.#polledAttributes.set(nodeId, attributesToPoll);
+        this.#polledAttributes.set(peer, attributesToPoll);
         logger.info(
-            `Registered node ${nodeId} for custom attribute polling: ${Array.from(attributesToPoll).join(", ")}`,
+            `Registered node ${formatNodeId(peer)} for custom attribute polling: ${Array.from(attributesToPoll).join(", ")}`,
         );
 
         // Start the poller if not already running
@@ -151,9 +157,9 @@ export class CustomClusterPoller {
     /**
      * Unregister a node from polling (e.g., when decommissioned or disconnected).
      */
-    unregisterNode(nodeId: NodeId): void {
-        if (this.#polledAttributes.delete(nodeId)) {
-            logger.info(`Unregistered node ${nodeId} from custom attribute polling`);
+    unregisterNode(peer: PeerAddress): void {
+        if (this.#polledAttributes.delete(peer)) {
+            logger.info(`Unregistered node ${formatNodeId(peer)} from custom attribute polling`);
         }
         if (this.#polledAttributes.size === 0) {
             this.#pollerTimer.stop();
@@ -217,13 +223,13 @@ export class CustomClusterPoller {
                 if (this.#closed) {
                     break;
                 }
-                const [nodeId, attributePaths] = entries[i];
-                if (!this.#polledAttributes.has(nodeId)) {
+                const [peer, attributePaths] = entries[i];
+                if (!this.#polledAttributes.has(peer)) {
                     // Node was removed, so skip it
                     continue;
                 }
                 polledNodes++;
-                await this.#pollNode(nodeId, attributePaths);
+                await this.#pollNode(peer, attributePaths);
                 // Small delay between nodes to avoid overwhelming the network
                 // Only add this delay if there are more nodes remaining to be polled
                 if (i < entries.length - 1) {
@@ -249,25 +255,25 @@ export class CustomClusterPoller {
      * Poll a single node for its custom attributes.
      * The read will automatically trigger change events through the normal attribute flow.
      */
-    async #pollNode(nodeId: NodeId, attributePaths: Set<AttributePath>): Promise<void> {
-        if (!this.#attributeReader.nodeConnected(nodeId)) {
-            logger.debug(`Node ${nodeId} not connected, skipping custom attribute polling`);
+    async #pollNode(peer: PeerAddress, attributePaths: Set<AttributePath>): Promise<void> {
+        if (!this.#attributeReader.nodeConnected(peer)) {
+            logger.debug(`Node ${formatNodeId(peer)} not connected, skipping custom attribute polling`);
             return;
         }
         const paths = Array.from(attributePaths);
-        logger.debug(`Polling ${paths.length} custom attributes for node ${nodeId}`);
+        logger.debug(`Polling ${paths.length} custom attributes for node ${formatNodeId(peer)}`);
 
         try {
             // Read with fabricFiltered=true as per Eve's requirements
             // This automatically updates the attribute cache and triggers change events
-            const readPromise = this.#attributeReader.handleReadAttributes(nodeId, paths, true);
+            const readPromise = this.#attributeReader.handleReadAttributes(peer, paths, true);
             this.#currentReadPromise = readPromise.then(
                 () => {},
                 () => {},
             );
             await readPromise;
         } catch (error) {
-            logger.warn(`Failed to poll custom attributes for node ${nodeId}: `, error);
+            logger.warn(`Failed to poll custom attributes for node ${formatNodeId(peer)}: `, error);
         } finally {
             this.#currentReadPromise = undefined;
         }

package/src/controller/MatterController.ts

@@ -23,6 +23,7 @@ import { VendorId } from "@matter/main/types";
 import { CommissioningController } from "@project-chip/matter.js";
 import { Readable } from "node:stream";
 import { ConfigStorage } from "../server/ConfigStorage.js";
+import { BorderRouterDiscovery } from "./BorderRouterDiscovery.js";
 import { ControllerCommandHandler } from "./ControllerCommandHandler.js";
 import { LegacyDataInjector, LegacyServerData } from "./LegacyDataInjector.js";
 import { resolveServerId } from "./ServerIdResolver.js";
@@ -75,6 +76,7 @@ export class MatterController {
     #legacyCommissionedDates?: Map<string, Timestamp>;
     #enableTestNetDcl = false;
     #disableOtaProvider = true;
+    readonly #borderRouterDiscovery: BorderRouterDiscovery;
 
     static async create(
         environment: Environment,
@@ -144,6 +146,7 @@ export class MatterController {
 
     constructor(environment: Environment, config: ConfigStorage, options: MatterControllerOptions, serverId: string) {
         this.#env = environment;
+        this.#borderRouterDiscovery = new BorderRouterDiscovery(this.#env);
         this.#config = config;
         this.#serverId = serverId;
         this.#serverVersion = options.serverVersion ?? "0.0.0";
@@ -210,6 +213,8 @@ export class MatterController {
                     initPromises.push(this.#enableTestOtaImages());
                 }
 
+                initPromises.push(this.#borderRouterDiscovery.start());
+
                 try {
                     await MatterAggregateError.allSettled(initPromises);
                 } catch (error) {
@@ -221,6 +226,10 @@ export class MatterController {
         return this.#commandHandler;
     }
 
+    get borderRouters(): BorderRouterDiscovery {
+        return this.#borderRouterDiscovery;
+    }
+
     /**
      * Get the DCL vendor info service instance.
      * Lazily initializes the service if not already present.
@@ -294,6 +303,7 @@ export class MatterController {
     }
 
     async stop() {
+        await this.#borderRouterDiscovery.stop();
         await this.#commandHandler?.close(); // This closes also the controller instance if started
     }
 

package/src/server/WebSocketControllerHandler.ts

@@ -470,6 +470,9 @@ export class WebSocketControllerHandler implements WebServerHandler {
                 case "set_thread_dataset":
                     result = await this.#handleSetThreadDataset(args);
                     break;
+                case "get_thread_border_routers":
+                    result = this.#controller.borderRouters.list();
+                    break;
                 case "open_commissioning_window":
                     result = await this.#handleOpenCommissioningWindow(args);
                     break;

package/src/util/formatNodeId.ts

@@ -5,16 +5,18 @@
  */
 
 import { FabricIndex, NodeId } from "@matter/main";
+import { PeerAddress } from "@matter/main/protocol";
 
 /**
- * Format a NodeId as a PeerAddress string for logging.
+ * Format a NodeId or PeerAddress as a string for logging.
  * Uses the Matter address format: @fabricIndexDecimal:nodeIdHex (e.g., "@1:a", "@10:1f").
  *
- * @param nodeId The node ID to format (rendered in hexadecimal)
- * @param fabricIndex The fabric index (rendered in decimal). If omitted or unknown, "?" is used.
  * @returns Formatted PeerAddress string like "@1:a", "@10:1f", or "@?:1f" when fabric index is unknown.
  */
-export function formatNodeId(nodeId: NodeId, fabricIndex?: FabricIndex): string {
-    const fabricIndexPart = fabricIndex === undefined ? "?" : fabricIndex.toString(10);
+export function formatNodeId(peer: PeerAddress): string;
+export function formatNodeId(nodeId: NodeId, fabricIndex?: FabricIndex): string;
+export function formatNodeId(arg: NodeId | PeerAddress, fabricIndex?: FabricIndex): string {
+    const [nodeId, resolvedFabricIndex] = typeof arg === "object" ? [arg.nodeId, arg.fabricIndex] : [arg, fabricIndex];
+    const fabricIndexPart = resolvedFabricIndex === undefined ? "?" : resolvedFabricIndex.toString(10);
     return `@${fabricIndexPart}:${nodeId.toString(16)}`;
 }