@matter/node 0.15.1 → 0.15.2-alpha.0-20250703-2e16aba2b

package/src/node/client/ClientBehavior.ts

@@ -0,0 +1,254 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Behavior } from "#behavior/Behavior.js";
+import { ClusterBehavior } from "#behavior/cluster/ClusterBehavior.js";
+import { camelize, capitalize, InternalError } from "#general";
+import { AttributeModel, ClusterModel, CommandModel, FeatureBitmap, Matter } from "#model";
+import type { ClientNode } from "#node/ClientNode.js";
+import { Node } from "#node/Node.js";
+import { Invoke } from "#protocol";
+import {
+    Attribute,
+    AttributeId,
+    ClusterComposer,
+    ClusterId,
+    ClusterRegistry,
+    ClusterType,
+    Command,
+    CommandId,
+    MutableCluster,
+    Status,
+    StatusResponseError,
+    TlvAny,
+    TlvNoResponse,
+} from "#types";
+
+const BIT_BLOCK_SIZE = Math.log2(Number.MAX_SAFE_INTEGER);
+
+const cache = {} as Record<string, ClusterBehavior.Type>;
+
+/**
+ * Obtain a {@link ClusterBehavior.Type} for a remote cluster.
+ */
+export function ClientBehavior(shape: ClientBehavior.ClusterShape): ClusterBehavior.Type {
+    const analysis = ShapeAnalysis(shape);
+
+    const fingerprint = createFingerprint(analysis);
+    let type = cache[fingerprint];
+    if (type) {
+        return type;
+    }
+
+    let baseType: Behavior.Type;
+    const standardCluster = ClusterRegistry.get(shape.id);
+    if (standardCluster) {
+        baseType = ClusterBehavior.for(standardCluster);
+    } else {
+        baseType = ClusterBehavior;
+    }
+
+    type = cache[fingerprint] = generateType(analysis, baseType);
+
+    return type;
+}
+
+export namespace ClientBehavior {
+    export interface ClusterShape {
+        id: ClusterId;
+        revision: number;
+        features: FeatureBitmap | number;
+        attributes: AttributeId[];
+        commands: CommandId[];
+        attributeNames: Record<AttributeId, string>;
+        commandNames: Record<CommandId, string>;
+    }
+}
+
+function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): ClusterBehavior.Type {
+    // Ensure the input type is a ClusterBehavior
+    if (!ClusterBehavior.is(baseType)) {
+        throw new InternalError(`Base Behavior for cluster ${analysis.schema.name} is not a ClusterBehavior`);
+    }
+
+    let { schema } = analysis;
+    const { extraAttrs, extraCommands } = analysis;
+
+    // Obtain a ClusterType.  This provides TLV for known elements
+    let { cluster } = baseType;
+    if (!cluster) {
+        cluster = MutableCluster({ id: schema.id, name: schema.name, revision: schema.revision });
+    }
+
+    // Identify known features the device supports
+    let supportedFeatures = analysis.shape.features;
+    if (typeof supportedFeatures === "number") {
+        if (supportedFeatures) {
+            supportedFeatures = cluster.attributes.featureMap.schema.decode(supportedFeatures as any) as FeatureBitmap;
+        } else {
+            supportedFeatures = {};
+        }
+    }
+
+    // If there are features supported, customize the ClusterModel and ClusterType accordingly
+    const featureNames = Object.entries(supportedFeatures)
+        .filter(([, v]) => v)
+        .map(([k]) => k);
+    if (featureNames.length) {
+        // Update ClusterModel
+        schema = schema.clone();
+        schema.supportedFeatures = featureNames;
+
+        // Update the cluster.  Note that we do not validate feature combinations.  What the device sends we work with
+        cluster = new ClusterComposer(cluster, true).compose(featureNames.map(capitalize));
+    }
+
+    // If the schema does not match what the device actually returned, further augment both the ClusterModel and
+    // ClusterType with unknown attributes and/or commands
+    if (schema.revision !== analysis.shape.revision || extraAttrs.size || extraCommands.size) {
+        schema = schema.clone();
+
+        cluster = {
+            ...cluster,
+            supportedFeatures,
+            attributes: { ...cluster.attributes },
+            commands: { ...cluster.commands },
+        };
+
+        schema.supportedFeatures = supportedFeatures;
+
+        for (const id of extraAttrs) {
+            const name = createUnknownName("attr", id);
+            cluster.attributes[camelize(name, false)] = Attribute(id, TlvAny);
+            schema.children.push(new AttributeModel({ id, name, type: "any" }));
+        }
+
+        for (const id of extraCommands) {
+            const name = createUnknownName("command", id);
+            cluster.commands[camelize(name, false)] = Command(id, TlvAny, 0, TlvNoResponse);
+            schema.children.push(new CommandModel({ id, name, type: "any" }));
+        }
+    }
+
+    // Specialize for the specific cluster and schema
+    const type = baseType.for(cluster, schema, `${schema.name}Client`);
+
+    // Add command implementations
+    for (const id of analysis.shape.commands) {
+        const name = schema.get(CommandModel, id)?.name ?? createUnknownName("command", id);
+        const command = cluster.commands[camelize(name)];
+        type.prototype[camelize(name, false)] = implementCommand(command);
+    }
+
+    return type;
+
+    function implementCommand(command: ClusterType.Command) {
+        return async function (this: ClusterBehavior, fields?: {}) {
+            const node = this.env.get(Node) as ClientNode;
+
+            const chunks = node.interaction.invoke(
+                Invoke(
+                    Invoke.Command<any>({
+                        endpoint: this.endpoint,
+                        cluster,
+                        command,
+                        fields,
+                    }),
+                ),
+            );
+
+            for await (const chunk of chunks) {
+                for (const entry of chunk) {
+                    // TODO - do we need to support multiple data chunks?
+                    switch (entry.kind) {
+                        case "cmd-status":
+                            if (entry.status !== Status.Success) {
+                                throw StatusResponseError.create(entry.status, undefined, entry.clusterStatus);
+                            }
+                            break;
+
+                        case "cmd-response":
+                            return command.responseSchema.decodeTlv(entry.data);
+                    }
+                }
+            }
+        };
+    }
+}
+
+/**
+ * Create a compact string that uniquely identifies a shape for matching purposes.
+ */
+function createFingerprint(analysis: ShapeAnalysis) {
+    const fingerprint = [analysis.shape.id] as (number | string)[];
+
+    if (analysis.extraAttrs.size) {
+        fingerprint.push("a", createElementFingerprint(analysis.extraAttrs));
+    }
+
+    if (analysis.extraCommands.size) {
+        fingerprint.push("c", createElementFingerprint(analysis.extraCommands));
+    }
+
+    return fingerprint.join(";");
+
+    /**
+     * Create a fingerprint for a specific type of ACE element.
+     *
+     * For elements we divide create series of bitmaps, one for each range of BIT_BLOCK_SIZE unique integers with an
+     * ID present.  Note that these bitmaps may not be consecutive due to gaps in IDs.  We then serialize all bitmaps
+     * present as "<block index>:<bitmap value>" and concatenate to create a unique fingerprint.
+     *
+     * The goal is to efficiently create a compact unique identifier.
+     */
+    function createElementFingerprint(ids: Iterable<number>) {
+        const blocks = {} as Record<number, number>;
+
+        for (const id of ids) {
+            const block = Math.floor(id / BIT_BLOCK_SIZE);
+            blocks[block] = (blocks[block] ?? 0) | (1 << id % BIT_BLOCK_SIZE);
+        }
+
+        return Object.entries(blocks)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([block, map]) => (block ? `${block}:${map}` : map))
+            .join(",");
+    }
+}
+
+function createUnknownName(prefix: string, id: number) {
+    return `${prefix}$${id.toString(16)}`;
+}
+
+interface ShapeAnalysis {
+    schema: ClusterModel & { id: ClusterId };
+    shape: ClientBehavior.ClusterShape;
+    extraAttrs: Set<number>;
+    extraCommands: Set<number>;
+}
+
+function ShapeAnalysis(shape: ClientBehavior.ClusterShape): ShapeAnalysis {
+    const schema =
+        Matter.get(ClusterModel, shape.id) ??
+        new ClusterModel({ id: shape.id, name: createUnknownName("Cluster", shape.id), revision: shape.revision });
+
+    const extraAttrs = new Set(shape.attributes);
+    for (const attr of schema.attributes) {
+        extraAttrs.delete(attr.id as AttributeId);
+    }
+
+    const extraCommands = new Set(shape.commands);
+    for (const command of schema.commands) {
+        extraCommands.delete(command.id as CommandId);
+    }
+
+    return {
+        schema: schema as ClusterModel & { id: ClusterId },
+        shape,
+        extraAttrs,
+        extraCommands,
+    };
+}

