/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { Message, PacketHeader, SessionType } from "#codec/MessageCodec.js"; import { Mark } from "#common/Mark.js"; import { NetworkProfile } from "#peer/NetworkProfile.js"; import { PeerAckMissingError, PeerMessageMissingError, TransientPeerCommunicationError, } from "#peer/PeerCommunicationError.js"; import { GroupSession } from "#session/GroupSession.js"; import { Session } from "#session/Session.js"; import { SessionParameters } from "#session/SessionParameters.js"; import { Abort, AbortedError, asError, AsyncObservableValue, Bytes, causedBy, ClosedError, createPromise, CRYPTO_AEAD_MIC_LENGTH_BYTES, DataReadQueue, Diagnostic, Duration, Forever, hex, Instant, InternalError, Lifetime, Logger, MatterFlowError, Millis, NetworkError, Seconds, ServerAddress, ServerAddressUdp, Time, TimeoutError, Timer, Timestamp, } from "@matter/general"; import { BDX_PROTOCOL_ID, GroupId, NodeId, SECURE_CHANNEL_PROTOCOL_ID, SecureMessageType, Status, StatusResponseError, } from "@matter/types"; import { SessionClosedError, UnexpectedMessageError } from "./errors.js"; import { MessageChannel } from "./MessageChannel.js"; import { MRP } from "./MRP.js"; const logger = Logger.get("MessageExchange"); /** * How long a BDX peer waits for the next BDX message before it abandons the transfer. * * BDX peers bound a transfer by progress at the BDX layer, not by MRP: CHIP's OTA requestor aborts after this long * awaiting a response, and neither our acknowledgement nor the peer's own MRP retransmissions reset its clock. So an * MRP schedule that outlives this budget turns a recoverable block loss into a dead transfer. */ const BDX_PEER_RESPONSE_BUDGET = Seconds(30); /** Leaves the final attempt time to reach the peer while the budget is still open. */ const BDX_RESPONSE_BUDGET_MARGIN = Millis(100); /** Retransmission interval that still fits every attempt inside {@link BDX_PEER_RESPONSE_BUDGET}. */ const BDX_MAX_RETRANSMISSION_INTERVAL = Millis( BDX_PEER_RESPONSE_BUDGET / (MRP.MAX_TRANSMISSIONS - 1) - BDX_RESPONSE_BUDGET_MARGIN, ); export type ExchangeLogContext = Record; export interface ExchangeSendOptions { /** * The response to this send should be an ack only and no StatusResponse or such. If a StatusResponse is returned * then this is handled as error. */ expectAckOnly?: boolean; /** * If the message is part of a multiple message interaction, this flag indicates that it is not allowed * to establish a new exchange */ multipleMessageInteraction?: boolean; /** * Defined an expected processing time by the responder for the message. This is used to calculate the final * timeout for responses together with the normal retransmission logic when MRP is used. */ expectedProcessingTime?: Duration; /** * Sends the message without requesting acknowledgement, for a message whose delivery we deliberately do not * track — a Busy or CloseSession status report, or an ICD check-in on a session we are about to drop. * * MRP requests an ack for every message on an MRP session, so there is nothing to opt into: only suppression is * expressible. */ suppressAck?: true; /** * Disables the MRP logic which means that no retransmissions are done and receiving an ack is not awaited. */ disableMrpLogic?: boolean; /** Additional context information for logging to be included at the beginning of the Message log. */ logContext?: ExchangeLogContext; /** * Aborts sending. Before or during the first transmission the send rejects with {@link AbortedError} (cause: the * reason). While waiting for the ack it resolves if the reason is an {@link AbortedError}, otherwise it rejects with * the reason. */ abort?: AbortSignal; /** * Ends only the waits for the ack and for retransmissions; the message is still transmitted once, even when this * fired before. The send then resolves. Either this or {@link abort} ends the waits; only {@link abort} stops the * transmission. */ ackWaitAbort?: AbortSignal; /** Number of MRP transmissions, the first one included (default: MRP.MAX_TRANSMISSIONS) */ maxRetransmissions?: number; /** Maximum MRP retransmission time (default: unlimited) */ maxRetransmissionTime?: Duration; /** Initial MRP retransmission time (default: calculated as by Matter specification) */ initialRetransmissionTime?: Duration; /** * Time after the first transmission from which no further retransmission is sent (default: unlimited). It applies * only once {@link MRP.MAX_TRANSMISSIONS} transmissions went out, so the peer always gets the standard MRP budget. * Reaching it ends the send the same way as reaching {@link maxRetransmissions}, including the final wait for a * response that may still be on its way. */ retransmissionTimeLimit?: Duration; /** * Transmission number at which the MRP backoff schedule of this send starts (default: 0). Lets a new exchange * continue the schedule of one it replaces instead of falling back to the base interval. Does not count against * {@link maxRetransmissions}. */ backoffOffset?: number; /** Suppress peer-loss reporting for this send. OR'd with {@link MessageExchange.Options.suppressPeerLoss}. */ suppressPeerLoss?: boolean; } export interface ExchangeReceiveOptions { /** Aborts receiving; rejects with {@link AbortedError} (cause: the reason) unless a message is already queued. */ abort?: AbortSignal; timeout?: Duration; /** * Defined an expected processing time by the responder for the message. This is used to calculate the final * timeout for responses together with the normal retransmission logic when MRP is used. */ expectedProcessingTime?: Duration; /** Suppress peer-loss reporting for this receive. OR'd with {@link MessageExchange.Options.suppressPeerLoss}. */ suppressPeerLoss?: boolean; } /** * Message size overhead of a Matter message: * 26 (Matter Message Header) + 12 (Matter Payload Header) taken from https://github.com/project-chip/connectedhomeip/blob/2d97cda23024e72f36216900ca667bf1a0d9499f/src/system/SystemConfig.h#L327 * 16 byte MIC is then also needed to be excluded from the max payload size * Secure Extensions and Message Extensions need to be handled by exchange additionally! */ export const MATTER_MESSAGE_OVERHEAD = 26 + 12 + CRYPTO_AEAD_MIC_LENGTH_BYTES; /** * Interfaces {@link MessageExchange} with other components. */ export interface MessageExchangeContext { session: Session; localSessionParameters: SessionParameters; /** Additive MRP retransmission margin for our own (sender-side) network. */ localAdditionalMrpDelay: Duration; /** Fixed sender-side MRP backoff pad (e.g. an ICD's fast-polling interval), not amplified by backoff. */ localFixedMrpBackoff: Duration; peerLost(exchange: MessageExchange, cause: Error): Promise; /** @deprecated */ retry(number: number): void; } /** * A Matter "message exchange" is a sequence of messages associated with a single interaction. * * TODO - rewrite main send retransmission loop using sleeps instead of timers * TODO - track dangling promises (annotated with TODO) * TODO - replace throws with logging for some errors triggered by peer */ export class MessageExchange { static fromInitialMessage( context: MessageExchangeContext, initialMessage: Message, options?: MessageExchange.Options, ) { const { session } = context; return new MessageExchange({ context, isInitiator: false, peerSessionId: session.id, nodeId: initialMessage.packetHeader.destNodeId, peerNodeId: initialMessage.packetHeader.sourceNodeId, exchangeId: initialMessage.payloadHeader.exchangeId, protocolId: initialMessage.payloadHeader.protocolId, ...options, }); } static initiate( context: MessageExchangeContext, exchangeId: number, protocolId: number, options?: MessageExchange.Options, ) { const { session } = context; return new MessageExchange({ context, isInitiator: true, peerSessionId: session.peerSessionId, nodeId: session.nodeId, peerNodeId: session.peerNodeId, exchangeId, protocolId, ...options, }); } readonly #context: MessageExchangeContext; readonly #isInitiator: boolean; readonly #messagesQueue = new DataReadQueue(); readonly #lifetime: Lifetime; #onSend?: MessageExchange.SendNotifier; #onReceive?: MessageExchange.ReceiveNotifier; readonly #addressOverride?: ServerAddressUdp; #peerAdditionalMrpDelay?: Duration; readonly #suppressPeerLoss: boolean; #receivedMessageToAck: Message | undefined; #receivedMessageAckTimer = Time.getTimer("ack receipt timeout", MRP.STANDALONE_ACK_TIMEOUT, () => { if (this.#receivedMessageToAck !== undefined) { const messageToAck = this.#receivedMessageToAck; this.#receivedMessageToAck = undefined; // TODO await this.sendStandaloneAckForMessage(messageToAck).catch(error => logger.warn("An error happened when sending a standalone ack", error), ); } }); #closeTimer: Timer | undefined; #closeCause?: Error; #isDestroyed = false; #timedInteractionTimer: Timer | undefined; #used: boolean; readonly #peerSessionId: number; readonly #nodeId: NodeId | undefined; readonly #peerNodeId: NodeId | undefined; readonly #exchangeId: number; readonly #protocolId: number; readonly #closed = AsyncObservableValue(); readonly #closing = AsyncObservableValue(); #channel?: MessageChannel; // TODO - following are associated with current active transmission and should maybe go in a closure #sentMessageToAck?: Message; #sentMessageAckSuccess?: (message: Message | undefined) => void; #sentMessageAckFailure?: () => void; #sendOptions: ExchangeSendOptions = {}; #retransmissionCounter = 0; #totalRetransmissionCounter = 0; // counter for all messages within this exchange #messageSendCounter = 0; #messageReceivedCounter = 0; #retransmissionTimer?: Timer; /** A pending message whose ack wait ended: it still awaits its ack for close(), but is never transmitted again. */ #retransmissionEndedFor?: Message; #firstTransmissionAt?: Timestamp; #lastTransmissionAt?: Timestamp; #lastActive = Time.nowMs; constructor(config: MessageExchange.Config) { const { context, isInitiator, peerSessionId, nodeId, peerNodeId, exchangeId, protocolId, onSend, onReceive, network, peerAdditionalMrpDelay, addressOverride, suppressPeerLoss = false, } = config; this.#context = context; this.#isInitiator = isInitiator; this.#peerSessionId = peerSessionId; this.#nodeId = nodeId; this.#peerNodeId = peerNodeId; this.#exchangeId = exchangeId; this.#protocolId = protocolId; this.#onSend = onSend; this.#onReceive = onReceive; this.#addressOverride = addressOverride; this.#peerAdditionalMrpDelay = peerAdditionalMrpDelay; this.#suppressPeerLoss = suppressPeerLoss; const { activeThreshold, activeInterval, idleInterval } = this.session.parameters; this.#used = !isInitiator; // If we are the initiator then exchange was not used yet, so track it const { session } = context; logger.debug( "New exchange", isInitiator ? Mark.OUTBOUND : Mark.INBOUND, this.via, Diagnostic.dict({ protocol: this.#protocolId, peerSess: Session.idStrOf(this.#peerSessionId), address: addressOverride ? ServerAddress.urlFor(addressOverride) : undefined, SAT: activeThreshold !== undefined ? Duration.format(activeThreshold) : undefined, SAI: activeInterval !== undefined ? Duration.format(activeInterval) : undefined, SII: idleInterval !== undefined ? Duration.format(idleInterval) : undefined, maxTrans: MRP.MAX_TRANSMISSIONS, exchangeFlags: Diagnostic.asFlags({ MRP: this.session.usesMrp, I: this.isInitiator, ...(network ? { [network.id]: true } : {}), }), }), ); session.addExchange(this); // Only do partial via because other details are in parent lifetime this.#lifetime = this.#context.session.join("exchange", Diagnostic.via(hex.word(this.id))); } get context() { return this.#context; } get isInitiator() { return this.#isInitiator; } /** * Overrides the medium-derived MRP retransmission margin for this exchange. * * An exchange the peer initiated has no construction options to carry {@link MessageExchange.Options * .peerAdditionalMrpDelay}, so a protocol that knows better than the peer's medium — BDX with a per-transfer * margin, say — applies it here once it has adopted the exchange. */ set peerAdditionalMrpDelay(margin: Duration) { this.#peerAdditionalMrpDelay = margin; } /** * Sets the receive-notifier when none was provided at construction time. This allows code that obtains an exchange * after its creation (e.g. via protocol handler dispatch) to hook into message receipt. */ set onReceive(fn: MessageExchange.ReceiveNotifier) { if (this.#onReceive === undefined) { this.#onReceive = fn; } } /** * Sets the send-notifier when none was provided at construction time. Mirrors {@link onReceive} for code that * obtains an exchange after its creation and needs to observe transmissions. */ set onSend(fn: MessageExchange.SendNotifier) { if (this.#onSend === undefined) { this.#onSend = fn; } } /** Emits when the exchange is actually closed. This happens after all Retries and Communication are done. */ get closed() { return this.#closed; } get considerClosed() { return this.#closed.value || (this.#isInitiator && this.#closing.value); } /** Timestamp of the last send or receive on this exchange, used to evict the least-recently-active exchange. */ get lastActive() { return this.#lastActive; } #notifySent() { this.#lastActive = Time.nowMs; this.session.notifyActivity(false); } /** * Emit when the exchange is closing, but not yet closed. We only wait for acks and retries to happen, but the * actual interaction logic is already done. */ get closing() { return this.#closing; } get id() { return this.#exchangeId; } get idStr() { return hex.word(this.#exchangeId); } get session() { return this.context.session; } /** Number of retransmissions of the current outstanding message (resets on ack or new send). */ get retransmissionCount() { return this.#retransmissionCounter; } /** * True while a message we sent still awaits peer acknowledgement. The exchange cannot send a new message in this * state, so best-effort status reports (e.g. PASE/CASE InvalidParam on failure) must be skipped: the peer never * acked our prior message, so the send would only fail with a flow error. */ get hasUnackedMessage() { return this.#sentMessageToAck !== undefined; } get channel() { if (this.#channel === undefined) { this.#channel = this.session.channel; } return this.#channel; } /** * Max Payload size of the exchange which bases on the maximum payload size of the channel reduced by Matter * protocol overhead. */ get maxPayloadSize() { // TODO: Whenever we add support for MessageExtensions or Secured Message extensions then these need to be also // considered here and their size needs to be subtracted from the maxPayloadSize of the channel. return this.channel.maxPayloadSize - MATTER_MESSAGE_OVERHEAD; } join(...name: unknown[]) { return this.#lifetime.join(...name); } async onMessageReceived(message: Message, duplicate = false) { logger.debug("Message", Mark.INBOUND, Message.diagnosticsOf(this, message, { duplicate })); this.#messageReceivedCounter++; // Adjust the incoming message when ack was required, but this exchange does not use it to skip all relevant logic if (message.payloadHeader.requiresAck && !this.session.usesMrp) { logger.debug("Ignoring ack-required flag because MRP is not used for this exchange"); message.payloadHeader.requiresAck = false; } const { packetHeader: { messageId }, payloadHeader: { requiresAck, ackedMessageId, protocolId, messageType }, } = message; const isStandaloneAck = SecureMessageType.isStandaloneAck(protocolId, messageType); const isStatusReport = SecureMessageType.isStatusReport(protocolId, messageType); if (protocolId !== this.#protocolId && !isStandaloneAck && !isStatusReport) { throw new MatterFlowError( `Drop received a message for an unexpected protocol. Expected: ${this.#protocolId}, received: ${protocolId}`, ); } this.#lastActive = Time.nowMs; this.#onReceive?.(message, duplicate); if (duplicate) { // Received a message retransmission, but the reply is not ready yet, ignoring if (requiresAck) { // A retransmission of our pending message acknowledges this duplicate by definition, so it stands in // for the standalone ack. Only a transmission that actually reached the channel counts. if (!this.#kickRetransmissionForLiveness(message)) { await this.sendStandaloneAckForMessage(message); } } return; } if (messageId === this.#sentMessageToAck?.payloadHeader.ackedMessageId) { // Received a message retransmission. This means that the other side didn't get our ack // Resending the previous reply message which contains the ack using _acking = this.join("resending ack"); this.#messageSendCounter++; this.#lastTransmissionAt = Time.nowMs; await this.channel.send(this.#sentMessageToAck, { exchange: this, addressOverride: this.#addressOverride }); return; } const sentMessageIdToAck = this.#sentMessageToAck?.packetHeader.messageId; if (sentMessageIdToAck !== undefined) { if (ackedMessageId === undefined) { // The message has no ack, but one previous message sent still needs to be acked. throw new MatterFlowError("Previous message ack is missing"); } else if (ackedMessageId !== sentMessageIdToAck) { // The message has an ack for another message. if (isStandaloneAck) { // Ignore if this is a standalone ack, probably this was a retransmission. } else { throw new MatterFlowError( `Incorrect ack received. Expected ${hex.fixed(sentMessageIdToAck, 8)}, received: ${hex.fixed(ackedMessageId, 8)}`, ); } } else { // The other side has received our previous message this.#retransmissionTimer?.stop(); this.#retransmissionCounter = 0; this.#sentMessageAckSuccess?.(message); this.#sentMessageAckSuccess = undefined; this.#sentMessageAckFailure = undefined; this.#sentMessageToAck = undefined; if (isStandaloneAck && this.#closeTimer !== undefined) { // All retransmissions done and in closing, no need to wait further return this.#close(); } } } if (isStandaloneAck) { // Don't include standalone acks in the message stream return; } if (requiresAck) { // We still have a message to ack, so ack the old one as standalone ack directly if (this.#receivedMessageToAck !== undefined) { this.#receivedMessageAckTimer.stop(); await this.sendStandaloneAckForMessage(this.#receivedMessageToAck); } this.#receivedMessageToAck = message; this.#receivedMessageAckTimer.start(); } this.#messagesQueue.write(message); } /** * Retransmits the pending message early when a duplicate proves both that the peer is awake right now and that our * pending reply never reached it. A backoff sized for an idle peer would otherwise spend a window we know is open, * which for a sleepy peer mid-transfer may not reopen for a long time. * * This departs from the retransmission schedule of {@link MatterSpecification.v161.Core} § 4.12.2.1 and, when it * transmits, from the standalone ack of § 4.12.5.2.2 — the retransmission carries that ack instead. Both are * confined to BDX, where transfers are long-running and lock-step makes the predicate unambiguous. * * Returns true only if a transmission actually reached the channel, in which case the caller must not send a * standalone ack: the transmitted message already acknowledges the duplicate that triggered it. * * {@link BDX_MAX_RETRANSMISSION_INTERVAL} currently bounds what this can save. It earns its keep again for any * peer whose response budget is larger than CHIP's, or if that cap is ever relaxed. */ #kickRetransmissionForLiveness(duplicate: Message) { if (this.#protocolId !== BDX_PROTOCOL_ID || this.considerClosed) { return false; } // A running timer also tells us no send is in flight, so we cannot transmit on top of one const pending = this.#sentMessageToAck; const timer = this.#retransmissionTimer; if (pending === undefined || timer === undefined || !timer.isRunning) { return false; } if (duplicate.packetHeader.messageId !== pending.payloadHeader.ackedMessageId) { return false; } // Taking the last slot early would leave the scheduled attempt with none, and MRP would report the peer as // unresponsive without ever having retried inside the window we are trying to hit if (this.#isTransmissionBudgetSpent(this.#retransmissionCounter + 1)) { return false; } const { activeInterval, activeThreshold } = this.session.parameters; // Never transmit faster than the cadence the schedule itself uses, medium margin included const cadence = Millis(activeInterval + this.#sendAdditionalDelay); const elapsed = this.#lastTransmissionAt === undefined ? Forever : Timestamp.delta(this.#lastTransmissionAt); if (elapsed < cadence) { return false; } // Only worth a slot if the peer would fall asleep again before the scheduled attempt; a wait it can stay // awake through costs nothing to honour const remaining = Millis(Math.max(0, timer.interval - elapsed)); if (remaining <= activeThreshold) { return false; } logger.debug( this.via, "Kicking retransmission because peer proved liveness", Diagnostic.dict({ waited: Duration.format(elapsed), saved: Duration.format(remaining), "retrans#": this.#retransmissionCounter, }), ); timer.stop(); return this.#retransmitMessage( pending, this.#sendOptions.expectedProcessingTime ?? MRP.DEFAULT_EXPECTED_PROCESSING_TIME, ); } async send(messageType: number, payload: Bytes, options: ExchangeSendOptions = {}) { if (this.#closeCause) { throw new ClosedError("Exchange is closed", { cause: this.#closeCause }); } this.#sendOptions = options; this.#retransmissionCounter = 0; try { await this.#send(messageType, payload); } catch (e) { if ( this.#reportsPeerLoss(options.suppressPeerLoss) && causedBy(e, TransientPeerCommunicationError, TimeoutError, NetworkError) ) { await this.#context.peerLost(this, asError(e)); } throw e; } } /** * 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 && !this.session.suppressPeerLoss && suppressedForOperation !== true && this.#messageReceivedCounter === 0 ); } async #send(messageType: number, payload: Bytes, standaloneAckMessageId?: number) { const { expectAckOnly = false, disableMrpLogic, ackWaitAbort, expectedProcessingTime = MRP.DEFAULT_EXPECTED_PROCESSING_TIME, logContext = {}, } = this.#sendOptions; using abort = new Abort(this.#sendOptions); using waiting = new Abort({ abort: [abort, ackWaitAbort] }); const isStandaloneAck = standaloneAckMessageId !== undefined; if (standaloneAckMessageId !== undefined) { if (!this.session.usesMrp) { throw new InternalError("Cannot include an acknowledge message ID when MRP is not used"); } if (messageType !== SecureMessageType.StandaloneAck) { throw new InternalError("Cannot override an acknowledge message ID for non-standalone acks"); } } const requiresAck = !this.#sendOptions.suppressAck && this.session.usesMrp && !isStandaloneAck; // StandaloneAck and StatusReport are SecureChannel messages and are always sent via SECURE_CHANNEL_PROTOCOL_ID // regardless of the exchange's protocol (Matter spec 4.10). const isStatusReport = messageType === SecureMessageType.StatusReport; const protocolId = isStandaloneAck || isStatusReport ? SECURE_CHANNEL_PROTOCOL_ID : this.#protocolId; if (isStandaloneAck && !this.session.usesMrp) { return; } if (this.#sentMessageToAck !== undefined && !isStandaloneAck) { throw new MatterFlowError( `The previous message ${Message.via(this, this.#sentMessageToAck)} has not been acked yet, cannot send a new message`, ); } this.#used = true; this.#messageSendCounter++; this.#notifySent(); let ackedMessageId = standaloneAckMessageId; if (ackedMessageId === undefined && this.session.usesMrp) { ackedMessageId = this.#receivedMessageToAck?.packetHeader.messageId; if (ackedMessageId !== undefined) { this.#receivedMessageAckTimer.stop(); this.#receivedMessageToAck = undefined; } } let packetHeader: PacketHeader; if (this.session.type === SessionType.Unicast) { const messageId = isStandaloneAck ? await this.session.getIncrementedMessageCounter() // Standalone acks always need to be sendable : await abort.attempt(this.session.getIncrementedMessageCounter()); if (messageId === undefined) { return; } packetHeader = { sessionId: this.#peerSessionId, sessionType: SessionType.Unicast, messageId, destNodeId: this.#peerNodeId, sourceNodeId: this.#nodeId, hasPrivacyEnhancements: false, // Privacy is only defined for group messages isControlMessage: false, hasMessageExtensions: false, }; } else if (this.session.type === SessionType.Group) { const session = this.session; if (!GroupSession.is(session)) { throw new InternalError("Session is not a GroupSession, but session type is Group."); } const peerNodeId = this.#peerNodeId; if (peerNodeId === undefined) { throw new InternalError("Group message exchange requires a peer NodeId."); } const destGroupId = GroupId.fromNodeId(peerNodeId); if (destGroupId === 0) { throw new InternalError(`Invalid GroupId extracted from NodeId ${peerNodeId}`); } const messageId = await abort.attempt(this.session.getIncrementedMessageCounter()); if (messageId === undefined) { return; } packetHeader = { sessionId: this.#peerSessionId, sessionType: SessionType.Group, messageId, destGroupId, // The fabric's node ID can change during the exchange's lifetime (NOC update), so it is read per message sourceNodeId: session.nodeId, hasPrivacyEnhancements: this.session.usePrivacy, isControlMessage: false, hasMessageExtensions: false, }; } else { throw new InternalError(`Unknown session type: ${this.session.type}`); } const message: Message = { packetHeader, payloadHeader: { exchangeId: this.#exchangeId, protocolId, messageType, isInitiatorMessage: this.isInitiator, requiresAck, ackedMessageId, hasSecuredExtension: false, }, payload, }; let ackPromise: Promise | undefined; if (this.session.usesMrp && message.payloadHeader.requiresAck && !disableMrpLogic) { this.#sentMessageToAck = message; const backOff = this.#mrpResubmissionBackOffTime; logContext.backOff = Duration.format(backOff); this.#retransmissionTimer = Time.getTimer(`retransmitting ${Message.via(this, message)}`, backOff, () => this.#retransmitMessage(message, expectedProcessingTime), ); const { promise, resolver } = createPromise(); ackPromise = promise; this.#sentMessageAckSuccess = resolver; const startedWaitingAt = Time.nowMs; this.#sentMessageAckFailure = () => { abort.abort(new PeerAckMissingError(Timestamp.delta(startedWaitingAt))); }; } if (ackPromise !== undefined) { this.#firstTransmissionAt = Time.nowUs; } this.#onSend?.(message, 0); using sending = this.join("sending", Diagnostic.strong(Message.via(this, message))); if (isStandaloneAck) { await this.channel.send(message, { exchange: this, addressOverride: this.#addressOverride }); } else { await abort.attempt( this.channel.send(message, { exchange: this, logContext, addressOverride: this.#addressOverride }), ); } if (waiting.aborted) { this.#endAckWait(); return; } if (!isStandaloneAck) { this.#lastTransmissionAt = Time.nowMs; } if (ackPromise !== undefined) { this.#retransmissionCounter = 0; this.#retransmissionTimer?.start(); // Await response. Resolves with message when received, undefined when aborted, and rejects on timeout. // Use race (not attempt) so that on abort we fall through to the cleanup block below // instead of throwing immediately — we need to stop the retransmission timer first. using _waiting = sending.join("waiting for ack"); const responseMessage = await waiting.race(ackPromise); if (waiting.aborted) { // Aborted — stop the retransmission timer immediately so we don't keep sending // packets to an unreachable peer while the exchange is being torn down. // Leave #sentMessageToAck and the ack callbacks intact so that exchange.close() // still sees the pending ack and can handle cleanup properly. this.#endAckWait(); this.#retransmissionTimer?.stop(); if (abort.aborted && !causedBy(abort.reason, AbortedError)) { throw abort.reason; } return; } this.#sentMessageAckSuccess = undefined; this.#sentMessageAckFailure = undefined; if (responseMessage) { // If we only expect an Ack without data but got data, throw an error const { payloadHeader: { protocolId, messageType }, } = responseMessage; if (expectAckOnly && !SecureMessageType.isStandaloneAck(protocolId, messageType)) { throw new UnexpectedMessageError("Expected ack only", this.session, responseMessage); } } } } async nextMessage(options?: ExchangeReceiveOptions) { try { return await this.#nextMessage(options); } catch (e) { if (this.#reportsPeerLoss(options?.suppressPeerLoss) && causedBy(e, TransientPeerCommunicationError)) { await this.#context.peerLost(this, asError(e)); } throw e; } } async #nextMessage(options?: ExchangeReceiveOptions) { let timeout: Duration | undefined; if (options?.timeout !== undefined) { timeout = options.timeout; } else if (!this.session.isClosed) { timeout = this.channel.calculateMaximumPeerResponseTime( this.session.parameters, this.context.localSessionParameters, options?.expectedProcessingTime, undefined, this.#sendAdditionalDelay, this.#context.localFixedMrpBackoff, ); } using localAbort = new Abort({ timeout, abort: options?.abort, timeoutHandler: () => { throw new PeerMessageMissingError(timeout!); }, }); return await this.#messagesQueue.read(localAbort); } async sendStandaloneAckForMessage(message: Message) { const { packetHeader: { messageId }, payloadHeader: { requiresAck }, } = message; if (!requiresAck || !this.session.usesMrp) { return; } await this.#send(SecureMessageType.StandaloneAck, new Uint8Array(0), messageId); } /** * Whether the transmission with this number may not be sent any more, by either {@link * ExchangeSendOptions.maxRetransmissions} or {@link ExchangeSendOptions.retransmissionTimeLimit}. */ #isTransmissionBudgetSpent(transmissionNumber: number) { const { maxRetransmissions = MRP.MAX_TRANSMISSIONS, retransmissionTimeLimit } = this.#sendOptions; if (transmissionNumber >= maxRetransmissions) { return true; } return ( retransmissionTimeLimit !== undefined && transmissionNumber >= MRP.MAX_TRANSMISSIONS && this.#firstTransmissionAt !== undefined && Timestamp.delta(this.#firstTransmissionAt, Time.nowUs) >= retransmissionTimeLimit ); } /** * Transmits the pending message again. Returns whether a transmission was actually started: the budget may be * spent, in which case this only schedules the final wait, and a caller that treats "attempted" as "sent" would * drop whatever the transmission was meant to convey. */ #retransmitMessage(message: Message, expectedProcessingTime?: Duration) { // The message may have been acked, or its ack wait ended, while an earlier transmission of it was still in // flight. Its timers must neither outlive it nor spend the retransmission budget of whatever is pending now. if (!this.#retransmits(message)) { return false; } this.#retransmissionCounter++; this.#totalRetransmissionCounter++; if (this.considerClosed || this.#isTransmissionBudgetSpent(this.#retransmissionCounter)) { // Ok all resubmissions are done, but we need to wait a bit longer because of processing time and the // resubmissions from the other side if (expectedProcessingTime && !this.considerClosed) { // We already have waited after the last message was sent, so deduct this time from the final wait time const finalWaitTime = Millis( this.channel.calculateMaximumPeerResponseTime( this.session.parameters, this.context.localSessionParameters, expectedProcessingTime, undefined, this.#sendAdditionalDelay, this.#context.localFixedMrpBackoff, ) - (this.#retransmissionTimer?.interval ?? Instant), ); if (finalWaitTime > 0) { this.#retransmissionCounter--; // We will not resubmit the message again this.#totalRetransmissionCounter--; logger.debug( `Message ${Message.via(this, message)}: Wait additional ${Duration.format(finalWaitTime)} for processing time and peer resubmissions after all our resubmissions`, ); this.#retransmissionTimer = Time.getTimer( `waiting after resubmissions for ${Message.via(this, message)}`, finalWaitTime, () => this.#retransmitMessage(message), ).start(); return false; } } // All resubmissions done and no expected processing time, close directly if (this.#sentMessageToAck !== undefined && this.#sentMessageAckFailure !== undefined) { this.#receivedMessageToAck = undefined; this.#sentMessageAckFailure(); this.#sentMessageAckFailure = undefined; this.#sentMessageAckSuccess = undefined; } if (this.#closeTimer !== undefined) { // All resubmissions done and in closing, no need to wait further // TODO await this.#close().catch(error => logger.warn("Error closing exchange", error)); } return false; } this.#messageSendCounter++; this.#notifySent(); this.#lastTransmissionAt = Time.nowMs; this.context.retry(this.#retransmissionCounter); const resubmissionBackoffTime = this.#mrpResubmissionBackOffTime; this.#onSend?.(message, this.#retransmissionCounter); // TODO await this.channel .send(message, { exchange: this, logContext: { "retrans#": this.#retransmissionCounter, backoff: Duration.format(resubmissionBackoffTime), }, addressOverride: this.#addressOverride, }) .then(() => this.#initializeResubmission(message, resubmissionBackoffTime, expectedProcessingTime)) .catch(error => { logger.warn(`Error retransmitting ${Message.via(this, message)}:`, error); if (error instanceof SessionClosedError) { this.#close().catch(error => logger.warn("An error happened when closing the exchange", error)); } else { this.#initializeResubmission(message, resubmissionBackoffTime, expectedProcessingTime); } }); return true; } /** * Ends the ack wait of the message awaiting an ack. It stays pending for close() but is never transmitted again. * Standalone acks never await one, so they cannot take its place. */ #endAckWait() { this.#retransmissionEndedFor = this.#sentMessageToAck; } #retransmits(message: Message) { return this.#sentMessageToAck === message && this.#retransmissionEndedFor !== message; } #initializeResubmission(message: Message, resubmissionBackoffTime: Duration, expectedProcessingTimeMs?: Duration) { // An ack may have landed, or the ack wait ended, while the transmission we are following up on was in flight; // a timer armed then would retransmit a message nobody waits for if (!this.#retransmits(message)) { return; } this.#retransmissionTimer = Time.getTimer("Message retransmission", resubmissionBackoffTime, () => this.#retransmitMessage(message, expectedProcessingTimeMs), ).start(); } [Symbol.asyncDispose]() { return this.destroy(); } async destroy() { if (this.#isDestroyed) { return; } this.#isDestroyed = true; if (this.#closeTimer === undefined && this.#receivedMessageToAck !== undefined) { this.#receivedMessageAckTimer.stop(); const messageToAck = this.#receivedMessageToAck; this.#receivedMessageToAck = undefined; try { await this.sendStandaloneAckForMessage(messageToAck); } catch (error) { logger.warn("An error happened when closing the exchange", error); } } await this.#close(); } startTimedInteraction(timeout: Duration) { if (this.#timedInteractionTimer !== undefined && this.#timedInteractionTimer.isRunning) { this.#timedInteractionTimer.stop(); throw new StatusResponseError("Timed interaction already running for this exchange", Status.InvalidAction); } logger.debug( "Starting timed interaction", Mark.INBOUND, this.channel.name, Diagnostic.dict({ exId: this.#exchangeId, timeout: Duration.format(timeout) }), ); this.#timedInteractionTimer = Time.getTimer("Timed interaction", timeout, () => { logger.debug( "Timed interaction timeout!", Diagnostic.dict({ exId: this.#exchangeId, via: this.channel.name }), ); }).start(); } clearTimedInteraction() { if (this.#timedInteractionTimer !== undefined) { logger.debug( "Clearing timed interaction", Diagnostic.dict({ exId: this.#exchangeId, via: this.channel.name }), ); this.#timedInteractionTimer.stop(); this.#timedInteractionTimer = undefined; } } hasTimedInteraction() { return this.#timedInteractionTimer !== undefined; } hasActiveTimedInteraction() { return this.#timedInteractionTimer !== undefined && this.#timedInteractionTimer.isRunning; } hasExpiredTimedInteraction() { return this.#timedInteractionTimer !== undefined && !this.#timedInteractionTimer.isRunning; } /** * Closes the exchange. * * If cause is defined, the exchange is closed immediately, even if there are still messages to send. Further * attempts at communicating via the exchange will throw this error. * * If cause is undefined, the exchange is closed only after all messages have been sent. */ async close(cause?: Error) { if (this.#isDestroyed) { return; } using closing = this.#lifetime.closing(); if (this.#closeTimer !== undefined) { if (cause) { // Force close does not wait any longer this.#closeTimer.stop(); return this.#close(cause); } // close was already called, so let retries happen because close not forced return; } if (!this.#used) { // The exchange was never in use, so we can close it directly // If we see that in the wild, we should fix the reasons logger.info(this.via, `Exchange never used, closing directly`); return this.#close(cause); } if (!this.#closed.value) { using _emitting = closing.join("emitting"); await this.#closing.emit(true); } // A closing handler may have already completed the close (e.g. aborting the exchange) if (this.#closed.value) { return; } if (this.#receivedMessageToAck !== undefined) { this.#receivedMessageAckTimer.stop(); const messageToAck = this.#receivedMessageToAck; this.#receivedMessageToAck = undefined; try { using _acking = closing.join("acking"); await this.sendStandaloneAckForMessage(messageToAck); } catch (error) { logger.warn(this.via, `Unhandled error closing exchange`, error); } if (cause || this.#sentMessageToAck === undefined) { // We have sent the Ack and there's nothing left waiting for a peer ack, close directly await this.#close(cause); return; } } else if (this.#sentMessageToAck === undefined || cause) { // No message left that we need to ack and no sent message left that waits for an ack, close directly await this.#close(cause); return; } // Wait until all potential outstanding Resubmissions are done (up to default of MRP.MAX_TRANSMISSIONS), also // for Standalone-Acks. // // We might wait a bit longer than needed, but because this is mainly a failsafe mechanism, it is acceptable. // Normal this timer is cancelled before it triggers when all retries are done. let maxResubmissionTime = Instant; for (let i = this.#retransmissionCounter; i <= MRP.MAX_TRANSMISSIONS; i++) { maxResubmissionTime = Millis( maxResubmissionTime + this.channel.getMrpResubmissionBackOffTime( i, undefined, true, this.#sendAdditionalDelay, this.#context.localFixedMrpBackoff, ), ); } this.#closeTimer = Time.getTimer( `Exchange ${this.via} close`, maxResubmissionTime, async () => await this.#close(cause), ).start(); } async #close(cause?: Error) { using _closing = this.#lifetime.closing(); // Cleanup must repeat: a send may have started after an earlier close. Only the notification is once-only. const wasClosed = this.#closed.value; if (this.#closeCause === undefined) { this.#closeCause = cause; } try { this.#retransmissionTimer?.stop(); this.#receivedMessageAckTimer.stop(); this.#sentMessageAckSuccess?.(undefined); this.#closeTimer?.stop(); this.#timedInteractionTimer?.stop(); this.#messagesQueue.close(this.#closeCause); } finally { if (!wasClosed) { await this.#closed.emit(true); } } } get via() { if (this.session === undefined) { return Diagnostic.via(`${Mark.EXCHANGE}${this.idStr}`); } return Diagnostic.via(`${this.session.via}${Mark.EXCHANGE}${this.idStr}`); } /** * Expose some diagnostics for logging. * For simply one message exchanges without retransmissions nothing will be exposed */ get diagnostics() { if ( this.#totalRetransmissionCounter === 0 && this.#messageSendCounter === 1 && this.#messageReceivedCounter === 1 ) { return ""; } return `${this.#messageReceivedCounter}${Mark.TRANSFERRED}${this.#messageSendCounter}${this.#totalRetransmissionCounter > 0 ? `+${this.#totalRetransmissionCounter}` : ""}`; } /** * Backoff of a first transmission on the base MRP schedule, without the schedule options of the current send. */ get #baseBackOff() { return this.#backOffFor(0, {}); } get #mrpResubmissionBackOffTime() { return this.#backOffFor(this.#retransmissionCounter); } /** * Amplified backoff addition applied to our sends: the larger of our own and the peer's network-profile delay for * this exchange's traffic class. */ get #sendAdditionalDelay() { const peerMargin = this.#peerAdditionalMrpDelay ?? MRP.marginFor(this.session.peerMrpMargins, this.#protocolId); return Duration.max(this.#context.localAdditionalMrpDelay, peerMargin ?? Millis(0)); } /** * Scheduled MRP backoff for a given (re)transmission number, after the send-option overrides. * * The cap never drops below the peer's idle interval: a peer whose idle base backoff already exceeds * maxRetransmissionTime must not be retried faster than its own idle cadence. * * BDX overrides even that floor. Its schedule has to fit the peer's response budget, and the idle cadence does not * apply mid-transfer: per {@link MatterSpecification.v161.Core} § 4.12.2.1 a peer awaiting an acknowledgement is in * active mode, because it holds an open exchange. */ #backOffFor( retransmissionCount: number, { backoffOffset = 0, initialRetransmissionTime, }: Pick = this.#sendOptions, ) { let backOff = this.channel.getMrpResubmissionBackOffTime( retransmissionCount + backoffOffset, undefined, false, this.#sendAdditionalDelay, this.#context.localFixedMrpBackoff, ); if (initialRetransmissionTime !== undefined) { backOff = Millis(backOff + initialRetransmissionTime); } const idleInterval = this.session.parameters.idleInterval; let cap = Duration.max(this.#sendOptions.maxRetransmissionTime ?? Forever, idleInterval); if (this.#protocolId === BDX_PROTOCOL_ID) { cap = Duration.min(cap, BDX_MAX_RETRANSMISSION_INTERVAL); } return Duration.min(backOff, cap); } /** * How much restarting on a new exchange with the base MRP schedule would shorten the wait until the next * (re)transmission. The base schedule has no {@link ExchangeSendOptions.backoffOffset} and no * {@link ExchangeSendOptions.initialRetransmissionTime}. Roughly zero near the base interval — e.g. an idle * peer, whose fresh interval is just as slow. */ get retransmissionRestartSaving(): Duration { // No pending retransmit → nothing for a restart to shorten → report no saving so the kick is suppressed. const currentWait = this.#retransmissionTimer?.interval; if (currentWait === undefined) { return Instant; } // Read the live timer's real interval (margins/jitter/cap baked in), not a freshly recomputed random one. return Duration.max(Instant, Millis(currentWait - this.#baseBackOff)); } } export namespace MessageExchange { export interface Options { /** * Invoked when a message transmits */ onSend?: SendNotifier; /** * Invoked upon message receipt. */ onReceive?: ReceiveNotifier; /** * Network profile governing exchange throttling. Retained for diagnostics; MRP backoff derives from * {@link peerAdditionalMrpDelay} instead, so an explicit throttle override (e.g. "unlimited") does not * affect retransmission timing. */ network?: NetworkProfile; /** * Additive MRP retransmission margin for the peer's network medium. Sourced independently of * {@link network} so concurrency overrides cannot strip the medium-correct margin (e.g. thread's). * * Overrides {@link Session.peerMrpMargins}, which supplies the margin for exchanges created without this * option (notably peer-initiated ones). */ peerAdditionalMrpDelay?: Duration; /** * Optional address override for this exchange. When set, messages are sent to this address * 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 { context: MessageExchangeContext; isInitiator: boolean; peerSessionId: number; nodeId?: NodeId; peerNodeId?: NodeId; exchangeId: number; protocolId: number; } /** * Callback invoked by exchange before message transmission. */ export type SendNotifier = (message: Message, retransmission: number) => void; /** * Callback invoked by exchange after message receipt. */ export type ReceiveNotifier = (message: Message, duplicate: boolean) => void; }