@matter/general 0.16.1 → 0.16.2-alpha.0-20260114-d3127faee

package/src/net/ServerAddressSet.ts

@@ -0,0 +1,225 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { AddressStatus, ServerAddress } from "./ServerAddress.js";
+
+/**
+ * A set of server addresses ordered by a comparator.
+ */
+export interface ServerAddressSet<T extends ServerAddress> {
+    /**
+     * Add an address.
+     *
+     * If the address alreay exists, returns the existing address to facilitate comparison by value.  If not, returns
+     * the input address.
+     */
+    add(address: T): T;
+
+    /**
+     * Delete an address.
+     */
+    delete(address: T): boolean;
+
+    /**
+     * Replace the stored addresses.
+     */
+    replace(newAddresses: Iterable<T>): void;
+
+    /**
+     * Test for existence of address.
+     */
+    has(address: T): boolean;
+
+    /**
+     * The number of addresses.
+     */
+    size: number;
+
+    /**
+     * Iterate.
+     *
+     * If you replace addresses during iteration only addresses not already produced will be covered by remaining
+     * iterations.
+     */
+    [Symbol.iterator](): Iterator<T>;
+}
+
+/**
+ * Create a new {@link ServerAddressSet}.
+ */
+export function ServerAddressSet<T extends ServerAddress>(
+    initial?: Iterable<T>,
+    comparator = ServerAddressSet.compareDesirability,
+) {
+    let version = 0;
+    let addresses: undefined | Map<string, T>;
+
+    const set: ServerAddressSet<T> = {
+        add(address: T) {
+            version++;
+            const key = ServerAddress.urlFor(address);
+            const existing = addresses?.get(key);
+            if (existing) {
+                return existing;
+            }
+
+            if (!addresses) {
+                addresses = new Map();
+            }
+
+            addresses.set(key, address);
+            return address;
+        },
+
+        delete(address: T) {
+            version++;
+            return addresses?.delete(ServerAddress.urlFor(address)) ?? false;
+        },
+
+        has(address: T) {
+            return addresses?.has(ServerAddress.urlFor(address)) ?? false;
+        },
+
+        replace(newAddresses) {
+            version++;
+            const oldAddresses = addresses;
+            addresses = new Map();
+            for (const address of newAddresses) {
+                const key = ServerAddress.urlFor(address);
+                addresses.set(key, oldAddresses?.get(key) ?? address);
+            }
+        },
+
+        get size() {
+            return addresses?.size ?? 0;
+        },
+
+        *[Symbol.iterator]() {
+            const tried = new Set<string>();
+
+            all: while (true) {
+                const currentVersion = version;
+                const ordered = addresses
+                    ? [...addresses.entries()].map(([, address]) => address).sort(comparator)
+                    : [];
+
+                for (const address of ordered) {
+                    // Skip duplicates or addresses we've tried with previous sets
+                    const key = ServerAddress.urlFor(address);
+                    if (tried.has(key)) {
+                        continue;
+                    }
+
+                    yield address;
+
+                    // Restart iteration if the underlying address set changed
+                    if (currentVersion !== version) {
+                        continue all;
+                    }
+                }
+
+                break;
+            }
+        },
+    };
+
+    if (initial) {
+        set.replace(initial);
+    }
+
+    return set;
+}
+
+export namespace ServerAddressSet {
+    export interface Comparator<T extends ServerAddress = ServerAddress> {
+        (addr1: T, addr2: T): number;
+    }
+
+    /**
+     * Update a list of addresses with health information from another list.
+     */
+    export function copyHealth<T extends ServerAddress>(targetAddresses: Iterable<T>, sourceAddresses: Iterable<T>) {
+        const output = [...targetAddresses];
+
+        nextTarget: for (let i = 0; i < output.length; i++) {
+            const target = output[i];
+            for (const source of sourceAddresses) {
+                if (ServerAddress.isEqual(target, source)) {
+                    if (source.healthyAt !== undefined || source.unhealthyAt !== undefined) {
+                        output[i] = { ...target, healthyAt: source.healthyAt, unhealthyAt: source.unhealthyAt };
+                    }
+                    continue nextTarget;
+                }
+            }
+        }
+
+        return output;
+    }
+
+    /**
+     * Compare the "desirability" of two addresses for communication.
+     */
+    export function compareDesirability(a: ServerAddress, b: ServerAddress) {
+        const value = ServerAddress.selectionPreferenceOf(a) - ServerAddress.selectionPreferenceOf(b);
+
+        if (value) {
+            return value;
+        }
+
+        // Compare health
+        const relativeHealth = compareHealth(a, b);
+        if (relativeHealth) {
+            return relativeHealth;
+        }
+
+        // Compare priority if known for both addresses
+        if (a.priority !== undefined && b.priority !== undefined) {
+            return b.priority - a.priority;
+        }
+
+        return 0;
+    }
+
+    /**
+     * Compare the health of two addresses.
+     *
+     * Returns a negative number if a is healthier, positive if b is healthier and 0 if assessment is neutral.
+     */
+    export function compareHealth(a: AddressStatus, b: AddressStatus) {
+        const ha = ServerAddress.healthOf(a);
+        const hb = ServerAddress.healthOf(b);
+
+        // If a is unhealthy, check b's unhealth
+        if (ha.unhealthyAt) {
+            if (hb.unhealthyAt) {
+                // Prefer smaller "unhealthy at" value
+                return ha.unhealthyAt - hb.unhealthyAt;
+            }
+
+            // Prefer b as it is healthy or unused
+            return 1;
+        }
+
+        // If b is unhealthy and a is not; prefer b
+        if (hb.unhealthyAt) {
+            return -1;
+        }
+
+        // If a is known healthy, check b's health
+        if (ha.healthyAt) {
+            if (hb.healthyAt) {
+                // Prefer greater health value
+                return hb.healthyAt - ha.healthyAt;
+            }
+
+            // Prefer a as b has not been used
+            return -1;
+        }
+
+        // No preference
+        return 0;
+    }
+}

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

