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

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/time/TimeUnit.ts

@@ -159,3 +159,8 @@ export const Days = TimeUnit("day", "d", 86_400_000);
  * A zero-length interval.
  */
 export const Instant = Millis(0);
+
+/**
+ * An infinite interval.
+ */
+export const Forever = Millis(Infinity);

package/src/time/Timestamp.ts

@@ -96,7 +96,7 @@ export namespace Timestamp {
     /**
      * Compute the duration between two timestamps.
      */
-    export function delta(from: Timestamp, to: Timestamp) {
+    export function delta(from: Timestamp, to: Timestamp = Time.nowMs) {
         return (to - from) as Duration;
     }
 }

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.
      */

package/src/util/Heap.ts

@@ -0,0 +1,332 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "#MatterError.js";
+import { Abort } from "./Abort.js";
+import { Observable } from "./Observable.js";
+
+/**
+ * A heap, useful as a priority queue.
+ *
+ * Features:
+ *
+ * * Configurable as min-heap or max-heap using comparator
+ *
+ * * O(1) lookup of first item
+ *
+ * * O(log(n)) enqueue and dequeue
+ *
+ * * O(1) deletion of arbitrary position, but will add expense of maintaining index of positions
+ *
+ * * {@link added}, {@link deleted} and {@link firstChanged} events
+ */
+export class Heap<T> {
+    // We encode the heap as an array for efficiency.  See #leftChildOf and #rightChildOf for how to navigate the tree
+    // when encoded this way
+    readonly #buffer = Array<T>();
+
+    readonly #compare: (a: T, b: T) => number;
+    readonly #normalize?: (a: T) => T;
+    #firstChanged?: Observable<[T | undefined]>;
+    #deleted?: Observable<[T]>;
+    #added?: Observable<[T]>;
+    #positions?: Map<T, number>;
+
+    /**
+     * Create new heap.
+     *
+     * @param comparator performs ordering of items in the heap
+     * @param normalizer optionally converts items to normal form on insert
+     */
+    constructor(comparator: (a: T, b: T) => number, normalizer?: (entry: T) => T) {
+        this.#compare = comparator;
+        this.#normalize = normalizer;
+    }
+
+    /**
+     * Return lowest-ranked item.
+     */
+    shift() {
+        if (!this.#buffer?.length) {
+            return undefined;
+        }
+        const result = this.first;
+
+        this.#deleteAt(0);
+
+        return result;
+    }
+
+    /**
+     * The lowest-ranked item.
+     */
+    get first(): T | undefined {
+        return this.#buffer?.[0];
+    }
+
+    /**
+     * The queue length.
+     */
+    get size() {
+        return this.#buffer.length;
+    }
+
+    /**
+     * Is the heap empty?
+     */
+    get isEmpty() {
+        return !!this.#buffer.length;
+    }
+
+    /**
+     * Emits when the head of the queue changes.
+     */
+    get firstChanged() {
+        if (!this.#firstChanged) {
+            this.#firstChanged = new Observable();
+        }
+        return this.#firstChanged;
+    }
+
+    /**
+     * Emits when an item is added to the heap.
+     */
+    get added() {
+        if (!this.#added) {
+            this.#added = new Observable();
+        }
+        return this.#added;
+    }
+
+    /**
+     * Emits when an item is deleted.
+     */
+    get deleted() {
+        if (!this.#deleted) {
+            this.#deleted = new Observable();
+        }
+        return this.#deleted;
+    }
+
+    /**
+     * Add an item.
+     */
+    add(...items: T[]) {
+        for (let item of items) {
+            if (this.#normalize) {
+                item = this.#normalize(item);
+            }
+
+            this.#buffer.push(item);
+            this.#bubbleUp(this.#buffer.length - 1);
+
+            this.#added?.emit(item);
+        }
+    }
+
+    /**
+     * Delete an item.
+     *
+     * The first delete is O(n); subsequent deletes are O(1) but insertions and deletions will have additional cost
+     * associated.
+     */
+    delete(item: T) {
+        if (this.#buffer === undefined) {
+            return false;
+        }
+
+        if (!this.#positions) {
+            this.#positions = new Map();
+            for (let i = 0; i < this.#buffer.length; i++) {
+                this.#positions.set(this.#buffer[i], i);
+            }
+        }
+
+        if (this.#normalize) {
+            item = this.#normalize(item);
+        }
+
+        const pos = this.#positions.get(item);
+        if (pos === undefined) {
+            return false;
+        }
+
+        this.#deleteAt(pos);
+        return true;
+    }
+
+    /**
+     * Remove all entries.
+     */
+    clear() {
+        if (this.#buffer.length) this.#buffer.length = 0;
+    }
+
+    /**
+     * Stream the first value from the heap until aborted.
+     */
+    async *stream(abort?: Abort.Signal) {
+        if (Abort.is(abort)) {
+            return;
+        }
+
+        while (true) {
+            // Yield values currently available
+            while (this.size) {
+                yield this.shift()!;
+
+                if (Abort.is(abort)) {
+                    return;
+                }
+            }
+
+            // Create promise to resolve when a new value is ready
+            let resolve!: () => void;
+            const ready = new Promise<void>(r => (resolve = r));
+
+            // Wait for new value
+            try {
+                this.added.once(resolve);
+
+                await Abort.race(abort, ready);
+
+                if (Abort.is(abort)) {
+                    return;
+                }
+            } finally {
+                this.added.off(resolve);
+            }
+        }
+    }
+
+    /**
+     * Perform internal validation of queue order.
+     */
+    validate() {
+        for (let i = 0; i < this.#buffer.length; i++) {
+            const leftChild = this.#leftChildOf(i);
+            if (leftChild < this.#buffer.length) {
+                if (this.#compare(this.#buffer[i], this.#buffer[leftChild]) > 0) {
+                    throw new InternalError(
+                        `Heap error: buffer #${i} (${this.#buffer[i]}) is greater than left child #${leftChild} (${this.#buffer[leftChild]})`,
+                    );
+                }
+
+                const rightChild = this.#rightChildOf(i);
+                if (rightChild < this.#buffer.length) {
+                    if (this.#compare(this.#buffer[i], this.#buffer[rightChild]) > 0) {
+                        throw new InternalError(
+                            `Heap error: buffer #${i} (${this.#buffer[i]}) is greater than right child #${rightChild} (${this.#buffer[rightChild]})`,
+                        );
+                    }
+
+                    if (this.#compare(this.#buffer[leftChild], this.#buffer[rightChild]) > 0) {
+                        throw new InternalError(
+                            `Heap error: buffer #${leftChild} (${this.#buffer[leftChild]}) is greater than right sibling #${rightChild} (${this.#buffer[rightChild]})`,
+                        );
+                    }
+                }
+            }
+        }
+    }
+
+    #deleteAt(index: number) {
+        if (index >= this.#buffer.length) {
+            return;
+        }
+
+        const item = this.#buffer[index];
+        if (this.#buffer.length === 1) {
+            this.#buffer.length = 0;
+        } else {
+            const lastIndex = this.#buffer.length - 1;
+            this.#buffer[index] = this.#buffer[lastIndex];
+            this.#positions?.set(this.#buffer[index], index);
+            this.#buffer.length = lastIndex;
+            if (index < this.#buffer.length) {
+                if (index) {
+                    index = this.#bubbleUp(index);
+                }
+                this.#sinkDown(index);
+            }
+        }
+
+        this.#positions?.delete(item);
+
+        this.#deleted?.emit(item);
+        if (!index) {
+            this.#firstChanged?.emit(this.first);
+        }
+    }
+
+    #sinkDown(index: number) {
+        while (true) {
+            let moveTo: number | undefined;
+
+            const leftChild = this.#leftChildOf(index);
+
+            if (leftChild < this.#buffer.length) {
+                if (this.#compare(this.#buffer[index], this.#buffer[leftChild]) > 0) {
+                    moveTo = leftChild;
+                }
+
+                const rightChild = this.#rightChildOf(index);
+
+                if (rightChild < this.#buffer.length) {
+                    if (this.#compare(this.#buffer[moveTo ?? index], this.#buffer[rightChild]) > 0) {
+                        moveTo = rightChild;
+                    }
+                }
+            }
+
+            if (moveTo === undefined) {
+                break;
+            }
+
+            this.#swap(index, moveTo);
+            index = moveTo;
+        }
+    }
+
+    #bubbleUp(index: number) {
+        while (index) {
+            const parent = this.#parentOf(index);
+
+            if (this.#compare(this.#buffer[parent], this.#buffer[index]) <= 0) {
+                break;
+            }
+
+            this.#swap(index, parent);
+            index = parent;
+        }
+
+        if (!index) {
+            this.#firstChanged?.emit(this.first);
+        }
+
+        return index;
+    }
+
+    #swap(index1: number, index2: number) {
+        [this.#buffer[index1], this.#buffer[index2]] = [this.#buffer[index2], this.#buffer[index1]];
+        if (this.#positions) {
+            this.#positions.set(this.#buffer[index1], index1);
+            this.#positions.set(this.#buffer[index2], index2);
+        }
+    }
+
+    #leftChildOf(index: number) {
+        return 2 * index + 1;
+    }
+
+    #rightChildOf(index: number) {
+        return 2 * index + 2;
+    }
+
+    #parentOf(index: number) {
+        return Math.floor((index - 1) / 2);
+    }
+}