@matter/node 0.15.1 → 0.15.2-alpha.0-20250704-2715344f0

package/src/behavior/system/controller/ControllerBehavior.ts

@@ -6,24 +6,22 @@
 
 import { Behavior } from "#behavior/Behavior.js";
 import { BasicInformationBehavior } from "#behaviors/basic-information";
-import {
-    ImplementationError,
-    isNetworkInterface,
-    Logger,
-    MatterAggregateError,
-    NetInterfaceSet,
-    TransportInterfaceSet,
-} from "#general";
+import { ImplementationError, isNetworkInterface, NetInterfaceSet, TransportInterfaceSet } from "#general";
 import { Node } from "#node/Node.js";
 import { InteractionServer } from "#node/server/InteractionServer.js";
 import {
     Ble,
+    ClientSubscriptionHandler,
+    ClientSubscriptions,
+    Fabric,
     FabricAuthority,
     FabricAuthorityConfigurationProvider,
     FabricManager,
+    MdnsScanner,
+    MdnsScannerTargetCriteria,
     MdnsService,
+    Scanner,
     ScannerSet,
-    SubscriptionClient,
 } from "#protocol";
 import type { CommissioningClient } from "../commissioning/CommissioningClient.js";
 import { CommissioningServer } from "../commissioning/CommissioningServer.js";
@@ -31,8 +29,6 @@ import { NetworkServer } from "../network/NetworkServer.js";
 import { ActiveDiscoveries } from "./discovery/ActiveDiscoveries.js";
 import type { Discovery } from "./discovery/Discovery.js";
 
-const logger = Logger.get("ControllerBehavior");
-
 /**
  * Node controller functionality.
  *
@@ -44,10 +40,11 @@ const logger = Logger.get("ControllerBehavior");
 export class ControllerBehavior extends Behavior {
     static override readonly id = "controller";
 
+    declare internal: ControllerBehavior.Internal;
     declare state: ControllerBehavior.State;
 
     override async initialize() {
-        if (this.state.adminFabricLabel === undefined) {
+        if (this.state.adminFabricLabel === undefined || this.state.adminFabricLabel === "") {
             throw new ImplementationError("adminFabricLabel must be set for ControllerBehavior.");
         }
         const adminFabricLabel = this.state.adminFabricLabel;
@@ -84,12 +81,15 @@ export class ControllerBehavior extends Behavior {
             );
         }
 
+        // Ensure the fabric authority is fully initialized
+        await this.env.load(FabricAuthority);
+
         // "Automatic" controller mode - disable commissioning if node is not otherwise configured as a commissionable
         // device
         const commissioning = this.agent.get(CommissioningServer);
         if (commissioning.state.enabled === undefined) {
-            const controlledFabrics = this.env.get(FabricAuthority).fabrics.length;
             const totalFabrics = this.env.get(FabricManager).length;
+            const controlledFabrics = this.env.get(FabricAuthority).fabrics.length;
             if (controlledFabrics === totalFabrics) {
                 commissioning.state.enabled = false;
             }
@@ -103,17 +103,7 @@ export class ControllerBehavior extends Behavior {
     }
 
     override async [Symbol.asyncDispose]() {
-        const discoveries = this.env.get(ActiveDiscoveries);
-        while (discoveries.size) {
-            for (const discovery of discoveries) {
-                discovery.cancel();
-            }
-
-            await MatterAggregateError.allSettled([...discoveries], "Error while cancelling discoveries").catch(error =>
-                logger.error(error),
-            );
-        }
-
+        await this.env.close(ActiveDiscoveries);
         this.env.delete(FabricAuthority);
         this.env.delete(ScannerSet);
     }
@@ -131,15 +121,33 @@ export class ControllerBehavior extends Behavior {
             netInterfaces.add(Ble.get().getBleCentralInterface());
         }
 
-        // This is necessary to receive data reports for subscriptions
-        this.env.get(InteractionServer).clientHandler = this.env.get(SubscriptionClient);
+        // Install handler to receive data reports for subscriptions
+        const subscriptions = this.env.get(ClientSubscriptions);
+        const interactionServer = this.env.get(InteractionServer);
+        interactionServer.clientHandler = new ClientSubscriptionHandler(subscriptions);
 
         // Clean up as the node goes offline
         const node = Node.forEndpoint(this.endpoint);
         this.reactTo(node.lifecycle.goingOffline, this.#nodeGoingOffline);
+
+        // Add each pre-existing fabric to discovery criteria
+        const authority = this.env.get(FabricAuthority);
+        for (const fabric of authority.fabrics) {
+            this.#enableScanningForFabric(fabric);
+        }
+        this.reactTo(authority.fabricAdded, this.#enableScanningForFabric);
+
+        // Configure each MDNS scanner with criteria
+        const scanners = this.env.get(ScannerSet);
+        for (const scanner of scanners) {
+            this.#enableScanningForScanner(scanner);
+        }
+        this.reactTo(scanners.added, this.#enableScanningForScanner);
     }
 
     async #nodeGoingOffline() {
+        await this.env.close(ClientSubscriptions);
+
         const netInterfaces = this.env.get(NetInterfaceSet);
         const netTransports = this.env.get(TransportInterfaceSet);
 
@@ -152,9 +160,30 @@ export class ControllerBehavior extends Behavior {
 
         await this.env.close(NetInterfaceSet);
     }
+
+    #enableScanningForFabric(fabric: Fabric) {
+        this.internal.mdnsTargetCriteria.operationalTargets.push({ operationalId: fabric.operationalId });
+    }
+
+    #enableScanningForScanner(scanner: Scanner) {
+        if (!(scanner instanceof MdnsScanner)) {
+            return;
+        }
+        scanner.targetCriteriaProviders.add(this.internal.mdnsTargetCriteria);
+    }
 }
 
 export namespace ControllerBehavior {
+    export class Internal {
+        /**
+         * MDNS scanner criteria for each controlled fabric (keyed by operational ID).
+         */
+        mdnsTargetCriteria: MdnsScannerTargetCriteria = {
+            commissionable: true,
+            operationalTargets: [],
+        };
+    }
+
     export class State {
         /**
          * Set to false to disable scanning on BLE.
@@ -173,6 +202,6 @@ export namespace ControllerBehavior {
         /**
          * Contains the label of the admin fabric which is set for all commissioned devices
          */
-        adminFabricLabel!: string;
+        adminFabricLabel = "matter.js";
     }
 }