package/src/node/client/ClientEndpointInitializer.ts

@@ -5,22 +5,25 @@
  */
 
 import { Behavior } from "#behavior/Behavior.js";
+import { ClusterBehavior } from "#behavior/cluster/ClusterBehavior.js";
 import { BehaviorBacking } from "#behavior/internal/BehaviorBacking.js";
 import { ClientBehaviorBacking } from "#behavior/internal/ClientBehaviorBacking.js";
+import { ServerBehaviorBacking } from "#behavior/internal/ServerBehaviorBacking.js";
 import { Endpoint } from "#endpoint/Endpoint.js";
 import { EndpointInitializer } from "#endpoint/properties/EndpointInitializer.js";
 import type { ClientNode } from "#node/ClientNode.js";
-import { NodeStore } from "#node/storage/NodeStore.js";
-import { ServerNodeStore } from "#node/storage/ServerNodeStore.js";
+import { NodeStore } from "#storage/NodeStore.js";
+import { ClientStructure } from "./ClientStructure.js";
 
 export class ClientEndpointInitializer extends EndpointInitializer {
     #node: ClientNode;
     #store: NodeStore;
+    #structure?: ClientStructure;
 
     constructor(node: ClientNode) {
         super();
         this.#node = node;
-        this.#store = node.env.get(ServerNodeStore).clientStores.storeForNode(node);
+        this.#store = node.env.get(NodeStore);
     }
 
     async eraseDescendant(endpoint: Endpoint) {
@@ -33,7 +36,7 @@ export class ClientEndpointInitializer extends EndpointInitializer {
             return;
         }
 
-        const store = this.#store.endpointStores.storeForEndpoint(endpoint);
+        const store = this.#store.storeForEndpoint(endpoint);
         await store.erase();
     }
 
@@ -41,18 +44,19 @@ export class ClientEndpointInitializer extends EndpointInitializer {
         // nothing to do
     }
 
-    get ready() {
-        return this.#store.construction.ready;
-    }
+    override createBacking(endpoint: Endpoint, type: Behavior.Type): BehaviorBacking {
+        if ((type as ClusterBehavior.Type).cluster === undefined) {
+            return new ServerBehaviorBacking(endpoint, type, endpoint.behaviors.optionsFor(type));
+        }
 
-    static async create(node: ClientNode) {
-        const instance = new ClientEndpointInitializer(node);
-        await instance.ready;
-        return instance;
+        const store = this.structure.storeFor(endpoint, type as ClusterBehavior.Type);
+        return new ClientBehaviorBacking(endpoint, type, store, endpoint.behaviors.optionsFor(type));
     }
 
-    override createBacking(endpoint: Endpoint, behavior: Behavior.Type): BehaviorBacking {
-        const store = this.#store.endpointStores.storeForEndpoint(endpoint);
-        return new ClientBehaviorBacking(endpoint, behavior, store, endpoint.behaviors.optionsFor(behavior));
+    get structure() {
+        if (this.#structure === undefined) {
+            this.#structure = new ClientStructure(this.#node);
+        }
+        return this.#structure;
     }
 }

package/src/node/client/ClientNodeFactory.ts

@@ -4,8 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { RemoteDescriptor } from "#behavior/system/commissioning/RemoteDescriptor.js";
-import { ImmutableSet } from "#general";
+import type { RemoteDescriptor } from "#behavior/system/commissioning/RemoteDescriptor.js";
+import type { ImmutableSet } from "#general";
 import type { ClientNode } from "#node/ClientNode.js";
 
 /**

package/src/node/client/ClientNodeInteraction.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { ActionContext } from "#behavior/context/ActionContext.js";
+import { EndpointInitializer } from "#endpoint/properties/EndpointInitializer.js";
+import type { ClientNode } from "#node/ClientNode.js";
+import type {
+    Interactable,
+    InvokeRequest,
+    InvokeResult,
+    Read,
+    ReadResult,
+    Subscribe,
+    SubscribeResult,
+    Write,
+    WriteResult,
+} from "#protocol";
+import { ClientInteraction } from "#protocol";
+import { ClientEndpointInitializer } from "./ClientEndpointInitializer.js";
+
+/**
+ * A {@link ClientInteraction} that brings the node online before attempting interaction.
+ */
+export class ClientNodeInteraction implements Interactable<ActionContext> {
+    #node: ClientNode;
+
+    constructor(node: ClientNode) {
+        this.#node = node;
+    }
+
+    async *read(request: Read, context?: ActionContext): ReadResult {
+        request = this.structure.injectVersionFilters(request);
+        const interaction = await this.#connect();
+        const response = interaction.read(request, context);
+        yield* this.structure.mutate(request, response);
+    }
+
+    async subscribe(request: Subscribe, context?: ActionContext): SubscribeResult {
+        const intermediateRequest: Subscribe = {
+            ...this.structure.injectVersionFilters(request),
+
+            updated: async data => {
+                const result = this.structure.mutate(request, data);
+                if (request.updated) {
+                    await request.updated(result);
+                } else {
+                    for await (const _chunk of result);
+                }
+            },
+
+            closed(cause) {
+                // TODO - log cause?
+                request.closed?.(cause);
+            },
+        };
+        const interaction = await this.#connect();
+        return interaction.subscribe(intermediateRequest, context);
+    }
+
+    async write<T extends Write>(request: T, context?: ActionContext): WriteResult<T> {
+        return (await this.#connect()).write(request, context);
+    }
+
+    async *invoke(request: InvokeRequest, context?: ActionContext): InvokeResult {
+        yield* (await this.#connect()).invoke(request, context);
+    }
+
+    async #connect(): Promise<ClientInteraction> {
+        if (!this.#node.lifecycle.isOnline) {
+            await this.#node.start();
+        }
+        return this.#node.env.get(ClientInteraction);
+    }
+
+    get structure() {
+        return (this.#node.env.get(EndpointInitializer) as ClientEndpointInitializer).structure;
+    }
+}

package/src/node/client/ClientNodes.ts

@@ -10,14 +10,16 @@ import { ContinuousDiscovery } from "#behavior/system/controller/discovery/Conti
 import { Discovery } from "#behavior/system/controller/discovery/Discovery.js";
 import { InstanceDiscovery } from "#behavior/system/controller/discovery/InstanceDiscovery.js";
 import { EndpointContainer } from "#endpoint/properties/EndpointContainer.js";
-import { CancelablePromise, Lifespan, Time } from "#general";
-import { ServerNodeStore } from "#node/storage/ServerNodeStore.js";
+import { CancelablePromise, Lifespan, Logger, Time } from "#general";
 import { PeerAddress, PeerAddressStore } from "#protocol";
+import { ServerNodeStore } from "#storage/server/ServerNodeStore.js";
 import { ClientNode } from "../ClientNode.js";
 import type { ServerNode } from "../ServerNode.js";
 import { ClientNodeFactory } from "./ClientNodeFactory.js";
 import { NodePeerAddressStore } from "./NodePeerAddressStore.js";
 
+const logger = Logger.get("ClientNodes");
+
 const DEFAULT_TTL = 900 * 1000;
 const EXPIRATION_INTERVAL = 60 * 1000;
 
@@ -27,7 +29,9 @@ const EXPIRATION_INTERVAL = 60 * 1000;
  * Remote nodes are either peers (commissioned into a fabric we share) or commissionable.
  */
 export class ClientNodes extends EndpointContainer<ClientNode> {
-    #expirationInterval: CancelablePromise | undefined;
+    #expirationInterval?: CancelablePromise;
+    #expirationWorker?: Promise<void>;
+    #closed = false;
 
     constructor(owner: ServerNode) {
         super(owner);
@@ -79,23 +83,8 @@ export class ClientNodes extends EndpointContainer<ClientNode> {
     /**
      * Find a specific commissionable node and commission.
      */
-    commission(passcode: number, discriminator?: number): Promise<ClientNode>;
-
-    /**
-     * Find a specific commissionable node and commission.
-     */
-    commission(options: CommissioningDiscovery.Options): Promise<ClientNode>;
-
-    commission(optionsOrPasscode: CommissioningDiscovery.Options | number, discriminator?: number) {
-        if (typeof optionsOrPasscode !== "object") {
-            optionsOrPasscode = { passcode: optionsOrPasscode };
-        }
-
-        if (discriminator !== undefined) {
-            (optionsOrPasscode as { longDiscriminator: number }).longDiscriminator = discriminator;
-        }
-
-        return new CommissioningDiscovery(this.owner, optionsOrPasscode);
+    commission(options: CommissioningDiscovery.Options) {
+        return new CommissioningDiscovery(this.owner, options);
     }
 
     override get(id: string | PeerAddress) {
@@ -124,7 +113,9 @@ export class ClientNodes extends EndpointContainer<ClientNode> {
     }
 
     override async close() {
+        this.#closed = true;
         this.#cancelExpiration();
+        await this.#expirationWorker;
         await super.close();
     }
 
@@ -136,6 +127,10 @@ export class ClientNodes extends EndpointContainer<ClientNode> {
     }
 
     #manageExpiration() {
+        if (this.#closed || this.#expirationWorker) {
+            return;
+        }
+
         if (this.#expirationInterval) {
             if (!this.size) {
                 this.#cancelExpiration();
@@ -147,14 +142,21 @@ export class ClientNodes extends EndpointContainer<ClientNode> {
             return;
         }
 
-        this.#expirationInterval = Time.sleep("client node expiration", EXPIRATION_INTERVAL).then(async () => {
-            this.#expirationInterval = undefined;
-            try {
-                await this.#cullExpiredNodesAndAddresses();
-            } finally {
+        this.#expirationInterval = Time.sleep("client node expiration", EXPIRATION_INTERVAL).then(
+            this.#onExpirationIntervalElapsed.bind(this),
+        );
+    }
+
+    #onExpirationIntervalElapsed() {
+        this.#expirationInterval = undefined;
+        this.#expirationWorker = this.#cullExpiredNodesAndAddresses()
+            .catch(error => {
+                logger.error("Error culling expired nodes", error);
+            })
+            .finally(() => {
+                this.#expirationWorker = undefined;
                 this.#manageExpiration();
-            }
-        });
+            });
     }
 
     async #cullExpiredNodesAndAddresses() {
@@ -182,7 +184,7 @@ export class ClientNodes extends EndpointContainer<ClientNode> {
 
             // Cull commissionable nodes that have expired
             if (!isCommissioned) {
-                if (!newAddresses?.length || expirationOf(state) <= now) {
+                if (!newAddresses?.length || (expirationOf(state) ?? 0) <= now) {
                     await node.delete();
                     continue;
                 }