@matter/general 0.16.8-alpha.0-20260123-dff2cae52 → 0.16.8-alpha.0-20260127-65e1b40e2

package/src/net/dns-sd/DnssdName.ts

@@ -0,0 +1,252 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { DnsRecord, DnsRecordType, SrvRecordValue } from "#codec/DnsCodec.js";
+import { Logger } from "#log/Logger.js";
+import { Time } from "#time/Time.js";
+import type { Timestamp } from "#time/Timestamp.js";
+import { AsyncObserver, BasicObservable } from "#util/Observable.js";
+import { MaybePromise } from "#util/Promises.js";
+import type { DnssdNames } from "./DnssdNames.js";
+
+const logger = Logger.get("DnssdName");
+
+/**
+ * Manages records associated with a single DNS-SD qname.
+ *
+ * Every DNS-SD qname of interest has a 1:1 relationship with a single instance of this class in the context of a
+ * {@link DnssdNames}.  We therefore can use the qname or {@link DnssdName} interchangeably.
+ *
+ * An {@link DnssdName} is created when a new name is discovered or requested by another component.  The name
+ * automatically deletes when there are no longer observers or unexpired records.
+ */
+export class DnssdName extends BasicObservable<[changes: DnssdName.Changes], MaybePromise> {
+    #context: DnssdName.Context;
+    #records = new Map<string, DnssdName.Record>();
+    #recordCount = 0;
+    #changes?: Map<string, { kind: "update" | "delete"; record: DnssdName.Record }>;
+    #notified?: Promise<void>;
+    #maybeDeleting?: Promise<void>;
+    #parameters?: Map<string, string>;
+
+    constructor(
+        readonly qname: string,
+        context: DnssdName.Context,
+    ) {
+        super(e => logger.error(`Unhandled error in observer for DNS name "${qname}":`, e));
+        this.#context = context;
+    }
+
+    override off(observer: AsyncObserver<[]>) {
+        super.off(observer);
+        this.#deleteIfUnused();
+    }
+
+    async close() {
+        if (this.#notified) {
+            await this.#notified;
+        }
+        if (this.#maybeDeleting) {
+            await this.#maybeDeleting;
+        }
+    }
+
+    get records() {
+        return this.#records.values();
+    }
+
+    get parameters() {
+        if (this.#parameters === undefined) {
+            this.#parameters = new Map();
+        }
+        return this.#parameters;
+    }
+
+    get isDiscovered() {
+        return !!this.#recordCount;
+    }
+
+    installRecord(record: DnsRecord<any>) {
+        // For TXT records, extract the standard DNS-SD k/v's
+        if (record.recordType === DnsRecordType.TXT) {
+            const entries = record.value;
+            for (const entry of entries) {
+                const pos = entry.indexOf("=");
+                if (pos === -1) {
+                    this.parameters.set(entry, "");
+                } else {
+                    this.parameters.set(entry.slice(0, pos), entry.slice(pos + 1));
+                }
+            }
+        }
+
+        const key = keyOf(record);
+        if (key === undefined) {
+            this.#deleteIfUnused();
+            return false;
+        }
+
+        const oldRecord = this.#records.get(key);
+        if (oldRecord) {
+            this.#context.unregisterForExpiration(oldRecord);
+        } else {
+            this.#recordCount++;
+        }
+
+        const recordWithExpire = { ...record, expiresAt: Time.nowMs + record.ttl } as DnssdName.Record;
+
+        this.#records.set(key, recordWithExpire);
+
+        this.#context.registerForExpiration(recordWithExpire);
+
+        this.#notify("update", key, recordWithExpire);
+    }
+
+    deleteRecord(record: DnsRecord, ifOlderThan?: Timestamp) {
+        const key = keyOf(record);
+        if (key === undefined) {
+            this.#deleteIfUnused();
+            return;
+        }
+
+        const recordWithExpire = this.#records?.get(key);
+        if (!recordWithExpire) {
+            this.#deleteIfUnused();
+            return;
+        }
+
+        if (ifOlderThan !== undefined && recordWithExpire.expiresAt - recordWithExpire.ttl >= ifOlderThan) {
+            return;
+        }
+
+        this.#records.delete(key);
+        this.#recordCount--;
+
+        this.#context.unregisterForExpiration(recordWithExpire);
+
+        if (this.#deleteIfUnused()) {
+            return;
+        }
+
+        this.#notify("delete", key, recordWithExpire);
+    }
+
+    /**
+     * Delete if unused.
+     *
+     * This is async so we assess whether deletion is appropriate after a batch of updates.
+     */
+    #deleteIfUnused() {
+        if (this.isObserved || this.isDiscovered) {
+            return false;
+        }
+
+        if (this.#maybeDeleting) {
+            return true;
+        }
+
+        const maybeDelete = async () => {
+            this.#maybeDeleting = undefined;
+
+            if (this.isObserved || this.isDiscovered) {
+                return;
+            }
+
+            this.#context.delete(this);
+        };
+
+        this.#maybeDeleting = maybeDelete();
+
+        return true;
+    }
+
+    /**
+     * Notification of observers.
+     *
+     * This is async so we coalesce changes into a single notification.
+     */
+    #notify(kind: "update" | "delete", key: string, record: DnssdName.Record) {
+        if (this.#changes === undefined) {
+            this.#changes = new Map();
+        }
+        this.#changes.set(key, { kind, record });
+
+        if (this.#notified) {
+            return;
+        }
+
+        const notify = async () => {
+            while (this.#changes?.size) {
+                const changes: DnssdName.Changes = { name: this };
+                for (const { kind, record } of this.#changes.values()) {
+                    const key: "updated" | "deleted" = `${kind}d`;
+                    const list = changes[key];
+                    if (list === undefined) {
+                        changes[key] = [record];
+                    } else {
+                        list.push(record);
+                    }
+                }
+                this.#changes.clear();
+                await this.emit(changes);
+            }
+            this.#notified = undefined;
+        };
+
+        this.#notified = notify();
+    }
+}
+
+function keyOf(record: DnsRecord): string | undefined {
+    switch (record.recordType) {
+        case DnsRecordType.A:
+        case DnsRecordType.AAAA:
+        case DnsRecordType.PTR:
+            if (typeof record.value === "string") {
+                return `${record.recordType} ${record.value}`;
+            }
+            break;
+
+        case DnsRecordType.SRV:
+            if (typeof record.value === "object") {
+                const srv = record.value as SrvRecordValue;
+                return `${record.recordType} ${srv.target}:${srv.port}`;
+            }
+            break;
+    }
+}
+
+export namespace DnssdName {
+    export interface Context {
+        delete(name: DnssdName): void;
+        registerForExpiration(record: Record): void;
+        unregisterForExpiration(record: Record): void;
+    }
+
+    export interface Expiration {
+        expiresAt: Timestamp;
+    }
+
+    export interface PointerRecord extends DnsRecord<string>, Expiration {
+        recordType: DnsRecordType.PTR;
+    }
+
+    export interface HostRecord extends DnsRecord<string>, Expiration {
+        recordType: DnsRecordType.A | DnsRecordType.AAAA;
+    }
+
+    export interface ServiceRecord extends DnsRecord<SrvRecordValue>, Expiration {
+        recordType: DnsRecordType.SRV;
+    }
+
+    export type Record = PointerRecord | ServiceRecord | HostRecord;
+
+    export interface Changes {
+        name: DnssdName;
+        updated?: Record[];
+        deleted?: Record[];
+    }
+}