package/src/behavior/system/controller/discovery/ActiveDiscoveries.ts

@@ -5,15 +5,64 @@
  */
 
 import { Environment, Environmental } from "#general";
+import { MdnsScanner, MdnsScannerTargetCriteria, Scanner, ScannerSet } from "#protocol";
 import type { Discovery } from "./Discovery.js";
 
 /**
  * Ongoing node discoveries registered with the environment.
  */
 export class ActiveDiscoveries extends Set<Discovery<any>> {
+    #env: Environment;
+    #mdnsTargetCriteria?: MdnsScannerTargetCriteria;
+
+    constructor(env: Environment) {
+        super();
+
+        this.#env = env;
+
+        this.#activateCommissionableScanning();
+        env.get(ScannerSet).added.on(this.#activateCommissionableScanningFor.bind(this));
+    }
+
     static [Environmental.create](env: Environment) {
-        const instance = new ActiveDiscoveries();
+        const instance = new ActiveDiscoveries(env);
         env.set(ActiveDiscoveries, instance);
         return instance;
     }
+
+    async close() {
+        this.#env.delete(ActiveDiscoveries, this);
+
+        this.#deactivateCommissionableScanning();
+    }
+
+    #activateCommissionableScanning() {
+        const scanners = this.#env.get(ScannerSet);
+        for (const scanner of scanners) {
+            this.#activateCommissionableScanningFor(scanner);
+        }
+    }
+
+    #activateCommissionableScanningFor(scanner: Scanner) {
+        if (!(scanner instanceof MdnsScanner)) {
+            return;
+        }
+
+        if (this.#mdnsTargetCriteria === undefined) {
+            this.#mdnsTargetCriteria = { commissionable: true, operationalTargets: [] };
+        }
+        scanner.targetCriteriaProviders.add(this.#mdnsTargetCriteria);
+    }
+
+    #deactivateCommissionableScanning() {
+        if (!this.#mdnsTargetCriteria) {
+            return;
+        }
+        const scanners = this.#env.get(ScannerSet);
+        for (const scanner of scanners) {
+            if (scanner instanceof MdnsScanner) {
+                scanner.targetCriteriaProviders.delete(this.#mdnsTargetCriteria);
+            }
+        }
+    }
 }

