@matter/protocol 0.16.0-alpha.0-20250807-37b08c9bb → 0.16.0-alpha.0-20250810-5c91a95d2

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@matter/protocol",
-    "version": "0.16.0-alpha.0-20250807-37b08c9bb",
+    "version": "0.16.0-alpha.0-20250810-5c91a95d2",
     "description": "Low-level APIs for Matter interaction",
     "keywords": [
         "iot",
@@ -17,12 +17,12 @@
         "Greg Lauckhart <greg@lauckhart.com>"
     ],
     "bugs": {
-        "url": "https://github.com/matter-js/matter/issues"
+        "url": "https://github.com/matter-js/matter.js/issues"
     },
-    "homepage": "https://github.com/matter-js/matter",
+    "homepage": "https://github.com/matter-js/matter.js",
     "repository": {
         "type": "git",
-        "url": "git+https://github.com/matter-js/matter.git"
+        "url": "git+https://github.com/matter-js/matter.js.git"
     },
     "scripts": {
         "clean": "matter-build clean",
@@ -40,13 +40,13 @@
         "#*": "./src/*"
     },
     "dependencies": {
-        "@matter/general": "0.16.0-alpha.0-20250807-37b08c9bb",
-        "@matter/model": "0.16.0-alpha.0-20250807-37b08c9bb",
-        "@matter/types": "0.16.0-alpha.0-20250807-37b08c9bb"
+        "@matter/general": "0.16.0-alpha.0-20250810-5c91a95d2",
+        "@matter/model": "0.16.0-alpha.0-20250810-5c91a95d2",
+        "@matter/types": "0.16.0-alpha.0-20250810-5c91a95d2"
     },
     "devDependencies": {
-        "@matter/tools": "0.16.0-alpha.0-20250807-37b08c9bb",
-        "@matter/testing": "0.16.0-alpha.0-20250807-37b08c9bb"
+        "@matter/tools": "0.16.0-alpha.0-20250810-5c91a95d2",
+        "@matter/testing": "0.16.0-alpha.0-20250810-5c91a95d2"
     },
     "files": [
         "dist/**/*",

package/src/advertisement/Advertisement.ts

@@ -0,0 +1,348 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { asError, CancelablePromise, CanceledError, Diagnostic, Logger, MatterAggregateError, Time } from "#general";
+import { STANDARD_COMMISSIONING_TIMEOUT_S } from "#types";
+import type { Advertiser } from "./Advertiser.js";
+import { ServiceDescription } from "./ServiceDescription.js";
+
+const logger = Logger.get("Advertisement");
+
+/**
+ * An advertisement for a discrete service.
+ */
+export abstract class Advertisement<T extends ServiceDescription = ServiceDescription> {
+    /**
+     * The service advertised.
+     *
+     * This is a unique ID associated with the advertisement.
+     */
+    readonly service: string;
+
+    /**
+     * The information advertised.
+     */
+    readonly description: T;
+
+    /**
+     * The {@link Advertiser} that owns this advertisement.
+     */
+    readonly advertiser: Advertiser;
+
+    /**
+     * Configuration options.
+     */
+    readonly options: Advertisement.Options;
+
+    #isBroadcasting = false;
+    #closed?: Promise<void>;
+    #startedAt = Time.nowMs();
+
+    /**
+     * Current activity.  This is a promise with helpers for base implementations.
+     */
+    #activity?: ActivityContext;
+
+    constructor(advertiser: Advertiser, service: string, description: T, options?: Advertisement.Options) {
+        this.options = options ?? {};
+        this.service = service;
+        this.advertiser = advertiser;
+        this.description = description;
+
+        advertiser.advertisements.add(this);
+
+        // Initial activity just handles async setup
+        this.#start(this.onCreate.bind(this));
+    }
+
+    /**
+     * Begin automatic broadcast.
+     */
+    start(event: Advertiser.BroadcastEvent) {
+        if (this.#closed) {
+            return;
+        }
+
+        // If we are already broadcasting, do not reset the schedule.  In cases where the schedule should reset,
+        // higher-level components replace the advertisement or stop manually
+        if (this.isBroadcasting) {
+            return;
+        }
+
+        // Run broadcast as the current activity
+        this.#start(context => this.#run(context, event));
+    }
+
+    /**
+     * End automatic broadcast.
+     */
+    stop() {
+        this.#activity?.cancel();
+        this.#isBroadcasting = false;
+    }
+
+    /**
+     * Notify the advertiser that a client connection to the advertised service is established.
+     */
+    serviceConnected() {
+        // No default behavior
+    }
+
+    /**
+     * Notify the advertiser that there is no client connection to the advertised service.
+     */
+    serviceDisconnected() {
+        // No default behavior
+    }
+
+    /**
+     * Close the advertisement but do not wait for the close to finish.
+     *
+     * The advertisement is still tracked by the advertiser until closed.
+     */
+    cancel() {
+        this.close().catch(e => {
+            // This shouldn't happen because close should log errors itself
+            logger.error("Unhandled error closing advertisement for", Diagnostic.strong(this.service), e);
+        });
+    }
+
+    /**
+     * Close the advertisement.
+     */
+    close() {
+        if (this.#closed) {
+            return this.#closed;
+        }
+
+        return (this.#closed = this.#close());
+    }
+
+    async #close() {
+        try {
+            this.#activity?.cancel();
+            await this.#activity;
+
+            try {
+                await this.onClose();
+            } catch (e) {
+                logger.error("Unhandled error closing advertisement for", Diagnostic.strong(this.service), e);
+            }
+        } finally {
+            this.advertiser.advertisements.delete(this);
+        }
+    }
+
+    /**
+     * Async setup logic.
+     */
+    protected async onCreate() {
+        // Deduplicate advertisements.  There may only be a single commissioning advertisement per advertiser and a
+        // single operational advertisement per advertiser+service
+        const duplicates = [...this.advertiser.advertisements].filter(this.isDuplicate.bind(this));
+        if (duplicates.length) {
+            await Advertisement.closeAll(duplicates);
+        }
+    }
+
+    /**
+     * Async cleanup logic.
+     */
+    protected async onClose() {}
+
+    /**
+     * Indicates that broadcasts should omit private details.
+     */
+    protected get isPrivacyMasked() {
+        // Private broadcast configured explicitly
+        if (this.options.omitPrivateDetails) {
+            return true;
+        }
+
+        // Extended announcement
+        if (Time.nowMs() - this.#startedAt >= STANDARD_COMMISSIONING_TIMEOUT_S * 1000) {
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * Implement automatic advertising.
+     */
+    protected abstract run(context: Advertisement.ActivityContext, event: Advertiser.BroadcastEvent): Promise<void>;
+
+    isCommissioning(): this is
+        | Advertisement<ServiceDescription.Commissionable>
+        | Advertisement<ServiceDescription.Commissioner> {
+        return ServiceDescription.isCommissioning(this.description);
+    }
+
+    isOperational(): this is Advertisement<ServiceDescription.Operational> {
+        return ServiceDescription.isOperational(this.description);
+    }
+
+    /**
+     * Cancel a set of advertisements.
+     */
+    static cancelAll(ads: Iterable<Advertisement>) {
+        for (const ad of ads) {
+            ad.cancel();
+        }
+    }
+
+    /**
+     * Cancel a set of advertisements and wait for them to complete.
+     */
+    static async closeAll(ads: Iterable<Advertisement>) {
+        await MatterAggregateError.allSettled([...ads].map(ad => ad.close()));
+    }
+
+    /**
+     * Identify other advertisers for the same service.  The advertiser will close these automatically.
+     */
+    abstract isDuplicate(other: Advertisement): boolean;
+
+    /**
+     * Total duration so far.
+     */
+    get duration() {
+        return Time.nowMs() - this.#startedAt;
+    }
+
+    /**
+     * True if the advertisement is actively broadcasting.
+     */
+    get isBroadcasting() {
+        return this.#isBroadcasting;
+    }
+
+    protected dict(values?: Record<string, unknown>) {
+        return Diagnostic.dict({ kind: this.description.kind, service: this.service, ...values });
+    }
+
+    #start(executor: (context: ActivityContext) => Promise<void>) {
+        // Only one activity may be active
+        const previous = this.#activity;
+        previous?.cancel();
+
+        this.#activity = new ActivityContext(async context => {
+            // Wait for previous activity to complete
+            if (previous) {
+                await previous;
+            }
+
+            // Run the new activity
+            try {
+                await executor(context);
+            } finally {
+                // Clear the current activity if it's this one
+                if (this.#activity === context) {
+                    this.#activity = undefined;
+                }
+            }
+        });
+    }
+
+    async #run(context: ActivityContext, event: Advertiser.BroadcastEvent, previous?: ActivityContext) {
+        // If automatic advertisement starts when it is already active, kill the previous version
+        if (previous) {
+            await previous;
+        }
+
+        logger.debug("Begin auto broadcast", this.dict());
+
+        // Perform advertisement
+        try {
+            this.#isBroadcasting = true;
+            await this.run(context, event);
+        } catch (e) {
+            if (!(e instanceof CanceledError)) {
+                logger.error("Unhandled error during automatic advertisement for", Diagnostic.strong(this.service), e);
+            }
+        } finally {
+            if (this.#activity === context) {
+                // We clear this flag in stop() but it will still be set if the automatic broadcast period elapses
+                this.#isBroadcasting = false;
+            }
+        }
+
+        logger.debug("End auto broadcast", this.dict());
+    }
+}
+
+export namespace Advertisement {
+    export interface Options {
+        /**
+         * Set this to omit optional details from broadcasts that may affect privacy.
+         *
+         * Per core spec 5.4.2.3.1, the device always omits vendor ID, product ID and extended data during extended
+         * announcement.  Set this value to omit this fields unconditionally.
+         */
+        omitPrivateDetails?: boolean;
+    }
+
+    export interface ActivityContext {
+        /**
+         * Enter cancelable sleep.
+         *
+         * Throws {@link CanceledError} if interrupted.  If thrown from {@link run} this will result in the promise
+         * resolving.
+         */
+        sleep(name: string, intervalMs: number): Promise<void>;
+    }
+}
+
+class ActivityContext extends CancelablePromise implements Advertisement.ActivityContext {
+    #sleep?: CancelablePromise;
+    #cancelReason?: Error;
+
+    constructor(executor: (context: ActivityContext) => Promise<void>) {
+        let resolve, reject;
+        super((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+
+        executor(this).then(resolve, cause => {
+            if (cause instanceof CanceledError) {
+                resolve!();
+            } else {
+                reject!(cause);
+            }
+        });
+    }
+
+    sleep(name: string, intervalMs: number) {
+        this.abortIfCanceled();
+
+        const sleep = Time.sleep(name, intervalMs).finally(() => {
+            if (this.#sleep === sleep) {
+                this.#sleep = undefined;
+            }
+        });
+
+        this.#sleep = sleep;
+        return sleep;
+    }
+
+    protected abortIfCanceled() {
+        if (this.#cancelReason) {
+            throw this.#cancelReason;
+        }
+    }
+
+    protected override onCancel(reason: unknown) {
+        if (this.#cancelReason) {
+            return;
+        }
+        this.#cancelReason = asError(reason);
+
+        if (this.#sleep) {
+            this.#sleep.cancel(reason);
+        }
+    }
+}

package/src/advertisement/Advertiser.ts

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Fabric } from "#fabric/Fabric.js";
+import { Advertisement } from "./Advertisement.js";
+import type { ServiceDescription } from "./ServiceDescription.js";
+
+/**
+ * A component that advertises a Matter service.
+ */
+export abstract class Advertiser {
+    #advertisements = new Set<Advertisement>();
+    #isClosed = false;
+
+    /**
+     * Begin advertising on configured schedule.
+     *
+     * Note that so long as the advertisement is installed the device will continue to respond to MDNS queries even if
+     * the advertisement schedule is elapsed.
+     *
+     * Returns undefined if the advertiser does not support this type of advertisement.
+     */
+    advertise(description: ServiceDescription, event: Advertiser.BroadcastEvent): Advertisement | undefined {
+        if (this.#isClosed) {
+            return;
+        }
+
+        const ad = this.getAdvertisement(description);
+        if (ad) {
+            ad.start(event);
+        }
+
+        return ad;
+    }
+
+    /**
+     * Create a new advertiser or retrieve existing advertiser.
+     */
+    protected abstract getAdvertisement(description: ServiceDescription): Advertisement | undefined;
+
+    /**
+     * Destroy the instance.
+     */
+    async close() {
+        this.#isClosed = true;
+        await Advertisement.closeAll(this.#advertisements);
+    }
+
+    /**
+     * The set of advertisements active for this advertiser.
+     */
+    get advertisements() {
+        return this.#advertisements;
+    }
+
+    /**
+     * Obtain the active advertisement for {@link fabric}, if any.
+     */
+    advertisementForFabric(fabric: Fabric) {
+        for (const ad of this.#advertisements) {
+            if (ad.isOperational() && ad.description.fabric === fabric) {
+                return ad;
+            }
+        }
+    }
+
+    /**
+     * Select advertisements using a predicate.
+     */
+    filter(predicate: (ad: Advertisement) => boolean) {
+        return [...this.#advertisements].filter(predicate);
+    }
+}
+
+export namespace Advertiser {
+    /**
+     * A hint for scheduling regarding why broadcast is initiated.
+     */
+    export type BroadcastEvent = "startup" | "reconnect" | "retransmit";
+}

package/src/advertisement/CommissioningMode.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export enum CommissioningMode {
+    NotCommissioning = 0,
+    Basic = 1,
+    Enhanced = 2,
+}

package/src/{common/InstanceBroadcaster.ts → advertisement/PairingHintBitmap.ts}

@@ -4,8 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { BitFlag, BitmapSchema, ProductDescription, TypeFromPartialBitSchema, VendorId } from "#types";
-import { Fabric } from "../fabric/Fabric.js";
+import { BitFlag, BitmapSchema } from "@matter/types";
 
 export const PairingHintBitmap = {
     /**
@@ -128,93 +127,3 @@ export const PairingHintBitmap = {
 };
 
 export const PairingHintBitmapSchema = BitmapSchema(PairingHintBitmap);
-
-export interface CommissioningModeInstanceData extends ProductDescription {
-    /** Device discriminator for commissionable announcements. */
-    discriminator: number;
-
-    /** Session Idle Interval of the device for commissionable announcements. */
-    sessionIdleInterval?: number;
-
-    /** Session Active Interval of the device for commissionable announcements. */
-    sessionActiveInterval?: number;
-
-    /** Duration of time the node should stay active after the last network activity. **/
-    sessionActiveThreshold?: number;
-
-    /** Pairing hint of the device for commissionable announcements. */
-    pairingHint?: TypeFromPartialBitSchema<typeof PairingHintBitmap>;
-
-    /** Pairing instruction of the device for commissionable announcements. */
-    pairingInstructions?: string;
-}
-
-export type CommissionerInstanceData = {
-    /** Device name for commissionable announcements. */
-    deviceName: string;
-
-    /** Device type for commissionable announcements. */
-    vendorId: VendorId;
-
-    /** Vendor ID for commissionable announcements. */
-    productId: number;
-
-    /** Device type for commissionable announcements. */
-    deviceType?: number;
-
-    /** Session Idle Interval of the device for commissionable announcements. */
-    sessionIdleInterval?: number;
-
-    /** Session Active Interval of the device for commissionable announcements. */
-    sessionActiveInterval?: number;
-
-    /** This key defines the duration of time the node stays Active after the last network activity. **/
-    sessionActiveThreshold?: number;
-};
-
-export type OperationalInstanceData = {
-    /** Session Idle Interval of the device for operational announcements. */
-    sessionIdleInterval?: number;
-
-    /** Session Active Interval of the device for operational announcements. */
-    sessionActiveInterval?: number;
-
-    /** This key defines the duration of time the node stays Active after the last network activity. **/
-    sessionActiveThreshold?: number;
-};
-
-export enum CommissioningMode {
-    NotCommissioning = 0,
-    Basic = 1,
-    Enhanced = 2,
-}
-
-/** Interface for classes that allow to announce one Matter instance. */
-export interface InstanceBroadcaster {
-    /** Set a commissionable mode and details to announce a commissionable device. */
-    setCommissionMode(mode: CommissioningMode, deviceData: CommissioningModeInstanceData): Promise<void>;
-
-    /**
-     * Set operational details to Announce an operational device which is already commissioned.
-     * Use expireCommissioningAnnouncements = true when Fabrics are changed after a n commissioning process.
-     */
-    setFabrics(fabrics: Fabric[], expireCommissioningAnnouncements?: boolean): Promise<void>;
-
-    /** Set commissioner details to announce a commissioner service for User directed commissioning (UDC). */
-    setCommissionerInfo(commissionerData: CommissionerInstanceData): Promise<void>;
-
-    /** Send out announcements for this instance. */
-    announce(): Promise<void>;
-
-    /** Expire the announcement for this operative instance. */
-    expireFabricAnnouncement(): Promise<void>;
-
-    /** Expire the announcement for this commissioning instance. */
-    expireCommissioningAnnouncement(): Promise<void>;
-
-    /** Expire all announcements. */
-    expireAllAnnouncements(): Promise<void>;
-
-    /** Destroy the instance */
-    close(): Promise<void>;
-}

package/src/advertisement/ServiceDescription.ts

@@ -0,0 +1,110 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { PairingHintBitmap } from "#advertisement/PairingHintBitmap.js";
+import { SupportedTransportsBitmap } from "#common/SupportedTransportsBitmap.js";
+import type { Fabric } from "#fabric/Fabric.js";
+import { SessionIntervals } from "#session/SessionIntervals.js";
+import type { ProductDescription, TypeFromPartialBitSchema } from "@matter/types";
+import { IcdManagement } from "@matter/types/clusters/icd-management";
+import { CommissioningMode } from "./CommissioningMode.js";
+
+export type ServiceDescription =
+    | ServiceDescription.Operational
+    | ServiceDescription.Commissionable
+    | ServiceDescription.Commissioner;
+
+export namespace ServiceDescription {
+    export function isCommissioning(description: ServiceDescription): description is Commissionable | Commissioner {
+        return description.kind === "commissionable" || description.kind === "commissioner";
+    }
+
+    export function isOperational(description: ServiceDescription): description is Operational {
+        return description.kind === "operational";
+    }
+
+    export interface Base extends Partial<SessionIntervals> {
+        /**
+         * The IP port for the Matter protocol.
+         */
+        port?: number;
+
+        /**
+         * Indicate support for TCP.
+         */
+        tcp?: SupportedTransportsBitmap;
+
+        /**
+         * Indicate support for ICD.
+         */
+        icd?: IcdManagement.OperatingMode;
+    }
+
+    export interface Commissionable extends Base, ProductDescription {
+        readonly kind: "commissionable";
+
+        /**
+         * The commissioning mode.
+         */
+        readonly mode: CommissioningMode;
+
+        /**
+         * Device discriminator for commissionable announcements.
+         */
+        readonly discriminator: number;
+
+        /**
+         * Pairing hint of the device for commissionable announcements.
+         */
+        readonly pairingHint?: TypeFromPartialBitSchema<typeof PairingHintBitmap>;
+
+        /**
+         * Pairing instruction of the device for commissionable announcements.
+         */
+        readonly pairingInstructions?: string;
+    }
+
+    export function Commissionable(definition: Omit<Commissionable, "kind">): Commissionable {
+        return {
+            ...definition,
+            kind: "commissionable",
+        };
+    }
+
+    export interface Operational extends Base {
+        readonly kind: "operational";
+
+        /**
+         * The advertised fabric.
+         */
+        readonly fabric: Fabric;
+    }
+
+    export function Operational(definition: Omit<Operational, "kind">): Operational {
+        return {
+            ...definition,
+            kind: "operational",
+        };
+    }
+
+    export interface Commissioner extends Omit<ProductDescription, "deviceType">, Base {
+        readonly kind: "commissioner";
+
+        /**
+         * The device type.
+         *
+         * This is optional for commissioner advertisement.
+         */
+        readonly deviceType?: number;
+    }
+
+    export function Commissioner(definition: Omit<Commissioner, "kind">): Commissioner {
+        return {
+            ...definition,
+            kind: "commissioner",
+        };
+    }
+}