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

package/src/environment/ProcessManager.ts

@@ -0,0 +1,128 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Destructable, Environment, Logger, RuntimeService, VariableService } from "#general";
+import type { NodeJsEnvironment } from "./NodeJsEnvironment.js";
+
+const logger = Logger.get("ProcessManager");
+
+/**
+ * ProcessManager watches Node.js signals SIGINT and SIGUSR2 to terminate the Matter.js runtime and trigger Matter.js
+ * diagnostics respectively.  It sets the process exit code to 0 if the runtime completes without error and to 1 if the
+ * runtime crashes.
+ *
+ * If enabled, SIGINT will perform a soft interrupt of the runtime once.  ProcessManager will not process subsequent
+ * interrupts so they will result in forced exit if no other handler exists.
+ *
+ * {@link NodeJsEnvironment} installs a ProcessManager into the default Matter.js {@link Environment}.
+ *
+ * You can modify behavior by:
+ *
+ *   - Passing an {@link Environment} other than {@link Environment.default} to your components
+ *
+ *   - Disabling signal and exit code support with {@link VariableService} variables "runtime.signals" and
+ *     "runtime.exitcode" respectively
+ *
+ *   - Destroying ProcessManager in the default environment using {@link ProcessManager.close}
+ *
+ *   - Subclassing ProcessManager, overriding specific functionality, and installing with {@link Environment.set}
+ */
+export class ProcessManager implements Destructable {
+    protected runtime: RuntimeService;
+    #signalHandlersInstalled = false;
+
+    constructor(protected env: Environment) {
+        this.runtime = env.get(RuntimeService);
+
+        this.runtime.started.on(this.startListener);
+        this.runtime.stopped.on(this.stopListener);
+        this.runtime.crashed.on(this.crashListener);
+
+        if (this.hasUnhandledErrorSupport) {
+            process.addListener("uncaughtExceptionMonitor", event => {
+                Logger.reportUnhandledError(event);
+            });
+        }
+    }
+
+    close() {
+        this.runtime.started.off(this.startListener);
+        this.runtime.stopped.off(this.stopListener);
+        this.runtime.crashed.off(this.crashListener);
+        this.#ignoreSignals();
+    }
+
+    [Symbol.dispose]() {
+        this.close();
+    }
+
+    protected get hasSignalSupport() {
+        return this.env.vars.get("runtime.signals", true);
+    }
+
+    protected get hasExitCodeSupport() {
+        return this.env.vars.get("runtime.exitcode", true);
+    }
+
+    protected get hasUnhandledErrorSupport() {
+        return this.env.vars.get("runtime.unhandlederrors", true);
+    }
+
+    protected startListener = () => {
+        this.env.vars.use(() => {
+            if (this.hasSignalSupport) {
+                if (this.#signalHandlersInstalled) {
+                    return;
+                }
+                process.on("SIGINT", this.interruptHandler);
+                process.on("SIGTERM", this.interruptHandler);
+                process.on("SIGUSR2", this.diagnosticHandler);
+                process.on("exit", this.exitHandler);
+            } else {
+                this.#ignoreSignals();
+            }
+        });
+    };
+
+    protected stopListener = () => {
+        this.#ignoreSignals();
+
+        if (this.hasExitCodeSupport && process.exitCode === undefined) {
+            process.exitCode = 0;
+        }
+    };
+
+    protected crashListener = () => {
+        if (this.hasExitCodeSupport) {
+            process.exitCode = 1;
+        }
+    };
+
+    protected interruptHandler = (signal: string) => {
+        process.off(signal, this.interruptHandler);
+        this.runtime.cancel();
+    };
+
+    protected exitHandler = () => {
+        if (process.exitCode === 13) {
+            logger.error("Internal error: Premature process exit because ongoing work has stalled");
+        }
+    };
+
+    protected diagnosticHandler = () => {
+        this.env.diagnose();
+    };
+
+    #ignoreSignals() {
+        if (this.#signalHandlersInstalled) {
+            process.off("SIGINT", this.interruptHandler);
+            process.off("SIGTERM", this.interruptHandler);
+            process.off("SIGUSR2", this.diagnosticHandler);
+            process.off("exit", this.exitHandler);
+            this.#signalHandlersInstalled = false;
+        }
+    }
+}

package/src/environment/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import "./register.js";
+export * from "./NodeJsActionTracer.js";
+export * from "./NodeJsEnvironment.js";
+export * from "./ProcessManager.js";

