@matter/general 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/net/Network.ts

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MatterError, NoProviderError } from "../MatterError.js";
+import { MaybePromise } from "../util/Promises.js";
+import { UdpChannel, UdpChannelOptions } from "./UdpChannel.js";
+
+export class NetworkError extends MatterError {}
+
+/**
+ * @see {@link MatterSpecification.v11.Core} § 11.11.4.4
+ * Duplicated from the GeneralDiagnostics cluster to avoid circular dependencies.
+ */
+export enum InterfaceType {
+    /**
+     * Indicates an interface of an unspecified type.
+     */
+    Unspecified = 0,
+
+    /**
+     * Indicates a Wi-Fi interface.
+     */
+    WiFi = 1,
+
+    /**
+     * Indicates a Ethernet interface.
+     */
+    Ethernet = 2,
+
+    /**
+     * Indicates a Cellular interface.
+     */
+    Cellular = 3,
+
+    /**
+     * Indicates a Thread interface.
+     */
+    Thread = 4,
+}
+
+export type NetworkInterface = {
+    name: string;
+    type?: InterfaceType;
+};
+
+export type NetworkInterfaceDetails = {
+    mac: string;
+    ipV4: string[];
+    ipV6: string[];
+};
+
+export type NetworkInterfaceDetailed = NetworkInterface & NetworkInterfaceDetails;
+
+export abstract class Network {
+    // TODO - remove this singleton
+    static get: () => Network = () => {
+        throw new NoProviderError("No provider configured");
+    };
+
+    abstract getNetInterfaces(configuration?: NetworkInterface[]): MaybePromise<NetworkInterface[]>;
+    abstract getIpMac(netInterface: string): MaybePromise<NetworkInterfaceDetails | undefined>;
+    abstract createUdpChannel(options: UdpChannelOptions): Promise<UdpChannel>;
+
+    async close() {
+        // Nothing to do
+    }
+}

package/src/net/ServerAddress.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export type ServerAddressIp = {
+    type: "udp";
+    ip: string;
+    port: number;
+};
+
+export type ServerAddressBle = {
+    type: "ble";
+    peripheralAddress: string;
+};
+
+export type ServerAddress = ServerAddressIp | ServerAddressBle;
+
+export function serverAddressToString(address: ServerAddress): string {
+    return address.type === "udp" ? `udp://${address.ip}:${address.port}` : `ble://${address.peripheralAddress}`;
+}

package/src/net/TransportInterface.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { BasicSet } from "#util/Set.js";
+import { Channel, ChannelType } from "./Channel.js";
+
+/**
+ * A TransportInterface is a generic interface for sending and receiving data on an established incoming connection.
+ * It cannot open new connections.
+ */
+export interface TransportInterface {
+    onData(listener: (socket: Channel<Uint8Array>, data: Uint8Array) => void): TransportInterface.Listener;
+    close(): Promise<void>;
+    supports(type: ChannelType, address?: string): boolean;
+}
+
+export namespace TransportInterface {
+    export interface Listener {
+        close(): Promise<void>;
+    }
+}
+
+/**
+ * A collection of {@link TransportInterfaces} managed as a unit.
+ */
+export class TransportInterfaceSet<T extends TransportInterface = TransportInterface> extends BasicSet<T> {
+    constructor(...initialInterfaces: T[]) {
+        super(...initialInterfaces);
+    }
+
+    /**
+     * Closes all interfaces.
+     */
+    async close() {
+        for (const transportInterface of this) {
+            await transportInterface.close();
+        }
+    }
+
+    /**
+     * Obtain an interface capable of routing an address.
+     */
+    interfaceFor(type: ChannelType, address?: string) {
+        return this.find(transportInterface => transportInterface.supports(type, address));
+    }
+
+    /**
+     * Obtain an interface of specific type.
+     */
+    hasInterfaceFor(type: ChannelType, address?: string) {
+        return this.interfaceFor(type, address) !== undefined;
+    }
+}

package/src/net/UdpChannel.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ChannelType } from "./Channel.js";
+import { TransportInterface } from "./TransportInterface.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 interface UdpChannelOptions {
+    listeningPort?: number;
+    type: "udp4" | "udp6";
+    listeningAddress?: string;
+    netInterface?: string;
+    membershipAddresses?: string[];
+}
+
+export interface UdpChannel {
+    maxPayloadSize: number;
+    onData(
+        listener: (netInterface: string, peerAddress: string, peerPort: number, data: Uint8Array) => void,
+    ): TransportInterface.Listener;
+    send(host: string, port: number, data: Uint8Array): Promise<void>;
+    close(): void;
+    get port(): number;
+    supports(type: ChannelType, address?: string): boolean;
+}

