@matter/protocol 0.16.0-alpha.0-20251016-b56cf5683 → 0.16.0-alpha.0-20251018-dd1ea6a8a

package/src/action/client/ClientInteraction.ts

@@ -4,23 +4,37 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { resolvePathForSpecifier } from "#action/index.js";
 import { Interactable, InteractionSession } from "#action/Interactable.js";
-import { Invoke } from "#action/request/Invoke.js";
+import { ClientInvoke, Invoke } from "#action/request/Invoke.js";
 import { Read } from "#action/request/Read.js";
 import { Subscribe } from "#action/request/Subscribe.js";
 import { Write } from "#action/request/Write.js";
-import { InvokeResult } from "#action/response/InvokeResult.js";
+import { DecodedInvokeResult, 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 { BasicSet, Environment, Environmental, ImplementationError, PromiseQueue, Seconds } from "#general";
+import {
+    BasicSet,
+    Diagnostic,
+    Duration,
+    Environment,
+    Environmental,
+    ImplementationError,
+    isObject,
+    Logger,
+    PromiseQueue,
+    Seconds,
+} from "#general";
 import { InteractionClientMessenger, MessageType } from "#interaction/InteractionMessenger.js";
 import { InteractionQueue } from "#peer/InteractionQueue.js";
 import { ExchangeProvider } from "#protocol/ExchangeProvider.js";
-import { TlvSubscribeResponse } from "#types";
+import { Status, TlvNoResponse, TlvSubscribeResponse } from "#types";
 import { ClientSubscriptions } from "./ClientSubscriptions.js";
 import { InputChunk } from "./InputChunk.js";
 
+const logger = Logger.get("ClientInteraction");
+
 export interface ClientInteractionContext {
     exchanges: ExchangeProvider;
     subscriptions: ClientSubscriptions;
@@ -29,6 +43,9 @@ export interface ClientInteractionContext {
 
 export const DEFAULT_MIN_INTERVAL_FLOOR = Seconds(1);
 
+const DEFAULT_TIMED_REQUEST_TIMEOUT = Seconds(10);
+const DEFAULT_MINIMUM_RESPONSE_TIMEOUT_WITH_FAILSAFE = Seconds(30);
+
 /**
  * Client-side implementation of the Matter protocol.
  */
@@ -74,37 +91,85 @@ export class ClientInteraction<SessionT extends InteractionSession = Interaction
     }
 
     async *read(request: Read, _session?: SessionT): ReadResult {
+        const readPathsCount = (request.attributeRequests?.length ?? 0) + (request.eventRequests?.length ?? 0);
+        if (readPathsCount > 9) {
+            logger.debug(
+                "Read interactions with more then 9 paths might be not allowed by the device. Consider splitting then into several read requests.",
+            );
+        }
+
+        this.#begin(request);
+
+        let messenger: undefined | InteractionClientMessenger;
         try {
-            this.#begin(request);
-            const messenger = await InteractionClientMessenger.create(this.#exchanges);
+            messenger = await InteractionClientMessenger.create(this.#exchanges);
 
+            logger.debug("Read »", messenger.exchange.via, request);
             await messenger.sendReadRequest(request);
 
+            let attributeReportCount = 0;
+            let eventReportCount = 0;
+
             for await (const report of messenger.readDataReports()) {
+                attributeReportCount += report.attributeReports?.length ?? 0;
+                eventReportCount += report.eventReports?.length ?? 0;
                 yield InputChunk(report);
             }
+
+            logger.debug(
+                "Read «",
+                messenger.exchange.via,
+                Diagnostic.weak(
+                    attributeReportCount + eventReportCount === 0
+                        ? "(empty)"
+                        : Diagnostic.dict({ attributes: attributeReportCount, events: eventReportCount }),
+                ),
+            );
         } finally {
+            await messenger?.close();
             this.#end(request);
         }
     }
 
+    /**
+     * Write chosen attributes remotely to the node.
+     * The returned attribute write status information is returned. No error is thrown for individual attribute write
+     * failures.
+     */
     async write<T extends Write>(request: T, _session?: SessionT): WriteResult<T> {
+        this.#begin(request);
+
         let messenger: undefined | InteractionClientMessenger;
         try {
-            this.#begin(request);
             messenger = await InteractionClientMessenger.create(this.#exchanges);
+
+            if (request.timedRequest) {
+                await messenger.sendTimedRequest(request.timeout ?? DEFAULT_TIMED_REQUEST_TIMEOUT);
+            }
+
+            logger.info("Write »", messenger.exchange.via, request);
+
             const response = await messenger.sendWriteCommand(request);
             if (request.suppressResponse) {
                 return undefined as Awaited<WriteResult<T>>;
             }
             if (!response || !response.writeResponses?.length) {
-                return new Array<WriteResult.AttributeStatus>() as Awaited<WriteResult<T>>;
-            } else {
-                return response.writeResponses.map(
-                    ({
-                        path: { nodeId, endpointId, clusterId, attributeId, listIndex },
-                        status: { status, clusterStatus },
-                    }) => ({
+                return [] as Awaited<WriteResult<T>>;
+            }
+
+            let successCount = 0;
+            let failureCount = 0;
+            const result = response.writeResponses.map(
+                ({
+                    path: { nodeId, endpointId, clusterId, attributeId, listIndex },
+                    status: { status, clusterStatus },
+                }) => {
+                    if (status === Status.Success) {
+                        successCount++;
+                    } else {
+                        failureCount++;
+                    }
+                    return {
                         kind: "attr-status",
                         path: {
                             nodeId,
@@ -115,21 +180,53 @@ export class ClientInteraction<SessionT extends InteractionSession = Interaction
                         },
                         status,
                         clusterStatus,
-                    }),
-                ) as Awaited<WriteResult<T>>;
-            }
+                    };
+                },
+            ) as Awaited<WriteResult<T>>;
+
+            logger.info(
+                "Write «",
+                messenger.exchange.via,
+                Diagnostic.weak(
+                    successCount + failureCount === 0
+                        ? "(empty)"
+                        : Diagnostic.dict({ success: successCount, failure: failureCount }),
+                ),
+            );
+
+            return result;
         } finally {
             await messenger?.close();
             this.#end(request);
         }
     }
 
-    async *invoke(request: Invoke, _session?: SessionT): InvokeResult {
-        let messenger: undefined | InteractionClientMessenger;
+    async *invoke(request: ClientInvoke, _session?: SessionT): DecodedInvokeResult {
+        this.#begin(request);
+
+        let messenger: InteractionClientMessenger | undefined;
         try {
-            this.#begin(request);
             messenger = await InteractionClientMessenger.create(this.#exchanges);
-            const result = await messenger.sendInvokeCommand(request);
+
+            if (request.timedRequest) {
+                await messenger.sendTimedRequest(request.timeout ?? DEFAULT_TIMED_REQUEST_TIMEOUT);
+            }
+
+            logger.info(
+                "Invoke »",
+                messenger.exchange.via,
+                Diagnostic.asFlags({ suppressResponse: request.suppressResponse, timed: request.timedRequest }),
+                request,
+            );
+
+            const { expectedProcessingTime, useExtendedFailSafeMessageResponseTimeout } = request;
+            const result = await messenger.sendInvokeCommand(
+                request,
+                expectedProcessingTime ??
+                    (useExtendedFailSafeMessageResponseTimeout
+                        ? DEFAULT_MINIMUM_RESPONSE_TIMEOUT_WITH_FAILSAFE
+                        : undefined),
+            );
             if (!request.suppressResponse) {
                 if (result && result.invokeResponses?.length) {
                     const chunk: InvokeResult.Chunk = result.invokeResponses
@@ -140,15 +237,38 @@ export class ClientInteraction<SessionT extends InteractionSession = Interaction
                                     commandRef,
                                     commandFields,
                                 } = response.command;
-                                const res: InvokeResult.CommandResponse = {
+                                const cmd = request.commands.get(commandRef);
+                                if (!cmd) {
+                                    throw new ImplementationError(
+                                        `No response schema found for commandRef ${commandRef} (endpoint ${endpointId}, cluster ${clusterId}, command ${commandId})`,
+                                    );
+                                }
+                                const responseSchema = Invoke.commandOf(cmd).responseSchema;
+                                if (commandFields === undefined && responseSchema !== TlvNoResponse) {
+                                    throw new ImplementationError(
+                                        `No command fields found for commandRef ${commandRef} (endpoint ${endpointId}, cluster ${clusterId}, command ${commandId})`,
+                                    );
+                                }
+
+                                const data =
+                                    commandFields === undefined ? undefined : responseSchema.decodeTlv(commandFields);
+
+                                logger.info(
+                                    "Invoke «",
+                                    messenger!.exchange.via,
+                                    Diagnostic.strong(resolvePathForSpecifier(cmd)),
+                                    isObject(data) ? Diagnostic.dict(data) : Diagnostic.weak("(no payload)"),
+                                );
+
+                                const res: InvokeResult.DecodedCommandResponse = {
                                     kind: "cmd-response",
                                     path: {
                                         endpointId: endpointId!,
-                                        clusterId: clusterId,
-                                        commandId: commandId,
+                                        clusterId,
+                                        commandId,
                                     },
                                     commandRef,
-                                    data: commandFields!, // TODO add decoding
+                                    data,
                                 };
                                 return res;
                             } else if (response.status !== undefined) {
@@ -187,12 +307,37 @@ export class ClientInteraction<SessionT extends InteractionSession = Interaction
     }
 
     async subscribe(request: Subscribe, _session?: SessionT): SubscribeResult {
+        const subscriptionPathsCount = (request.attributeRequests?.length ?? 0) + (request.eventRequests?.length ?? 0);
+        if (subscriptionPathsCount > 3) {
+            logger.debug("Subscribe interactions with more then 3 paths might be not allowed by the device.");
+        }
+
+        if (!request.keepSubscriptions) {
+            for (const subscription of this.#subscriptions) {
+                logger.debug(
+                    `Removing subscription with ID ${subscription.subscriptionId} because new subscription replaces it`,
+                );
+                subscription.close();
+            }
+        }
+
+        this.#begin(request);
+
         let messenger: undefined | InteractionClientMessenger;
         try {
-            this.#begin(request);
-
             messenger = await InteractionClientMessenger.create(this.#exchanges);
 
+            logger.info(
+                "Subscribe »",
+                messenger.exchange.via,
+                Diagnostic.asFlags({ keepSubscriptions: request.keepSubscriptions }),
+                Diagnostic.dict({
+                    min: Duration.format(request.minIntervalFloor),
+                    max: Duration.format(request.maxIntervalCeiling),
+                }),
+                request,
+            );
+
             await messenger.sendSubscribeRequest({
                 minIntervalFloorSeconds: Seconds.of(DEFAULT_MIN_INTERVAL_FLOOR),
                 maxIntervalCeilingSeconds: Seconds.of(DEFAULT_MIN_INTERVAL_FLOOR), // TODO use better max fallback
@@ -204,6 +349,15 @@ export class ClientInteraction<SessionT extends InteractionSession = Interaction
             const responseMessage = await messenger.nextMessage(MessageType.SubscribeResponse);
             const response = TlvSubscribeResponse.decode(responseMessage.payload);
 
+            logger.info(
+                "Subscription successful «",
+                messenger.exchange.via,
+                Diagnostic.dict({
+                    subId: response.subscriptionId,
+                    interval: Duration.format(Seconds(response.maxInterval)),
+                }),
+            );
+
             return this.#subscriptions.add(request, response);
         } finally {
             await messenger?.close();

package/src/action/request/Invoke.ts

@@ -4,32 +4,46 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Diagnostic, Duration, isObject } from "#general";
 import { FALLBACK_INTERACTIONMODEL_REVISION } from "#session/Session.js";
-import { ClusterType, CommandData, InvokeRequest, TlvSchema, TlvStream, TypeFromSchema } from "#types";
+import { ClusterType, CommandData, FabricIndex, InvokeRequest, ObjectSchema, TlvSchema, TypeFromSchema } from "#types";
 import { MalformedRequestError } from "./MalformedRequestError.js";
-import { Specifier } from "./Specifier.js";
+import { resolvePathForSpecifier, Specifier } from "./Specifier.js";
+
+export interface InvokeCommandData extends CommandData {
+    timed?: boolean;
+}
 
 export interface Invoke extends InvokeRequest {
     /** Timeout only relevant for Client Interactions */
-    timeout?: number;
+    timeout?: Duration;
+    expectedProcessingTime?: Duration;
+    useExtendedFailSafeMessageResponseTimeout?: boolean;
+}
+
+export interface ClientInvoke extends Invoke {
+    commands: Map<number | undefined, Invoke.CommandRequest<any>>;
 }
 
 /**
  * Request invocation of one or more commands.
  */
-export function Invoke(options: Invoke.Definition): Invoke;
+export function Invoke(options: Invoke.Definition): ClientInvoke;
 
 /**
  * Request invocation multiple commands with defined options
  */
-export function Invoke(options: Invoke.Definition, ...commands: CommandData[]): Invoke;
+export function Invoke(options: Invoke.Definition, ...commands: Invoke.CommandRequest<any>[]): ClientInvoke;
 
 /**
  * Request invocation multiple commands as list of Commands with default options.
  */
-export function Invoke(...commands: CommandData[]): Invoke;
+export function Invoke(...commands: Invoke.CommandRequest<any>[]): ClientInvoke;
 
-export function Invoke(optionsOrData: Invoke.Definition | CommandData, ...commands: CommandData[]): Invoke {
+export function Invoke(
+    optionsOrData: Invoke.Definition | Invoke.CommandRequest<any>,
+    ...commands: Invoke.CommandRequest<any>[]
+): ClientInvoke {
     if (optionsOrData === undefined) {
         throw new MalformedRequestError(`Invocation requires at least one command`);
     }
@@ -37,62 +51,141 @@ export function Invoke(optionsOrData: Invoke.Definition | CommandData, ...comman
     let options;
     if ("commands" in optionsOrData) {
         options = optionsOrData;
+        commands = [...optionsOrData.commands, ...commands];
     } else {
         commands = [optionsOrData, ...commands];
         options = {};
     }
 
     const {
-        commands: invokeRequests = [],
         interactionModelRevision = FALLBACK_INTERACTIONMODEL_REVISION,
         suppressResponse = false,
-        timed: timedRequest = false,
+        timeout,
+        expectedProcessingTime,
+        useExtendedFailSafeMessageResponseTimeout = false,
+        skipValidation = false,
     } = options;
+    let timedRequest = !!options.timed || !!timeout;
 
-    if (commands.length) {
-        for (const entry of commands) {
-            invokeRequests.push(entry);
-        }
+    if (!commands?.length) {
+        throw new MalformedRequestError(`Invocation requires at least one command`);
     }
 
-    if (!invokeRequests?.length) {
-        throw new MalformedRequestError(`Invocation requires at least one command`);
+    if (commands.length > 1) {
+        const commandRefs = new Set<number>();
+        for (const { commandRef } of commands) {
+            if (commandRef === undefined) {
+                throw new MalformedRequestError(`CommandRef required when invoking multiple commands`);
+            }
+            if (commandRefs.has(commandRef)) {
+                throw new MalformedRequestError(`Duplicate commandRef ${commandRef} in multiple command invoke`);
+            }
+            commandRefs.add(commandRef);
+        }
     }
 
+    const commandMap = new Map<number | undefined, Invoke.CommandRequest<any>>();
+    const invokeRequests: InvokeCommandData[] = commands.map(cmd => {
+        const cmdData = Invoke.Command(cmd, skipValidation);
+        timedRequest ||= !!cmdData.timed;
+        commandMap.set(cmdData.commandRef, cmd);
+        return cmdData;
+    });
+
     return {
+        timedRequest,
+        timeout,
         invokeRequests,
         interactionModelRevision,
         suppressResponse,
-        timedRequest,
-    };
+        expectedProcessingTime,
+        useExtendedFailSafeMessageResponseTimeout,
+
+        // Additional meta-data for client side processing
+        commands: commandMap,
+        [Diagnostic.value]: () =>
+            Diagnostic.list(
+                commands.map(cmd => {
+                    const { commandRef } = cmd;
+                    const fields = "fields" in cmd ? cmd.fields : undefined;
+
+                    return [
+                        Diagnostic.strong(resolvePathForSpecifier(cmd)),
+                        "with",
+                        isObject(fields) ? Diagnostic.dict(fields) : "(no payload)",
+                        commandRef !== undefined ? `(ref ${commandRef})` : "",
+                    ];
+                }),
+            ),
+    } as ClientInvoke;
 }
 
 export namespace Invoke {
     export interface Definition {
-        commands: CommandData[];
+        /** List of commands to invoke */
+        commands: Invoke.CommandRequest<any>[];
+
+        /** Tell the server to not send a response */
         suppressResponse?: boolean;
+
+        /** Whether this is sent as a timed request, if no timeout is specified a default is used */
         timed?: boolean;
+
+        /** Timeout when sent as a timed request, if timed flag is not set it will be set automatically */
+        timeout?: Duration;
+
+        /** Interaction model revision to use, if not specified a default is used */
         interactionModelRevision?: number;
+
+        /** Processing time of the command of the server assumed for this invoke. If not set a default is used */
+        expectedProcessingTime?: Duration;
+
+        /** Whether to use extended timeout for fail-safe messages.  Overwrites the expectedProcessingTime if both are set */
+        useExtendedFailSafeMessageResponseTimeout?: boolean;
+
+        /** Whether to skip validation of command fields against schema */
+        skipValidation?: boolean;
     }
 
-    export function Command<const C extends ClusterType>(request: Invoke.CommandRequest<C>): CommandData {
+    export function Command<const C extends ClusterType>(
+        request: Invoke.CommandRequest<C>,
+        skipValidation = false,
+    ): InvokeCommandData {
         const command = Invoke.commandOf(request);
+        const { requestSchema, requestId, timed } = command;
+        const { commandRef } = request;
+
+        let fields: any = "fields" in request ? request.fields : undefined;
+        if (requestSchema instanceof ObjectSchema) {
+            if (fields === undefined) {
+                // If developer did not provide a request object, create an empty one if it needs to be an object
+                // This can happen when all object properties are optional
+                fields = {};
+            }
+            if (requestSchema.isFabricScoped && fields.fabricIndex === undefined) {
+                fields.fabricIndex = FabricIndex.NO_FABRIC;
+            }
+        }
 
-        let commandFields: TlvStream | undefined;
-
-        if ("fields" in request) {
-            commandFields = command.requestSchema.encodeTlv(request.fields, { forWriteInteraction: true });
+        if (!skipValidation) {
+            requestSchema.validate(fields);
         }
 
-        const result: CommandData = {
+        const commandFields = requestSchema.encodeTlv(fields);
+
+        const result: InvokeCommandData = {
             commandPath: {
+                // Endpoint id is added below if not wildcard
                 clusterId: Specifier.clusterFor(request.cluster).id,
-                commandId: command.requestId,
+                commandId: requestId,
             },
             commandFields,
+            timed: timed ?? false,
+            commandRef,
         };
 
-        const endpointId = Specifier.endpointIdOf(request);
+        // Optional endpoint is handled by the Specifier utility, so we can just cast here
+        const endpointId = Specifier.endpointIdOf(request as ConcreteCommandRequest);
         if (endpointId !== undefined) {
             result.commandPath.endpointId = endpointId;
         }
@@ -103,12 +196,41 @@ export namespace Invoke {
     export type CommandRequest<
         C extends Specifier.Cluster = Specifier.Cluster,
         CMD extends Specifier.Command<Specifier.ClusterFor<C>> = Specifier.Command<Specifier.ClusterFor<C>>,
+    > = ConcreteCommandRequest<C, CMD> | WildcardCommandRequest<C, CMD>;
+
+    export type ConcreteCommandRequest<
+        C extends Specifier.Cluster = Specifier.Cluster,
+        CMD extends Specifier.Command<Specifier.ClusterFor<C>> = Specifier.Command<Specifier.ClusterFor<C>>,
+    > = WildcardCommandRequest<C, CMD> & { endpoint: Specifier.Endpoint };
+
+    export function ConcreteCommandRequest<const C extends ClusterType>(
+        data: Invoke.ConcreteCommandRequest<C>,
+    ): Invoke.ConcreteCommandRequest<any> {
+        if (data.endpoint === undefined) {
+            throw new MalformedRequestError(`ConcreteCommandRequest requires an endpoint`);
+        }
+        return data;
+    }
+
+    export type WildcardCommandRequest<
+        C extends Specifier.Cluster = Specifier.Cluster,
+        CMD extends Specifier.Command<Specifier.ClusterFor<C>> = Specifier.Command<Specifier.ClusterFor<C>>,
     > = {
-        endpoint?: Specifier.Endpoint;
         cluster: C;
         command: CMD;
+        commandName?: string;
+        commandRef?: number;
     } & Fields<Specifier.CommandFor<Specifier.ClusterFor<C>, CMD>["requestSchema"]>;
 
+    export function WildcardCommandRequest<const C extends ClusterType>(
+        data: Invoke.WildcardCommandRequest<C>,
+    ): Invoke.WildcardCommandRequest<any> {
+        if ("endpoint" in data && data.endpoint !== undefined) {
+            throw new MalformedRequestError(`ConcreteCommandRequest must not have an endpoint`);
+        }
+        return data;
+    }
+
     export function commandOf<const R extends CommandRequest>(request: R): ClusterType.Command {
         if (typeof request.command === "string") {
             const cluster = Specifier.clusterFor(request.cluster);

package/src/action/request/Read.ts

@@ -4,9 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { camelize } from "#general";
-import { FALLBACK_INTERACTIONMODEL_REVISION } from "#session/Session.js";
-import type {
+import { camelize, Diagnostic } from "#general";
+import { Specification } from "#model";
+import {
     AttributePath,
     ClusterType,
     DataVersionFilter,
@@ -16,7 +16,7 @@ import type {
     ReadRequest,
 } from "#types";
 import { MalformedRequestError } from "./MalformedRequestError.js";
-import { Specifier } from "./Specifier.js";
+import { resolvePathForSpecifier, Specifier } from "./Specifier.js";
 
 /**
  * A read request formulated using Matter protocol semantics.
@@ -47,10 +47,30 @@ export function Read(optionsOrSelector: Read.Options | Read.Selector, ...selecto
     }
     let { attributes: attributeRequests, versionFilters, events: eventRequests, eventFilters } = options;
 
-    const result: Read = {
+    const result = {
         isFabricFiltered: options.fabricFilter ?? true,
-        interactionModelRevision: options.interactionModelRevision ?? FALLBACK_INTERACTIONMODEL_REVISION,
-    };
+        interactionModelRevision: options.interactionModelRevision ?? Specification.INTERACTION_MODEL_REVISION,
+        [Diagnostic.value]: () =>
+            Diagnostic.dict({
+                attributes: attributeRequests?.length
+                    ? attributeRequests?.map(path => resolvePathForSpecifier(path)).join(", ")
+                    : undefined,
+                events: eventRequests?.length
+                    ? eventRequests?.map(path => resolvePathForSpecifier(path)).join(", ")
+                    : undefined,
+                dataVersionFilters: versionFilters?.length
+                    ? versionFilters
+                          .map(
+                              ({ path: { endpointId, clusterId }, dataVersion }) =>
+                                  `${endpointId}/${clusterId}=${dataVersion}`,
+                          )
+                          .join(", ")
+                    : undefined,
+                eventFilters: eventFilters?.length
+                    ? eventFilters.map(({ nodeId, eventMin }) => `${nodeId}=${eventMin}`).join(", ")
+                    : undefined,
+            }),
+    } as Read;
 
     for (const selector of selectors) {
         reifySelector(selector);