@matter/node 0.16.0-alpha.0-20251210-206ca2db7 → 0.16.0-alpha.0-20251212-4dde71be3

package/src/endpoint/properties/Behaviors.ts

@@ -761,9 +761,9 @@ export class Behaviors {
         const { id, Events } = type;
 
         const get = () => this.#backingFor(type).stateView;
-        Object.defineProperty(this.#endpoint.state, id, { get, enumerable: true });
+        Object.defineProperty(this.#endpoint.state, id, { get, enumerable: true, configurable: true });
         if (type.schema.id !== undefined) {
-            Object.defineProperty(this.#endpoint.state, type.schema.id, { get });
+            Object.defineProperty(this.#endpoint.state, type.schema.id, { get, configurable: true });
         }
 
         Object.defineProperty(this.#endpoint.events, id, {
@@ -780,6 +780,7 @@ export class Behaviors {
             },
 
             enumerable: true,
+            configurable: true,
         });
     }
 }

package/src/node/client/ClientEventEmitter.ts

@@ -5,6 +5,7 @@
  */
 
 import type { ElementEvent, Events } from "#behavior/Events.js";
+import { NetworkClient } from "#behavior/system/network/NetworkClient.js";
 import { camelize, Diagnostic, isObject, Logger } from "#general";
 import { ClusterModel, EventModel, MatterModel } from "#model";
 import type { ClientNode } from "#node/ClientNode.js";
@@ -18,10 +19,9 @@ const logger = Logger.get("ClientEventEmitter");
  * Event handler for Matter events transmitted by a peer.
  *
  * TODO - set priority on context when split for server vs. client
- * TODO - record latest event number for each subscription shape (or just wildcard?)
  */
 export interface ClientEventEmitter {
-    (event: ReadResult.EventValue): void;
+    (event: ReadResult.EventValue): Promise<void>;
 }
 
 /**
@@ -40,7 +40,7 @@ const warnedForUnknown = new Set<ClusterId | `${ClusterId}-${EventId}`>();
 export function ClientEventEmitter(node: ClientNode, structure: ClientStructure) {
     return emitClientEvent;
 
-    function emitClientEvent(occurrence: ReadResult.EventValue) {
+    async function emitClientEvent(occurrence: ReadResult.EventValue) {
         const names = getNames(node.matter, occurrence);
         if (!names) {
             return;
@@ -48,10 +48,18 @@ export function ClientEventEmitter(node: ClientNode, structure: ClientStructure)
 
         const event = getEvent(node, occurrence, names.cluster, names.event);
         if (event) {
-            node.act(agent => {
+            await node.act(async agent => {
                 // Current ActionContext is not writable, could skip act() but meh, see TODO above
                 //agent.context.priority = occurrence.priority;
                 event.emit(occurrence.value, agent.context);
+
+                const network = agent.get(NetworkClient);
+                if (occurrence.number > network.state.maxEventNumber) {
+                    await agent.context.transaction.addResources(network);
+                    await agent.context.transaction.begin();
+                    network.state.maxEventNumber = occurrence.number;
+                    await agent.context.transaction.commit();
+                }
             });
         }
     }

package/src/node/client/ClientGroupInteraction.ts

@@ -8,11 +8,11 @@ import type { ActionContext } from "#behavior/index.js";
 import { ImplementationError } from "#general";
 import {
     ClientInvoke,
+    ClientSubscription,
     DecodedInvokeResult,
     Read,
     ReadResult,
     Subscribe,
-    SubscribeResult,
     Write,
     WriteResult,
 } from "#protocol";
@@ -27,7 +27,7 @@ export class ClientGroupInteraction extends ClientNodeInteraction {
     }
 
     /** Groups do not support reading or subscribing to attributes */
-    override async subscribe(_request: Subscribe, _context?: ActionContext): SubscribeResult {
+    override async subscribe(_request: Subscribe, _context?: ActionContext): Promise<ClientSubscription> {
         throw new InvalidGroupOperationError("Groups do not support subscribing to attributes");
     }
 
@@ -65,6 +65,8 @@ export class ClientGroupInteraction extends ClientNodeInteraction {
             throw new InvalidGroupOperationError("Timed requests are not supported for group address invokes.");
         }
 
+        request.suppressResponse = true; // Invoking on a group does not yield a response by definition
+
         return super.invoke(request, context);
     }
 }

package/src/node/client/ClientNodeInteraction.ts

@@ -74,7 +74,7 @@ export class ClientNodeInteraction implements Interactable<ActionContext> {
                 request,
             }),
 
