@matter/protocol 0.15.1 → 0.15.2-alpha.0-20250704-2715344f0

package/src/action/client/ClientInteraction.ts

@@ -13,34 +13,48 @@ 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 { Environment, Environmental, NotImplementedError, PromiseQueue } from "#general";
-import { InteractionClientMessenger } from "#interaction/InteractionMessenger.js";
-import { SubscriptionClient } from "#interaction/SubscriptionClient.js";
+import { BasicSet, Environment, Environmental, ImplementationError, PromiseQueue } 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 { ClientSubscriptions } from "./ClientSubscriptions.js";
+import { InputChunk } from "./InputChunk.js";
 
-export interface ClientInteractableContext {
+export interface ClientInteractionContext {
     exchanges: ExchangeProvider;
-    subscriptions: SubscriptionClient;
+    subscriptions: ClientSubscriptions;
     queue: PromiseQueue;
 }
 
+export const DEFAULT_MIN_INTERVAL_FLOOR_SECONDS = 1;
+
 /**
- * This is a WIP and currently largely a stub.
+ * Client-side implementation of the Matter protocol.
  */
 export class ClientInteraction<SessionT extends InteractionSession = InteractionSession>
     implements Interactable<SessionT>
 {
     readonly #exchanges: ExchangeProvider;
-    readonly #subscriptions: SubscriptionClient;
+    readonly #subscriptions: ClientSubscriptions;
     readonly #queue?: PromiseQueue;
+    readonly #interactions = new BasicSet<Read | Write | Invoke | Subscribe>();
+    #closed = false;
 
-    constructor(context: ClientInteractableContext) {
+    constructor(context: ClientInteractionContext) {
         this.#exchanges = context.exchanges;
         this.#subscriptions = context.subscriptions;
         this.#queue = context.queue;
     }
 
+    async close() {
+        this.#closed = true;
+
+        while (this.#interactions.size) {
+            await this.#interactions.deleted;
+        }
+    }
+
     get subscriptions() {
         return this.#subscriptions;
     }
@@ -52,104 +66,178 @@ export class ClientInteraction<SessionT extends InteractionSession = Interaction
     static [Environmental.create](env: Environment) {
         const instance = new ClientInteraction({
             exchanges: env.get(ExchangeProvider),
-            subscriptions: env.get(SubscriptionClient),
+            subscriptions: env.get(ClientSubscriptions),
             queue: env.get(InteractionQueue),
         });
         env.set(ClientInteraction, instance);
         return instance;
     }
 
-    read(_request: Read, _session?: SessionT): ReadResult {
-        // TODO
-        throw new NotImplementedError();
+    async *read(request: Read, _session?: SessionT): ReadResult {
+        try {
+            this.#begin(request);
+            const messenger = await InteractionClientMessenger.create(this.#exchanges);
+
+            await messenger.sendReadRequest(request);
+
+            for await (const report of messenger.readDataReports()) {
+                yield InputChunk(report);
+            }
+        } finally {
+            this.#end(request);
+        }
     }
 
     async write<T extends Write>(request: T, _session?: SessionT): WriteResult<T> {
-        const messenger = await InteractionClientMessenger.create(this.#exchanges);
-        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 },
-                }) => ({
-                    kind: "attr-status",
-                    path: {
-                        nodeId,
-                        endpointId: endpointId!,
-                        clusterId: clusterId!,
-                        attributeId: attributeId!,
-                        listIndex,
-                    },
-                    status,
-                    clusterStatus,
-                }),
-            ) as Awaited<WriteResult<T>>;
+        let messenger: undefined | InteractionClientMessenger;
+        try {
+            this.#begin(request);
+            messenger = await InteractionClientMessenger.create(this.#exchanges);
+            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 },
+                    }) => ({
+                        kind: "attr-status",
+                        path: {
+                            nodeId,
+                            endpointId: endpointId!,
+                            clusterId: clusterId!,
+                            attributeId: attributeId!,
+                            listIndex,
+                        },
+                        status,
+                        clusterStatus,
+                    }),
+                ) as Awaited<WriteResult<T>>;
+            }
+        } finally {
+            await messenger?.close();
+            this.#end(request);
         }
     }
 
     async *invoke(request: Invoke, _session?: SessionT): InvokeResult {
-        const messenger = await InteractionClientMessenger.create(this.#exchanges);
-        const result = await messenger.sendInvokeCommand(request);
-        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 res: InvokeResult.CommandResponse = {
-                                kind: "cmd-response",
-                                path: {
-                                    endpointId: endpointId!,
-                                    clusterId: clusterId,
-                                    commandId: commandId,
-                                },
-                                commandRef,
-                                data: commandFields!, // TODO add decoding
-                            };
-                            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 [];
+        let messenger: undefined | InteractionClientMessenger;
+        try {
+            this.#begin(request);
+            messenger = await InteractionClientMessenger.create(this.#exchanges);
+            const result = await messenger.sendInvokeCommand(request);
+            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 res: InvokeResult.CommandResponse = {
+                                    kind: "cmd-response",
+                                    path: {
+                                        endpointId: endpointId!,
+                                        clusterId: clusterId,
+                                        commandId: commandId,
+                                    },
+                                    commandRef,
+                                    data: commandFields!, // TODO add decoding
+                                };
+                                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);
         }
     }
 
-    subscribe(_request: Subscribe, _session?: SessionT): SubscribeResult {
-        // TODO
-        throw new NotImplementedError();
+    async subscribe(request: Subscribe, _session?: SessionT): SubscribeResult {
+        let messenger: undefined | InteractionClientMessenger;
+        try {
+            this.#begin(request);
+
+            messenger = await InteractionClientMessenger.create(this.#exchanges);
+
+            await messenger.sendSubscribeRequest({
+                ...request,
+                minIntervalFloorSeconds: DEFAULT_MIN_INTERVAL_FLOOR_SECONDS,
+                maxIntervalCeilingSeconds: DEFAULT_MIN_INTERVAL_FLOOR_SECONDS,
+            });
+
+            await this.#handleSubscriptionResponse(request, readChunks(messenger));
+
+            const responseMessage = await messenger.nextMessage(MessageType.SubscribeResponse);
+            const response = TlvSubscribeResponse.decode(responseMessage.payload);
+
+            return this.#subscriptions.add(request, response);
+        } finally {
+            await messenger?.close();
+            this.#end(request);
+        }
+    }
+
+    async #handleSubscriptionResponse(request: Subscribe, result: ReadResult) {
+        if (request.updated) {
+            await request.updated(result);
+        } else {
+            // It doesn't really make sense to subscribe without listening to the result, but higher-level Interactables
+            // may process responses so the subscriber doesn't need to.  So "updated" may be omitted from the API, so
+            // we handle this case
+            //
+            // We need to await the generator or the interactable will hang
+            for await (const _chunk of result);
+        }
+    }
+
+    #begin(request: Read | Write | Invoke | Subscribe) {
+        if (this.#closed) {
+            throw new ImplementationError("Client interaction unavailable after close");
+        }
+        this.#interactions.add(request);
+    }
+
+    #end(request: Read | Write | Invoke | Subscribe) {
+        this.#interactions.delete(request);
+    }
+}
+
+async function* readChunks(messenger: InteractionClientMessenger) {
+    for await (const report of messenger.readDataReports()) {
+        yield InputChunk(report);
     }
 }