package/src/environment/register.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Environment } from "#general";
+import { NodeJsEnvironment } from "./NodeJsEnvironment.js";
+
+Environment.default = NodeJsEnvironment();

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./behavior/index.js";
+export * from "./crypto/index.js";
+export * from "./environment/index.js";
+export * from "./log/index.js";
+export * from "./net/index.js";
+export * from "./storage/index.js";

package/src/log/FileLogger.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { LogLevel } from "#general";
+import { open } from "fs/promises";
+
+/**
+ * Creates a file based logger to append to the given path.
+ * The file is opened on start and closed when the process shuts down.
+ * Errors are logged to the console.
+ */
+export async function createFileLogger(path: string) {
+    const fileHandle = await open(path, "a");
+    const writer = fileHandle.createWriteStream();
+    process.on(
+        "beforeExit",
+        () => void fileHandle.close().catch(err => err && console.error(`Failed to close log file: ${err}`)),
+    );
+
+    return (_level: LogLevel, formattedLog: string) => {
+        try {
+            writer.write(`${formattedLog}\n`);
+        } catch (error) {
+            console.error(`Failed to write to log file: ${error}`);
+        }
+    };
+}

package/src/log/index.ts

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

package/src/net/NodeJsNetwork.ts

@@ -0,0 +1,157 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    Cache,
+    InterfaceType,
+    isIPv6,
+    Logger,
+    Network,
+    NetworkError,
+    NetworkInterface,
+    NetworkInterfaceDetails,
+    onSameNetwork,
+    UdpChannel,
+    UdpChannelOptions,
+} from "#general";
+import { NetworkInterfaceInfo, networkInterfaces } from "os";
+import { NodeJsUdpChannel } from "./NodeJsUdpChannel.js";
+
+const logger = Logger.get("NetworkNode");
+
+export class NodeJsNetwork extends Network {
+    static getMulticastInterfaceIpv4(netInterface: string): string | undefined {
+        const netInterfaceInfo = networkInterfaces()[netInterface];
+        if (netInterfaceInfo === undefined) throw new NetworkError(`Unknown interface: ${netInterface}`);
+        for (const { address, family } of netInterfaceInfo) {
+            if (family === "IPv4") {
+                return address;
+            }
+        }
+        return undefined;
+    }
+
+    static getMembershipMulticastInterfaces(netInterface: string | undefined, ipv4: boolean): (string | undefined)[] {
+        if (ipv4) {
+            return [undefined];
+        } else {
+            let networkInterfaceEntries = Object.entries(networkInterfaces());
+            if (netInterface !== undefined) {
+                networkInterfaceEntries = networkInterfaceEntries.filter(([name]) => name === netInterface);
+            }
+            const multicastInterfaces = networkInterfaceEntries.flatMap(([netInterface, netInterfaceInfo]) => {
+                if (netInterfaceInfo === undefined) return [];
+                const zone = this.getNetInterfaceZoneIpv6Internal(netInterface, netInterfaceInfo);
+                return zone === undefined ? [] : [`::%${zone}`];
+            });
+            if (multicastInterfaces.length === 0) {
+                logger.warn(
+                    `No IPv6 multicast interface found${
+                        netInterface !== undefined ? ` for interface ${netInterface}` : ""
+                    }.`,
+                );
+            }
+            return multicastInterfaces;
+        }
+    }
+
+    static getNetInterfaceZoneIpv6(netInterface: string): string | undefined {
+        const netInterfaceInfo = networkInterfaces()[netInterface];
+        if (netInterfaceInfo === undefined) throw new NetworkError(`Unknown interface: ${netInterface}`);
+        return this.getNetInterfaceZoneIpv6Internal(netInterface, netInterfaceInfo);
+    }
+
+    static getNetInterfaceForIp(ip: string) {
+        // Finding the local interface on the same interface is complex and won't change
+        // So let's cache the results for 5mn
+        return this.netInterfaces.get(ip);
+    }
+
+    private static readonly netInterfaces = new Cache<string | undefined>(
+        "Network interface",
+        (ip: string) => this.getNetInterfaceForRemoteAddress(ip),
+        5 * 60 * 1000 /* 5mn */,
+    );
+
+    override async close() {
+        await NodeJsNetwork.netInterfaces.close();
+    }
+
+    private static getNetInterfaceForRemoteAddress(ip: string) {
+        if (ip.includes("%")) {
+            // IPv6 address with scope
+            return ip.split("%")[1];
+        } else {
+            const interfaces = networkInterfaces();
+            for (const name in interfaces) {
+                const netInterfaces = interfaces[name] as NetworkInterfaceInfo[];
+                for (const { address, netmask } of netInterfaces) {
+                    if (onSameNetwork(ip, address, netmask)) {
+                        return this.getNetInterfaceZoneIpv6Internal(name, netInterfaces);
+                    }
+                }
+            }
+            if (isIPv6(ip)) {
+                if (ip.startsWith("fd")) {
+                    // IPv6 address is an ULA
+                    return ""; // consider it as being ok and using the "Default interface"
+                }
+            }
+            return undefined;
+        }
+    }
+
+    private static getNetInterfaceZoneIpv6Internal(
+        netInterface: string,
+        netInterfaceInfos: NetworkInterfaceInfo[] | undefined,
+    ): string | undefined {
+        if (process.platform !== "win32") {
+            return netInterface;
+        }
+        if (netInterfaceInfos === undefined) return undefined;
+        return netInterfaceInfos
+            .find(({ address, family }) => family === "IPv6" && address.startsWith("fe80::"))
+            ?.scopeid?.toString();
+    }
+
+    /**
+     * Get all network interfaces.
+     * The optional configuration parameter allows to map interface names to types if this mapping is known.
+     * Each network interface which has no mapped type is returned as Ethernet for now.
+     *
+     * @param configuration - An array of objects with the name and type properties.
+     */
+    getNetInterfaces(configuration: NetworkInterface[] = []): NetworkInterface[] {
+        const result = new Array<NetworkInterface>();
+        const interfaces = networkInterfaces();
+        for (const name in interfaces) {
+            const netInterfaces = interfaces[name] as NetworkInterfaceInfo[];
+            if (netInterfaces.length === 0) continue;
+            if (netInterfaces[0].internal) continue;
+            let type = InterfaceType.Ethernet;
+            if (configuration.length > 0) {
+                const nameType = configuration.find(({ name: mapName }) => name === mapName);
+                if (nameType !== undefined && nameType.type !== undefined) {
+                    type = nameType.type;
+                }
+            }
+            result.push({ name, type });
+        }
+        return result;
+    }
+
+    getIpMac(netInterface: string): NetworkInterfaceDetails | undefined {
+        const netInterfaceInfo = networkInterfaces()[netInterface];
+        if (netInterfaceInfo === undefined) return undefined;
+        const ipV4 = netInterfaceInfo.filter(({ family }) => family === "IPv4").map(({ address }) => address);
+        const ipV6 = netInterfaceInfo.filter(({ family }) => family === "IPv6").map(({ address }) => address);
+        return { mac: netInterfaceInfo[0].mac, ipV4, ipV6 };
+    }
+
+    override createUdpChannel(options: UdpChannelOptions): Promise<UdpChannel> {
+        return NodeJsUdpChannel.create(options);
+    }
+}

