@matter/protocol 0.13.1-alpha.0-20250520-d699cd56d → 0.14.0-alpha.0-20250521-979eda05d

package/src/action/server/CommandInvokeResponse.ts

@@ -0,0 +1,427 @@
+/**
+ * @license
+ * Copyright 2022-2025 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { CommandInvokeHandler, Invoke, InvokeResult } from "#action/index.js";
+import { InteractionSession } from "#action/Interactable.js";
+import { CommandTypeProtocol, EndpointProtocol, NodeProtocol } from "#action/protocols.js";
+import { AccessControl } from "#action/server/AccessControl.js";
+import { DataResponse, FallbackLimits } from "#action/server/DataResponse.js";
+import { Diagnostic, InternalError, Logger } from "#general";
+import { CommandModel, DataModelPath, ElementTag, FabricIndex as FabricIndexField } from "#model";
+import {
+    CommandPath,
+    FabricIndex,
+    Status,
+    StatusCode,
+    StatusResponseError,
+    TlvSchema,
+    TlvStream,
+    ValidationError,
+} from "#types";
+
+const logger = Logger.get("CommandInvokeResponse");
+
+/**
+ * Implements invoking of commands for matter "invoke" interactions.
+ *
+ * TODO - profile; ensure nested functions are properly JITed and/or inlined
+ */
+export class CommandInvokeResponse<
+    SessionT extends InteractionSession = InteractionSession,
+> extends DataResponse<SessionT> {
+    #fabricIndex: FabricIndex;
+
+    // The initial "chunk" may be a list of errors.  As producers execute it is a set of records associated with the
+    // most recently touched endpoint.  When the endpoint changes the previous chunk emits
+    #chunk?: InvokeResult.Data[];
+
+    // Each input CommandDataIB that does not have an error installs a producer.  Producers run after validation and
+    // generate actual command data
+    #invokers?: Array<(this: CommandInvokeResponse) => AsyncIterable<InvokeResult.Chunk>>;
+
+    // The following state updates as data producers execute.  This serves both to convey state between functions and as
+    // a cache between producers that touch the same endpoint and/or cluster
+    #currentEndpoint?: EndpointProtocol;
+
+    #registeredPaths = new Set<string>();
+    #registeredCommandRefs = new Set<number>();
+
+    // Count how many command status (on error) and command invokes (success) we have emitted
+    #statusCount = 0;
+    #successCount = 0;
+    #errorCount = 0;
+
+    constructor(node: NodeProtocol, session: SessionT) {
+        super(node, session);
+        this.#fabricIndex = session.fabric ?? FabricIndex.NO_FABRIC;
+    }
+
+    async *process<T extends Invoke>({ invokeRequests, suppressResponse }: T): InvokeResult {
+        const multipleInvokes = invokeRequests.length > 1;
+
+        // Register paths
+        for (const command of invokeRequests) {
+            const { commandPath: path, commandFields, commandRef } = command;
+            if (path.endpointId === undefined || path.clusterId === undefined || path.commandId === undefined) {
+                if (multipleInvokes) {
+                    throw new StatusResponseError(
+                        "Wildcard path must not be used with multiple invokes",
+                        StatusCode.InvalidAction,
+                    );
+                }
+                this.#processWildcard(path, commandRef, commandFields);
+            } else {
+                if (multipleInvokes && commandRef === undefined) {
+                    throw new StatusResponseError(
+                        "The CommandRef field must be specified for all commands in a batch invoke",
+                        StatusCode.InvalidAction,
+                    );
+                }
+                this.#processConcrete(path as InvokeResult.ConcreteCommandPath, commandRef, commandFields);
+            }
+        }
+
+        if (this.#invokers) {
+            for (const invoker of this.#invokers) {
+                for await (const chunk of invoker.apply(this)) {
+                    if (!suppressResponse) {
+                        yield chunk;
+                    }
+                }
+            }
+        }
+
+        // We emit chunks lazily when the endpoint changes so there may be one remaining chunk.  There may also be a
+        // chunk with errors even if there are no data producers
+        if (!suppressResponse && this.#chunk !== undefined) {
+            yield this.#chunk;
+        }
+    }
+
+    get counts() {
+        return {
+            status: this.#statusCount,
+            success: this.#successCount,
+            existent: this.#successCount + this.#errorCount,
+        };
+    }
+
+    /**
+     * Process a wildcard path and invoke commands on all endpoints that match the path.
+     */
+    #processWildcard(path: CommandPath, commandRef: number | undefined, commandFields: TlvStream | undefined) {
+        const { clusterId, commandId } = path;
+
+        // Formally, according to spec, we should check for node mismatch here but commandPath do not have a nodeId
+
+        // TODO: Add Group handling and validation
+        /*
+        if (isGroupSession && endpointId !== undefined) {
+            throw new StatusResponseError("Illegal write request with group ID and endpoint ID", StatusCode.InvalidAction);
+        }
+        */
+
+        if (clusterId === undefined || commandId === undefined) {
+            throw new StatusResponseError(
+                "Wildcard path write must specify a clusterId and commandId",
+                StatusCode.InvalidAction,
+            );
+        }
+
+        // If we are here, then endpointId must be wildcard aka undefined
+        this.#addInvoker(async function* invokeWildcardEndpoints(this: CommandInvokeResponse) {
+            for (const endpoint of this.node) {
+                yield* this.#processEndpointForWildcard(endpoint, path, commandRef, commandFields);
+            }
+        });
+    }
+
+    /**
+     * Invoke a command specified by a concrete path
+     */
+    #processConcrete(
+        path: InvokeResult.ConcreteCommandPath,
+        commandRef: number | undefined,
+        commandFields: TlvStream | undefined,
+    ) {
+        const { endpointId, clusterId, commandId } = path;
+
+        const pathKey = `${endpointId}-${clusterId}-${commandId}`;
+        if (this.#registeredPaths.has(pathKey)) {
+            throw new StatusResponseError(
+                `Duplicate concrete command path ${this.node.inspectPath(path)} on batch invoke`,
+                StatusCode.InvalidAction,
+            );
+        }
+        this.#registeredPaths.add(pathKey);
+        if (commandRef !== undefined) {
+            if (this.#registeredCommandRefs.has(commandRef)) {
+                throw new StatusResponseError(
+                    `Duplicate commandRef ${commandRef} on batch invoke`,
+                    StatusCode.InvalidAction,
+                );
+            }
+            this.#registeredCommandRefs.add(commandRef);
+        }
+
+        // Formally, according to spec, we should check for node mismatch here but commandPath do not have a nodeId
+
+        // Resolve path elements
+        const endpoint = this.node[endpointId];
+        const cluster = endpoint?.[clusterId];
+        const command = cluster?.type.commands[commandId];
+        let limits;
+        if (command === undefined) {
+            // 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
+            // command.  So attempt to resolve via the active model
+            const modelAttr = this.node.matter
+                .member(path.clusterId, [ElementTag.Cluster])
+                ?.member(path.commandId, [ElementTag.Command]);
+
+            if (modelAttr) {
+                // OK cluster doesn't exist at that location, but we do understand semantically, so use limits from the
+                // model
+                limits = AccessControl(modelAttr as CommandModel).limits;
+            } else {
+                // We've got no idea.  This effectively falls back to "view" privilege
+                limits = FallbackLimits;
+            }
+        } else {
+            limits = command.limits;
+        }
+
+        // Validate access.  Order here prescribed by 1.4 core spec 8.4.3.2
+        // We need some fallback location if cluster is not defined
+        const location = {
+            ...(cluster?.location ?? {
+                path: DataModelPath.none,
+                endpoint: endpointId,
+                cluster: clusterId,
+            }),
+            owningFabric: this.session.fabric,
+        };
+
+        const permission = this.session.authorityAt(limits.writeLevel, location);
+        switch (permission) {
+            case AccessControl.Authority.Granted:
+                break;
+
+            case AccessControl.Authority.Unauthorized:
+                return this.#addStatus(path, commandRef, Status.UnsupportedAccess);
+
+            case AccessControl.Authority.Restricted:
+                return this.#addStatus(path, commandRef, Status.AccessRestricted);
+
+            default:
+                throw new InternalError(`Unsupported authorization state ${permission}`);
+        }
+
+        if (endpoint === undefined) {
+            return this.#addStatus(path, commandRef, Status.UnsupportedEndpoint);
+        }
+        if (cluster === undefined) {
+            return this.#addStatus(path, commandRef, Status.UnsupportedCluster);
+        }
+        if (command === undefined || !cluster.type.commands[command.id]) {
+            return this.#addStatus(path, commandRef, Status.UnsupportedCommand);
+        }
+
+        if (limits.fabricScoped && this.session.fabric === undefined) {
+            this.#errorCount++;
+            return this.#addStatus(path, commandRef, Status.UnsupportedAccess);
+        }
+
+        if (limits.timed && !this.session.timed) {
+            this.#errorCount++;
+            return this.#addStatus(path, commandRef, Status.NeedsTimedInteraction);
+        }
+
+        // This path contributes an command value
+        this.#addInvoker(async function* invokeConcretePath() {
+            // Update internal state for target endpoint
+            if (this.#currentEndpoint !== endpoint) {
+                if (this.#chunk) {
+                    yield this.#chunk;
+                    this.#chunk = undefined;
+                }
+                this.#currentEndpoint = endpoint;
+            }
+
+            await this.#invokeCommand(command, path, commandRef, commandFields, cluster.commands[command.id]);
+        });
+    }
+
+    /**
+     * Starts new chunk or adds to current chunk all values from {@link endpoint} selected by {@link path}.
+     *
+     * Emits previous chunk if it exists and was not for this endpoint.  This means that our chunk size is one endpoint
+     * worth of data, except for the initial error chunk if there are path errors.
+     **
+     * TODO - skip endpoints for which subject is unauthorized as optimization
+     */
+    async *#processEndpointForWildcard(
+        endpoint: EndpointProtocol,
+        path: CommandPath,
+        commandRef: number | undefined,
+        commandFields: TlvStream | undefined,
+    ) {
+        const { clusterId } = path;
+
+        if (this.#currentEndpoint !== endpoint) {
+            if (this.#chunk) {
+                yield this.#chunk;
+                this.#chunk = undefined;
+            }
+            this.#currentEndpoint = endpoint;
+        }
+
+        const cluster = endpoint[clusterId];
+        if (cluster !== undefined) {
+            const { commandId } = path;
+
+            const command = cluster.type.commands[commandId];
+            if (command !== undefined) {
+                if (
+                    this.session.authorityAt(command.limits.writeLevel, cluster.location) !==
+                        AccessControl.Authority.Granted ||
+                    (command.limits.timed && !this.session.timed)
+                ) {
+                    return;
+                }
+
+                await this.#invokeCommand(
+                    command,
+                    {
+                        ...path,
+                        endpointId: endpoint.id,
+                    },
+                    commandRef,
+                    commandFields,
+                    cluster.commands[command.id],
+                );
+            }
+        }
+    }
+
+    /**
+     * Add a function that invokes commands and produces data.  These functions are run after validation of input paths.
+     */
+    #addInvoker(producer: (this: CommandInvokeResponse) => AsyncIterable<InvokeResult.Chunk>) {
+        if (this.#invokers) {
+            this.#invokers.push(producer);
+        } else {
+            this.#invokers = [producer];
+        }
+    }
+
+    #addResponse(chunk: InvokeResult.Data) {
+        if (this.#chunk) {
+            this.#chunk.push(chunk);
+        } else {
+            this.#chunk = [chunk];
+        }
+    }
+
+    /**
+     * Add a status value.
+     */
+    #addStatus(
+        path: InvokeResult.ConcreteCommandPath,
+        commandRef: number | undefined,
+        status: Status,
+        clusterStatus?: number,
+    ) {
+        if (status !== StatusCode.Success) {
+            logger.info(
+                () =>
+                    `Invoke error ${this.node.inspectPath(path)}: Status=${StatusCode[status]}(${status}), ClusterStatus=${clusterStatus}`,
+            );
+        }
+
+        const response: InvokeResult.CommandStatus = {
+            kind: "cmd-status",
+            path,
+            status,
+            clusterStatus,
+            commandRef,
+        };
+
+        if (status !== StatusCode.Success) {
+            this.#statusCount++;
+        }
+        this.#addResponse(response);
+    }
+
+    async #invokeCommand(
+        command: CommandTypeProtocol,
+        path: InvokeResult.ConcreteCommandPath,
+        commandRef: number | undefined,
+        commandFields: TlvStream | undefined,
+        invoker: CommandInvokeHandler,
+    ) {
+        try {
+            const { requestTlv, responseTlv } = command;
+            const request = this.#decodeWithSchema(requestTlv, commandFields);
+            requestTlv.validate(request);
+            const response = await invoker(request, this.session);
+            await this.session.transaction?.commit();
+
+            this.#successCount++;
+            const encodedResponse = responseTlv.encodeTlv(response);
+            if (encodedResponse.length === 0) {
+                this.#addStatus(path, commandRef, StatusCode.Success);
+            } else {
+                this.#addResponse({
+                    kind: "cmd-response",
+                    path: {
+                        ...path,
+                        commandId: command.responseId,
+                    },
+                    data: encodedResponse,
+                    commandRef,
+                });
+            }
+        } catch (error) {
+            await this.session.transaction?.rollback();
+            if (StatusResponseError.is(error)) {
+                this.#errorCount++;
+
+                let errorCode = error.code;
+                const errorLogText = `Error ${Diagnostic.hex(errorCode)}${
+                    error.clusterCode !== undefined ? `/${Diagnostic.hex(error.clusterCode)}` : ""
+                } while invoking command: ${error.message}`;
+
+                if (error instanceof ValidationError) {
+                    logger.info(
+                        `Validation-${errorLogText}${error.fieldName !== undefined ? ` in field ${error.fieldName}` : ""}`,
+                    );
+                    if (errorCode === StatusCode.InvalidAction) {
+                        errorCode = StatusCode.InvalidCommand;
+                    }
+                } else {
+                    logger.info(errorLogText);
+                }
+
+                this.#addStatus(path, commandRef, errorCode, error.clusterCode);
+                return;
+            }
+            throw error;
+        }
+    }
+
+    #decodeWithSchema(tlv: TlvSchema<any>, value: TlvStream | undefined) {
+        if (value === undefined) {
+            return undefined; // The validation will fail if the schema expected data
+        }
+        return tlv.injectField(
+            tlv.decodeTlv(value),
+            <number>FabricIndexField.id,
+            this.#fabricIndex,
+            () => true, // We always inject the current fabricIndex for invokes
+        );
+    }
+}