package/src/action/client/ClientSubscription.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Subscribe } from "#action/request/Subscribe.js";
+import { ActiveSubscription } from "#action/response/SubscribeResult.js";
+
+/**
+ * The client view of an established Matter subscription.
+ */
+export interface ClientSubscription extends ActiveSubscription {
+    request: Subscribe;
+    timeoutAtMs?: number;
+    isClosed: boolean;
+    isReading: boolean;
+}

package/src/action/client/ClientSubscriptionHandler.ts

@@ -0,0 +1,137 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ReadResult } from "#action/response/ReadResult.js";
+import { DecodedDataReport } from "#interaction/DecodedDataReport.js";
+import { IncomingInteractionClientMessenger } from "#interaction/InteractionMessenger.js";
+import { SubscriptionId } from "#interaction/Subscription.js";
+import { MessageExchange } from "#protocol/MessageExchange.js";
+import { ProtocolHandler } from "#protocol/ProtocolHandler.js";
+import { DataReport, INTERACTION_PROTOCOL_ID, Status } from "#types";
+import { Diagnostic, InternalError, Logger } from "@matter/general";
+import { ClientSubscriptions } from "./ClientSubscriptions.js";
+import { InputChunk } from "./InputChunk.js";
+
+const logger = Logger.get("ClientSubscriptionHandler");
+
+/**
+ * A protocol handler that informs {@link ClientSubscriptions} of new exchanges.
+ */
+export class ClientSubscriptionHandler implements ProtocolHandler {
+    id = INTERACTION_PROTOCOL_ID;
+    requiresSecureSession = true;
+
+    #subscriptions: ClientSubscriptions;
+
+    constructor(subscriptions: ClientSubscriptions) {
+        this.#subscriptions = subscriptions;
+    }
+
+    async onNewExchange(exchange: MessageExchange) {
+        const messenger = new IncomingInteractionClientMessenger(exchange);
+        // Read the initial report
+        const reports = messenger.readDataReports();
+
+        const initialIteration = await reports.next();
+        if (initialIteration.done) {
+            throw new InternalError("Exchange initiated with no initial message");
+        }
+        const initialReport = initialIteration.value;
+
+        // Ensure there is a subscription ID present
+        const { subscriptionId } = initialReport;
+        if (subscriptionId === undefined) {
+            logger.debug("Ignoring unsolicited data report with no subscription ID");
+            await sendInvalid(messenger, undefined);
+            return;
+        }
+
+        // Ensure the subscription ID is valid
+        const subscription = this.#subscriptions.get(subscriptionId);
+        if (subscription === undefined) {
+            logger.debug("Ignoring data report for unknown subscription ID", Diagnostic.strong(subscriptionId));
+            await sendInvalid(messenger, subscriptionId);
+            return;
+        }
+
+        // If this is just a ping, only reset the timeout
+        if (!initialReport.attributeReports?.length && !initialReport.eventReports?.length) {
+            subscription.timeoutAtMs = undefined;
+            this.#subscriptions.resetTimer();
+            await exchange.close();
+            return;
+        }
+
+        // Pass the data to the recipient
+        try {
+            subscription.isReading = true;
+
+            if (subscription.request.updated) {
+                await subscription.request.updated(processReports(initialReport, reports, messenger));
+            } else {
+                // It doesn't make sense to have the callback undefined but we allow it in the type because they may
+                // be handled by intermediate interactables.  So we handle the case here too, but just iterate and throw
+                // away the reports
+                for await (const _chunk of reports);
+            }
+        } finally {
+            subscription.isReading = false;
+            subscription.timeoutAtMs = undefined;
+            this.#subscriptions.resetTimer();
+            await exchange.close();
+        }
+    }
+
+    async close() {}
+}
+
+async function sendInvalid(messenger: IncomingInteractionClientMessenger, subscriptionId?: SubscriptionId) {
+    await messenger.sendStatus(Status.InvalidSubscription, {
+        multipleMessageInteraction: true,
+        logContext: {
+            subId: subscriptionId,
+        },
+    });
+    await messenger.close();
+}
+
+/**
+ * Convert incoming data reports into a {@link ReadResult}.
+ *
+ * Parses incoming reports and validates subscription IDs.
+ */
+async function* processReports(
+    initialReport: DataReport,
+    otherReports: AsyncIterable<DataReport>,
+    messenger: IncomingInteractionClientMessenger,
+): ReadResult {
+    yield InputChunk(initialReport);
+
+    const { subscriptionId } = initialReport;
+
+    for await (const report of otherReports) {
+        const decoded = DecodedDataReport(report);
+
+        if (decoded.subscriptionId === undefined) {
+            logger.debug(
+                "Ignoring data report for incorrect subscription id",
+                Diagnostic.strong(decoded.subscriptionId),
+            );
+            await sendInvalid(messenger, decoded.subscriptionId);
+        }
+
+        if (decoded.subscriptionId !== subscriptionId) {
+            logger.debug(
+                "Ignoring data report for incorrect subscription id",
+                Diagnostic.strong(decoded.subscriptionId),
+            );
+            await sendInvalid(messenger, decoded.subscriptionId);
+            continue;
+        }
+
+        yield InputChunk(report);
+    }
+}