package/src/net/NodeJsUdpChannel.ts

@@ -0,0 +1,179 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    ChannelType,
+    Diagnostic,
+    isIPv4,
+    isIPv6,
+    Logger,
+    MAX_UDP_MESSAGE_SIZE,
+    NetworkError,
+    UdpChannel,
+    UdpChannelOptions,
+} from "#general";
+import { RetransmissionLimitReachedError } from "#protocol";
+import * as dgram from "dgram";
+import { NodeJsNetwork } from "./NodeJsNetwork.js";
+
+const logger = Logger.get("UdpChannelNode");
+
+function createDgramSocket(host: string | undefined, port: number | undefined, options: dgram.SocketOptions) {
+    const socket = dgram.createSocket(options);
+    return new Promise<dgram.Socket>((resolve, reject) => {
+        const handleBindError = (error: Error) => {
+            try {
+                socket.close();
+            } catch (error) {
+                logger.debug("Error on closing socket", error);
+            }
+            reject(error);
+        };
+        socket.on("error", handleBindError);
+        socket.bind(port, host, () => {
+            const { address: localHost, port: localPort } = socket.address();
+            logger.debug(
+                "Socket created and bound ",
+                Diagnostic.dict({
+                    remoteAddress: `${host}:${port}`,
+                    localAddress: `${localHost}:${localPort}`,
+                }),
+            );
+            socket.removeListener("error", handleBindError);
+            socket.on("error", error => logger.error(error));
+            resolve(socket);
+        });
+    });
+}
+
+export class NodeJsUdpChannel implements UdpChannel {
+    static async create({
+        listeningPort,
+        type,
+        listeningAddress,
+        netInterface,
+        membershipAddresses,
+    }: UdpChannelOptions) {
+        const socketOptions: dgram.SocketOptions = { type, reuseAddr: true };
+        if (type === "udp6") {
+            socketOptions.ipv6Only = true;
+        }
+        const socket = await createDgramSocket(listeningAddress, listeningPort, socketOptions);
+        socket.setBroadcast(true);
+        let netInterfaceZone: string | undefined;
+        if (netInterface !== undefined) {
+            netInterfaceZone = NodeJsNetwork.getNetInterfaceZoneIpv6(netInterface);
+            let multicastInterface: string | undefined;
+            if (type === "udp4") {
+                multicastInterface = NodeJsNetwork.getMulticastInterfaceIpv4(netInterface);
+                if (multicastInterface === undefined) {
+                    throw new NetworkError(`No IPv4 addresses on interface: ${netInterface}`);
+                }
+            } else {
+                if (netInterfaceZone === undefined) {
+                    throw new NetworkError(`No IPv6 addresses on interface: ${netInterface}`);
+                }
+                multicastInterface = `::%${netInterfaceZone}`;
+            }
+            logger.debug(
+                "Initialize multicast",
+                Diagnostic.dict({
+                    address: `${multicastInterface}:${listeningPort}`,
+                    interface: netInterface,
+                    type: type,
+                }),
+            );
+            socket.setMulticastInterface(multicastInterface);
+        }
+        if (membershipAddresses !== undefined) {
+            const multicastInterfaces = NodeJsNetwork.getMembershipMulticastInterfaces(netInterface, type === "udp4");
+            for (const address of membershipAddresses) {
+                for (const multicastInterface of multicastInterfaces) {
+                    try {
+                        socket.addMembership(address, multicastInterface);
+                    } catch (error) {
+                        logger.warn(
+                            `Error adding membership for address ${address}${
+                                multicastInterface ? ` with interface ${multicastInterface}` : ""
+                            }: ${error}`,
+                        );
+                    }
+                }
+            }
+        }
+        return new NodeJsUdpChannel(type, socket, netInterfaceZone);
+    }
+
+    readonly maxPayloadSize = MAX_UDP_MESSAGE_SIZE;
+
+    constructor(
+        private readonly type: "udp4" | "udp6",
+        private readonly socket: dgram.Socket,
+        private readonly netInterface?: string,
+    ) {}
+
+    onData(listener: (netInterface: string, peerAddress: string, peerPort: number, data: Uint8Array) => void) {
+        const messageListener = (data: Uint8Array, { address, port }: dgram.RemoteInfo) => {
+            const netInterface = this.netInterface ?? NodeJsNetwork.getNetInterfaceForIp(address);
+            if (netInterface === undefined) return;
+            listener(netInterface, address, port, data);
+        };
+
+        this.socket.on("message", messageListener);
+        return {
+            close: async () => {
+                this.socket.removeListener("message", messageListener);
+            },
+        };
+    }
+
+    async send(host: string, port: number, data: Uint8Array) {
+        return new Promise<void>((resolve, reject) => {
+            this.socket.send(data, port, host, error => {
+                if (error !== null) {
+                    const netError =
+                        error instanceof Error && "code" in error && error.code === "EHOSTUNREACH"
+                            ? new RetransmissionLimitReachedError(error.message)
+                            : new NetworkError(error.message);
+                    netError.stack = error.stack;
+                    reject(netError);
+                    return;
+                }
+                resolve();
+            });
+        });
+    }
+
+    async close() {
+        try {
+            this.socket.close();
+        } catch (error) {
+            logger.debug("Error on closing socket", error);
+        }
+    }
+
+    get port() {
+        return this.socket.address().port;
+    }
+
+    supports(type: ChannelType, address?: string) {
+        if (type !== ChannelType.UDP) {
+            return false;
+        }
+
+        if (address === undefined) {
+            return true;
+        }
+
+        // TODO - we currently only discriminate based on protocol type.  We should also determine whether the address subnet is correct
+
+        if (this.type === "udp4") {
+            return isIPv4(address);
+        }
+
+        return isIPv6(address);
+    }
+}

package/src/net/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import "./register.js";
+export * from "./NodeJsNetwork.js";
+export * from "./NodeJsUdpChannel.js";

package/src/net/register.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Network, NoProviderError, singleton } from "#general";
+import { NodeJsNetwork } from "./NodeJsNetwork.js";
+
+// Check if Network singleton is already registered and auto register if not
+try {
+    Network.get();
+} catch (error) {
+    NoProviderError.accept(error);
+
+    Network.get = singleton(() => new NodeJsNetwork());
+
+    // Ensure network gets cleaned up on exit
+    process.on("beforeExit", () => void Network.get().close());
+}