@matter/general 0.16.0-alpha.0-20251006-3fe1e7c57 → 0.16.0-alpha.0-20251013-89bb7099d

package/src/net/http/HttpSharedEndpoint.ts

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger } from "#log/Logger.js";
+import { HttpEndpoint } from "./HttpEndpoint.js";
+
+const logger = Logger.get("HttpSharedEntpoint");
+
+/**
+ * Shared access to a single underlying HTTP endpoint.
+ */
+export class HttpSharedEndpoint {
+    #create: () => Promise<HttpEndpoint>;
+    #target?: Promise<HttpEndpoint>;
+    #instances = new Set<HttpEndpoint>();
+    #isTls: boolean;
+
+    constructor(isTls: boolean, create: () => Promise<HttpEndpoint>) {
+        this.#isTls = isTls;
+        this.#create = create;
+    }
+
+    get isTls() {
+        return this.#isTls;
+    }
+
+    async use() {
+        if (this.#target === undefined) {
+            this.#target = this.#createTarget();
+        }
+
+        await this.#target;
+
+        const instance: HttpEndpoint = {
+            http: undefined,
+            ws: undefined,
+
+            close: async () => {
+                this.#instances.delete(instance);
+                if (!this.#instances.size) {
+                    try {
+                        await (await this.#target)?.close();
+                    } catch (e) {
+                        logger.error("Error closing HTTP endpoint", e);
+                    } finally {
+                        this.#target = undefined;
+                    }
+                }
+            },
+        };
+
+        this.#instances.add(instance);
+
+        return instance;
+    }
+
+    async #createTarget() {
+        const target = await this.#create();
+
+        target.http = async request => {
+            for (const instance of this.#instances) {
+                const response = await instance.http?.(request);
+                if (response) {
+                    return response;
+                }
+            }
+        };
+
+        target.ws = async (request, connect) => {
+            let connected = false;
+            for (const instance of this.#instances) {
+                await instance.ws?.(request, async () => {
+                    connected = true;
+                    return connect();
+                });
+
+                if (connected) {
+                    break;
+                }
+            }
+        };
+
+        return target;
+    }
+}

package/src/net/http/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./HttpEndpoint.js";
+export * from "./HttpEndpointFactory.js";
+export * from "./HttpEndpointGroup.js";
+export * from "./HttpService.js";
+export * from "./HttpSharedEndpoint.js";

package/src/net/index.ts

@@ -7,7 +7,9 @@
 export * from "./AppAddress.js";
 export * from "./Channel.js";
 export * from "./ConnectionlessTransport.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";

package/src/net/mqtt/MqttEndpoint.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Environment } from "#environment/Environment.js";
+import { AppAddress } from "#net/AppAddress.js";
+import { Abort } from "#util/Abort.js";
+import { Bytes } from "#util/Bytes.js";
+import { MaybePromise } from "#util/Promises.js";
+
+export interface MqttEndpoint {
+    subscribe(
+        topic: string,
+        options?: MqttEndpoint.SubscriptionOptions,
+    ): AsyncIterableIterator<MqttEndpoint.Message, void, void>;
+    publish(message: MqttEndpoint.Message): Promise<void>;
+
+    close(): Promise<void>;
+}
+
+export namespace MqttEndpoint {
+    export interface Message {
+        topic: string;
+        payload: Bytes | string | null;
+        retain?: boolean;
+        contentType?: string;
+        responseTopic?: string;
+        correlationData?: Bytes;
+        qos?: 0 | 1 | 2;
+    }
+
+    export function Message(message: Message) {
+        return message;
+    }
+
+    export interface ConnectionOptions {
+        address: AppAddress.Definition;
+        environment?: Environment;
+        will?: Message;
+        onUp?: (endpoint: MqttEndpoint) => MaybePromise<void>;
+        onDown?: (endpoint: MqttEndpoint) => MaybePromise<void>;
+    }
+
+    export interface SubscriptionOptions {
+        noLocal?: boolean;
+        abort?: Abort.Signal;
+    }
+}

