@matter/node 0.16.0-alpha.0-20251004-92135c7df → 0.16.0-alpha.0-20251011-d8942d7d5

package/src/behavior/system/remote/api/resources/CommandResource.ts

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Behavior } from "#behavior/Behavior.js";
+import { ValueSupervisor } from "#behavior/supervision/ValueSupervisor.js";
+import { camelize, decamelize, ImplementationError, NotImplementedError } from "#general";
+import { CommandModel } from "#model";
+import { ApiResource } from "../ApiResource.js";
+import { Envelope } from "../Envelope.js";
+
+/**
+ * API item for commands.
+ */
+export class CommandResource extends ApiResource {
+    #behavior: Behavior;
+    supervisor: ValueSupervisor;
+
+    override readonly isInvocable = true;
+
+    constructor(parent: ApiResource, behavior: Behavior, schema: CommandModel) {
+        super(parent);
+        this.#behavior = behavior;
+        this.supervisor = this.supervisorFor(schema);
+    }
+
+    override get schema() {
+        return this.supervisor.schema as CommandModel;
+    }
+
+    get id() {
+        return decamelize(this.schema.name);
+    }
+
+    get dataModelPath() {
+        return this.parent!.dataModelPath.at(this.id);
+    }
+
+    override get valueKind(): ApiResource.Kind {
+        return "command";
+    }
+
+    get value() {
+        return undefined;
+    }
+
+    override async invoke(request?: Envelope.Data) {
+        let input = new Envelope({ supervisor: this.supervisor, ...request });
+        if (input.js === undefined || input.js === null) {
+            // The command validator always expects an object even if empty
+            input = new Envelope({ supervisor: this.supervisor, js: {} });
+        }
+
+        // Method must exist on behavior or we cannot invoke
+        const name = camelize(this.id);
+        const method = (this.#behavior as unknown as Record<string, undefined | ((...args: unknown[]) => unknown)>)[
+            name
+        ];
+        if (typeof method !== "function") {
+            throw new NotImplementedError();
+        }
+
+        // Validate input
+        input.validate();
+
+        // Invoke
+        const result = await method.call(this.#behavior, input.js);
+
+        // If there is no response schema, do not return an envelope
+        const responseSchema = this.schema.responseModel;
+        if (!responseSchema) {
+            return;
+        }
+
+        // Create and validate result
+        const output = new Envelope({ supervisor: this.supervisorFor(responseSchema), js: result });
+        try {
+            output.validate();
+        } catch (e) {
+            // If output validation fails it is an internal error
+            const error = new ImplementationError("Command output validation failed");
+            error.cause = e;
+            throw error;
+        }
+
+        // Done
+        return output;
+    }
+}

package/src/behavior/system/remote/api/resources/EndpointContainerResource.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ApiResource } from "../ApiResource.js";
+import type { EndpointResource } from "./EndpointResource.js";
+
+/**
+ * API item for collections of endpoints.
+ */
+export class EndpointContainerResource extends ApiResource {
+    readonly id: string;
+    readonly #list: () => string[];
+    readonly #find: (path: string) => ApiResource | undefined;
+    declare readonly parent: EndpointResource;
+    supervisor: undefined;
+    readonly valueKind: ApiResource.Kind = "index";
+
+    constructor(
+        parent: EndpointResource,
+        id: string,
+        list: () => string[],
+        find: (path: string) => ApiResource | undefined,
+    ) {
+        super(parent);
+
+        this.id = id;
+        this.#list = list;
+        this.#find = find;
+    }
+
+    get dataModelPath() {
+        return this.parent.dataModelPath.at(this.id);
+    }
+
+    get value() {
+        return this.#list();
+    }
+
+    override async childFor(id: string) {
+        return this.#find(id);
+    }
+}