package/src/net/UdpInterface.ts

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Channel, ChannelType } from "./Channel.js";
+import { NetInterface } from "./NetInterface.js";
+import { Network, NetworkError } from "./Network.js";
+import { ServerAddress } from "./ServerAddress.js";
+import { TransportInterface } from "./TransportInterface.js";
+import { UdpChannel } from "./UdpChannel.js";
+
+export class UdpInterface implements NetInterface {
+    static async create(network: Network, type: "udp4" | "udp6", port?: number, host?: string, netInterface?: string) {
+        return new UdpInterface(
+            await network.createUdpChannel({ listeningPort: port, type, netInterface, listeningAddress: host }),
+        );
+    }
+
+    constructor(private readonly server: UdpChannel) {}
+
+    supports(type: ChannelType, address: string) {
+        return this.server.supports(type, address);
+    }
+
+    async openChannel(address: ServerAddress) {
+        if (address.type !== "udp") {
+            throw new NetworkError(`Unsupported address type ${address.type}`);
+        }
+        const { ip, port } = address;
+        return Promise.resolve(new UdpConnection(this.server, ip, port));
+    }
+
+    onData(listener: (channel: Channel<Uint8Array>, messageBytes: Uint8Array) => void): TransportInterface.Listener {
+        return this.server.onData((_netInterface, peerHost, peerPort, data) =>
+            listener(new UdpConnection(this.server, peerHost, peerPort), data),
+        );
+    }
+
+    get port() {
+        return this.server.port;
+    }
+
+    async close() {
+        this.server.close();
+    }
+}
+
+class UdpConnection implements Channel<Uint8Array> {
+    readonly isReliable = false;
+    readonly type = ChannelType.UDP;
+
+    constructor(
+        private readonly server: UdpChannel,
+        private readonly peerAddress: string,
+        private readonly peerPort: number,
+    ) {}
+
+    get maxPayloadSize() {
+        return this.server.maxPayloadSize;
+    }
+
+    send(data: Uint8Array) {
+        return this.server.send(this.peerAddress, this.peerPort, data);
+    }
+
+    get name() {
+        return `${this.type}://${this.peerAddress}:${this.peerPort}`;
+    }
+
+    async close() {
+        // UDP is connectionless, so nothing to do here
+    }
+}

package/src/net/UdpMulticastServer.ts

