@matter/protocol 0.16.0-alpha.0-20250809-ee8375bcb → 0.16.0-alpha.0-20250812-285b75d83

package/src/mdns/index.ts

@@ -4,9 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-export * from "./MdnsBroadcaster.js";
+export * from "./MdnsClient.js";
 export * from "./MdnsConsts.js";
-export * from "./MdnsInstanceBroadcaster.js";
-export * from "./MdnsScanner.js";
 export * from "./MdnsServer.js";
 export * from "./MdnsService.js";
+export * from "./MdnsSocket.js";

package/src/peer/ControllerCommissioner.ts

@@ -23,7 +23,7 @@ import {
     serverAddressToString,
 } from "#general";
 import { InteractionClient, InteractionClientProvider } from "#interaction/InteractionClient.js";
-import { MdnsScanner } from "#mdns/MdnsScanner.js";
+import { MdnsClient } from "#mdns/MdnsClient.js";
 import {
     CommissioningError,
     ControllerCommissioningFlow,
@@ -306,7 +306,7 @@ export class ControllerCommissioner {
     ): Promise<MessageChannel> {
         let paseChannel: Channel<Uint8Array>;
         if (device !== undefined) {
-            logger.info(`Establish PASE to device`, MdnsScanner.discoveryDataDiagnostics(device));
+            logger.info(`Establish PASE to device`, MdnsClient.discoveryDataDiagnostics(device));
         }
         if (address.type === "udp") {
             const { ip } = address;

package/src/peer/ControllerDiscovery.ts

@@ -16,7 +16,7 @@ import {
     Scanner,
 } from "../common/Scanner.js";
 import { Fabric } from "../fabric/Fabric.js";
-import { MdnsScanner } from "../mdns/MdnsScanner.js";
+import { MdnsClient } from "../mdns/MdnsClient.js";
 import { RetransmissionLimitReachedError } from "../protocol/MessageExchange.js";
 
 const logger = Logger.get("ControllerDiscovery");
@@ -117,7 +117,7 @@ export class ControllerDiscovery {
     static async discoverOperationalDevice(
         fabric: Fabric,
         peerNodeId: NodeId,
-        scanner: MdnsScanner,
+        scanner: MdnsClient,
         timeoutSeconds?: number,
         ignoreExistingRecords?: boolean,
     ): Promise<OperationalDevice> {
@@ -135,7 +135,7 @@ export class ControllerDiscovery {
         return foundDevice;
     }
 
-    static cancelOperationalDeviceDiscovery(fabric: Fabric, peerNodeId: NodeId, scanner: MdnsScanner) {
+    static cancelOperationalDeviceDiscovery(fabric: Fabric, peerNodeId: NodeId, scanner: MdnsClient) {
         scanner.cancelOperationalDeviceDiscovery(fabric, peerNodeId);
     }
 

package/src/peer/PeerSet.ts

@@ -30,7 +30,7 @@ import {
     Timer,
 } from "#general";
 import { SubscriptionClient } from "#interaction/SubscriptionClient.js";
-import { MdnsScanner } from "#mdns/MdnsScanner.js";
+import { MdnsClient } from "#mdns/MdnsClient.js";
 import { PeerAddress, PeerAddressMap } from "#peer/PeerAddress.js";
 import { ChannelManager } from "#protocol/ChannelManager.js";
 import { ExchangeManager } from "#protocol/ExchangeManager.js";
@@ -86,7 +86,7 @@ interface RunningDiscovery {
     type: NodeDiscoveryType;
     promises?: (() => Promise<MessageChannel>)[];
     stopTimerFunc?: (() => void) | undefined;
-    mdnsScanner?: MdnsScanner;
+    mdnsClient?: MdnsClient;
 }
 
 /**
@@ -147,7 +147,13 @@ export class PeerSet implements ImmutableSet<OperationalPeer>, ObservableSet<Ope
             this.#peersByAddress.delete(peer.address);
         });
 
-        this.#sessions.resubmissionStarted.on(this.#handleResubmissionStarted.bind(this));
+        this.#sessions.retry.on((session, count) => {
+            if (count !== 1) {
+                return;
+            }
+
+            this.#handleFirstRetry(session);
+        });
 
         /** A channel was added by ourselves */
         this.#channels.added.on((address, msgChannel) => {
@@ -375,7 +381,7 @@ export class PeerSet implements ImmutableSet<OperationalPeer>, ObservableSet<Ope
     }
 
     async close() {
-        for (const [address, { stopTimerFunc, mdnsScanner }] of this.#runningPeerDiscoveries.entries()) {
+        for (const [address, { stopTimerFunc, mdnsClient: mdnsScanner }] of this.#runningPeerDiscoveries.entries()) {
             stopTimerFunc?.();
 
             // This ends discovery without triggering promises
@@ -442,7 +448,7 @@ export class PeerSet implements ImmutableSet<OperationalPeer>, ObservableSet<Ope
             throw new ImplementationError("Cannot set retransmission discovery type.");
         }
 
-        const mdnsScanner = this.#scanners.scannerFor(ChannelType.UDP) as MdnsScanner | undefined;
+        const mdnsScanner = this.#scanners.scannerFor(ChannelType.UDP) as MdnsClient | undefined;
         if (!mdnsScanner) {
             throw new ImplementationError("Cannot discover device without mDNS scanner.");
         }
@@ -593,7 +599,7 @@ export class PeerSet implements ImmutableSet<OperationalPeer>, ObservableSet<Ope
             type: requestedDiscoveryType,
             promises: discoveryPromises,
             stopTimerFunc,
-            mdnsScanner,
+            mdnsClient: mdnsScanner,
         });
 
         return await anyPromise(discoveryPromises).finally(() => {
@@ -765,7 +771,7 @@ export class PeerSet implements ImmutableSet<OperationalPeer>, ObservableSet<Ope
             return lastKnownAddress;
         }
 
-        const mdnsScanner = this.#scanners.scannerFor(ChannelType.UDP) as MdnsScanner | undefined;
+        const mdnsScanner = this.#scanners.scannerFor(ChannelType.UDP) as MdnsClient | undefined;
         const discoveredAddresses = mdnsScanner?.getDiscoveredOperationalDevice(
             this.#sessions.fabricFor(address),
             address.nodeId,
@@ -810,7 +816,7 @@ export class PeerSet implements ImmutableSet<OperationalPeer>, ObservableSet<Ope
         if (this.#runningPeerDiscoveries.has(address)) {
             logger.info(`Found ${address} during discovery, cancel discovery.`);
             // We are currently discovering this node, so we need to update the discovery data
-            const { mdnsScanner } = this.#runningPeerDiscoveries.get(address) ?? {};
+            const { mdnsClient: mdnsScanner } = this.#runningPeerDiscoveries.get(address) ?? {};
 
             // This ends discovery and triggers the promises
             mdnsScanner?.cancelOperationalDeviceDiscovery(this.#sessions.fabricFor(address), address.nodeId, true);
@@ -821,7 +827,7 @@ export class PeerSet implements ImmutableSet<OperationalPeer>, ObservableSet<Ope
         return this.#peersByAddress.get(address)?.operationalAddress;
     }
 
-    #handleResubmissionStarted(session: Session) {
+    #handleFirstRetry(session: Session) {
         if (!session.isSecure || (session as SecureSession).fabric === undefined) {
             // For insecure sessions from CASE/PASE or not yet fabric bound session establishments we do not need to do anything
             return;

package/src/protocol/DeviceAdvertiser.ts

@@ -4,25 +4,14 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { CommissioningMode, CommissioningModeInstanceData, InstanceBroadcaster } from "#common/InstanceBroadcaster.js";
+import { Advertisement } from "#advertisement/Advertisement.js";
+import { Advertiser } from "#advertisement/Advertiser.js";
+import { ServiceDescription } from "#advertisement/ServiceDescription.js";
 import { Fabric } from "#fabric/Fabric.js";
 import { FabricManager } from "#fabric/FabricManager.js";
-import {
-    AsyncObservable,
-    Diagnostic,
-    Environment,
-    Environmental,
-    Logger,
-    MatterAggregateError,
-    Mutex,
-    ObserverGroup,
-    Time,
-    Timer,
-} from "#general";
+import { Environment, Environmental, MatterAggregateError, ObserverGroup } from "#general";
+import { SecureSession } from "#session/SecureSession.js";
 import { SessionManager } from "#session/SessionManager.js";
-import { DEVICE_ANNOUNCEMENT_DURATION_MS, DEVICE_ANNOUNCEMENT_INTERVAL_MS } from "#types";
-
-const logger = Logger.get("DeviceAdvertiser");
 
 /**
  * Interfaces the {@link DeviceAdvertiser} with other components.
@@ -36,51 +25,81 @@ export interface DeviceAdvertiserContext {
  * Advertises a node for commissioning (if uncommissioned) or operationally (if commissioned).
  */
 export class DeviceAdvertiser {
-    readonly #context: DeviceAdvertiserContext;
-    readonly #broadcasters = new Set<InstanceBroadcaster>();
-    readonly #timedOut = AsyncObservable<[]>();
-    readonly #operationalModeEnabled = new AsyncObservable<[]>();
-    readonly #operationalModeEnded = new AsyncObservable<[]>();
-    readonly #observers = new ObserverGroup();
-    #interval: Timer;
-    #startTime: number | null = null;
+    #context: DeviceAdvertiserContext;
+    #advertisers = new Set<Advertiser>();
+    #observers = new ObserverGroup();
+    #isOperational = false;
     #isClosing = false;
-    #commissioningMode = CommissioningMode.NotCommissioning;
-
-    // Currently we do not put much effort into synchronizing announcements as it probably isn't really necessary.  But
-    // this mutex prevents automated announcements from piling up and allows us to ensure announcements are complete on
-    // close
-    #mutex = new Mutex(this);
+    #commissioningService?: ServiceDescription;
 
     constructor(context: DeviceAdvertiserContext) {
         this.#context = context;
+        const { fabrics, sessions } = this.#context;
 
-        this.#interval = Time.getPeriodicTimer("Server node announcement", DEVICE_ANNOUNCEMENT_INTERVAL_MS, () =>
-            // Announcement needs to await a previous announcement because otherwise in testing at least announcement
-            // may crash if started simultaneously
-            this.#mutex.run(this.advertise.bind(this)),
-        );
+        // When a fabric is added, begin advertising automatically if in operational mode
+        this.#observers.on(fabrics.events.added, fabric => {
+            if (!this.#isOperational) {
+                return;
+            }
+
+            this.#advertiseFabric(fabric, "startup");
+        });
+
+        // When a fabric is deleted, cancel any active advertisement
+        this.#observers.on(fabrics.events.deleted, fabric => {
+            Advertisement.cancelAll(this.#advertisements(ad => ad.isOperational() && ad.description.fabric === fabric));
+        });
+
+        // When an operational session is established, notify relevant advertisers so they can stop advertising if so
+        // configured
+        this.#observers.on(sessions.sessions.added, session => {
+            const fabricIndex = session.fabric?.fabricIndex;
+            const fabric = fabricIndex ? fabrics.findByIndex(fabricIndex) : undefined;
+            if (!fabric) {
+                return;
+            }
 
-        this.#observers.on(this.#context.fabrics.events.deleted, () => {
-            if (this.#context.fabrics.length === 0) {
-                // Last fabric got removed, so expire all announcements
-                this.#mutex.run(this.#exitOperationalMode.bind(this));
-            } else {
-                // At least one fabric is still present, so re-announce
-                this.#mutex.run(() => this.advertise(true));
+            for (const advertiser of this.#advertisers) {
+                const ad = advertiser.advertisementForFabric(fabric);
+                if (ad) {
+                    ad.serviceConnected();
+                }
             }
         });
 
-        this.#observers.on(this.#context.sessions.resubmissionStarted, (session?) => {
-            logger.debug(`Resubmission started, re-announce node ${session?.nodeId}`);
-            this.#mutex.run(() => this.advertise(true));
+        // 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;
+
+            // If this was an operational connection, readvertise if we're no longer connected to the peer
+            if (fabric) {
+                if (fabric.hasSessionForPeer(session.peerNodeId)) {
+                    return;
+                }
+
+                for (const advertiser of this.#advertisers) {
+                    const ad = advertiser.advertisementForFabric(fabric);
+                    if (ad) {
+                        ad.serviceDisconnected();
+                    }
+                }
+
+                return;
+            }
+
+            // If we're in commissioning mode, resume advertising for commissioning
+            this.#startCommissioningAdvertisement();
         });
 
-        this.#observers.on(this.#context.sessions.subscriptionsChanged, (_session, subscription) => {
-            if (subscription.isCanceledByPeer) {
-                logger.debug(`Subscription canceled by peer, re-announce`);
-                this.#mutex.run(this.startAdvertising.bind(this));
+        // Trigger retransmission broadcast on retry
+        this.#observers.on(sessions.retry, session => {
+            if (!session.isSecure || !(session as SecureSession).fabric) {
+                return;
             }
+
+            // Each time we retry a transmission, also trigger retry broadcast for associated fabric
+            this.#advertiseFabric(session.associatedFabric, "retransmit");
         });
     }
 
@@ -98,146 +117,137 @@ export class DeviceAdvertiser {
     }
 
     /**
-     * Emitted when the advertising window closes with no response.
+     * Advertise the device as commissionable.
      */
-    get timedOut() {
-        return this.#timedOut;
+    enterCommissioningMode(description: ServiceDescription.Commissionable) {
+        this.#commissioningService = description;
+        this.#startCommissioningAdvertisement();
     }
 
     /**
-     * Emitted when the device stops advertising due to decommissioning.
+     * Begin automatic broadcast for commissioning if in commissionable mode.
      */
-    get operationalModeEnded() {
-        return this.#operationalModeEnded;
-    }
+    #startCommissioningAdvertisement() {
+        if (this.#isClosing) {
+            return;
+        }
 
-    /**
-     * Emitted when the device starts advertising in operational mode.
-     */
-    get operationalModeEnabled() {
-        return this.#operationalModeEnabled;
-    }
+        if (this.#commissioningService === undefined) {
+            return;
+        }
 
-    async enterCommissioningMode(mode: CommissioningMode, deviceData: CommissioningModeInstanceData) {
-        this.#commissioningMode = mode;
-        for (const broadcaster of this.#broadcasters) {
-            await broadcaster.setCommissionMode(mode, deviceData);
+        for (const advertiser of this.#advertisers) {
+            advertiser.advertise(this.#commissioningService, "startup");
         }
-        await this.startAdvertising();
     }
 
-    async exitCommissioningMode() {
-        this.#commissioningMode = CommissioningMode.NotCommissioning;
-        this.#interval.stop();
-        this.#startTime = null;
-        for (const broadcaster of this.#broadcasters) {
-            await broadcaster.expireCommissioningAnnouncement();
+    /**
+     * Cease advertising the device as commissionable.
+     */
+    exitCommissioningMode() {
+        if (!this.#commissioningService) {
+            return;
         }
+
+        this.#commissioningService = undefined;
+        return Advertisement.closeAll(this.#advertisements(ad => ad.isCommissioning()));
     }
 
-    async startAdvertising() {
-        if (this.#isClosing) return;
-        if (this.#interval.isRunning) {
-            this.#interval.stop();
+    /**
+     * Advertise the device as operational.
+     */
+    enterOperationalMode() {
+        if (this.#isOperational) {
+            return;
         }
-        this.#startTime = Time.nowMs();
-        this.#interval.start();
-        await this.advertise();
-    }
 
-    async advertise(once = false) {
-        if (!once) {
-            // Stop announcement if duration is reached
-            if (this.#startTime !== null && Time.nowMs() - this.#startTime > DEVICE_ANNOUNCEMENT_DURATION_MS) {
-                logger.debug("Announcement duration reached, stop announcing");
-                await this.#timedOut.emit();
-                return;
-            }
+        this.#isOperational = true;
 
-            if (this.#commissioningMode !== CommissioningMode.NotCommissioning) {
-                // Re-Announce but do not reset Fabrics
-                for (const broadcaster of this.#broadcasters) {
-                    await broadcaster.announce();
-                }
-                return;
-            }
+        this.#startOperationalAdvertisement();
+    }
+
+    /**
+     * Begin automatic broadcast for fabrics if in operational mode.
+     */
+    #startOperationalAdvertisement() {
+        if (!this.#isOperational) {
+            return;
         }
 
-        const fabrics = this.#context.fabrics;
-
-        if (fabrics.length) {
-            let fabricsWithoutSessions = 0;
-            for (const fabric of fabrics) {
-                const session = this.#context.sessions.getSessionForNode(fabric.addressOf(fabric.rootNodeId));
-                if (session === undefined || !session.isSecure || session.subscriptions.size === 0) {
-                    fabricsWithoutSessions++;
-                    logger.debug(
-                        "Announcing",
-                        Diagnostic.dict({ fabricIndex: fabric.fabricIndex, fabricId: fabric.fabricId }),
-                    );
-                }
-            }
-            for (const broadcaster of this.#broadcasters) {
-                await broadcaster.setFabrics(fabrics.fabrics);
-                if (fabricsWithoutSessions > 0 || this.#commissioningMode !== CommissioningMode.NotCommissioning) {
-                    await broadcaster.announce();
-                }
+        const fabricsAdvertised = new Set(
+            this.#advertisements(ad => ad.isOperational()).map(
+                ad => (ad as Advertisement<ServiceDescription.Operational>).description.fabric,
+            ),
+        );
+
+        for (const fabric of this.#context.fabrics) {
+            if (!fabricsAdvertised.has(fabric)) {
+                this.#advertiseFabric(fabric, "startup");
             }
-        } else {
-            // Expire operational Fabric announcements (if fabric got just deleted)
-            await this.#exitOperationalMode();
-            await this.#operationalModeEnded.emit();
         }
     }
 
-    async advertiseFabrics(fabrics: Fabric[], expireCommissioningAnnouncement = false) {
-        if (expireCommissioningAnnouncement) {
-            // TODO: For real "non-ethernet-only" cases like Wifi or Thread devices this might still be too early.
-            //  In these cases we might need an option to (re-)create mdns broadcaster just when interface
-            //  is connected
-            await this.#operationalModeEnabled.emit();
-        }
-        for (const broadcaster of this.#broadcasters) {
-            await broadcaster.setFabrics(fabrics, expireCommissioningAnnouncement);
-            await broadcaster.announce();
+    /**
+     * Cease advertising the device as operational.
+     */
+    exitOperationalMode() {
+        if (!this.#isOperational) {
+            return;
         }
+
+        this.#isOperational = false;
+
+        Advertisement.cancelAll(this.#advertisements(ad => ad.isOperational()));
     }
 
-    async #exitOperationalMode() {
-        for (const broadcaster of this.#broadcasters) {
-            await broadcaster.expireFabricAnnouncement();
-        }
+    /**
+     * Reset automatic advertisement.
+     *
+     * This is useful when there is a network change.
+     */
+    restartAdvertisement() {
+        this.#startCommissioningAdvertisement();
+        this.#startOperationalAdvertisement();
     }
 
     async close() {
         this.#isClosing = true;
-        await this.#mutex;
         this.#observers.close();
-        this.#interval.stop();
-        await this.clearBroadcasters();
+        await this.clearAdvertisers();
+    }
+
+    hasAdvertiser(advertiser: Advertiser) {
+        return this.#advertisers.has(advertiser);
+    }
+
+    addAdvertiser(advertiser: Advertiser) {
+        this.#advertisers.add(advertiser);
     }
 
-    hasBroadcaster(broadcaster: InstanceBroadcaster) {
-        return this.#broadcasters.has(broadcaster);
+    async deleteAdvertiser(advertiser: Advertiser) {
+        this.#advertisers.delete(advertiser);
+        await advertiser.close();
     }
 
-    addBroadcaster(broadcaster: InstanceBroadcaster) {
-        this.#broadcasters.add(broadcaster);
+    async clearAdvertisers() {
+        const advertisers = [...this.#advertisers];
+        this.#advertisers.clear();
+        await MatterAggregateError.allSettled(advertisers.map(advertiser => advertiser.close()));
     }
 
-    async deleteBroadcaster(broadcaster: InstanceBroadcaster) {
-        if (this.#broadcasters.delete(broadcaster)) {
-            await broadcaster.expireAllAnnouncements();
+    #advertiseFabric(fabric: Fabric, event: Advertiser.BroadcastEvent) {
+        if (this.#isClosing) {
+            return;
+        }
+
+        for (const advertiser of this.#advertisers) {
+            advertiser.advertise(ServiceDescription.Operational({ fabric }), event);
         }
     }
 
-    async clearBroadcasters() {
-        const broadcasters = [...this.#broadcasters];
-        const closed = MatterAggregateError.allSettled(
-            broadcasters.map(b => b.close()),
-            "Error closing broadcasters",
-        ).catch(error => logger.error(error));
-        this.#broadcasters.clear();
-        await closed;
+    #advertisements(predicate?: (ad: Advertisement) => boolean) {
+        return [...this.#advertisers].flatMap(advertiser =>
+            predicate ? advertiser.filter(predicate) : [...advertiser.advertisements],
+        );
     }
 }