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

package/src/behavior/system/product-description/ProductDescriptionServer.ts

@@ -5,6 +5,7 @@
  */
 
 import { Agent } from "#endpoint/Agent.js";
+import { EndpointType } from "#endpoint/type/EndpointType.js";
 import { AggregatorDt, BridgedNodeDt, DeviceClassification, RootNodeDt } from "#model";
 import { DeviceTypeId, ProductDescription, VendorId } from "#types";
 import { BasicInformationBehavior } from "../../../behaviors/basic-information/BasicInformationBehavior.js";
@@ -40,7 +41,7 @@ export class ProductDescriptionServer extends Behavior {
     }
 
     #setDeviceType() {
-        if (this.state.deviceType !== ProductDescriptionServer.UNKNOWN_DEVICE_TYPE) {
+        if (this.state.deviceType !== EndpointType.UNKNOWN_DEVICE_TYPE) {
             return;
         }
 
@@ -63,7 +64,8 @@ export class ProductDescriptionServer extends Behavior {
 }
 
 export namespace ProductDescriptionServer {
-    export const UNKNOWN_DEVICE_TYPE = DeviceTypeId(-1, false);
+    export const UNKNOWN_VENDOR_ID = VendorId(-1, false);
+    export const UNKNOWN_PRODUCT_ID = -1;
 
     export class State implements ProductDescription {
         /**
@@ -74,17 +76,17 @@ export namespace ProductDescriptionServer {
         /**
          * The device type for commissioning announcements.
          */
-        deviceType: DeviceTypeId = UNKNOWN_DEVICE_TYPE;
+        deviceType: DeviceTypeId = EndpointType.UNKNOWN_DEVICE_TYPE;
 
         /**
          * The vendor ID for commissioning announcements.
          */
-        vendorId = VendorId(-1, false);
+        vendorId = UNKNOWN_VENDOR_ID;
 
         /**
          * The product ID for commissioning announcements.
          */
-        productId = -1;
+        productId = UNKNOWN_PRODUCT_ID;
     }
 }
 

package/src/behavior/system/remote/RemoteInterface.ts

@@ -0,0 +1,119 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { AppAddress, BasicMultiplex, ImplementationError, Logger } from "#general";
+import type { ServerNode } from "#node/ServerNode.js";
+import { ApiPath } from "./api/ApiPath.js";
+
+const logger = Logger.get("RemoteAdapter");
+
+/**
+ * An implementation of a non-Matter network protocol for accessing a {@link ServerNode}.
+ */
+export abstract class RemoteInterface {
+    #node: ServerNode;
+    #address: AppAddress;
+    #abort = new AbortController();
+    #root: ApiPath;
+    #workers = new BasicMultiplex();
+
+    constructor(node: ServerNode, address: AppAddress) {
+        if (address.appProtocol !== (this.constructor as unknown as RemoteInterface.Type).protocol) {
+            throw new ImplementationError(
+                `API endpoint type ${this.constructor.name} does not support address ${address}`,
+            );
+        }
+        this.#node = node;
+        this.#address = address;
+        this.#root = new ApiPath(address);
+    }
+
+    get root() {
+        return this.#root;
+    }
+
+    get env() {
+        return this.#node.env;
+    }
+
+    get node() {
+        return this.#node;
+    }
+
+    get address() {
+        return this.#address;
+    }
+
+    get isAborted() {
+        return this.#abort.signal.aborted;
+    }
+
+    get abort() {
+        return this.#abort.signal;
+    }
+
+    static async create<This extends new (node: ServerNode, address: AppAddress) => RemoteInterface>(
+        this: This,
+        node: ServerNode,
+        address: AppAddress,
+    ) {
+        const instance = new this(node, address);
+        try {
+            await instance.start();
+        } catch (e) {
+            await instance.close();
+            throw e;
+        }
+        return instance;
+    }
+
+    async close(): Promise<void> {
+        if (this.isAborted) {
+            return;
+        }
+
+        this.#abort.abort();
+
+        try {
+            await this.stop();
+        } catch (e) {
+            logger.error(`Error terminating API endpoint ${this.address}`);
+        }
+    }
+
+    protected assertProtocol(appProtocol: string) {
+        if (this.address.appProtocol !== appProtocol) {
+            throw new ImplementationError(
+                `Invalid protocol ${this.address} for API endpoin type ${this.constructor.name}`,
+            );
+        }
+    }
+
+    protected addWorker(worker: Promise<void>, description: string) {
+        this.#workers.add(worker, description);
+    }
+
+    static protocol = "";
+
+    /**
+     * Initialize and begin handling requests to the interface.
+     */
+    protected abstract start(): Promise<void>;
+
+    /**
+     * Stop servicing requests.  Called on close.  The default implementation just waits for any workers to complete.
+     */
+    protected async stop(): Promise<void> {
+        await this.#workers.close();
+    }
+}
+
+export namespace RemoteInterface {
+    export interface Type {
+        protocol: string;
+        create(node: ServerNode, address: AppAddress): Promise<RemoteInterface>;
+    }
+}

package/src/behavior/system/remote/RemoteServer.ts

@@ -0,0 +1,132 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Behavior } from "#behavior/Behavior.js";
+import { EndpointInitializer } from "#endpoint/index.js";
+import { AppAddress, ImplementationError, InternalError } from "#general";
+import { DatatypeModel, FieldElement } from "#model";
+import type { ServerNode } from "#node/ServerNode.js";
+import { ServerEndpointInitializer } from "#node/index.js";
+import { RemoteInterface } from "./RemoteInterface.js";
+
+/**
+ * Base class for {@link Behavior}s that enable remote access to a {@link ServerNode} via a non-Matter API.
+ *
+ * Each protocol supported by Matter.js implements a subclass of {@link RemoteServer} and {@link RemoteInterface}.
+ *
+ * The {@link RemoteServer} provides a convenient interface for adding a protocol to a {@link ServerNode}.  The The
+ * {@link RemoteInterface} implements the actual protocol.
+ *
+ * For greater control you may instantiate and manage {@link RemoteInterface} separately from {@link RemoteServer}. To
+ * implement your own protocol you may extend the server implementations provided by matter.js, or create a new protocol
+ * implementation by subclassing {@link RemoteInterface} yourself.
+ */
+export abstract class RemoteServer extends Behavior {
+    static override readonly early = true;
+
+    static interfaceType: RemoteInterface.Type;
+
+    declare internal: RemoteServer.Internal;
+    declare state: RemoteServer.State;
+
+    override async initialize() {
+        if (!(this.env.get(EndpointInitializer) instanceof ServerEndpointInitializer)) {
+            throw new ImplementationError("Remote server is not installed in a ServerNode");
+        }
+
+        this.reactTo((this.endpoint as ServerNode).lifecycle.online, this.#start);
+        this.reactTo((this.endpoint as ServerNode).lifecycle.offline, this.#onOffline);
+
+        // If configured to allow interfaces when offline, we must manually ensure we aren't active during node
+        // destruction
+        this.reactTo((this.endpoint as ServerNode).lifecycle.destroying, this.#stop);
+
+        if (this.state.allowOfflineUse) {
+            await this.#start();
+        }
+    }
+
+    override [Symbol.asyncDispose]() {
+        return this.#stop();
+    }
+
+    async #start() {
+        if (!this.state.enabled || this.internal.interface) {
+            return;
+        }
+
+        const interfaceType = (this.constructor as typeof RemoteServer).interfaceType;
+        if (typeof (interfaceType as any) !== "function") {
+            throw new InternalError(`Remote server ${this.constructor.name} does not define a remote interface`);
+        }
+
+        const address = new AppAddress(this.state.address);
+        const intf = await interfaceType.create(this.endpoint as ServerNode, address);
+
+        this.internal.interface = intf;
+    }
+
+    async #stop() {
+        const { interface: intf } = this.internal;
+        if (!intf) {
+            return;
+        }
+
+        this.internal.interface = undefined;
+        await intf.close();
+    }
+
+    async #onOffline() {
+        if (!this.state.allowOfflineUse) {
+            await this.#stop();
+        }
+    }
+
+    static override readonly schema = new DatatypeModel(
+        {
+            name: "ApiState",
+            type: "struct",
+        },
+
+        FieldElement({ name: "address", type: "string" }),
+        FieldElement({ name: "enabled", type: "bool" }),
+        FieldElement({ name: "allowOfflineUse", type: "bool" }),
+    );
+}
+
+export namespace RemoteServer {
+    export class Internal {
+        interface?: RemoteInterface;
+    }
+
+    export class State {
+        /**
+         * The public address at which the service endpoint is accessible.
+         *
+         * The address is a URL.  See subclasses for supported protocols.  An "s" suffix indicates standard TLS support.
+         * The "+unix" suffix indicates that the hostname is a URL encoded path to a UNIX socket.  The socket path may
+         * be absolute or relative to the node's storage root.
+         *
+         * The path portion of the URL generally acts as a namespace prefix for the relevant protocol implementation.
+         * Matter.js replaces the special token `{node}` in the URL with the {@link ServerNode.id}.  This allows for
+         * multiple nodes to participate in a protocol in separate namespaces.
+         */
+        address = "";
+
+        /**
+         * Set to false to disable this service.
+         */
+        enabled = true;
+
+        /**
+         * By default the HTTP endpoint is available as soon as the {@link Node} initializes.
+         *
+         * If you set this to false, the HTTP endpoint is only available when the {@link Node}'s Matter networking is
+         * also online.
+         */
+        allowOfflineUse = true;
+    }
+}

