@matter/protocol 0.12.4-alpha.0-20250223-1e0341a1a → 0.12.4-alpha.0-20250224-46934b522

package/src/interaction/InteractionMessenger.ts

@@ -18,11 +18,9 @@ import {
     StatusCode,
     StatusResponseError,
     TlvAny,
-    TlvAttributeReport,
     TlvDataReport,
     TlvDataReportForSend,
     TlvDataVersionFilter,
-    TlvEventReport,
     TlvInvokeRequest,
     TlvInvokeResponse,
     TlvReadRequest,
@@ -693,15 +691,10 @@ export class IncomingInteractionClientMessenger extends InteractionMessenger {
         return message;
     }
 
-    // TODO: Adjust to use callbacks or events to push put received data to allow parallel processing
-    async readDataReports(expectedSubscriptionIds?: number[]): Promise<DataReport> {
-        let subscriptionId: number | undefined;
-        const attributeValues: TypeFromSchema<typeof TlvAttributeReport>[] = [];
-        const eventValues: TypeFromSchema<typeof TlvEventReport>[] = [];
+    async readAggregateDataReport(expectedSubscriptionIds?: number[]): Promise<DataReport> {
+        let result: DataReport | undefined;
 
-        while (true) {
-            const dataReportMessage = await this.waitFor("DataReport", MessageType.ReportData);
-            const report = TlvDataReport.decode(dataReportMessage.payload);
+        for await (const report of this.readDataReports()) {
             if (expectedSubscriptionIds !== undefined) {
                 if (report.subscriptionId === undefined || !expectedSubscriptionIds.includes(report.subscriptionId)) {
                     await this.sendStatus(StatusCode.InvalidSubscription, {
@@ -718,56 +711,82 @@ export class IncomingInteractionClientMessenger extends InteractionMessenger {
                 }
             }
 
-            if (subscriptionId === undefined && report.subscriptionId !== undefined) {
-                subscriptionId = report.subscriptionId;
-            } else if (
-                (subscriptionId !== undefined || report.subscriptionId !== undefined) &&
-                report.subscriptionId !== subscriptionId
-            ) {
+            if (result?.subscriptionId !== undefined && report.subscriptionId !== result.subscriptionId) {
                 throw new UnexpectedDataError(`Invalid subscription ID ${report.subscriptionId} received`);
             }
 
-            const logContext = {
-                subId: report.subscriptionId,
-                dataReportFlags: Diagnostic.asFlags({
-                    empty: !report.attributeReports?.length && !report.eventReports?.length,
-                    suppressResponse: report.suppressResponse,
-                    moreChunkedMessages: report.moreChunkedMessages,
-                }),
-                attr: report.attributeReports?.length,
-                ev: report.eventReports?.length,
-            };
-
-            if (Array.isArray(report.attributeReports) && report.attributeReports.length > 0) {
-                attributeValues.push(...report.attributeReports);
-            }
-            if (Array.isArray(report.eventReports) && report.eventReports.length > 0) {
-                eventValues.push(...report.eventReports);
+            if (!result) {
+                result = report;
+            } else {
+                if (Array.isArray(report.attributeReports)) {
+                    if (!result.attributeReports) {
+                        result.attributeReports = report.attributeReports;
+                    } else {
+                        result.attributeReports.push(...report.attributeReports);
+                    }
+                }
+                if (Array.isArray(report.eventReports)) {
+                    if (!result.eventReports) {
+                        result.eventReports = report.eventReports;
+                    } else {
+                        result.eventReports.push(...report.eventReports);
+                    }
+                }
             }
+        }
+
+        if (result === undefined) {
+            // readDataReports should have thrown
+            throw new InternalError("No data reports loaded during read");
+        }
+
+        return result;
+    }
+
+    /**
+     * Read data reports as they come in on the wire.
+     *
+     * Data reports payloads are decoded but list attributes may be split across messages; these will require reassembly.
+     */
+    async *readDataReports() {
+        while (true) {
+            const dataReportMessage = await this.waitFor("DataReport", MessageType.ReportData);
+            const report = TlvDataReport.decode(dataReportMessage.payload);
+
+            yield report;
 
             if (report.moreChunkedMessages) {
                 await this.sendStatus(StatusCode.Success, {
                     multipleMessageInteraction: true,
-                    logContext,
+                    logContext: this.#logContextOf(report),
                 });
             } else if (!report.suppressResponse) {
-                // We received the last message and need to send a final Success, but we do not need to wait for it and
+                // We received the last message and need to send a final success, but we do not need to wait for it and
                 // also don't care if it fails
                 this.sendStatus(StatusCode.Success, {
                     multipleMessageInteraction: true,
-                    logContext,
-                }).catch(error =>
-                    logger.info("Error while sending final Success after receiving all DataReport chunks", error),
-                );
+                    logContext: this.#logContextOf(report),
+                }).catch(error => logger.info("Error sending success after final data report chunk", error));
             }
 
             if (!report.moreChunkedMessages) {
-                report.attributeReports = attributeValues;
-                report.eventReports = eventValues;
-                return report;
+                break;
             }
         }
     }
+
+    #logContextOf(report: DataReport) {
+        return {
+            subId: report.subscriptionId,
+            dataReportFlags: Diagnostic.asFlags({
+                empty: !report.attributeReports?.length && !report.eventReports?.length,
+                suppressResponse: report.suppressResponse,
+                moreChunkedMessages: report.moreChunkedMessages,
+            }),
+            attr: report.attributeReports?.length,
+            ev: report.eventReports?.length,
+        };
+    }
 }
 
 export class InteractionClientMessenger extends IncomingInteractionClientMessenger {
@@ -793,6 +812,7 @@ export class InteractionClientMessenger extends IncomingInteractionClientMesseng
             return await this.exchange.send(messageType, payload, options);
         } catch (error) {
             if (
+                this.exchangeProvider.supportsReconnect &&
                 (error instanceof RetransmissionLimitReachedError || error instanceof ChannelNotConnectedError) &&
                 !options?.multipleMessageInteraction
             ) {
@@ -815,7 +835,7 @@ export class InteractionClientMessenger extends IncomingInteractionClientMesseng
     async sendReadRequest(readRequest: ReadRequest) {
         await this.send(MessageType.ReadRequest, this.#encodeReadingRequest(TlvReadRequest, readRequest));
 
-        return this.readDataReports();
+        return this.readAggregateDataReport();
     }
 
     #encodeReadingRequest<T extends TlvSchema<any>>(schema: T, request: TypeFromSchema<T>) {
@@ -876,7 +896,7 @@ export class InteractionClientMessenger extends IncomingInteractionClientMesseng
         const request = this.#encodeReadingRequest(TlvSubscribeRequest, subscribeRequest);
         await this.send(MessageType.SubscribeRequest, request);
 
-        const report = await this.readDataReports();
+        const report = await this.readAggregateDataReport();
         const { subscriptionId } = report;
 
         if (subscriptionId === undefined) {

package/src/interaction/InteractionServer.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Crypto, Diagnostic, InternalError, Logger, MatterFlowError } from "#general";
+import { Crypto, Diagnostic, InternalError, Logger, MatterFlowError, Observable, ServerAddressIp } from "#general";
 import { AttributeModel, ClusterModel, CommandModel, GLOBAL_IDS, MatterModel, Specification } from "#model";
 import { PeerAddress } from "#peer/PeerAddress.js";
 import { SessionManager } from "#session/SessionManager.js";
@@ -67,6 +67,19 @@ import { ServerSubscriptionConfig } from "./SubscriptionOptions.js";
 
 const logger = Logger.get("InteractionServer");
 
+export interface PeerSubscription {
+    subscriptionId: number;
+    peerAddress: PeerAddress;
+    minIntervalFloorSeconds: number;
+    maxIntervalCeilingSeconds: number;
+    attributeRequests?: TypeFromSchema<typeof TlvAttributePath>[];
+    eventRequests?: TypeFromSchema<typeof TlvEventPath>[];
+    isFabricFiltered: boolean;
+    maxInterval: number;
+    sendInterval: number;
+    operationalAddress?: ServerAddressIp;
+}
+
 export interface CommandPath {
     nodeId?: NodeId;
     endpointId: EndpointNumber;
@@ -227,11 +240,14 @@ export interface InteractionContext {
  * Translates interactions from the Matter protocol to matter.js APIs.
  */
 export class InteractionServer implements ProtocolHandler, InteractionRecipient {
+    readonly id = INTERACTION_PROTOCOL_ID;
     #context: InteractionContext;
     #nextSubscriptionId = Crypto.getRandomUInt32();
     #isClosing = false;
+    #clientHandler?: ProtocolHandler;
     readonly #subscriptionConfig: ServerSubscriptionConfig;
     readonly #maxPathsPerInvoke;
+    readonly #subscriptionEstablishmentStarted = Observable<[peerAddress: PeerAddress]>();
 
     constructor(context: InteractionContext) {
         this.#context = context;
@@ -244,10 +260,6 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
         });
     }
 
-    getId() {
-        return INTERACTION_PROTOCOL_ID;
-    }
-
     protected get isClosing() {
         return this.#isClosing;
     }
@@ -256,13 +268,32 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
         return this.#maxPathsPerInvoke;
     }
 
-    async onNewExchange(exchange: MessageExchange) {
+    get subscriptionEstablishmentStarted() {
+        return this.#subscriptionEstablishmentStarted;
+    }
+
+    async onNewExchange(exchange: MessageExchange, message: Message) {
         // Note - changes here must be copied to TransactionalInteractionServer as it does not call super() to avoid
         // the stack frame
         if (this.#isClosing) return; // We are closing, ignore anything newly incoming
+
+        // An incoming data report as the first message is not a valid server operation.  We instead delegate to a
+        // client implementation if available
+        if (message.payloadHeader.messageType === MessageType.SubscribeRequest && this.#clientHandler) {
+            return this.#clientHandler.onNewExchange(exchange, message);
+        }
+
         await new InteractionServerMessenger(exchange).handleRequest(this);
     }
 
+    get clientHandler(): ProtocolHandler | undefined {
+        return this.#clientHandler;
+    }
+
+    set clientHandler(clientHandler: ProtocolHandler) {
+        this.#clientHandler = clientHandler;
+    }
+
     async #collectEventDataForRead(
         { eventRequests, eventFilters, isFabricFiltered }: ReadRequest,
         exchange: MessageExchange,
@@ -962,7 +993,11 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
 
     async handleSubscribeRequest(
         exchange: MessageExchange,
-        {
+        request: SubscribeRequest,
+        messenger: InteractionServerMessenger,
+        message: Message,
+    ): Promise<void> {
+        const {
             minIntervalFloorSeconds,
             maxIntervalCeilingSeconds,
             attributeRequests,
@@ -972,10 +1007,7 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
             keepSubscriptions,
             isFabricFiltered,
             interactionModelRevision,
-        }: SubscribeRequest,
-        messenger: InteractionServerMessenger,
-        message: Message,
-    ): Promise<void> {
+        } = request;
         logger.debug(
             `Received subscribe request from ${exchange.channel.name} (keepSubscriptions=${keepSubscriptions}, isFabricFiltered=${isFabricFiltered})`,
         );
@@ -1004,8 +1036,7 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
 
         if (!keepSubscriptions) {
             const clearedCount = await this.#context.sessions.clearSubscriptionsForNode(
-                fabric.fabricIndex,
-                session.peerNodeId,
+                fabric.addressOf(session.peerNodeId),
                 true,
             );
             if (clearedCount > 0) {
@@ -1071,6 +1102,71 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
         if (this.#nextSubscriptionId === 0xffffffff) this.#nextSubscriptionId = 0;
         const subscriptionId = this.#nextSubscriptionId++;
 
+        this.#subscriptionEstablishmentStarted.emit(session.peerAddress);
+        let subscription: ServerSubscription;
+        try {
+            subscription = await this.#establishSubscription(
+                subscriptionId,
+                request,
+                messenger,
+                session,
+                exchange,
+                message,
+            );
+        } catch (error: any) {
+            logger.error(
+                `Subscription ${subscriptionId} for Session ${session.id}: Error while sending initial data reports`,
+                error,
+            );
+            if (error instanceof StatusResponseError) {
+                logger.info(`Sending status response ${error.code} for interaction error: ${error.message}`);
+                await messenger.sendStatus(error.code, {
+                    logContext: {
+                        for: "I/SubscriptionSeed-Status",
+                    },
+                });
+            }
+            await messenger.close();
+            return; // Make sure to not bubble up the exception
+        }
+
+        const maxInterval = subscription.maxInterval;
+        // Then send the subscription response
+        await messenger.send(
+            MessageType.SubscribeResponse,
+            TlvSubscribeResponse.encode({
+                subscriptionId,
+                maxInterval,
+                interactionModelRevision: Specification.INTERACTION_MODEL_REVISION,
+            }),
+            {
+                logContext: {
+                    subId: subscriptionId,
+                    maxInterval,
+                },
+            },
+        );
+
+        // When an error occurs while sending the response, the subscription is not yet active and will be cleaned up by GC
+        subscription.activate();
+    }
+
+    async #establishSubscription(
+        id: number,
+        {
+            minIntervalFloorSeconds,
+            maxIntervalCeilingSeconds,
+            attributeRequests,
+            dataVersionFilters,
+            eventRequests,
+            eventFilters,
+            isFabricFiltered,
+        }: SubscribeRequest,
+        messenger: InteractionServerMessenger,
+        session: SecureSession,
+        exchange: MessageExchange,
+        message: Message,
+    ) {
         const context: ServerSubscriptionContext = {
             session,
             structure: this.#endpointStructure,
@@ -1088,7 +1184,7 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
         };
 
         const subscription = new ServerSubscription({
-            id: subscriptionId,
+            id,
             context,
             criteria: {
                 attributeRequests,
@@ -1097,56 +1193,86 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
                 eventFilters,
                 isFabricFiltered,
             },
-            minIntervalFloor: minIntervalFloorSeconds,
-            maxIntervalCeiling: maxIntervalCeilingSeconds,
+            minIntervalFloorSeconds,
+            maxIntervalCeilingSeconds,
             subscriptionOptions: this.#subscriptionConfig,
         });
 
         try {
             // Send initial data report to prime the subscription with initial data
             await subscription.sendInitialReport(messenger);
-        } catch (error: any) {
-            logger.error(
-                `Subscription ${subscriptionId} for Session ${session.id}: Error while sending initial data reports`,
-                error,
-            );
+        } catch (error) {
             await subscription.close(); // Cleanup
-            if (error instanceof StatusResponseError) {
-                logger.info(`Sending status response ${error.code} for interaction error: ${error.message}`);
-                await messenger.sendStatus(error.code, {
-                    logContext: {
-                        for: "I/SubscriptionSeed-Status",
-                    },
-                });
-            }
-            await messenger.close();
-            return; // Make sure to not bubble up the exception
+            throw error;
         }
 
-        const maxInterval = subscription.maxInterval;
         logger.info(
-            `Successfully created subscription ${subscriptionId} for Session ${
+            `Successfully created subscription ${id} for Session ${
                 session.id
-            }. Updates: ${minIntervalFloorSeconds} - ${maxIntervalCeilingSeconds} => ${maxInterval} seconds (sendInterval = ${subscription.sendInterval} seconds)`,
+            }. Updates: ${minIntervalFloorSeconds} - ${maxIntervalCeilingSeconds} => ${subscription.maxInterval} seconds (sendInterval = ${subscription.sendInterval} seconds)`,
         );
-        // Then send the subscription response
-        await messenger.send(
-            MessageType.SubscribeResponse,
-            TlvSubscribeResponse.encode({
-                subscriptionId,
-                maxInterval,
-                interactionModelRevision: Specification.INTERACTION_MODEL_REVISION,
-            }),
-            {
-                logContext: {
-                    subId: subscriptionId,
-                    maxInterval,
-                },
-            },
+        return subscription;
+    }
+
+    async establishFormerSubscription(
+        {
+            subscriptionId,
+            attributeRequests,
+            eventRequests,
+            isFabricFiltered,
+            minIntervalFloorSeconds,
+            maxIntervalCeilingSeconds,
+            maxInterval,
+            sendInterval,
+        }: PeerSubscription,
+        session: SecureSession,
+    ) {
+        const exchange = this.#context.initiateExchange(session.peerAddress, INTERACTION_PROTOCOL_ID);
+        const message = {} as Message;
+        logger.debug(
+            `Send DataReports to re-establish subscription ${subscriptionId} to `,
+            Diagnostic.dict({ isFabricFiltered, maxInterval, sendInterval }),
         );
+        const context: ServerSubscriptionContext = {
+            session,
+            structure: this.#endpointStructure,
 
-        // When an error occurs while sending the response, the subscription is not yet active and will be cleaned up by GC
-        subscription.activateSendingUpdates();
+            readAttribute: (path, attribute, offline) =>
+                this.readAttribute(path, attribute, exchange, isFabricFiltered, message, offline),
+
+            readEndpointAttributesForSubscription: attributes =>
+                this.readEndpointAttributesForSubscription(attributes, exchange, isFabricFiltered, message),
+
+            readEvent: (path, event, eventFilters) =>
+                this.readEvent(path, eventFilters, event, exchange, isFabricFiltered, message),
+
+            initiateExchange: (address: PeerAddress, protocolId) => this.#context.initiateExchange(address, protocolId),
+        };
+
+        const subscription = new ServerSubscription({
+            id: subscriptionId,
+            context,
+            minIntervalFloorSeconds,
+            maxIntervalCeilingSeconds,
+            criteria: {
+                attributeRequests,
+                eventRequests,
+                isFabricFiltered,
+            },
+            subscriptionOptions: this.#subscriptionConfig,
+            useAsMaxInterval: maxInterval,
+            useAsSendInterval: sendInterval,
+        });
+
+        try {
+            // Send initial data report to prime the subscription with initial data
+            await subscription.sendInitialReport(new InteractionServerMessenger(exchange));
+            subscription.activate();
+        } catch (error) {
+            await subscription.close(); // Cleanup
+            throw error;
+        }
+        return subscription;
     }
 
     async handleInvokeRequest(