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

package/src/interaction/Subscription.ts

@@ -4,111 +4,39 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { AsyncObservable, Duration, InternalError, Logger } from "#general";
-import { NodeSession } from "#session/NodeSession.js";
-import { TlvAttributePath, TlvDataVersionFilter, TlvEventFilter, TlvEventPath, TypeFromSchema } from "#types";
-
-const logger = Logger.get("Subscription");
+import { hex } from "#general";
+import { Session } from "#session/Session.js";
 
 export type SubscriptionId = number;
 
-export interface SubscriptionCriteria {
-    attributeRequests?: TypeFromSchema<typeof TlvAttributePath>[];
-    dataVersionFilters?: TypeFromSchema<typeof TlvDataVersionFilter>[];
-    eventRequests?: TypeFromSchema<typeof TlvEventPath>[];
-    eventFilters?: TypeFromSchema<typeof TlvEventFilter>[];
-    isFabricFiltered: boolean;
-}
-
 /**
  * A single active subscription.
  */
-export abstract class Subscription {
-    #session: NodeSession;
-    #id: SubscriptionId;
-    #isClosed?: boolean;
-    #isCanceledByPeer?: boolean;
-    #criteria: SubscriptionCriteria;
-    #cancelled = AsyncObservable<[subscription: Subscription]>();
-    #maxInterval?: Duration;
-
-    constructor(session: NodeSession, id: SubscriptionId, criteria: SubscriptionCriteria) {
-        this.#session = session;
-        this.#id = id;
-        this.#criteria = criteria;
-    }
-
-    get id() {
-        return this.#id;
-    }
-
-    get criteria() {
-        return this.#criteria;
-    }
-
-    get isClosed() {
-        return !!this.#isClosed;
-    }
-
-    get isCanceledByPeer() {
-        return !!this.#isCanceledByPeer;
-    }
+export interface Subscription {
+    subscriptionId: SubscriptionId;
 
-    get session() {
-        return this.#session;
-    }
-
-    get cancelled() {
-        return this.#cancelled;
-    }
+    // TODO - these should reside in a server-specific interface
+    isCanceledByPeer: boolean;
+    handlePeerCancel(): Promise<void>;
+    close(flushViaSession?: Session): Promise<void>;
+}
 
-    get maxInterval() {
-        if (this.#maxInterval === undefined) {
-            throw new InternalError("Subscription maxInterval accessed before it was set");
+export namespace Subscription {
+    export function idStrOf(subscription: undefined | number | { subscriptionId?: number }) {
+        if (typeof subscription === "object") {
+            subscription = subscription.subscriptionId;
         }
-        return this.#maxInterval;
-    }
 
-    set maxInterval(value: Duration) {
-        if (this.#maxInterval !== undefined) {
-            throw new InternalError("Subscription maxInterval set twice");
+        if (subscription === undefined) {
+            return undefined;
         }
-        this.#maxInterval = value;
-    }
-
-    /**
-     * Update session state.  This probably is meaningless except in a server context.
-     */
-    async update() {}
-
-    /**
-     * This flag is set on closed sessions when the close was initiated by the peer.
-     */
-    protected set isCanceledByPeer(value: boolean) {
-        this.#isCanceledByPeer = value;
-    }
-
-    protected set isClosed(value: boolean) {
-        this.#isClosed = value;
-    }
-
-    /** Close the subscription with the option to gracefully flush outstanding data. */
-    abstract close(graceful: boolean, cancelledByPeer?: boolean): Promise<void>;
-
-    /**
-     * Destroy the subscription. Unsubscribe from all attributes and events and stop all timers.
-     */
-    protected async destroy(): Promise<void> {
-        this.#isClosed = true;
-        this.#session.subscriptions.delete(this);
-        logger.debug(`Removed subscription ${this.id} from ${this.#session.name}`);
 
-        this.#cancelled.emit(this);
+        return hex.fixed(subscription, 8);
     }
 
-    protected activate() {
-        // TODO Do not add to session but to node/peer
-        this.#session.subscriptions.add(this);
-        logger.debug(`Added subscription ${this.#id} to ${this.#session.name}`);
+    export function diagnosticOf(subscription: undefined | number | { subscriptionId?: number }) {
+        return {
+            "sub#": idStrOf(subscription),
+        };
     }
 }

package/src/interaction/SubscriptionClient.ts

@@ -19,7 +19,7 @@ export interface RegisteredSubscription {
     maximumPeerResponseTime: Duration;
     maxInterval: Duration;
     onData: (dataReport: DecodedDataReport) => MaybePromise<void>;
-    onTimeout?: () => void;
+    onTimeout?: Timer.Callback;
 }
 
 /**
@@ -51,10 +51,10 @@ export class SubscriptionClient implements ProtocolHandler {
 
             const maxInterval = Millis(subscription.maxInterval + subscription.maximumPeerResponseTime);
 
-            timer = Time.getTimer("Subscription timeout", maxInterval, () => {
+            timer = Time.getTimer("subscription timeout", maxInterval, lifetime => {
                 logger.info(`Subscription ${id} timed out after ${Duration.format(maxInterval)}`);
                 this.delete(id);
-                onTimeout();
+                onTimeout(lifetime);
             }).start();
 
             this.#timeouts.set(id, timer);

package/src/mdns/MdnsClient.ts

@@ -20,6 +20,7 @@ import {
     Instant,
     InternalError,
     Lifespan,
+    Lifetime,
     Logger,
     Millis,
     Minutes,
@@ -34,6 +35,7 @@ import {
     createPromise,
     isIPv6,
 } from "#general";
+import { PeerAddress } from "#peer/PeerAddress.js";
 import { NodeId, VendorId } from "#types";
 import {
     CommissionableDevice,
@@ -122,6 +124,8 @@ export interface MdnsScannerTargetCriteria {
  * queries to discover various types of Matter device types and listens for announcements.
  */
 export class MdnsClient implements Scanner {
+    readonly #lifetime: Lifetime;
+
     readonly type = ChannelType.UDP;
 
     /** Active announces by queryId with queries and known answers */
@@ -164,7 +168,9 @@ export class MdnsClient implements Scanner {
     /** True, if any node is interested in MDNS traffic, else we ignore all traffic */
     #listening = false;
 
-    constructor(socket: MdnsSocket) {
+    constructor(socket: MdnsSocket, lifetime = Lifetime.process) {
+        this.#lifetime = lifetime.join("mdns client");
+
         this.#socket = socket;
         this.#observers.on(this.#socket.receipt, this.#handleMessage.bind(this));
         this.#periodicTimer = Time.getPeriodicTimer("Discovered node expiration", Minutes.one, () =>
@@ -498,7 +504,7 @@ export class MdnsClient implements Scanner {
      * IP/ports or an empty array if not found.
      */
     async findOperationalDevice(
-        { operationalId }: Fabric,
+        fabric: Fabric,
         nodeId: NodeId,
         timeout?: Duration,
         ignoreExistingRecords = false,
@@ -506,10 +512,14 @@ export class MdnsClient implements Scanner {
         if (this.#closing) {
             throw new ImplementationError("Cannot discover operational device because scanner is closing.");
         }
-        const deviceMatterQname = this.#createOperationalMatterQName(operationalId, nodeId);
+        const deviceMatterQname = this.#createOperationalMatterQName(fabric.operationalId, nodeId);
 
         let storedDevice = ignoreExistingRecords ? undefined : this.#getOperationalDeviceRecords(deviceMatterQname);
         if (storedDevice === undefined) {
+            using _finding = this.#lifetime.join(
+                "finding peer",
+                PeerAddress({ fabricIndex: fabric.fabricIndex, nodeId }),
+            );
             const promise = this.#registerWaiterPromise(deviceMatterQname, false, timeout, () =>
                 this.#getOperationalDeviceRecords(deviceMatterQname),
             );
@@ -737,6 +747,9 @@ export class MdnsClient implements Scanner {
             ? []
             : this.#getCommissionableDeviceRecords(identifier).filter(({ addresses }) => addresses.length > 0);
         if (storedRecords.length === 0) {
+            using finding = this.#lifetime.join("finding commissionable");
+            Object.assign(finding.details, identifier);
+
             const queryId = this.#buildCommissionableQueryIdentifier(identifier);
             const promise = this.#registerWaiterPromise(queryId, true, timeout, () =>
                 this.#getCommissionableDeviceRecords(identifier),
@@ -791,6 +804,9 @@ export class MdnsClient implements Scanner {
         const criteria: MdnsScannerTargetCriteria = { commissionable: true, operationalTargets: [] };
         this.targetCriteriaProviders.add(criteria);
 
+        using finding = this.#lifetime.join("finding commissionable");
+        Object.assign(finding.details, identifier);
+
         try {
             let lastDiscoveredDevices: CommissionableDevice[] | undefined = undefined;
             while (!canceled) {
@@ -832,6 +848,7 @@ export class MdnsClient implements Scanner {
      * Close all connects, end all timers and resolve all pending promises.
      */
     async close() {
+        using _closing = this.#lifetime.closing();
         this.#closing = true;
         this.#observers.close();
         this.#periodicTimer.stop();

package/src/mdns/MdnsServer.ts

@@ -6,12 +6,15 @@
 
 import {
     AsyncCache,
+    describeList,
+    Diagnostic,
     DnsMessageType,
     DnsMessageTypeFlag,
     DnsRecord,
     DnsRecordType,
     Instant,
     isDeepEqual,
+    Lifetime,
     Logger,
     MatterAggregateError,
     Millis,
@@ -26,6 +29,7 @@ import { MdnsSocket } from "./MdnsSocket.js";
 const logger = Logger.get("MdnsServer");
 
 export class MdnsServer {
+    #lifetime: Lifetime;
     #observers = new ObserverGroup();
     #recordsGenerator = new Map<string, MdnsServer.RecordGenerator>();
     readonly #records = new AsyncCache<Map<string, DnsRecord<any>[]>>(
@@ -50,8 +54,9 @@ export class MdnsServer {
 
     readonly #socket: MdnsSocket;
 
-    constructor(socket: MdnsSocket) {
+    constructor(socket: MdnsSocket, lifetime = Lifetime.process) {
         this.#socket = socket;
+        this.#lifetime = lifetime.join("mdns server");
         this.#observers.on(this.#socket.receipt, this.#handleMessage.bind(this));
     }
 
@@ -68,6 +73,8 @@ export class MdnsServer {
     }
 
     async #handleMessage(incomingMessage: MdnsSocket.Message) {
+        using _processing = this.#lifetime.join("processing message");
+
         const records = await this.#records.get(incomingMessage.sourceIntf);
 
         // Ignore if we have no records for interface
@@ -166,6 +173,8 @@ export class MdnsServer {
     }
 
     async broadcast(...services: string[]) {
+        using _broadcasting = this.#lifetime.join("broadcasting", Diagnostic.strong(describeList("and", ...services)));
+
         await MatterAggregateError.allSettled(
             (await this.#getMulticastInterfacesForAnnounce()).map(async ({ name: netInterface }) => {
                 const records = await this.#records.get(netInterface);
@@ -182,6 +191,8 @@ export class MdnsServer {
     }
 
     async expireAnnouncements(...services: string[]) {
+        using _expiring = this.#lifetime.join("expiring", Diagnostic.strong(describeList("and", ...services)));
+
         await MatterAggregateError.allSettled(
             this.#records.keys().map(async netInterface => {
                 const records = await this.#records.get(netInterface);
@@ -218,6 +229,7 @@ export class MdnsServer {
     }
 
     async close() {
+        using _closing = this.#lifetime.closing();
         this.#observers.close();
         await this.#records.close();
         for (const { timer } of this.#truncatedQueryCache.values()) {

package/src/mdns/MdnsService.ts

@@ -45,12 +45,13 @@ export class MdnsService {
 
         this.#construction = Construction(this, async () => {
             this.#socket = await MdnsSocket.create(network, {
+                lifetime: this.#construction,
                 enableIpv4: this.enableIpv4,
                 netInterface: this.limitedToNetInterface,
             });
 
-            this.#server = new MdnsServer(this.#socket);
-            this.#client = new MdnsClient(this.#socket);
+            this.#server = new MdnsServer(this.#socket, this.#construction);
+            this.#client = new MdnsClient(this.#socket, this.#construction);
         });
     }
 

package/src/mdns/MdnsSocket.ts

@@ -5,6 +5,7 @@
  */
 
 import {
+    AsyncObservable,
     BasicObservable,
     Bytes,
     Diagnostic,
@@ -13,6 +14,7 @@ import {
     DnsMessagePartiallyPreEncoded,
     DnsMessageType,
     DnsMessageTypeFlag,
+    Lifetime,
     Logger,
     MatterAggregateError,
     MAX_MDNS_MESSAGE_SIZE,
@@ -31,15 +33,19 @@ export class MdnsSocket {
     #socket: UdpMulticastServer;
     #handlers?: Set<PromiseLike<void>>;
     #isClosed = false;
-    #receipt = new BasicObservable<[message: MdnsSocket.Message]>(
+    #receipt: AsyncObservable<[message: MdnsSocket.Message]> = new BasicObservable(
         error => logger.error("Unhandled error in MDNS listener", error),
         true,
     );
 
-    static async create(network: Network, options?: { enableIpv4?: boolean; netInterface?: string }) {
-        const { enableIpv4 = true, netInterface } = options ?? {};
+    static async create(
+        network: Network,
+        options?: { enableIpv4?: boolean; netInterface?: string; lifetime?: Lifetime.Owner },
+    ) {
+        const { enableIpv4 = true, netInterface, lifetime } = options ?? {};
         const socket = new MdnsSocket(
             await UdpMulticastServer.create({
+                lifetime,
                 network,
                 netInterface,
                 broadcastAddressIpv4: enableIpv4 ? MDNS_BROADCAST_IPV4 : undefined,

package/src/peer/ControllerCommissioner.ts

@@ -38,8 +38,8 @@ import {
 import { ControllerDiscovery, PairRetransmissionLimitReachedError } from "#peer/ControllerDiscovery.js";
 import { ExchangeManager } from "#protocol/ExchangeManager.js";
 import { DedicatedChannelExchangeProvider } from "#protocol/ExchangeProvider.js";
-import { MessageChannel } from "#protocol/MessageChannel.js";
 import { ChannelStatusResponseError } from "#securechannel/SecureChannelMessenger.js";
+import { NodeSession } from "#session/NodeSession.js";
 import { PaseClient } from "#session/pase/PaseClient.js";
 import { SessionManager } from "#session/SessionManager.js";
 import { DiscoveryCapabilitiesBitmap, NodeId, SECURE_CHANNEL_PROTOCOL_ID, TypeFromPartialBitSchema } from "#types";
@@ -177,21 +177,21 @@ export class ControllerCommissioner {
         addresses.sort(a => (a.type === "udp" ? -1 : 1));
 
         // Attempt a connection on each known address
-        let channel: MessageChannel | undefined;
+        let session: NodeSession | undefined;
         for (const address of addresses) {
             try {
-                channel = await this.#initializePaseSecureChannel(address, passcode, discoveryData);
+                session = await this.#initializePaseSecureChannel(address, passcode, discoveryData);
             } catch (e) {
                 NoResponseTimeoutError.accept(e);
                 logger.warn(`Could not connect to ${ServerAddress.urlFor(address)}: ${e.message}`);
             }
         }
 
-        if (channel === undefined) {
+        if (session === undefined) {
             throw new NoResponseTimeoutError("Could not connect to device");
         }
 
-        return await this.#commissionConnectedNode(channel, options, discoveryData);
+        return await this.#commissionConnectedNode(session, options, discoveryData);
     }
 
     /**
@@ -199,7 +199,7 @@ export class ControllerCommissioner {
      */
     async discoverAndEstablishPase(
         options: DiscoveryAndCommissioningOptions,
-    ): Promise<{ paseSecureChannel: MessageChannel; discoveryData?: DiscoveryData }> {
+    ): Promise<{ paseSession: NodeSession; discoveryData?: DiscoveryData }> {
         const {
             discovery: { timeout = Seconds(30) },
             passcode,
@@ -245,18 +245,18 @@ export class ControllerCommissioner {
         );
 
         // If we have a known address we try this first before we discover the device
-        let paseSecureChannel: MessageChannel | undefined;
+        let paseSession: NodeSession | undefined;
         let discoveryData: DiscoveryData | undefined;
 
         // If we have a last known address, try this first
         if (knownAddress !== undefined) {
             try {
-                paseSecureChannel = await this.#initializePaseSecureChannel(knownAddress, passcode);
+                paseSession = await this.#initializePaseSecureChannel(knownAddress, passcode);
             } catch (error) {
                 NoResponseTimeoutError.accept(error);
             }
         }
-        if (paseSecureChannel === undefined) {
+        if (paseSession === undefined) {
             const discoveredDevices = await ControllerDiscovery.discoverDeviceAddressesByIdentifier(
                 scannersToUse,
                 identifierData,
@@ -276,10 +276,10 @@ export class ControllerCommissioner {
             );
 
             // Pairing was successful, so store the address and assign the established secure channel
-            paseSecureChannel = result;
+            paseSession = result;
         }
 
-        return { paseSecureChannel, discoveryData };
+        return { paseSession, discoveryData };
     }
 
     /**
@@ -293,10 +293,10 @@ export class ControllerCommissioner {
         }
 
         // Establish PASE channel
-        const { paseSecureChannel, discoveryData } = await this.discoverAndEstablishPase(options);
+        const { paseSession, discoveryData } = await this.discoverAndEstablishPase(options);
 
         // Commission the node
-        return await this.#commissionConnectedNode(paseSecureChannel, options, discoveryData);
+        return await this.#commissionConnectedNode(paseSession, options, discoveryData);
     }
 
     /**
@@ -308,7 +308,7 @@ export class ControllerCommissioner {
         address: ServerAddress,
         passcode: number,
         device?: DiscoveryData,
-    ): Promise<MessageChannel> {
+    ): Promise<NodeSession> {
         let paseChannel: Channel<Bytes>;
         if (device !== undefined) {
             logger.info(`Establish PASE to device`, MdnsClient.discoveryDataDiagnostics(device));
@@ -349,8 +349,9 @@ export class ControllerCommissioner {
                 );
         }
 
-        // Do PASE paring
-        const unsecureSession = this.#context.sessions.createInsecureSession({
+        // Do PASE pairing
+        const unsecuredSession = this.#context.sessions.createUnsecuredSession({
+            channel: paseChannel,
             // Use the session parameters from MDNS announcements when available and rest is assumed to be fallbacks
             sessionParameters: {
                 idleInterval: Millis(device?.SII),
@@ -359,32 +360,31 @@ export class ControllerCommissioner {
             },
             isInitiator: true,
         });
-        const paseUnsecureMessageChannel = new MessageChannel(paseChannel, unsecureSession);
-        const paseExchange = this.#context.exchanges.initiateExchangeWithChannel(
-            paseUnsecureMessageChannel,
+        const paseExchange = this.#context.exchanges.initiateExchangeForSession(
+            unsecuredSession,
             SECURE_CHANNEL_PROTOCOL_ID,
         );
 
-        let paseSecureSession;
         try {
-            paseSecureSession = await this.#paseClient.pair(
+            const caseSession = await this.#paseClient.pair(
                 this.#context.sessions.sessionParameters,
                 paseExchange,
+                paseChannel,
                 passcode,
             );
+            unsecuredSession.detachChannel();
+            return caseSession;
         } catch (e) {
             // Close the exchange and rethrow
-            await paseExchange.close();
             if (e instanceof ChannelStatusResponseError) {
                 throw new NoResponseTimeoutError(
                     `Establishing PASE channel failed with channel status response error ${e.message}`,
                 );
             }
             throw e;
+        } finally {
+            await unsecuredSession.initiateForceClose();
         }
-
-        await unsecureSession.destroy();
-        return new MessageChannel(paseChannel, paseSecureSession);
     }
 
     /** Validate if a Peer Address is already known and commissioned */
@@ -415,7 +415,7 @@ export class ControllerCommissioner {
      * success.
      */
     async #commissionConnectedNode(
-        paseSecureMessageChannel: MessageChannel,
+        paseSession: NodeSession,
         options: CommissioningOptions,
         discoveryData?: DiscoveryData,
     ): Promise<PeerAddress> {
@@ -466,7 +466,7 @@ export class ControllerCommissioner {
         const commissioningManager = new commissioningFlowImpl(
             // Use the created secure session to do the commissioning
             new InteractionClient(
-                new DedicatedChannelExchangeProvider(this.#context.exchanges, paseSecureMessageChannel),
+                new DedicatedChannelExchangeProvider(this.#context.exchanges, paseSession),
                 undefined,
                 address,
             ),
@@ -480,7 +480,7 @@ export class ControllerCommissioner {
                         commissioning flow the commissioning channel SHALL terminate after successful step 12 (trigger
                         joining of operational network at Commissionee).
                      */
-                    await paseSecureMessageChannel.close(); // We reconnect using Case, so close PASE connection
+                    await paseSession.initiateClose(); // We reconnect using Case, so close PASE connection
                 }
 
                 if (performCaseCommissioning !== undefined) {
@@ -504,17 +504,15 @@ export class ControllerCommissioner {
             await commissioningManager.executeCommissioning();
         } catch (error) {
             // We might have added data for an operational address that we need to cleanup
-            await this.#context.clients.peers.delete(address);
+            await this.#context.clients.peers.get(address)?.delete();
             throw error;
         } finally {
-            if (!paseSecureMessageChannel.closed) {
-                /*
-                    In concurrent connection commissioning flow the commissioning channel SHALL terminate after
-                    successful step 15 (CommissioningComplete command invocation).
-                    If PaseSecureMessageChannel is not already closed, we are in non-concurrent connection commissioning flow.
-                 */
-                await paseSecureMessageChannel.close(); // We are done, so close PASE session
-            }
+            /*
+                In concurrent connection commissioning flow the commissioning channel SHALL terminate after
+                successful step 15 (CommissioningComplete command invocation).
+                If PaseSecureMessageChannel is not already closed, we are in non-concurrent connection commissioning flow.
+                */
+            await paseSession.initiateClose(); // We are done, so close PASE session
         }
 
         return address;

package/src/peer/ControllerDiscovery.ts

@@ -15,6 +15,7 @@ import {
     ServerAddress,
 } from "#general";
 import { CommissionableDeviceDiscoveryFailedError } from "#peer/ControllerCommissioningFlow.js";
+import { RetransmissionLimitReachedError } from "#protocol/errors.js";
 import { NodeId } from "#types";
 import {
     AddressTypeFromDevice,
@@ -26,7 +27,6 @@ import {
 } from "../common/Scanner.js";
 import { Fabric } from "../fabric/Fabric.js";
 import { MdnsClient } from "../mdns/MdnsClient.js";
-import { RetransmissionLimitReachedError } from "../protocol/MessageExchange.js";
 
 const logger = Logger.get("ControllerDiscovery");