@matter/protocol 0.13.1-alpha.0-20250509-28e1567e1 → 0.13.1-alpha.0-20250511-74ef153aa

package/src/action/server/AttributeResponse.ts

@@ -8,45 +8,35 @@ import { AttributeTypeProtocol, ClusterProtocol, EndpointProtocol, NodeProtocol
 import { Read } from "#action/request/Read.js";
 import { ReadResult } from "#action/response/ReadResult.js";
 import { AccessControl } from "#action/server/AccessControl.js";
+import { DataResponse, FallbackLimits, WildcardPathFlagsCodec } from "#action/server/DataResponse.js";
 import { Val } from "#action/Val.js";
-import { InternalError } from "#general";
-import { AccessLevel, AttributeModel, ElementTag } from "#model";
+import { Diagnostic, InternalError, Logger } from "#general";
+import { AttributeModel, DataModelPath, ElementTag } from "#model";
 import {
     AttributePath,
-    BitmapSchema,
     ClusterId,
     EndpointNumber,
     GlobalAttributes,
     NodeId,
     Status,
     StatusResponseError,
-    WildcardPathFlagsBitmap,
+    TlvSchema,
 } from "#types";
-import { DataModelPath } from "@matter/model";
-import { TlvSchema } from "@matter/types";
+import { StatusCode } from "@matter/types";
+
+const logger = Logger.get("AttributeResponse");
 
 export const GlobalAttrIds = new Set(Object.values(GlobalAttributes({})).map(attr => attr.id));
-export const WildcardPathFlagsCodec = BitmapSchema(WildcardPathFlagsBitmap);
-export const FallbackLimits: AccessControl.Limits = {
-    fabricScoped: false,
-    fabricSensitive: false,
-    readable: true,
-    readLevel: AccessLevel.View,
-    timed: false,
-    writable: true,
-    writeLevel: AccessLevel.Administer,
-};
 
 /**
  * Implements read of attribute data for Matter "read" and "subscribe" interactions.
  *
  * TODO - profile; ensure nested functions are properly JITed and/or inlined
  */
-export class AttributeResponse<SessionT extends AccessControl.Session = AccessControl.Session> {
-    // Configuration
-    #session: SessionT;
-    #node: NodeProtocol;
-    #versions?: Record<EndpointNumber, Record<ClusterId, number>> | undefined;
+export class AttributeResponse<
+    SessionT extends AccessControl.Session = AccessControl.Session,
+> extends DataResponse<SessionT> {
+    #versions?: Record<EndpointNumber, Record<ClusterId, number>>;
 
     // Each input AttributePathIB that does not have an error installs a producer.  Producers run after validation and
     // generate actual attribute data
@@ -63,14 +53,17 @@ export class AttributeResponse<SessionT extends AccessControl.Session = AccessCo
     #currentState?: Val.ProtocolStruct;
     #wildcardPathFlags = 0;
 
-    // The node ID may be expensive to retrieve and is invariant so we cache it here
-    #cachedNodeId?: NodeId;
+    // Count how many attribute status (on error) and attribute values (on success) we have emitted
+    #statusCount = 0;
+    #valueCount = 0;
+    #filteredCount = 0;
 
-    constructor(node: NodeProtocol, session: SessionT, { dataVersionFilters, attributeRequests }: Read.Attributes) {
-        this.#node = node;
-        this.#session = session;
+    constructor(node: NodeProtocol, session: SessionT) {
+        super(node, session);
+    }
 
-        const nodeId = session.fabric === undefined ? NodeId.UNSPECIFIED_NODE_ID : this.#nodeId;
+    *process({ dataVersionFilters, attributeRequests }: Read.Attributes): Generator<ReadResult.Chunk, void, void> {
+        const nodeId = this.session.fabric === undefined ? NodeId.UNSPECIFIED_NODE_ID : this.nodeId;
 
         // Index versions
         if (dataVersionFilters?.length) {
@@ -93,17 +86,12 @@ export class AttributeResponse<SessionT extends AccessControl.Session = AccessCo
         // Register paths
         for (const path of attributeRequests) {
             if (path.endpointId === undefined || path.clusterId === undefined || path.attributeId === undefined) {
-                this.#addWildcard(path);
+                this.addWildcard(path);
             } else {
-                this.#addConcrete(path as ReadResult.ConcreteAttributePath);
+                this.addConcrete(path as ReadResult.ConcreteAttributePath);
             }
         }
-    }
 
-    /**
-     * Emits chunks produced by paths added via {@link #addWildcard} and {@link #addConcrete}.
-     */
-    *[Symbol.iterator](): Generator<ReadResult.Chunk, void, void> {
         if (this.#dataProducers) {
             for (const producer of this.#dataProducers) {
                 yield* producer.apply(this);
@@ -117,18 +105,36 @@ export class AttributeResponse<SessionT extends AccessControl.Session = AccessCo
         }
     }
 
+    /** Guarded accessor for this.#currentEndpoint.  This should never be undefined */
+    get #guardedCurrentEndpoint() {
+        if (this.#currentEndpoint === undefined) {
+            throw new InternalError("currentEndpoint is not set. Should never happen");
+        }
+        return this.#currentEndpoint;
+    }
+
+    /** Guarded accessor for this.#currentCluster.  This should never be undefined */
+    get #guardedCurrentCluster(): ClusterProtocol {
+        if (this.#currentCluster === undefined) {
+            throw new InternalError("currentCluster is not set. Should never happen");
+        }
+        return this.#currentCluster;
+    }
+
+    get counts() {
+        return {
+            status: this.#statusCount,
+            value: this.#valueCount,
+            existent: this.#valueCount + this.#filteredCount,
+        };
+    }
+
     /**
      * Validate a wildcard path and update internal state.
      */
-    #addWildcard(path: AttributePath) {
+    protected addWildcard(path: AttributePath) {
         const { nodeId, endpointId, clusterId, attributeId, wildcardPathFlags } = path;
 
-        if (nodeId !== undefined && nodeId !== this.#nodeId) {
-            return;
-        }
-
-        const wpf = wildcardPathFlags ? WildcardPathFlagsCodec.encode(wildcardPathFlags) : 0;
-
         if (clusterId === undefined && attributeId !== undefined && !GlobalAttrIds.has(attributeId)) {
             throw new StatusResponseError(
                 `Illegal read of wildcard cluster with non-global attribute #${attributeId}`,
@@ -136,21 +142,27 @@ export class AttributeResponse<SessionT extends AccessControl.Session = AccessCo
             );
         }
 
+        if (nodeId !== undefined && nodeId !== this.nodeId) {
+            return;
+        }
+
+        const wpf = wildcardPathFlags ? WildcardPathFlagsCodec.encode(wildcardPathFlags) : 0;
+
         if (endpointId === undefined) {
             this.#addProducer(function* (this: AttributeResponse) {
                 this.#wildcardPathFlags = wpf;
-                for (const endpoint of this.#node) {
-                    yield* this.#readEndpointForWildcard(endpoint, path);
+                for (const endpoint of this.node) {
+                    yield* this.readEndpointForWildcard(endpoint, path);
                 }
             });
             return;
         }
 
-        const endpoint = this.#node[endpointId];
+        const endpoint = this.node[endpointId];
         if (endpoint) {
             this.#addProducer(function (this: AttributeResponse) {
                 this.#wildcardPathFlags = wpf;
-                return this.#readEndpointForWildcard(endpoint, path);
+                return this.readEndpointForWildcard(endpoint, path);
             });
         }
     }
@@ -158,14 +170,16 @@ export class AttributeResponse<SessionT extends AccessControl.Session = AccessCo
     /**
      * Validate a concrete path and update internal state.
      */
-    #addConcrete(path: ReadResult.ConcreteAttributePath) {
+    protected addConcrete(path: ReadResult.ConcreteAttributePath) {
         const { nodeId, endpointId, clusterId, attributeId } = path;
-        if (nodeId !== undefined && this.#nodeId !== nodeId) {
-            this.#addStatus(path, Status.UnsupportedNode);
+
+        if (nodeId !== undefined && this.nodeId !== nodeId) {
+            this.addStatus(path, Status.UnsupportedNode);
+            return;
         }
 
         // Resolve path elements
-        const endpoint = this.#node[endpointId];
+        const endpoint = this.node[endpointId];
         const cluster = endpoint?.[clusterId];
         const attribute = cluster?.type.attributes[attributeId];
         let limits;
@@ -173,7 +187,7 @@ export class AttributeResponse<SessionT extends AccessControl.Session = AccessCo
             // We still need to authorize the user for access even though this path doesn't resolve.  Spec is not
             // explicit on what privilege level we should require as normally that information comes from the resolved
             // attribute.  So attempt to resolve via the active model
-            const modelAttr = this.#node.matter
+            const modelAttr = this.node.matter
                 .member(path.clusterId, [ElementTag.Cluster])
                 ?.member(path.attributeId, [ElementTag.Attribute]);
 
@@ -197,44 +211,45 @@ export class AttributeResponse<SessionT extends AccessControl.Session = AccessCo
                 endpoint: endpointId,
                 cluster: clusterId,
             }),
-            owningFabric: this.#session.fabric,
+            owningFabric: this.session.fabric,
         };
