@matter/protocol 0.16.0-alpha.0-20251203-aaf94bca8 → 0.16.0-alpha.0-20251207-37e501b18

package/src/peer/index.ts

@@ -7,8 +7,8 @@
 export * from "./ControllerCommissioner.js";
 export * from "./ControllerCommissioningFlow.js";
 export * from "./ControllerDiscovery.js";
-export * from "./OperationalPeer.js";
 export * from "./PeerAddress.js";
 export * from "./PeerAddressStore.js";
+export * from "./PeerDescriptor.js";
 export * from "./PeerSet.js";
 export * from "./PhysicalDeviceProperties.js";

package/src/protocol/DeviceAdvertiser.ts

@@ -48,7 +48,7 @@ export class DeviceAdvertiser {
         });
 
         // When a fabric is updated we might need to adjust announcements
-        this.#observers.on(fabrics.events.updated, async fabric => {
+        this.#observers.on(fabrics.events.replaced, async fabric => {
             if (!this.#isOperational) {
                 return;
             }
@@ -78,7 +78,7 @@ export class DeviceAdvertiser {
         });
 
         // When a fabric is deleted, cancel any active advertisement
-        this.#observers.on(fabrics.events.deleted, fabric => {
+        this.#observers.on(fabrics.events.deleting, fabric => {
             Advertisement.cancelAll(this.#advertisements(ad => ad.isOperational() && ad.description.fabric === fabric));
         });
 
