@matter/general 0.16.8-alpha.0-20260125-38e62bc3e → 0.16.8-alpha.0-20260127-de48449ad

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

@@ -0,0 +1,346 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { DnsRecordType, SrvRecordValue } from "#codec/DnsCodec.js";
+import { Diagnostic } from "#log/Diagnostic.js";
+import { AddressLifespan, ServerAddressUdp } from "#net/ServerAddress.js";
+import { ServerAddressSet } from "#net/ServerAddressSet.js";
+import { Duration } from "#time/Duration.js";
+import { Time } from "#time/Time.js";
+import { Abort } from "#util/Abort.js";
+import { AsyncObservable, AsyncObservableValue, ObserverGroup } from "#util/Observable.js";
+import { DnssdName } from "./DnssdName.js";
+import { DnssdNames } from "./DnssdNames.js";
+import { IpServiceStatus } from "./IpServiceStatus.js";
+
+/**
+ * A service addressable by IP that updates as {@link DnssdNames} change.
+ */
+export class IpService {
+    readonly #name: DnssdName;
+    readonly #via: string;
+    readonly #names: DnssdNames;
+    readonly #observers = new ObserverGroup(this);
+    readonly #services = new Map<string, Service>();
+    readonly #changed = new AsyncObservable<[]>();
+    readonly #addresses = ServerAddressSet<ServerAddressUdp>();
+    #status = new IpServiceStatus(this);
+    #notified?: Promise<void>;
+
+    constructor(name: string, via: string, names: DnssdNames) {
+        this.#name = names.get(name);
+        this.#names = names;
+        this.#via = Diagnostic.via(via);
+        this.#observers.on(this.#name, this.#onServiceChanged);
+
+        for (const record of this.#name.records) {
+            const service = serviceOf(record);
+            if (!service) {
+                continue;
+            }
+
+            this.#updateService(record.ttl, service);
+        }
+    }
+
+    /**
+     * The DNS-SD name.
+     */
+    get name() {
+        return this.#name;
+    }
+
+    /**
+     * Other DNS-SD names.
+     */
+    get names() {
+        return this.#names;
+    }
+
+    /**
+     * Identifier used for logging.
+     */
+    get via() {
+        return this.#via;
+    }
+
+    /**
+     * Status details of the service.
+     */
+    get status() {
+        return this.#status;
+    }
+
+    /**
+     * Release resources.
+     */
+    async close() {
+        this.#observers.close();
+        await this.#status.close();
+        if (this.#notified) {
+            await this.#notified;
+        }
+    }
+
+    /**
+     * Known addresses.
+     */
+    get addresses() {
+        return this.#addresses;
+    }
+
+    /**
+     * Values from TXT records.
+     */
+    get parameters() {
+        return this.#name.parameters;
+    }
+
+    /**
+     * Emits when the service changes.
+     */
+    get changed() {
+        return this.#changed;
+    }
+
+    map<T>(fn: (addr: ServerAddressUdp) => T): T[] {
+        return [...this.addresses].map(fn);
+    }
+
+    /**
+     * Stream address updates, starting with initial set of addresses.
+     *
+     * Outputs addresses in priority order so the stream may be used directly for establishing new connections.
+     *
+     * If no addresses are present, triggers discovery using standard MDNS backoff schedule.
+     */
+    async *addressChanges({
+        abort,
+        order = ServerAddressSet.compareDesirability,
+    }: {
+        abort?: AbortSignal;
+        order?: ServerAddressSet.Comparator;
+        ipv4?: boolean;
+    } = {}): AsyncGenerator<{ kind: "add" | "delete"; address: ServerAddressUdp }> {
+        let knownAddresses = new Set<ServerAddressUdp>();
+
+        // Implement change detection
+        const dirty = new AsyncObservableValue<[isDirty: boolean]>();
+        using _changed = this.changed.use(() => dirty.emit(true));
+
+        loop: while (true) {
+            // Collect and order addresses; do not use return from resolve() to avoid race condition with dirty
+            // observation
+            dirty.emit(false);
+            const addresses = ServerAddressSet(this.addresses, order);
+
+            // Enqueue new addresses
+            let changes = new Array<IpService.AddressChange>();
+            const oldKnownAddresses = knownAddresses;
+            knownAddresses = new Set();
+            for (const address of addresses) {
+                knownAddresses.add(address);
+
+                if (oldKnownAddresses.has(address)) {
+                    oldKnownAddresses.delete(address);
+                    continue;
+                }
+
+                changes.push({ kind: "add", address });
+            }
+
+            // Enqueue deleted addresses
+            if (oldKnownAddresses.size) {
+                const deletedAddresses = [...oldKnownAddresses.values()];
+                const deletes = deletedAddresses.map(address => ({ kind: "delete", address }) as const);
+                changes = [...deletes, ...changes];
+            }
+
+            // Output
+            for (const change of changes) {
+                yield change;
+
+                // Abort if aborted
+                if (Abort.is(abort)) {
+                    return;
+                }
+
+                // Restart if changed
+                if (dirty.value) {
+                    continue loop;
+                }
+            }
+
+            // All addresses emitted; wait for change
+            await Abort.race(abort, dirty);
+            if (Abort.is(abort)) {
+                return;
+            }
+        }
+    }
+
+    #onServiceChanged = async ({ updated, deleted }: DnssdName.Changes) => {
+        if (updated) {
+            for (const record of updated) {
+                const service = serviceOf(record);
+                if (service) {
+                    this.#updateService(record.ttl, service);
+                }
+            }
+        }
+
+        if (deleted) {
+            for (const record of deleted) {
+                const service = serviceOf(record);
+                if (service) {
+                    this.#deleteService(service);
+                }
+            }
+        }
+    };
+
+    #updateService(ttl: Duration, { target, port, priority, weight }: SrvRecordValue) {
+        const key = hostKeyOf(target, port);
+        let service = this.#services.get(key);
+
+        if (service) {
+            service.discoveredAt = Time.nowMs;
+            service.ttl = ttl;
+            service.port = port;
+            service.priority = priority;
+            service.weight = weight;
+            return;
+        }
+
+        service = {
+            name: this.#names.get(target),
+            discoveredAt: Time.nowMs,
+            ttl,
+            port,
+            priority,
+            weight,
+            onChange: changes => this.#onAddressChanged(service!, changes),
+        };
+
+        this.#observers.on(service.name, service.onChange);
+
+        this.#onAddressChanged(service, { name: service.name, updated: [...service.name.records] });
+
+        this.#services.set(key, service);
+    }
+
+    #deleteService({ target, port }: SrvRecordValue) {
+        const key = hostKeyOf(target, port);
+        const service = this.#services.get(key);
+
+        if (!service) {
+            return;
+        }
+
+        this.#services.delete(key);
+
+        this.#observers.off(service.name, service.onChange);
+
+        this.#onAddressChanged(service, { name: service.name, deleted: [...service.name.records] });
+
+        return;
+    }
+
+    #onAddressChanged = (service: Service, { updated, deleted }: DnssdName.Changes) => {
+        if (updated) {
+            for (const record of updated) {
+                const addr = addressOf(record);
+                if (addr) {
+                    this.#updateAddress(service, addr);
+                }
+            }
+        }
+        if (deleted) {
+            for (const record of deleted) {
+                const addr = addressOf(record);
+                if (addr) {
+                    this.#deleteAddress(service, addr);
+                }
+            }
+        }
+    };
+
+    #updateAddress(service: Service, ip: string) {
+        const address: ServerAddressUdp = { type: "udp", ip, port: service.port };
+
+        if (this.#addresses.has(address)) {
+            return;
+        }
+
+        this.#addresses.add(address);
+
+        // Set status to reachable any time we add a new address
+        this.#status.isReachable = true;
+
+        this.#notify();
+    }
+
+    #deleteAddress(service: Service, ip: string) {
+        const address: ServerAddressUdp = { type: "udp", ip, port: service.port };
+
+        if (!this.#addresses.has(address)) {
+            return;
+        }
+
+        this.#addresses.delete(address);
+
+        this.#notify();
+    }
+
+    #notify = () => {
+        if (this.#notified) {
+            return;
+        }
+
+        // We notify asynchronously so changes coalesce
+        this.#notified = this.#emitNotification();
+    };
+
+    async #emitNotification() {
+        await Time.sleep("discovery service coalescence", 0);
+        this.#notified = undefined;
+        await this.changed.emit();
+    }
+}
+
+export namespace IpService {
+    export interface AddressChange {
+        kind: "add" | "delete";
+        address: ServerAddressUdp;
+    }
+}
+
+interface Service extends AddressLifespan {
+    name: DnssdName;
+    priority: number;
+    weight: number;
+    port: number;
+    onChange(changes: DnssdName.Changes): void;
+}
+
+function serviceOf(record: DnssdName.Record) {
+    if (record.recordType !== DnsRecordType.SRV) {
+        return;
+    }
+
+    return record.value;
+}
+
+function hostKeyOf(name: string, port: number) {
+    return `${name}:${port}`;
+}
+
+function addressOf(record: DnssdName.Record) {
+    if (record.recordType !== DnsRecordType.A && record.recordType !== DnsRecordType.AAAA) {
+        return;
+    }
+    return record.value;
+}

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

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { DnsRecordType } from "#codec/DnsCodec.js";
+import { ServerAddressSet } from "#net/ServerAddressSet.js";
+import { Abort } from "#util/Abort.js";
+import { isIPv4, isIPv6 } from "#util/Ip.js";
+import { BasicMultiplex } from "#util/Multiplex.js";
+import { ObserverGroup } from "#util/Observable.js";
+import { BasicSet } from "#util/Set.js";
+import { DnssdName } from "./DnssdName.js";
+import type { DnssdSolicitor } from "./DnssdSolicitor.js";
+import { IpService } from "./IpService.js";
+
+/**
+ * Discovers new IP addresses for an {@link IpService}.
+ *
+ * This primarily involves sending queries for SRV records using {@link DnssdSolicitor#discover}.  We also query for
+ * A and AAAA records for any SRV target hostnames for which we do not know IP addresses.
+ *
+ * Runs until aborted or we discover a new IP address (we ignore existing addresses).
+ */
+export async function IpServiceResolution(service: IpService, abort: AbortSignal, ipv4 = true) {
+    using localAbort = new Abort({ abort });
+    await using workers = new BasicMultiplex();
+    using observers = new ObserverGroup();
+
+    // Target names for SRV records.  We report this to the solicitor as associated records and initiate discovery on
+    // any name that has no IP records
+    const hosts = new BasicSet<DnssdName>();
+
+    // We record an abort function for any hostname (SRV target) we are discovering because it has no known IPs
+    let hostResolvers: undefined | Map<DnssdName, Abort>;
+
+    // Resolve hosts with no IPs
+    observers.on(hosts.added, name => {
+        // Skip if host has IP records
+        if (
+            [...name.records].find(
+                record => record.recordType === DnsRecordType.AAAA || record.recordType === DnsRecordType.A,
+            )
+        ) {
+            return;
+        }
+
+        // Begin resolving
+        if (!hostResolvers) {
+            hostResolvers = new Map();
+        }
+        const hostAbort = new Abort({ abort: localAbort });
+        hostResolvers.set(name, hostAbort);
+        workers.add(
+            service.names.solicitor
+                .discover({
+                    name,
+                    recordTypes: ipv4 ? [DnsRecordType.A, DnsRecordType.AAAA] : [DnsRecordType.AAAA],
+                    abort: hostAbort,
+                })
+                .finally(hostAbort.close.bind(hostAbort)),
+        );
+    });
+
+    // Stop resolving hosts when deleted
+    observers.on(hosts.deleted, name => {
+        const abortHost = hostResolvers?.get(name);
+        if (!abortHost) {
+            return;
+        }
+
+        hostResolvers?.delete(name);
+        abortHost();
+    });
+
+    // Resolve any initial hosts without records
+    for (const record of service.name.records) {
+        if (record.recordType !== DnsRecordType.SRV) {
+            continue;
+        }
+
+        hosts.add(service.names.get(record.name));
+    }
+
+    // Wire the service to a.) stop discovery when we discover a new address, and b.) update known hosts
+    const existingAddresses = ServerAddressSet(service.addresses);
+    observers.on(service.changed, () => {
+        // Detect new address which means discovery is complete
+        for (const address of service.addresses) {
+            if (!ipv4 && isIPv4(address.ip)) {
+                // Ignore ipv4 if ipv4 is unused
+                continue;
+            }
+
+            if (!existingAddresses.has(address) && (ipv4 || isIPv6(address.ip))) {
+                // Address discovered; we're done
+                localAbort();
+            }
+        }
+
+        // Add/remove hosts as necessary
+        const srvs = [...service.name.records].filter(record => record.recordType === DnsRecordType.SRV);
+        const newHostnames = new Set(srvs.map(record => record.value.target));
+        for (const hostname of newHostnames) {
+            // Host is newly added; add to associated names
+            hosts.add(service.names.get(hostname));
+        }
+        for (const name of hosts) {
+            if (newHostnames.has(name.qname)) {
+                continue;
+            }
+
+            // Host is no longer targeted; remove from associated names
+            hosts.delete(name);
+        }
+    });
+
+    // Begin discovering SVC records
+    workers.add(
+        service.names.solicitor.discover({
+            abort: localAbort,
+            name: service.name,
+            recordTypes: [DnsRecordType.SRV],
+
+            get associatedNames() {
+                return hosts;
+            },
+        }),
+    );
+
+    // Run until aborted, either because we discovered a new IP or input abort was signaled
+    await localAbort;
+}

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