package/src/action/server/EventReadResponse.ts

@@ -50,7 +50,7 @@ export class EventReadResponse<
     // Collected allowed and existing event paths to consider when reading events
     #allowedEventPaths = new Map<string, TlvSchema<unknown>>();
 
-    // Count how many attribute status (on error) and attribute values (on success) we have emitted
+    // Count how many events status (on error) and event values (on success) we have emitted
     #statusCount = 0;
     #valueCount = 0;
 

package/src/action/server/ServerInteraction.ts

@@ -14,6 +14,7 @@ import { InvokeResult } from "#action/response/InvokeResult.js";
 import { ReadResult } from "#action/response/ReadResult.js";
 import { SubscribeResult } from "#action/response/SubscribeResult.js";
 import { WriteResult } from "#action/response/WriteResult.js";
+import { CommandInvokeResponse } from "#action/server/CommandInvokeResponse.js";
 import { EventReadResponse } from "#action/server/EventReadResponse.js";
 import { Logger, NotImplementedError } from "#general";
 import { AttributeReadResponse } from "./AttributeReadResponse.js";
@@ -28,8 +29,6 @@ const logger = Logger.get("ServerInteraction");
  * completion there will be redundancy with other components including:
  *
  * - InteractionServer (significant overlap with this class)
- *
- * - InteractionEndpointStructure ({@link NodeProtocol} is largely duplicative)
  */
 export class ServerInteraction<SessionT extends InteractionSession = InteractionSession>
     implements Interactable<SessionT>
