@matter/protocol 0.17.7 → 0.17.8-alpha.0-20260801-92169d0aa

package/src/protocol/ExchangeManager.ts

@@ -520,7 +520,11 @@ export class ExchangeManager implements Transport.Provider {
                 }
 
                 // Report peer loss to the session manager; this notifies all (relevant) sessions for the peer
-                await this.#sessions.handlePeerLoss(session.peerAddress, cause, createdAt);
+                await this.#sessions.handlePeerLoss(session.peerAddress, {
+                    cause,
+                    asOf: createdAt,
+                    currentExchange: exchange,
+                });
             },
 
             retry: number => this.#sessions.retry.emit(session, number),

package/src/protocol/MessageExchange.ts

@@ -103,7 +103,7 @@ export interface ExchangeSendOptions {
     /** Initial MRP retransmission time (default: calculated as by Matter specification) */
     initialRetransmissionTime?: Duration;
 
-    /** Suppress peer-loss reporting on send-failure so the session stays alive. Used by probing. */
+    /** Suppress peer-loss reporting for this send.  OR'd with {@link MessageExchange.Options.suppressPeerLoss}. */
     suppressPeerLoss?: boolean;
 }
 
@@ -119,7 +119,7 @@ export interface ExchangeReceiveOptions {
      */
     expectedProcessingTime?: Duration;
 
-    /** Suppress peer-loss reporting on receive failure so the session stays alive for further probing. */
+    /** Suppress peer-loss reporting for this receive.  OR'd with {@link MessageExchange.Options.suppressPeerLoss}. */
     suppressPeerLoss?: boolean;
 }
 
