@matter/general 0.16.0-alpha.0-20251006-3fe1e7c57 → 0.16.0-alpha.0-20251011-d8942d7d5

package/src/environment/Environmental.ts

@@ -22,10 +22,25 @@ export namespace Environmental {
         construction?: Promise<any>;
     }
 
+    /**
+     * An object used for service identification.
+     *
+     * We use classes as the key for service registration.  Classes serve as ideal keys because they are trivial to
+     * manage and allow us to manage services in a type-safe manner.
+     *
+     * Any class may be used as the service identifier; the only requirement is that a registered instance is a subclass
+     * of the {@link ServiceType}.
+     *
+     * Note that {@link Environment} only considers service available for the exact class under which they are
+     * registered.  You cannot retrieve a service registered for a subclass of a {@link ServiceType} using the base
+     * class.  You can however register the under both the base and derived {@link ServiceType}s.
+     */
+    export type ServiceType<T extends object = object> = abstract new (...args: any[]) => T;
+
     /**
      * A factory for a {@link Service}.
      *
-     * A "factory" is just a class with a static {@link create} method that performs instantiation.
+     * A "factory" is a concrete {@link ServiceType} with a static {@link create} method that performs instantiation.
      */
     export interface Factory<T extends object = object> {
         new (...args: any[]): T;
@@ -42,7 +57,7 @@ export namespace Environmental {
     /**
      * Events related to service lifecycle.
      */
-    export interface ServiceEvents<T extends abstract new (...args: any[]) => T> {
+    export interface ServiceEvents<T extends Environmental.ServiceType> {
         added: Observable<[instance: InstanceType<T>]>;
         deleted: Observable<[instance: InstanceType<T>]>;
     }

package/src/log/Logger.ts

@@ -215,7 +215,7 @@ export class Logger {
             const dest = Logger.destinations[name];
 
             if (level < (dest.facilityLevels?.[this.#name] ?? dest.level)) {
-                return;
+                continue;
             }
 
             if (!dest.context) {

package/src/net/Network.ts

@@ -12,6 +12,10 @@ export class NetworkError extends MatterError {}
 
 export class NoAddressAvailableError extends NetworkError {}
 
+export class BindError extends NetworkError {}
+
+export class AddressInUseError extends BindError {}
+
 export const STANDARD_MATTER_PORT = 5540;
 
 /**

package/src/net/ServerAddress.ts

@@ -84,6 +84,22 @@ export namespace ServerAddress {
         return Diagnostic.squash(...diagnostic);
     }
 
+    export function isEqual(a: ServerAddress, b: ServerAddress): boolean {
+        if (a.type !== b.type) {
+            return false;
+        }
+
+        if (a.type === "udp" && b.type === "udp") {
+            return a.ip === b.ip && a.port === b.port;
+        }
+
+        if (a.type === "ble" && b.type === "ble") {
+            return a.peripheralAddress === b.peripheralAddress;
+        }
+
+        return false;
+    }
+
     export function definitionOf(address: ServerAddress): Definition {
         return address;
     }

package/src/net/http/HttpEndpoint.ts

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { AppAddress } from "#net/AppAddress.js";
+import { Bytes } from "#util/Bytes.js";
+import { MaybePromise } from "#util/Promises.js";
+
+/**
+ * A platform-independent HTTP endpoint implementation.
+ *
+ * This provides a modern WinterTC-style interface with a focus on simplifying platform-specific implementations.
+ */
+export interface HttpEndpoint {
+    /**
+     * Handler for normal HTTP requests.
+     */
+    http?: HttpEndpoint.HttpHandler;
+
+    /**
+     * Handler for WebSocket upgrade requests.
+     */
+    ws?: HttpEndpoint.WsHandler;
+
+    /**
+     * Release resources for the endpoint.
+     */
+    close(): Promise<void>;
+}
+
+export namespace HttpEndpoint {
+    /**
+     * HTTP request callback.
+     */
+    export type HttpHandler = (request: Request) => MaybePromise<void | Response>;
+
+    /**
+     * WebSocket request callback.
+     */
+    export type WsHandler = (request: Request, upgrade: () => Promise<WsConnection>) => MaybePromise<void>;
+
+    /**
+     * A WebSocket connection.
+     */
+    export interface WsConnection extends ReadableWritablePair<WsMessage, WsMessage> {}
+
+    /**
+     * Raw WebSocket message payload.
+     */
+    export type WsMessage = Bytes | string;
+
+    /**
+     * Configuration options.
+     */
+    export interface Options {
+        address: AppAddress.Definition;
+    }
+}

package/src/net/http/HttpEndpointFactory.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { HttpEndpoint } from "./HttpEndpoint.js";
+import type { HttpService } from "./HttpService.js";
+
+/**
+ * Environmental component that creates HTTP endpoints.
+ *
+ * This component creates a dedicated HTTP server.  Use {@link HttpService} for shared access to HTTP endpoints.
+ */
+export abstract class HttpEndpointFactory {
+    /**
+     * Indicates support for HTTP handlers.
+     */
+    supportsHttp = true;
+
+    /**
+     * Indicates support for WebSocket handlers.
+     */
+    supportsWs = true;
+
+    abstract create(options: HttpEndpoint.Options): Promise<HttpEndpoint>;
+}

package/src/net/http/HttpEndpointGroup.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger } from "#log/Logger.js";
+import { MatterAggregateError } from "#MatterError.js";
+import { HttpEndpoint } from "./HttpEndpoint.js";
+
+const logger = Logger.get("HttpEndpointGroup");
+
+/**
+ * A collection of HTTP endpoints that support the same set of handlers.
+ */
+export class HttpEndpointGroup implements HttpEndpoint {
+    #endpoints: HttpEndpoint[];
+
+    constructor(endpoints: HttpEndpoint[]) {
+        this.#endpoints = endpoints;
+    }
+
+    set http(handler: HttpEndpoint.HttpHandler) {
+        for (const endpoint of this.#endpoints) {
+            endpoint.http = handler;
+        }
+    }
+
+    set ws(handler: HttpEndpoint.WsHandler) {
+        for (const endpoint of this.#endpoints) {
+            endpoint.ws = handler;
+        }
+    }
+
+    async close(): Promise<void> {
+        try {
+            await MatterAggregateError.allSettled(this.#endpoints.map(endpoint => endpoint.close()));
+        } catch (e) {
+            logger.error("Error closing HTTP endpoints", e);
+        }
+        this.#endpoints = [];
+    }
+}

package/src/net/http/HttpService.ts

@@ -0,0 +1,75 @@
+/**
+ * @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 { HttpEndpoint } from "./HttpEndpoint.js";
+import { HttpEndpointFactory } from "./HttpEndpointFactory.js";
+import { HttpEndpointGroup } from "./HttpEndpointGroup.js";
+import { HttpSharedEndpoint } from "./HttpSharedEndpoint.js";
+
+/**
+ * An environmental service that manages shared access to a set of endpoints.
+ */
+export class HttpService {
+    #factory: HttpEndpointFactory;
+    #endpoints = {} as Record<string, HttpSharedEndpoint>;
+
+    constructor(factory: HttpEndpointFactory) {
+        this.#factory = factory;
+    }
+
+    async create(...addresses: AppAddress.Definition[]) {
+        if (addresses.length === 1) {
+            return this.#forAddress(addresses[0]);
+        }
+
+        const endpoints = Array<HttpEndpoint>();
+
+        try {
+            for (const address of addresses) {
+                endpoints.push(await this.#forAddress(address));
+            }
+        } catch (e) {
+            await Promise.allSettled(endpoints.map(endpoint => endpoint.close()));
+            throw e;
+        }
+
+        return new HttpEndpointGroup(endpoints);
+    }
+
+    async #forAddress(address: AppAddress.Definition) {
+        const addr = AppAddress.for(address);
+        if (addr.appProtocol !== "http" && addr.appProtocol !== "ws") {
+            throw new ImplementationError(`Unsupported address ${addr} for HTTP endpoint`);
+        }
+
+        const key = JSON.stringify(addr.transport);
+        let endpoint = this.#endpoints[key];
+        if (endpoint) {
+            if (endpoint.isTls !== addr.isTls) {
+                const addrIs = addr.isTls ? "encrypted" : "unencrypted";
+                const endpointIs = endpoint.isTls ? "encrypted" : "unencrypted";
+                throw new ImplementationError(
+                    `Service address ${addr} is ${addrIs} but existing endpoint is ${endpointIs}`,
+                );
+            }
+        } else {
+            endpoint = new HttpSharedEndpoint(addr.isTls, () => this.#factory.create({ address }));
+            this.#endpoints[key] = endpoint;
+        }
+
+        return await endpoint.use();
+    }
+
+    static [Environmental.create](env: Environment) {
+        const instance = new HttpService(env.get(HttpEndpointFactory));
+        env.set(HttpService, instance);
+        return instance;
+    }
+}

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.