@@ -86,7 +86,7 @@ export class DeviceAdvertiser {
         // configured
         this.#observers.on(sessions.sessions.added, session => {
             const fabricIndex = session.fabric?.fabricIndex;
-            const fabric = fabricIndex ? fabrics.findByIndex(fabricIndex) : undefined;
+            const fabric = fabricIndex ? fabrics.maybeForIndex(fabricIndex) : undefined;
             if (!fabric) {
                 return;
             }
@@ -102,7 +102,7 @@ export class DeviceAdvertiser {
         // When a session is closed, conditionally resume broadcast
         this.#observers.on(sessions.sessions.deleted, session => {
             const fabricIndex = session.fabric?.fabricIndex;
-            const fabric = fabricIndex ? fabrics.findByIndex(fabricIndex) : undefined;
+            const fabric = fabricIndex ? fabrics.maybeForIndex(fabricIndex) : undefined;
 
             // If this was an operational connection, readvertise if we're no longer connected to the peer
             if (fabric) {

package/src/protocol/ExchangeManager.ts

@@ -5,7 +5,9 @@
  */
 
 import { DecodedMessage, MessageCodec, SessionType } from "#codec/MessageCodec.js";
+import { Mark } from "#common/Mark.js";
 import {
+    BasicMultiplex,
     Bytes,
     Channel,
     ConnectionlessTransport,
@@ -14,94 +16,88 @@ import {
     Entropy,
     Environment,
     Environmental,
+    hex,
     ImplementationError,
+    Lifetime,
     Logger,
-    MatterAggregateError,
-    MatterError,
     MatterFlowError,
     ObserverGroup,
     UdpInterface,
     UnexpectedDataError,
 } from "#general";
 import { PeerAddress } from "#peer/PeerAddress.js";
-import {
-    ChannelNotConnectedError,
-    DEFAULT_EXPECTED_PROCESSING_TIME,
-    MessageChannel,
-} from "#protocol/MessageChannel.js";
+import { DEFAULT_EXPECTED_PROCESSING_TIME } from "#protocol/MessageChannel.js";
 import { SecureChannelMessenger } from "#securechannel/SecureChannelMessenger.js";
-import { UNICAST_UNSECURE_SESSION_ID } from "#session/InsecureSession.js";
 import { NodeSession } from "#session/NodeSession.js";
 import { Session } from "#session/Session.js";
 import { SessionManager } from "#session/SessionManager.js";
+import { UNICAST_UNSECURE_SESSION_ID } from "#session/UnsecuredSession.js";
 import { NodeId, SECURE_CHANNEL_PROTOCOL_ID, SecureMessageType } from "#types";
-import { ChannelManager } from "./ChannelManager.js";
 import { MessageExchange, MessageExchangeContext } from "./MessageExchange.js";
 import { DuplicateMessageError } from "./MessageReceptionState.js";
 import { ProtocolHandler } from "./ProtocolHandler.js";
 
 const logger = Logger.get("ExchangeManager");
 
-const MAXIMUM_CONCURRENT_EXCHANGES_PER_SESSION = 5;
+/**
+ * Maximum number of concurrent outgoing exchanges per session.
+ * We chose 30 under the assumption that each exchange has one message in flight and the usual SecureSession message
+ * counter window tracks 32 messages. So we have "2 spare messages" if really someone uses that many parallel exchanges.
+ * TODO: Change this into an exchange creation queue instead of hard limiting it.
+ */
+const MAXIMUM_CONCURRENT_OUTGOING_EXCHANGES_PER_SESSION = 30;
 
 /**
  * Interfaces {@link ExchangeManager} with other components.
  */
 export interface ExchangeManagerContext {
+    lifetime: Lifetime.Owner;
     entropy: Entropy;
     netInterface: ConnectionlessTransportSet;
-    sessionManager: SessionManager;
-    channelManager: ChannelManager;
+    sessions: SessionManager;
 }
 
 export class ExchangeManager {
+    readonly #lifetime: Lifetime;
     readonly #transports: ConnectionlessTransportSet;
-    readonly #sessionManager: SessionManager;
-    readonly #channelManager: ChannelManager;
+    readonly #sessions: SessionManager;
     readonly #exchangeCounter: ExchangeCounter;
     readonly #exchanges = new Map<number, MessageExchange>();
     readonly #protocols = new Map<number, ProtocolHandler>();
     readonly #listeners = new Map<ConnectionlessTransport, ConnectionlessTransport.Listener>();
-    readonly #closers = new Set<Promise<void>>();
+    readonly #workers: BasicMultiplex;
     readonly #observers = new ObserverGroup(this);
-    #closing = false;
+    readonly #sessionObservers = new Map<Session, ObserverGroup>();
+    #isClosing = false;
 
     constructor(context: ExchangeManagerContext) {
+        this.#lifetime = context.lifetime.join("exchanges");
+        this.#workers = new BasicMultiplex();
         this.#transports = context.netInterface;
-        this.#sessionManager = context.sessionManager;
-        this.#channelManager = context.channelManager;
+        this.#sessions = context.sessions;
         this.#exchangeCounter = new ExchangeCounter(context.entropy);
 
         for (const netInterface of this.#transports) {
-            this.#addListener(netInterface);
+            this.#addTransport(netInterface);
         }
 
-        this.#observers.on(this.#transports.added, this.#addListener);
-        this.#observers.on(this.#transports.deleted, this.#deleteListener);
-
-        this.#observers.on(this.#sessionManager.sessions.deleted, session => {
-            if (!session.closingAfterExchangeFinished) {
-                // Delayed closing is executed when exchange is closed
-                session.closer = this.#closeSession(session);
-            }
-        });
+        this.#observers.on(this.#transports.added, this.#addTransport);
+        this.#observers.on(this.#transports.deleted, this.#deleteTransport);
+        this.#observers.on(this.#sessions.sessions.added, this.#addSession);
+        this.#observers.on(this.#sessions.sessions.deleted, this.#deleteSession);
     }
 
     static [Environmental.create](env: Environment) {
         const instance = new ExchangeManager({
+            lifetime: env,
             entropy: env.get(Entropy),
             netInterface: env.get(ConnectionlessTransportSet),
-            sessionManager: env.get(SessionManager),
-            channelManager: env.get(ChannelManager),
+            sessions: env.get(SessionManager),
         });
         env.set(ExchangeManager, instance);
         return instance;
     }
 
-    get channels() {
-        return this.#channelManager;
-    }
-
     hasProtocolHandler(protocolId: number) {
         return this.#protocols.has(protocolId);
     }
@@ -118,36 +114,57 @@ export class ExchangeManager {
     }
 
     initiateExchange(address: PeerAddress, protocolId: number) {
-        return this.initiateExchangeWithChannel(this.#channelManager.getChannel(address), protocolId);
+        return this.initiateExchangeForSession(this.#sessions.sessionFor(address), protocolId);
     }
 
-    initiateExchangeWithChannel(channel: MessageChannel, protocolId: number) {
+    initiateExchangeForSession(session: Session, protocolId: number) {
         const exchangeId = this.#exchangeCounter.getIncrementedCounter();
         const exchangeIndex = exchangeId | 0x10000; // Ensure initiated and received exchange index are different, since the exchangeID can be the same
-        const exchange = MessageExchange.initiate(this.#messageExchangeContextFor(channel), exchangeId, protocolId);
+        const exchange = MessageExchange.initiate(this.#messageExchangeContextFor(session), exchangeId, protocolId);
         this.#addExchange(exchangeIndex, exchange);
         return exchange;
     }
 
     async close() {
-        this.#closing = true;
+        if (this.#isClosing) {
+            return;
+        }
+
+        using closing = this.#lifetime.closing();
+
+        this.#isClosing = true;
+
+        const exchangesClosed = new BasicMultiplex();
+
+        for (const exchange of this.#exchanges.values()) {
+            exchangesClosed.add(exchange.close(true));
+        }
+
+        {
+            using _closing = closing.join("exchanges");
+            await exchangesClosed;
+        }
+
+        for (const listener of this.#listeners.keys()) {
+            this.#deleteTransport(listener);
+        }
+
         for (const protocol of this.#protocols.values()) {
-            await protocol.close();
+            this.#workers.add(protocol.close());
         }
-        for (const listeners of this.#listeners.keys()) {
-            this.#deleteListener(listeners);
+
+        {
+            using _closing = closing.join("workers");
+            await this.#workers;
         }
-        await MatterAggregateError.allSettled(this.#closers, "Error closing exchanges").catch(error =>
-            logger.error(error),
-        );
-        await MatterAggregateError.allSettled(
-            Array.from(this.#exchanges.values()).map(exchange => exchange.close(true)),
-            "Error closing exchanges",
-        ).catch(error => logger.error(error));
+
         this.#exchanges.clear();
+        this.#observers.close();
     }
 
-    private async onMessage(channel: Channel<Bytes>, messageBytes: Bytes) {
+    async #onMessage(channel: Channel<Bytes>, messageBytes: Bytes) {
+        using _lifetime = this.#lifetime.join("receiving from", Diagnostic.strong(channel.name));
+
         const packet = MessageCodec.decodePacket(messageBytes);
         const bytes = Bytes.of(messageBytes);
         const aad = bytes.slice(0, bytes.length - packet.applicationPayload.byteLength); // Header+Extensions
@@ -159,25 +176,27 @@ export class ExchangeManager {
         let message: DecodedMessage | undefined;
         if (packet.header.sessionType === SessionType.Unicast) {
             if (packet.header.sessionId === UNICAST_UNSECURE_SESSION_ID) {
-                if (this.#closing) return;
+                if (this.#isClosing) return;
                 const initiatorNodeId = packet.header.sourceNodeId ?? NodeId.UNSPECIFIED_NODE_ID;
                 session =
-                    this.#sessionManager.getUnsecureSession(initiatorNodeId) ??
-                    this.#sessionManager.createInsecureSession({
+                    this.#sessions.getUnsecuredSession(initiatorNodeId) ??
+                    this.#sessions.createUnsecuredSession({
+                        channel,
                         initiatorNodeId,
                     });
             } else {
-                session = this.#sessionManager.getSession(packet.header.sessionId);
+                session = this.#sessions.getSession(packet.header.sessionId);
             }
 
             if (session === undefined) {
-                throw new MatterFlowError(
-                    `Cannot find a session for ID ${packet.header.sessionId}${
+                logger.warn(
+                    `Ignoring message for unknown session ${Session.idStrOf(packet)}${
                         packet.header.sourceNodeId !== undefined
-                            ? ` and source NodeId ${packet.header.sourceNodeId}`
+                            ? ` from node ${hex.fixed(packet.header.sourceNodeId, 16)}`
                             : ""
                     }`,
                 );
+                return;
             }
 
             message = session.decode(packet, aad);
@@ -190,13 +209,13 @@ export class ExchangeManager {
                 isDuplicate = true;
             }
         } else if (packet.header.sessionType === SessionType.Group) {
-            if (this.#closing) return;
+            if (this.#isClosing) return;
             if (packet.header.sourceNodeId === undefined) {
                 throw new UnexpectedDataError("Group session message must include a source NodeId");
             }
 
             let key: Bytes;
-            ({ session, message, key } = this.#sessionManager.groupSessionFromPacket(packet, aad));
+            ({ session, message, key } = this.#sessions.groupSessionFromPacket(packet, aad));
 
             try {
                 session.updateMessageCounter(messageId, packet.header.sourceNodeId, key);
@@ -231,19 +250,18 @@ export class ExchangeManager {
             exId: message.payloadHeader.exchangeId,
             via: channel.name,
         });
+
         if (exchange !== undefined) {
-            if (
-                exchange.requiresSecureSession !== session.isSecure ||
-                exchange.session.id !== packet.header.sessionId ||
-                (exchange.isClosing && !isStandaloneAck)
-            ) {
+            this.#lifetime.details.exchange = exchange.idStr;
+            if (exchange.session.id !== packet.header.sessionId || (exchange.isClosing && !isStandaloneAck)) {
                 logger.debug(
-                    "Ignore « message because",
+                    exchange.via,
+                    "Ignore",
+                    Mark.INBOUND,
+                    "message because",
                     exchange.isClosing
                         ? "exchange is closing"
-                        : exchange.session.id !== packet.header.sessionId
-                          ? `session ID mismatch ${exchange.session.id} vs ${packet.header.sessionId}`
-                          : `session security requirements (${exchange.requiresSecureSession}) not fulfilled`,
+                        : `session ID mismatch (header session is ${Session.idStrOf(packet)}`,
                     messageDiagnostics,
                 );
 
@@ -257,10 +275,10 @@ export class ExchangeManager {
 
             await exchange.onMessageReceived(message, isDuplicate);
         } else {
-            if (this.#closing) return;
-            if (session.closingAfterExchangeFinished) {
+            if (this.#isClosing) return;
+            if (session.isClosing) {
                 throw new MatterFlowError(
-                    `Session with ID ${packet.header.sessionId} marked for closure, decline new exchange creation.`,
+                    `Declining new exchange because session ${Session.idStrOf(packet)} is closing`,
                 );
             }
 
@@ -273,7 +291,9 @@ export class ExchangeManager {
             // TODO When adding Group sessions, we need to check how to adjust that handling
             if (handlerSecurityMismatch) {
                 logger.debug(
-                    `Ignore « message because not matching the security requirements (${protocolHandler.requiresSecureSession} vs. ${session.isSecure})`,
+                    "Ignore",
+                    Mark.INBOUND,
+                    `message because not matching the security requirements (${protocolHandler.requiresSecureSession} vs. ${session.isSecure})`,
                     messageDiagnostics,
                 );
             }
@@ -285,29 +305,25 @@ export class ExchangeManager {
                 !handlerSecurityMismatch
             ) {
                 if (isStandaloneAck && !message.payloadHeader.requiresAck) {
-                    logger.debug("Ignore « unsolicited standalone ack message", messageDiagnostics);
+                    logger.debug("Ignore", Mark.INBOUND, "unsolicited standalone ack message", messageDiagnostics);
                     return;
                 }
 
-                const exchange = MessageExchange.fromInitialMessage(
-                    this.#messageExchangeContextFor(await this.#channelManager.getOrCreateChannel(channel, session)),
-                    message,
-                );
+                const exchange = MessageExchange.fromInitialMessage(this.#messageExchangeContextFor(session), message);
+                this.#lifetime.details.exchange = exchange.idStr;
                 this.#addExchange(exchangeIndex, exchange);
                 await exchange.onMessageReceived(message);
                 await protocolHandler.onNewExchange(exchange, message);
             } else if (message.payloadHeader.requiresAck) {
-                const exchange = MessageExchange.fromInitialMessage(
-                    this.#messageExchangeContextFor(await this.#channelManager.getOrCreateChannel(channel, session)),
-                    message,
-                );
+                const exchange = MessageExchange.fromInitialMessage(this.#messageExchangeContextFor(session), message);
+                this.#lifetime.details.exchange = exchange.idStr;
                 this.#addExchange(exchangeIndex, exchange);
                 await exchange.send(SecureMessageType.StandaloneAck, new Uint8Array(0), {
                     includeAcknowledgeMessageId: message.packetHeader.messageId,
                     protocolId: SECURE_CHANNEL_PROTOCOL_ID,
                 });
                 await exchange.close();
-                logger.debug("Ignore « unsolicited message", messageDiagnostics);
+                logger.debug("Ignore", Mark.INBOUND, "unsolicited message", messageDiagnostics);
             } else {
                 if (protocolHandler === undefined) {
                     throw new MatterFlowError(`Unsupported protocol ${message.payloadHeader.protocolId}`);
@@ -315,82 +331,25 @@ export class ExchangeManager {
                 if (isDuplicate) {
                     if (message.packetHeader.destGroupId === undefined) {
                         // Duplicate Non-Group messages are still interesting to log to know them
-                        logger.debug("Ignore « duplicate message", messageDiagnostics);
+                        logger.debug("Ignore", Mark.INBOUND, "duplicate message", messageDiagnostics);
                     }
                     return;
                 }
                 if (!isStandaloneAck) {
-                    logger.info("Discard « unexpected message", messageDiagnostics, Diagnostic.json(message));
+                    logger.info(
+                        "Discard",
+                        Mark.INBOUND,
+                        "unexpected message",
+                        messageDiagnostics,
+                        Diagnostic.json(message),
+                    );
                 }
             }
         }
     }
 
     async deleteExchange(exchangeIndex: number) {
-        const exchange = this.#exchanges.get(exchangeIndex);
-        if (exchange === undefined) {
-            logger.info(`Exchange with index ${exchangeIndex} to delete not found or already deleted.`);
-            return;
-        }
-        const { session } = exchange;
         this.#exchanges.delete(exchangeIndex);
-        if (NodeSession.is(session) && session.closingAfterExchangeFinished) {
-            logger.debug(
-                `Exchange index ${exchangeIndex} on Session ${session.name} is already marked for closure. Close session now.`,
-            );
-            try {
-                await this.#closeSession(session);
-            } catch (error) {
-                logger.error(`Error closing session ${session.name}. Ignoring.`, error);
-            }
-        }
-    }
-
-    async #closeSession(session: NodeSession) {
-        const sessionId = session.id;
-        const sessionName = session.name;
-
-        const asExchangeSession = session as { closedByExchange?: boolean };
-        if (asExchangeSession.closedByExchange) {
-            // Session already removed, so we do not need to close again
-            return;
-        }
-        asExchangeSession.closedByExchange = true;
-
-        for (const [_exchangeIndex, exchange] of this.#exchanges.entries()) {
-            if (exchange.session.id === sessionId) {
-                await exchange.destroy();
-            }
-        }
-        if (session.sendCloseMessageWhenClosing) {
-            let channel;
-            try {
-                channel = this.#channelManager.getChannelForSession(session);
-            } catch (e) {
-                logger.debug(`Not sending close for session ${sessionName}:`, e);
-                return;
-            }
-            logger.debug(`Channel for session ${sessionName} is ${channel?.name}`);
-            if (channel !== undefined) {
-                const exchange = this.initiateExchangeWithChannel(channel, SECURE_CHANNEL_PROTOCOL_ID);
-                logger.debug(`Initiated exchange ${exchange.id} to close session ${sessionName}`);
-                try {
-                    const messenger = new SecureChannelMessenger(exchange);
-                    await messenger.sendCloseSession();
-                    await messenger.close();
-                } catch (error) {
-                    if (error instanceof ChannelNotConnectedError) {
-                        logger.debug("Session already closed because channel is disconnected.");
-                    } else {
-                        logger.error("Error closing session", error);
-                    }
-                }
-                await exchange.destroy();
-            }
-        }
-        if (session.closingAfterExchangeFinished) {
-            await session.destroy(false, false);
-        }
     }
 
     #addExchange(exchangeIndex: number, exchange: MessageExchange) {
@@ -409,37 +368,39 @@ export class ExchangeManager {
             return;
         }
         const sessionExchanges = Array.from(this.#exchanges.values()).filter(
-            exchange => exchange.session.id === sessionId && !exchange.isClosing,
+            exchange => exchange.session.id === sessionId && !exchange.isClosing && exchange.isInitiator,
         );
-        if (sessionExchanges.length <= MAXIMUM_CONCURRENT_EXCHANGES_PER_SESSION) {
+        if (sessionExchanges.length <= MAXIMUM_CONCURRENT_OUTGOING_EXCHANGES_PER_SESSION) {
             return;
         }
         // let's use the first entry in the Map as the oldest exchange and close it
+        // TODO: Adjust this logic into a Exchange creation queue instead of hard closing
         const exchangeToClose = sessionExchanges[0];
-        logger.debug(`Closing oldest exchange ${exchangeToClose.id} for session ${sessionId}`);
-        exchangeToClose.close().catch(error => logger.error("Error closing exchange", error)); // TODO Promise??
+        logger.info(
+            exchangeToClose.via,
+            `Closing oldest exchange for session because of too many concurrent outgoing exchanges. Ensure to not send that many parallel messages to one peer.`,
+        );
+        logger.debug(exchangeToClose.via, "Closing oldest exchange");
+        this.#workers.add(exchangeToClose.close());
     }
 
-    calculateMaximumPeerResponseTimeMsFor(
-        channel: MessageChannel,
-        expectedProcessingTime = DEFAULT_EXPECTED_PROCESSING_TIME,
-    ) {
-        return channel.calculateMaximumPeerResponseTime(
-            channel.session.parameters,
-            this.#sessionManager.sessionParameters,
+    calculateMaximumPeerResponseTimeMsFor(session: Session, expectedProcessingTime = DEFAULT_EXPECTED_PROCESSING_TIME) {
+        return session.channel.calculateMaximumPeerResponseTime(
+            session.parameters,
+            this.#sessions.sessionParameters,
             expectedProcessingTime,
         );
     }
 
-    #messageExchangeContextFor(channel: MessageChannel): MessageExchangeContext {
+    #messageExchangeContextFor(session: Session): MessageExchangeContext {
         return {
-            channel,
-            localSessionParameters: this.#sessionManager.sessionParameters,
-            retry: number => this.#sessionManager.retry.emit(channel.session, number),
+            session,
+            localSessionParameters: this.#sessions.sessionParameters,
+            retry: number => this.#sessions.retry.emit(session, number),
         };
     }
 
-    #addListener(netInterface: ConnectionlessTransport) {
+    #addTransport(netInterface: ConnectionlessTransport) {
         const udpInterface = netInterface instanceof UdpInterface;
         this.#listeners.set(
             netInterface,
@@ -451,35 +412,54 @@ export class ExchangeManager {
                     return;
                 }
 
-                try {
-                    this.onMessage(socket, data).catch(error =>
-                        logger.info(
-                            `Error on channel ${socket.name}:`,
-                            error instanceof MatterError ? error.message : error,
-                        ),
-                    );
-                } catch (error) {
-                    logger.info(
-                        `Ignoring UDP message on channel ${socket.name} with error`,
-                        error instanceof MatterError ? error.message : error,
-                    );
-                }
+                this.#workers.add(this.#onMessage(socket, data));
             }),
         );
     }
 
-    #deleteListener(netInterface: ConnectionlessTransport) {
+    #deleteTransport(netInterface: ConnectionlessTransport) {
         const listener = this.#listeners.get(netInterface);
         if (listener === undefined) {
             return;
         }
         this.#listeners.delete(netInterface);
 
-        const closer = listener
-            .close()
-            .catch(e => logger.error("Error closing network listener", e))
-            .finally(() => this.#closers.delete(closer));
-        this.#closers.add(closer);
+        this.#workers.add(listener.close());
+    }
+
+    #addSession(session: Session) {
+        if (!(session instanceof NodeSession)) {
+            return;
+        }
+
+        let observers = this.#sessionObservers.get(session);
+        if (!observers) {
+            this.#sessionObservers.set(session, (observers = new ObserverGroup()));
+        }
+
+        observers.on(session.gracefulClose, () => this.#sendCloseSession(session));
+    }
+
+    #deleteSession(session: Session) {
+        const observers = this.#sessionObservers.get(session);
+        if (!observers) {
+            return;
+        }
+
+        observers.close();
+        this.#sessionObservers.delete(session);
+    }
+
+    async #sendCloseSession(session: NodeSession) {
+        await using exchange = this.initiateExchangeForSession(session, SECURE_CHANNEL_PROTOCOL_ID);
+        logger.debug(exchange.via, "Closing session");
+        try {
+            const messenger = new SecureChannelMessenger(exchange);
+            await messenger.sendCloseSession();
+            await messenger.close();
+        } catch (error) {
+            logger.error(exchange.via, "Error closing session:", error);
+        }
     }
 }