@matter/protocol 0.16.0-alpha.0-20251030-e9ca79f93 → 0.16.0-alpha.0-20251101-70c8d51d7

package/src/action/client/ClientInteraction.ts

@@ -12,33 +12,37 @@ import { Subscribe } from "#action/request/Subscribe.js";
 import { Write } from "#action/request/Write.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 {
+    Abort,
     BasicSet,
     Diagnostic,
     Duration,
+    Entropy,
     Environment,
-    Environmental,
     ImplementationError,
     isObject,
     Logger,
-    PromiseQueue,
+    RetrySchedule,
     Seconds,
 } from "#general";
 import { InteractionClientMessenger, MessageType } from "#interaction/InteractionMessenger.js";
-import { InteractionQueue } from "#peer/InteractionQueue.js";
 import { ExchangeProvider } from "#protocol/ExchangeProvider.js";
+import { SecureSession } from "#session/SecureSession.js";
 import { Status, TlvNoResponse, TlvSubscribeResponse } from "#types";
-import { ClientSubscriptions } from "./ClientSubscriptions.js";
 import { InputChunk } from "./InputChunk.js";
+import { ClientSubscribe } from "./subscription/ClientSubscribe.js";
+import { ClientSubscription } from "./subscription/ClientSubscription.js";
+import { ClientSubscriptions } from "./subscription/ClientSubscriptions.js";
+import { PeerSubscription } from "./subscription/PeerSubscription.js";
+import { SustainedSubscription } from "./subscription/SustainedSubscription.js";
 
 const logger = Logger.get("ClientInteraction");
 
 export interface ClientInteractionContext {
-    exchanges: ExchangeProvider;
-    subscriptions: ClientSubscriptions;
-    queue: PromiseQueue;
+    environment: Environment;
+    abort?: Abort.Signal;
+    sustainRetries?: RetrySchedule.Configuration;
 }
 
 export const DEFAULT_MIN_INTERVAL_FLOOR = Seconds(1);
