@matter/node 0.16.0-alpha.0-20251003-dc6d5523d → 0.16.0-alpha.0-20251006-3fe1e7c57

package/src/behavior/supervision/RootSupervisor.ts

@@ -8,11 +8,11 @@ import { camelize, InternalError } from "#general";
 import {
     AttributeModel,
     ClusterModel,
-    ElementTag,
     FeatureMap,
     FeatureSet,
     Matter,
     Model,
+    ModelIndex,
     Schema,
     Scope,
     ValueModel,
@@ -59,7 +59,7 @@ export class RootSupervisor implements ValueSupervisor {
     #rootSchema: Schema;
     #root: ValueSupervisor;
     #memberNames?: Set<string>;
-    #attributeNamesToIds?: Map<string, AttributeId>; // Whenever we need more than Attributes and Fields, we need to generalize
+    #propertyNamesAndIds?: Map<string, AttributeId | undefined>;
 
     /**
      * Create a new supervisor.
@@ -86,12 +86,20 @@ export class RootSupervisor implements ValueSupervisor {
     /**
      * Obtain the supervisor for schema.  The result is cached.
      */
-    static for(schema: Schema) {
+    static for<T extends Schema | undefined>(
+        schema: T,
+    ): T extends undefined ? RootSupervisor | undefined : RootSupervisor {
+        if (!schema) {
+            return undefined as any;
+        }
+
         if (cache.has(schema)) {
             return cache.get(schema)!;
         }
+
         const supervisor = new RootSupervisor(schema);
         cache.set(schema, supervisor);
+
         return supervisor;
     }
 
@@ -168,17 +176,14 @@ export class RootSupervisor implements ValueSupervisor {
         return persistent;
     }
 
-    get attributeNamesToIds() {
-        let names = this.#attributeNamesToIds;
+    get propertyNamesAndIds() {
+        let names = this.#propertyNamesAndIds;
         if (!names) {
             names = new Map();
             for (const member of this.#members) {
-                if (member.id === undefined || member.tag !== ElementTag.Attribute) {
-                    continue;
-                }
-                names.set(camelize(member.name), AttributeId(member.id));
+                names.set(camelize(member.name), member.id as AttributeId | undefined);
             }
-            this.#attributeNamesToIds = names;
+            this.#propertyNamesAndIds = names;
         }
         return names;
     }
@@ -188,7 +193,7 @@ export class RootSupervisor implements ValueSupervisor {
      *
      * The {@link Scope.ConformanceMode} defaults to "deconflicted" if you do not override.
      */
-    membersOf<T extends Schema>(schema: T, options: Scope.MemberOptions = {}): Model.ChildOf<T>[] {
+    membersOf<T extends Schema>(schema: T, options: Scope.MemberOptions = {}): ModelIndex<Model.ChildOf<T>> {
         if (options.conformance === undefined) {
             options = { ...options, conformance: "deconflicted" };
         }

package/src/behavior/supervision/ValueSupervisor.ts

@@ -54,7 +54,7 @@ export interface ValueSupervisor {
     readonly manage: ValueSupervisor.Manage;
 
     /**
-     * Apply changes.  Does not validate perform validation.
+     * Apply changes.  Does not perform validation.
      */
     readonly patch: ValueSupervisor.Patch;
 

package/src/behavior/system/commissioning/CommissioningClient.ts

@@ -8,8 +8,10 @@ import { Behavior } from "#behavior/Behavior.js";
 import { Events as BaseEvents } from "#behavior/Events.js";
 import { OperationalCredentialsClient } from "#behaviors/operational-credentials";
 import {
+    Diagnostic,
     Duration,
     ImplementationError,
+    Logger,
     NotImplementedError,
     Observable,
     ServerAddress,
@@ -45,6 +47,8 @@ import { ControllerBehavior } from "../controller/ControllerBehavior.js";
 import { NetworkClient } from "../network/NetworkClient.js";
 import { RemoteDescriptor } from "./RemoteDescriptor.js";
 
+const logger = Logger.get("CommissioningClient");
+
 /**
  * Client functionality related to commissioning.
  *
@@ -155,6 +159,13 @@ export class CommissioningClient extends Behavior {
         network.state.startupSubscription = opts.startupSubscription;
         network.state.caseAuthenticatedTags = opts.caseAuthenticatedTags;
 
+        logger.notice(
+            "Commissioned",
+            Diagnostic.strong(this.endpoint.id),
+            "as",
+            Diagnostic.strong(this.endpoint.identity),
+        );
+
         node.lifecycle.commissioned.emit(this.context);
 
         await node.start();
@@ -177,11 +188,22 @@ export class CommissioningClient extends Behavior {
             throw new ImplementationError("Cannot decommission node that is not commissioned");
         }
 
+        const formerAddress = PeerAddress(peerAddress).toString();
+
         const opcreds = this.agent.get(OperationalCredentialsClient);
 
         await opcreds.removeFabric({ fabricIndex: opcreds.state.currentFabricIndex });
 
         this.state.peerAddress = undefined;
+
+        await this.context.transaction.commit();
+
+        logger.info(
+            "Decommissioned",
+            Diagnostic.strong(this.endpoint.id),
+            "formerly",
+            Diagnostic.strong(formerAddress),
+        );
     }
 
     /**

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

@@ -23,6 +23,7 @@ import {
     Scanner,
     ScannerSet,
 } from "#protocol";
+import { FabricId } from "@matter/types";
 import type { CommissioningClient } from "../commissioning/CommissioningClient.js";
 import { CommissioningServer } from "../commissioning/CommissioningServer.js";
 import { NetworkServer } from "../network/NetworkServer.js";
@@ -48,6 +49,7 @@ export class ControllerBehavior extends Behavior {
             throw new ImplementationError("adminFabricLabel must be set for ControllerBehavior.");
         }
         const adminFabricLabel = this.state.adminFabricLabel;
+        const adminFabricId = this.state.adminFabricId;
 
         // Configure discovery transports
         if (this.state.ip === undefined) {
@@ -77,6 +79,10 @@ export class ControllerBehavior extends Behavior {
                     override get adminFabricLabel() {
                         return adminFabricLabel;
                     }
+
+                    get fabricId() {
+                        return adminFabricId;
+                    }
                 })(),
             );
         }
@@ -185,5 +191,12 @@ export namespace ControllerBehavior {
          * Contains the label of the admin fabric which is set for all commissioned devices
          */
         adminFabricLabel = "matter.js";
+
+        /**
+         * Contains the FabricId of the admin fabric when a defined number needs to be used because special Certificates
+         * are used.
+         * If not provided, a random FabricId will be generated.
+         */
+        adminFabricId?: FabricId = undefined;
     }
 }

package/src/behavior/system/subscriptions/SubscriptionsServer.ts

@@ -281,7 +281,7 @@ export class SubscriptionsBehavior extends Behavior {
         interactionServer.subscriptionEstablishmentStarted.off(blockHandler);
 
         logger.info(
-            `Re-established ${successfullReEstablishments.length} ${successfullReEstablishments.length ? `(${successfullReEstablishments.join(",")})` : ""} of ${formerSubscriptions.length} former subscriptions successfully`,
+            `Re-established ${successfullReEstablishments.length}${successfullReEstablishments.length ? ` (${successfullReEstablishments.join(",")})` : ""} of ${formerSubscriptions.length} former subscriptions successfully`,
         );
     }
 }

package/src/endpoint/Endpoint.ts

@@ -24,6 +24,7 @@ import { DataModelPath } from "#model";
 import type { Node } from "#node/Node.js";
 import { IdentityService } from "#node/server/IdentityService.js";
 import { ProtocolService } from "#node/server/ProtocolService.js";
+import { Val } from "#protocol";
 import { EndpointNumber } from "#types";
 import { RootEndpoint } from "../endpoints/root.js";
 import { Agent } from "./Agent.js";
@@ -170,14 +171,28 @@ export class Endpoint<T extends EndpointType = EndpointType.Empty> {
         return this.#stateView;
     }
 
+    /**
+     * Current state for a specific behavior ID.
+     */
+    stateOf(type: string): Immutable<Val.Struct>;
+
     /**
      * Current state for a specific behavior.
      */
-    stateOf<T extends Behavior.Type>(type: T) {
-        if (!this.behaviors.has(type)) {
-            throw new ImplementationError(`Behavior ${type.id} is not supported by ${this}`);
+    stateOf<T extends Behavior.Type>(type: T): Immutable<Behavior.StateOf<T>>;
+
+    stateOf(type: Behavior.Type | string) {
+        if (typeof type === "string") {
+            if (!(type in this.#stateView)) {
+                throw new ImplementationError(`Behavior ${type} is not supported by ${this}`);
+            }
+        } else {
+            if (!this.behaviors.has(type)) {
+                throw new ImplementationError(`Behavior ${type.id} is not supported by ${this}`);
+            }
+            type = type.id;
         }
-        return (this.#stateView as Record<string, unknown>)[type.id] as Immutable<Behavior.StateOf<T>>;
+        return (this.#stateView as Record<string, unknown>)[type];
     }
 
     /**
@@ -719,20 +734,28 @@ export class Endpoint<T extends EndpointType = EndpointType.Empty> {
      * Path identifying the endpoint in the Matter data model.
      */
     get path(): DataModelPath {
-        let ident;
+        if (this.#owner) {
+            return this.#owner.path.at(this.identity, this.#type.name);
+        }
+
+        return DataModelPath(this.identity, this.type?.name);
+    }
+
+    /**
+     * Diagnostic identity.
+     *
+     * This is an unqualified path segment.
+     */
+    get identity() {
         if (this.lifecycle?.hasId) {
-            ident = this.id;
-        } else if (this.lifecycle?.hasNumber) {
-            ident = this.number;
-        } else {
-            ident = "?";
+            return this.id;
         }
 
-        if (this.#owner) {
-            return this.#owner.path.at(ident, this.#type.name);
+        if (this.lifecycle?.hasNumber) {
+            return this.number;
         }
 
-        return DataModelPath(ident, this.type?.name);
+        return "?";
     }
 
     /**

package/src/endpoint/properties/Behaviors.ts

@@ -19,6 +19,7 @@ import {
     describeList,
     Diagnostic,
     EventEmitter,
+    Immutable,
     ImplementationError,
     Lifecycle,
     Logger,
@@ -557,6 +558,14 @@ export class Behaviors {
         return elements;
     }
 
+    /**
+     * Access the state view of a behavior if loaded.
+     */
+    maybeStateOf(behaviorId: string): Immutable<Val.Struct> | undefined {
+        const backing = this.#backings[behaviorId];
+        return backing?.maybeDatasource?.view;
+    }
+
     [Symbol.iterator]() {
         return Object.values(this.#supported)[Symbol.iterator]();
     }

package/src/node/ClientNode.ts

@@ -11,8 +11,8 @@ import { NetworkClient } from "#behavior/system/network/NetworkClient.js";
 import { NetworkRuntime } from "#behavior/system/network/NetworkRuntime.js";
 import { Agent } from "#endpoint/Agent.js";
 import { EndpointInitializer } from "#endpoint/properties/EndpointInitializer.js";
-import { Identity, Lifecycle, MaybePromise } from "#general";
-import { Interactable, OccurrenceManager } from "#protocol";
+import { Diagnostic, Identity, Lifecycle, Logger, MaybePromise } from "#general";
+import { Interactable, OccurrenceManager, PeerAddress } from "#protocol";
 import { ClientNodeStore } from "#storage/client/ClientNodeStore.js";
 import { RemoteWriter } from "#storage/client/RemoteWriter.js";
 import { ServerNodeStore } from "#storage/server/ServerNodeStore.js";
@@ -22,6 +22,8 @@ import { ClientNodeInteraction } from "./client/ClientNodeInteraction.js";
 import { Node } from "./Node.js";
 import type { ServerNode } from "./ServerNode.js";
 
+const logger = Logger.get("ClientNode");
+
 /**
  * A remote Matter {@link Node}.
  *
@@ -188,6 +190,30 @@ export class ClientNode extends Node<ClientNode.RootEndpoint> {
 
         return this.#interaction;
     }
+
+    override get identity() {
+        // If commissioned, use the peer address for logging purposes
+        let address = this.behaviors.maybeStateOf("commissioning")?.peerAddress as PeerAddress | undefined;
+
+        // During early initialization commissioning state may not be loaded, so check directly in storage too
+        if (!address) {
+            address = this.env.get(ClientNodeStore).storeForEndpoint(this).peerAddress as PeerAddress | undefined;
+        }
+
+        // Use the peer address as a log identifier if present
+        if (address) {
+            return PeerAddress(address).toString();
+        }
+
+        // Fall back to persistence ID
+        return super.identity;
+    }
+
+    protected override statusUpdate(message: string): void {
+        // Log client node status updates as info rather than notice and change the log facility to make clear it's a
+        // client
+        logger.info(Diagnostic.strong(this.toString()), message);
+    }
 }
 
 export namespace ClientNode {

package/src/node/client/ClientStructure.ts

@@ -236,6 +236,7 @@ export class ClientStructure {
         const attrs = cluster.store.initialValues ?? {};
 
         // Generate a behavior if enough information is available
+        // TODO: Detect changes in revision/features/attributes/commands and update behavior if needed
         if (cluster.behavior === undefined) {
             const {
                 [ClusterRevision.id]: clusterRevision,
@@ -291,6 +292,9 @@ export class ClientStructure {
 
         const serverList = attrs[SERVER_LIST_ATTR_ID];
         if (Array.isArray(serverList)) {
+            // TODO: Remove clusters that are no longer present
+            //  Including events vis parts/endpoints on node (per endpoint and generic "changed")?
+            //  Including data cleanup
             for (const cluster of serverList) {
                 if (typeof cluster === "number") {
                     this.#clusterFor(endpoint, cluster as ClusterId);
@@ -307,6 +311,9 @@ export class ClientStructure {
 
                 const part = this.#endpointFor(partNo as EndpointNumber);
 
+                // TODO - remove endpoints/parts that are no longer present
+                //  Including events vis parts/endpoints on node (per endpoint and generic "changed")?
+                //  Including data cleanup
                 let isAlreadyDescendant = false;
                 for (let owner = part.endpoint.owner; owner; owner = owner.owner) {
                     if (owner === endpoint.endpoint) {

package/src/node/server/ProtocolService.ts

@@ -303,7 +303,7 @@ class ClusterState implements DisposableClusterProtocol {
         this.#datasource = backing.datasource;
         this.#endpointId = backing.endpoint.number;
 
-        const attributeNameToIdMap = backing.type.supervisor.attributeNamesToIds;
+        const attributeNameToIdMap = backing.type.supervisor.propertyNamesAndIds;
         // For quieter attributes, we need to use the online events to get real state changes
         for (const attr of type.attributes) {
             attributeNameToIdMap.set(attr.name, attr.id);

package/src/storage/client/ClientEndpointStore.ts

@@ -26,6 +26,13 @@ export class ClientEndpointStore extends EndpointStore {
         return this.#number;
     }
 
+    /**
+     * Shortcut to persisted peer address so we can use in logging prior to full initialization.
+     */
+    get peerAddress() {
+        return this.initialValues.get("commissioning")?.["peerAddress"];
+    }
+
     participantFor(transaction: Transaction) {
         let participant = transaction.getParticipant(this.#owner);
         if (participant === undefined) {