package/src/behavior/system/remote/api/resources/EndpointResource.ts

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Agent } from "#endpoint/Agent.js";
+import { camelize } from "#general";
+import { ApiResource } from "../ApiResource.js";
+import { BehaviorResource } from "./BehaviorResource.js";
+import { EndpointContainerResource } from "./EndpointContainerResource.js";
+
+/**
+ * API item for endpoints.
+ *
+ * Direct descendents are either behaviors or collections, represented by {@link BehaviorResource} and
+ * {@link EndpointContainerResource} respectively.
+ */
+export class EndpointResource extends ApiResource {
+    readonly agent: Agent;
+    readonly supervisor: undefined;
+
+    constructor(agent: Agent, parent: undefined | ApiResource) {
+        super(parent);
+        this.agent = agent;
+    }
+
+    get valueKind(): ApiResource.Kind {
+        return "endpoint";
+    }
+
+    get id() {
+        return this.agent.endpoint.id;
+    }
+
+    get dataModelPath() {
+        return this.agent.endpoint.path;
+    }
+
+    override get value() {
+        return this.agent.endpoint.state;
+    }
+
+    override async childFor(name: string): Promise<ApiResource | void> {
+        if (name === "parts") {
+            return new EndpointContainerResource(
+                this,
+                "parts",
+                () => this.agent.endpoint.parts.map(part => part.id),
+                name => {
+                    const part = this.agent.endpoint.parts.get(name);
+                    if (part) {
+                        return new EndpointResource(part.agentFor(this.agent.context), this);
+                    }
+                },
+            );
+        }
+
+        name = camelize(name);
+
+        const { supported } = this.agent.endpoint.behaviors;
+        if (name in supported) {
+            const type = supported[name];
+
+            const behavior = this.agent.get(type);
+
+            // A behavior must have schema to be publicly accessible
+            if (behavior.type.schema === undefined) {
+                return;
+            }
+
+            return new BehaviorResource(behavior, this);
+        }
+    }
+}

package/src/behavior/system/remote/api/resources/NodeResource.ts

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Agent } from "#endpoint/Agent.js";
+import { Node } from "#node/Node.js";
+import { ApiResource } from "../ApiResource.js";
+import { EndpointContainerResource } from "./EndpointContainerResource.js";
+import { EndpointResource } from "./EndpointResource.js";
+
+/**
+ * Specialization for {@link EndpointResource} that adds "endpoints" collection.
+ */
+export class NodeResource extends EndpointResource {
+    constructor(agent: Agent, parent: undefined | ApiResource) {
+        super(agent, parent);
+    }
+
+    override get valueKind(): ApiResource.Kind {
+        return "node";
+    }
+
+    override async childFor(name: string): Promise<ApiResource | void> {
+        const {
+            node: { endpoints },
+        } = this;
+
+        // The "flat" endpoint IDs only apply at the top-level of an endpoint; otherwise they map to cluster IDs.  That
+        // should be fine because clusters will usually be referenced by name
+        if (!this.isSelfReferential) {
+            // Numeric indices on nodes map to endpoints
+            if (name.match(/^\d+$/)) {
+                return (await this.childFor("endpoints"))?.childFor(name);
+            }
+        }
+
+        // Endpoint collection
+        if (name === "endpoints") {
+            return new EndpointContainerResource(
+                this,
+                "endpoints",
+                () => endpoints.map(endpoint => endpoint.number.toString()),
+                name => {
+                    if (!name.match(/^\d+$/)) {
+                        return;
+                    }
+                    const number = Number.parseInt(name);
+                    if (Number.isNaN(number) || !endpoints.has(number)) {
+                        return;
+                    }
+
+                    const endpoint = endpoints.for(number);
+                    return new EndpointResource(endpoint.agentFor(this.agent.context), this);
+                },
+            );
+        }
+
+        // Pass to endpoint resolver
+        return super.childFor(name);
+    }
+
+    get node() {
+        return this.agent.endpoint as Node;
+    }
+
+    get isSelfReferential() {
+        return this.parent instanceof NodeResource && this.parent.node === this.node;
+    }
+}

package/src/behavior/system/remote/api/resources/PropertyResource.ts