@@ -54,18 +58,22 @@ export class ClientInteraction<SessionT extends InteractionSession = Interaction
 {
     readonly #exchanges: ExchangeProvider;
     readonly #subscriptions: ClientSubscriptions;
-    readonly #queue?: PromiseQueue;
     readonly #interactions = new BasicSet<Read | Write | Invoke | Subscribe>();
-    #closed = false;
-
-    constructor(context: ClientInteractionContext) {
-        this.#exchanges = context.exchanges;
-        this.#subscriptions = context.subscriptions;
-        this.#queue = context.queue;
+    readonly #abort;
+    readonly #sustainRetries: RetrySchedule;
+
+    constructor({ environment, abort, sustainRetries }: ClientInteractionContext) {
+        this.#exchanges = environment.get(ExchangeProvider);
+        this.#subscriptions = environment.get(ClientSubscriptions);
+        this.#abort = Abort.subtask(abort);
+        this.#sustainRetries = new RetrySchedule(
+            environment.get(Entropy),
+            RetrySchedule.Configuration(SustainedSubscription.DefaultRetrySchedule, sustainRetries),
+        );
     }
 
     async close() {
-        this.#closed = true;
+        this.#abort();
 
         while (this.#interactions.size) {
             await this.#interactions.deleted;
@@ -76,21 +84,10 @@ export class ClientInteraction<SessionT extends InteractionSession = Interaction
         return this.#subscriptions;
     }
 
-    get queue() {
-        return this.#queue;
-    }
-
-    static [Environmental.create](env: Environment) {
-        const instance = new ClientInteraction({
-            exchanges: env.get(ExchangeProvider),
-            subscriptions: env.get(ClientSubscriptions),
-            queue: env.get(InteractionQueue),
-        });
-        env.set(ClientInteraction, instance);
-        return instance;
-    }
-
-    async *read(request: Read, _session?: SessionT): ReadResult {
+    /**
+     * Read attributes and events.
+     */
+    async *read(request: Read, session?: SessionT): ReadResult {
         const readPathsCount = (request.attributeRequests?.length ?? 0) + (request.eventRequests?.length ?? 0);
         if (readPathsCount > 9) {
             logger.debug(
@@ -98,215 +95,209 @@ export class ClientInteraction<SessionT extends InteractionSession = Interaction
             );
         }
 
-        this.#begin(request);
-
-        let messenger: undefined | InteractionClientMessenger;
-        try {
-            messenger = await InteractionClientMessenger.create(this.#exchanges);
-
-            logger.debug("Read »", messenger.exchange.via, request);
-            await messenger.sendReadRequest(request);
+        await using context = await this.#begin(request, session);
+        const { checkAbort, messenger } = context;
 
-            let attributeReportCount = 0;
-            let eventReportCount = 0;
+        logger.debug("Read »", messenger.exchange.via, request);
+        await messenger.sendReadRequest(request);
+        checkAbort();
 
-            for await (const report of messenger.readDataReports()) {
-                attributeReportCount += report.attributeReports?.length ?? 0;
-                eventReportCount += report.eventReports?.length ?? 0;
-                yield InputChunk(report);
-            }
+        let attributeReportCount = 0;
+        let eventReportCount = 0;
 
-            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);
+        for await (const report of messenger.readDataReports()) {
+            checkAbort();
+            attributeReportCount += report.attributeReports?.length ?? 0;
+            eventReportCount += report.eventReports?.length ?? 0;
+            yield InputChunk(report);
+            checkAbort();
         }
+
+        logger.debug(
+            "Read «",
+            messenger.exchange.via,
+            Diagnostic.weak(
+                attributeReportCount + eventReportCount === 0
+                    ? "(empty)"
+                    : Diagnostic.dict({ attributes: attributeReportCount, events: eventReportCount }),
+            ),
+        );
     }
 
     /**
-     * Write chosen attributes remotely to the node.
-     * The returned attribute write status information is returned. No error is thrown for individual attribute write
-     * failures.
+     * Update node attributes.
+     *
+     * Writes with the Matter protocol are generally not atomic, so this method only throws if the entire action fails.
+     * You must check each {@link WriteResult.AttributeStatus} to determine whether individual updates failed.
      */
-    async write<T extends Write>(request: T, _session?: SessionT): WriteResult<T> {
-        this.#begin(request);
-
-        let messenger: undefined | InteractionClientMessenger;
-        try {
-            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 [] as Awaited<WriteResult<T>>;
-            }
+    async write<T extends Write>(request: T, session?: SessionT): WriteResult<T> {
+        await using context = await this.#begin(request, session);
+        const { checkAbort, messenger } = context;
 
-            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,
-                            endpointId: endpointId!,
-                            clusterId: clusterId!,
-                            attributeId: attributeId!,
-                            listIndex,
-                        },
-                        status,
-                        clusterStatus,
-                    };
-                },
-            ) as Awaited<WriteResult<T>>;
+        if (request.timedRequest) {
+            await messenger.sendTimedRequest(request.timeout ?? DEFAULT_TIMED_REQUEST_TIMEOUT);
+            checkAbort();
+        }
 
-            logger.info(
-                "Write «",
-                messenger.exchange.via,
-                Diagnostic.weak(
-                    successCount + failureCount === 0
-                        ? "(empty)"
-                        : Diagnostic.dict({ success: successCount, failure: failureCount }),
-                ),
-            );
+        logger.info("Write »", messenger.exchange.via, request);
 
-            return result;
-        } finally {
-            await messenger?.close();
-            this.#end(request);
+        const response = await messenger.sendWriteCommand(request);
+        checkAbort();
+        if (request.suppressResponse) {
+            return undefined as Awaited<WriteResult<T>>;
+        }
+        if (!response || !response.writeResponses?.length) {
+            return [] as Awaited<WriteResult<T>>;
         }
-    }
-
-    async *invoke(request: ClientInvoke, _session?: SessionT): DecodedInvokeResult {
-        this.#begin(request);
 
-        let messenger: InteractionClientMessenger | undefined;
-        try {
-            messenger = await InteractionClientMessenger.create(this.#exchanges);
+        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,
+                        endpointId: endpointId!,
+                        clusterId: clusterId!,
+                        attributeId: attributeId!,
+                        listIndex,
+                    },
+                    status,
+                    clusterStatus,
+                };
+            },
+        ) as Awaited<WriteResult<T>>;
+
+        logger.info(
+            "Write «",
+            messenger.exchange.via,
+            Diagnostic.weak(
+                successCount + failureCount === 0
+                    ? "(empty)"
+                    : Diagnostic.dict({ success: successCount, failure: failureCount }),
+            ),
+        );
+
+        return result;
+    }
 
