@matter/node 0.16.0-alpha.0-20250819-0a388db8b → 0.16.0-alpha.0-20250821-dd03e1003

package/src/node/client/ClientBehavior.ts

@@ -75,6 +75,7 @@ function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): Cluster
     }
 
     let { schema } = analysis;
+    let isCloned = false;
     const { extraAttrs, extraCommands } = analysis;
 
     // Obtain a ClusterType.  This provides TLV for known elements
@@ -99,8 +100,7 @@ function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): Cluster
         .map(([k]) => k);
     if (featureNames.length) {
         // Update ClusterModel
-        schema = schema.clone();
-        schema.supportedFeatures = featureNames;
+        cloneSchema();
 
         // Update the cluster.  Note that we do not validate feature combinations.  What the device sends we work with
         cluster = new ClusterComposer(cluster, true).compose(featureNames.map(capitalize));
@@ -109,7 +109,7 @@ function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): Cluster
     // If the schema does not match what the device actually returned, further augment both the ClusterModel and
     // ClusterType with unknown attributes and/or commands
     if (schema.revision !== analysis.shape.revision || extraAttrs.size || extraCommands.size) {
-        schema = schema.clone();
+        cloneSchema();
 
         cluster = {
             ...cluster,
@@ -118,8 +118,6 @@ function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): Cluster
             commands: { ...cluster.commands },
         };
 
-        schema.supportedFeatures = supportedFeatures;
-
         for (const id of extraAttrs) {
             const name = createUnknownName("attr", id);
             cluster.attributes[camelize(name, false)] = Attribute(id, TlvAny);
@@ -145,6 +143,15 @@ function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): Cluster
 
     return type;
 
+    function cloneSchema() {
+        if (isCloned) {
+            return;
+        }
+        schema = schema.clone();
+        schema.supportedFeatures = featureNames;
+        isCloned = true;
+    }
+
     function implementCommand(command: ClusterType.Command) {
         return async function (this: ClusterBehavior, fields?: {}) {
             const node = this.env.get(Node) as ClientNode;

package/src/node/client/ClientEventEmitter.ts

@@ -0,0 +1,115 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ElementEvent, Events } from "#behavior/Events.js";
+import { camelize, Logger } from "#general";
+import { ClusterModel, EventModel, MatterModel } from "#model";
+import { ClientNode } from "#node/ClientNode.js";
+import { ReadResult } from "#protocol";
+import { ClusterId, EndpointNumber, EventId } from "#types";
+import { ClientStructure } from "./ClientStructure.js";
+
+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;
+}
+
+/**
+ * Cache of MatterModel + cluster + event ID -> event name.
+ */
+const nameCache = new WeakMap<
+    MatterModel,
+    Record<`${ClusterId}-${EventId}`, undefined | { cluster: string; event: string }>
+>();
+
+/**
+ * We warn for each cluster or cluster+event that we don't support.
+ */
+const warnedForUnknown = new Set<ClusterId | `${ClusterId}-${EventId}`>();
+
+export function ClientEventEmitter(node: ClientNode, structure: ClientStructure) {
+    return emitClientEvent;
+
+    function emitClientEvent(occurrence: ReadResult.EventValue) {
+        const names = getNames(node.matter, occurrence);
+        if (!names) {
+            return;
+        }
+
+        const event = getEvent(occurrence.path.endpointId, names.cluster, names.event);
+        if (event) {
+            node.act(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);
+            });
+        }
+    }
+
+    function getEvent(endpointId: EndpointNumber, clusterName: string, eventName: string) {
+        const endpoint = structure.endpointFor(endpointId);
+        if (endpoint === undefined) {
+            logger.error(`Received event for unsupported endpoint #${endpointId}`);
+            return;
+        }
+
+        const events = (endpoint.events as Events.Generic<ElementEvent>)[clusterName];
+        if (events === undefined) {
+            logger.error(`Received event ${eventName} for unsupported cluster ${clusterName} on ${endpoint}`);
+            return;
+        }
+
+        const event = events[eventName];
+        if (event === undefined) {
+            logger.error(`Received unsupported event ${eventName} for cluster ${clusterName} on ${endpoint}`);
+            return;
+        }
+
+        return event;
+    }
+}
+
+function getNames(matter: MatterModel, { path: { clusterId, eventId } }: ReadResult.EventValue) {
+    let matterCache = nameCache.get(matter);
+    if (matterCache === undefined) {
+        matterCache = {};
+        nameCache.set(matter, matterCache);
+    }
+
+    const key = `${clusterId}-${eventId}` as const;
+    if (key in matterCache) {
+        return matterCache[key];
+    }
+
+    const cluster = matter.get(ClusterModel, clusterId);
+    if (cluster === undefined) {
+        if (!warnedForUnknown.has(clusterId)) {
+            logger.warn(`Ignoring events for unknown cluster #${clusterId}`);
+            warnedForUnknown.add(clusterId);
+            matterCache[key] = undefined;
+        }
+        return;
+    }
+
+    const event = cluster.get(EventModel, eventId);
+    if (event === undefined) {
+        if (!warnedForUnknown.has(key)) {
+            logger.warn(`Ignoring unknown event #${eventId} for ${cluster.name} cluster`);
+            warnedForUnknown.add(key);
+            matterCache[key] = undefined;
+        }
+        return;
+    }
+
+    return (matterCache[key] = { cluster: camelize(cluster.name), event: camelize(event.name) });
+}