@@ -0,0 +1,138 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger } from "../log/Logger.js";
+import { Cache } from "../util/Cache.js";
+import { isIPv4 } from "../util/Ip.js";
+import { Network } from "./Network.js";
+import { UdpChannel } from "./UdpChannel.js";
+
+const logger = Logger.get("UdpMulticastServer");
+
+export interface UdpMulticastServerOptions {
+    network: Network;
+    listeningPort: number;
+    broadcastAddressIpv6: string;
+    broadcastAddressIpv4?: string;
+    netInterface?: string;
+}
+
+export class UdpMulticastServer {
+    static async create({
+        netInterface,
+        broadcastAddressIpv4,
+        broadcastAddressIpv6,
+        listeningPort,
+        network,
+    }: UdpMulticastServerOptions) {
+        return new UdpMulticastServer(
+            network,
+            broadcastAddressIpv4,
+            broadcastAddressIpv6,
+            listeningPort,
+            broadcastAddressIpv4 === undefined
+                ? undefined
+                : await network.createUdpChannel({
+                      type: "udp4",
+                      netInterface,
+                      listeningPort,
+                      membershipAddresses: [broadcastAddressIpv4],
+                  }),
+            await network.createUdpChannel({
+                type: "udp6",
+                netInterface,
+                listeningPort,
+                membershipAddresses: [broadcastAddressIpv6],
+            }),
+            netInterface,
+        );
+    }
+
+    private readonly broadcastChannels = new Cache<Promise<UdpChannel>>(
+        "UDP broadcast channel",
+        (netInterface, iPv4) => this.createBroadcastChannel(netInterface, iPv4),
+        5 * 60 * 1000 /* 5mn */,
+        async (_netInterface, channel) => (await channel).close(),
+    );
+
+    private constructor(
+        private readonly network: Network,
+        private readonly broadcastAddressIpv4: string | undefined,
+        private readonly broadcastAddressIpv6: string,
+        private readonly broadcastPort: number,
+        private readonly serverIpv4: UdpChannel | undefined,
+        private readonly serverIpv6: UdpChannel,
+        private readonly netInterface: string | undefined,
+    ) {}
+
+    onMessage(listener: (message: Uint8Array, peerAddress: string, netInterface: string) => void) {
+        this.serverIpv4?.onData((netInterface, peerAddress, _port, message) =>
+            listener(message, peerAddress, netInterface),
+        );
+        this.serverIpv6.onData((netInterface, peerAddress, _port, message) =>
+            listener(message, peerAddress, netInterface),
+        );
+    }
+
+    async send(message: Uint8Array, netInterface?: string, uniCastTarget?: string) {
+        netInterface = netInterface ?? this.netInterface;
+
+        // When we know the network interface and the unicast target, we can send unicast
+        if (uniCastTarget !== undefined && netInterface !== undefined) {
+            try {
+                await (
+                    await this.broadcastChannels.get(netInterface, isIPv4(uniCastTarget))
+                ).send(uniCastTarget, this.broadcastPort, message);
+            } catch (error) {
+                logger.info(`${netInterface} ${uniCastTarget}: ${(error as Error).message}`);
+            }
+        } else {
+            const netInterfaces =
+                netInterface !== undefined ? [{ name: netInterface }] : await this.network.getNetInterfaces();
+            await Promise.all(
+                netInterfaces.map(async ({ name: netInterface }) => {
+                    const { ipV4, ipV6 } = (await this.network.getIpMac(netInterface)) ?? {
+                        mac: "",
+                        ipV4: [],
+                        ipV6: [],
+                    };
+                    const ips = [...ipV4, ...ipV6];
+                    await Promise.all(
+                        ips.map(async ip => {
+                            const iPv4 = ipV4.includes(ip);
+                            const broadcastTarget = iPv4 ? this.broadcastAddressIpv4 : this.broadcastAddressIpv6;
+                            if (broadcastTarget == undefined) {
+                                // IPv4 but disabled, so just resolve
+                                return;
+                            }
+                            try {
+                                await (
+                                    await this.broadcastChannels.get(netInterface, iPv4)
+                                ).send(broadcastTarget, this.broadcastPort, message);
+                            } catch (error) {
+                                logger.info(`${netInterface}: ${(error as Error).message}`);
+                            }
+                        }),
+                    );
+                }),
+            );
+        }
+    }
+
+    private async createBroadcastChannel(netInterface: string, iPv4: string): Promise<UdpChannel> {
+        return await this.network.createUdpChannel({
+            type: iPv4 ? "udp4" : "udp6",
+            listeningPort: this.broadcastPort,
+            netInterface,
+        });
+    }
+
+    async close() {
+        this.serverIpv4?.close();
+        this.serverIpv6.close();
+        await this.broadcastChannels.close();
+    }
+}

package/src/net/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./Channel.js";
+export * from "./mock/MockNetwork.js";
+export * from "./mock/MockUdpChannel.js";
+export * from "./mock/NetworkSimulator.js";
+export * from "./NetInterface.js";
+export * from "./Network.js";
+export * from "./ServerAddress.js";
+export * from "./TransportInterface.js";
+export * from "./UdpChannel.js";
+export * from "./UdpInterface.js";
+export * from "./UdpMulticastServer.js";

package/src/net/mock/MockNetwork.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ChannelType } from "#net/Channel.js";
+import { isIPv4 } from "../../util/Ip.js";
+import { Network, NetworkInterface, NetworkInterfaceDetails } from "../Network.js";
+import { UdpChannel, UdpChannelOptions } from "../UdpChannel.js";
+import { MockUdpChannel } from "./MockUdpChannel.js";
+import { NetworkSimulator } from "./NetworkSimulator.js";
+
+export class MockNetwork extends Network {
+    private readonly ipV4: string[];
+    private readonly ipV6: string[];
+
+    constructor(
+        private readonly mac: string,
+        ips: string[],
+    ) {
+        super();
+        this.ipV4 = ips.filter(ip => isIPv4(ip));
+        this.ipV6 = ips.filter(ip => !isIPv4(ip));
+    }
+
+    getNetInterfaces(): NetworkInterface[] {
+        return [{ name: NetworkSimulator.INTERFACE_NAME }];
+    }
+
+    getIpMac(_netInterface: string): NetworkInterfaceDetails {
+        return { mac: this.mac, ipV4: this.ipV4, ipV6: this.ipV6 };
+    }
+
+    override createUdpChannel(options: UdpChannelOptions): Promise<UdpChannel> {
+        return MockUdpChannel.create(this, options);
+    }
+
+    supports(type: ChannelType, _address: string) {
+        return type === ChannelType.UDP;
+    }
+}