package/src/behavior/system/controller/discovery/CommissioningDiscovery.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type { CommissioningClient } from "#behavior/system/commissioning/CommissioningClient.js";
+import { CommissioningClient } from "#behavior/system/commissioning/CommissioningClient.js";
 import type { ServerNode } from "#node/ServerNode.js";
 import type { Discovery } from "./Discovery.js";
 import { InstanceDiscovery } from "./InstanceDiscovery.js";
@@ -16,7 +16,15 @@ export class CommissioningDiscovery extends InstanceDiscovery {
     #options: CommissioningDiscovery.Options;
 
     constructor(owner: ServerNode, options: CommissioningDiscovery.Options) {
+        const opts = CommissioningClient.PasscodeOptions(options);
+
+        const { discriminator } = opts;
+        if (discriminator !== undefined) {
+            options = { ...options, longDiscriminator: discriminator };
+        }
+
         super(owner, options);
+
         this.#options = options;
     }
 
@@ -31,5 +39,5 @@ export class CommissioningDiscovery extends InstanceDiscovery {
 }
 
 export namespace CommissioningDiscovery {
-    export type Options = Discovery.Options & CommissioningClient.CommissioningOptions;
+    export type Options = Discovery.InstanceOptions & CommissioningClient.CommissioningOptions;
 }

package/src/behavior/system/controller/discovery/Discovery.ts

@@ -4,24 +4,16 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { CancelablePromise, MatterAggregateError, MatterError, MaybePromise } from "#general";
+import { CancelablePromise, Diagnostic, Logger, MaybePromise, withTimeout } from "#general";
 import { ClientNodeFactory } from "#node/client/ClientNodeFactory.js";
 import type { ClientNode } from "#node/ClientNode.js";
 import type { ServerNode } from "#node/ServerNode.js";
 import { CommissionableDeviceIdentifiers, ScannerSet } from "#protocol";
 import { ControllerBehavior } from "../ControllerBehavior.js";
 import { ActiveDiscoveries } from "./ActiveDiscoveries.js";
+import { DiscoveryAggregateError } from "./DiscoveryError.js";
 
-export class DiscoveryError extends MatterError {
-    static override [Symbol.hasInstance](instance: unknown) {
-        if (instance instanceof DiscoveryAggregateError) {
-            return true;
-        }
-        return super[Symbol.hasInstance](instance);
-    }
-}
-
-export class DiscoveryAggregateError extends MatterAggregateError {}
+const logger = Logger.get("Logger");
 
 /**
  * Discovery of commissionable devices.
@@ -29,12 +21,15 @@ export class DiscoveryAggregateError extends MatterAggregateError {}
  * This is a cancelable promise; use cancel() to terminate discovery.
  */
 export abstract class Discovery<T = unknown> extends CancelablePromise<T> {
-    #isCanceled = false;
-    #cancel?: () => void;
+    #abortReason?: Error;
+    #isStopped = false;
+    #stopDiscovery?: () => void;
     #owner: ServerNode;
     #options: Discovery.Options;
-    #resolve!: (value: T) => void;
-    #reject!: (cause?: any) => void;
+    #resolve: (value: T) => void;
+    #reject: (cause?: any) => void;
+    #settled?: Promise<void>;
+    #resolveSettled?: () => void;
 
     constructor(owner: ServerNode, options: Discovery.Options | undefined) {
         let resolve: (value: T) => void, reject: (cause?: any) => void;
@@ -42,8 +37,19 @@ export abstract class Discovery<T = unknown> extends CancelablePromise<T> {
             resolve = resolver;
             reject = rejecter;
         });
-        this.#resolve = resolve!;
-        this.#reject = reject!;
+
+        this.#resolve = result => {
+            this.#isStopped = true;
+            this.#owner.env.get(ActiveDiscoveries).delete(this);
+            resolve!(result);
+            this.#resolveSettled?.();
+        };
+        this.#reject = cause => {
+            this.#isStopped = true;
+            this.#owner.env.get(ActiveDiscoveries).delete(this);
+            reject!(cause);
+            this.#resolveSettled?.();
+        };
 
         owner.env.get(ActiveDiscoveries).add(this);
 