@@ -73,8 +72,10 @@ export class ServerInteraction<SessionT extends InteractionSession = Interaction
         return writer.process(request);
     }
 
-    invoke<T extends Invoke>(_request: T, _session?: SessionT): InvokeResult<T> {
-        // TODO
-        throw new NotImplementedError();
+    invoke(request: Invoke, session: SessionT): InvokeResult {
+        // TODO -  validate request
+
+        const invoker = new CommandInvokeResponse(this.#node, session);
+        return invoker.process(request);
     }
 }

package/src/action/server/index.ts

@@ -8,6 +8,7 @@ export * from "./AccessControl.js";
 export * from "./AttributeReadResponse.js";
 export * from "./AttributeSubscriptionResponse.js";
 export * from "./AttributeWriteResponse.js";
+export * from "./CommandInvokeResponse.js";
 export * from "./DataResponse.js";
 export * from "./EventReadResponse.js";
 export * from "./ServerInteraction.js";

package/src/cluster/client/AttributeClient.ts

@@ -106,6 +106,18 @@ export class AttributeClient<T = any> {
         });
     }
 
+    get fabricScoped() {
+        return this.#isFabricScoped;
+    }
+
+    getLocal() {
+        return this.#interactionClient.getStoredAttribute({
+            endpointId: this.endpointId,
+            clusterId: this.clusterId,
+            attribute: this.attribute,
+        });
+    }
+
     /**
      * Get the value of the attribute. Fabric scoped reads are always done with the remote.
      * The `requestFromRemote` parameter allowed to force or prevent remote reads:

package/src/cluster/client/ClusterClientTypes.ts

@@ -229,12 +229,6 @@ export type ClusterClientObj<T extends ClusterType = ClusterType> = {
     /** Returns if a given Attribute with provided name is present and supported at the connected cluster server. */
     isAttributeSupportedByName: (attributeName: string) => boolean;
 