package/src/net/mqtt/MqttEndpointFactory.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MqttEndpoint } from "./MqttEndpoint.js";
+import type { MqttService } from "./MqttService.js";
+
+/**
+ * Connects to an MQTT broker.
+ *
+ * MQTT adapters should implement this class.  Clients should access via {@link MqttService}.
+ */
+export abstract class MqttEndpointFactory {
+    abstract connect(options: MqttEndpoint.ConnectionOptions): Promise<MqttEndpoint>;
+}

package/src/net/mqtt/MqttService.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Environment } from "#environment/Environment.js";
+import { Environmental } from "#environment/Environmental.js";
+import { ImplementationError } from "#MatterError.js";
+import { AppAddress } from "#net/AppAddress.js";
+import { MqttEndpoint } from "./MqttEndpoint.js";
+import { MqttEndpointFactory } from "./MqttEndpointFactory.js";
+
+/**
+ * Provides connections to MQTT brokers.
+ */
+export class MqttService {
+    #factory: MqttEndpointFactory;
+
+    constructor(factory: MqttEndpointFactory) {
+        this.#factory = factory;
+    }
+
+    static [Environmental.create](env: Environment) {
+        const factory = env.get(MqttEndpointFactory);
+        const instance = new this(factory);
+        env.set(MqttService, instance);
+        return instance;
+    }
+
+    connect(options: MqttEndpoint.ConnectionOptions) {
+        const addr = AppAddress.for(options.address);
+
+        if (addr.appProtocol !== "mqtt") {
+            throw new ImplementationError(`Unsupported address ${addr} for MQTT connection`);
+        }
+
+        return this.#factory.connect(options);
+    }
+}

package/src/net/mqtt/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./MqttEndpoint.js";
+export * from "./MqttEndpointFactory.js";
+export * from "./MqttService.js";

package/src/net/udp/UdpChannel.ts

@@ -11,13 +11,46 @@ import { ConnectionlessTransport } from "../ConnectionlessTransport.js";
 /** @see {@link MatterSpecification.v12.Core} § 4.4.4 */
 export const MAX_UDP_MESSAGE_SIZE = 1280 - 48; // 48 bytes IP and UDP header size for IPv6
 
-export type UdpSocketType = "udp4" | "udp6";
+/**
+ * UDP socket address type.
+ *
+ * "udp4" and "udp6" are IPv4 and IPv6 exclusively.  "udp" binds both IPv4 and IPv6 addresses.
+ */
+export type UdpSocketType = "udp" | "udp4" | "udp6";
 
 export interface UdpChannelOptions {
-    listeningPort?: number;
+    /**
+     * UDP channel type.  "udp4" and "udp6" mean IPv4 and IPv6 respectively.  "udp" is dual-mode IPv4/IPv6.
+     */
     type: UdpSocketType;
+
+    /**
+     * The port to listen on.  undefined or 0 directs the operating system to select an open port.
+     */
+    listeningPort?: number;
+
+    /**
+     * The address to listen on, either a hostname or IP address in correct format based on {@link type}.
+     *
+     * undefined directs the operating system to listen on all addresses on the port.  "0.0.0.0" is wildcard IPv4 and
+     * "::" is wildcard IPv6.
+     *
+     * "0.0.0.0" is not allowed if {@link type} is "udp".
+     */
     listeningAddress?: string;
+
+    /**
+     * Specifies a specific network interface.
+     *
+     * This is required for multicast sockets.
+     */
     netInterface?: string;
+
+    /**
+     * Address+port pairs are normally may normally only be opened by a single socket.  This allows shared access to a
+     * port.
+     */
+    reuseAddress?: boolean;
 }
 
 export interface UdpChannel {

package/src/net/udp/UdpMulticastServer.ts

@@ -39,6 +39,7 @@ export class UdpMulticastServer {
                     type: "udp4",
                     netInterface,
                     listeningPort,
+                    reuseAddress: true,
                 });
                 await ipv4UdpChannel.addMembership(broadcastAddressIpv4);
             } catch (error) {
@@ -52,6 +53,7 @@ export class UdpMulticastServer {
                 type: "udp6",
                 netInterface,
                 listeningPort,
+                reuseAddress: true,
             });
             await ipv6UdpChannel.addMembership(broadcastAddressIpv6);
             return new UdpMulticastServer(
@@ -160,6 +162,7 @@ export class UdpMulticastServer {
             type: iPv4 ? "udp4" : "udp6",
             listeningPort: this.broadcastPort,
             netInterface,
+            reuseAddress: true,
         });
     }
 