-        const permission = this.#session.authorityAt(limits.readLevel, location);
+        const permission = this.session.authorityAt(limits.readLevel, location);
         switch (permission) {
             case AccessControl.Authority.Granted:
                 break;
 
             case AccessControl.Authority.Unauthorized:
-                this.#addStatus(path, Status.UnsupportedAccess);
+                this.addStatus(path, Status.UnsupportedAccess);
                 return;
 
             case AccessControl.Authority.Restricted:
-                this.#addStatus(path, Status.AccessRestricted);
+                this.addStatus(path, Status.AccessRestricted);
                 return;
 
             default:
                 throw new InternalError(`Unsupported authorization state ${permission}`);
         }
         if (endpoint === undefined) {
-            this.#addStatus(path, Status.UnsupportedEndpoint);
+            this.addStatus(path, Status.UnsupportedEndpoint);
             return;
         }
         if (cluster === undefined) {
-            this.#addStatus(path, Status.UnsupportedCluster);
+            this.addStatus(path, Status.UnsupportedCluster);
             return;
         }
-        if (attribute === undefined) {
-            this.#addStatus(path, Status.UnsupportedAttribute);
+        if (attribute === undefined || !cluster.type.attributes[attribute.id]) {
+            this.addStatus(path, Status.UnsupportedAttribute);
             return;
         }
         if (!limits.readable) {
-            this.#addStatus(path, Status.UnsupportedRead);
+            this.addStatus(path, Status.UnsupportedRead);
             return;
         }
 
         // Skip if version is unchanged
         const skipVersion = this.#versions?.[path.endpointId]?.[path.clusterId];
         if (skipVersion !== undefined && skipVersion === cluster.version) {
+            this.#filteredCount++;
             return;
         }
 
@@ -248,21 +263,21 @@ export class AttributeResponse<SessionT extends AccessControl.Session = AccessCo
                 }
                 this.#currentEndpoint = endpoint;
                 this.#currentCluster = cluster;
