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

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

@@ -0,0 +1,169 @@
+/**
+ * @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 { Abort, MaybePromise, NotImplementedError } from "#general";
+import { any, DataModelPath, Schema } from "#model";
+import { Envelope } from "./Envelope.js";
+import { LocalResponse } from "./LocalResponse.js";
+
+/**
+ * A node in the logical API tree structure.
+ *
+ * {@link ApiResource}s are ephemeral objects created on-demand as the server navigates paths.
+ */
+export abstract class ApiResource {
+    /**
+     * The item's identifier in the logical model path.
+     */
+    abstract readonly id: string;
+
+    /**
+     * The item's owner, if any.
+     */
+    readonly parent?: ApiResource;
+
+    /**
+     * Data model path used for diagnostics.
+     */
+    abstract readonly dataModelPath: DataModelPath;
+
+    /**
+     * Value supervisor, if any.
+     */
+    abstract readonly supervisor?: ValueSupervisor;
+
+    /**
+     * Data value.
+     */
+    abstract readonly value: unknown;
+
+    /**
+     * Indicates whether this is an RPC endpoint.
+     */
+    readonly isInvocable: boolean = false;
+
+    /**
+     * Indicates whether this is an event endpoint.
+     */
+    readonly isSubscribable: boolean = false;
+
+    /**
+     * The {@link ApiResource.Kind} for {@link value}.
+     */
+    abstract readonly valueKind: ApiResource.Kind;
+
+    constructor(parent: undefined | ApiResource) {
+        this.parent = parent;
+    }
+
+    /**
+     * Retrieve the body of the item.
+     */
+    read() {
+        if (this.value === undefined) {
+            return;
+        }
+
+        return new Envelope({
+            supervisor: this.supervisor ?? RootSupervisor.for(any),
+            js: this.value,
+        });
+    }
+
+    /**
+     * Create or replace item.
+     */
+    write(_request: Envelope.Data): void {
+        throw new NotImplementedError();
+    }
+
+    /**
+     * Update item using matter.js patch semantics.
+     */
+    patch(_request: Envelope.Data): MaybePromise<void> {
+        throw new NotImplementedError();
+    }
+
+    /**
+     * Add a child item of this item.
+     */
+    add(_request: Envelope.Data): MaybePromise<void> {
+        throw new NotImplementedError();
+    }
+
+    /**
+     * Remove this item.
+     */
+    delete(): MaybePromise<void> {
+        throw new NotImplementedError();
+    }
+
+    /**
+     * The {@link Schema} for this resource subtree.
+     */
+    get schema() {
+        return this.supervisor?.schema;
+    }
+
+    /**
+     * Obtain the appropriate {@link ValueSupervisor} for a {@link Schema} in this subtree.
+     */
+    supervisorFor(schema: Schema) {
+        return this.rootSupervisor?.get(schema) ?? RootSupervisor.for(schema);
+    }
+
+    /**
+     * The {@link RootSupervisor} for this resource subtree.
+     */
+    get rootSupervisor(): RootSupervisor | undefined {
+        return this.parent?.rootSupervisor;
+    }
+
+    /**
+     * Execute a procedure.
+     */
+    async invoke(_request?: Envelope.Data): Promise<undefined | Envelope> {
+        throw new NotImplementedError();
+    }
+
+    /**
+     * Subscribe to events.
+     */
+    // eslint-disable-next-line require-yield
+    async *subscribe(
+        _abort: Abort.Signal,
+        _request?: Envelope.Data,
+    ): AsyncGenerator<Envelope<LocalResponse>, void, void> {
+        throw new NotImplementedError();
+    }
+
+    /**
+     * Retrieve a child with the specified ID.
+     */
+    async childFor(_id: string): Promise<ApiResource | void> {
+        return undefined;
+    }
+}
+
+export namespace ApiResource {
+    /**
+     * "Kind" values provided in response JSON payloads.
+     */
+    export type Kind =
+        | "ok"
+        | "node"
+        | "endpoint"
+        | "index"
+        | "cluster"
+        | "attribute"
+        | "field"
+        | "error"
+        | "command"
+        | "response"
+        | "changes";
+}

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

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { LocalActorContext } from "#behavior/context/index.js";
+import type { ValueSupervisor } from "#behavior/supervision/ValueSupervisor.js";
+import { asJson, Bytes } from "#general";
+import { DataModelPath } from "#model";
+import { StatusResponse, TlvOfModel } from "#types";
+
+/**
+ * Api data envelope packages used for request and response.
+ *
+ * This allows for transparent conversion between our three "native" formats -- JS values, serialized JSON and
+ * serialized TLV.
+ */
+export class Envelope<T = unknown> {
+    #supervisor: ValueSupervisor;
+    #js?: T;
+    #json?: string;
+    #tlv?: Bytes;
+
+    constructor({ supervisor, js, json, tlv }: Envelope.Definition<T>) {
+        this.#supervisor = supervisor;
+        this.#js = js;
+        this.#json = json;
+        this.#tlv = tlv;
+    }
+
+    /**
+     * Validate against the schema.  Casts to appropriate types if necessary.
+     */
+    validate(path?: DataModelPath) {
+        if (!path) {
+            path = DataModelPath(this.#supervisor.schema.path);
+        }
+
+        this.#js = this.#supervisor.cast(this.#js) as T;
+        this.#supervisor.validate?.(this.js, LocalActorContext.ReadOnly, { path });
+    }
+
+    /**
+     * Convert a {@link js} value to {@link JSON}.
+     *
+     * This acts as a deep copy and optimizes JSON access.  If TLV becomes a priority then we can make this conversion
+     * configurable.
+     */
+    convertToJson() {
+        if (this.#js !== undefined) {
+            void this.json;
+        }
+        this.#js = undefined;
+    }
+
+    /**
+     * Native JS format.
+     */
+    get js() {
+        if (this.#js === undefined) {
+            if (this.#json) {
+                try {
+                    this.#js = JSON.parse(this.#json) as T;
+                } catch (e) {
+                    if (e instanceof SyntaxError) {
+                        throw new StatusResponse.FailureError(`Unparseable JSON: ${e.message}`);
+                    }
+                    throw e;
+                }
+            } else if (this.#tlv) {
+                this.#js = TlvOfModel(this.#supervisor.schema).decode(this.#tlv) as T;
+            } else {
+                this.#js = null as T;
+            }
+        }
+        return this.#js;
+    }
+
+    /**
+     * JSON format.
+     */
+    get json() {
+        if (this.#json === undefined) {
+            this.#json = asJson(this.js);
+        }
+        return this.#json;
+    }
+
+    /**
+     * Serialized TLV format.
+     */
+    get tlv() {
+        if (this.#tlv === undefined) {
+            this.#tlv = TlvOfModel(this.#supervisor.schema).encode(this.#js);
+        }
+        return this.#tlv;
+    }
+}
+
+export namespace Envelope {
+    export interface Data<T = unknown> {
+        id?: string;
+        js?: T;
+        json?: string;
+        tlv?: Bytes;
+    }
+
+    export interface Definition<T = unknown> extends Data<T> {
+        supervisor: ValueSupervisor;
+    }
+}

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

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Envelope } from "./Envelope.js";
+import { RemoteResponse } from "./RemoteResponse.js";
+
+/**
+ * The intermediate version of a {@link RemoteResponse}, transformed before transmission.
+ */
+export type LocalResponse =
+    | RemoteResponse.OK
+    | RemoteResponse.Change
+    | LocalResponse.Value
+    | LocalResponse.Subscription
+    | LocalResponse.Error;
+
+export namespace LocalResponse {
+    export interface Value extends RemoteResponse.Base {
+        kind: "value";
+        value: Envelope;
+    }
+
+    export interface Subscription extends RemoteResponse.Base {
+        kind: "subscription";
+        stream: Stream;
+    }
+
+    export interface Error extends RemoteResponse.Base {
+        kind: "error";
+        error: globalThis.Error;
+    }
+
+    export interface Stream extends AsyncIterableIterator<Envelope<LocalResponse>, void, void> {}
+}

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

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { isObject } from "#general";
+import { StateStream } from "#node/integration/StateStream.js";
+import { StatusResponse } from "#types";
+
+/**
+ * An RPC request.
+ */
+export type RemoteRequest =
+    | RemoteRequest.Read
+    | RemoteRequest.Write
+    | RemoteRequest.Add
+    | RemoteRequest.Delete
+    | RemoteRequest.Invoke
+    | RemoteRequest.Subscribe;
+
+/**
+ * Validate and return request object.
+ */
+export function RemoteRequest(request: unknown) {
+    if (!isObject(request)) {
+        throw new StatusResponse.InvalidActionError("Request is not an object");
+    }
+
+    const { target, method } = request;
+    if (typeof method !== "string") {
+        throw new StatusResponse.InvalidActionError('Request does not specify opcode in "method" property');
+    }
+
+    switch (method) {
+        case "read":
+        case "write":
+        case "add":
+        case "delete":
+        case "invoke":
+        case "subscribe":
+            break;
+
+        default:
+            throw new StatusResponse.InvalidActionError(`Unsupported request method "${method}"`);
+    }
+
+    if (typeof target !== "string") {
+        throw new StatusResponse.InvalidActionError('Request does not specify resource in "target" property');
+    }
+
+    return request as unknown as RemoteRequest;
+}
+
+export namespace RemoteRequest {
+    export interface Base {
+        target: string;
+        id?: string;
+    }
+
+    export interface Read extends Base {
+        method: "read";
+    }
+
+    export interface Write extends Base {
+        method: "write";
+        value: unknown;
+    }
+
+    export interface Add extends Base {
+        method: "add";
+        value: unknown;
+    }
+
+    export interface Delete extends Base {
+        method: "delete";
+    }
+
+    export interface Invoke extends Base {
+        method: "invoke";
+        target: string;
+        parameters?: unknown;
+    }
+
+    export interface Subscribe extends Base, StateStream.Options {
+        method: "subscribe";
+    }
+}

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

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError, MatterError } from "#general";
+import type { StateStream } from "#node/integration/StateStream.js";
+import { StatusResponseError } from "#types";
+import type { LocalResponse } from "./LocalResponse.js";
+
+/**
+ * An RPC response.
+ *
+ * This is the serializable object delivered over the wire.
+ */
+export type RemoteResponse = RemoteResponse.OK | RemoteResponse.Value | RemoteResponse.Error | RemoteResponse.Change;
+
+/**
+ * Create a {@link RemoteResponse} from a {@link LocalResponse}.
+ */
+export function RemoteResponse(local: LocalResponse): RemoteResponse {
+    switch (local.kind) {
+        case "ok":
+        case "update":
+        case "delete":
+            return local;
+
+        case "value":
+            return {
+                ...local,
+                value: local.value.js,
+            };
+
+        case "error":
+            return {
+                kind: "error",
+                id: local.id,
+                code: MatterError.idFor(local.error.constructor),
+                message: (local.error as StatusResponseError).bareMessage ?? local.error.message,
+            };
+
+        default:
+            throw new InternalError(`Cannot convert local response kind "${local.kind}" to remote response`);
+    }
+}
+
+export namespace RemoteResponse {
+    export interface Base {
+        id?: string;
+    }
+
+    export interface OK extends Base {
+        kind: "ok";
+        requestId?: string;
+    }
+
+    export interface Value extends Base {
+        kind: "value";
+        value: unknown;
+    }
+
+    export interface Error extends Base {
+        kind: "error";
+        message: string;
+        code: string;
+    }
+
+    export type Change = Base & StateStream.WireChange;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./Api.js";
+export * from "./ApiResource.js";
+export * from "./Envelope.js";
+export * from "./LocalResponse.js";
+export * from "./RemoteRequest.js";
+export * from "./RemoteResponse.js";
+export * from "./resources/index.js";

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

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Behavior } from "#behavior/Behavior.js";
+import { RootSupervisor } from "#behavior/supervision/RootSupervisor.js";
+import { InternalError } from "#general";
+import { ClusterModel, CommandModel } from "#model";
+import { StatusResponse } from "#types";
+import { ApiResource } from "../ApiResource.js";
+import { CommandResource } from "./CommandResource.js";
+import { PropertyResource } from "./PropertyResource.js";
+
+/**
+ * API item for behaviors.
+ */
+export class BehaviorResource extends PropertyResource {
+    #behavior: Behavior;
+
+    override get valueKind(): ApiResource.Kind {
+        return "cluster";
+    }
+
+    constructor(behavior: Behavior, parent: ApiResource) {
+        const { id, supervisor } = behavior.type;
+        if (supervisor === undefined) {
+            throw new InternalError(`API behavior reference has no value supervisor`);
+        }
+
+        super(parent, id, supervisor, behavior.endpoint.path.at(id));
+        this.#behavior = behavior;
+    }
+
+    override get value() {
+        return this.#behavior.state;
+    }
+
+    override write() {
+        throw new StatusResponse.UnsupportedWriteError(`Only patch supported for this path`);
+    }
+
+    override async childFor(id: string) {
+        // "state" is a view of the cluster without commands; adds consistency w/ JS API and useful for handling name
+        // collision
+        if (id === "state") {
+            return new PropertyResource(this, "state", this.supervisor, this.dataModelPath.at("state"));
+        }
+
+        // For direct children, commands take precedence should there be a name collision
+        if (this.schema instanceof ClusterModel) {
+            const command = this.schema.conformant.commands.for(id, CommandModel);
+            if (command) {
+                return new CommandResource(this, this.#behavior, command);
+            }
+        }
+
+        // Now attributes (or fields in case of non-Matter properties)
+        return super.childFor(id);
+    }
+
+    override get rootSupervisor() {
+        return this.supervisor as RootSupervisor;
+    }
+}

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

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { RootSupervisor } from "#behavior/supervision/RootSupervisor.js";
+import { Abort, InternalError } from "#general";
+import { StateStream } from "#node/integration/StateStream.js";
+import { ServerNode } from "#node/ServerNode.js";
+import { ApiResource } from "../ApiResource.js";
+import { Envelope } from "../Envelope.js";
+import { LocalResponse } from "../LocalResponse.js";
+import { NodeResource as ServerNodeItem } from "./NodeResource.js";
+
+/**
+ * An item that delivers state changes via subscription.
+ */
+export class ChangesResource extends ApiResource {
+    readonly id = "changes";
+    readonly valueKind = "changes";
+    readonly supervisor = undefined;
+    readonly value = undefined;
+    override readonly isSubscribable = true;
+
+    declare readonly parent: ServerNodeItem;
+
+    constructor(parent: ServerNodeItem) {
+        super(parent);
+    }
+
+    get dataModelPath() {
+        return this.parent.dataModelPath.at("changes");
+    }
+
+    override async *subscribe(
+        abort: Abort.Signal,
+        request: Envelope.Data,
+    ): AsyncGenerator<Envelope<LocalResponse>, void, void> {
+        const requestEnv = new Envelope({ supervisor: RootSupervisor.for(StateStream.OptionsSchema), ...request });
+
+        let options: undefined | StateStream.Options;
+        if (requestEnv.js) {
+            requestEnv.validate();
+            options = requestEnv.js as StateStream.Options;
+        }
+
+        const stream = StateStream(this.parent.node as ServerNode, { ...options, abort });
+
+        const { id } = request;
+
+        for await (const change of stream) {
+            const wire = StateStream.WireChange(change);
+
+            switch (change.kind) {
+                case "update":
+                    yield new Envelope({
+                        supervisor: RootSupervisor.for(StateStream.WireUpdateSchema),
+                        js: { id, ...wire },
+                    });
+                    break;
+
+                case "delete":
+                    yield new Envelope({
+                        supervisor: RootSupervisor.for(StateStream.WireDeleteSchema),
+                        js: { id, ...wire },
+                    });
+                    break;
+
+                default:
+                    throw new InternalError(`Unsupported change kind ${(change as StateStream.Change).kind}`);
+            }
+        }
+    }
+}