@matter/protocol 0.17.3 → 0.17.4-alpha.0-20260623-5647634fc

package/src/peer/PeerAddressMonitor.ts

@@ -4,7 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import type { ReachabilityReason } from "#protocol/ExchangeProvider.js";
 import {
+    Abort,
     ChannelType,
     Diagnostic,
     Duration,
@@ -21,6 +23,9 @@ import { PeerUnresponsiveError } from "./PeerCommunicationError.js";
 
 const logger = Logger.get("PeerAddressMonitor");
 
+/** A liveness probe does not need the full MRP retransmission budget. */
+const PROBE_MAX_RETRANSMISSIONS = 2;
+
 /**
  * Monitors mDNS-discovered addresses for a peer and probes the current session when the session's IP
  * disappears from discovered addresses.
@@ -41,12 +46,11 @@ export class PeerAddressMonitor {
     readonly #timer: Timer;
     readonly #cooldownMin: Duration;
     readonly #cooldownMax: Duration;
-    readonly #trackWork: (work: PromiseLike<void>) => void;
-    #probing?: Promise<void>;
+    readonly #trackWork: (work: PromiseLike<unknown>) => void;
+    #probing?: Promise<boolean>;
 
-    // Fibonacci backoff state — resets when probed IP changes
+    // Fibonacci backoff state — grows on each successful probe, resets only on a real reachability scare
     #lastProbeAt?: Timestamp;
-    #lastProbedIp?: string;
     #fibPrev: Duration = 0;
     #fibCurr: Duration = 0;
 
@@ -55,7 +59,7 @@ export class PeerAddressMonitor {
         stabilizationDelay: Duration,
         probeCooldown: { minimum: Duration; maximum: Duration },
         abort: AbortSignal,
-        trackWork: (work: PromiseLike<void>) => void,
+        trackWork: (work: PromiseLike<unknown>) => void,
     ) {
         this.#peer = peer;
         this.#abort = abort;
@@ -63,15 +67,7 @@ export class PeerAddressMonitor {
         this.#cooldownMax = probeCooldown.maximum;
         this.#trackWork = trackWork;
         this.#timer = Time.getTimer("address check stabilization", stabilizationDelay, () => {
-            if (!this.#probing) {
-                this.#probing = this.#check().finally(() => {
-                    this.#probing = undefined;
-
-                    // If address changes arrived during the probe, re-check
-                    this.schedule();
-                });
-                this.#trackWork(this.#probing);
-            }
+            this.#trackWork(this.verifyReachability({ reason: "address-change", abort: this.#abort }));
         });
     }
 
@@ -94,110 +90,149 @@ export class PeerAddressMonitor {
         this.#timer.stop();
     }
 
-    async #check() {
+    /**
+     * Tear down: stop the timer and await any in-flight run so teardown does not race a probe.  The
+     * caller is expected to have aborted the peer first, so the in-flight run unwinds promptly.
+     */
+    async close() {
+        this.#timer.stop();
+        await this.#probing;
+    }
+
+    /**
+     * Verify the peer is reachable, driving recovery.  Coalesces concurrent triggers into one run.
+     *
+     * An `address-change` run probes the current address then walks discovered alternates (migrating in
+     * place on success); a `session-suspect` run only probes the current address and never walks alternates.
+     * Returns `true` if the session is usable afterward (current address answered, or an alternate
+     * answered and the session migrated); `false` if no address answered and the session was closed.
+     */
+    async verifyReachability(options: { reason: ReachabilityReason; abort?: AbortSignal }): Promise<boolean> {
+        if (this.#probing === undefined) {
+            this.#probing = this.#run(options.reason).finally(() => {
+                this.#probing = undefined;
+                // Only an address-change run may have coalesced newer mDNS changes worth re-checking;
+                // a lone session-suspect run must not arm the debounce timer.
+                if (options.reason === "address-change") {
+                    this.schedule();
+                }
+            });
+        }
+
+        const run = this.#probing;
+        // A joiner waits on the shared run but bails on its own abort without cancelling it for others.
+        return options.abort !== undefined && options.abort !== this.#abort
+            ? ((await Abort.race(options.abort, run)) ?? false)
+            : run;
+    }
+
+    async #run(reason: ReachabilityReason): Promise<boolean> {
+        const abort = this.#abort;
         const session = this.#peer.newestSession();
         const interaction = this.#peer.interaction;
         if (!session || !interaction) {
-            return;
+            return false;
         }
 
         const channel = session.channel.transportChannel;
