@matter/protocol 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/interaction/Subscription.ts

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger } from "#general";
+import { type SecureSession } from "#session/SecureSession.js";
+import { TlvAttributePath, TlvDataVersionFilter, TlvEventFilter, TlvEventPath, TypeFromSchema } from "#types";
+
+const logger = Logger.get("Subscription");
+
+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 class Subscription {
+    #session: SecureSession;
+    #id: SubscriptionId;
+    #isClosed?: boolean;
+    #isCanceledByPeer?: boolean;
+    #criteria: SubscriptionCriteria;
+
+    constructor(session: SecureSession, id: SubscriptionId, criteria: SubscriptionCriteria) {
+        this.#session = session;
+        this.#id = id;
+        this.#criteria = criteria;
+
+        this.#session.subscriptions.add(this);
+        logger.debug(`Added subscription ${this.#id} to ${this.#session.name}`);
+    }
+
+    get id() {
+        return this.#id;
+    }
+
+    get criteria() {
+        return this.#criteria;
+    }
+
+    get isClosed() {
+        return !!this.#isClosed;
+    }
+
+    get isCanceledByPeer() {
+        return !!this.#isCanceledByPeer;
+    }
+
+    get session() {
+        return this.#session;
+    }
+
+    /**
+     * Update session state.  This probably is meaniningless 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 session.
+     *
+     * @param _graceful in a server context this means flush pending updates.  Not sure if applies to client
+     * subscriptions
+     */
+    async close(_graceful = true): Promise<void> {
+        this.#isClosed = true;
+        this.#session.subscriptions.delete(this);
+        logger.debug(`Removed subscription ${this.id} from ${this.#session.name}`);
+    }
+}

package/src/interaction/SubscriptionOptions.ts

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export const INTERNAL_INTERVAL_PUBLISHER_LIMIT_S = 3 * 60; /** 3 min */
+export const MIN_INTERVAL_S = 2; // We do not send faster than 2 seconds
+export const DEFAULT_RANDOMIZATION_WINDOW_S = 10; // 10 seconds
+
+/**
+ * Server options that control subscription handling.
+ */
+export interface ServerSubscriptionConfig {
+    /**
+     * Optional maximum subscription interval to use for sending subscription reports. It will be used if not too
+     * low and inside the range requested by the connected controller.
+     */
+    maxIntervalSeconds: number;
+
+    /**
+     * Optional minimum subscription interval to use for sending subscription reports. It will be used when other
+     * calculated values are smaller than it. Use this to make sure your device hardware can handle the load and to
+     * set limits.
+     */
+    minIntervalSeconds: number;
+
+    /**
+     * Optional subscription randomization window to use for sending subscription reports. This specifies a window
+     * in seconds from which a random part is added to the calculated maximum interval to make sure that devices
+     * that get powered on in parallel not all send at the same timepoint.
+     */
+    randomizationWindowSeconds: number;
+}
+
+export namespace ServerSubscriptionConfig {
+    /**
+     * Validate options and set defaults.
+     *
+     * @returns the resulting options
+     */
+    export function of(options?: Partial<ServerSubscriptionConfig>) {
+        return {
+            maxIntervalSeconds: options?.maxIntervalSeconds ?? INTERNAL_INTERVAL_PUBLISHER_LIMIT_S,
+            minIntervalSeconds: Math.max(options?.minIntervalSeconds ?? MIN_INTERVAL_S, MIN_INTERVAL_S),
+            randomizationWindowSeconds: options?.randomizationWindowSeconds ?? DEFAULT_RANDOMIZATION_WINDOW_S,
+        };
+    }
+}

package/src/interaction/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./AccessControlManager.js";
+export * from "./AttributeDataDecoder.js";
+export * from "./AttributeDataEncoder.js";
+export * from "./EventDataDecoder.js";
+export * from "./EventHandler.js";
+export * from "./InteractionClient.js";
+export * from "./InteractionEndpointStructure.js";
+export * from "./InteractionMessenger.js";
+export * from "./InteractionServer.js";
+export * from "./ServerSubscription.js";
+export * from "./Subscription.js";