package/src/net/mock/MockUdpChannel.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ChannelType } from "#net/Channel.js";
+import { NetworkError } from "../Network.js";
+import { TransportInterface } from "../TransportInterface.js";
+import { MAX_UDP_MESSAGE_SIZE, UdpChannel, UdpChannelOptions } from "../UdpChannel.js";
+import { MockNetwork } from "./MockNetwork.js";
+import { NetworkSimulator } from "./NetworkSimulator.js";
+
+export class MockUdpChannel implements UdpChannel {
+    static async create(
+        network: MockNetwork,
+        { listeningAddress, listeningPort, netInterface, type }: UdpChannelOptions,
+    ) {
+        const { ipV4, ipV6 } = network.getIpMac(netInterface ?? NetworkSimulator.INTERFACE_NAME);
+        const localAddress = type === "udp4" ? ipV4[0] : (ipV6[0] ?? ipV4[0]);
+        if (localAddress === undefined) {
+            throw new NetworkError("No matching IP on the specified interface");
+        }
+        return new MockUdpChannel(type, localAddress, listeningAddress, listeningPort);
+    }
+
+    private readonly netListeners = new Array<TransportInterface.Listener>();
+    private readonly simulatedNetwork = NetworkSimulator.get();
+    private readonly listeningPort: number;
+    readonly maxPayloadSize = MAX_UDP_MESSAGE_SIZE;
+
+    constructor(
+        readonly type: "udp4" | "udp6",
+        private readonly localAddress: string,
+        private readonly listeningAddress: string | undefined,
+        listeningPort?: number,
+    ) {
+        this.listeningPort = listeningPort ?? 1024 + Math.floor(Math.random() * 64511); // Random port 1024-65535
+    }
+
+    onData(listener: (netInterface: string, peerAddress: string, peerPort: number, data: Uint8Array) => void) {
+        const netListener = this.simulatedNetwork.onUdpData(this.listeningAddress, this.listeningPort, listener);
+        this.netListeners.push(netListener);
+        return netListener;
+    }
+
+    async send(host: string, port: number, data: Uint8Array) {
+        this.simulatedNetwork.sendUdp(this.localAddress, this.listeningPort, host, port, data);
+    }
+
+    async close() {
+        for (const netListener of this.netListeners) {
+            await netListener.close();
+        }
+        this.netListeners.length = 0;
+    }
+
+    async [Symbol.asyncDispose]() {
+        return this.close();
+    }
+
+    get port() {
+        return this.listeningPort;
+    }
+
+    supports(type: ChannelType, _address: string) {
+        return type === ChannelType.UDP;
+    }
+}

package/src/net/mock/NetworkSimulator.ts

@@ -0,0 +1,63 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger } from "../../log/Logger.js";
+import { singleton } from "../../util/Singleton.js";
+import { TransportInterface } from "../TransportInterface.js";
+
+const logger = Logger.get("SimulatedNetwork");
+
+export class NetworkSimulator {
+    static get = singleton(() => new NetworkSimulator());
+
+    private readonly listenersMap = new Map<string, Array<NetworkSimulator.Listener>>();
+
+    onUdpData(
+        host: string | undefined,
+        port: number,
+        listener: NetworkSimulator.Listener,
+    ): TransportInterface.Listener {
+        const ipPort = `${host ?? "*"}:${port}`;
+        let listeners = this.listenersMap.get(ipPort);
+        if (listeners === undefined) {
+            listeners = new Array<NetworkSimulator.Listener>();
+            this.listenersMap.set(ipPort, listeners);
+        }
+        listeners.push(listener);
+        return {
+            close: async () => this.offUdpData(host, port, listener),
+        };
+    }
+
+    private offUdpData(host: string | undefined, port: number, listenerToRemove: NetworkSimulator.Listener) {
+        const ipPort = `${host ?? "*"}:${port}`;
+        const listeners = this.listenersMap.get(ipPort);
+        if (listeners === undefined) return;
+        const newListeners = listeners.filter(listener => listener !== listenerToRemove);
+        if (newListeners.length === 0) {
+            this.listenersMap.delete(ipPort);
+            return;
+        }
+        this.listenersMap.set(ipPort, newListeners);
+    }
+
+    sendUdp(localAddress: string, localPort: number, remoteAddress: string, remotePort: number, data: Uint8Array) {
+        [`${remoteAddress}:${remotePort}`, `*:${remotePort}`].forEach(ipPort =>
+            this.listenersMap.get(ipPort)?.forEach(listener => {
+                try {
+                    listener(NetworkSimulator.INTERFACE_NAME, localAddress, localPort, data);
+                } catch (error) {
+                    logger.error(error);
+                }
+            }),
+        );
+    }
+}
+
+export namespace NetworkSimulator {
+    export type Listener = (netInterface: string, peerAddress: string, peerPort: number, data: Uint8Array) => void;
+    export const INTERFACE_NAME = "fakeInterface";
+}