@@ -53,6 +59,13 @@ export abstract class Discovery<T = unknown> extends CancelablePromise<T> {
         queueMicrotask(this.#initializeController.bind(this));
     }
 
+    get settled() {
+        if (this.#settled === undefined) {
+            this.#settled = new Promise(resolve => (this.#resolveSettled = resolve));
+        }
+        return this.#settled;
+    }
+
     protected abstract onDiscovered(node: ClientNode): void;
     protected abstract onComplete(): MaybePromise<T>;
 
@@ -61,45 +74,60 @@ export abstract class Discovery<T = unknown> extends CancelablePromise<T> {
      *
      * This will not abort node initialization but it will terminate any active discoveries.  The discovery result will
      * be the same as if the discovery had timed out.
+     *
+     * To abort the operation due to error use {@link cancel}.
      */
-    override cancel() {
-        if (this.#isCanceled) {
+    stop() {
+        if (this.#isStopped) {
             return;
         }
 
-        this.#isCanceled = true;
-        this.#cancel?.();
+        this.#isStopped = true;
+        this.#stopDiscovery?.();
     }
 
     override toString() {
+        const description = this.#description;
+        if (description === undefined) {
+            return "node discovery";
+        }
+        return `discovery of ${description}`;
+    }
+
+    get #description() {
         if ("instanceId" in this.#options) {
-            return `Discovery of node instance ${this.#options.instanceId}`;
+            return `node instance ${this.#options.instanceId}`;
         }
 
         if ("longDiscriminator" in this.#options) {
-            return `Discovery of node with discriminator ${this.#options.longDiscriminator}`;
+            return `node with discriminator ${this.#options.longDiscriminator}`;
         }
 
         if ("shortDiscriminator" in this.#options) {
-            return `Discovery of node with discriminator ${this.#options.shortDiscriminator}`;
+            return `node with discriminator ${this.#options.shortDiscriminator}`;
         }
 
         if ("productId" in this.#options && this.#options.productId !== undefined) {
             if ("vendorId" in this.#options) {
-                return `Discovery of product ${this.#options.productId} from vendor ${this.#options.vendorId}`;
+                return `product ${this.#options.productId} from vendor ${this.#options.vendorId}`;
             }
-            return `Discovery of product ${this.#options.productId}`;
+            return `product ${this.#options.productId}`;
         }
 
         if ("vendorId" in this.#options) {
-            return `Discovery of node from vendor ${this.#options.vendorId}`;
+            return `node from vendor ${this.#options.vendorId}`;
         }
 
         if ("deviceType" in this.#options) {
-            return `Discovery of node with device type ${this.#options.deviceType}`;
+            return `node with device type ${this.#options.deviceType}`;
         }
 
-        return "Node discovery";
+        return "node discovery";
+    }
+
+    protected override onCancel(reason: Error) {
+        this.#abortReason = reason;
+        this.stop();
     }
 
     /**
@@ -127,8 +155,8 @@ export abstract class Discovery<T = unknown> extends CancelablePromise<T> {
      * Step 2 - ensure node is online
      */
     #startNode() {
-        if (this.#isCanceled) {
-            this.#invokeCompleter();
+        if (this.#isStopped) {
+            this.#afterDiscovery();
             return;
         }
 
@@ -144,16 +172,23 @@ export abstract class Discovery<T = unknown> extends CancelablePromise<T> {
      * Step 3 - perform actual discovery
      */
     #performDiscovery() {
-        if (this.#isCanceled) {
-            this.#invokeCompleter();
+        if (this.#isStopped) {
+            this.#afterDiscovery();
             return;
         }
 
+        const description = this.#description;
+        if (description === undefined) {
+            logger.info("Initiating", Diagnostic.strong("node discovery"));
+        } else {
+            logger.info("Initiating discovery of", Diagnostic.strong(description));
+        }
+
         const scanners = this.#owner.env.get(ScannerSet);
 
         const factory = this.#owner.env.get(ClientNodeFactory);
         const promises = new Array<PromiseLike<unknown>>();
-        const cancelSignal = new Promise<void>(resolve => (this.#cancel = resolve));
+        const cancelSignal = new Promise<void>(resolve => (this.#stopDiscovery = resolve));
         for (const scanner of scanners) {
             promises.push(
                 scanner.findCommissionableDevicesContinuously(
@@ -173,6 +208,7 @@ export abstract class Discovery<T = unknown> extends CancelablePromise<T> {
                         } else {
                             // This node is new to us
                             node = factory.create({
+                                id: (this.#options as Discovery.InstanceOptions).id,
                                 environment: this.#owner.env,
                                 commissioning: { descriptor },
                             });
@@ -180,22 +216,32 @@ export abstract class Discovery<T = unknown> extends CancelablePromise<T> {
 
                         this.onDiscovered(node);
                     },
-                    this.#options.timeoutSeconds,
+                    undefined,
                     cancelSignal,
                 ),
             );
         }
 
-        DiscoveryAggregateError.allSettled(promises, `${this} failed`)
-            .then(() => this.#invokeCompleter())
-            .catch(this.#reject);
+        let promise = DiscoveryAggregateError.allSettled(promises, `${this} failed`);
+
+        if (this.#options.timeoutSeconds !== undefined) {
+            promise = withTimeout(this.#options.timeoutSeconds * 1_000, promise, this.stop.bind(this));
+        }
+
+        promise.then(this.#afterDiscovery.bind(this)).catch(this.#reject);
     }
 
     /**
      * Step 4 - invoke completion callback
      */
-    #invokeCompleter() {
+    #afterDiscovery() {
         let result: MaybePromise<T>;
+
+        if (this.#abortReason) {
+            this.#reject(this.#abortReason);
+            return;
+        }
+
         try {
             result = this.onComplete();
         } catch (e) {
@@ -204,18 +250,10 @@ export abstract class Discovery<T = unknown> extends CancelablePromise<T> {
         }
 
         if (MaybePromise.is(result)) {
-            result.then(this.#finish.bind(this), this.#reject);
+            result.then(this.#resolve.bind(this), this.#reject);
             return;
         }
 
-        this.#finish(result);
-    }
-
-    /**
-     * Step 5 - deregister from environment and resolve
-     */
-    #finish(result: T) {
-        this.#owner.env.get(ActiveDiscoveries).delete(this);
         this.#resolve(result);
     }
 }
@@ -224,4 +262,14 @@ export namespace Discovery {
     export type Options = CommissionableDeviceIdentifiers & {
         timeoutSeconds?: number;
     };
+
+    export type InstanceOptions = Options & {
+        /**
+         * The local ID to assign the node if newly discovered.  This is the stable identifier used for the node's "id"
+         * property.
+         *
+         * By default matter.js assigns an ID of the form "nodeN".
+         */
+        id?: string;
+    };
 }

package/src/behavior/system/controller/discovery/DiscoveryError.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MatterAggregateError, MatterError } from "#general";
+
+export class DiscoveryError extends MatterError {
+    static override [Symbol.hasInstance](instance: unknown) {
+        if (instance instanceof DiscoveryAggregateError) {
+            return true;
+        }
+        return super[Symbol.hasInstance](instance);
+    }
+}
+
+export class DiscoveryAggregateError extends MatterAggregateError {}

package/src/behavior/system/controller/discovery/InstanceDiscovery.ts

@@ -7,7 +7,8 @@
 import type { MaybePromise } from "#general";
 import type { ClientNode } from "#node/ClientNode.js";
 import type { ServerNode } from "#node/ServerNode.js";
-import { Discovery, DiscoveryError } from "./Discovery.js";
+import { Discovery } from "./Discovery.js";
+import { DiscoveryError } from "./DiscoveryError.js";
 
 /**
  * Locates a single node and returns it.
@@ -17,13 +18,13 @@ import { Discovery, DiscoveryError } from "./Discovery.js";
 export class InstanceDiscovery extends Discovery<ClientNode> {
     #result?: ClientNode;
 
-    constructor(owner: ServerNode, options?: Discovery.Options) {
+    constructor(owner: ServerNode, options?: Discovery.InstanceOptions) {
         super(owner, options);
     }
 
     protected onDiscovered(node: ClientNode) {
         this.#result = node;
-        this.cancel();
+        this.stop();
     }
 
     protected onComplete(): MaybePromise<ClientNode> {

package/src/behavior/system/controller/discovery/index.ts

@@ -8,4 +8,5 @@ export * from "./ActiveDiscoveries.js";
 export * from "./CommissioningDiscovery.js";
 export * from "./ContinuousDiscovery.js";
 export * from "./Discovery.js";
+export * from "./DiscoveryError.js";
 export * from "./InstanceDiscovery.js";

package/src/behavior/system/network/ClientNetworkRuntime.ts

@@ -4,9 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { BasicSet, createPromise, Logger, MatterError, UninitializedDependencyError } from "#general";
+import { InternalError, Logger, MatterError } from "#general";
 import type { ClientNode } from "#node/ClientNode.js";
-import { ClientInteraction, ExchangeProvider, Interactable, PeerSet } from "#protocol";
+import { ClientInteraction, ExchangeProvider, PeerSet } from "#protocol";
 import { CommissioningClient } from "../commissioning/CommissioningClient.js";
 import { RemoteDescriptor } from "../commissioning/RemoteDescriptor.js";
 import { NetworkRuntime } from "./NetworkRuntime.js";
@@ -20,38 +20,25 @@ const logger = Logger.get("ClientNetworkRuntime");
  * Handles network functionality for {@link ClientNode}.
  */
 export class ClientNetworkRuntime extends NetworkRuntime {
-    #interactions = new BasicSet<Promise<unknown>>();
-    #client?: Interactable;
+    #client?: ClientInteraction;
 
     constructor(owner: ClientNode) {
         super(owner);
     }
 
-    interact<T>(interactor: (client: Interactable) => Promise<T>) {
-        if (this.#client === undefined) {
-            throw new UninitializedDependencyError(`Node ${this.owner}`, `Interaction client unavailable`);
-        }
-
-        const { promise, resolver, rejecter } = createPromise<T>();
-
-        this.#interactions.add(promise);
-
-        interactor(this.#client)
-            .then(resolver, rejecter)
-            .finally(() => this.#interactions.delete(promise));
-
-        return promise;
-    }
-
     protected async start() {
         if (!this.owner.lifecycle.isCommissioned) {
-            throw new UncommissionedError(`Node unavailable: ${this.owner} is uncommissioned`);
+            throw new UncommissionedError(`Cannot interact with ${this.owner} because it is uncommissioned`);
         }
 
         const commissioningState = this.owner.stateOf(CommissioningClient);
-        const address = this.owner.stateOf(CommissioningClient).peerAddress!;
+        const address = this.owner.stateOf(CommissioningClient).peerAddress;
         const peers = this.owner.env.get(PeerSet);
 
+        if (address === undefined) {
+            throw new InternalError(`Commissioned node ${this.owner} has no peer address`);
+        }
+
         const exchangeProvider = await peers.exchangeProviderFor(address, {
             discoveryData: RemoteDescriptor.fromLongForm(commissioningState),
         });
@@ -63,34 +50,14 @@ export class ClientNetworkRuntime extends NetworkRuntime {
     protected async stop() {
         await this.construction;
 
-        this.blockNewActivity();
-
-        // TODO - cancel client initialization if/when possible
-
         try {
-            // TODO - currently no need to close client.  Shut down exchange?
-            //this.#client?.close();
+            await this.#client?.close();
         } catch (e) {
             logger.error(`Error closing connection to ${this.owner}`, e);
         }
-
-        if (this.#interactions.size) {
-            // TODO - cancel interactions if/when possible
-
-            await new Promise<void>(resolve => {
-                const deletionListener = () => {
-                    if (!this.#interactions.size) {
-                        this.#interactions.deleted.off(deletionListener);
-                        resolve();
-                    }
-                };
-
-                this.#interactions.deleted.on(deletionListener);
-            });
-        }
     }
 
     blockNewActivity() {
-        this.#client = undefined;
+        this.owner.env.delete(ClientInteraction, this.#client);
     }
 }