package/src/net/dns-sd/DnssdNames.ts

@@ -0,0 +1,208 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { DnsRecord } from "#codec/DnsCodec.js";
+import { Duration } from "#time/Duration.js";
+import { Time } from "#time/Time.js";
+import { Timestamp } from "#time/Timestamp.js";
+import { Seconds } from "#time/TimeUnit.js";
+import { Entropy } from "#util/Entropy.js";
+import { Lifetime } from "#util/Lifetime.js";
+import { Observable, ObserverGroup } from "#util/Observable.js";
+import { Scheduler } from "#util/Scheduler.js";
+import { DnssdName } from "./DnssdName.js";
+import { QueryMulticaster } from "./DnssdSolicitor.js";
+import { MdnsSocket } from "./MdnsSocket.js";
+
+/**
+ * Names collected via DNS-SD.
+ *
+ * TODO - API is designed to support Avahi, Bonjour etc. but current implementation is tied to local MDNS
+ */
+export class DnssdNames {
+    readonly #socket: MdnsSocket;
+    readonly #lifetime: Lifetime;
+    readonly #entropy: Entropy;
+    readonly #filter?: (record: DnsRecord) => boolean;
+    readonly #solicitor: QueryMulticaster;
+    readonly #observers = new ObserverGroup();
+    readonly #names = new Map<string, DnssdName>();
+    readonly #expiration: Scheduler<DnssdName.Record>;
+    readonly #discovered = new Observable<[name: DnssdName]>();
+    readonly #goodbyeProtectionWindow: Duration;
+    readonly #minTtl: Duration;
+
+    constructor({
+        socket,
+        lifetime = Lifetime.process,
+        entropy,
+        filter,
+        goodbyeProtectionWindow,
+        minTtl: minTtl,
+    }: DnssdNames.Context) {
+        this.#socket = socket;
+        this.#lifetime = lifetime.join("mdns client");
+        this.#entropy = entropy;
+        this.#filter = filter;
+        this.#solicitor = new QueryMulticaster(this);
+        this.#goodbyeProtectionWindow = goodbyeProtectionWindow ?? DnssdNames.defaults.goodbyeProtectionWindow;
+        this.#minTtl = minTtl ?? DnssdNames.defaults.minTtl;
+        this.#observers.on(this.#socket.receipt, this.#handleMessage.bind(this));
+
+        this.#expiration = new Scheduler({
+            name: "expiration scheduler",
+            lifetime: this.#lifetime,
+            timeOf: a => {
+                return a.expiresAt;
+            },
+            run: record => {
+                const discoveryName = this.#names.get(record.name);
+                if (discoveryName) {
+                    discoveryName.deleteRecord(record);
+                }
+            },
+        });
+    }
+
+    #handleMessage(message: MdnsSocket.Message) {
+        let goodbyesBefore: undefined | Timestamp;
+        for (let record of [...message.answers, ...message.additionalRecords]) {
+            if (this.#filter && !this.#filter(record)) {
+                continue;
+            }
+
+            const name = this.get(record.name);
+            if (record.ttl) {
+                if (record.ttl < this.#minTtl) {
+                    record = { ...record, ttl: this.#minTtl };
+                }
+                const wasDiscovered = name.isDiscovered;
+                name.installRecord(record);
+                if (!wasDiscovered && name.isDiscovered) {
+                    this.#discovered.emit(name);
+                }
+            } else {
+                if (goodbyesBefore === undefined) {
+                    goodbyesBefore = Timestamp(Time.nowMs - this.#goodbyeProtectionWindow);
+                }
+                name.deleteRecord(record, goodbyesBefore);
+            }
+        }
+    }
+
+    /**
+     * Test for existence of name.
+     */
+    has(name: string) {
+        name = name.toLowerCase();
+        return this.#names.has(name);
+    }
+
+    /**
+     * Retrieve the {@link DnssdName} for {@link name}.
+     *
+     * This will create the name if it does not exist, and if you do not add an observer then it will not automatically
+     * delete if there are no records.  So if you may not use the record test for existence with {@link has} first.
+     */
+    get(qname: string): DnssdName {
+        let name = this.maybeGet(qname);
+        if (name === undefined) {
+            name = new DnssdName(qname, this.#nameContext);
+            this.#names.set(qname, name);
+        }
+        return name;
+    }
+
+    /**
+     * Retrieve the {@link DnssdName} if known.
+     */
+    maybeGet(name: string) {
+        name = name.toLowerCase();
+        return this.#names.get(name);
+    }
+
+    /**
+     * Wait for all workers and close all names.
+     */
+    async close() {
+        using _closing = this.#lifetime.closing();
+        this.#observers.close();
+        await this.#expiration.close();
+        for (const name of this.#names.values()) {
+            await name.close();
+            this.#names.delete(name.qname);
+        }
+        await this.#solicitor.close();
+    }
+
+    get socket() {
+        return this.#socket;
+    }
+
+    /**
+     * Emits when a {@link DnssdName} is first discovered.
+     */
+    get discovered() {
+        return this.#discovered;
+    }
+
+    /**
+     * Shared solicitor.
+     *
+     * We offer solicitation in this object so there is not redundant solicitation across interested parties.
+     */
+    get solicitor() {
+        return this.#solicitor;
+    }
+
+    get entropy() {
+        return this.#entropy;
+    }
+
+    #nameContext: DnssdName.Context = {
+        delete: name => {
+            const known = this.#names.get(name.qname);
+            if (known === name) {
+                this.#names.delete(name.qname);
+            }
+        },
+
+        registerForExpiration: record => {
+            this.#expiration.add(record);
+        },
+
+        unregisterForExpiration: record => {
+            this.#expiration.delete(record);
+        },
+    };
+}
+
+export namespace DnssdNames {
+    export interface Context {
+        socket: MdnsSocket;
+        lifetime?: Lifetime.Owner;
+        entropy: Entropy;
+        filter?: (record: DnsRecord) => boolean;
+
+        /**
+         * The interval after discovering a record for which we ignore goodbyes.
+         *
+         * This serves as protection for out-of-order messages when a device expires then broadcasts the same record
+         * in a very short amount of time.
+         */
+        goodbyeProtectionWindow?: Duration;
+
+        /**
+         * Minimum TTL for PTR records.
+         */
+        minTtl?: Duration;
+    }
+
+    export const defaults = {
+        goodbyeProtectionWindow: Seconds(1),
+        minTtl: Seconds(15), // This is the value that Apple uses
+    };
+}

