@matter/protocol 0.13.1-alpha.0-20250520-d699cd56d → 0.14.0-alpha.0-20250524-51a7e1721

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/events/OccurrenceManager.ts

@@ -16,7 +16,15 @@ import {
     MaybePromise,
     Observable,
 } from "#general";
-import { EventNumber, FabricIndex, resolveEventName, TlvEventFilter, TlvEventPath, TypeFromSchema } from "#types";
+import {
+    EventNumber,
+    EventPriority,
+    FabricIndex,
+    resolveEventName,
+    TlvEventFilter,
+    TlvEventPath,
+    TypeFromSchema,
+} from "#types";
 import { EventStore, OccurrenceSummary } from "./EventStore.js";
 import { NumberedOccurrence, Occurrence } from "./Occurrence.js";
 
@@ -49,7 +57,7 @@ export class OccurrenceManager {
 
     // As we don't (yet) have storage with secondary indices we currently maintain indices in memory regardless of
     // whether underlying store is volatile
-    readonly #occurrences = new Array<OccurrenceSummary>();
+    #occurrences = new Array<OccurrenceSummary>();
 
     #construction: Construction<OccurrenceManager>;
 
@@ -298,23 +306,82 @@ export class OccurrenceManager {
     }
 
     #dropOldOccurrences() {
-        const count = this.#storedEventCount - this.#bufferConfig.minEventAllowance;
-        if (count <= 0) {
+        let toDelete = this.#storedEventCount - this.#bufferConfig.minEventAllowance;
+        if (toDelete <= 0) {
             return;
         }
 
-        logger.debug(`Event store is full; dropping ${count} old occurrence${count === 1 ? "s" : ""}`);
+        logger.debug(`Event store is full; dropping ${toDelete} old occurrence${toDelete === 1 ? "s" : ""}`);
+
+        const prioData = {
+            [EventPriority.Info]: {
+                count: this.#bufferConfig.minPriorityEventAllowance["info"],
+                minPosition: -1,
+            },
+            [EventPriority.Debug]: {
+                count: this.#bufferConfig.minPriorityEventAllowance["debug"],
+                minPosition: -1,
+            },
+        };
 
         const asyncDrops = Array<PromiseLike<void>>();
 
-        for (const entry of this.#occurrences.splice(0, count)) {
-            const drop = MaybePromise.catch(this.#store.delete(entry.number), error =>
-                logger.warn(`Error dropping occurrence #${entry}: ${error}`),
-            );
-            if (MaybePromise.is(drop)) {
-                asyncDrops.push(drop);
+        // Find out on which index positions we reached the minimum allowed entries for each priority.
+        // For that we count the entries for Non-Critical priorities from the end of the list to the beginning.
+        for (let i = this.#occurrences.length - 1; i >= 0; i--) {
+            const { priority } = this.#occurrences[i];
+
+            if (priority !== EventPriority.Critical) {
+                const data = prioData[priority];
+                if (data.count > 0) {
+                    data.count--;
+                    if (data.count === 0) {
+                        data.minPosition = i;
+                        if (
+                            prioData[EventPriority.Info].minPosition > -1 &&
+                            prioData[EventPriority.Debug].minPosition > -1
+                        ) {
+                            // We have found the minimum position for both priorities, we can stop
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+
+        // Now we can drop the occurrences from the beginning of the list until we reach the minimum allowed entries
+        // for each priority, started with the lowest priority, until we reached the maximum number of entries we need
+        // to remove. Critical events are removed last from the beginning as many as needed to reach the maximum number
+        // of entries to remove.
+        // Deleted entries are marked as undefined in the array, so we can filter them out later in one pass.
+        const occurrences = this.#occurrences as Array<OccurrenceSummary | undefined>;
+        for (const priority of [EventPriority.Debug, EventPriority.Info, EventPriority.Critical]) {
+            const checkUpTo =
+                priority === EventPriority.Critical ? this.#storedEventCount : prioData[priority].minPosition;
+            if (checkUpTo === -1) {
+                // We have less than the minimum of this event type, so we can not remove any
+                continue;
+            }
+            for (let i = 0; i < checkUpTo && toDelete > 0; i++) {
+                if (occurrences[i] === undefined) continue;
+                const { priority: entryPriority, number } = occurrences[i]!;
+                if (entryPriority === priority) {
+                    const drop = MaybePromise.catch(this.#store.delete(number), error =>
+                        logger.warn(`Error dropping occurrence #${number}: ${error}`),
+                    );
+                    if (MaybePromise.is(drop)) {
+                        asyncDrops.push(drop);
+                    }
+                    occurrences[i] = undefined;
+                    toDelete--;
+                }
+            }
+            if (toDelete <= 0) {
+                break;
             }
         }
+        this.#occurrences = occurrences.filter(entry => entry) as OccurrenceSummary[];
+
         this.#storedEventCount = this.#occurrences.length;
 
         if (asyncDrops.length) {
@@ -342,10 +409,23 @@ export namespace OccurrenceManager {
          * {@link minimumEventAllowance}.
          */
         maxEventAllowance: number;
+
+        /**
+         * Minimum allowances by priority.  This ensures a minimum number of non-critical events avoid LRU
+         * harvesting. Critical events take the rest of the entries up to the defined global minimum.
+         */
+        minPriorityEventAllowance: {
+            info: number;
+            debug: number;
+        };
     }
 
     export const DefaultBufferConfig: BufferConfig = {
         minEventAllowance: 10_000,
         maxEventAllowance: 11_000,
+        minPriorityEventAllowance: {
+            info: 2_000,
+            debug: 2_000,
+        },
     };
 }