@@ -0,0 +1,203 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    DnsCodec,
+    DnsMessage,
+    DnsMessagePartiallyPreEncoded,
+    DnsMessageType,
+    DnsMessageTypeFlag,
+    MAX_MDNS_MESSAGE_SIZE,
+} from "#codec/DnsCodec.js";
+import { Diagnostic } from "#log/Diagnostic.js";
+import { Logger } from "#log/Logger.js";
+import { MatterAggregateError } from "#MatterError.js";
+import { Network } from "#net/Network.js";
+import { UdpMulticastServer } from "#net/udp/UdpMulticastServer.js";
+import { Bytes } from "#util/Bytes.js";
+import { Lifetime } from "#util/Lifetime.js";
+import { AsyncObservable, BasicObservable } from "#util/Observable.js";
+import { MaybePromise } from "#util/Promises.js";
+
+const logger = Logger.get("MdnsListener");
+
+/**
+ * Manages the UDP socket for other components that implement MDNS logic.
+ */
+export class MdnsSocket {
+    #socket: UdpMulticastServer;
+    #handlers?: Set<PromiseLike<void>>;
+    #isClosed = false;
+    #receipt: AsyncObservable<[message: MdnsSocket.Message]> = new BasicObservable(
+        error => logger.error("Unhandled error in MDNS listener", error),
+        true,
+    );
+
+    static async create(
+        network: Network,
+        options?: { enableIpv4?: boolean; netInterface?: string; lifetime?: Lifetime.Owner },
+    ) {
+        const { enableIpv4 = true, netInterface, lifetime } = options ?? {};
+        const socket = new MdnsSocket(
+            await UdpMulticastServer.create({
+                lifetime,
+                network,
+                netInterface,
+                broadcastAddressIpv4: enableIpv4 ? MdnsSocket.BROADCAST_IPV4 : undefined,
+                broadcastAddressIpv6: MdnsSocket.BROADCAST_IPV6,
+                listeningPort: MdnsSocket.BROADCAST_PORT,
+            }),
+        );
+        return socket;
+    }
+
+    constructor(socket: UdpMulticastServer) {
+        this.#socket = socket;
+        socket.onMessage(this.#handleMessage.bind(this));
+    }
+
+    get network() {
+        return this.#socket.network;
+    }
+
+    get supportsIpv4() {
+        return this.#socket.supportsIpv4;
+    }
+
+    get netInterface() {
+        return this.#socket.netInterface;
+    }
+
+    get receipt() {
+        return this.#receipt;
+    }
+
+    async send(message: Partial<DnsMessage> & { messageType: DnsMessageType }, intf?: string, unicastDest?: string) {
+        const { messageType } = message;
+        // When we send Queries that are too long they need to have the Truncated flag set
+        const truncatedMessageType = DnsMessageType.isQuery(messageType)
+            ? messageType | DnsMessageTypeFlag.TC
+            : messageType;
+
+        const chunk: DnsMessagePartiallyPreEncoded = {
+            transactionId: 0,
+            queries: [],
+            authorities: [],
+
+            ...message,
+
+            answers: [],
+            additionalRecords: [],
+        };
+
+        // Note - for size calculations we assume queries are relatively small.  We only split answers across messages
+        let encodedChunkWithoutAnswers = DnsCodec.encode(chunk);
+        let chunkSize = encodedChunkWithoutAnswers.byteLength;
+
+        // Add answers, splitting message as necessary
+        for (const answer of message.answers ?? []) {
+            const answerEncoded = DnsCodec.encodeRecord(answer);
+
+            if (chunkSize + answerEncoded.byteLength > MAX_MDNS_MESSAGE_SIZE) {
+                if (chunk.answers.length === 0) {
+                    // The first answer is already too big, log at least a warning
+                    logger.warn(
+                        `MDNS message with ${Diagnostic.json(
+                            chunk.queries,
+                        )} is too big to fit into a single MDNS message. Send anyway, but please report!`,
+                    );
+                }
+
+                // New answer does not fit anymore, send out the message
+                // When sending a query, we set the Truncated flag to indicate more answers are available
+                await this.#send(
+                    {
+                        ...chunk,
+                        messageType: truncatedMessageType,
+                    },
+                    intf,
+                    unicastDest,
+                );
+
+                // Reset the message, length counter and included answers to count for next message
+                if (chunk.queries.length) {
+                    chunk.queries.length = 0;
+                    encodedChunkWithoutAnswers = DnsCodec.encode(chunk);
+                }
+                chunk.answers.length = 0;
+                chunkSize = encodedChunkWithoutAnswers.byteLength + answerEncoded.byteLength;
+            } else {
+                chunkSize += answerEncoded.byteLength;
+            }
+
+            chunk.answers.push(answerEncoded);
+        }
+
+        // Add "additional records"...  We include these but only if they fit
+        const additionalRecords = message.additionalRecords ?? [];
+        for (const additionalRecord of additionalRecords) {
+            const additionalRecordEncoded = DnsCodec.encodeRecord(additionalRecord);
+            chunkSize += additionalRecordEncoded.byteLength;
+            if (chunkSize > MAX_MDNS_MESSAGE_SIZE) {
+                break;
+            }
+            chunk.additionalRecords.push(additionalRecordEncoded);
+        }
+
+        await this.#send(chunk, intf, unicastDest);
+    }
+
+    async #send(message: DnsMessagePartiallyPreEncoded, intf?: string, unicastDest?: string) {
+        await this.#socket.send(DnsCodec.encode(message), intf, unicastDest);
+    }
+
+    async close() {
+        this.#isClosed = true;
+        await this.#socket.close();
+        if (this.#handlers) {
+            await MatterAggregateError.allSettled(this.#handlers);
+        }
+    }
+
+    #handleMessage(bytes: Bytes, sourceIp: string, sourceIntf: string) {
+        // Ignore if closed
+        if (this.#isClosed) {
+            return;
+        }
+
+        // Parse
+        const parsed = DnsCodec.decode(bytes);
+
+        // Skip unparseable
+        if (parsed === undefined) {
+            return;
+        }
+
+        let promise = this.#receipt.emit({
+            ...parsed,
+            sourceIp,
+            sourceIntf,
+        }) as MaybePromise;
+
+        if (MaybePromise.is(promise)) {
+            if (this.#handlers === undefined) {
+                this.#handlers = new Set();
+            }
+            promise = Promise.resolve(promise).finally(() => this.#handlers?.delete(promise as PromiseLike<void>));
+        }
+    }
+}
+
+export namespace MdnsSocket {
+    export interface Message extends DnsMessage {
+        sourceIp: string;
+        sourceIntf: string;
+    }
+
+    export const BROADCAST_IPV4 = "224.0.0.251";
+    export const BROADCAST_IPV6 = "ff02::fb";
+    export const BROADCAST_PORT = 5353;
+}

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

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./MdnsSocket.js";