-            if (request.timedRequest) {
-                await messenger.sendTimedRequest(request.timeout ?? DEFAULT_TIMED_REQUEST_TIMEOUT);
-            }
+    /**
+     * Invoke one or more commands.
+     */
+    async *invoke(request: ClientInvoke, session?: SessionT): DecodedInvokeResult {
+        await using context = await this.#begin(request, session);
+        const { checkAbort, messenger } = context;
 
-            logger.info(
-                "Invoke »",
-                messenger.exchange.via,
-                Diagnostic.asFlags({ suppressResponse: request.suppressResponse, timed: request.timedRequest }),
-                request,
-            );
+        if (request.timedRequest) {
+            await messenger.sendTimedRequest(request.timeout ?? DEFAULT_TIMED_REQUEST_TIMEOUT);
+            checkAbort();
+        }
 
-            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
-                        .map(response => {
-                            if (response.command !== undefined) {
-                                const {
-                                    commandPath: { endpointId, clusterId, commandId },
-                                    commandRef,
-                                    commandFields,
-                                } = response.command;
-                                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)"),
+        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),
+        );
+        checkAbort();
+        if (!request.suppressResponse) {
+            if (result && result.invokeResponses?.length) {
+                const chunk: InvokeResult.Chunk = result.invokeResponses
+                    .map(response => {
+                        if (response.command !== undefined) {
+                            const {
+                                commandPath: { endpointId, clusterId, commandId },
+                                commandRef,
+                                commandFields,
+                            } = response.command;
+                            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 res: InvokeResult.DecodedCommandResponse = {
-                                    kind: "cmd-response",
-                                    path: {
-                                        endpointId: endpointId!,
-                                        clusterId,
-                                        commandId,
-                                    },
-                                    commandRef,
-                                    data,
-                                };
-                                return res;
-                            } else if (response.status !== undefined) {
-                                const {
-                                    commandPath: { endpointId, clusterId, commandId },
-                                    commandRef,
-                                    status: { status, clusterStatus },
-                                } = response.status;
-                                const res: InvokeResult.CommandStatus = {
-                                    kind: "cmd-status",
-                                    path: {
-                                        endpointId: endpointId!,
-                                        clusterId: clusterId,
-                                        commandId: commandId,
-                                    },
-                                    commandRef,
-                                    status,
-                                    clusterStatus,
-                                };
-                                return res;
-                            } else {
-                                // Should not happen but if we ignore the response?
-                                return undefined;
                             }
-                        })
-                        .filter(r => r !== undefined);
-                    yield chunk;
-                } else {
-                    yield [];
-                }
+                            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,
+                                    commandId,
+                                },
+                                commandRef,
+                                data,
+                            };
+                            return res;
+                        } else if (response.status !== undefined) {
+                            const {
+                                commandPath: { endpointId, clusterId, commandId },
+                                commandRef,
+                                status: { status, clusterStatus },
+                            } = response.status;
+                            const res: InvokeResult.CommandStatus = {
+                                kind: "cmd-status",
+                                path: {
+                                    endpointId: endpointId!,
+                                    clusterId: clusterId,
+                                    commandId: commandId,
+                                },
+                                commandRef,
+                                status,
+                                clusterStatus,
+                            };
+                            return res;
+                        } else {
+                            // Should not happen but if we ignore the response?
+                            return undefined;
+                        }
+                    })
+                    .filter(r => r !== undefined);
+                yield chunk;
+            } else {
+                yield [];
             }
-        } finally {
-            await messenger?.close();
-            this.#end(request);
+            checkAbort();
         }
     }
 
-    async subscribe(request: Subscribe, _session?: SessionT): SubscribeResult {
+    /**
+     * Subscribe to attribute values and events.
+     */
+    async subscribe(request: ClientSubscribe, session?: SessionT) {
         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.");
@@ -321,11 +312,12 @@ export class ClientInteraction<SessionT extends InteractionSession = Interaction
             }
         }
 