package/src/net/dns-sd/DnssdSolicitor.ts

@@ -0,0 +1,231 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { DnsMessageType, DnsQuery, DnsRecord, DnsRecordClass, DnsRecordType } from "#codec/DnsCodec.js";
+import { Logger } from "#log/Logger.js";
+import { RetrySchedule } from "#net/RetrySchedule.js";
+import { Time } from "#time/Time.js";
+import { Hours, Millis, Seconds } from "#time/TimeUnit.js";
+import { Abort } from "#util/Abort.js";
+import { BasicMultiplex } from "#util/Multiplex.js";
+import { ObservableValue } from "#util/Observable.js";
+import type { DnssdName } from "./DnssdName.js";
+import type { DnssdNames } from "./DnssdNames.js";
+
+const logger = new Logger("DiscoverySolicitor");
+
+/**
+ * Solicits DNS-SD records for specific names.
+ */
+export interface DnssdSolicitor {
+    /**
+     * Send a single MDNS query for a specific DNS-SD name.
+     *
+     * Multiple solicitations for the same name are coalesced into the same query using a macrotask.
+     */
+    solicit(solicitation: DnssdSolicitor.Solicitation): void;
+
+    /**
+     * Send MDNS queries for a specific DNS-SD name using a standard MDNS transmission schedule.
+     *
+     * The solicitor does not have a notion of "discovery complete", so this function does not return until
+     * {@link DnssdSolicitor.Discovery.abort} signals abort (or the solicitor is closed).
+     *
+     * Multiple simultaneous attempts to complete discovery of the same name will not result in redundant solicitations.
+     *
+     * If fields in {@link discovery} change their value is used for the next solicitation.
+     */
+    discover(discovery: DnssdSolicitor.Discovery): Promise<void>;
+}
+
+/**
+ * Solicit one or more record types for a name.
+ *
+ * "Soliciting" consists of broadcasting a query for a DNS-SD name.  Groups multiple solicitations in the same
+ * macrotask into a single packet.
+ */
+export namespace DnssdSolicitor {
+    /**
+     * Configures solicitation of a single name.
+     */
+    export interface Solicitation {
+        /**
+         * The name to solicit.
+         */
+        name: DnssdName;
+
+        /**
+         * Record types to request.
+         */
+        recordTypes: DnsRecordType[];
+
+        /**
+         * Additional names to include as known answers.
+         */
+        associatedNames?: Iterable<DnssdName>;
+    }
+
+    /**
+     * Configures repeated solicitation.
+     */
+    export interface Discovery extends Solicitation {
+        /**
+         * Terminates discovery.
+         */
+        abort: AbortSignal;
+    }
+
+    /**
+     * Default retry schedule per RFC 6762 (initial delay of 20-120ms. handled separately).
+     */
+    export const DefaultRetries: RetrySchedule.Configuration = {
+        initialInterval: Seconds(1),
+        jitterFactor: 0.2,
+        backoffFactor: 2,
+        maximumInterval: Hours(1),
+    };
+}
+
+/**
+ * Concrete implementation of {@link DnssdSolicitor} that sends DNS-SD queries via multicast.
+ */
+export class QueryMulticaster implements DnssdSolicitor {
+    #names: DnssdNames;
+    #schedule: RetrySchedule;
+    #abort = new Abort();
+    #toSolicit = new Map<DnssdName, DnssdSolicitor.Solicitation>();
+    #discovering = new Map<DnssdName, { abort: Abort; finished: Promise<void>; waiting: Set<{}> }>();
+    #namesReady = new ObservableValue();
+    #workers = new BasicMultiplex();
+
+    constructor(names: DnssdNames, retries?: RetrySchedule.Configuration) {
+        this.#names = names;
+        this.#schedule = new RetrySchedule(
+            names.entropy,
+            RetrySchedule.Configuration(DnssdSolicitor.DefaultRetries, retries),
+        );
+        this.#workers.add(this.#emitSolicitations());
+    }
+
+    solicit(solicitation: DnssdSolicitor.Solicitation) {
+        if (this.#abort.aborted) {
+            return;
+        }
+        const entry = this.#toSolicit.get(solicitation.name);
+        if (entry === undefined) {
+            this.#toSolicit.set(solicitation.name, { ...solicitation });
+        } else {
+            entry.recordTypes = [...new Set([...entry.recordTypes, ...solicitation.recordTypes])];
+            if (solicitation.associatedNames) {
+                if (!entry.associatedNames) {
+                    entry.associatedNames = solicitation.associatedNames;
+                } else {
+                    entry.associatedNames = [...new Set([...entry.associatedNames, ...solicitation.associatedNames])];
+                }
+            }
+        }
+        this.#namesReady.emit(true);
+    }
+
+    async discover(discovery: DnssdSolicitor.Discovery) {
+        let active = this.#discovering.get(discovery.name);
+        if (active) {
+            active.waiting.add(discovery);
+        } else {
+            // This abort is different from the input abort because we only abort when the input aborts if nobody else
+            // is waiting on discovery of the same name
+            const abort = new Abort({ abort: this.#abort });
+            active = {
+                abort,
+                finished: this.#discover(discovery, abort),
+                waiting: new Set([discovery]),
+            };
+            this.#discovering.set(discovery.name, active);
+        }
+
+        try {
+            await Abort.race(discovery.abort, active.finished);
+        } finally {
+            active.waiting.delete(discovery);
+            if (active.waiting.size === 0) {
+                active.abort();
+                this.#discovering.delete(discovery.name);
+            }
+        }
+    }
+
+    async #discover(solicitation: DnssdSolicitor.Solicitation, abort: Abort) {
+        // Wait initially 20 - 120 ms per RFC 6762
+        let timeout = Millis.floor(Millis(20 + 100 * (this.#names.entropy.randomUint32 / Math.pow(2, 32))));
+
+        for (const nextTimeout of this.#schedule) {
+            using delay = new Abort({ abort, timeout });
+
+            await delay;
+            if (abort.aborted) {
+                break;
+            }
+
+            timeout = nextTimeout;
+
+            this.solicit(solicitation);
+        }
+    }
+
+    async close() {
+        this.#abort();
+        await this.#workers;
+    }
+
+    async #emitSolicitations() {
+        while (true) {
+            // Wait for names to solicit
+            await this.#abort.race(this.#namesReady);
+            if (this.#abort.aborted) {
+                return;
+            }
+
+            // Delay using a macrotask so we coalesce names
+            await this.#abort.race(Time.sleep("discovery solicitor delay", 0));
+            if (this.#abort.aborted) {
+                return;
+            }
+
+            // Gather names we will solicit in this iteration
+            const entries = [...this.#toSolicit.values()];
+            this.#namesReady.value = false;
+            this.#toSolicit.clear();
+
+            // Create sets for queries and known answers
+            const queries = Array<DnsQuery>();
+            const answers = Array<DnsRecord>();
+
+            for (const {
+                name: { qname: name, records },
+                recordTypes,
+            } of entries) {
+                for (const recordType of recordTypes) {
+                    queries.push({ name, recordClass: DnsRecordClass.IN, recordType });
+                }
+
+                answers.push(...records);
+            }
+
+            // Send the message
+            try {
+                await this.#abort.race(
+                    this.#names.socket.send({
+                        messageType: DnsMessageType.Query,
+                        queries,
+                        answers,
+                    }),
+                );
+            } catch (e) {
+                logger.error("Unhandled error soliciting DNS-SD names:", e);
+            }
+        }
+    }
+}