-                this.#currentState = cluster.open(this.#session);
+                this.#currentState = cluster.open(this.session);
             } else if (this.#currentCluster !== cluster) {
                 this.#currentCluster = cluster;
-                this.#currentState = cluster.open(this.#session);
+                this.#currentState = cluster.open(this.session);
             } else if (this.#currentState === undefined) {
-                this.#currentState = cluster.open(this.#session);
+                this.#currentState = cluster.open(this.session);
             }
 
-            // Perform actual read of one attribute
-            this.#addValue(
-                path,
-                this.#currentState[attributeId],
-                cluster.version,
-                this.#currentCluster.type.attributes[attributeId]!.tlv,
+            const value = this.#currentState[attributeId];
+            const version = cluster.version;
+            logger.debug(
+                () => `Reading attribute ${this.node.inspectPath(path)}=${Diagnostic.json(value)} (version=${version})`,
             );
+            // Perform actual read of one attribute
+            this.#addValue(path, value, version, this.#currentCluster.type.attributes[attributeId]!.tlv);
         });
     }
 
@@ -274,9 +289,9 @@ export class AttributeResponse<SessionT extends AccessControl.Session = AccessCo
      *
      * {@link this.#wildcardPathFlags} to numeric bitmap must be set prior to invocation.
      *
-     * TODO - skip endpoints for which subject is unauthorized
+     * TODO - skip endpoints for which subject is unauthorized as optimization
      */
-    *#readEndpointForWildcard(endpoint: EndpointProtocol, path: AttributePath) {
+    protected *readEndpointForWildcard(endpoint: EndpointProtocol, path: AttributePath) {
         if (endpoint.wildcardPathFlags & this.#wildcardPathFlags) {
             return;
         }
@@ -293,12 +308,12 @@ export class AttributeResponse<SessionT extends AccessControl.Session = AccessCo
         const { clusterId } = path;
         if (clusterId === undefined) {
             for (const cluster of endpoint) {
-                this.#readClusterForWildcard(cluster, path);
+                this.readClusterForWildcard(cluster, path);
             }
         } else {
             const cluster = endpoint[clusterId];
             if (cluster !== undefined) {
-                this.#readClusterForWildcard(cluster, path);
+                this.readClusterForWildcard(cluster, path);
             }
         }
     }
@@ -310,7 +325,7 @@ export class AttributeResponse<SessionT extends AccessControl.Session = AccessCo
      *
      * TODO - skip clusters for which subject is unauthorized
      */
-    #readClusterForWildcard(cluster: ClusterProtocol, path: AttributePath) {
+    protected readClusterForWildcard(cluster: ClusterProtocol, path: AttributePath) {
         if (cluster.type.wildcardPathFlags & this.#wildcardPathFlags) {
             return;
         }
@@ -320,20 +335,30 @@ export class AttributeResponse<SessionT extends AccessControl.Session = AccessCo
             this.#currentState = undefined;
         }
 
-        const skipVersion = this.#versions?.[this.#currentEndpoint!.id]?.[cluster.type.id];
-        if (skipVersion !== undefined && skipVersion === cluster.version) {
-            return;
-        }
-
         const { attributeId } = path;
+        const skipVersion = this.#versions?.[this.#guardedCurrentEndpoint.id]?.[cluster.type.id];
+        const filteredByVersion = skipVersion !== undefined && skipVersion === cluster.version;
+
         if (attributeId === undefined) {
+            if (filteredByVersion) {
+                for (const attribute of cluster.type.attributes) {
+                    if (attribute.limits.readable) {
+                        this.#filteredCount++;
+                    }
+                }
+                return;
+            }
             for (const attribute of cluster.type.attributes) {
-                this.#readAttributeForWildcard(attribute, path);
+                this.readAttributeForWildcard(attribute, path);
             }
         } else {
+            if (filteredByVersion) {
+                this.#filteredCount++;
+                return;
+            }
             const attribute = cluster.type.attributes[attributeId];
             if (attribute !== undefined) {
-                this.#readAttributeForWildcard(attribute, path);
+                this.readAttributeForWildcard(attribute, path);
             }
         }
     }