package/src/polyfills/disposable.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// See https://github.com/tc39/proposal-explicit-resource-management
+//
+// We downlevel support for "using foo = ..." using esbuild but downleveling does not include a polyfill so we patch in
+// standin symbols here
+
+if (typeof Symbol.dispose !== "symbol") {
+    (Symbol as { dispose: symbol }).dispose = Symbol("dispose");
+    if (typeof Symbol.dispose !== "symbol") {
+        throw new Error("Symbol.dispose is undefined and polyfill installation failed");
+    }
+}
+
+if (typeof Symbol.asyncDispose !== "symbol") {
+    (Symbol as { asyncDispose: symbol }).asyncDispose = Symbol("asyncDispose");
+    if (typeof Symbol.asyncDispose !== "symbol") {
+        throw new Error("Symbol.asyncDispose is undefined and polyfill installation failed");
+    }
+}

package/src/polyfills/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import "./disposable.js";

package/src/storage/Storage.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MatterError } from "../MatterError.js";
+import { MaybePromise } from "../util/Promises.js";
+import { SupportedStorageTypes } from "./StringifyTools.js";
+
+export class StorageError extends MatterError {}
+
+/**
+ * Matter.js uses this key/value API to manage persistent state.
+ */
+export interface Storage {
+    readonly initialized: boolean;
+    initialize(): MaybePromise<void>;
+    close(): MaybePromise<void>;
+    get(contexts: string[], key: string): MaybePromise<SupportedStorageTypes | undefined>;
+    set(contexts: string[], values: Record<string, SupportedStorageTypes>): MaybePromise<void>;
+    set(contexts: string[], key: string, value: SupportedStorageTypes): MaybePromise<void>;
+    delete(contexts: string[], key: string): MaybePromise<void>;
+    keys(contexts: string[]): MaybePromise<string[]>;
+    values(contexts: string[]): MaybePromise<Record<string, SupportedStorageTypes>>;
+    contexts(contexts: string[]): MaybePromise<string[]>;
+    clearAll(contexts: string[]): MaybePromise<void>;
+}
+
+// This extra class is needed because of https://github.com/microsoft/TypeScript/issues/57905 in order
+// to have the generics typing support on the "get" method and can be removed when the TS issue is fixed
+// or we remove the legacy API.
+export abstract class MaybeAsyncStorage implements Storage {
+    abstract initialized: boolean;
+    abstract initialize(): MaybePromise<void>;
+    abstract close(): MaybePromise<void>;
+    abstract get<T extends SupportedStorageTypes>(contexts: string[], key: string): MaybePromise<T | undefined>;
+    abstract set(contexts: string[], values: Record<string, SupportedStorageTypes>): MaybePromise<void>;
+    abstract set(contexts: string[], key: string, value: SupportedStorageTypes): MaybePromise<void>;
+    abstract delete(contexts: string[], key: string): MaybePromise<void>;
+    abstract keys(contexts: string[]): MaybePromise<string[]>;
+    abstract values(contexts: string[]): MaybePromise<Record<string, SupportedStorageTypes>>;
+    abstract contexts(contexts: string[]): MaybePromise<string[]>;
+    abstract clearAll(contexts: string[]): MaybePromise<void>;
+}
+
+// This can be removed once we remove the legacy API
+export abstract class SyncStorage implements Storage {
+    abstract initialized: boolean;
+    abstract initialize(): MaybePromise<void>;
+    abstract close(): MaybePromise<void>;
+    abstract get<T extends SupportedStorageTypes>(contexts: string[], key: string): T | undefined;
+    abstract set(contexts: string[], values: Record<string, SupportedStorageTypes>): void;
+    abstract set(contexts: string[], key: string, value: SupportedStorageTypes): void;
+    abstract delete(contexts: string[], key: string): void;
+    abstract keys(contexts: string[]): string[];
+    abstract values(contexts: string[]): Record<string, SupportedStorageTypes>;
+    abstract contexts(contexts: string[]): string[];
+    abstract clearAll(contexts: string[]): void;
+}
+
+export type StorageOperationResult<S extends Storage, T = void> = S extends SyncStorage ? T : Promise<T>;