package/src/action/client/ClientSubscriptions.ts

@@ -0,0 +1,172 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Subscribe } from "#action/request/Subscribe.js";
+import { ReadResult } from "#action/response/ReadResult.js";
+import { ActiveSubscription } from "#action/response/SubscribeResult.js";
+import {
+    BasicSet,
+    CanceledError,
+    Diagnostic,
+    Environment,
+    Environmental,
+    Logger,
+    Time,
+    TimeoutError,
+    Timer,
+} from "#general";
+import { SubscriptionId } from "#interaction/Subscription.js";
+import { SubscribeResponse } from "#types";
+import { ClientSubscription } from "./ClientSubscription.js";
+
+const logger = Logger.get("ClientSubscriptions");
+
+/**
+ * A managed set of {@link ClientSubscription} instances.
+ */
+export class ClientSubscriptions {
+    #subscriptions = new BasicSet<ClientSubscription>();
+    #timeout?: Timer;
+    #nextTimeoutAt?: number;
+
+    static [Environmental.create](env: Environment) {
+        const instance = new ClientSubscriptions();
+        env.set(ClientSubscriptions, instance);
+        return instance;
+    }
+
+    /**
+     * Register an active subscription.
+     */
+    add(request: Subscribe, response: SubscribeResponse): ActiveSubscription {
+        const subscription: ClientSubscription = {
+            ...response,
+            request,
+            close: () => this.#closeOne(subscription, new CanceledError()),
+            timeoutAtMs: undefined,
+            isClosed: false,
+            isReading: true,
+        };
+
+        this.#subscriptions.add(subscription);
+        this.resetTimer();
+
+        return subscription;
+    }
+
+    /**
+     * Retrieve a subscription by ID.
+     */
+    get(id: SubscriptionId) {
+        return this.#subscriptions.get("subscriptionId", id);
+    }
+
+    /**
+     * Iterate over active subscriptions.
+     */
+    [Symbol.iterator]() {
+        return this.#subscriptions[Symbol.iterator]();
+    }
+
+    /**
+     * Terminate all subscriptions.
+     */
+    async close() {
+        if (this.#timeout) {
+            this.#timeout.stop();
+            this.#timeout = undefined;
+        }
+        for (const subscription of this.#subscriptions) {
+            subscription.close();
+        }
+    }
+
+    /**
+     * Restart the timeout timer for the current set of active subscriptions.
+     */
+    resetTimer() {
+        const now = Time.nowMs();
+        let nextTimeoutAt: number | undefined;
+
+        // Process each subscription
+        for (const subscription of this.#subscriptions) {
+            // If reading data reports, ignore for timeout purposes
+            if (subscription.isReading) {
+                continue;
+            }
+
+            // Update timeout or expire if timed out
+            let { timeoutAtMs } = subscription;
+            if (timeoutAtMs === undefined) {
+                // Set timeout time
+                timeoutAtMs = subscription.timeoutAtMs = timeoutFor(subscription);
+            } else if (timeoutAtMs < now) {
+                // Timeout
+                this.#timeOut(subscription);
+                continue;
+            }
+
+            // If this is the earliest timeout, record
+            if (nextTimeoutAt === undefined || nextTimeoutAt > timeoutAtMs) {
+                nextTimeoutAt = timeoutAtMs;
+            }
+        }
+
+        // If no subscriptions require timeout, disable timer
+        if (nextTimeoutAt === undefined) {
+            this.#nextTimeoutAt = undefined;
+            this.#timeout?.stop();
+            return;
+        }
+
+        // Create or update timer if not set for correct interval
+        if (nextTimeoutAt !== this.#nextTimeoutAt) {
+            this.#nextTimeoutAt = nextTimeoutAt;
+            if (this.#timeout) {
+                this.#timeout?.stop();
+                this.#timeout.intervalMs = nextTimeoutAt - now;
+            } else {
+                this.#timeout = Time.getTimer("SubscriptionTimeout", nextTimeoutAt - now, this.resetTimer.bind(this));
+            }
+        }
+    }
+
+    #closeOne(subscription: ClientSubscription, cause: CanceledError | TimeoutError) {
+        if (subscription.isClosed) {
+            return;
+        }
+        subscription.isClosed = true;
+        this.#subscriptions.delete(subscription);
+
+        try {
+            subscription.request.closed?.(cause);
+        } catch (e) {
+            logger.error("Error canceling subscription", Diagnostic.strong(subscription.subscriptionId), e);
+        }
+    }
+
+    #timeOut(registration: ClientSubscription) {
+        logger.info(
+            "Subscription",
+            Diagnostic.strong(registration.subscriptionId),
+            "timed out after",
+            Diagnostic.strong(`${timeoutFor(registration)}ms`),
+        );
+
+        // TODO - rather than closing, put into dormant state and resubscribe when connection reestablishes
+        this.#closeOne(registration, new TimeoutError());
+    }
+}
+
+function timeoutFor(subscription: ClientSubscription) {
+    return subscription.maxInterval * 1000 + (subscription.request.maxPeerResponseTime ?? 0);
+}
+
+export namespace ClientSubscriptions {
+    export interface Listener {
+        (reports: AsyncIterable<ReadResult.Chunk>): Promise<void>;
+    }
+}