@@ -343,37 +368,44 @@ export class AttributeResponse<SessionT extends AccessControl.Session = AccessCo
      *
      * Depends on state initialized by {@link #readClusterForWildcard}.
      */
-    #readAttributeForWildcard(attribute: AttributeTypeProtocol, path: AttributePath) {
+    protected readAttributeForWildcard(attribute: AttributeTypeProtocol, path: AttributePath) {
+        if (!this.#guardedCurrentCluster.type.attributes[attribute.id]) {
+            return;
+        }
+
         if (attribute.wildcardPathFlags & this.#wildcardPathFlags) {
             return;
         }
 
         if (
             !attribute.limits.readable ||
-            this.#session.authorityAt(attribute.limits.readLevel, this.#currentCluster!.location) !==
+            this.session.authorityAt(attribute.limits.readLevel, this.#guardedCurrentCluster.location) !==
                 AccessControl.Authority.Granted
         ) {
             return;
         }
 
         if (this.#currentState === undefined) {
-            this.#currentState = this.#currentCluster!.open(this.#session);
+            this.#currentState = this.#guardedCurrentCluster.open(this.session);
         }
         const value = this.#currentState[attribute.id];
-        if (value !== undefined) {
-            // Only if we have a state value set
-            this.#addValue(
-                {
-                    ...path,
-                    endpointId: this.#currentEndpoint?.id as EndpointNumber,
-                    clusterId: this.#currentCluster?.type.id as ClusterId,
-                    attributeId: attribute.id,
-                },
-                this.#currentState[attribute.id],
-                this.#currentCluster!.version,
-                attribute.tlv,
-            );
+        if (value === undefined) {
+            // Should normally never happen
+            logger.warn(`Attribute ${this.node.inspectPath(path)} defined and enabled but has no value.`);
+            return;
         }
+
+        this.#addValue(
+            {
+                ...path,
+                endpointId: this.#guardedCurrentEndpoint.id,
+                clusterId: this.#guardedCurrentCluster.type.id,
+                attributeId: attribute.id,
+            },
+            this.#currentState[attribute.id],
+            this.#guardedCurrentCluster.version,
+            attribute.tlv,
+        );
     }
 
     /**
@@ -387,21 +419,30 @@ export class AttributeResponse<SessionT extends AccessControl.Session = AccessCo
         }
     }
 
+    #addReportData(report: ReadResult.Report) {
+        if (this.#chunk) {
+            this.#chunk.push(report);
+        } else {
+            this.#chunk = [report];
+        }
+    }
+
     /**
      * Add a status value.
      */
-    #addStatus(path: ReadResult.ConcreteAttributePath, status: Status) {
+    protected addStatus(path: ReadResult.ConcreteAttributePath, status: Status) {
+        logger.debug(
+            () => `Error reading attribute ${this.node.inspectPath(path)}: Status=${StatusCode[status]}(${status})`,
+        );
+
         const report: ReadResult.GlobalAttributeStatus = {
             kind: "attr-status",
             path,
             status,
         };
 
-        if (this.#chunk) {
-            this.#chunk.push(report);
-        } else {
-            this.#chunk = [report];
-        }
+        this.#addReportData(report);
+        this.#statusCount++;
     }
 
     /**
@@ -416,21 +457,7 @@ export class AttributeResponse<SessionT extends AccessControl.Session = AccessCo
             tlv,
         };
 
-        if (this.#chunk) {
-            this.#chunk.push(report);
-        } else {
-            this.#chunk = [report];
-        }
-    }
-
-    /**
-     * The node ID used to filter paths with node ID specified.  Unsure if this is ever actually used.
-     */
-    get #nodeId() {
-        if (this.#cachedNodeId === undefined) {
-            this.#cachedNodeId =
-                (this.#session.fabric && this.#node.nodeIdFor(this.#session.fabric)) ?? NodeId.UNSPECIFIED_NODE_ID;
-        }
-        return this.#cachedNodeId;
+        this.#addReportData(report);
+        this.#valueCount++;
     }
 }