package/src/mdns/MdnsBroadcaster.ts

@@ -0,0 +1,415 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    AAAARecord,
+    ARecord,
+    BasicSet,
+    Bytes,
+    Crypto,
+    Diagnostic,
+    DnsRecord,
+    ImplementationError,
+    Logger,
+    Network,
+    PtrRecord,
+    SrvRecord,
+    TxtRecord,
+    isIPv4,
+    isIPv6,
+} from "#general";
+import { FabricIndex, NodeId, TypeFromPartialBitSchema } from "#types";
+import {
+    CommissionerInstanceData,
+    CommissioningModeInstanceData,
+    OperationalInstanceData,
+    PairingHintBitmap,
+    PairingHintBitmapSchema,
+} from "../common/InstanceBroadcaster.js";
+import { Fabric } from "../fabric/Fabric.js";
+import {
+    SESSION_ACTIVE_INTERVAL_MS,
+    SESSION_ACTIVE_THRESHOLD_MS,
+    SESSION_IDLE_INTERVAL_MS,
+} from "../session/Session.js";
+import {
+    MATTER_COMMISSIONER_SERVICE_QNAME,
+    MATTER_COMMISSION_SERVICE_QNAME,
+    MATTER_SERVICE_QNAME,
+    SERVICE_DISCOVERY_QNAME,
+    getCommissioningModeQname,
+    getDeviceInstanceQname,
+    getDeviceMatterQname,
+    getDeviceTypeQname,
+    getFabricQname,
+    getLongDiscriminatorQname,
+    getShortDiscriminatorQname,
+    getVendorQname,
+} from "./MdnsConsts.js";
+import { MdnsInstanceBroadcaster } from "./MdnsInstanceBroadcaster.js";
+import { AnnouncementType, MdnsServer } from "./MdnsServer.js";
+
+const logger = Logger.get("MdnsBroadcaster");
+
+//const TCP_SUPPORTED = 0;
+//const ICD_SUPPORTED = 0; // TODO: Implement ICD later
+const DEFAULT_PAIRING_HINT = {
+    powerCycle: true,
+    deviceManual: true,
+};
+
+/**
+ * This class is handing MDNS Announcements for multiple instances/devices
+ */
+export class MdnsBroadcaster {
+    readonly #activeCommissioningAnnouncements = new Set<number>();
+    readonly #activeOperationalAnnouncements = new Map<number, FabricIndex[]>();
+    readonly #network: Network;
+    readonly #mdnsServer: MdnsServer;
+    readonly #enableIpv4?: boolean;
+    readonly #instances = new BasicSet<MdnsInstanceBroadcaster>();
+
+    static async create(network: Network, options?: { enableIpv4?: boolean; multicastInterface?: string }) {
+        const { enableIpv4, multicastInterface } = options ?? {};
+        return new MdnsBroadcaster(
+            network,
+            await MdnsServer.create(network, { enableIpv4, netInterface: multicastInterface }),
+            enableIpv4,
+        );
+    }
+
+    constructor(network: Network, mdnsServer: MdnsServer, enableIpv4?: boolean) {
+        this.#network = network;
+        this.#mdnsServer = mdnsServer;
+        this.#enableIpv4 = enableIpv4;
+    }
+
+    createInstanceBroadcaster(port: number) {
+        const instance = new MdnsInstanceBroadcaster(port, this, () => {
+            this.#instances.delete(instance);
+        });
+        this.#instances.add(instance);
+
+        return instance;
+    }
+
+    #validateCommissioningData(data: CommissioningModeInstanceData) {
+        const { sessionIdleInterval, sessionActiveInterval, sessionActiveThreshold } = data;
+
+        if (sessionIdleInterval !== undefined && sessionIdleInterval > 3_600_000) {
+            throw new ImplementationError("Session Idle Interval must be less than 1 hour");
+        }
+        if (sessionActiveInterval !== undefined && sessionActiveInterval > 3_600_000) {
+            throw new ImplementationError("Session Active Interval must be less than 1 hour");
+        }
+        if (sessionActiveThreshold !== undefined && sessionActiveThreshold > 65_535) {
+            throw new ImplementationError("Session Active Threshold must be less than 65535 seconds");
+        }
+    }
+
+    #validatePairingInstructions(
+        pairingHint: TypeFromPartialBitSchema<typeof PairingHintBitmap>,
+        pairingInstructions: string,
+    ) {
+        const needsInstructions = [
+            "customInstruction",
+            "pressRestButtonForNumberOfSeconds",
+            "pressResetButtonUntilLightBlinks",
+            "pressResetButtonForNumberOfSecondsWithApplicationOfPower",
+            "pressResetButtonUntilLightBlinksWithApplicationOfPower",
+            "pressResetButtonNumberOfTimes",
+            "pressSetupButtonForNumberOfSeconds",
+            "pressSetupButtonUntilLightBlinks",
+            "pressSetupButtonForNumberOfSecondsWithApplicationOfPower",
+            "pressSetupButtonUntilLightBlinksWithApplicationOfPower",
+            "pressSetupButtonNumberOfTimes",
+        ].find(hint => (pairingHint as any)[hint] === true);
+        if (needsInstructions && pairingInstructions.length === 0) {
+            throw new ImplementationError(
+                `Pairing instructions required for Pairing Hint of type "${needsInstructions}"`,
+            );
+        }
+    }
+
+    #getIpRecords(hostname: string, ips: string[]) {
+        const records = new Array<DnsRecord<any>>();
+        ips.forEach(ip => {
+            if (isIPv6(ip)) {
+                records.push(AAAARecord(hostname, ip));
+            } else if (isIPv4(ip)) {
+                if (this.#enableIpv4) {
+                    records.push(ARecord(hostname, ip));
+                }
+            } else {
+                logger.warn(`Unknown IP address type: ${ip}`);
+            }
+        });
+        return records;
+    }
+
+    /** Set the Broadcaster data to announce a device ready for commissioning in a special mode */
+    async setCommissionMode(
+        announcedNetPort: number,
+        mode: number,
+        commissioningModeData: CommissioningModeInstanceData,
+    ) {
+        this.#validateCommissioningData(commissioningModeData); // Throws error if invalid!
+
+        const {
+            name: deviceName,
+            deviceType,
+            vendorId,
+            productId,
+            discriminator,
+            sessionIdleInterval = SESSION_IDLE_INTERVAL_MS,
+            sessionActiveInterval = SESSION_ACTIVE_INTERVAL_MS,
+            sessionActiveThreshold = SESSION_ACTIVE_THRESHOLD_MS,
+            pairingHint = DEFAULT_PAIRING_HINT,
+            pairingInstructions = "",
+        } = commissioningModeData;
+        this.#validatePairingInstructions(pairingHint, pairingInstructions); // Throws error if invalid!
+
+        // When doing a commission announcement, we need to expire any previous commissioning announcements
+        await this.expireCommissioningAnnouncement(announcedNetPort);
+
+        logger.debug(
+            `Announce commissioning mode ${mode} ${deviceName} ${deviceType} ${vendorId} ${productId} ${discriminator} ${announcedNetPort}`,
+        );
+        this.#activeCommissioningAnnouncements.add(announcedNetPort);
+
+        const shortDiscriminator = (discriminator >> 8) & 0x0f;
+        const instanceId = Bytes.toHex(Crypto.getRandomData(8)).toUpperCase();
+        const vendorQname = getVendorQname(vendorId);
+        const deviceTypeQname = getDeviceTypeQname(deviceType);
+        const shortDiscriminatorQname = getShortDiscriminatorQname(shortDiscriminator);
+        const longDiscriminatorQname = getLongDiscriminatorQname(discriminator);
+        const commissionModeQname = getCommissioningModeQname();
+        const deviceQname = getDeviceInstanceQname(instanceId);
+
+        await this.#mdnsServer.setRecordsGenerator(
+            announcedNetPort,
+            AnnouncementType.Commissionable,
+            async netInterface => {
+                const ipMac = await this.#network.getIpMac(netInterface);
+                if (ipMac === undefined) return [];
+                const { mac, ipV4, ipV6 } = ipMac;
+                const hostname = mac.replace(/:/g, "").toUpperCase() + "0000.local";
+
+                logger.debug(
+                    "Announcement Generator: Commission mode ",
+                    Diagnostic.dict({
+                        mode,
+                        qname: deviceQname,
+                        port: announcedNetPort,
+                        interface: netInterface,
+                    }),
+                );
+
+                const records = [
+                    PtrRecord(SERVICE_DISCOVERY_QNAME, MATTER_COMMISSION_SERVICE_QNAME),
+                    PtrRecord(SERVICE_DISCOVERY_QNAME, vendorQname),
+                    PtrRecord(SERVICE_DISCOVERY_QNAME, deviceTypeQname),
+                    PtrRecord(SERVICE_DISCOVERY_QNAME, shortDiscriminatorQname),
+                    PtrRecord(SERVICE_DISCOVERY_QNAME, longDiscriminatorQname),
+                    PtrRecord(SERVICE_DISCOVERY_QNAME, commissionModeQname),
+                    PtrRecord(MATTER_COMMISSION_SERVICE_QNAME, deviceQname),
+                    PtrRecord(vendorQname, deviceQname),
+                    PtrRecord(deviceTypeQname, deviceQname),
+                    PtrRecord(shortDiscriminatorQname, deviceQname),
+                    PtrRecord(longDiscriminatorQname, deviceQname),
+                    PtrRecord(commissionModeQname, deviceQname),
+                    SrvRecord(deviceQname, { priority: 0, weight: 0, port: announcedNetPort, target: hostname }),
+                    TxtRecord(deviceQname, [
+                        `VP=${vendorId}+${productId}` /* Vendor / Product */,
+                        `DT=${deviceType}` /* Device Type */,
+                        `DN=${deviceName}` /* Device Name */,
+                        `SII=${sessionIdleInterval}` /* Session Idle Interval */,
+                        `SAI=${sessionActiveInterval}` /* Session Active Interval */,
+                        `SAT=${sessionActiveThreshold}` /* Session Active Threshold */,
+                        //`T=${TCP_SUPPORTED}` /* TCP not supported */,
+                        `D=${discriminator}` /* Discriminator */,
+                        `CM=${mode}` /* Commission Mode */,
+                        `PH=${PairingHintBitmapSchema.encode(pairingHint)}` /* Pairing Hint */,
+                        `PI=${pairingInstructions}` /* Pairing Instruction */,
+                        //`ICD=${ICD_SUPPORTED}` /* ICD not supported */,
+                    ]),
+                ];
+                records.push(...this.#getIpRecords(hostname, [...ipV6, ...ipV4]));
+                return records;
+            },
+        );
+    }
+
+    /** Set the Broadcaster Data to announce a device for operative discovery (aka "already paired") */
+    async setFabrics(
+        announcedNetPort: number,
+        fabrics: Fabric[],
+        {
+            sessionIdleInterval = SESSION_IDLE_INTERVAL_MS,
+            sessionActiveInterval = SESSION_ACTIVE_INTERVAL_MS,
+            sessionActiveThreshold = SESSION_ACTIVE_THRESHOLD_MS,
+        }: OperationalInstanceData = {},
+    ) {
+        const currentOperationalFabrics = this.#activeOperationalAnnouncements.get(announcedNetPort);
+        if (currentOperationalFabrics !== undefined) {
+            const fabricIndexesSet = new Set(fabrics.map(f => f.fabricIndex));
+
+            // Expire Fabric announcements if any entry got removed
+            if (!currentOperationalFabrics.every(fabricIndex => fabricIndexesSet.has(fabricIndex))) {
+                await this.expireFabricAnnouncement(announcedNetPort);
+            }
+        }
+
+        this.#activeOperationalAnnouncements.set(
+            announcedNetPort,
+            fabrics.map(f => f.fabricIndex),
+        );
+
+        await this.#mdnsServer.setRecordsGenerator(announcedNetPort, AnnouncementType.Operative, async netInterface => {
+            const ipMac = await this.#network.getIpMac(netInterface);
+            if (ipMac === undefined) return [];
+            const { mac, ipV4, ipV6 } = ipMac;
+            const hostname = mac.replace(/:/g, "").toUpperCase() + "0000.local";
+
+            const records: DnsRecord<any>[] = [PtrRecord(SERVICE_DISCOVERY_QNAME, MATTER_SERVICE_QNAME)];
+            fabrics.forEach(fabric => {
+                const { operationalId, nodeId } = fabric;
+                const operationalIdString = Bytes.toHex(operationalId).toUpperCase();
+                const fabricQname = getFabricQname(operationalIdString);
+                const deviceMatterQname = getDeviceMatterQname(operationalIdString, NodeId.toHexString(nodeId));
+
+                logger.debug(
+                    "Announcement Generator: Fabric",
+                    Diagnostic.dict({
+                        id: `${Bytes.toHex(operationalId)}/${nodeId}`,
+                        qname: deviceMatterQname,
+                        port: announcedNetPort,
+                        interface: netInterface,
+                    }),
+                );
+                const fabricRecords = [
+                    PtrRecord(SERVICE_DISCOVERY_QNAME, fabricQname),
+                    PtrRecord(MATTER_SERVICE_QNAME, deviceMatterQname),
+                    PtrRecord(fabricQname, deviceMatterQname),
+                    SrvRecord(deviceMatterQname, { priority: 0, weight: 0, port: announcedNetPort, target: hostname }),
+                    TxtRecord(deviceMatterQname, [
+                        `SII=${sessionIdleInterval}` /* Session Idle Interval */,
+                        `SAI=${sessionActiveInterval}` /* Session Active Interval */,
+                        `SAT=${sessionActiveThreshold}` /* Session Active Threshold */,
+                        //`T=${TCP_SUPPORTED}` /* TCP not supported */,
+                        //`ICD=${ICD_SUPPORTED}` /* ICD not supported */,
+                    ]),
+                ];
+                records.push(...fabricRecords);
+            });
+            records.push(...this.#getIpRecords(hostname, [...ipV6, ...ipV4]));
+            return records;
+        });
+    }
+
+    /** Set the Broadcaster data to announce a Commissioner (aka Commissioner discovery) */
+    async setCommissionerInfo(
+        announcedNetPort: number,
+        {
+            deviceName,
+            deviceType,
+            vendorId,
+            productId,
+            sessionIdleInterval = SESSION_IDLE_INTERVAL_MS,
+            sessionActiveInterval = SESSION_ACTIVE_INTERVAL_MS,
+            sessionActiveThreshold = SESSION_ACTIVE_THRESHOLD_MS,
+        }: CommissionerInstanceData,
+    ) {
+        logger.debug(
+            "Announcement: Commissioner",
+            Diagnostic.dict({
+                port: announcedNetPort,
+                deviceType,
+            }),
+        );
+
+        const instanceId = Bytes.toHex(Crypto.getRandomData(8)).toUpperCase();
+        const deviceTypeQname = `_T${deviceType}._sub.${MATTER_COMMISSIONER_SERVICE_QNAME}`;
+        const vendorQname = `_V${vendorId}._sub.${MATTER_COMMISSIONER_SERVICE_QNAME}`;
+        const deviceQname = `${instanceId}.${MATTER_COMMISSIONER_SERVICE_QNAME}`;
+
+        this.#activeCommissioningAnnouncements.add(announcedNetPort);
+
+        await this.#mdnsServer.setRecordsGenerator(
+            announcedNetPort,
+            AnnouncementType.Commissionable,
+            async netInterface => {
+                const ipMac = await this.#network.getIpMac(netInterface);
+                if (ipMac === undefined) return [];
+                const { mac, ipV4, ipV6 } = ipMac;
+                const hostname = mac.replace(/:/g, "").toUpperCase() + "0000.local";
+                const records = [
+                    PtrRecord(SERVICE_DISCOVERY_QNAME, MATTER_COMMISSIONER_SERVICE_QNAME),
+                    PtrRecord(MATTER_COMMISSIONER_SERVICE_QNAME, vendorQname),
+                    PtrRecord(vendorQname, deviceQname),
+                    SrvRecord(deviceQname, { priority: 0, weight: 0, port: announcedNetPort, target: hostname }),
+                    TxtRecord(deviceQname, [
+                        `VP=${vendorId}+${productId}` /* Vendor / Product */,
+                        `DT=${deviceType}` /* Device Type */,
+                        `DN=${deviceName}` /* Device Name */,
+                        `SII=${sessionIdleInterval}` /* Session Idle Interval */,
+                        `SAI=${sessionActiveInterval}` /* Session Active Interval */,
+                        `SAT=${sessionActiveThreshold}` /* Session Active Threshold */,
+                        //`T=${TCP_SUPPORTED}` /* TCP not supported */,
+                        //`ICD=${ICD_SUPPORTED}` /* ICD not supported */,
+                    ]),
+                ];
+                if (deviceType !== undefined) {
+                    records.push(PtrRecord(SERVICE_DISCOVERY_QNAME, deviceTypeQname));
+                    records.push(PtrRecord(deviceTypeQname, deviceQname));
+                }
+
+                records.push(...this.#getIpRecords(hostname, [...ipV6, ...ipV4]));
+                return records;
+            },
+        );
+    }
+
+    async announce(announcementPort: number) {
+        this.#mdnsServer.announce(announcementPort).catch(error => logger.error(error));
+    }
+
+    async expireFabricAnnouncement(announcementPort: number) {
+        if (this.#activeOperationalAnnouncements.has(announcementPort)) {
+            await this.#mdnsServer.expireAnnouncements(announcementPort, AnnouncementType.Operative);
+            this.#activeOperationalAnnouncements.delete(announcementPort);
+        }
+    }
+
+    async expireCommissioningAnnouncement(announcementPort: number) {
+        if (this.#activeCommissioningAnnouncements.has(announcementPort)) {
+            await this.#mdnsServer.expireAnnouncements(announcementPort, AnnouncementType.Commissionable);
+            this.#activeCommissioningAnnouncements.delete(announcementPort);
+        }
+    }
+
+    async expireAllAnnouncements(announcementPort: number) {
+        if (
+            !this.#activeCommissioningAnnouncements.has(announcementPort) &&
+            !this.#activeOperationalAnnouncements.has(announcementPort)
+        )
+            return;
+        await this.#mdnsServer.expireAnnouncements(announcementPort);
+        this.#activeCommissioningAnnouncements.delete(announcementPort);
+        this.#activeOperationalAnnouncements.delete(announcementPort);
+    }
+
+    async close() {
+        while (this.#instances.size) {
+            await this.#instances.deleted;
+        }
+
+        await this.#mdnsServer.expireAnnouncements();
+        this.#activeCommissioningAnnouncements.clear();
+        this.#activeOperationalAnnouncements.clear();
+        await this.#mdnsServer.close();
+    }
+}