-    /** Returns if a given Event Id is present and supported at the connected cluster server. */
-    isEventSupported: (eventId: EventId) => boolean;
-
-    /** Returns if a given Event with provided name is present and supported at the connected cluster server. */
-    isEventSupportedByName: (eventName: string) => boolean;
-
     /** Returns if a given Command Id is present and supported at the connected cluster server. */
     isCommandSupported: (commandId: CommandId) => boolean;
 

package/src/cluster/index.ts

@@ -5,4 +5,3 @@
  */
 
 export * from "./client/index.js";
-export * from "./server/index.js";

package/src/index.ts

@@ -10,7 +10,6 @@ export * from "./certificate/index.js";
 export * from "./cluster/index.js";
 export * from "./codec/index.js";
 export * from "./common/index.js";
-export * from "./endpoint/index.js";
 export * from "./events/index.js";
 export * from "./fabric/index.js";
 export * from "./interaction/index.js";

package/src/interaction/InteractionClient.ts

@@ -398,6 +398,30 @@ export class InteractionClient {
         return response?.value;
     }
 
+    getStoredAttribute<A extends Attribute<any, any>>(options: {
+        endpointId: EndpointNumber;
+        clusterId: ClusterId;
+        attribute: A;
+    }): AttributeJsType<A> | undefined {
+        return this.getStoredAttributeWithVersion(options)?.value;
+    }
+
+    getStoredAttributeWithVersion<A extends Attribute<any, any>>(options: {
+        endpointId: EndpointNumber;
+        clusterId: ClusterId;
+        attribute: A;
+    }): { value: AttributeJsType<A>; version: number } | undefined {
+        const { endpointId, clusterId, attribute } = options;
+        const { id: attributeId } = attribute;
+        if (this.#nodeStore !== undefined) {
+            const { value, version } = this.#nodeStore.retrieveAttribute(endpointId, clusterId, attributeId) ?? {};
+            if (value !== undefined && version !== undefined) {
+                return { value, version } as { value: AttributeJsType<A>; version: number };
+            }
+        }
+        return undefined;
+    }
+
     async getAttributeWithVersion<A extends Attribute<any, any>>(options: {
         endpointId: EndpointNumber;
         clusterId: ClusterId;

package/src/interaction/index.ts

@@ -9,7 +9,6 @@ export * from "./AttributeDataDecoder.js";
 export * from "./AttributeDataEncoder.js";
 export * from "./EventDataDecoder.js";
 export * from "./InteractionClient.js";
-export * from "./InteractionEndpointStructure.js";
 export * from "./InteractionMessenger.js";
 export * from "./Subscription.js";
 export * from "./SubscriptionClient.js";