@@ -0,0 +1,124 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { RootSupervisor } from "#behavior/supervision/RootSupervisor.js";
+import { type ValueSupervisor } from "#behavior/supervision/ValueSupervisor.js";
+import { InternalError, NotImplementedError } from "#general";
+import { DataModelPath, Metatype, Schema } from "#model";
+import { Val } from "@matter/protocol";
+import { StatusResponse } from "@matter/types";
+import { ApiResource } from "../ApiResource.js";
+import { Envelope } from "../Envelope.js";
+
+/**
+ * API item for sub-properties of collections (clusters, structs and lists in the Matter data model).
+ */
+export class PropertyResource extends ApiResource {
+    id: string;
+    supervisor: ValueSupervisor;
+    dataModelPath: DataModelPath;
+
+    get valueKind(): ApiResource.Kind {
+        if (this.schema.tag === "attribute") {
+            return "attribute";
+        }
+        return "field";
+    }
+
+    constructor(parent: ApiResource, id: string, supervisor: ValueSupervisor, path: DataModelPath) {
+        super(parent);
+
+        this.id = id;
+        this.supervisor = supervisor;
+        this.dataModelPath = path;
+    }
+
+    override get schema() {
+        return this.supervisor.schema;
+    }
+
+    get value() {
+        return (this.parent?.value as Val.Struct | undefined)?.[this.id];
+    }
+
+    override write(request: Envelope.Data) {
+        const requestEnv = new Envelope({ supervisor: this.supervisor, ...request });
+        requestEnv.validate();
+        this.#target[this.id] = requestEnv.js;
+    }
+
+    override patch(request: Envelope) {
+        request = new Envelope({ supervisor: this.supervisor, ...request });
+        request.validate();
+        this.#targetSupervisor.patch({ [this.id]: request.js }, this.#target, this.dataModelPath);
+    }
+
+    override add(request: Envelope) {
+        const struct = this.#target;
+        if (!Array.isArray(struct)) {
+            throw new NotImplementedError();
+        }
+
+        request = new Envelope({ supervisor: this.supervisor, ...request });
+        struct.push(request.js);
+    }
+
+    override delete() {
+        const struct = this.#target;
+        if (Array.isArray(struct)) {
+            struct.splice(this.id as unknown as number, 1);
+        } else {
+            this.#target[this.id] = undefined;
+        }
+    }
+
+    override async childFor(id: string): Promise<ApiResource | void> {
+        let mySchema: Schema | undefined;
+        switch (this.schema.effectiveMetatype) {
+            case Metatype.object:
+                mySchema = this.schema.conformant.properties.for(id);
+                break;
+
+            case Metatype.array:
+                if (!id.match(/^\d+$/)) {
+                    mySchema = undefined;
+                } else {
+                    mySchema = this.schema.conformant.properties.for("entry");
+                }
+                break;
+
+            default:
+                throw new NotImplementedError();
+        }
+
+        if (!mySchema) {
+            throw new StatusResponse.NotFoundError();
+        }
+
+        const myCollection = this.#target[this.id];
+        if (!myCollection) {
+            return;
+        }
+
+        return new PropertyResource(this, id, this.supervisorFor(mySchema), this.dataModelPath.at(id));
+    }
+
+    get #target() {
+        const collection = this.parent?.value as Val.Struct;
+        if (!collection || typeof collection !== "object") {
+            throw new InternalError("Value of property item has no collection");
+        }
+        return collection;
+    }
+
+    get #targetSupervisor() {
+        const supervisor = RootSupervisor.for(this.parent?.schema);
+        if (!supervisor) {
+            throw new InternalError("No supervisor for parent collection");
+        }
+        return supervisor;
+    }
+}

package/src/behavior/system/remote/api/resources/ServerNodeResource.ts