-            sustain: request.sustain === undefined ? true : request.sustain,
+            sustain: request.sustain !== false,
 
             updated: async data => {
                 const result = this.structure.mutate(request, data);

package/src/node/client/ClientStructure.ts

@@ -11,7 +11,7 @@ import { Descriptor } from "#clusters/descriptor";
 import { Endpoint } from "#endpoint/Endpoint.js";
 import { EndpointType } from "#endpoint/type/EndpointType.js";
 import { RootEndpoint } from "#endpoints/root";
-import { Diagnostic, InternalError, isDeepEqual, Logger } from "#general";
+import { Diagnostic, InternalError, isDeepEqual, Logger, Observable } from "#general";
 import {
     AcceptedCommandList,
     AttributeList,
@@ -19,14 +19,15 @@ import {
     DeviceClassification,
     DeviceTypeModel,
     FeatureMap,
+    GeneratedCommandList,
     Matter,
     type FeatureBitmap,
 } from "#model";
 import type { ClientNode } from "#node/ClientNode.js";
 import type { Node } from "#node/Node.js";
 import { ReadScope, type Read, type ReadResult } from "#protocol";
+import { ClientNodeStore } from "#storage/client/ClientNodeStore.js";
 import { DatasourceCache } from "#storage/client/DatasourceCache.js";
-import { ClientNodeStore } from "#storage/index.js";
 import type { AttributeId, ClusterId, ClusterType, CommandId, EndpointNumber } from "#types";
 import { Status } from "#types";
 import { ClientEventEmitter } from "./ClientEventEmitter.js";
@@ -52,6 +53,7 @@ export class ClientStructure {
     #pendingStructureEvents = Array<PendingEvent>();
     #delayedClusterEvents = new Array<ReadResult.EventValue>();
     #events: ClientStructureEvents;
+    #changed = Observable<[void]>();
 
     constructor(node: ClientNode) {
         this.#node = node;
@@ -64,6 +66,10 @@ export class ClientStructure {
         this.#events = this.#node.env.get(ClientStructureEvents);
     }
 
+    get changed() {
+        return this.#changed;
+    }
+
     /**
      * Load initial structure from cache.
      */
@@ -175,14 +181,16 @@ export class ClientStructure {
         // Apply changes
         const scope = ReadScope(request);
         for await (const chunk of changes) {
+            const chunkData = new Array<ReadResult.Report>();
             for (const change of chunk) {
+                chunkData.push(change);
                 switch (change.kind) {
                     case "attr-value":
                         currentUpdates = await this.#mutateAttribute(change, scope, currentUpdates);
                         break;
 
                     case "event-value":
-                        this.#emitEvent(change, currentUpdates);
+                        await this.#emitEvent(change, currentUpdates);
                         break;
 
                     case "attr-status":
@@ -197,7 +205,7 @@ export class ClientStructure {
                 }
             }
 
-            yield chunk;
+            yield chunkData;
         }
 
         // The last cluster still needs its changes applied
@@ -226,6 +234,7 @@ export class ClientStructure {
 
         // Likewise, we don't emit events until we've applied all structural changes
         this.#emitPendingStructureEvents();
+        await this.#emitPendingEvents();
     }
 
     /** Reference to the default subscription used when the node was started. */
@@ -280,7 +289,7 @@ export class ClientStructure {
         return currentUpdates;
     }
 
-    #emitEvent(occurrence: ReadResult.EventValue, currentUpdates?: AttributeUpdates) {
+    async #emitEvent(occurrence: ReadResult.EventValue, currentUpdates?: AttributeUpdates) {
         const { endpointId, clusterId } = occurrence.path;
 
         const endpoint = this.#endpoints.get(endpointId);
@@ -291,7 +300,7 @@ export class ClientStructure {
         ) {
             this.#delayedClusterEvents.push(occurrence);
         } else {
-            this.#eventEmitter(occurrence);
+            await this.#eventEmitter(occurrence);
         }
     }
 
@@ -370,7 +379,7 @@ export class ClientStructure {
     #synchronizeCluster(structure: EndpointStructure, cluster: ClusterStructure) {
         const { endpoint } = structure;
 
-        // Generate a behavior if enough information is available
+        // Generate a behavior if enough             information is available
         if (cluster.behavior === undefined) {
             if (cluster.store.initialValues) {
                 const {
@@ -378,6 +387,7 @@ export class ClientStructure {
                     [FeatureMap.id]: features,
                     [AttributeList.id]: attributeList,
                     [AcceptedCommandList.id]: commandList,
+                    [GeneratedCommandList.id]: generatedCommandList,
                 } = cluster.store.initialValues;
 
                 if (typeof clusterRevision === "number") {
@@ -399,13 +409,21 @@ export class ClientStructure {
                         (a, b) => a - b,
                     );
                 }
+
+                if (Array.isArray(generatedCommandList)) {
+                    cluster.generatedCommands = (
+                        generatedCommandList.filter(cmd => typeof cmd === "number") as CommandId[]
+                    ).sort((a, b) => a - b);
+                }
             }
 
             if (
-                cluster.revision !== undefined &&
-                cluster.features !== undefined &&
-                cluster.attributes !== undefined &&
-                cluster.commands !== undefined
+                // All global attributes have fallbacks so we can't wait until we're sure we have them all.  Instead
+                // wait until we are sure there is something useful.  We therefore rely on unspecified behavior that all
+                // attributes travel consecutively to ensure we initialize fully as we have no other choice
+                cluster.attributes?.length ||
+                cluster.commands?.length ||
+                cluster.generatedCommands?.length
             ) {
                 const behaviorType = PeerBehavior(cluster as PeerBehavior.ClusterShape);
 
@@ -628,7 +646,7 @@ export class ClientStructure {
     /**
      * Replace clusters after activation because fixed global attributes have changed.
      *
-     * Currently we apply granular updates to clusters.  This will possibly result in subtle errors if peers change in
+     * Currently, we apply granular updates to clusters.  This will possibly result in subtle errors if peers change in
      * incompatible ways, but the backings are designed to be fairly resilient to this.  This is simpler for API users
      * to deal with in the common case where they can just ignore. If it becomes problematic we can revert to replacing
      * entire endpoints or behaviors when there are structural changes.
@@ -742,8 +760,6 @@ export class ClientStructure {
      */
     #emitPendingStructureEvents() {
         const structureEvents = this.#pendingStructureEvents;
-        const clusterEvents = this.#delayedClusterEvents;
-        this.#delayedClusterEvents = [];
         this.#pendingStructureEvents = [];
         for (const event of structureEvents) {
             switch (event.kind) {
@@ -789,8 +805,14 @@ export class ClientStructure {
                 }
             }
         }
+        this.#changed.emit();
+    }
+
+    async #emitPendingEvents() {
+        const clusterEvents = this.#delayedClusterEvents;
+        this.#delayedClusterEvents = [];
         for (const occurrence of clusterEvents) {
-            this.#eventEmitter(occurrence);
+            await this.#eventEmitter(occurrence);
         }
     }
 }

package/src/node/client/NodePeerAddressStore.ts

@@ -5,12 +5,12 @@
  */
 
 import { RemoteDescriptor } from "#behavior/system/commissioning/RemoteDescriptor.js";
+import { Crypto, ServerAddress, ServerAddressUdp } from "#general";
 import type { ClientNode } from "#node/ClientNode.js";
 import { IdentityService } from "#node/server/IdentityService.js";
 import type { ServerNode } from "#node/ServerNode.js";
 import { PeerAddress, PeerAddressMap, PeerAddressStore, PeerDescriptor } from "#protocol";
 import { FabricIndex, NodeId } from "#types";
-import { Crypto, ServerAddress, ServerAddressUdp } from "@matter/general";
 
 /**
  * This is an adapter for lower-level components in the protocol package.
@@ -74,17 +74,20 @@ export class NodePeerAddressStore extends PeerAddressStore {
 
     async updatePeer(peer: PeerDescriptor) {
         const node = this.#owner.peers.get(peer.address);
-        if (!node) {
+        if (!node || !node.lifecycle.isInstalled) {
             return;
         }
 
-        await node.act(agent => {
+        await node.act(async agent => {
+            await agent.context.transaction.addResources(agent.commissioning);
+            await agent.context.transaction.begin();
             const state = agent.commissioning.state;
             RemoteDescriptor.toLongForm(peer.discoveryData, state);
             if (peer.operationalAddress) {
                 // TODO - modify lower tiers to pass along full set of operational addresses
                 state.addresses = [peer.operationalAddress];
             }
+            await agent.context.transaction.commit();
         });
     }
 

package/src/node/client/PeerBehavior.ts

@@ -25,6 +25,7 @@ import {
     ClusterComposer,
     ClusterId,
     ClusterRegistry,
+    ClusterType,
     Command,
     CommandId,
     MutableCluster,
@@ -78,11 +79,10 @@ export namespace PeerBehavior {
         kind: "discovered";
         id: ClusterId;
         revision: number;
-        features: FeatureBitmap | number;
-        attributes: AttributeId[];
-        commands: CommandId[];
-        attributeNames: Record<AttributeId, string>;
-        commandNames: Record<CommandId, string>;
+        features?: FeatureBitmap | number;
+        attributes?: AttributeId[];
+        commands?: CommandId[];
+        generatedCommands?: CommandId[];
     }
 
     /**
@@ -103,12 +103,10 @@ function instrumentDiscoveredShape(shape: PeerBehavior.DiscoveredClusterShape) {
         return type;
     }
 
-    let baseType: Behavior.Type;
+    let baseType: Behavior.Type | undefined;
     const standardCluster = ClusterRegistry.get(shape.id);
-    if (standardCluster) {
+    if (standardCluster && !standardCluster.name.startsWith("Unknown cluster 0x")) {
         baseType = ClusterBehavior.for(standardCluster);
-    } else {
-        baseType = ClusterBehavior;
     }
 
     type = discoveredCache[fingerprint] = generateDiscoveredType(analysis, baseType);
@@ -138,30 +136,38 @@ function instrumentKnownShape(shape: PeerBehavior.KnownClusterShape) {
     return type;
 }
 
-function generateDiscoveredType(analysis: DiscoveredShapeAnalysis, baseType: Behavior.Type): ClusterBehavior.Type {
-    // Ensure the input type is a ClusterBehavior
-    if (!ClusterBehavior.is(baseType)) {
-        throw new InternalError(`Base for cluster ${analysis.schema.name} is not a ClusterBehavior`);
-    }
-
+function generateDiscoveredType(analysis: DiscoveredShapeAnalysis, baseType?: Behavior.Type): ClusterBehavior.Type {
     let { schema } = analysis;
-    let isExtended = false;
-    const { attrSupportOverrides, extraAttrs, commandSupportOverrides, extraCommands } = analysis;
 
-    // Obtain a ClusterType.  This provides TLV for known elements
-    let { cluster } = baseType;
-    if (!cluster) {
+    let isExtended: boolean;
+    let cluster: ClusterType;
+
+    if (baseType) {
+        isExtended = false;
+
+        // Ensure the input type is a ClusterBehavior
+        if (!ClusterBehavior.is(baseType)) {
+            throw new InternalError(`Base for cluster ${analysis.schema.name} is not a ClusterBehavior`);
+        }
+
+        cluster = baseType.cluster;
+    } else {
+        isExtended = true;
+
         cluster = MutableCluster({ id: schema.id, name: schema.name, revision: schema.revision });
+
+        baseType = ClusterBehavior;
     }
 
+    const { attrSupportOverrides, extraAttrs, commandSupportOverrides, extraCommands } = analysis;
+
     // Identify known features the device supports
     let supportedFeatures = analysis.shape.features;
     if (typeof supportedFeatures === "number") {
-        if (supportedFeatures) {
-            supportedFeatures = cluster.attributes.featureMap.schema.decode(supportedFeatures as any) as FeatureBitmap;
-        } else {
-            supportedFeatures = {};
-        }
+        supportedFeatures = cluster.attributes.featureMap.schema.decode(supportedFeatures as any) as FeatureBitmap;
+    }
+    if (supportedFeatures === undefined) {
+        supportedFeatures = {};
     }
 
     // If there are features supported, customize the ClusterModel and ClusterType accordingly
@@ -354,18 +360,18 @@ function DiscoveredShapeAnalysis(shape: PeerBehavior.DiscoveredClusterShape): Di
     if (typeof shape.features === "number") {
         featureBitmap = shape.features;
     } else {
-        featureBitmap = EncodedBitmap(schema.featureMap, shape.features);
+        featureBitmap = EncodedBitmap(schema.featureMap, shape.features ?? {});
     }
 
     const attrSupportOverrides = new Map<AttributeModel, boolean>();
-    const extraAttrs = new Set<number>(shape.attributes);
+    const extraAttrs = new Set<number>(shape.attributes ?? []);
     for (const attr of schema.attributes) {
         maybeOverrideSupport(standardCluster, attr, extraAttrs, attrSupportOverrides);
         extraAttrs.delete(attr.id as AttributeId);
     }
 
     const commandSupportOverrides = new Map<CommandModel, boolean>();
-    const extraCommands = new Set(shape.commands);
+    const extraCommands = new Set(shape.commands ?? []);
     for (const command of schema.commands) {
         maybeOverrideSupport(standardCluster, command, extraCommands, commandSupportOverrides);
         extraCommands.delete(command.id as CommandId);

package/src/node/server/InteractionServer.ts

@@ -449,6 +449,7 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
         if (fabric !== undefined && !keepSubscriptions) {
             let clearedCount = 0;
             for (const sess of this.#context.sessions.sessions) {
+                // TODO Adjust this filtering when subscriptions move to Peer
                 if (!PeerAddress.is(sess.peerAddress, session.peerAddress)) {
                     // Ignore subscriptions from other peers
                     continue;