package/src/action/server/AttributeSubscriptionResponse.ts

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2022-2025 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AttributeTypeProtocol, ClusterProtocol, EndpointProtocol, NodeProtocol } from "#action/protocols.js";
+import { ReadResult } from "#action/response/ReadResult.js";
+import { InternalError } from "#general";
+import { AttributeId, AttributePath, ClusterId, EndpointNumber } from "#types";
+import { AccessControl } from "./AccessControl.js";
+import { AttributeResponse } from "./AttributeResponse.js";
+
+type ClusterFilter = {
+    [clusterId: ClusterId]: Set<AttributeId>;
+};
+export type AttributeResponseFilter = {
+    [endpointId: EndpointNumber]: ClusterFilter;
+};
+
+/**
+ * AttributeSubscriptionResponse is a specialized version of AttributeResponse that processes a read/subscribe request
+ * with a filter applied to the attributes. Only the attributes that match the filter will be processed.
+ */
+export class AttributeSubscriptionResponse<
+    SessionT extends AccessControl.Session = AccessControl.Session,
+> extends AttributeResponse<SessionT> {
+    #filter: AttributeResponseFilter;
+    #currentEndpointFilter?: ClusterFilter;
+    #currentClusterFilter?: Set<number>;
+
+    constructor(node: NodeProtocol, session: SessionT, filter: AttributeResponseFilter) {
+        super(node, session);
+        this.#filter = filter;
+    }
+
+    get filter() {
+        return this.#filter;
+    }
+
+    /** Guarded accessor for this.#currentEndpointFilter.  This should never be undefined */
+    protected get currentEndpointFilter() {
+        if (!this.#currentEndpointFilter) {
+            throw new InternalError("currentEndpointFilter is not set. Should never happen");
+        }
+        return this.#currentEndpointFilter;
+    }
+
+    /** Guarded accessor for this.#currentCLusterFilter.  This should never be undefined */
+    protected get currentClusterFilter() {
+        if (!this.#currentClusterFilter) {
+            throw new InternalError("currentClusterFilter is not set. Should never happen");
+        }
+        return this.#currentClusterFilter;
+    }
+
+    protected override addConcrete(path: ReadResult.ConcreteAttributePath) {
+        const { endpointId, clusterId, attributeId } = path;
+        if (this.#filter[endpointId]?.[clusterId]?.has(attributeId) === undefined) {
+            return;
+        }
+        super.addConcrete(path);
+    }
+
+    protected override *readEndpointForWildcard(endpoint: EndpointProtocol, path: AttributePath) {
+        this.#currentEndpointFilter = this.#filter[endpoint.id];
+        if (this.#currentEndpointFilter === undefined) {
+            return;
+        }
+        yield* super.readEndpointForWildcard(endpoint, path);
+    }
+
+    protected override readClusterForWildcard(cluster: ClusterProtocol, path: AttributePath) {
+        this.#currentClusterFilter = this.currentEndpointFilter[cluster.type.id];
+        if (this.#currentClusterFilter === undefined) {
+            return;
+        }
+        super.readClusterForWildcard(cluster, path);
+    }
+
+    protected override readAttributeForWildcard(attribute: AttributeTypeProtocol, path: AttributePath) {
+        if (!this.currentClusterFilter.has(attribute.id)) {
+            return;
+        }
+        super.readAttributeForWildcard(attribute, path);
+    }
+
+    protected override addStatus() {
+        // For Filtered responses we suppress all status reports
+    }
+}

