@matter/protocol 0.16.0-alpha.0-20251016-b56cf5683 → 0.16.0-alpha.0-20251020-3f6e46245

package/src/action/request/Specifier.ts

@@ -41,7 +41,7 @@ export namespace Specifier {
     export type Command<C extends ClusterType = ClusterType> = ClusterType.Command | (string & keyof C["commands"]);
 
     /**
-     * An event specifier may be the name of a cluser event or an event object.
+     * An event specifier may be the name of a cluster event or an event object.
      */
     export type Event<C extends ClusterType = ClusterType> = ClusterType.Event | (string & keyof C["events"]);
 
@@ -97,6 +97,26 @@ export namespace Specifier {
           ? CMD
           : never;
 
+    export function commandFor<const C extends ClusterType, const CMD extends Specifier.Command<C>>(
+        cluster: C | undefined,
+        specifier: CMD,
+    ): CommandFor<C, CMD> {
+        if (typeof specifier !== "string") {
+            return specifier as CommandFor<C, CMD>;
+        }
+
+        if (cluster === undefined) {
+            throw new MalformedRequestError(`Cannot designate command "${specifier}" without a cluster`);
+        }
+
+        const command = cluster.commands?.[specifier];
+        if (command === undefined) {
+            throw new MalformedRequestError(`Cluster ${cluster.name} does not define command ${specifier}`);
+        }
+
+        return command as CommandFor<C, CMD>;
+    }
+
     /**
      * Extract an event object from a cluster and event specifier.
      */
@@ -144,3 +164,62 @@ export namespace Specifier {
         return request.endpoint?.number;
     }
 }
+
+export function toWildcardOrHexPath(name: string, value: number | bigint | undefined) {
+    if (value === undefined) {
+        return "*";
+    }
+    return `${name ? `${name}:` : ""}0x${value.toString(16)}`;
+}
+
+/**
+ * Resolve a path into a human readable textual form for logging
+ * TODO: Add a Diagnostic display formatter for this
+ */
+export function resolvePathForSpecifier<const C extends ClusterType>(location: {
+    endpoint?: Specifier.Endpoint;
+    cluster?: Specifier.Cluster;
+    attribute?: Specifier.Attribute<Specifier.ClusterFor<C>>;
+    event?: Specifier.Event<Specifier.ClusterFor<C>>;
+    command?: Specifier.Command<Specifier.ClusterFor<C>>;
+    isUrgent?: boolean;
+    listIndex?: number | null;
+}) {
+    const endpointId = Specifier.endpointIdOf(location);
+    const cluster = location.cluster ? Specifier.clusterFor(location.cluster) : undefined;
+    const attribute = location.attribute && cluster ? Specifier.attributeFor(cluster, location.attribute) : undefined;
+    const event = location.event && cluster ? Specifier.eventFor(cluster, location.event) : undefined;
+    const command = location.command && cluster ? Specifier.commandFor(cluster, location.command) : undefined;
+    const isUrgentString = "isUrgent" in location && location.isUrgent ? "!" : "";
+    const listIndexString = "listIndex" in location && location.listIndex === null ? "[ADD]" : "";
+    const postString = `${listIndexString}${isUrgentString}`;
+
+    const clusterId = cluster?.id;
+    const elementId = attribute ? attribute.id : event ? event.id : command ? command.requestId : undefined;
+
+    if (endpointId === undefined) {
+        return `*.${toWildcardOrHexPath("", clusterId)}.${toWildcardOrHexPath("", elementId)}${postString}`;
+    }
+
+    const endpointName = toWildcardOrHexPath("", endpointId);
+
+    if (cluster === undefined || clusterId === undefined) {
+        return `${endpointName}.*.${toWildcardOrHexPath("", elementId)}${postString}`;
+    }
+
+    const clusterName = toWildcardOrHexPath(cluster.name, clusterId);
+
+    if (elementId !== undefined) {
+        if (event) {
+            return `${endpointName}.${clusterName}.${toWildcardOrHexPath(typeof location.event === "string" ? location.event : "?", elementId)}${postString}`;
+        } else if (attribute) {
+            return `${endpointName}.${clusterName}.${toWildcardOrHexPath(typeof location.attribute === "string" ? location.attribute : "?", elementId)}${postString}`;
+        } else if (command) {
+            return `${endpointName}.${clusterName}.${toWildcardOrHexPath(typeof location.command === "string" ? location.command : "?", elementId)}${postString}`;
+        } else {
+            return "unknown";
+        }
+    } else {
+        return `${endpointName}.${clusterName}.*${postString}`;
+    }
+}

package/src/action/request/Write.ts

@@ -4,14 +4,25 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { FALLBACK_INTERACTIONMODEL_REVISION } from "#session/Session.js";
-import { AttributeData, ClusterType, WriteRequest } from "#types";
+import { AccessControl } from "#clusters/access-control";
+import { Diagnostic, Duration } from "#general";
+import { Specification } from "#model";
+import { ArraySchema, AttributeData, AttributeId, ClusterId, ClusterType, WriteRequest } from "#types";
 import { MalformedRequestError } from "./MalformedRequestError.js";
-import { Specifier } from "./Specifier.js";
+import { resolvePathForSpecifier, Specifier } from "./Specifier.js";
+
+const AclClusterId = AccessControl.Complete.id;
+const AclAttributeId = AccessControl.Complete.attributes.acl.id;
+const AclExtensionAttributeId = AccessControl.Complete.attributes.extension.id;
+
+function isAclOrExtensionPath(path: { clusterId: ClusterId; attributeId: AttributeId }) {
+    const { clusterId, attributeId } = path;
+    return clusterId === AclClusterId && (attributeId === AclAttributeId || attributeId === AclExtensionAttributeId);
+}
 
 export interface Write extends WriteRequest {
-    /** Timeout only relevant for Client Interactions */
-    timeout?: number;
+    /** Timeout only relevant for Client Interactions with a required TimedRequest flagging */
+    timeout?: Duration;
 }
 
 /**
@@ -41,13 +52,25 @@ export function Write(optionsOrData: Write.Options | Write.Attribute, ...data: W
     } else {
         options = optionsOrData;
     }
-    const { writes: writeRequests = [] } = options;
+    const { writes: writeRequests = [], timed, timeout, chunkLists } = options;
 
-    const result: Write = {
-        timedRequest: !!options.timed || !!options.timeout,
+    const result = {
+        timedRequest: !!timed || !!timeout,
+        timeout,
         writeRequests,
-        interactionModelRevision: options.interactionModelRevision ?? FALLBACK_INTERACTIONMODEL_REVISION,
-    };
+        moreChunkedMessages: false,
+        interactionModelRevision: options.interactionModelRevision ?? Specification.INTERACTION_MODEL_REVISION,
+
+        [Diagnostic.value]: () =>
+            Diagnostic.list(
+                data.map(entry => {
+                    const { version, value } = entry;
+                    return `${resolvePathForSpecifier(entry)} = ${Diagnostic.json(
+                        value,
+                    )}${version !== undefined ? `(version=${version})` : ""}`;
+                }),
+            ),
+    } as Write;
 
     for (const entry of data) {
         reifyData(entry);
@@ -87,15 +110,43 @@ export function Write(optionsOrData: Write.Options | Write.Attribute, ...data: W
         };
 
         for (const specifier of attributes) {
+            const clusterId = cluster.id;
             const attribute = Specifier.attributeFor(cluster, specifier);
-            writeRequests.push({
-                ...prototype,
-                path: {
-                    ...prototype.path,
-                    attributeId: attribute.id,
-                },
-                data: attribute.schema.encodeTlv(value, { forWriteInteraction: true }),
-            });
+            const { schema, id: attributeId } = attribute;
+
+            if (
+                chunkLists &&
+                Array.isArray(value) &&
+                schema instanceof ArraySchema &&
+                // As implemented for Matter 1.4.2 in https://github.com/project-chip/connectedhomeip/pull/38263
+                // Acl writes will no longer be chunked by default, all others still
+                // Will be streamlined later ... see https://github.com/project-chip/connectedhomeip/issues/38270
+                !isAclOrExtensionPath({ clusterId, attributeId })
+            ) {
+                writeRequests.push(
+                    ...schema
+                        .encodeAsChunkedArray(value, { forWriteInteraction: true })
+                        .map(({ element: data, listIndex }) => ({
+                            path: {
+                                ...prototype.path,
+                                attributeId: attribute.id,
+                                listIndex,
+                            },
+                            data,
+                            dataVersion,
+                        })),
+                );
+            } else {
+                writeRequests.push({
+                    ...prototype,
+                    path: {
+                        ...prototype.path,
+                        attributeId: attribute.id,
+                    },
+                    data: attribute.schema.encodeTlv(value, { forWriteInteraction: true }),
+                });
+            }
+            result.timedRequest ||= attribute.timed;
         }
     }
 }
@@ -104,8 +155,9 @@ export namespace Write {
     export interface Options {
         writes?: AttributeData[];
         timed?: boolean;
-        timeout?: number;
+        timeout?: Duration;
         interactionModelRevision?: number;
+        chunkLists?: boolean;
     }
 
     /**

package/src/action/response/InvokeResult.ts

@@ -8,10 +8,14 @@ import type { ClusterId, CommandId, CommandPath, EndpointNumber, StatusCode, Tlv
 
 export type InvokeResult = AsyncIterable<InvokeResult.Chunk>;
 
+export type DecodedInvokeResult = AsyncIterable<InvokeResult.DecodedChunk>;
+
 export namespace InvokeResult {
     export type Chunk = Iterable<Data>;
+    export type DecodedChunk = Iterable<DecodedData>;
 
     export type Data = CommandStatus | CommandResponse;
+    export type DecodedData = CommandStatus | DecodedCommandResponse;
 
     export interface ConcreteCommandPath extends CommandPath {
         endpointId: EndpointNumber;
@@ -33,4 +37,8 @@ export namespace InvokeResult {
         commandRef?: number;
         data: TlvStream;
     }
+
+    export interface DecodedCommandResponse extends Omit<CommandResponse, "data"> {
+        data: any;
+    }
 }

package/src/common/FailsafeContext.ts

@@ -14,6 +14,7 @@ import {
     UnexpectedDataError,
     UninitializedDependencyError,
 } from "#general";
+import { SecureSession } from "#session/SecureSession.js";
 import { CaseAuthenticatedTag, NodeId, ValidationError, VendorId } from "#types";
 import { Fabric, FabricBuilder } from "../fabric/Fabric.js";
 import { FabricManager } from "../fabric/FabricManager.js";
@@ -47,11 +48,11 @@ export abstract class FailsafeContext {
     #commissioned = AsyncObservable<[], void>();
 
     constructor(options: FailsafeContext.Options) {
-        const { expiryLength, associatedFabric, maxCumulativeFailsafe } = options;
+        const { sessions, fabrics, expiryLength, session, maxCumulativeFailsafe } = options;
 
-        this.#sessions = options.sessions;
-        this.#fabrics = options.fabrics;
-        this.#associatedFabric = options.associatedFabric;
+        this.#sessions = sessions;
+        this.#fabrics = fabrics;
+        this.#associatedFabric = session.fabric;
 
         this.#construction = Construction(this, async () => {
             this.#fabricBuilder = await FabricBuilder.create(this.#fabrics.crypto);
@@ -62,10 +63,18 @@ export abstract class FailsafeContext {
 
             // If ExpiryLengthSeconds is non-zero and the fail-safe timer was not currently armed, then the fail-safe
             // timer SHALL be armed for that duration.
-            this.#failsafe = new FailsafeTimer(associatedFabric, expiryLength, maxCumulativeFailsafe, () =>
+            this.#failsafe = new FailsafeTimer(this.#associatedFabric, expiryLength, maxCumulativeFailsafe, () =>
                 this.#failSafeExpired(),
             );
             logger.debug(`Arm failSafe timer for ${Duration.format(expiryLength)}`);
+
+            // When the PASE session used to arm the Fail-Safe timer is terminated by peer, the Fail-Safe timer SHALL
+            // be considered expired and do the relevant cleanup actions.
+            session.closedByPeer.on(() => {
+                if (!this.#failsafe?.completed) {
+                    return this.#failSafeExpired();
+                }
+            });
         });
     }
 
@@ -341,6 +350,6 @@ export namespace FailsafeContext {
         fabrics: FabricManager;
         expiryLength: Duration;
         maxCumulativeFailsafe: Duration;
-        associatedFabric: Fabric | undefined;
+        session: SecureSession;
     }
 }

package/src/common/FailsafeTimer.ts

@@ -19,6 +19,7 @@ export class FailsafeTimer {
     #expiryCallback: () => Promise<void>;
     #failsafeTimer: Timer;
     #maxCumulativeFailsafeTimer: Timer;
+    #completed = false;
 
     constructor(
         public associatedFabric: Fabric | undefined,
@@ -69,14 +70,24 @@ export class FailsafeTimer {
         }
     }
 
+    /** Returns whether the FailSafe context is currently armed. */
+    get completed() {
+        return this.#completed;
+    }
+
     /** Expire the FailSafe context. This is called by the timer and can also be called manually if needed. */
     async expire() {
+        if (this.#completed) {
+            // Completion was already triggered, so do nothing
+            return;
+        }
         this.complete();
         await this.#expiryCallback();
     }
 
     /** Complete the FailSafe context. This is called when the commissioning is completed. */
     complete() {
+        this.#completed = true;
         this.#failsafeTimer.stop();
         this.#maxCumulativeFailsafeTimer.stop();
     }