@@ -0,0 +1,63 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { ServerNode } from "#node/ServerNode.js";
+import { ChangesResource } from "./ChangesResource.js";
+import { EndpointContainerResource } from "./EndpointContainerResource.js";
+import { NodeResource } from "./NodeResource.js";
+
+/**
+ * Specialization of {@link NodeResource} that adds "peers" collection and "changes" subscription item.
+ */
+export class ServerNodeResource extends NodeResource {
+    /**
+     * For the root node, we provide a "flat" namespace that is rooted at Node IDs, in addition to the normal
+     * endpoint namespace.  This could conceivably lead to conflict but we also provide typed subcollections that
+     * cannot have conflicts.
+     *
+     * We disable the flat namespace if the node is referenced as a child of itself so conflicts cannot occur.
+     */
+    override async childFor(name: string) {
+        if (!this.isSelfReferential) {
+            // Dedicated name "host" and my node ID always map back to myself
+            if (name === this.id || name === "host") {
+                return this;
+            }
+
+            // If the name is a peer, map to that
+            const peer = this.node.peers.get(name);
+            if (peer) {
+                return new NodeResource(peer.agentFor(this.agent.context), this);
+            }
+        }
+
+        switch (name) {
+            // Explicit collection of peers
+            case "peers":
+                return new EndpointContainerResource(
+                    this,
+                    "peers",
+                    () => this.node.peers.map(peer => peer.id),
+                    id => {
+                        const peer = this.node.peers.get(id);
+                        if (peer) {
+                            return new NodeResource(peer.agentFor(this.agent.context), this);
+                        }
+                    },
+                );
+
+            // Subscription target
+            case "changes":
+                return new ChangesResource(this);
+        }
+
+        return super.childFor(name);
+    }
+
+    override get node() {
+        return this.agent.endpoint as ServerNode;
+    }
+}

package/src/behavior/system/remote/api/resources/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./BehaviorResource.js";
+export * from "./CommandResource.js";
+export * from "./EndpointContainerResource.js";
+export * from "./EndpointResource.js";
+export * from "./NodeResource.js";
+export * from "./PropertyResource.js";
+export * from "./ServerNodeResource.js";

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

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./api/index.js";
+export * from "./RemoteInterface.js";
+export * from "./RemoteServer.js";

package/src/behavior/system/subscriptions/SubscriptionsServer.ts

