@matter/node 0.15.1 → 0.15.2-alpha.0-20250703-2e16aba2b

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(
@@ -180,22 +215,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 +249,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);
     }
 }

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.
@@ -23,7 +24,7 @@ export class InstanceDiscovery extends Discovery<ClientNode> {
 
     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);
     }
 }

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

@@ -4,16 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { RootEndpoint } from "#endpoints/root";
-import { ImplementationError } from "#general";
 import { DatatypeModel, FieldElement } from "#model";
 import { Node } from "#node/Node.js";
-import { Interactable, Subscribe } from "#protocol";
+import { DEFAULT_MIN_INTERVAL_FLOOR_SECONDS, Subscribe } from "#protocol";
 import { ClientNetworkRuntime } from "./ClientNetworkRuntime.js";
 import { NetworkBehavior } from "./NetworkBehavior.js";
 
-const DEFAULT_MIN_INTERVAL_FLOOR_SECONDS = 1;
-
 export class NetworkClient extends NetworkBehavior {
     declare internal: NetworkClient.Internal;
     declare state: NetworkClient.State;
@@ -22,34 +18,31 @@ export class NetworkClient extends NetworkBehavior {
         this.reactTo(this.#node.lifecycle.online, this.startup);
     }
 
-    interact<T>(interactor: (client: Interactable) => Promise<T>) {
-        const { runtime } = this.internal;
-        if (!runtime) {
-            throw new ImplementationError("Cannot advertise offline server");
-        }
-        return runtime.interact(interactor);
-    }
-
     protected async startup() {
         const { startupSubscription } = this.state;
+
         if (startupSubscription === null) {
             return;
         }
 
         // TODO - configure subscription based on physical device properties
-        const message = Subscribe({
-            isFabricFiltered: true,
+        const subscribe = Subscribe({
+            fabricFilter: true,
             minIntervalFloorSeconds: DEFAULT_MIN_INTERVAL_FLOOR_SECONDS,
             maxIntervalCeilingSeconds: 0,
+            attributes: [{}],
             ...startupSubscription,
         });
 
-        // TODO - subscription management & population of state
-        this.#node.interaction.subscribe(message);
+        // First, read.  This allows us to retrieve attributes that do not support subscription
+        for await (const _chunk of this.#node.interaction.read(subscribe));
+
+        // Now subscribe for subsequent updates
+        await this.#node.interaction.subscribe(subscribe);
     }
 
     get #node() {
-        return this.endpoint.ownerOfType(RootEndpoint) as unknown as Node;
+        return this.env.get(Node);
     }
 
     /**
@@ -79,13 +72,10 @@ export namespace NetworkClient {
         /**
          * A subscription installed when the node is first commissioned and when the service is restarted.
          *
-         * The default subscription is a wildcard for all attributes and events of the node.  You can set to undefined
-         * or filter the fields and values but this will prevent the relevant state values from loading.
-         *
-         * If this subscription does not include appropriate BasicInformation and Descriptor attributes then the
-         * endpoint structure may not initialize fully.
+         * The default subscription is a wildcard for all attributes and of the node.  You can set to undefined or
+         * filter the fields and values but only values selected by this subscription will update automatically.
          *
-         * Set to null to disable.
+         * Set to null to disable automatic subscription.
          */
         startupSubscription?: Subscribe | null;
     }

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

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { ImplementationError, Logger } from "#general";
+import { Logger } from "#general";
 import { ServerSubscriptionConfig } from "#node/server/ServerSubscription.js";
 import { Ble } from "#protocol";
 import { DiscoveryCapabilitiesBitmap, TypeFromPartialBitSchema } from "#types";
@@ -17,7 +17,7 @@ const logger = Logger.get("NetworkingServer");
 /**
  * Server implementation of {@link NetworkBehavior}.
  *
- * This behavior mostly deals with configuration and events.  {@link NetworkServer} provides the actual network
+ * This behavior mostly deals with configuration and events.  {@link ServerNetworkRuntime} provides the actual network
  * implementation.
  */
 export class NetworkServer extends NetworkBehavior {
@@ -54,35 +54,6 @@ export class NetworkServer extends NetworkBehavior {
         return super.initialize();
     }
 
-    /**
-     * Advertise and continue advertising at regular intervals until timeout per Matter specification.  If already
-     * advertising, the advertisement timeout resets.
-     *
-     * If the node is uncommissioned and commissioning is enabled, announces as commissionable on all available
-     * transports. Commissioned devices only advertise for operational discovery via DNS-SD.
-     *
-     * Advertisement begins at startup.
-     */
-    openAdvertisementWindow() {
-        if (!this.internal.runtime) {
-            throw new ImplementationError("Cannot advertise offline server");
-        }
-
-        this.internal.runtime
-            .openAdvertisementWindow()
-            .catch(error => logger.error("Failed to open advertisement window", error));
-    }
-
-    /**
-     * Immediately broadcast presence to the network regardless of whether the advertisement window is open.
-     */
-    advertiseNow() {
-        if (!this.internal.runtime) {
-            throw new ImplementationError("Cannot advertise offline server");
-        }
-        this.env.runtime.add(this.internal.runtime.advertiseNow());
-    }
-
     #endUncommissionedMode() {
         if (this.internal.runtime) {
             this.internal.runtime.endUncommissionedMode();

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

@@ -25,7 +25,6 @@ import { InteractionServer } from "#node/server/InteractionServer.js";
 import {
     Ble,
     ChannelManager,
-    CommissioningConfigProvider,
     DeviceAdvertiser,
     DeviceCommissioner,
     ExchangeManager,
@@ -38,7 +37,6 @@ import {
     SecureChannelProtocol,
     SessionManager,
 } from "#protocol";
-import { CommissioningOptions } from "#types";
 import { CommissioningServer } from "../commissioning/CommissioningServer.js";
 import { ProductDescriptionServer } from "../product-description/ProductDescriptionServer.js";
 import { SessionsBehavior } from "../sessions/SessionsBehavior.js";
@@ -110,18 +108,6 @@ export class ServerNetworkRuntime extends NetworkRuntime {
         return interfaceDetails;
     }
 
-    async openAdvertisementWindow() {
-        if (!this.#formerSubscriptionsHandled) {
-            await this.#reestablishFormerSubscriptions();
-        }
-
-        await this.owner.env.get(DeviceAdvertiser).startAdvertising();
-    }
-
-    advertiseNow() {
-        return this.owner.env.get(DeviceAdvertiser).advertise(true);
-    }
-
     /**
      * A BLE broadcaster.
      */
@@ -260,10 +246,6 @@ export class ServerNetworkRuntime extends NetworkRuntime {
         return this.owner.state.operationalCredentials.commissionedFabrics;
     }
 
-    endCommissioning() {
-        return this.owner.env.get(DeviceCommissioner).endCommissioning();
-    }
-
     protected override async start() {
         const { owner } = this;
         const { env } = owner;
@@ -295,6 +277,9 @@ export class ServerNetworkRuntime extends NetworkRuntime {
         env.set(InteractionServer, interactionServer);
         env.get(ExchangeManager).addProtocolHandler(interactionServer);
 
+        // Ensure SecureChannelProtocol is installed
+        env.get(SecureChannelProtocol);
+
         await this.owner.act("load-sessions", agent => agent.load(SessionsBehavior));
 
         // Monitor CommissioningServer to end "uncommissioned" mode when we are commissioned
@@ -302,38 +287,6 @@ export class ServerNetworkRuntime extends NetworkRuntime {
 
         // Monitor DeviceAdvertiser to enable MDNS broadcasting when the first Fabric is added
         this.#observers.on(advertiser.operationalModeEnabled, this.enableMdnsBroadcasting);
-
-        // When first going online, enable commissioning by controllers unless we ourselves are configured as a
-        // controller
-        if (owner.state.commissioning.enabled === undefined) {
-            await owner.set({
-                commissioning: { enabled: true },
-            });
-        }
-
-        // Ensure the environment will convey the commissioning configuration to the DeviceCommissioner
-        if (!env.has(CommissioningConfigProvider)) {
-            // Configure the DeviceCommissioner
-            env.set(
-                CommissioningConfigProvider,
-                new (class extends CommissioningConfigProvider {
-                    get values() {
-                        const config = {
-                            ...owner.state.commissioning,
-                            productDescription: owner.state.productDescription,
-                            ble: !!owner.state.network.ble,
-                        };
-
-                        return config as CommissioningOptions.Configuration;
-                    }
-                })(),
-            );
-        }
-
-        // Ensure there is a device commissioner if (but only if) commissioning is enabled
-        await this.configureCommissioning();
-
-        this.#observers.on(this.owner.eventsOf(CommissioningServer).enabled$Changed, this.configureCommissioning);
     }
 
     override async [Construction.construct]() {
@@ -344,7 +297,12 @@ export class ServerNetworkRuntime extends NetworkRuntime {
         this.owner.env.set(PeerAddressStore, new NodePeerAddressStore(this.owner));
         await this.owner.env.load(PeerSet);
 
-        await this.openAdvertisementWindow();
+        // Restore previous subscriptions
+        //
+        // TODO - move to SubscriptionsBehavior, and rename to SubscriptionsServer?
+        if (!this.#formerSubscriptionsHandled) {
+            await this.#reestablishFormerSubscriptions();
+        }
     }
 
     protected override async stop() {
@@ -380,16 +338,6 @@ export class ServerNetworkRuntime extends NetworkRuntime {
         this.owner.env.maybeGet(InteractionServer)?.blockNewActivity();
     }
 
-    protected async configureCommissioning() {
-        if (this.owner.state.commissioning.enabled) {
-            // Ensure a DeviceCommissioner is active
-            this.owner.env.get(DeviceCommissioner);
-        } else if (this.owner.env.has(DeviceCommissioner)) {
-            // Ensure no DeviceCommissioner is active
-            await this.owner.env.close(DeviceCommissioner);
-        }
-    }
-
     async #reestablishFormerSubscriptions() {
         const { env } = this.owner;
         if (!env.has(InteractionServer)) {

package/src/behavior/system/subscription/SubscriptionBehavior.ts

@@ -29,9 +29,9 @@ const REESTABLISH_SUBSCRIPTIONS_TIMEOUT_S = 2;
 /**
  * Subscriptions Persistence handling.
  *
- * This behavior collects and stores active subscriptions to allow re-activating them on restart in order to try to speed
- * up the controller reconnection process. This can mean  a bit more memory usage on start of the device. To disable this
- * feature set `persistenceEnabled` as state of the `subscription` behavior to `false`.
+ * This behavior collects and stores active subscriptions to allow re-activating them on restart in order to try to
+ * speed up the controller reconnection process. This can mean a bit more memory usage on start of the device. To
+ * disable this feature set `persistenceEnabled` as state of the `subscription` behavior to `false`.
  */
 export class SubscriptionBehavior extends Behavior {
     static override readonly id = "subscription";