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

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

@@ -227,9 +227,11 @@ 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;
 
@@ -244,10 +246,6 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
         });
     }
 
-    getId() {
-        return INTERACTION_PROTOCOL_ID;
-    }
-
     protected get isClosing() {
         return this.#isClosing;
     }
@@ -256,13 +254,28 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
         return this.#maxPathsPerInvoke;
     }
 
-    async onNewExchange(exchange: MessageExchange) {
+    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,

package/src/interaction/SubscriptionClient.ts

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MessageExchange } from "#protocol/MessageExchange.js";
+import { ProtocolHandler } from "#protocol/ProtocolHandler.js";
+import { Environment, Environmental, Logger, MaybePromise, Time, Timer } from "@matter/general";
+import { INTERACTION_PROTOCOL_ID } from "@matter/types";
+import { DataReport, IncomingInteractionClientMessenger } from "./InteractionMessenger.js";
+
+const logger = Logger.get("SubscriptionClient");
+
+export interface RegisteredSubscription {
+    id: number;
+    maximumPeerResponseTime: number;
+    maxIntervalS: number;
+    onData: (dataReport: DataReport) => MaybePromise<void>;
+    onTimeout?: () => void;
+}
+
+/**
+ * A simple protocol handler that handles exchanges starting with data reports.
+ *
+ * Incoming data reports must match to a subscription registered with {@link add} or the exchange is invalid.
+ */
+export class SubscriptionClient implements ProtocolHandler {
+    readonly #listeners = new Map<number, (dataReport: DataReport) => MaybePromise<void>>();
+    readonly #timeouts = new Map<number, Timer>();
+
+    constructor() {}
+
+    static [Environmental.create](env: Environment) {
+        const client = new SubscriptionClient();
+        env.set(SubscriptionClient, client);
+        return client;
+    }
+
+    readonly id = INTERACTION_PROTOCOL_ID;
+
+    /**
+     * Register a subscription.
+     */
+    add(subscription: RegisteredSubscription) {
+        const { id, onData, onTimeout } = subscription;
+
+        this.#listeners.set(id, onData);
+        if (onTimeout) {
+            let timer = this.#timeouts.get(id);
+            if (timer !== undefined) {
+                timer.stop();
+                this.#timeouts.delete(id);
+            }
+
+            const maxIntervalMs = subscription.maxIntervalS * 1000 + subscription.maximumPeerResponseTime;
+
+            timer = Time.getTimer("Subscription timeout", maxIntervalMs, () => {
+                logger.info(`Subscription ${id} timed out after ${maxIntervalMs}ms`);
+                this.delete(id);
+                onTimeout();
+            }).start();
+
+            this.#timeouts.set(id, timer);
+        }
+    }
+
+    /**
+     * Unregister a subscription.
+     */
+    delete(id: number) {
+        this.#listeners.delete(id);
+        const timer = this.#timeouts.get(id);
+        if (timer !== undefined) {
+            timer.stop();
+            this.#timeouts.delete(id);
+        }
+    }
+
+    async onNewExchange(exchange: MessageExchange) {
+        const messenger = new IncomingInteractionClientMessenger(exchange);
+
+        let dataReport: DataReport;
+        try {
+            // TODO Adjust this to getting packages as callback when received to handle error cases and checks outside
+            dataReport = await messenger.readAggregateDataReport([...this.#listeners.keys()]);
+        } finally {
+            messenger.close().catch(error => logger.info("Error closing client messenger", error));
+        }
+        const subscriptionId = dataReport.subscriptionId as number; // this is checked in the messenger already because we hand over allowed list
+
+        const listener = this.#listeners.get(subscriptionId);
+        const timer = this.#timeouts.get(subscriptionId);
+
+        if (timer !== undefined) {
+            timer.stop().start(); // Restart timer because we received data
+        }
+
+        await listener?.(dataReport);
+    }
+
+    async close() {
+        this.#listeners.clear();
+        this.#timeouts.forEach(timer => timer.stop());
+        this.#timeouts.clear();
+    }
+}

package/src/interaction/index.ts

@@ -14,3 +14,4 @@ export * from "./InteractionMessenger.js";
 export * from "./InteractionServer.js";
 export * from "./ServerSubscription.js";
 export * from "./Subscription.js";
+export * from "./SubscriptionClient.js";

package/src/peer/ControllerCommissioner.ts

@@ -27,11 +27,11 @@ import { ChannelStatusResponseError } from "#securechannel/index.js";
 import { PaseClient } from "#session/index.js";
 import { SessionManager } from "#session/SessionManager.js";
 import { DiscoveryCapabilitiesBitmap, NodeId, SECURE_CHANNEL_PROTOCOL_ID, TypeFromPartialBitSchema } from "#types";
-import { InteractionClient } from "../interaction/InteractionClient.js";
+import { InteractionClient, InteractionClientProvider } from "../interaction/InteractionClient.js";
 import { ExchangeManager, MessageChannel } from "../protocol/ExchangeManager.js";
 import { DedicatedChannelExchangeProvider } from "../protocol/ExchangeProvider.js";
 import { PeerAddress } from "./PeerAddress.js";
-import { NodeDiscoveryType, PeerSet } from "./PeerSet.js";
+import { NodeDiscoveryType } from "./PeerSet.js";
 
 const logger = Logger.get("PeerCommissioner");
 
@@ -108,7 +108,7 @@ export interface DiscoveryAndCommissioningOptions extends CommissioningOptions {
  * Interfaces {@link ControllerCommissioner} with other components.
  */
 export interface ControllerCommissionerContext {
-    peers: PeerSet;
+    clients: InteractionClientProvider;
     scanners: ScannerSet;
     netInterfaces: NetInterfaceSet;
     sessions: SessionManager;
@@ -130,7 +130,7 @@ export class ControllerCommissioner {
 
     static [Environmental.create](env: Environment) {
         const instance = new ControllerCommissioner({
-            peers: env.get(PeerSet),
+            clients: env.get(InteractionClientProvider),
             scanners: env.get(ScannerSet),
             netInterfaces: env.get(NetInterfaceSet),
             sessions: env.get(SessionManager),
@@ -385,6 +385,7 @@ export class ControllerCommissioner {
             // Use the created secure session to do the commissioning
             new InteractionClient(
                 new DedicatedChannelExchangeProvider(this.#context.exchanges, paseSecureMessageChannel),
+                this.#context.clients.peers.subscriptionClient,
                 address,
             ),
             this.#context.ca,
@@ -406,7 +407,7 @@ export class ControllerCommissioner {
                 }
 
                 // Look for the device broadcast over MDNS and do CASE pairing
-                return await this.#context.peers.connect(
+                return await this.#context.clients.connect(
                     address,
                     {
                         discoveryType: NodeDiscoveryType.TimedDiscovery,
@@ -422,7 +423,7 @@ export class ControllerCommissioner {
             await commissioningManager.executeCommissioning();
         } catch (error) {
             // We might have added data for an operational address that we need to cleanup
-            await this.#context.peers.delete(address);
+            await this.#context.clients.peers.delete(address);
             throw error;
         } finally {
             if (!paseSecureMessageChannel.closed) {

package/src/peer/InteractionQueue.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Environment, Environmental, PromiseQueue } from "@matter/general";
+
+const CONCURRENT_QUEUED_INTERACTIONS = 4;
+const INTERACTION_QUEUE_DELAY_MS = 100;
+
+export class InteractionQueue extends PromiseQueue {
+    constructor() {
+        super(CONCURRENT_QUEUED_INTERACTIONS, INTERACTION_QUEUE_DELAY_MS);
+    }
+
+    static [Environmental.create](env: Environment) {
+        const instance = new InteractionQueue();
+        env.set(InteractionQueue, instance);
+        return instance;
+    }
+}

package/src/peer/PeerAddressStore.ts

@@ -18,7 +18,7 @@ export abstract class PeerAddressStore {
     abstract loadPeers(): MaybePromise<Iterable<OperationalPeer>>;
     abstract updatePeer(peer: OperationalPeer): MaybePromise<void>;
     abstract deletePeer(address: PeerAddress): MaybePromise<void>;
-    abstract createNodeStore(address: PeerAddress): Promise<PeerDataStore>;
+    abstract createNodeStore(address: PeerAddress): MaybePromise<PeerDataStore | undefined>;
 }
 
 export abstract class PeerDataStore {