package/src/node/client/ClientStructure.ts

@@ -17,6 +17,7 @@ import { DatasourceCache } from "#storage/client/DatasourceCache.js";
 import { ClientNodeStore } from "#storage/index.js";
 import type { AttributeId, ClusterId, ClusterType, CommandId, DeviceTypeId, EndpointNumber } from "#types";
 import { ClientBehavior } from "./ClientBehavior.js";
+import { ClientEventEmitter } from "./ClientEventEmitter.js";
 
 const DEVICE_TYPE_LIST_ATTR_ID = DescriptorCluster.attributes.deviceTypeList.id;
 const SERVER_LIST_ATTR_ID = DescriptorCluster.attributes.serverList.id;
@@ -28,6 +29,7 @@ const PARTS_LIST_ATTR_ID = DescriptorCluster.attributes.partsList.id;
 export class ClientStructure {
     #nodeStore: ClientNodeStore;
     #endpoints: Record<EndpointNumber, EndpointStructure> = {};
+    #emitEvent: ClientEventEmitter;
 
     constructor(node: ClientNode) {
         this.#nodeStore = node.env.get(ClientNodeStore);
@@ -35,6 +37,7 @@ export class ClientStructure {
             endpoint: node,
             clusters: {},
         };
+        this.#emitEvent = ClientEventEmitter(node, this);
     }
 
     /**
@@ -76,9 +79,9 @@ export class ClientStructure {
     }
 
     /**
+     * Obtain the store for a non-cluster behavior.
      *
-     * @param request
-     * @returns
+     * The data for these behaviors is managed locally and not synced from the peer.
      */
     storeForLocal(endpoint: Endpoint, type: Behavior.Type) {
         return this.#nodeStore.storeForEndpoint(endpoint).createStoreForLocalBehavior(type.id);
@@ -132,39 +135,17 @@ export class ClientStructure {
 
         for await (const chunk of changes) {
             for (const change of chunk) {
-                if (change.kind !== "attr-value") {
-                    continue;
-                }
-
-                const { endpointId, clusterId, attributeId } = change.path;
+                switch (change.kind) {
+                    case "attr-value":
+                        currentUpdates = await this.#mutateAttribute(change, scope, currentUpdates);
+                        break;
 
-                // If we are building updates to a cluster and the cluster/endpoint changes, apply the current update
-                // set
-                if (
-                    currentUpdates &&
-                    (currentUpdates.endpointId !== endpointId || currentUpdates.clusterId !== clusterId)
-                ) {
-                    await this.#updateCluster(currentUpdates);
-                    currentUpdates = undefined;
+                    case "event-value":
+                        this.#emitEvent(change);
+                        break;
                 }
-
-                if (currentUpdates === undefined) {
-                    // Updating a new endpoint/cluster
-                    currentUpdates = {
-                        endpointId,
-                        clusterId,
-                        values: {
-                            [attributeId]: change.value,
-                        },
-                    };
-
-                    // Update version but only if this was a wildcard read
-                    if (scope.isWildcard(endpointId, clusterId)) {
-                        currentUpdates.values[DatasourceCache.VERSION_KEY] = change.version;
-                    }
-                } else {
-                    // Add value to change set for current endpoint/cluster
-                    currentUpdates.values[attributeId] = change.value;
+                if (change.kind !== "attr-value") {
+                    continue;
                 }
             }
 
@@ -176,8 +157,44 @@ export class ClientStructure {
         }
     }
 
+    async #mutateAttribute(
+        change: ReadResult.AttributeValue,
+        scope: ReadScope,
+        currentUpdates: undefined | AttributeUpdates,
+    ) {
+        const { endpointId, clusterId, attributeId } = change.path;
+
+        // If we are building updates to a cluster and the cluster/endpoint changes, apply the current update
+        // set
+        if (currentUpdates && (currentUpdates.endpointId !== endpointId || currentUpdates.clusterId !== clusterId)) {
+            await this.#updateCluster(currentUpdates);
+            currentUpdates = undefined;
+        }
+
+        if (currentUpdates === undefined) {
+            // Updating a new endpoint/cluster
+            currentUpdates = {
+                endpointId,
+                clusterId,
+                values: {
+                    [attributeId]: change.value,
+                },
+            };
+
+            // Update version but only if this was a wildcard read
+            if (scope.isWildcard(endpointId, clusterId)) {
+                currentUpdates.values[DatasourceCache.VERSION_KEY] = change.version;
+            }
+        } else {
+            // Add value to change set for current endpoint/cluster
+            currentUpdates.values[attributeId] = change.value;
+        }
+
+        return currentUpdates;
+    }
+
     /**
-     * Obtain the {@link ClusterType} for an endpoint number and cluster ID.
+     * Obtain the {@link ClusterType} for an {@link EndpointNumber} and {@link ClusterId}.
      */
     clusterFor(endpoint: EndpointNumber, cluster: ClusterId) {
         const ep = this.#endpointFor(endpoint);
@@ -188,6 +205,13 @@ export class ClientStructure {
         return this.#clusterFor(ep, cluster)?.behavior?.cluster;
     }
 
+    /**
+     * Obtain the {@link Endpoint} for a {@link EndpointNumber}.
+     */
+    endpointFor(endpoint: EndpointNumber): Endpoint | undefined {
+        return this.#endpoints[endpoint]?.endpoint;
+    }
+
     /**
      * Apply new attribute values for specific endpoint/cluster.
      *

package/src/node/server/IdentityService.ts

@@ -44,7 +44,7 @@ export class IdentityService {
             other = this.#node;
         } else {
             if (this.#partsById === undefined) {
-                this.#partsById = OfflineContext.ReadOnly.agentFor(this.#node).get(IndexBehavior).partsById;
+                this.#partsById = this.#node.agentFor(OfflineContext.ReadOnly).get(IndexBehavior).partsById;
             }
             other = this.#partsById?.[number];
         }

package/src/node/server/ProtocolService.ts

@@ -602,7 +602,7 @@ function invokeCommand(
         requestDiagnostic,
     );
 
-    const agent = context.agentFor(endpoint);
+    const agent = endpoint.agentFor(context);
     const behavior = agent.get(backing.type);
 
     let isAsync = false;