package/src/storage/StorageService.ts

@@ -18,9 +18,17 @@ export class StorageService {
     #factory?: (namespace: string) => Storage;
     #location?: string;
 
-    constructor(environment: Environment, factory?: (namespace: string) => Storage) {
+    constructor(
+        environment: Environment,
+        factory?: (namespace: string) => Storage,
+        resolver?: (...paths: string[]) => string,
+    ) {
         environment.set(StorageService, this);
         this.#factory = factory;
+
+        // Fallback resolver is dumb and probably not useful; expected to be replaced by platform implementation if
+        // file resolution is necessary
+        this.resolve = resolver ?? ((...paths: []) => paths.join("/"));
     }
 
     static [Environmental.create](environment: Environment) {
@@ -61,6 +69,11 @@ export class StorageService {
         this.#location = location;
     }
 
+    /**
+     * Join one or more relative paths to some platform-dependent notion of an absolute storage path.
+     */
+    resolve: (...paths: string[]) => string;
+
     [Diagnostic.value]() {
         return [
             "Persistence",

package/src/time/Duration.ts

@@ -19,7 +19,7 @@ import type { Millis, Seconds, TimeUnit } from "./TimeUnit.js";
  * Math operators always result in millisecond values and can thus be converted back to an interval using
  * {@link Millis}.  For example, `Millisecs(Hours(1) + Minutes(30))` would produce a 90 minute {@link Duration}.
  */
-export type Duration = Branded<number, "Interval"> | 0;
+export type Duration = Branded<number, "Duration"> | 0;
 
 /**
  * Create an interval from a number or string.

package/src/util/Abort.ts

@@ -4,6 +4,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { TimeoutError } from "#MatterError.js";
+import { Duration } from "#time/Duration.js";
+import { Time, Timer } from "#time/Time.js";
+
 /**
  * Utilities for implementing abort logic.
  */
@@ -72,20 +76,40 @@ export namespace Abort {
      * aborts.
      *
      * Closing the returned controller unregisters with the input controller.  It does not perform an abort.
+     *
+     * {@link timeout} is a convenience for adding a timeout.
      */
-    export function subtask(signal: Signal | undefined): DisposableController {
+    export function subtask(signal: Signal | undefined, timeout?: Duration): DisposableController {
+        let timer: Timer | undefined;
+
         if (signal && "signal" in signal) {
             signal = signal.signal;
         }
 
         const controller = new AbortController() as DisposableController;
 
+        if (timeout) {
+            timer = Time.getPeriodicTimer("subtask timeout", timeout, () => {
+                if (controller.signal.aborted) {
+                    return;
+                }
+
+                controller.abort(new TimeoutError());
+            });
+            timer.start();
+        }
+
         if (signal) {
-            const outerHandler = () => controller.abort();
+            const outerHandler = () => controller.abort(signal.reason);
             signal.addEventListener("abort", outerHandler);
-            controller[Symbol.dispose] = () => signal.removeEventListener("abort", outerHandler);
+            controller[Symbol.dispose] = () => {
+                signal.removeEventListener("abort", outerHandler);
+                timer?.stop();
+            };
         } else {
-            controller[Symbol.dispose] = () => {};
+            controller[Symbol.dispose] = () => {
+                timer?.stop();
+            };
         }
 
         return controller;

package/src/util/Construction.ts

@@ -39,7 +39,7 @@ export async function asyncNew<const A extends any[], const C extends new (...ar
  * Construction happens in the initializer parameter of {@link Construction} or via {@link Construction.construct} on
  * the subject.  You invoke in your constructor and place in a property called "construction".
  *
- * Destruciton is optional and happens in the destructor parameter of {@link Construction#close} or via
+ * Destruction is optional and happens in the destructor parameter of {@link Construction#close} or via
  * {@link Construction.destruct} on the subject.  Typically you invoke in a "close" method of the subject.
  *
  * If construction or destruction is not asynchronous (does not return a Promise) then they complete synchronously,
@@ -430,7 +430,7 @@ export function Construction<const T extends Constructable>(
                   }
                 : invokeDestruct;
 
-            // Destruction phase 1 - move to destroyed state
+            // Destruction phase 1 - move to destroying state
             function beginDestruction() {
                 if (status === Lifecycle.Status.Destroying || status === Lifecycle.Status.Destroyed) {
                     return self.closed;

package/src/util/Multiplex.ts

@@ -43,7 +43,7 @@ export class BasicMultiplex implements PromiseLike<void> {
                     if (description) {
                         message = `${message} in ${description}`;
                     }
-                    logger.error(message, e);
+                    logger.error(`${message}:`, e);
                 })
                 .finally(() => this.#workers.delete(entry)),
             description,

package/src/util/String.ts

@@ -104,7 +104,7 @@ export function decamelize(name: string, separator = "-") {
 /**
  * Like JSON.stringify but targets well-formed JS and is slightly more readable.
  */
-export function serialize(value: any) {
+export function serialize(value: unknown) {
     const visited = new Set();
 
     function asValidKey(key: string) {
@@ -114,15 +114,15 @@ export function serialize(value: any) {
         return JSON.stringify(key);
     }
 
-    function serializeOne(value: any): string | undefined {
+    function serializeOne(value: unknown): string | undefined {
         if (value === undefined) {
             return;
         }
         if (value === null) {
             return "null";
         }
-        if (value[serialize.SERIALIZE]) {
-            return value[serialize.SERIALIZE]();
+        if ((value as { [serialize.SERIALIZE](): string })[serialize.SERIALIZE]) {
+            return (value as { [serialize.SERIALIZE](): string })[serialize.SERIALIZE]();
         }
         if (typeof value === "function") {
             return;
@@ -147,7 +147,7 @@ export function serialize(value: any) {
         if (visited.has(value)) {
             return;
         }
-        if (value.toJSON) {
+        if ((value as { toJSON(): string }).toJSON) {
             value = JSON.parse(JSON.stringify(value));
         }
 
@@ -161,7 +161,7 @@ export function serialize(value: any) {
                 return "[]";
             }
 
-            const entries = Object.entries(value)
+            const entries = Object.entries(value as {})
                 .map(([k, v]) => [k, serializeOne(v)])
                 .filter(([_k, v]) => v !== undefined)
                 .map(([k, v]) => `${asValidKey(k ?? "")}: ${v}`);
@@ -179,6 +179,25 @@ export function serialize(value: any) {
     return serializeOne(value);
 }
 
+/**
+ * Like {@link JSON.stringify} but with support for additional standard objects.
+ */
+export function asJson(value: unknown, space?: number) {
+    return JSON.stringify(
+        value,
+        (_key, value) => {
+            if (typeof value === "bigint") {
+                return value.toString();
+            }
+            if (Bytes.isBytes(value)) {
+                return Bytes.toHex(value);
+            }
+            return value;
+        },
+        space,
+    );
+}
+
 export namespace serialize {
     /**
      * Custom serialization function key.