-        this.#begin(request);
+        SecureSession.assert(this.#exchanges.session);
+        const peer = this.#exchanges.session.peerAddress;
 
-        let messenger: undefined | InteractionClientMessenger;
-        try {
-            messenger = await InteractionClientMessenger.create(this.#exchanges);
+        const subscribe = async (request: ClientSubscribe) => {
+            await using context = await this.#begin(request, session);
+            const { checkAbort, messenger } = context;
 
             logger.info(
                 "Subscribe »",
@@ -343,8 +335,10 @@ export class ClientInteraction<SessionT extends InteractionSession = Interaction
                 maxIntervalCeilingSeconds: Seconds.of(DEFAULT_MIN_INTERVAL_FLOOR), // TODO use better max fallback
                 ...request,
             });
+            checkAbort();
 
             await this.#handleSubscriptionResponse(request, readChunks(messenger));
+            checkAbort();
 
             const responseMessage = await messenger.nextMessage(MessageType.SubscribeResponse);
             const response = TlvSubscribeResponse.decode(responseMessage.payload);
@@ -353,20 +347,40 @@ export class ClientInteraction<SessionT extends InteractionSession = Interaction
                 "Subscription successful «",
                 messenger.exchange.via,
                 Diagnostic.dict({
-                    subId: response.subscriptionId,
+                    id: response.subscriptionId,
                     interval: Duration.format(Seconds(response.maxInterval)),
                 }),
             );
 
-            return this.#subscriptions.add(request, response);
-        } finally {
-            await messenger?.close();
-            this.#end(request);
+            const subscription = new PeerSubscription({
+                request,
+                peer,
+                closed: () => this.#subscriptions.delete(subscription),
+                response,
+                abort: session?.abort,
+            });
+            this.#subscriptions.addPeer(subscription);
+
+            return subscription;
+        };
+
+        let subscription: ClientSubscription;
+        if (request.sustain) {
+            subscription = new SustainedSubscription({
+                subscribe,
+                peer,
+                closed: () => this.#subscriptions.delete(subscription),
+                request,
+                abort: session?.abort,
+                retries: this.#sustainRetries,
+            });
+        } else {
+            subscription = await subscribe(request);
         }
-    }
 
-    cancelSubscription(id: number) {
-        this.#subscriptions.get(id)?.close();
+        this.#subscriptions.addActive(subscription);
+
+        return subscription;
     }
 
     async #handleSubscriptionResponse(request: Subscribe, result: ReadResult) {
@@ -382,18 +396,42 @@ export class ClientInteraction<SessionT extends InteractionSession = Interaction
         }
     }
 
-    #begin(request: Read | Write | Invoke | Subscribe) {
-        if (this.#closed) {
+    async #begin(request: Read | Write | Invoke | Subscribe, session?: SessionT) {
+        if (this.#abort.aborted) {
             throw new ImplementationError("Client interaction unavailable after close");
         }
         this.#interactions.add(request);
-    }
 
-    #end(request: Read | Write | Invoke | Subscribe) {
-        this.#interactions.delete(request);
+        const checkAbort = Abort.checkerFor(session);
+
+        const messenger = await InteractionClientMessenger.create(this.#exchanges);
+
+        const context: RequestContext = {
+            checkAbort,
+            messenger,
+            [Symbol.asyncDispose]: async () => {
+                await messenger.close();
+                this.#interactions.delete(request);
+            },
+        };
+
+        try {
+            context.checkAbort();
+        } catch (e) {
+            await context[Symbol.asyncDispose]();
+        }
+
+        return context;
     }
 }
 
+interface RequestContext {
+    checkAbort(): void;
+    messenger: InteractionClientMessenger;
+
+    [Symbol.asyncDispose](): Promise<void>;
+}
+
 async function* readChunks(messenger: InteractionClientMessenger) {
     for await (const report of messenger.readDataReports()) {
         yield InputChunk(report);

package/src/action/client/index.ts

@@ -5,8 +5,6 @@
  */
 
 export * from "./ClientInteraction.js";
-export * from "./ClientSubscription.js";
-export * from "./ClientSubscriptionHandler.js";
-export * from "./ClientSubscriptions.js";
 export * from "./InputChunk.js";
 export * from "./ReadScope.js";
+export * from "./subscription/index.js";

package/src/action/client/subscription/ClientSubscribe.ts

@@ -0,0 +1,8 @@
+import { Subscribe } from "#action/request/Subscribe.js";
+
+export interface ClientSubscribe extends Subscribe {
+    /**
+     * If true the subscription is virtualized and the underlying subscription is reestablished when lost.
+     */
+    sustain?: boolean;
+}