@matter/general 0.16.0-alpha.0-20251003-dc6d5523d → 0.16.0-alpha.0-20251004-92135c7df

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@matter/general",
-    "version": "0.16.0-alpha.0-20251003-dc6d5523d",
+    "version": "0.16.0-alpha.0-20251004-92135c7df",
     "description": "Non-Matter support for Matter.js",
     "keywords": [
         "iot",
@@ -36,7 +36,7 @@
         "@noble/curves": "^2.0.1"
     },
     "devDependencies": {
-        "@matter/testing": "0.16.0-alpha.0-20251003-dc6d5523d"
+        "@matter/testing": "0.16.0-alpha.0-20251004-92135c7df"
     },
     "files": [
         "dist/**/*",

package/src/codec/DnsCodec.ts

@@ -122,11 +122,50 @@ export type DnsMessagePartiallyPreEncoded = Omit<DnsMessage, "answers" | "additi
     additionalRecords: (DnsRecord<any> | Bytes)[];
 };
 
+/** Bit flags to use to determine separate flags in the DnsMessageType field */
+export enum DnsMessageTypeFlag {
+    /** Indicates if the message is a query (0) or a reply (1). */
+    QR = 0x8000,
+
+    /** The type can be QUERY (standard query, 0), IQUERY (inverse query, 1), or STATUS (server status request, 2). */
+    OPCODE = 0x7800,
+
+    /** Authoritative Answer, in a response, indicates if the DNS server is authoritative for the queried hostname. */
+    AA = 0x0400,
+
+    /** TrunCation, indicates that this message was truncated due to excessive length. */
+    TC = 0x0200,
+
+    /** Recursion Desired, indicates if the client means a recursive query. */
+    RD = 0x0100,
+
+    /** Recursion Available, in a response, indicates if the replying DNS server supports recursion. */
+    RA = 0x0080,
+
+    /** Authentic Data, in a response, indicates if the replying DNS server verified the data. */
+    AD = 0x0020,
+
+    /** Checking Disabled, in a query, indicates that non-verified data is acceptable in a response. */
+    CD = 0x0010,
+
+    /** Response code, can be NOERROR (0), FORMERR (1, Format error), SERVFAIL (2), NXDOMAIN (3, Nonexistent domain), etc. */
+    RCODE = 0x000f,
+}
+
+/** Convenient Message types we use when sending mDNS messages */
 export enum DnsMessageType {
-    Query = 0x0000,
-    TruncatedQuery = 0x0200,
-    Response = 0x8400, // Authoritative Answer
-    TruncatedResponse = 0x8600,
+    Query = 0, // No bit set
+    Response = DnsMessageTypeFlag.QR | DnsMessageTypeFlag.AA, // Authoritative Answer 0x8400
+}
+
+export namespace DnsMessageType {
+    export function isQuery(type: number) {
+        return (type & DnsMessageTypeFlag.QR) === 0;
+    }
+
+    export function isResponse(type: number) {
+        return (type & DnsMessageTypeFlag.QR) !== 0;
+    }
 }
 
 export enum DnsRecordType {
@@ -288,7 +327,7 @@ export class DnsCodec {
         additionalRecords = [],
     }: Partial<DnsMessagePartiallyPreEncoded>): Bytes {
         if (messageType === undefined) throw new InternalError("Message type must be specified!");
-        if (queries.length > 0 && messageType !== DnsMessageType.Query && messageType !== DnsMessageType.TruncatedQuery)
+        if (queries.length > 0 && !DnsMessageType.isQuery(messageType))
             throw new InternalError("Queries can only be included in query messages!");
         if (authorities.length > 0) throw new NotImplementedError("Authority answers are not supported yet!");
 

package/src/net/mock/MockRouter.ts

@@ -14,10 +14,17 @@ export interface MockRouter extends MockRouter.Route {
     delete(route: MockRouter.Route): void;
 }
 
-export function MockRouter() {
+export function MockRouter(manipulator?: MockRouter.PacketManipulator): MockRouter {
     const routes = new Set<MockRouter.Route>();
 
     const router = function router(packet: MockRouter.Packet) {
+        if (manipulator) {
+            const manipulatedPacket = manipulator(packet);
+            if (manipulatedPacket === null) {
+                return;
+            }
+            packet = manipulatedPacket;
+        }
         for (const route of routes) {
             try {
                 route(packet);
@@ -46,4 +53,6 @@ export namespace MockRouter {
     export interface Route {
         (packet: Packet): void;
     }
+
+    export type PacketManipulator = (packet: Packet) => Packet | null;
 }

package/src/net/mock/MockUdpChannel.ts

@@ -13,13 +13,18 @@ import { MockRouter } from "./MockRouter.js";
 
 export class MockUdpChannel implements UdpChannel {
     readonly #host: MockNetwork;
-    readonly #router = MockRouter();
+    readonly #router: MockRouter;
     readonly #sendFrom: string;
     readonly #receiveFrom: Set<string>;
     readonly #listeningPort: number;
     readonly maxPayloadSize = MAX_UDP_MESSAGE_SIZE;
 
-    constructor(network: MockNetwork, { listeningAddress, listeningPort, netInterface, type }: UdpChannelOptions) {
+    constructor(
+        network: MockNetwork,
+        { listeningAddress, listeningPort, netInterface, type }: UdpChannelOptions,
+        packetManipulator?: MockRouter.PacketManipulator,
+    ) {
+        this.#router = MockRouter(packetManipulator);
         const { ipV4, ipV6 } = network.getIpMac(netInterface ?? "fake0");
         let addresses = type === "udp4" ? ipV4 : ipV6;
 

package/src/util/Abort.ts

@@ -0,0 +1,93 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Utilities for implementing abort logic.
+ */
+export namespace Abort {
+    /**
+     * An entity that may be used to signal abort of an operation.
+     */
+    export type Signal = AbortController | AbortSignal;
+
+    /**
+     * An abort controller that can be closed.
+     */
+    export interface DisposableController extends AbortController {
+        [Symbol.dispose](): void;
+    }
+
+    /**
+     * Determine whether a {@link Signal} is aborted.
+     */
+    export function is(signal: Signal | undefined) {
+        if (!signal) {
+            return;
+        }
+
+        if ("signal" in signal) {
+            signal = signal.signal;
+        }
+
+        return signal.aborted;
+    }
+
+    /**
+     * Race one or more promises with an optional abort signal.
+     *
+     * If the abort signal is present and signals abort, the race will end and return undefined.  It will not throw the
+     * abort reason.
+     */
+    export function race<T>(
+        signal: Signal | undefined,
+        ...promises: Array<T | PromiseLike<T>>
+    ): Promise<Awaited<T> | void> {
+        if (signal) {
+            if ("signal" in signal) {
+                signal = signal.signal;
+            }
+
+            let off: () => void;
+            const aborted = new Promise<void>(resolve => {
+                const onabort = () => resolve();
+                (signal as AbortSignal).addEventListener("abort", onabort);
+                off = () => (signal as AbortSignal).removeEventListener("abort", onabort);
+            });
+
+            return Promise.race([aborted, ...promises]).finally(off!);
+        }
+
+        if (promises.length === 1) {
+            return Promise.resolve(promises[0]);
+        }
+
+        return Promise.race(promises);
+    }
+
+    /**
+     * Create independently abortable subtask with a new {@link AbortController} that is aborted if another controller
+     * aborts.
+     *
+     * Closing the returned controller unregisters with the input controller.  It does not perform an abort.
+     */
+    export function subtask(signal: Signal | undefined): DisposableController {
+        if (signal && "signal" in signal) {
+            signal = signal.signal;
+        }
+
+        const controller = new AbortController() as DisposableController;
+
+        if (signal) {
+            const outerHandler = () => controller.abort();
+            signal.addEventListener("abort", outerHandler);
+            controller[Symbol.dispose] = () => signal.removeEventListener("abort", outerHandler);
+        } else {
+            controller[Symbol.dispose] = () => {};
+        }
+
+        return controller;
+    }
+}

package/src/util/Bytes.ts

@@ -122,10 +122,22 @@ export namespace Bytes {
         return fromHex(result);
     }
 
-    export function fromString(string: string): Bytes {
+    export function fromString(string: string | Bytes): Bytes {
+        if (Bytes.isBytes(string)) {
+            return string;
+        }
+
         return new TextEncoder().encode(string);
     }
 
+    export function toString(bytes: string | Bytes): string {
+        if (!Bytes.isBytes(bytes)) {
+            return bytes;
+        }
+
+        return new TextDecoder().decode(bytes);
+    }
+
     export function concat(...arrays: Bytes[]): Bytes {
         let length = 0;
         const data = arrays.map(array => Bytes.of(array));
@@ -161,4 +173,6 @@ export namespace Bytes {
         }
         return result;
     }
+
+    export const empty = new Uint8Array();
 }

package/src/util/Cancelable.ts

@@ -7,7 +7,7 @@
 import type { Logger } from "#log/Logger.js";
 import { CanceledError } from "#MatterError.js";
 import { asError, errorOf } from "./Error.js";
-import { createPromise, MaybePromise } from "./Promises.js";
+import { MaybePromise } from "./Promises.js";
 
 /**
  * An operation that may be canceled.
@@ -155,226 +155,3 @@ export class CancelablePromise<T = void> implements Promise<T>, Cancelable {
         return this.#logger;
     }
 }
-
-/**
- * An {@link AsyncIterator} that may be canceled.
- */
-export class CancelableAsyncIterator<T, TReturn = T, TNext = void>
-    implements AsyncIterator<T, TReturn, TNext>, Cancelable
-{
-    // The result of the final iteration
-    #settled?: boolean;
-
-    // The input next implementation
-    #next: (...[value]: [] | [TNext]) => Promise<IteratorResult<T, TReturn>>;
-
-    // We race against this promise to detect cancelation during next()
-    #canceled: Promise<IteratorResult<T, TReturn>>;
-
-    // Rejects #canceled
-    #reject!: (reason: any) => void;
-
-    /**
-     * Create a new instance.
-     *
-     * @param next the function that produces results
-     * @param onCancel if provided this will overwrite {@link onCancel}
-     */
-    constructor(
-        next: (...[value]: [] | [TNext]) => Promise<IteratorResult<T, TReturn>>,
-        onCancel?: (reason: Error) => void,
-    ) {
-        this.#next = next;
-        this.#canceled = new Promise((_resolve, reject) => (this.#reject = reject));
-        if (onCancel !== undefined) {
-            this.onCancel = onCancel;
-        }
-    }
-
-    next(...[value]: [] | [TNext]): Promise<IteratorResult<T, TReturn>> {
-        if (this.#settled) {
-            // This type is a lie if TReturn does not allow undefined but TS doesn't give us any options here, and
-            // calling next after the final iteration doesn't make semantic sense anyway.  The spec does say subsequent
-            // calls should return done = true
-            return Promise.resolve({ done: true } as IteratorResult<T, TReturn>);
-        }
-
-        const next = value === undefined ? this.#next() : this.#next(value);
-
-        // If next resolves after we've canceled we ignore it, but if we were to do that with an error it would be
-        // unhandled.  Errors from next will still cause an unhandled error if not caught before we set this.#final
-        // because we rethrow from the race below where this.#final cannot be set
-        next.catch(reason => {
-            if (this.#settled) {
-                CancelablePromise.logger.warn(`Cancelable async iterator rejected after return:`, reason);
-            }
-        });
-
-        return Promise.race([next, this.#canceled]).then(
-            result => {
-                // next resolved (this.#canceled can only be rejected)
-                if (result.done) {
-                    this.#settled = true;
-                }
-                return result;
-            },
-            reason => {
-                // next or this.#canceled rejected; regardless we use this for all subsequent calls to next() since we
-                // will never receive TReturn
-                this.#settled = true;
-                throw reason;
-            },
-        );
-    }
-
-    cancel(reason: any): void {
-        if (this.#settled) {
-            return;
-        }
-
-        try {
-            this.onCancel(reason);
-        } catch (e) {
-            this.#reject(e);
-        }
-    }
-
-    /**
-     * Handle cancelation.
-     *
-     * If the underlying operation supports cancelation then it is better to use that.  Otherwise throwing
-     * {@link reason} (the default behavior) will reject the current (or next) iteration regardless of the state of the
-     * underyling operation.
-     *
-     * @param reason the reason provided to {@link cancel}
-     */
-    protected onCancel(reason: any) {
-        throw reason;
-    }
-
-    static is(value: unknown): value is CancelableAsyncIterator<unknown> {
-        return (
-            typeof value === "object" &&
-            value !== null &&
-            Symbol.asyncIterator in value &&
-            typeof value[Symbol.asyncIterator] === "function" &&
-            "cancel" in value &&
-            typeof value["cancel"] === "function"
-        );
-    }
-}
-
-/**
- * Create a function that returns a {@link CancelablePromise} and delegates cancelation internally to other async logic.
- *
- * The output function invokes the supplied {@link executor} with an additional "cancelable" argument.  This function
- * wraps supported types (currently {@link CancelablePromise}, {@link CancelableAsyncIterator} and {@link Promise}) with
- * cancelation logic.
- *
- * Any such wrapped object behaves normally but will throw with the cancelation reason on cancel.
- */
-export function Cancelable<ThisT, ArgsT extends unknown[], ReturnT>(
-    executor: Cancelable.Executor<ThisT, ArgsT, ReturnT>,
-) {
-    // The proxy that invokes the executor with a "canceable" argument used for delegation
-    return function cancelable(this: ThisT, ...args: ArgsT): CancelablePromise<ReturnT> {
-        // Active delegates register here
-        let delegates: undefined | Set<(reason: any) => void>;
-
-        // The return value from the proxy function
-        return new CancelablePromise<ReturnT>(
-            (resolve, reject) => {
-                // Invoke the executor
-                try {
-                    const result = executor.call(this, cancelable, ...args);
-
-                    if (MaybePromise.is(result)) {
-                        result.then(resolve, reject);
-                        return;
-                    }
-
-                    resolve(result);
-                } catch (e) {
-                    reject(e);
-                }
-
-                // We pass this function to the executor; the executor invokes on supported objects to perform
-                // delegation
-                function cancelable<T>(value: T): T {
-                    // Delegation to cancelable promise - just cancel when we are canceled; unregister when the target
-                    // resolves
-                    if (CancelablePromise.is(value)) {
-                        const undelegate = addDelegate(reason => value.cancel(reason));
-                        return value.finally(undelegate) as T;
-                    }
-
-                    // Delegation to cancelable async iterators - cancel when we cancel; unregister when iteration
-                    // completes
-                    if (CancelableAsyncIterator.is(value)) {
-                        const undelegate = addDelegate(reason => value.cancel(reason));
-                        const next = value.next.bind(value);
-                        value.next = () => {
-                            return next().then(
-                                result => {
-                                    if (result.done) {
-                                        undelegate();
-                                    }
-                                    return result;
-                                },
-                                reason => {
-                                    undelegate();
-                                    throw reason;
-                                },
-                            );
-                        };
-
-                        return value;
-                    }
-
-                    // Delegation to non-cancelable promises - use a race to abort the wait but operation will proceed
-                    if (MaybePromise.is(value)) {
-                        const { promise, rejecter } = createPromise<T>();
-                        const undelegate = addDelegate(reason => rejecter(reason));
-                        return Promise.race([promise, value]).finally(() => undelegate) as T;
-                    }
-
-                    // No delegation possible; just return the original value
-                    return value;
-                }
-            },
-
-            // Our "onCancel" that delegates to any registered delegators or simply rethrows if no delegation is active
-            reason => {
-                if (!delegates?.size) {
-                    throw reason;
-                }
-
-                for (const delegate of delegates) {
-                    delegate(reason);
-                }
-            },
-        );
-
-        // Register a delegate
-        function addDelegate(delegate: (reason: any) => void) {
-            if (!delegates) {
-                delegates = new Set();
-            }
-            delegates.add(delegate);
-
-            return () => {
-                delegates?.delete(delegate);
-            };
-        }
-    };
-}
-
-export namespace Cancelable {
-    export interface Delegator {
-        <T>(value: T): T;
-    }
-
-    export interface Executor<ThisT, ArgsT extends unknown[], ReturnT> {
-        (this: ThisT, cancelable: Delegator, ...args: ArgsT): MaybePromise<ReturnT>;
-    }
-}

package/src/util/DataReadQueue.ts

@@ -11,9 +11,9 @@ import { Minutes } from "#time/TimeUnit.js";
 import { MatterFlowError } from "../MatterError.js";
 import { Time, Timer } from "../time/Time.js";
 import { createPromise } from "./Promises.js";
-import { EndOfStreamError, NoResponseTimeoutError, Stream } from "./Stream.js";
+import { EndOfStreamError, NoResponseTimeoutError } from "./Streams.js";
 
-export class DataReadQueue<T> implements Stream<T> {
+export class DataReadQueue<T> {
     readonly #queue = new Array<T>();
     #pendingRead?: { resolver: (data: T) => void; rejecter: (reason: any) => void; timeoutTimer?: Timer };
     #closed = false;

package/src/util/Promises.ts

@@ -286,4 +286,117 @@ export const MaybePromise = {
     [Symbol.toStringTag]: "MaybePromise",
 };
 
+/**
+ * A recurring promise.
+ *
+ * A gate is duck-compatible with {@link Promise} and includes resolution methods on its public API.
+ *
+ * As an extension to normal promise semantics, a gate may be "opened" or "closed".  {@link open} provides multi-
+ * resolution so that future awaits return a new value.  {@link close} returns the promise to an unsettled state so that
+ * future awaits block.
+ *
+ * This is useful for basic synchronization of two tightly coupled ongoing tasks.
+ */
+export class Gate<T = void> implements Promise<T> {
+    #promise: Promise<T>;
+    #resolve: (value: T) => void;
+    #reject: (reason: any) => void;
+    #resolvedAs: unknown;
+    #isResolved = false;
+    #isRejected = false;
+
+    constructor() {
+        let resolve: (value: T) => void;
+        let reject: (reason: any) => void;
+
+        this.#promise = new Promise<T>((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+
+        this.#resolve = resolve!;
+        this.#reject = reject!;
+    }
+
+    /**
+     * Move to resolved state with the specified value.
+     */
+    open(value: T) {
+        if (this.#isResolved) {
+            if (this.#resolvedAs === value) {
+                return;
+            }
+
+            this.#resolvedAs = value;
+            this.#promise = Promise.resolve(value);
+            return;
+        }
+
+        if (this.#isRejected) {
+            this.#resolvedAs = value;
+            this.#isResolved = true;
+            this.#isRejected = false;
+            this.#promise = Promise.resolve(value);
+            return;
+        }
+
+        this.resolve(value);
+    }
+
+    /**
+     * Move to unresolved state.
+     */
+    close() {
+        if (!this.#isResolved && !this.#isRejected) {
+            return;
+        }
+
+        this.#isResolved = this.#isRejected = false;
+        this.#promise = new Promise((resolve, reject) => {
+            this.#resolve = resolve;
+            this.#reject = reject;
+        });
+    }
+
+    /**
+     * Perform normal promise resolution.  Ignored if promise is already settled.
+     */
+    resolve(value: T) {
+        if (this.#isResolved || this.#isRejected) {
+            return;
+        }
+        this.#resolvedAs = value;
+        this.#isResolved = true;
+        this.#resolve(value);
+    }
+
+    /**
+     * Perform normal promise rejection.  Ignored if promise is already settled.
+     */
+    reject(cause: any) {
+        if (this.#isResolved || this.#isRejected) {
+            return;
+        }
+        this.#isRejected = true;
+        this.#reject(cause);
+    }
+
+    then<TResult1 = T, TResult2 = never>(
+        resolve?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
+        reject?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
+    ) {
+        return this.#promise.then(resolve, reject);
+    }
+
+    catch<TResult = never>(reject?: ((reason: any) => TResult | PromiseLike<TResult>) | null) {
+        return this.#promise.catch(reject);
+    }
+
+    finally(then?: (() => void) | null) {
+        return this.#promise.finally(then);
+    }
+
+    [Symbol.toStringTag] = Promise.prototype[Symbol.toStringTag];
+}
+
 MaybePromise.toString = () => "MaybePromise";

package/src/util/Set.ts

@@ -215,7 +215,9 @@ export class BasicSet<T, AddT = T> implements ImmutableSet<T>, MutableSet<T, Add
     }
 
     clear() {
-        this.#entries.clear();
+        for (const entry of [...this]) {
+            this.delete(entry);
+        }
     }
 
     get added() {