package/src/mdns/MdnsConsts.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { VendorId } from "#types";
+
+export const SERVICE_DISCOVERY_QNAME = "_services._dns-sd._udp.local";
+export const MATTER_COMMISSION_SERVICE_QNAME = "_matterc._udp.local";
+export const MATTER_COMMISSIONER_SERVICE_QNAME = "_matterd._udp.local";
+export const MATTER_SERVICE_QNAME = "_matter._tcp.local";
+
+export const getFabricQname = (operationalIdString: string) => `_I${operationalIdString}._sub.${MATTER_SERVICE_QNAME}`;
+export const getDeviceMatterQname = (operationalIdString: string, nodeIdString: string) =>
+    `${operationalIdString}-${nodeIdString}.${MATTER_SERVICE_QNAME}`;
+export const getVendorQname = (vendorId: VendorId) => `_V${vendorId}._sub.${MATTER_COMMISSION_SERVICE_QNAME}`;
+export const getDeviceTypeQname = (deviceType: number) => `_T${deviceType}._sub.${MATTER_COMMISSION_SERVICE_QNAME}`;
+export const getShortDiscriminatorQname = (shortDiscriminator: number) =>
+    `_S${shortDiscriminator}._sub.${MATTER_COMMISSION_SERVICE_QNAME}`;
+export const getLongDiscriminatorQname = (longDiscriminator: number) =>
+    `_L${longDiscriminator}._sub.${MATTER_COMMISSION_SERVICE_QNAME}`;
+export const getCommissioningModeQname = () => `_CM._sub.${MATTER_COMMISSION_SERVICE_QNAME}`;
+export const getDeviceInstanceQname = (instanceId: string) => `${instanceId}.${MATTER_COMMISSION_SERVICE_QNAME}`;