@@ -0,0 +1,212 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Diagnostic } from "#log/Diagnostic.js";
+import { Logger } from "#log/Logger.js";
+import { AbortedError } from "#MatterError.js";
+import { ServerAddress } from "#net/ServerAddress.js";
+import { Time } from "#time/Time.js";
+import { Timestamp } from "#time/Timestamp.js";
+import { Abort } from "#util/Abort.js";
+import { asError } from "#util/Error.js";
+import { BasicSet } from "#util/Set.js";
+import type { IpService } from "./IpService.js";
+import { IpServiceResolution } from "./IpServiceResolution.js";
+
+const logger = Logger.get("IpServiceStatus");
+
+/**
+ * Tracks status of an {@link IpService}, logs state changes and manages service discovery.
+ */
+export class IpServiceStatus {
+    #service: IpService;
+    #isReachable = false;
+    #connecting = new BasicSet<PromiseLike<boolean>>();
+    #resolveAbort?: Abort;
+    #resolving?: Promise<void>;
+    #connectionInitiatedAt?: Timestamp;
+    #lastReceiptAt?: Timestamp;
+
+    constructor(service: IpService) {
+        this.#service = service;
+    }
+
+    async close() {
+        this.#stopResolving();
+        if (this.#resolving) {
+            await this.#resolving;
+        }
+    }
+
+    /**
+     * Is the service actively connecting?
+     *
+     * This is true so long as a promise passed to {@link connecting} is unresolved.
+     */
+    get isConnecting() {
+        return this.#connecting.size > 0;
+    }
+
+    /**
+     * Is the service currently reachable?
+     *
+     * This value is writable.  If you set {@link isReachable} to false and {@link isConnecting} is true, the service
+     * enters discovery mode and begins active solicitation so long as neither condition changes.
+     *
+     * The service sets {@link isReachable} to true automatically if:
+     *
+     * - It discovers a new (previously unknown) address, or
+     *
+     * - The input promise to {@link connecting} resolves to true
+     *
+     * The service sets {@link isReachable} to false automatically if the input promise to {@link connecting} resolves
+     * to false.
+     */
+    get isReachable() {
+        return this.#isReachable;
+    }
+
+    /**
+     * Are we actively performing MDNS discovery for the service?
+     */
+    get isResolving() {
+        return this.#resolving !== undefined;
+    }
+
+    set isReachable(isReachable: boolean) {
+        if (this.#isReachable === isReachable) {
+            return;
+        }
+
+        this.#isReachable = isReachable;
+
+        if (isReachable) {
+            this.#maybeStopResolving();
+        } else {
+            this.#maybeStartResolving();
+        }
+    }
+
+    get lastReceiptAt(): Timestamp | undefined {
+        return this.#lastReceiptAt;
+    }
+
+    set lastReceiptAt(time: Timestamp) {
+        this.#lastReceiptAt = time;
+    }
+
+    get connectionInitiatedAt() {
+        return this.#connectionInitiatedAt;
+    }
+
+    /**
+     * Register a new connection attempt.
+     *
+     * If {@link result} resolves as true the service is marked as reachable.  If {@link result} resolves as false
+     * reachability is not modified.
+     *
+     * If {@link result} throws an error other than {@link AbortedError}, the service is marked as unreachable and if
+     * the error logged.
+     *
+     * {@link isConnecting} will be true until {@link result} resolves.
+     */
+    connecting(result: PromiseLike<boolean>) {
+        logger.debug(this.#service.via, "Connecting");
+
+        result.then(
+            returned => {
+                this.#connecting.delete(result);
+
+                if (!this.#connecting.size) {
+                    this.#connectionInitiatedAt = undefined;
+                }
+
+                if (returned) {
+                    this.isReachable = true;
+
+                    logger.info(this.#service.via, "Connected");
+                } else {
+                    logger.debug(this.#service.via, "Connect attempt aborted");
+                }
+
+                this.#maybeStopResolving();
+            },
+
+            error => {
+                this.#connecting.delete(result);
+
+                if (!(error instanceof AbortedError)) {
+                    return;
+                }
+
+                logger.error(this.#service.via, "Connection error:", asError(error));
+
+                this.#isReachable = false;
+
+                this.#maybeStartResolving();
+            },
+        );
+
+        this.#connectionInitiatedAt = Time.nowMs;
+        this.#connecting.add(result);
+
+        this.#maybeStartResolving();
+    }
+
+    #maybeStartResolving() {
+        if (this.#isReachable || !this.isConnecting || this.#resolveAbort) {
+            return;
+        }
+
+        const numAddresses = this.#service.addresses.size;
+
+        let why;
+
+        switch (numAddresses) {
+            case 0:
+                why = "need address";
+                break;
+
+            case 1:
+                why = "address is unreachable";
+                break;
+
+            default:
+                why = `${numAddresses} known addresses are unreachable`;
+        }
+
+        logger.info(this.#service.via, "Resolving", Diagnostic.weak(`(${why})`));
+
+        this.#resolveAbort = new Abort();
+        this.#resolving = IpServiceResolution(this.#service, this.#resolveAbort).finally(() => {
+            if (this.#resolveAbort?.aborted === false) {
+                const addresses = [...this.#service.addresses].map(ServerAddress.urlFor);
+                logger.debug(this.#service.via, `Resolved as ${addresses.join(", ")}`);
+            }
+            this.#resolveAbort?.close();
+            this.#resolveAbort = undefined;
+            this.#resolving = undefined;
+        });
+    }
+
+    #maybeStopResolving() {
+        if (!this.#isReachable || this.isConnecting || !this.#resolveAbort) {
+            return;
+        }
+
+        this.#stopResolving();
+    }
+
+    #stopResolving() {
+        if (!this.#resolveAbort) {
+            return;
+        }
+
+        this.#resolveAbort();
+
+        logger.debug(this.#service.via, "Stopped resolving");
+    }
+}

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

@@ -4,4 +4,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+export * from "./DnssdName.js";
+export * from "./DnssdNames.js";
+export * from "./DnssdSolicitor.js";
+export * from "./IpService.js";
+export * from "./IpServiceResolution.js";
+export * from "./IpServiceStatus.js";
 export * from "./MdnsSocket.js";