package/src/net/index.ts

@@ -7,10 +7,12 @@
 export * from "./AppAddress.js";
 export * from "./Channel.js";
 export * from "./ConnectionlessTransport.js";
+export * from "./dns-sd/index.js";
 export * from "./http/index.js";
 export * from "./mock/index.js";
 export * from "./mqtt/index.js";
 export * from "./Network.js";
 export * from "./RetrySchedule.js";
 export * from "./ServerAddress.js";
+export * from "./ServerAddressSet.js";
 export * from "./udp/index.js";

package/src/util/Abort.ts

@@ -96,6 +96,13 @@ export class Abort extends Callable<[reason?: Error]> implements AbortController
         return Abort.race(this, ...promises);
     }
 
+    /**
+     * Race with throw on abort.
+     */
+    async attempt<T>(...promises: Array<T | PromiseLike<T>>) {
+        return Abort.attempt(this, ...promises);
+    }
+
     /**
      * Free resources.
      *
@@ -115,6 +122,12 @@ export class Abort extends Callable<[reason?: Error]> implements AbortController
         this.close();
     }
 
+    if(condition?: unknown, reason?: Error) {
+        if (condition) {
+            this.abort(reason);
+        }
+    }
+
     get aborted() {
         return this.signal.aborted;
     }
@@ -262,6 +275,18 @@ export namespace Abort {
         return SafePromise.race(promises);
     }
 
+    /**
+     * Race with throw on abort.
+     */
+    export async function attempt<T>(signal: Signal | undefined, ...promises: Array<T | PromiseLike<T>>) {
+        if (signal && "signal" in signal) {
+            signal = signal.signal;
+        }
+        const result = await race(signal, ...promises);
+        signal?.throwIfAborted();
+        return result as Awaited<T>;
+    }
+
     /**
      * Perform abortable sleep.
      */