package/src/mdns/MdnsInstanceBroadcaster.ts

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ImplementationError } from "#general";
+import {
+    CommissionerInstanceData,
+    CommissioningModeInstanceData,
+    InstanceBroadcaster,
+} from "../common/InstanceBroadcaster.js";
+import { Fabric } from "../fabric/Fabric.js";
+import type { MdnsBroadcaster } from "./MdnsBroadcaster.js";
+
+/**
+ * This class is handing MDNS Announcements for one instance of a device aka "port".
+ *
+ * Obtain an instance via {@link MdnsBroadcaster.createInstanceBroadcaster}.
+ */
+export class MdnsInstanceBroadcaster implements InstanceBroadcaster {
+    readonly #instancePort: number;
+    readonly #mdnsBroadcaster: MdnsBroadcaster;
+    readonly #onclose: () => void;
+    #isClosed = false;
+
+    constructor(instancePort: number, mdnsBroadcaster: MdnsBroadcaster, onclose: () => void) {
+        this.#instancePort = instancePort;
+        this.#mdnsBroadcaster = mdnsBroadcaster;
+        this.#onclose = onclose;
+    }
+
+    async close() {
+        if (this.#isClosed) {
+            return;
+        }
+        this.#isClosed = true;
+
+        await this.#mdnsBroadcaster.expireAllAnnouncements(this.#instancePort);
+        this.#onclose();
+    }
+
+    async setCommissionMode(mode: number, deviceData: CommissioningModeInstanceData) {
+        this.#assertOpen();
+        await this.#mdnsBroadcaster.setCommissionMode(this.#instancePort, mode, deviceData);
+    }
+
+    /** Set the Broadcaster Data to announce a device for operative discovery (aka "already paired") */
+    async setFabrics(fabrics: Fabric[], expireCommissioningAnnouncements = false) {
+        this.#assertOpen();
+        if (expireCommissioningAnnouncements) {
+            await this.#mdnsBroadcaster.expireCommissioningAnnouncement(this.#instancePort);
+        }
+        await this.#mdnsBroadcaster.setFabrics(this.#instancePort, fabrics);
+    }
+
+    /** Set the Broadcaster data to announce a Commissioner (aka Commissioner discovery) */
+    async setCommissionerInfo(commissionerData: CommissionerInstanceData) {
+        this.#assertOpen();
+        await this.#mdnsBroadcaster.setCommissionerInfo(this.#instancePort, commissionerData);
+    }
+
+    async announce() {
+        this.#assertOpen();
+        await this.#mdnsBroadcaster.announce(this.#instancePort);
+    }
+
+    async expireFabricAnnouncement() {
+        this.#assertOpen();
+        await this.#mdnsBroadcaster.expireFabricAnnouncement(this.#instancePort);
+    }
+
+    async expireCommissioningAnnouncement() {
+        this.#assertOpen();
+        await this.#mdnsBroadcaster.expireCommissioningAnnouncement(this.#instancePort);
+    }
+
+    async expireAllAnnouncements() {
+        this.#assertOpen();
+        await this.#mdnsBroadcaster.expireAllAnnouncements(this.#instancePort);
+    }
+
+    #assertOpen() {
+        if (this.#isClosed) {
+            throw new ImplementationError("Illegal operation on closed MdnsInstanceBroadcaster");
+        }
+    }
+}