-        if (!isIpNetworkChannel(channel)) {
-            return;
-        }
-
-        // TCP has 1:1 session-connection binding plus OS keep-alive — connection drops evict
-        // the session directly, so probing the address is unnecessary.
-        if (channel.type === ChannelType.TCP) {
-            return;
+        // TCP/non-IP sessions are evicted when their connection drops, so address probing is moot.
+        if (!isIpNetworkChannel(channel) || channel.type === ChannelType.TCP) {
+            return true;
         }
 
         const currentAddress = channel.networkAddress;
-        const currentIp = currentAddress.ip;
         const discoveredAddresses = this.#peer.service.addresses;
 
-        // If there are no discovered addresses at all, nothing to compare against
-        if (!discoveredAddresses.size) {
-            return;
-        }
-
-        // If the current address is still in the discovered set, all good
-        if (discoveredAddresses.has(currentAddress)) {
-            return;
-        }
-
-        const via = session.via;
-
-        // Reset backoff if the IP we're being asked about differs from last time
-        if (currentIp !== this.#lastProbedIp) {
+        if (reason === "session-suspect") {
+            // A subscription timeout is real evidence of trouble — drop accumulated trust so we probe now.
             this.#resetBackoff();
         }
 
-        // Cooldown: use the more recent of last-probe and last device activity
-        const lastKnownGood = Timestamp(Math.max(this.#lastProbeAt ?? 0, session.activeTimestamp));
-        const cooldown = this.#currentCooldown;
-        if (lastKnownGood > 0 && Timestamp.delta(lastKnownGood) < cooldown) {
-            return;
+        if (reason === "address-change") {
+            // Only probe when the current address dropped out of the discovered set. Match by ip/port:
+            // discovered addresses are channel-agnostic, so `has()` (keyed by URL incl. protocol) would always miss.
+            const stillDiscovered = [...discoveredAddresses].some(addr => ServerAddress.isEqual(addr, currentAddress));
+            if (!discoveredAddresses.size || stillDiscovered) {
+                return true;
+            }
+            const lastKnownGood = Timestamp(Math.max(this.#lastProbeAt ?? 0, session.activeTimestamp));
+            if (lastKnownGood > 0 && Timestamp.delta(lastKnownGood) < this.#currentCooldown) {
+                return true;
+            }
+            logger.info(
+                session.via,
+                "Session address",
+                Diagnostic.strong(ServerAddress.urlFor(currentAddress)),
+                "no longer in mDNS results, probing",
+            );
+            this.#lastProbeAt = Time.nowMs;
         }
 
-        logger.info(
-            via,
-            "Session address",
-            Diagnostic.strong(ServerAddress.urlFor(currentAddress)),
-            "no longer in mDNS results, probing",
-        );
-
-        this.#lastProbeAt = Time.nowMs;
-        this.#lastProbedIp = currentIp;
-
-        // Get probe network profile
         const network = this.#peer.network;
         const probeNetwork = network.probeAddress ?? network;
 
-        // Probe the current address — suppress peer-loss so the session stays alive for follow-up probes
-        if (await interaction.probe({ network: probeNetwork.id, abort: this.#abort, suppressPeerLoss: true })) {
-            this.#advanceBackoff();
-            return;
+        if (
+            await interaction.probe({
+                network: probeNetwork.id,
+                abort,
+                suppressPeerLoss: true,
+                maxRetransmissions: PROBE_MAX_RETRANSMISSIONS,
+            })
+        ) {
+            if (reason === "address-change") {
+                this.#advanceBackoff();
+            }
+            return true;
         }
 
-        // Current address unreachable — try discovered addresses on the still-alive session.
-        // Probe path is UDP-only (TCP returned above); IpService stores transport-agnostic
-        // ServerAddressIp, so tag each candidate as UDP for the override and channel update.
-        for (const ipAddress of discoveredAddresses) {
-            if (this.#abort.aborted) {
-                return;
-            }
-            const address: ServerAddressUdp = { ...ipAddress, type: "udp" };
-
-            if (
-                await interaction.probe({
-                    network: probeNetwork.id,
-                    abort: this.#abort,
-                    addressOverride: address,
-                    suppressPeerLoss: true,
-                })
-            ) {
-                logger.info(
-                    via,
-                    "Discovered address reachable, migrating session to",
-                    Diagnostic.strong(ServerAddress.urlFor(address)),
-                );
-                session.channel.networkAddress = address;
-                interaction.subscriptions.closeForPeer(this.#peer.address);
-                this.#resetBackoff();
-                return;
+        // Only an mDNS address change walks alternates; a session-suspect probe stays on the current address.
+        if (reason === "address-change") {
+            for (const ipAddress of discoveredAddresses) {
+                if (abort.aborted) {
+                    return false;
+                }
+                if (ServerAddress.isEqual(ipAddress, currentAddress)) {
+                    continue;
+                }
+                const address: ServerAddressUdp = { ...ipAddress, type: "udp" };
+                if (
+                    await interaction.probe({
+                        network: probeNetwork.id,
+                        abort,
+                        addressOverride: address,
+                        suppressPeerLoss: true,
+                        maxRetransmissions: PROBE_MAX_RETRANSMISSIONS,
+                    })
+                ) {
+                    logger.info(
+                        session.via,
+                        "Discovered address reachable, migrating session to",
+                        Diagnostic.strong(ServerAddress.urlFor(address)),
+                    );
+                    session.channel.networkAddress = address;
+                    // Subscriptions still target the old address for device->client reports; close them so they
+                    // re-establish and hand the device our new socket.
+                    interaction.subscriptions.closeForPeer(this.#peer.address);
+                    this.#resetBackoff();
+                    return true;
+                }
             }
+            this.#resetBackoff();
         }
 
-        this.#resetBackoff();
-
-        if (this.#abort.aborted) {
-            return;
+        if (abort.aborted) {
+            return false;
         }
 
-        // No address works — close the session so normal reconnection takes over
-        logger.info(via, "All probes failed, closing session");
-        await session.handlePeerLoss({ cause: new PeerUnresponsiveError() });
+        logger.info(session.via, "All probes failed, closing session");
+        try {
+            await session.handlePeerLoss({ cause: new PeerUnresponsiveError() });
+        } catch (error) {
+            // Best-effort recovery: a failure to close the unreachable session must not reject the run
+            // (which teardown awaits) — log and move on.
+            logger.warn(session.via, "Error closing unreachable session", error);
+        }
+        return false;
     }
 
     /** Current cooldown duration based on Fibonacci position. */

package/src/peer/PeerExchangeProvider.ts

@@ -5,7 +5,7 @@
  */
 
 import { PeerAddress } from "#peer/PeerAddress.js";
-import { ExchangeProvider, NewExchangeOptions } from "#protocol/ExchangeProvider.js";
+import { ExchangeProvider, NewExchangeOptions, type ReachabilityReason } from "#protocol/ExchangeProvider.js";
 import type { MessageExchange } from "#protocol/MessageExchange.js";
 import { MRP } from "#protocol/MRP.js";
 import { ChannelType, Duration, InternalError } from "@matter/general";
@@ -58,6 +58,10 @@ export class PeerExchangeProvider extends ExchangeProvider {
         });
     }
 
+    override verifyReachability(options: { reason: ReachabilityReason; abort?: AbortSignal }): Promise<boolean> {
+        return this.#peer.verifyReachability(options);
+    }
+
     override async initiateExchange(options?: NewExchangeOptions): Promise<MessageExchange> {
         const abort = options?.abort;
         const isGroup = PeerAddress.isGroup(this.#peer.address);

package/src/peer/PeerTimingParameters.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Duration, merge as mergeObjects, Millis, Minutes, Seconds } from "@matter/general";
+import { Duration, Hours, merge as mergeObjects, Millis, Minutes, Seconds } from "@matter/general";
 
 /**
  * Parameters that control network timing for Matter sessions controlled by matter.js.
@@ -105,11 +105,11 @@ export interface PeerTimingParameters {
     addressChangeStabilizationDelay: Duration;
 
     /**
-     * Probe cooldown range for address-change probes on the same IP.
+     * Probe cooldown range for address-change probes.
      *
      * When mDNS keeps reporting the session IP as gone but probes succeed, the cooldown grows
      * using a Fibonacci-like sequence from {@link minimum} to {@link maximum}.  The cooldown
-     * resets when the probed IP changes or a probe fails.
+     * resets on a probe failure or a subscription-liveness scare, not on a mere address change.
      *
      * Probes are also suppressed while the session is actively receiving data — the cooldown
      * is measured from whichever is more recent: the last probe or the last received message.
@@ -183,8 +183,8 @@ export namespace PeerTimingParameters {
         },
         addressChangeStabilizationDelay: Seconds(10),
         addressChangeProbeCooldown: {
-            minimum: Minutes(2),
-            maximum: Minutes(60),
+            minimum: Minutes(10),
+            maximum: Hours(24),
         },
     };
 }

package/src/protocol/ExchangeProvider.ts

@@ -61,6 +61,9 @@ export interface NewExchangeOptions extends Omit<InteractionSettings, "transacti
     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.
  */
@@ -89,6 +92,15 @@ export abstract class ExchangeProvider {
      * The default implementation is a no-op (already connected).
      */
     async connect(_options?: NewExchangeOptions): Promise<void> {}
+
+    /**
+     * 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<boolean> {
+        return true;
+    }
 }
 
 /**