@@ -235,12 +235,11 @@ export class SubscriptionsBehavior extends Behavior {
                 logger.debug(`We already have and existing session for peer ${peerAddress}`);
             } else {
                 try {
-                    await peers.ensureConnection(peerAddress, {
+                    await peers.connect(peerAddress, {
                         discoveryOptions: {
                             discoveryType: NodeDiscoveryType.TimedDiscovery,
                             timeout: REESTABLISH_SUBSCRIPTIONS_TIMEOUT,
                         },
-                        allowUnknownPeer: true,
                         operationalAddress,
                     });
                 } catch (error) {
@@ -281,7 +280,7 @@ export class SubscriptionsBehavior extends Behavior {
         interactionServer.subscriptionEstablishmentStarted.off(blockHandler);
 
         logger.info(
-            `Re-established ${successfullReEstablishments.length} ${successfullReEstablishments.length ? `(${successfullReEstablishments.join(",")})` : ""} of ${formerSubscriptions.length} former subscriptions successfully`,
+            `Re-established ${successfullReEstablishments.length}${successfullReEstablishments.length ? ` (${successfullReEstablishments.join(",")})` : ""} of ${formerSubscriptions.length} former subscriptions successfully`,
         );
     }
 }

package/src/behavior/system/websocket/WebSocketInterface.ts

@@ -0,0 +1,127 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Abort, AppAddress, asJson, Bytes, HttpEndpoint, HttpService, Mutex, Stream } from "#general";
+import { StatusResponse, StatusResponseError } from "#types";
+import { Api } from "../remote/api/Api.js";
+import { ApiPath } from "../remote/api/ApiPath.js";
+import { LocalResponse } from "../remote/api/LocalResponse.js";
+import { RemoteRequest } from "../remote/api/RemoteRequest.js";
+import { RemoteResponse } from "../remote/api/RemoteResponse.js";
+import { RemoteInterface } from "../remote/RemoteInterface.js";
+
+const LOG_FACILITY = "WebSocket";
+
+/**
+ * WebSocket remote interface.
+ */
+export class WebSocketInterface extends RemoteInterface {
+    static override protocol = "ws";
+
+    #http?: HttpEndpoint;
+    #mutex = new Mutex(this);
+
+    protected override async start() {
+        this.#http = await this.env.get(HttpService).create(this.address);
+        this.#http.ws = this.#handleConnection.bind(this);
+    }
+
+    protected override async stop() {
+        await super.stop();
+        await this.#http?.close();
+    }
+
+    /**
+     * Handle HTTP connections.
+     *
+     * Checks path, upgrades to a WebSocket if the path applies, then processes input messages
+     */
+    async #handleConnection(request: Request, upgrade: () => Promise<HttpEndpoint.WsConnection>) {
+        // Normalize path and compare to root
+        const address = new AppAddress(request.url);
+        const path = new ApiPath(address).toString();
+        if (path !== this.root.toString()) {
+            return;
+        }
+
+        // Upgrade to WebSocket
+        const ws = await Abort.race(this.abort, await upgrade());
+        if (!ws) {
+            return;
+        }
+
+        using subtask = Abort.subtask(this.abort);
+
+        const send = async (local: LocalResponse) => {
+            await this.#mutex.produce(async () => {
+                const message = RemoteResponse(local);
+                Api.logResponse(LOG_FACILITY, message);
+                const writer = ws.writable.getWriter();
+                try {
+                    await writer.write(asJson(message));
+                } finally {
+                    writer.releaseLock();
+                }
+            });
+        };
+
+        for await (let message of Stream.iterable(ws.readable)) {
+            let requestId: string | undefined;
+            try {
+                message = Bytes.toString(message);
+
+                let parsed;
+                try {
+                    parsed = JSON.parse(message);
+                } catch (e) {
+                    if (e instanceof SyntaxError) {
+                        throw new StatusResponse.InvalidCommandError(`Request parse error: ${e.message}`);
+                    }
+                    throw e;
+                }
+                requestId = (parsed as RemoteRequest)?.id;
+
+                const request = RemoteRequest(parsed);
+
+                await this.#handleRequest(request, subtask, send);
+            } catch (error) {
+                StatusResponseError.accept(error);
+
+                await send({
+                    kind: "error",
+                    id: requestId,
+                    error,
+                });
+            }
+        }
+
+        // Abort any ongoing subscriptions associated with the connection
+        subtask.abort();
+    }
+
+    async #handleRequest(
+        request: RemoteRequest,
+        abort: AbortController,
+        send: (message: LocalResponse) => Promise<void>,
+    ) {
+        const response = await this.#mutex.produce(() => Api.execute(LOG_FACILITY, this.node, request, abort));
+
+        if (response.kind !== "subscription") {
+            await send(response);
+            return;
+        }
+
+        await send({ id: request.id, kind: "ok" });
+
+        this.addWorker(this.#handleSubscription(response.stream, send), "ws subscription handler");
+    }
+
+    async #handleSubscription(stream: LocalResponse.Stream, send: (message: LocalResponse) => Promise<void>) {
+        for await (const update of stream) {
+            await send(update.js);
+        }
+    }
+}

package/src/behavior/system/websocket/WebSocketServer.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { RemoteServer } from "../remote/RemoteServer.js";
+import { WebSocketInterface } from "./WebSocketInterface.js";
+
+/**
+ * Allows control of a Matter node using an HTTP API.
+ */
+export class WebSocketServer extends RemoteServer {
+    static override readonly id = "websocket";
+    static override readonly interfaceType = WebSocketInterface;
+}
+
+export namespace WebSocketServer {
+    export class State extends RemoteServer.State {
+        /**
+         * The WebSocket address.
+         *
+         * Supported protocols:
+         *
+         *   - ws (unencrypted WebSocket)
+         *   - wss (encrypted WebSocket)
+         *   - ws+unix (WebSockets over a UNIX socket)
+         *   - wss+unix (WebSockets over a secure UNIX socket)
+         */
+        override address = "ws+unix:matter.sock";
+    }
+}

package/src/behavior/system/websocket/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./WebSocketInterface.js";
+export * from "./WebSocketServer.js";