package/src/behavior/system/remote/api/Api.ts

@@ -0,0 +1,179 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Agent } from "#endpoint/Agent.js";
+import { Abort, asError, Diagnostic, InternalError, Logger } from "#general";
+import { Node } from "#node/Node.js";
+import { ServerNode } from "#node/ServerNode.js";
+import { StatusResponse, StatusResponseError } from "#types";
+import { ApiPath } from "./ApiPath.js";
+import { ApiResource } from "./ApiResource.js";
+import { LocalResponse } from "./LocalResponse.js";
+import { RemoteRequest } from "./RemoteRequest.js";
+import { RemoteResponse } from "./RemoteResponse.js";
+import { EndpointResource } from "./resources/EndpointResource.js";
+import { NodeResource } from "./resources/NodeResource.js";
+import { ServerNodeResource } from "./resources/ServerNodeResource.js";
+
+const loggers = new Map<string, Logger>();
+
+/**
+ * Common substrate for the network APIs.
+ *
+ * The logical API covers RPC and read/write semantics.  These involve a "/"-separated path and a logical operation
+ * (read, write, invoke, etc.)
+ *
+ * This namespace provides utilities for mapping paths to resources and taking action on the resource.
+ */
+export namespace Api {
+    /**
+     * Retrieve the {@link ApiResource} for a path.
+     */
+    export async function resourceFor(agent: Agent, path: ApiPath): Promise<ApiResource | void> {
+        let item;
+        if ("peers" in agent.endpoint) {
+            item = new ServerNodeResource(agent, undefined);
+        } else if (agent.endpoint instanceof Node) {
+            item = new NodeResource(agent, undefined);
+        } else {
+            item = new EndpointResource(agent, undefined);
+        }
+
+        const breadcrumb: ApiResource[] = [item];
+
+        for (const segment of path) {
+            const parent = breadcrumb[breadcrumb.length - 1];
+
+            const item = await parent.childFor(segment);
+            if (!item) {
+                return;
+            }
+
+            breadcrumb.push(item);
+        }
+
+        return breadcrumb[breadcrumb.length - 1];
+    }
+
+    export function log(level: "error" | "info", facility: string, id: string | undefined, ...message: unknown[]) {
+        let logger = loggers.get(facility);
+        if (!logger) {
+            loggers.set(facility, (logger = Logger.get(facility)));
+        }
+        logger[level](Diagnostic.via(id ?? "(anon)"), message);
+    }
+
+    export function logRequest(facility: string, id: string | undefined, method: string, target: string) {
+        log("info", facility, id, "«", Diagnostic.strong(method), target);
+    }
+
+    export function logResponse(facility: string, response: RemoteResponse) {
+        const message = Array<unknown>("»", RemoteResponse.describe(response));
+        let level: "error" | "info";
+        switch (response.kind) {
+            case "error":
+                message.push(Diagnostic.squash("[", Diagnostic.strong(response.code), "]"));
+                message.push(response.message);
+                level = "error";
+                break;
+
+            default:
+                level = "info";
+                break;
+        }
+        log(level, facility, response.id, message);
+    }
+
+    /**
+     * Execute a {@link RemoteRequest}.
+     */
+    export async function execute(
+        facility: string,
+        node: ServerNode,
+        request: RemoteRequest,
+        signal: Abort.Signal,
+    ): Promise<LocalResponse> {
+        const { target, method, id } = request;
+
+        logRequest(facility, id, method, target);
+
+        try {
+            const message = await node.act("remote", async (agent): Promise<LocalResponse> => {
+                const item = await resourceFor(agent, new ApiPath(target));
+                if (item === undefined) {
+                    throw new StatusResponse.NotFoundError(`Target "${target}" not found`);
+                }
+
+                switch (method) {
+                    case "read":
+                        const value = item.read();
+                        if (value === undefined) {
+                            throw new StatusResponse.UnsupportedReadError(`Target "${target}" is not readable`);
+                        }
+                        value.convertToJson();
+
+                        return {
+                            kind: "value",
+                            id,
+
+                            // TODO - consider handling serialization here (in agent context) so copy is unnecessary
+                            value,
+                        };
+
+                    case "write":
+                        item.write({ js: request.value });
+                        return { kind: "ok", id };
+
+                    case "add":
+                        item.add({ js: item.value });
+                        return { kind: "ok", id };
+
+                    case "delete":
+                        item.delete();
+                        return { kind: "ok", id };
+
+                    case "invoke": {
+                        const value = await item.invoke({ js: request.parameters });
+                        if (value?.js === undefined || value?.js === null) {
+                            return { kind: "ok", id };
+                        }
+                        value.convertToJson();
+                        return { id, kind: "value", value };
+                    }
+
+                    case "subscribe": {
+                        const options = { ...request } as Record<string, unknown>;
+                        for (const field of ["target", "id", "method"]) {
+                            delete options[field];
+                        }
+                        const stream = item.subscribe(signal, {
+                            id,
+                            js: options,
+                        });
+                        return { kind: "subscription", id, stream };
+                    }
+                }
+            });
+
+            return message;
+        } catch (error) {
+            return errorResponseOf(facility, id, error);
+        }
+    }
+
+    export function errorResponseOf(facility: string, id: string | undefined, error: unknown): LocalResponse {
+        error = asError(error);
+
+        // User-facing message
+        if (error instanceof StatusResponseError) {
+            return { kind: "error", id, error };
+        }
+
+        // Internal error
+        log("error", facility, id, "Internal error:", error);
+        return { kind: "error", id, error: new InternalError() };
+    }
+}