package/src/action/server/DataResponse.ts

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright 2022-2025 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { NodeProtocol } from "#action/protocols.js";
+import { AccessControl } from "#action/server/AccessControl.js";
+import { AccessLevel } from "#model";
+import { BitmapSchema, NodeId, WildcardPathFlagsBitmap } from "#types";
+
+export const WildcardPathFlagsCodec = BitmapSchema(WildcardPathFlagsBitmap);
+export const FallbackLimits: AccessControl.Limits = {
+    fabricScoped: false,
+    fabricSensitive: false,
+    readable: true,
+    readLevel: AccessLevel.View,
+    timed: false,
+    writable: true,
+    writeLevel: AccessLevel.Administer,
+};
+
+export abstract class DataResponse<SessionT extends AccessControl.Session = AccessControl.Session> {
+    // Configuration
+    #session: SessionT;
+    #node: NodeProtocol;
+
+    // The node ID may be expensive to retrieve and is invariant so we cache it here
+    #cachedNodeId?: NodeId;
+
+    constructor(node: NodeProtocol, session: SessionT) {
+        this.#node = node;
+        this.#session = session;
+    }
+
+    protected get node() {
+        return this.#node;
+    }
+
+    protected get session() {
+        return this.#session;
+    }
+
+    /**
+     * The node ID used to filter paths with node ID specified.  Unsure if this is ever actually used.
+     */
+    protected get nodeId() {
+        if (this.#cachedNodeId === undefined) {
+            this.#cachedNodeId =
+                (this.#session.fabric && this.#node.nodeIdFor(this.#session.fabric)) ?? NodeId.UNSPECIFIED_NODE_ID;
+        }
+        return this.#cachedNodeId;
+    }
+
+    abstract counts: {
+        /**
+         * Number of existent entries that were processed. Not all must have had data to send.
+         */
+        existent: number;
+
+        /**
+         * Number of status responses (aka errors we have sent)
+         */
+        status: number;
+
+        /**
+         * Number of value responses (aka success we have sent)
+         */
+        value: number;
+    };
+}