/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { InteractionSettings } from "#action/InteractionSettings.js"; import { PeerAddress } from "#peer/PeerAddress.js"; import { ExchangeManager } from "#protocol/ExchangeManager.js"; import { MessageExchange } from "#protocol/MessageExchange.js"; import { NodeSession } from "#session/NodeSession.js"; import { SecureSession } from "#session/SecureSession.js"; import { ChannelType, Duration, ServerAddressUdp } from "@matter/general"; import { INTERACTION_PROTOCOL_ID } from "@matter/types"; import { MRP } from "./MRP.js"; /** * Message exchange configuration options. */ export interface NewExchangeOptions extends Omit { /** * The protocol for the message exchange. * * Defaults to {@link INTERACTION_PROTOCOL_ID}. */ protocol?: number; /** * The name of the logical {@link PeerNetwork}. * * By default, matter.js selects a network based on the node's physical properties. Use "unlimited" to disable * rate limiting. */ network?: string; /** * Per-call override for the peer-medium MRP retransmission margin. When omitted the margin derives from the * peer's network medium, independent of any {@link network} throttle override. */ additionalMrpDelay?: Duration; /** * Optional address override for the exchange. When set, messages are sent to this address * instead of the session's default peer address. */ addressOverride?: ServerAddressUdp; /** * When true, requires an existing session and does not attempt to establish a new one. * The exchange creation fails if no active session is available. */ requireExistingSession?: boolean; /** Required transport type for this exchange. If set, only sessions of this transport type are used. */ requiredTransport?: ChannelType; /** * Per-call soft transport preference. Honored only when the peer advertises matching server * capability; otherwise the connect path falls back to UDP. Has no effect when * {@link requiredTransport} is set. */ preferredTransport?: ChannelType; } /** Why a reachability check was requested. Gates entry conditions, not the probe mechanics. */ export type ReachabilityReason = "address-change" | "session-suspect"; /** * Interface for obtaining a message exchange with a specific peer. */ export abstract class ExchangeProvider { constructor(protected readonly exchangeManager: ExchangeManager) {} abstract maximumPeerResponseTime(expectedProcessingTime?: Duration, includeMaximumSendingTime?: boolean): Duration; abstract initiateExchange(options?: NewExchangeOptions): Promise; abstract readonly channelType: ChannelType; abstract readonly peerAddress?: PeerAddress; /** The peer's invoke path limit, or undefined where there is no peer to report one. Never below one. */ abstract readonly maxPathsPerInvoke?: number; /** * Peer-advertised CapabilityMinima path floors. Base values are the spec minimums. * @see {@link MatterSpecification.v161.Core} ยง 11.1.4.4 */ get readPathsSupported(): number { return 9; } get subscribePathsSupported(): number { return 3; } /** * Dedicated secure session backing this provider, if any. * * Providers that multiplex sessions (e.g. {@link PeerExchangeProvider}) return `undefined`. * Consumers can use this to react to session-lifecycle events without casting. */ get session(): SecureSession | undefined { return undefined; } /** * Ensure the peer is reachable without creating an exchange. * * The default implementation is a no-op (already connected). */ async connect(_options?: NewExchangeOptions): Promise {} /** * Verify the peer is reachable, driving recovery (alternate-address migration or session close). * * The default reports reachable; only peer-backed providers have a reachability authority and override this. */ async verifyReachability(_options: { reason: ReachabilityReason; abort?: AbortSignal }): Promise { return true; } } /** * Manages an exchange over an established channel. */ export class DedicatedChannelExchangeProvider extends ExchangeProvider { #session: SecureSession; constructor(exchangeManager: ExchangeManager, session: SecureSession) { super(exchangeManager); this.#session = session; } get maxPathsPerInvoke() { return this.#session.parameters.maxPathsPerInvoke; } async initiateExchange(options?: NewExchangeOptions): Promise { return this.exchangeManager.initiateExchangeForSession(this.#session, INTERACTION_PROTOCOL_ID, { peerAdditionalMrpDelay: options?.additionalMrpDelay, }); } get channelType() { return this.#session.channel.transportChannel.type; } override get session() { return this.#session; } maximumPeerResponseTime( expectedProcessingTime = MRP.DEFAULT_EXPECTED_PROCESSING_TIME, includeMaximumSendingTime?: boolean, ) { return this.exchangeManager.calculateMaximumPeerResponseTimeMsFor( this.#session, expectedProcessingTime, includeMaximumSendingTime, ); } get peerAddress() { if (NodeSession.is(this.#session)) { return this.#session.peerAddress; } } }