package/src/behavior/system/remote/api/ApiPath.ts

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { AppAddress, isDeepEqual } from "#general";
+
+/**
+ * A logical path in the API.
+ */
+export class ApiPath {
+    #segments = Array<string>();
+
+    /**
+     * Create a new path from:
+     *
+     * * An {@link AppAddress#pathname}
+     * * A text path, delimited with "/" with URL encoded segments
+     * * An array of decoded segments
+     *
+     * Ignores path segments that are empty or ".".  ".." resolves up one level.
+     *
+     * So generally normal UNIX/URL semantics.
+     */
+    constructor(path: AppAddress | string | string[]) {
+        if (path instanceof URL) {
+            path = path.pathname;
+        }
+
+        if (!Array.isArray(path)) {
+            path = path.split("/").map(decodeURIComponent);
+        }
+
+        for (const segment of path) {
+            if (segment === "" || segment === ".") {
+                continue;
+            }
+
+            if (segment === "..") {
+                this.#segments.pop();
+                continue;
+            }
+
+            this.#segments.push(segment);
+        }
+    }
+
+    get isEmpty() {
+        return !this.#segments.length;
+    }
+
+    [Symbol.iterator]() {
+        return this.#segments[Symbol.iterator]();
+    }
+
+    slice(start?: number, end?: number) {
+        return new ApiPath(this.#segments.slice(start, end));
+    }
+
+    at(path: AppAddress | string | string[]) {
+        if (this.isEmpty) {
+            return new ApiPath(path);
+        }
+
+        if (path instanceof URL) {
+            path = path.pathname;
+        }
+
+        if (Array.isArray(path)) {
+            path = path.map(encodeURIComponent).join("/");
+        }
+
+        if (path.startsWith("/")) {
+            return new ApiPath(path);
+        }
+
+        // Note - parse combined path as a string so that ".." resolves relative to myself if necessary
+        return new ApiPath(`${this.toString()}/${path}`);
+    }
+
+    toString() {
+        return `${this.#segments.map(encodeURIComponent).join("/")}`;
+    }
+
+    includes(other: ApiPath) {
+        return isDeepEqual(this.#segments, other.slice(0, this.#segments.length).#segments);
+    }
+
+    subpathFor(other: ApiPath) {
+        if (!this.#segments.length) {
+            return other;
+        }
+
+        if (!this.includes(other)) {
+            return undefined;
+        }
+
+        return other.slice(this.#segments.length);
+    }
+}