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

package/src/peer/PeerSet.ts

@@ -7,6 +7,7 @@
 import { DiscoveryData, ScannerSet } from "#common/Scanner.js";
 import {
     anyPromise,
+    AsyncObservable,
     BasicSet,
     ChannelType,
     Construction,
@@ -22,13 +23,12 @@ import {
     NetInterfaceSet,
     NoResponseTimeoutError,
     ObservableSet,
-    PromiseQueue,
     ServerAddressIp,
     serverAddressToString,
     Time,
     Timer,
 } from "#general";
-import { InteractionClient } from "#interaction/InteractionClient.js";
+import { SubscriptionClient } from "#interaction/SubscriptionClient.js";
 import { MdnsScanner } from "#mdns/MdnsScanner.js";
 import { PeerAddress, PeerAddressMap } from "#peer/PeerAddress.js";
 import { CaseClient, SecureSession, Session } from "#session/index.js";
@@ -39,6 +39,7 @@ import { ChannelNotConnectedError, ExchangeManager, MessageChannel } from "../pr
 import { ReconnectableExchangeProvider } from "../protocol/ExchangeProvider.js";
 import { RetransmissionLimitReachedError } from "../protocol/MessageExchange.js";
 import { ControllerDiscovery, DiscoveryError, PairRetransmissionLimitReachedError } from "./ControllerDiscovery.js";
+import { InteractionQueue } from "./InteractionQueue.js";
 import { OperationalPeer } from "./OperationalPeer.js";
 import { PeerAddressStore, PeerDataStore } from "./PeerAddressStore.js";
 
@@ -47,9 +48,6 @@ const logger = Logger.get("PeerSet");
 const RECONNECTION_POLLING_INTERVAL_MS = 600_000; // 10 minutes
 const RETRANSMISSION_DISCOVERY_TIMEOUT_S = 5;
 
-const CONCURRENT_QUEUED_INTERACTIONS = 4;
-const INTERACTION_QUEUE_DELAY_MS = 100;
-
 /**
  * Types of discovery that may be performed when connecting operationally.
  */
@@ -93,6 +91,7 @@ export interface PeerSetContext {
     sessions: SessionManager;
     channels: ChannelManager;
     exchanges: ExchangeManager;
+    subscriptionClient: SubscriptionClient;
     scanners: ScannerSet;
     netInterfaces: NetInterfaceSet;
     store: PeerAddressStore;
@@ -105,6 +104,7 @@ export class PeerSet implements ImmutableSet<OperationalPeer>, ObservableSet<Ope
     readonly #sessions: SessionManager;
     readonly #channels: ChannelManager;
     readonly #exchanges: ExchangeManager;
+    readonly #subscriptionClient: SubscriptionClient;
     readonly #scanners: ScannerSet;
     readonly #netInterfaces: NetInterfaceSet;
     readonly #caseClient: CaseClient;
@@ -117,16 +117,17 @@ export class PeerSet implements ImmutableSet<OperationalPeer>, ObservableSet<Ope
     }>();
     readonly #construction: Construction<PeerSet>;
     readonly #store: PeerAddressStore;
-    readonly #interactionQueue = new PromiseQueue(CONCURRENT_QUEUED_INTERACTIONS, INTERACTION_QUEUE_DELAY_MS);
+    readonly #interactionQueue = new InteractionQueue();
     readonly #nodeCachedData = new PeerAddressMap<PeerDataStore>(); // Temporarily until we store it in new API
-    readonly #clients = new PeerAddressMap<InteractionClient>();
+    readonly #disconnected = AsyncObservable<[address: PeerAddress]>();
 
     constructor(context: PeerSetContext) {
-        const { sessions, channels, exchanges, scanners, netInterfaces, store } = context;
+        const { sessions, channels, exchanges, subscriptionClient, scanners, netInterfaces, store } = context;
 
         this.#sessions = sessions;
         this.#channels = channels;
         this.#exchanges = exchanges;
+        this.#subscriptionClient = subscriptionClient;
         this.#scanners = scanners;
         this.#netInterfaces = netInterfaces;
         this.#store = store;
@@ -165,6 +166,10 @@ export class PeerSet implements ImmutableSet<OperationalPeer>, ObservableSet<Ope
         return this.#peers.deleted;
     }
 
+    get disconnected() {
+        return this.#disconnected;
+    }
+
     has(item: PeerAddress | OperationalPeer) {
         if ("address" in item) {
             return this.#peers.has(item);
@@ -201,6 +206,7 @@ export class PeerSet implements ImmutableSet<OperationalPeer>, ObservableSet<Ope
             sessions: env.get(SessionManager),
             channels: env.get(ChannelManager),
             exchanges: env.get(ExchangeManager),
+            subscriptionClient: env.get(SubscriptionClient),
             scanners: env.get(ScannerSet),
             netInterfaces: env.get(NetInterfaceSet),
             store: env.get(PeerAddressStore),
@@ -213,20 +219,18 @@ export class PeerSet implements ImmutableSet<OperationalPeer>, ObservableSet<Ope
         return this.#peers;
     }
 
-    /**
-     * Connect to a node on a fabric.
-     */
-    async connect(
-        address: PeerAddress,
-        discoveryOptions: DiscoveryOptions,
-        allowUnknownPeer = false,
-    ): Promise<InteractionClient> {
-        await this.#ensureConnection(address, discoveryOptions, allowUnknownPeer);
+    get subscriptionClient() {
+        return this.#subscriptionClient;
+    }
 
-        return this.initializeInteractionClient(address, discoveryOptions);
+    get interactionQueue() {
+        return this.#interactionQueue;
     }
 
-    async #ensureConnection(address: PeerAddress, discoveryOptions: DiscoveryOptions, allowUnknownPeer = false) {
+    /**
+     * Ensure there is a channel to the designated peer.
+     */
+    async ensureConnection(address: PeerAddress, discoveryOptions: DiscoveryOptions, allowUnknownPeer = false) {
         if (!this.#peersByAddress.has(address) && !allowUnknownPeer) {
             throw new UnknownNodeError(`Cannot connect to unknown device ${PeerAddress(address)}`);
         }
@@ -256,62 +260,44 @@ export class PeerSet implements ImmutableSet<OperationalPeer>, ObservableSet<Ope
         }
     }
 
-    async initializeInteractionClient(address: PeerAddress, discoveryOptions?: DiscoveryOptions) {
-        const existingClient = this.#clients.get(address);
-        if (existingClient !== undefined) {
-            return existingClient;
-        }
-
-        const nodeStore = this.get(address)?.dataStore;
-        await nodeStore?.construction; // Lazy initialize the data if not already done
-
+    /**
+     * Obtain an exchange provider for the designated peer.
+     */
+    async exchangeProviderFor(address: PeerAddress, discoveryOptions?: DiscoveryOptions) {
         let initiallyConnected = this.#channels.hasChannel(address);
-        const client = new InteractionClient(
-            new ReconnectableExchangeProvider(this.#exchanges, this.#channels, address, async () => {
-                if (!initiallyConnected && !this.#channels.hasChannel(address)) {
-                    // We got an uninitialized node, so do the first connection as usual
-                    await this.#ensureConnection(address, { discoveryType: NodeDiscoveryType.None });
-                    initiallyConnected = true; // We only do this connection once, rest is handled in following code
-                    if (this.#channels.hasChannel(address)) {
-                        return;
-                    }
+        return new ReconnectableExchangeProvider(this.#exchanges, this.#channels, address, async () => {
+            if (!initiallyConnected && !this.#channels.hasChannel(address)) {
+                // We got an uninitialized node, so do the first connection as usual
+                await this.ensureConnection(address, { discoveryType: NodeDiscoveryType.None });
+                initiallyConnected = true; // We only do this connection once, rest is handled in following code
+                if (this.#channels.hasChannel(address)) {
+                    return;
                 }
+            }
 
-                if (!this.#channels.hasChannel(address)) {
-                    throw new RetransmissionLimitReachedError(
-                        `Device ${PeerAddress(address)} is currently not reachable.`,
-                    );
-                }
-                await this.#channels.removeAllNodeChannels(address);
+            if (!this.#channels.hasChannel(address)) {
+                throw new RetransmissionLimitReachedError(`Device ${PeerAddress(address)} is currently not reachable.`);
+            }
+            await this.#channels.removeAllNodeChannels(address);
 
-                // Enrich discoveryData with data from the node store when not provided
-                const { discoveryData } = discoveryOptions ?? {
-                    discoveryData: this.#peersByAddress.get(address)?.discoveryData,
-                };
-                // Try to use first result for one last try before we need to reconnect
-                const operationalAddress = this.#knownOperationalAddressFor(address, true);
-                if (operationalAddress === undefined) {
-                    logger.info(
-                        `Re-discovering device failed (no address found), remove all sessions for ${PeerAddress(address)}`,
-                    );
-                    // We remove all sessions, this also informs the PairedNode class
-                    await this.#sessions.removeAllSessionsForNode(address);
-                    throw new RetransmissionLimitReachedError(
-                        `No operational address found for ${PeerAddress(address)}`,
-                    );
-                }
-                if (
-                    (await this.#reconnectKnownAddress(address, operationalAddress, discoveryData, 2_000)) === undefined
-                ) {
-                    throw new RetransmissionLimitReachedError(`${PeerAddress(address)} is not reachable.`);
-                }
-            }),
-            address,
-            this.#interactionQueue,
-            nodeStore,
-        );
-        this.#clients.set(address, client);
-        return client;
+            // Enrich discoveryData with data from the node store when not provided
+            const { discoveryData } = discoveryOptions ?? {
+                discoveryData: this.#peersByAddress.get(address)?.discoveryData,
+            };
+            // Try to use first result for one last try before we need to reconnect
+            const operationalAddress = this.#knownOperationalAddressFor(address, true);
+            if (operationalAddress === undefined) {
+                logger.info(
+                    `Re-discovering device failed (no address found), remove all sessions for ${PeerAddress(address)}`,
+                );
+                // We remove all sessions, this also informs the PairedNode class
+                await this.#sessions.removeAllSessionsForNode(address);
+                throw new RetransmissionLimitReachedError(`No operational address found for ${PeerAddress(address)}`);
+            }
+            if ((await this.#reconnectKnownAddress(address, operationalAddress, discoveryData, 2_000)) === undefined) {
+                throw new RetransmissionLimitReachedError(`${PeerAddress(address)} is not reachable.`);
+            }
+        });
     }
 
     /**
@@ -327,10 +313,15 @@ export class PeerSet implements ImmutableSet<OperationalPeer>, ObservableSet<Ope
     /**
      * Terminate any active peer connection.
      */
-    async disconnect(address: PeerAddress, sendSessionClose = true) {
-        this.#clients.get(address)?.removeAllSubscriptions();
+    async disconnect(peer: PeerAddress | OperationalPeer, sendSessionClose = true) {
+        const address = this.get(peer)?.address;
+        if (address === undefined) {
+            return;
+        }
+
         await this.#sessions.removeAllSessionsForNode(address, sendSessionClose);
         await this.#channels.removeAllNodeChannels(address);
+        await this.#disconnected.emit(address);
     }
 
     /**
@@ -348,7 +339,6 @@ export class PeerSet implements ImmutableSet<OperationalPeer>, ObservableSet<Ope
         await this.#store.deletePeer(address);
         await this.disconnect(address, false);
         await this.#sessions.deleteResumptionRecord(address);
-        this.#clients.delete(address);
     }
 
     async close() {
@@ -358,8 +348,11 @@ export class PeerSet implements ImmutableSet<OperationalPeer>, ObservableSet<Ope
             // This ends discovery without triggering promises
             mdnsScanner?.cancelOperationalDeviceDiscovery(this.#sessions.fabricFor(address), address.nodeId, false);
         }
-        this.#clients.forEach(client => client.close());
-        this.#clients.clear();
+
+        for (const { address } of this.#peers) {
+            await this.disconnect(address, false);
+        }
+
         this.#interactionQueue.close();
         this.#runningPeerReconnections.forEach(({ rejecter }) =>
             rejecter(new ChannelNotConnectedError("PeerSet closed")),

package/src/peer/PhysicalDeviceProperties.ts

@@ -0,0 +1,80 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger } from "#general";
+
+const logger = Logger.get("PhysicalDeviceProperties");
+
+const DEFAULT_SUBSCRIPTION_FLOOR_DEFAULT_S = 1;
+const DEFAULT_SUBSCRIPTION_FLOOR_ICD_S = 0;
+const DEFAULT_SUBSCRIPTION_CEILING_WIFI_S = 60;
+const DEFAULT_SUBSCRIPTION_CEILING_THREAD_S = 60;
+const DEFAULT_SUBSCRIPTION_CEILING_THREAD_SLEEPY_S = 180;
+const DEFAULT_SUBSCRIPTION_CEILING_BATTERY_POWERED_S = 600;
+
+export interface PhysicalDeviceProperties {
+    threadConnected: boolean;
+    wifiConnected: boolean;
+    ethernetConnected: boolean;
+    rootEndpointServerList: number[];
+    isBatteryPowered: boolean;
+    isIntermittentlyConnected: boolean;
+    isThreadSleepyEndDevice: boolean;
+}
+
+export namespace PhysicalDeviceProperties {
+    export function determineSubscriptionParameters(options?: {
+        properties?: PhysicalDeviceProperties;
+        description?: string;
+        subscribeMinIntervalFloorSeconds?: number;
+        subscribeMaxIntervalCeilingSeconds?: number;
+    }) {
+        const { properties } = options ?? {};
+
+        let {
+            description,
+            subscribeMinIntervalFloorSeconds: minIntervalFloorSeconds,
+            subscribeMaxIntervalCeilingSeconds: maxIntervalCeilingSeconds,
+        } = options ?? {};
+
+        if (description === undefined) {
+            description = "Node";
+        }
+
+        const { isBatteryPowered, isIntermittentlyConnected, threadConnected, isThreadSleepyEndDevice } =
+            properties ?? {};
+
+        if (isIntermittentlyConnected) {
+            if (minIntervalFloorSeconds !== undefined && minIntervalFloorSeconds !== DEFAULT_SUBSCRIPTION_FLOOR_ICD_S) {
+                logger.info(
+                    `${description}: Overwriting minIntervalFloorSeconds for intermittently connected device to ${DEFAULT_SUBSCRIPTION_FLOOR_ICD_S}`,
+                );
+                minIntervalFloorSeconds = DEFAULT_SUBSCRIPTION_FLOOR_ICD_S;
+            }
+        }
+
+        const defaultCeiling = isBatteryPowered
+            ? DEFAULT_SUBSCRIPTION_CEILING_BATTERY_POWERED_S
+            : isThreadSleepyEndDevice
+              ? DEFAULT_SUBSCRIPTION_CEILING_THREAD_SLEEPY_S
+              : threadConnected
+                ? DEFAULT_SUBSCRIPTION_CEILING_THREAD_S
+                : DEFAULT_SUBSCRIPTION_CEILING_WIFI_S;
+        if (maxIntervalCeilingSeconds === undefined) {
+            maxIntervalCeilingSeconds = defaultCeiling;
+        }
+        if (maxIntervalCeilingSeconds < defaultCeiling) {
+            logger.debug(
+                `${description}: maxIntervalCeilingSeconds ideally is ${defaultCeiling}s instead of ${maxIntervalCeilingSeconds}s due to device type`,
+            );
+        }
+
+        return {
+            minIntervalFloorSeconds: minIntervalFloorSeconds ?? DEFAULT_SUBSCRIPTION_FLOOR_DEFAULT_S,
+            maxIntervalCeilingSeconds,
+        };
+    }
+}

package/src/peer/index.ts

@@ -11,3 +11,4 @@ export * from "./OperationalPeer.js";
 export * from "./PeerAddress.js";
 export * from "./PeerAddressStore.js";
 export * from "./PeerSet.js";
+export * from "./PhysicalDeviceProperties.js";

package/src/protocol/ExchangeManager.ts

@@ -150,6 +150,10 @@ export class ExchangeManager {
         return instance;
     }
 
+    get channels() {
+        return this.#channelManager;
+    }
+
     hasProtocolHandler(protocolId: number) {
         return this.#protocols.has(protocolId);
     }
@@ -159,10 +163,10 @@ export class ExchangeManager {
     }
 
     addProtocolHandler(protocol: ProtocolHandler) {
-        if (this.hasProtocolHandler(protocol.getId())) {
-            throw new ImplementationError(`Handler for protocol ${protocol.getId()} already registered.`);
+        if (this.hasProtocolHandler(protocol.id)) {
+            throw new ImplementationError(`Handler for protocol ${protocol.id} already registered.`);
         }
-        this.#protocols.set(protocol.getId(), protocol);
+        this.#protocols.set(protocol.id, protocol);
     }
 
     initiateExchange(address: PeerAddress, protocolId: number) {

package/src/protocol/ExchangeProvider.ts

@@ -12,8 +12,13 @@ import { MessageExchange } from "../protocol/MessageExchange.js";
 import { ProtocolHandler } from "../protocol/ProtocolHandler.js";
 import { Session } from "../session/Session.js";
 
+/**
+ * Interface for obtaining an exchange with a specific peer.
+ */
 export abstract class ExchangeProvider {
-    protected constructor(protected readonly exchangeManager: ExchangeManager) {}
+    abstract readonly supportsReconnect: boolean;
+
+    constructor(protected readonly exchangeManager: ExchangeManager) {}
 
     hasProtocolHandler(protocolId: number) {
         return this.exchangeManager.hasProtocolHandler(protocolId);
@@ -33,8 +38,12 @@ export abstract class ExchangeProvider {
     abstract channelType: ChannelType;
 }
 
+/**
+ * Manages an exchange over an established channel.
+ */
 export class DedicatedChannelExchangeProvider extends ExchangeProvider {
     #channel: MessageChannel;
+    readonly supportsReconnect = false;
 
     constructor(exchangeManager: ExchangeManager, channel: MessageChannel) {
         super(exchangeManager);
@@ -58,7 +67,11 @@ export class DedicatedChannelExchangeProvider extends ExchangeProvider {
     }
 }
 
+/**
+ * Manages peer exchange that will reestablish automatically in the case of communication failure.
+ */
 export class ReconnectableExchangeProvider extends ExchangeProvider {
+    readonly supportsReconnect = true;
     readonly #address: PeerAddress;
     readonly #reconnectChannelFunc: () => Promise<void>;
     readonly #channelUpdated = Observable<[void]>();

package/src/protocol/ProtocolHandler.ts

@@ -8,7 +8,7 @@ import { Message } from "../codec/MessageCodec.js";
 import { MessageExchange } from "./MessageExchange.js";
 
 export interface ProtocolHandler {
-    getId(): number;
+    readonly id: number;
     onNewExchange(exchange: MessageExchange, message: Message): Promise<void>;
     close(): Promise<void>;
 }

package/src/securechannel/SecureChannelProtocol.ts

@@ -28,9 +28,7 @@ import { TlvSecureChannelStatusMessage } from "./SecureChannelStatusMessageSchem
 const logger = Logger.get("SecureChannelProtocol");
 
 export class StatusReportOnlySecureChannelProtocol implements ProtocolHandler {
-    getId(): number {
-        return SECURE_CHANNEL_PROTOCOL_ID;
-    }
+    readonly id = SECURE_CHANNEL_PROTOCOL_ID;
 
     async onNewExchange(exchange: MessageExchange, message: Message) {
         const messageType = message.payloadHeader.messageType;

package/src/session/SessionManager.ts

@@ -386,6 +386,7 @@ export class SessionManager {
             const secureSession = session;
             if (secureSession.peerIs(address)) {
                 await secureSession.destroy(sendClose, false);
+                this.#sessions.delete(session);
             }
         }
     }

package/src/session/case/CaseServer.ts

@@ -30,6 +30,8 @@ import { CaseServerMessenger } from "./CaseMessenger.js";
 const logger = Logger.get("CaseServer");
 
 export class CaseServer implements ProtocolHandler {
+    readonly id = SECURE_CHANNEL_PROTOCOL_ID;
+
     #sessions: SessionManager;
     #fabrics: FabricManager;
 
@@ -58,10 +60,6 @@ export class CaseServer implements ProtocolHandler {
         }
     }
 
-    getId(): number {
-        return SECURE_CHANNEL_PROTOCOL_ID;
-    }
-
     private async handleSigma1(messenger: CaseServerMessenger) {
         logger.info(`Received pairing request from ${messenger.getChannelName()}`);
         // Generate pairing info

package/src/session/pase/PaseServer.ts

@@ -33,8 +33,10 @@ const PASE_COMMISSIONING_MAX_ERRORS = 20;
 export class MaximumPasePairingErrorsReachedError extends MatterFlowError {}
 
 export class PaseServer implements ProtocolHandler {
-    private pairingTimer: Timer | undefined;
-    private pairingErrors = 0;
+    readonly id = SECURE_CHANNEL_PROTOCOL_ID;
+
+    #pairingTimer: Timer | undefined;
+    #pairingErrors = 0;
 
     static async fromPin(sessions: SessionManager, setupPinCode: number, pbkdfParameters: PbkdfParameters) {
         const { w0, L } = await Spake2p.computeW0L(pbkdfParameters, setupPinCode);
@@ -58,18 +60,14 @@ export class PaseServer implements ProtocolHandler {
         private readonly pbkdfParameters?: PbkdfParameters,
     ) {}
 
-    getId(): number {
-        return SECURE_CHANNEL_PROTOCOL_ID;
-    }
-
     async onNewExchange(exchange: MessageExchange) {
         const messenger = new PaseServerMessenger(exchange);
         try {
             await this.handlePairingRequest(messenger);
         } catch (error) {
-            this.pairingErrors++;
+            this.#pairingErrors++;
             logger.error(
-                `An error occurred during the PASE commissioning (${this.pairingErrors}/${PASE_COMMISSIONING_MAX_ERRORS}):`,
+                `An error occurred during the PASE commissioning (${this.#pairingErrors}/${PASE_COMMISSIONING_MAX_ERRORS}):`,
                 error,
             );
 
@@ -77,7 +75,7 @@ export class PaseServer implements ProtocolHandler {
             const sendError = !(error instanceof ChannelStatusResponseError);
             await this.cancelPairing(messenger, sendError);
 
-            if (this.pairingErrors >= PASE_COMMISSIONING_MAX_ERRORS) {
+            if (this.#pairingErrors >= PASE_COMMISSIONING_MAX_ERRORS) {
                 throw new MaximumPasePairingErrorsReachedError(
                     `Pase server: Too many errors during PASE commissioning, aborting commissioning window`,
                 );
@@ -99,7 +97,7 @@ export class PaseServer implements ProtocolHandler {
             );
         }
 
-        if (this.pairingTimer !== undefined && this.pairingTimer.isRunning) {
+        if (this.#pairingTimer !== undefined && this.#pairingTimer.isRunning) {
             throw new MatterFlowError(
                 "Pase server: Pairing already in progress (PASE establishment Timer running), ignoring new exchange.",
             );
@@ -107,7 +105,7 @@ export class PaseServer implements ProtocolHandler {
 
         logger.info(`Received pairing request from ${messenger.getChannelName()}.`);
 
-        this.pairingTimer = Time.getTimer("PASE pairing timeout", PASE_PAIRING_TIMEOUT_MS, () =>
+        this.#pairingTimer = Time.getTimer("PASE pairing timeout", PASE_PAIRING_TIMEOUT_MS, () =>
             this.cancelPairing(messenger),
         ).start();
 
@@ -167,13 +165,13 @@ export class PaseServer implements ProtocolHandler {
         await messenger.sendSuccess();
         await messenger.close();
 
-        this.pairingTimer?.stop();
-        this.pairingTimer = undefined;
+        this.#pairingTimer?.stop();
+        this.#pairingTimer = undefined;
     }
 
     async cancelPairing(messenger: PaseServerMessenger, sendError = true) {
-        this.pairingTimer?.stop();
-        this.pairingTimer = undefined;
+        this.#pairingTimer?.stop();
+        this.#pairingTimer = undefined;
 
         if (sendError) {
             await messenger.sendError(ProtocolStatusCode.InvalidParam);