@matter/protocol 0.16.0-alpha.0-20250816-d22ad240d → 0.16.0-alpha.0-20250819-0a388db8b

package/src/interaction/InteractionClient.ts

@@ -7,12 +7,14 @@
 import { AccessControl } from "#clusters/access-control";
 import {
     Diagnostic,
+    Duration,
     Environment,
     Environmental,
     ImplementationError,
     Logger,
     MatterFlowError,
     PromiseQueue,
+    Seconds,
     ServerAddressIp,
     Timer,
     UnexpectedDataError,
@@ -61,8 +63,8 @@ import { RegisteredSubscription, SubscriptionClient } from "./SubscriptionClient
 const logger = Logger.get("InteractionClient");
 
 const REQUEST_ALL = [{}];
-const DEFAULT_TIMED_REQUEST_TIMEOUT_MS = 10_000; // 10 seconds
-const DEFAULT_MINIMUM_RESPONSE_TIMEOUT_WITH_FAILSAFE_MS = 30_000; // 30 seconds
+const DEFAULT_TIMED_REQUEST_TIMEOUT = Seconds(10);
+const DEFAULT_MINIMUM_RESPONSE_TIMEOUT_WITH_FAILSAFE = Seconds(30);
 
 const AclClusterId = AccessControl.Complete.id;
 const AclAttributeId = AccessControl.Complete.attributes.acl.id;
@@ -204,8 +206,8 @@ export class InteractionClient {
     }
 
     /** Calculates the current maximum response time for a message use in additional logic like timers. */
-    maximumPeerResponseTimeMs(expectedProcessingTimeMs?: number) {
-        return this.#exchangeProvider.maximumPeerResponseTimeMs(expectedProcessingTimeMs);
+    maximumPeerResponseTime(expectedProcessingTime?: Duration) {
+        return this.#exchangeProvider.maximumPeerResponseTime(expectedProcessingTime);
     }
 
     removeSubscription(subscriptionId: number) {
@@ -544,18 +546,18 @@ export class InteractionClient {
             dataVersion?: number;
         };
         asTimedRequest?: boolean;
-        timedRequestTimeoutMs?: number;
+        timedRequestTimeout?: Duration;
         suppressResponse?: boolean;
         executeQueued?: boolean;
         chunkLists?: boolean;
     }): Promise<void> {
-        const { attributeData, asTimedRequest, timedRequestTimeoutMs, suppressResponse, executeQueued, chunkLists } =
+        const { attributeData, asTimedRequest, timedRequestTimeout, suppressResponse, executeQueued, chunkLists } =
             options;
         const { endpointId, clusterId, attribute, value, dataVersion } = attributeData;
         const response = await this.setMultipleAttributes({
             attributes: [{ endpointId, clusterId, attribute, value, dataVersion }],
             asTimedRequest,
-            timedRequestTimeoutMs,
+            timedRequestTimeout,
             suppressResponse,
             executeQueued,
             chunkLists,
@@ -585,7 +587,7 @@ export class InteractionClient {
             dataVersion?: number;
         }[];
         asTimedRequest?: boolean;
-        timedRequestTimeoutMs?: number;
+        timedRequestTimeout?: Duration;
         suppressResponse?: boolean;
         executeQueued?: boolean;
         chunkLists?: boolean;
@@ -595,7 +597,7 @@ export class InteractionClient {
         const {
             attributes,
             asTimedRequest,
-            timedRequestTimeoutMs = DEFAULT_TIMED_REQUEST_TIMEOUT_MS,
+            timedRequestTimeout = DEFAULT_TIMED_REQUEST_TIMEOUT,
             suppressResponse = this.isGroupAddress,
             chunkLists = true, // Should be true currently to stay in sync with chip sdk
         } = options;
@@ -654,7 +656,7 @@ export class InteractionClient {
         const timedRequest =
             attributes.some(({ attribute: { timed } }) => timed) ||
             asTimedRequest === true ||
-            options.timedRequestTimeoutMs !== undefined;
+            options.timedRequestTimeout !== undefined;
         if (this.isGroupAddress && timedRequest) {
             throw new ImplementationError("Timed requests are not supported for group address writes.");
         }
@@ -662,7 +664,7 @@ export class InteractionClient {
         const response = await this.withMessenger<TypeFromSchema<typeof TlvWriteResponse> | undefined>(
             async messenger => {
                 if (timedRequest) {
-                    await messenger.sendTimedRequest(timedRequestTimeoutMs);
+                    await messenger.sendTimedRequest(timedRequestTimeout);
                 }
 
                 return await messenger.sendWriteCommand({
@@ -747,11 +749,11 @@ export class InteractionClient {
         const {
             subscribeResponse: { subscriptionId, maxInterval },
             report,
-            maximumPeerResponseTimeMs,
+            maximumPeerResponseTime,
         } = await this.withMessenger<{
             subscribeResponse: TypeFromSchema<typeof TlvSubscribeResponse>;
             report: DataReport;
-            maximumPeerResponseTimeMs: number;
+            maximumPeerResponseTime: Duration;
         }>(async messenger => {
             await messenger.sendSubscribeRequest({
                 interactionModelRevision: Specification.INTERACTION_MODEL_REVISION,
@@ -769,7 +771,7 @@ export class InteractionClient {
             return {
                 subscribeResponse,
                 report,
-                maximumPeerResponseTimeMs: this.maximumPeerResponseTimeMs(),
+                maximumPeerResponseTime: this.maximumPeerResponseTime(),
             };
         }, executeQueued);
 
@@ -800,8 +802,8 @@ export class InteractionClient {
         await this.#registerSubscription(
             {
                 id: subscriptionId,
-                maximumPeerResponseTimeMs,
-                maxIntervalS: maxInterval,
+                maximumPeerResponseTime,
+                maxInterval: Seconds(maxInterval),
                 onData: subscriptionListener,
                 onTimeout: updateTimeoutHandler,
             },
@@ -821,8 +823,8 @@ export class InteractionClient {
         endpointId: EndpointNumber;
         clusterId: ClusterId;
         event: E;
-        minIntervalFloorSeconds: number;
-        maxIntervalCeilingSeconds: number;
+        minIntervalFloor: Duration;
+        maxIntervalCeiling: Duration;
         isUrgent?: boolean;
         minimumEventNumber?: EventNumber;
         isFabricFiltered?: boolean;
@@ -840,8 +842,8 @@ export class InteractionClient {
             endpointId,
             clusterId,
             event,
-            minIntervalFloorSeconds,
-            maxIntervalCeilingSeconds,
+            minIntervalFloor,
+            maxIntervalCeiling,
             isUrgent,
             minimumEventNumber,
             isFabricFiltered = true,
@@ -853,32 +855,32 @@ export class InteractionClient {
         const { id: eventId } = event;
 
         logger.debug(
-            `Sending subscribe request for event: ${resolveEventName({ endpointId, clusterId, eventId })} with minInterval=${minIntervalFloorSeconds}s/maxInterval=${maxIntervalCeilingSeconds}s`,
+            `Sending subscribe request for event: ${resolveEventName({ endpointId, clusterId, eventId })} with minInterval=${minIntervalFloor}/maxInterval=${maxIntervalCeiling}`,
         );
 
         const {
             report,
             subscribeResponse: { subscriptionId, maxInterval },
-            maximumPeerResponseTimeMs,
+            maximumPeerResponseTime,
         } = await this.withMessenger<{
             subscribeResponse: TypeFromSchema<typeof TlvSubscribeResponse>;
             report: DataReport;
-            maximumPeerResponseTimeMs: number;
+            maximumPeerResponseTime: Duration;
         }>(async messenger => {
             await messenger.sendSubscribeRequest({
                 interactionModelRevision: Specification.INTERACTION_MODEL_REVISION,
                 eventRequests: [{ endpointId, clusterId, eventId, isUrgent }],
                 eventFilters: minimumEventNumber !== undefined ? [{ eventMin: minimumEventNumber }] : undefined,
                 keepSubscriptions: true,
-                minIntervalFloorSeconds,
-                maxIntervalCeilingSeconds,
+                minIntervalFloorSeconds: Seconds.of(minIntervalFloor),
+                maxIntervalCeilingSeconds: Seconds.of(maxIntervalCeiling),
                 isFabricFiltered,
             });
             const { subscribeResponse, report } = await messenger.readAggregateSubscribeResponse();
             return {
                 subscribeResponse,
                 report,
-                maximumPeerResponseTimeMs: this.maximumPeerResponseTimeMs(),
+                maximumPeerResponseTime: this.maximumPeerResponseTime(),
             };
         }, executeQueued);
 
@@ -906,8 +908,8 @@ export class InteractionClient {
         await this.#registerSubscription(
             {
                 id: subscriptionId,
-                maximumPeerResponseTimeMs,
-                maxIntervalS: maxInterval,
+                maximumPeerResponseTime,
+                maxInterval: Seconds(maxInterval),
                 onData: subscriptionListener,
                 onTimeout: updateTimeoutHandler,
             },
@@ -1027,11 +1029,11 @@ export class InteractionClient {
         const {
             report,
             subscribeResponse: { subscriptionId, maxInterval },
-            maximumPeerResponseTimeMs,
+            maximumPeerResponseTime,
         } = await this.withMessenger<{
             subscribeResponse: TypeFromSchema<typeof TlvSubscribeResponse>;
             report: DataReport;
-            maximumPeerResponseTimeMs: number;
+            maximumPeerResponseTime: Duration;
         }>(async messenger => {
             await messenger.sendSubscribeRequest({
                 interactionModelRevision: Specification.INTERACTION_MODEL_REVISION,
@@ -1051,7 +1053,7 @@ export class InteractionClient {
             return {
                 subscribeResponse,
                 report,
-                maximumPeerResponseTimeMs: this.maximumPeerResponseTimeMs(),
+                maximumPeerResponseTime: this.maximumPeerResponseTime(),
             };
         }, executeQueued);
 
@@ -1125,8 +1127,8 @@ export class InteractionClient {
         await this.#registerSubscription(
             {
                 id: subscriptionId,
-                maximumPeerResponseTimeMs,
-                maxIntervalS: maxInterval,
+                maximumPeerResponseTime,
+                maxInterval: Seconds(maxInterval),
 
                 onData: dataReport => subscriptionListener(DecodedDataReport(dataReport)),
 
@@ -1155,13 +1157,13 @@ export class InteractionClient {
         asTimedRequest?: boolean;
 
         /** Use this timeout and send the request as Timed Request. If this is specified the above parameter is implied. */
-        timedRequestTimeoutMs?: number;
+        timedRequestTimeout?: Duration;
 
         /**
          * Expected processing time on the device side for this command.
          * useExtendedFailSafeMessageResponseTimeout is ignored if this value is set.
          */
-        expectedProcessingTimeMs?: number;
+        expectedProcessingTime?: Duration;
 
         /** Use an extended Message Response Timeout as defined for FailSafe cases which is 30s. */
         useExtendedFailSafeMessageResponseTimeout?: boolean;
@@ -1179,14 +1181,14 @@ export class InteractionClient {
             clusterId,
             command: { requestId, requestSchema, responseId, responseSchema, optional, timed },
             asTimedRequest,
-            timedRequestTimeoutMs = DEFAULT_TIMED_REQUEST_TIMEOUT_MS,
-            expectedProcessingTimeMs,
+            timedRequestTimeout: timedRequestTimeoutMs = DEFAULT_TIMED_REQUEST_TIMEOUT,
+            expectedProcessingTime,
             useExtendedFailSafeMessageResponseTimeout = false,
             skipValidation,
         } = options;
         let { request } = options;
         const timedRequest =
-            (timed && !skipValidation) || asTimedRequest === true || options.timedRequestTimeoutMs !== undefined;
+            (timed && !skipValidation) || asTimedRequest === true || options.timedRequestTimeout !== undefined;
 
         if (this.isGroupAddress) {
             if (endpointId !== undefined) {
@@ -1234,9 +1236,9 @@ export class InteractionClient {
                     suppressResponse: false,
                     interactionModelRevision: Specification.INTERACTION_MODEL_REVISION,
                 },
-                expectedProcessingTimeMs ??
+                expectedProcessingTime ??
                     (useExtendedFailSafeMessageResponseTimeout
-                        ? DEFAULT_MINIMUM_RESPONSE_TIMEOUT_WITH_FAILSAFE_MS
+                        ? DEFAULT_MINIMUM_RESPONSE_TIMEOUT_WITH_FAILSAFE
                         : undefined),
             );
             if (response === undefined) {
@@ -1301,7 +1303,7 @@ export class InteractionClient {
         request: RequestType<C>;
         command: C;
         asTimedRequest?: boolean;
-        timedRequestTimeoutMs?: number;
+        timedRequestTimeout?: Duration;
         executeQueued?: boolean;
     }): Promise<void> {
         const { executeQueued } = options;
@@ -1312,9 +1314,9 @@ export class InteractionClient {
             request,
             command: { requestId, requestSchema, timed },
             asTimedRequest,
-            timedRequestTimeoutMs = DEFAULT_TIMED_REQUEST_TIMEOUT_MS,
+            timedRequestTimeout = DEFAULT_TIMED_REQUEST_TIMEOUT,
         } = options;
-        const timedRequest = timed || asTimedRequest === true || options.timedRequestTimeoutMs !== undefined;
+        const timedRequest = timed || asTimedRequest === true || options.timedRequestTimeout !== undefined;
 
         if (this.isGroupAddress) {
             if (timed) {
@@ -1336,7 +1338,7 @@ export class InteractionClient {
 
         await this.withMessenger<void>(async messenger => {
             if (timedRequest) {
-                await messenger.sendTimedRequest(timedRequestTimeoutMs);
+                await messenger.sendTimedRequest(timedRequestTimeout);
             }
 
             const response = await messenger.sendInvokeCommand({

package/src/interaction/InteractionMessenger.ts

@@ -8,9 +8,11 @@ import { ReadResult } from "#action/response/ReadResult.js";
 import {
     Bytes,
     Diagnostic,
+    Duration,
     InternalError,
     Logger,
     MatterFlowError,
+    Millis,
     NoResponseTimeoutError,
     UnexpectedDataError,
 } from "#general";
@@ -120,7 +122,7 @@ class InteractionMessenger {
 
     async waitForSuccess(
         expectedMessageInfo: string,
-        options?: { expectedProcessingTimeMs?: number; timeoutMs?: number },
+        options?: { expectedProcessingTime?: Duration; timeout?: Duration },
     ) {
         // If the status is not Success, this would throw an Error.
         await this.nextMessage(MessageType.StatusResponse, options, `Success-${expectedMessageInfo}`);
@@ -129,8 +131,8 @@ class InteractionMessenger {
     async nextMessage(
         expectedMessageType: number,
         options?: {
-            expectedProcessingTimeMs?: number;
-            timeoutMs?: number;
+            expectedProcessingTime?: Duration;
+            timeout?: Duration;
         },
         expectedMessageInfo?: string,
     ) {
@@ -140,8 +142,8 @@ class InteractionMessenger {
     async anyNextMessage(
         expectedMessageInfo: string,
         options?: {
-            expectedProcessingTimeMs?: number;
-            timeoutMs?: number;
+            expectedProcessingTime?: Duration;
+            timeout?: Duration;
         },
     ) {
         return this.#nextMessage(undefined, options, expectedMessageInfo);
@@ -150,13 +152,13 @@ class InteractionMessenger {
     async #nextMessage(
         expectedMessageType?: number,
         options?: {
-            expectedProcessingTimeMs?: number;
-            timeoutMs?: number;
+            expectedProcessingTime?: Duration;
+            timeout?: Duration;
         },
         expectedMessageInfo?: string,
     ) {
-        const { expectedProcessingTimeMs, timeoutMs } = options ?? {};
-        const message = await this.exchange.nextMessage({ expectedProcessingTimeMs, timeoutMs });
+        const { expectedProcessingTime, timeout } = options ?? {};
+        const message = await this.exchange.nextMessage({ expectedProcessingTime, timeout });
         const messageType = message.payloadHeader.messageType;
         if (expectedMessageType !== undefined && expectedMessageInfo === undefined) {
             expectedMessageInfo = MessageType[expectedMessageType];
@@ -697,7 +699,7 @@ export class InteractionServerMessenger extends InteractionMessenger {
                 logContext,
             });
             // We wait for a Success Message - when we don't request an Ack only wait 500ms
-            await this.waitForSuccess("DataReport", { timeoutMs: waitForAck ? undefined : 500 });
+            await this.waitForSuccess("DataReport", { timeout: waitForAck ? undefined : Millis(500) });
         }
     }
 
@@ -778,8 +780,8 @@ export class InteractionServerMessenger extends InteractionMessenger {
 }
 
 export class IncomingInteractionClientMessenger extends InteractionMessenger {
-    async waitFor(expectedMessageInfo: string, messageType: number, timeoutMs?: number) {
-        const message = await this.anyNextMessage(expectedMessageInfo, { timeoutMs });
+    async waitFor(expectedMessageInfo: string, messageType: number, timeout?: Duration) {
+        const message = await this.anyNextMessage(expectedMessageInfo, { timeout });
         const {
             payloadHeader: { messageType: receivedMessageType },
         } = message;
@@ -1031,13 +1033,13 @@ export class InteractionClientMessenger extends IncomingInteractionClientMesseng
         };
     }
 
-    async sendInvokeCommand(invokeRequest: InvokeRequest, expectedProcessingTimeMs?: number) {
+    async sendInvokeCommand(invokeRequest: InvokeRequest, expectedProcessingTime?: Duration) {
         if (invokeRequest.suppressResponse) {
             await this.requestWithSuppressedResponse(
                 MessageType.InvokeRequest,
                 TlvInvokeRequest,
                 invokeRequest,
-                expectedProcessingTimeMs,
+                expectedProcessingTime,
             );
         } else {
             return await this.request(
@@ -1046,7 +1048,7 @@ export class InteractionClientMessenger extends IncomingInteractionClientMesseng
                 MessageType.InvokeResponse,
                 TlvInvokeResponse,
                 invokeRequest,
-                expectedProcessingTimeMs,
+                expectedProcessingTime,
             );
         }
     }
@@ -1065,9 +1067,9 @@ export class InteractionClientMessenger extends IncomingInteractionClientMesseng
         }
     }
 
-    sendTimedRequest(timeoutSeconds: number) {
+    sendTimedRequest(timeout: Duration) {
         return this.request(MessageType.TimedRequest, TlvTimedRequest, MessageType.StatusResponse, TlvStatusResponse, {
-            timeout: timeoutSeconds,
+            timeout,
             interactionModelRevision: Specification.INTERACTION_MODEL_REVISION,
         });
     }
@@ -1076,11 +1078,11 @@ export class InteractionClientMessenger extends IncomingInteractionClientMesseng
         requestMessageType: number,
         requestSchema: TlvSchema<RequestT>,
         request: RequestT,
-        expectedProcessingTimeMs?: number,
+        expectedProcessingTime?: Duration,
     ): Promise<void> {
         await this.send(requestMessageType, requestSchema.encode(request), {
             expectAckOnly: true,
-            expectedProcessingTimeMs,
+            expectedProcessingTime: expectedProcessingTime,
             logContext: {
                 invokeFlags: Diagnostic.asFlags({
                     suppressResponse: true,
@@ -1095,15 +1097,15 @@ export class InteractionClientMessenger extends IncomingInteractionClientMesseng
         responseMessageType: number,
         responseSchema: TlvSchema<ResponseT>,
         request: RequestT,
-        expectedProcessingTimeMs?: number,
+        expectedProcessingTime?: Duration,
     ): Promise<ResponseT> {
         await this.send(requestMessageType, requestSchema.encode(request), {
             expectAckOnly: false,
-            expectedProcessingTimeMs,
+            expectedProcessingTime,
         });
         const responseMessage = await this.nextMessage(
             responseMessageType,
-            { expectedProcessingTimeMs },
+            { expectedProcessingTime },
             MessageType[responseMessageType] ?? `Response-${Diagnostic.hex(responseMessageType)}`,
         );
         return responseSchema.decode(responseMessage.payload);

package/src/interaction/Subscription.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { AsyncObservable, InternalError, Logger } from "#general";
+import { AsyncObservable, Duration, InternalError, Logger } from "#general";
 import { NodeSession } from "#session/NodeSession.js";
 import { TlvAttributePath, TlvDataVersionFilter, TlvEventFilter, TlvEventPath, TypeFromSchema } from "#types";
 
@@ -30,7 +30,7 @@ export abstract class Subscription {
     #isCanceledByPeer?: boolean;
     #criteria: SubscriptionCriteria;
     #cancelled = AsyncObservable<[subscription: Subscription]>();
-    #maxIntervalMs?: number;
+    #maxInterval?: Duration;
 
     constructor(session: NodeSession, id: SubscriptionId, criteria: SubscriptionCriteria) {
         this.#session = session;
@@ -62,22 +62,18 @@ export abstract class Subscription {
         return this.#cancelled;
     }
 
-    get maxIntervalMs(): number {
-        if (this.#maxIntervalMs === undefined) {
-            throw new InternalError("Subscription MaxIntervalMs accessed before it was set");
+    get maxInterval() {
+        if (this.#maxInterval === undefined) {
+            throw new InternalError("Subscription maxInterval accessed before it was set");
         }
-        return this.#maxIntervalMs;
+        return this.#maxInterval;
     }
 
-    set maxIntervalMs(value: number) {
-        if (this.#maxIntervalMs !== undefined) {
-            throw new InternalError("Subscription MaxIntervalMs set twice. This should never happen.");
+    set maxInterval(value: Duration) {
+        if (this.#maxInterval !== undefined) {
+            throw new InternalError("Subscription maxInterval set twice");
         }
-        this.#maxIntervalMs = value;
-    }
-
-    get maxInterval(): number {
-        return Math.ceil(this.maxIntervalMs / 1000);
+        this.#maxInterval = value;
     }
 
     /**

package/src/interaction/SubscriptionClient.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Environment, Environmental, Logger, MaybePromise, Time, Timer } from "#general";
+import { Duration, Environment, Environmental, Logger, MaybePromise, Millis, Time, Timer } from "#general";
 import { MessageExchange } from "#protocol/MessageExchange.js";
 import { ProtocolHandler } from "#protocol/ProtocolHandler.js";
 import { INTERACTION_PROTOCOL_ID } from "#types";
@@ -14,8 +14,8 @@ const logger = Logger.get("SubscriptionClient");
 
 export interface RegisteredSubscription {
     id: number;
-    maximumPeerResponseTimeMs: number;
-    maxIntervalS: number;
+    maximumPeerResponseTime: Duration;
+    maxInterval: Duration;
     onData: (dataReport: DataReport) => MaybePromise<void>;
     onTimeout?: () => void;
 }
@@ -53,10 +53,10 @@ export class SubscriptionClient implements ProtocolHandler {
                 this.#timeouts.delete(id);
             }
 
-            const maxIntervalMs = subscription.maxIntervalS * 1000 + subscription.maximumPeerResponseTimeMs;
+            const maxInterval = Millis(subscription.maxInterval + subscription.maximumPeerResponseTime);
 
-            timer = Time.getTimer("Subscription timeout", maxIntervalMs, () => {
-                logger.info(`Subscription ${id} timed out after ${maxIntervalMs}ms`);
+            timer = Time.getTimer("Subscription timeout", maxInterval, () => {
+                logger.info(`Subscription ${id} timed out after ${Duration.format(maxInterval)}`);
                 this.delete(id);
                 onTimeout();
             }).start();