@@ -203,6 +203,7 @@ export class MessageExchange {
     #onReceive?: MessageExchange.ReceiveNotifier;
     readonly #addressOverride?: ServerAddressUdp;
     readonly #peerAdditionalMrpDelay?: Duration;
+    readonly #suppressPeerLoss: boolean;
     #receivedMessageToAck: Message | undefined;
     #receivedMessageAckTimer = Time.getTimer("ack receipt timeout", MRP.STANDALONE_ACK_TIMEOUT, () => {
         if (this.#receivedMessageToAck !== undefined) {
@@ -256,6 +257,7 @@ export class MessageExchange {
             network,
             peerAdditionalMrpDelay,
             addressOverride,
+            suppressPeerLoss = false,
         } = config;
 
         this.#context = context;
@@ -269,6 +271,7 @@ export class MessageExchange {
         this.#onReceive = onReceive;
         this.#addressOverride = addressOverride;
         this.#peerAdditionalMrpDelay = peerAdditionalMrpDelay;
+        this.#suppressPeerLoss = suppressPeerLoss;
 
         const { activeThreshold, activeInterval, idleInterval } = this.session.parameters;
 
@@ -499,12 +502,8 @@ export class MessageExchange {
         try {
             await this.#send(messageType, payload);
         } catch (e) {
-            // Only declare the peer as lost when this exchange has never received a response.  If we already
-            // exchanged messages, the peer was reachable, and the later send-failure may be transient — declaring
-            // peer loss would unnecessarily close sessions and tear down subscriptions.
             if (
-                !options.suppressPeerLoss &&
-                this.#messageReceivedCounter === 0 &&
+                this.#reportsPeerLoss(options.suppressPeerLoss) &&
                 causedBy(e, TransientPeerCommunicationError, TimeoutError, NetworkError)
             ) {
                 await this.#context.peerLost(this, asError(e));
@@ -514,6 +513,14 @@ export class MessageExchange {
         }
     }
 
+    /**
+     * Whether a failure here is evidence the peer is gone.  Only if we never heard from it on this exchange: one that
+     * answered earlier was reachable, and peer loss closes every session with it.
+     */
+    #reportsPeerLoss(suppressedForOperation?: boolean) {
+        return !this.#suppressPeerLoss && suppressedForOperation !== true && this.#messageReceivedCounter === 0;
+    }
+
     async #send(messageType: number, payload: Bytes, standaloneAckMessageId?: number) {
         const {
             expectAckOnly = false,
@@ -704,14 +711,7 @@ export class MessageExchange {
         try {
             return await this.#nextMessage(options);
         } catch (e) {
-            // Only declare the peer as lost when this exchange has never received a message.  Receiving at least
-            // one message confirms the peer was reachable; a later timeout waiting for the next message in a
-            // multi-message exchange should not be treated as permanent peer absence.
-            if (
-                !options?.suppressPeerLoss &&
-                this.#messageReceivedCounter === 0 &&
-                causedBy(e, TransientPeerCommunicationError)
-            ) {
+            if (this.#reportsPeerLoss(options?.suppressPeerLoss) && causedBy(e, TransientPeerCommunicationError)) {
                 await this.#context.peerLost(this, asError(e));
             }
 
@@ -1119,6 +1119,9 @@ export namespace MessageExchange {
          * instead of the session's default peer address.
          */
         addressOverride?: ServerAddressUdp;
+
+        /** Waive peer-loss inference here.  Required for exchanges to a peer that drives its own recovery. */
+        suppressPeerLoss?: boolean;
     }
 
     export interface Config extends Options {

package/src/session/NodeSession.ts

@@ -27,9 +27,13 @@ import {
     Diagnostic,
     Duration,
     hex,
+    Instant,
     InternalError,
     Logger,
     MatterFlowError,
+    Mutex,
+    Time,
+    Timer,
 } from "@matter/general";
 import { CaseAuthenticatedTag, FabricIndex, GlobalFabricId, NodeId } from "@matter/types";
 import { SecureSession } from "./SecureSession.js";
@@ -55,6 +59,8 @@ export class NodeSession extends SecureSession {
     readonly supportsMRP = true;
     readonly type = SessionType.Unicast;
     readonly #closedByPeer = AsyncObservableValue();
+    #rolloverCloseTimer?: Timer;
+    readonly #rolloverClose = new Mutex(this);
     #isPeerLost = false;
 
     // TODO - remove this; subscriptions should be owned by the peer, not the session
@@ -108,13 +114,7 @@ export class NodeSession extends SecureSession {
             ...config,
             setActiveTimestamp: true, // We always set the active timestamp for Secure sessions
             // Can be changed to a PersistedMessageCounter if we implement session storage
-            messageCounter: new MessageCounter(crypto, async () => {
-                // Secure Session Message Counter
-                // Expire/End the session before the counter rolls over
-                await this.initiateClose(async () => {
-                    await this.closeSubscriptions(true);
-                });
-            }),
+            messageCounter: new MessageCounter(crypto, async () => this.#scheduleRolloverClose()),
             messageReceptionState: new MessageReceptionStateEncryptedWithoutRollover(0),
         });
 
@@ -269,10 +269,10 @@ export class NodeSession extends SecureSession {
         return this.#fabric;
     }
 
-    override async closeSubscriptions(flush = false) {
+    override async closeSubscriptions(flush = false, currentExchange?: MessageExchange) {
         const subscriptions = [...this.#subscriptions]; // get all values because subscriptions will remove themselves when cancelled
         for (const subscription of subscriptions) {
-            await subscription.close(flush ? this : undefined);
+            await subscription.close(flush ? this : undefined, currentExchange);
         }
         return subscriptions.length;
     }
@@ -337,7 +337,31 @@ export class NodeSession extends SecureSession {
         });
     }
 
+    /**
+     * Wind the session down before its message counter rolls over.  Notification arrives 100,000 messages ahead, on
+     * the stack of the send that consumed the counter, so closing there would make the flush wait on that send.
+     */
+    #scheduleRolloverClose() {
+        if (this.#rolloverCloseTimer !== undefined || this.isClosing) {
+            return;
+        }
+
+        logger.info(this.via, "Message counter nearing rollover, ending session");
+
+        this.#rolloverCloseTimer = Time.getTimer("session rollover close", Instant, () =>
+            this.#rolloverClose.run(async () => {
+                await this.initiateClose(async () => {
+                    await this.closeSubscriptions(true);
+                });
+            }),
+        ).start();
+    }
+
     protected override async close() {
+        this.#rolloverCloseTimer?.stop();
+        this.#rolloverCloseTimer = undefined;
+        await this.#rolloverClose;
+
         if (!this.#isPeerLost) {
             try {
                 await this.gracefulClose.emit();

package/src/session/Session.ts

@@ -274,7 +274,7 @@ export abstract class Session {
     async initiateForceClose(context: PeerLossContext) {
         await this.initiateClose(async () => {
             if (!context.keepSubscriptions) {
-                await this.closeSubscriptions();
+                await this.closeSubscriptions(false, context.currentExchange);
             }
             for (const exchange of this.#exchanges) {
                 if (exchange === context.currentExchange) {
@@ -317,7 +317,7 @@ export abstract class Session {
         return !!this.#exchanges.size;
     }
 
-    async closeSubscriptions(_cancelledByPeer = false): Promise<number> {
+    async closeSubscriptions(_flush = false, _currentExchange?: MessageExchange): Promise<number> {
         return 0;
     }
 

package/src/session/SessionManager.ts

@@ -156,6 +156,12 @@ export interface SessionManagerContext {
 
 const ID_SPACE_UPPER_BOUND = 0xffff;
 
+/**
+ * Sessions retained per peer.  A new CASE does not close the peer's previous sessions, so a peer that reconnects
+ * repeatedly accumulates them.  Per peer rather than global so one noisy peer cannot evict another's.
+ */
+const MAX_SESSIONS_PER_PEER = 5;
+
 /** Storage key for the node-global Group Encrypted Data Message Counter in the session storage context. */
 const GROUP_DATA_COUNTER_KEY = "groupDataCounter";
 
@@ -166,8 +172,15 @@ const GROUP_DATA_COUNTER_KEY = "groupDataCounter";
  */
 const GROUP_DATA_COUNTER_RESERVE = 1000;
 
+/** Thrown into a session closed because its peer exceeded {@link MAX_SESSIONS_PER_PEER}. */
+export class SessionEvictedError extends ClosedError {
+    constructor(message = "Session evicted; peer holds too many sessions", options?: ErrorOptions) {
+        super(message, options);
+    }
+}
+
 /**
- * Thrown when communication terminates due node shutdown.
+ * Thrown when communication terminates due to node shutdown.
  */
 export class ShutdownError extends ClosedError {
     constructor(message = "Local node shutdown", options?: ErrorOptions) {
@@ -203,6 +216,7 @@ export class SessionManager {
     readonly #construction: Construction<SessionManager>;
     readonly #observers = new ObserverGroup();
     readonly #subscriptionUpdateMutex = new Mutex(this);
+    readonly #sessionEvictionMutex = new Mutex(this);
     #idUpperBound = ID_SPACE_UPPER_BOUND;
 
     readonly #subscriptionsChanged = Observable<[session: NodeSession, subscription: Subscription]>();
@@ -224,6 +238,14 @@ export class SessionManager {
             await this.deleteResumptionRecordsForFabric(fabric);
         });
 
+        this.#sessions.added.on(session => {
+            // We are the responder, so nothing else reclaims these: an initiator's sessions are swept by the peer
+            // loss its own traffic reports
+            if (!session.isInitiator) {
+                this.#sessionEvictionMutex.run(() => this.#evictExcessSessionsFor(session));
+            }
+        });
+
         // Add subscription monitors to new node sessions
         this.#sessions.added.on(session => {
             const subscriptionsChanged = (subscription: Subscription) => {
@@ -444,19 +466,25 @@ export class SessionManager {
         return deletedCount > 0;
     }
 
-    findOldestInactiveSession() {
-        this.#construction.assert();
-
-        let oldestSession: NodeSession | undefined = undefined;
+    /** The session with the least recent traffic among those {@link filter} accepts, if any. */
+    #leastRecentlyUsedSession(filter: (session: NodeSession) => boolean) {
+        let oldest: NodeSession | undefined;
         for (const session of this.#sessions) {
-            if (!oldestSession || session.timestamp < oldestSession.timestamp) {
-                oldestSession = session;
+            if (filter(session) && (oldest === undefined || session.timestamp < oldest.timestamp)) {
+                oldest = session;
             }
         }
-        if (oldestSession === undefined) {
+        return oldest;
+    }
+
+    findOldestInactiveSession() {
+        this.#construction.assert();
+
+        const oldest = this.#leastRecentlyUsedSession(() => true);
+        if (oldest === undefined) {
             throw new MatterFlowError("No session found to close and all session ids are taken.");
         }
-        return oldestSession;
+        return oldest;
     }
 
     async getNextAvailableSessionId() {
@@ -556,8 +584,45 @@ export class SessionManager {
     /**
      * Removes all Peer sessions and closes subscriptions.
      */
-    async handlePeerLoss(address: PeerAddress, cause: Error, asOf?: Timestamp) {
-        return await this.#handlePeerLoss({ address, asOf: asOf ?? Time.nowMs, cause });
+    async handlePeerLoss(address: PeerAddress, context: PeerLossContext) {
+        return await this.#handlePeerLoss({ ...context, address, asOf: context.asOf ?? Time.nowMs });
+    }
+
+    /**
+     * Close the peer's least recently active sessions once it exceeds {@link MAX_SESSIONS_PER_PEER}.
+     *
+     * Only sessions the peer established are eligible: ones we initiated are ours to manage, and the peer loss our
+     * own traffic reports already sweeps them.  {@link added} is excluded so a burst of new sessions cannot evict the
+     * one that prompted the check.
+     */
+    async #evictExcessSessionsFor(added: NodeSession) {
+        if (added.isPase || added.isClosing) {
+            return;
+        }
+
+        const address = added.peerAddress;
+        const claimsSlot = (session: NodeSession) =>
+            session !== added && !session.isInitiator && session.peerIs(address);
+
+        // A session already closing still occupies a slot until it completes, so it counts here but is not evicted
+        // again -- otherwise one that parks in deferredClose drops out of the count and the cap stops capping
+        let excess = this.#sessions.filter(claimsSlot).length + 1 - MAX_SESSIONS_PER_PEER;
+
+        while (excess-- > 0) {
+            const session = this.#leastRecentlyUsedSession(s => claimsSlot(s) && !s.isClosing);
+            if (session === undefined) {
+                return;
+            }
+
+            logger.info(
+                session.via,
+                `Closing least recently used session; ${PeerAddress(address)} exceeds ${MAX_SESSIONS_PER_PEER} sessions`,
+            );
+
+            // Force close rather than the graceful path: that sends CloseSession over MRP, and the eviction target is
+            // typically the peer we can no longer reach, so it would hold this mutex for a full retransmission window
+            await session.initiateForceClose({ cause: new SessionEvictedError() });
+        }
     }
 
     async #handlePeerLoss(
@@ -917,6 +982,7 @@ export class SessionManager {
         }
 
         await this.#subscriptionUpdateMutex;
+        await this.#sessionEvictionMutex;
 
         const context: PeerLossContext = { cause: new ShutdownError("Session closed by node shutdown") };