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

package/src/node/client/ClientStructure.ts

@@ -0,0 +1,339 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ClusterBehavior } from "#behavior/cluster/ClusterBehavior.js";
+import { Datasource } from "#behavior/state/managed/Datasource.js";
+import { DescriptorCluster } from "#clusters/descriptor";
+import { Endpoint } from "#endpoint/Endpoint.js";
+import { EndpointType } from "#endpoint/type/EndpointType.js";
+import { AcceptedCommandList, AttributeList, ClusterRevision, FeatureMap, type FeatureBitmap } from "#model";
+import type { ClientNode } from "#node/ClientNode.js";
+import { ReadScope, type Read, type ReadResult } from "#protocol";
+import { DatasourceCache } from "#storage/client/DatasourceCache.js";
+import { ClientNodeStore } from "#storage/index.js";
+import type { AttributeId, ClusterId, CommandId, DeviceTypeId, EndpointNumber } from "#types";
+import { ClientBehavior } from "./ClientBehavior.js";
+
+const DEVICE_TYPE_LIST_ATTR_ID = DescriptorCluster.attributes.deviceTypeList.id;
+const SERVER_LIST_ATTR_ID = DescriptorCluster.attributes.serverList.id;
+const PARTS_LIST_ATTR_ID = DescriptorCluster.attributes.partsList.id;
+
+/**
+ * Manages endpoint and behavior structure for a single client node.
+ */
+export class ClientStructure {
+    #nodeStore: ClientNodeStore;
+    #endpoints: Record<EndpointNumber, EndpointStructure> = {};
+
+    constructor(node: ClientNode) {
+        this.#nodeStore = node.env.get(ClientNodeStore);
+        this.#endpoints[node.number] = {
+            endpoint: node,
+            clusters: {},
+        };
+    }
+
+    /**
+     * Load initial structure from cache.
+     */
+    loadCache() {
+        for (const store of this.#nodeStore.endpointStores) {
+            const id = store.id;
+
+            // Client storage uses the endpoint number as the key for the endpoint
+            const number = Number.parseInt(id);
+            if (Number.isNaN(number)) {
+                continue;
+            }
+
+            const endpoint = this.#endpointFor(number as EndpointNumber);
+
+            // Load state for each behavior
+            for (const idStr of store.knownBehaviors) {
+                const id = Number.parseInt(idStr) as ClusterId;
+                if (Number.isNaN(id)) {
+                    continue;
+                }
+
+                const cluster = this.#clusterFor(endpoint, id);
+                this.#initializeCluster(endpoint, cluster);
+            }
+        }
+    }
+
+    /**
+     * Obtain the store for a behavior.
+     */
+    storeFor(endpoint: Endpoint, type: ClusterBehavior.Type) {
+        const endpointStructure = this.#endpointFor(endpoint.number);
+        const clusterStructure = this.#clusterFor(endpointStructure, type.cluster.id);
+
+        return clusterStructure.store;
+    }
+
+    /**
+     * Inject version filters into a Read or Subscribe request.
+     */
+    injectVersionFilters<T extends Read>(request: T): T {
+        const scope = ReadScope(request);
+        let result = request;
+
+        for (const {
+            endpoint: { number: endpointId },
+            clusters,
+        } of Object.values(this.#endpoints)) {
+            for (const {
+                id: clusterId,
+                store: { version },
+            } of Object.values(clusters)) {
+                if (!scope.isRelevant(endpointId, clusterId)) {
+                    continue;
+                }
+
+                if (version === Datasource.UNKNOWN_VERSION) {
+                    continue;
+                }
+
+                if (result === request) {
+                    result = { ...request };
+                }
+
+                if (result.dataVersionFilters === undefined) {
+                    result.dataVersionFilters = [];
+                }
+
+                result.dataVersionFilters.push({ path: { endpointId, clusterId }, dataVersion: version });
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Update the node structure by applying attribute changes.
+     */
+    async *mutate(request: Read, changes: ReadResult) {
+        const scope = ReadScope(request);
+
+        let currentUpdates: AttributeUpdates | undefined;
+
+        for await (const chunk of changes) {
+            for (const change of chunk) {
+                if (change.kind !== "attr-value") {
+                    continue;
+                }
+
+                const { endpointId, clusterId, attributeId } = change.path;
+
+                // If we are building updates to a cluster and the cluster/endpoint changes, apply the current update
+                // set
+                if (
+                    currentUpdates &&
+                    (currentUpdates.endpointId !== endpointId || currentUpdates.clusterId !== clusterId)
+                ) {
+                    await this.#updateCluster(currentUpdates);
+                    currentUpdates = undefined;
+                }
+
+                if (currentUpdates === undefined) {
+                    // Updating a new endpoint/cluster
+                    currentUpdates = {
+                        endpointId,
+                        clusterId,
+                        values: {
+                            [attributeId]: change.value,
+                        },
+                    };
+
+                    // Update version but only if this was a wildcard read
+                    if (scope.isWildcard(endpointId, clusterId)) {
+                        currentUpdates.values[DatasourceCache.VERSION_KEY] = change.version;
+                    }
+                } else {
+                    // Add value to change set for current endpoint/cluster
+                    currentUpdates.values[attributeId] = change.value;
+                }
+            }
+
+            yield chunk;
+        }
+
+        if (currentUpdates) {
+            await this.#updateCluster(currentUpdates);
+        }
+    }
+
+    /**
+     * Apply new attribute values for specific endpoint/cluster.
+     *
+     * This is invoked in a batch when we've collected all sequential values for the current endpoint/cluster.
+     */
+    async #updateCluster(attrs: AttributeUpdates) {
+        const endpoint = this.#endpointFor(attrs.endpointId);
+        const cluster = this.#clusterFor(endpoint, attrs.clusterId);
+        await cluster.store.externalSet(attrs.values);
+        this.#initializeCluster(endpoint, cluster);
+    }
+
+    /**
+     * If enough attributes are present, installs a behavior on an endpoint
+     *
+     * If the cluster is Descriptor, performs additional {@link Endpoint} configuration such as installing parts and
+     * device types.
+     *
+     * Invoked once we've loaded all attributes in an interaction.
+     */
+    #initializeCluster(endpoint: EndpointStructure, cluster: ClusterStructure) {
+        const attrs = cluster.store.initialValues ?? {};
+
+        // Generate a behavior if enough information is available
+        if (cluster.behavior === undefined) {
+            const {
+                [ClusterRevision.id]: clusterRevision,
+                [FeatureMap.id]: features,
+                [AttributeList.id]: attributeList,
+                [AcceptedCommandList.id]: commandList,
+            } = attrs;
+
+            if (typeof clusterRevision === "number") {
+                cluster.revision = clusterRevision;
+            }
+
+            if (typeof features === "object" && features !== null && !Array.isArray(features)) {
+                cluster.features = features as FeatureBitmap;
+            }
+
+            if (Array.isArray(attributeList)) {
+                cluster.attributes = attributeList.filter(attr => typeof attr === "number") as AttributeId[];
+            }
+
+            if (Array.isArray(commandList)) {
+                cluster.commands = commandList.filter(cmd => typeof cmd === "number") as CommandId[];
+            }
+
+            if (
+                cluster.revision !== undefined &&
+                cluster.features !== undefined &&
+                cluster.attributes !== undefined &&
+                cluster.commands !== undefined
+            ) {
+                cluster.behavior = ClientBehavior(cluster as ClientBehavior.ClusterShape);
+                endpoint.endpoint.behaviors.require(cluster.behavior);
+            }
+        }
+
+        // Special handling for descriptor cluster
+        if (cluster.id === DescriptorCluster.id) {
+            this.#synchronizeDescriptor(endpoint, attrs);
+        }
+    }
+
+    #synchronizeDescriptor(endpoint: EndpointStructure, attrs: Record<number, unknown>) {
+        const deviceTypeList = attrs[DEVICE_TYPE_LIST_ATTR_ID];
+        if (Array.isArray(deviceTypeList) && deviceTypeList?.[0]) {
+            const [{ deviceType, revision }] = deviceTypeList;
+            if (typeof deviceType === "number") {
+                endpoint.endpoint.type.deviceType = deviceType as DeviceTypeId;
+            }
+            if (typeof revision === "number") {
+                endpoint.endpoint.type.deviceRevision = revision;
+            }
+        }
+
+        const serverList = attrs[SERVER_LIST_ATTR_ID];
+        if (Array.isArray(serverList)) {
+            for (const cluster of serverList) {
+                if (typeof cluster === "number") {
+                    this.#clusterFor(endpoint, cluster as ClusterId);
+                }
+            }
+        }
+
+        const partsList = attrs[PARTS_LIST_ATTR_ID];
+        if (Array.isArray(partsList)) {
+            for (const partNo of partsList) {
+                if (typeof partNo !== "number") {
+                    continue;
+                }
+
+                const part = this.#endpointFor(partNo as EndpointNumber);
+
+                let isAlreadyDescendant = false;
+                for (let owner = part.endpoint.owner; owner; owner = owner.owner) {
+                    if (owner === endpoint.endpoint) {
+                        isAlreadyDescendant = true;
+                        break;
+                    }
+                }
+
+                if (isAlreadyDescendant) {
+                    continue;
+                }
+
+                part.endpoint.owner = endpoint.endpoint;
+            }
+        }
+    }
+
+    #endpointFor(number: EndpointNumber) {
+        let endpoint = this.#endpoints[number];
+        if (endpoint) {
+            return endpoint;
+        }
+
+        endpoint = {
+            endpoint: new Endpoint({
+                id: `ep${number}`,
+                number,
+                type: EndpointType({
+                    name: "ClientEndpoint",
+                    deviceType: -1,
+                    deviceRevision: -1,
+                }),
+            }),
+            clusters: {},
+        };
+        this.#endpoints[number] = endpoint;
+
+        return endpoint;
+    }
+
+    #clusterFor(endpoint: EndpointStructure, id: ClusterId) {
+        let cluster = endpoint.clusters[id];
+        if (cluster) {
+            return cluster;
+        }
+
+        cluster = {
+            id,
+            store: this.#nodeStore
+                .storeForEndpoint(endpoint.endpoint)
+                .createStoreForBehavior(id.toString(), DatasourceCache),
+        };
+        endpoint.clusters[id] = cluster;
+
+        return cluster;
+    }
+}
+
+interface AttributeUpdates {
+    endpointId: EndpointNumber;
+    clusterId: ClusterId;
+    values: {
+        [K in number | typeof DatasourceCache.VERSION_KEY]?: unknown;
+    };
+}
+
+interface EndpointStructure {
+    endpoint: Endpoint;
+    clusters: Record<ClusterId, ClusterStructure>;
+}
+
+interface ClusterStructure extends Partial<ClientBehavior.ClusterShape> {
+    id: ClusterId;
+    behavior?: ClusterBehavior.Type;
+    store: Datasource.ExternallyMutableStore;
+}

package/src/node/client/index.ts

@@ -7,4 +7,3 @@
 export * from "./ClientEndpointInitializer.js";
 export * from "./ClientNodes.js";
 export * from "./NodePeerAddressStore.js";
-export * from "./storage/index.js";

package/src/node/index.ts

@@ -9,4 +9,3 @@ export * from "./Node.js";
 export * from "./NodeLifecycle.js";
 export * from "./server/index.js";
 export * from "./ServerNode.js";
-export * from "./storage/index.js";

package/src/node/server/InteractionServer.ts

@@ -60,12 +60,6 @@ import { ServerSubscription, ServerSubscriptionConfig, ServerSubscriptionContext
 
 const logger = Logger.get("InteractionServer");
 
-export const activityKey = Symbol("activity");
-
-export interface WithActivity {
-    [activityKey]?: NodeActivity.Activity;
-}
-
 export interface PeerSubscription {
     subscriptionId: number;
     peerAddress: PeerAddress;
@@ -190,12 +184,12 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
         // Activity tracking.  This provides diagnostic information and prevents the server from shutting down whilst
         // the exchange is active
         using activity = this.#activity.begin(`session#${exchange.session.id.toString(16)}`);
-        (exchange as WithActivity)[activityKey] = activity;
+        (exchange as NodeActivity.WithActivity)[NodeActivity.activityKey] = activity;
 
         // Delegate to InteractionServerMessenger
         return new InteractionServerMessenger(exchange)
             .handleRequest(this)
-            .finally(() => delete (exchange as WithActivity)[activityKey]);
+            .finally(() => delete (exchange as NodeActivity.WithActivity)[NodeActivity.activityKey]);
     }
 
     get aclServer() {
@@ -224,7 +218,7 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
         timed = false,
     ): OnlineContext.Options {
         return {
-            activity: (exchange as WithActivity)[activityKey],
+            activity: (exchange as NodeActivity.WithActivity)[NodeActivity.activityKey],
             fabricFiltered,
             timed,
             message,

package/src/node/server/OnlineServerInteraction.ts

@@ -1,4 +1,4 @@
-import { OnlineContext } from "#behavior/index.js";
+import { OnlineContext } from "#behavior/context/server/OnlineContext.js";
 import { NotImplementedError } from "#general";
 import {
     Interactable,

package/src/node/server/ProtocolService.ts

@@ -11,7 +11,7 @@ import { QuietEvent } from "#behavior/Events.js";
 import type { BehaviorBacking } from "#behavior/internal/BehaviorBacking.js";
 import { Datasource } from "#behavior/state/managed/Datasource.js";
 import { ValueSupervisor } from "#behavior/supervision/ValueSupervisor.js";
-import { DescriptorBehavior } from "#behaviors/descriptor";
+import type { DescriptorBehavior } from "#behaviors/descriptor";
 import type { Endpoint } from "#endpoint/Endpoint.js";
 import {
     camelize,
@@ -230,7 +230,7 @@ class EndpointState {
         const cluster = new ClusterState(type, backing);
 
         // When descriptor behavior initializes, sync device types
-        if (backing.type.id === DescriptorBehavior.id) {
+        if (backing.type.id === "descriptor") {
             this.#updateDeviceTypes(backing.endpoint.state.descriptor.deviceTypeList);
             (backing.events as DescriptorBehavior["events"]).deviceTypeList$Changed.on(
                 this.#updateDeviceTypes.bind(this),

package/src/{endpoint → node}/server/ServerEndpointInitializer.ts

@@ -10,8 +10,8 @@ import { ServerBehaviorBacking } from "#behavior/internal/ServerBehaviorBacking.
 import { Endpoint } from "#endpoint/Endpoint.js";
 import { EndpointInitializer } from "#endpoint/properties/EndpointInitializer.js";
 import { Environment, InternalError, Logger } from "#general";
+import { ServerNodeStore } from "#storage/server/ServerNodeStore.js";
 import { DescriptorServer } from "../../behaviors/descriptor/DescriptorServer.js";
-import { ServerNodeStore } from "../../node/storage/ServerNodeStore.js";
 
 const logger = Logger.get("BehaviorInit");
 
@@ -30,7 +30,10 @@ export class ServerEndpointInitializer extends EndpointInitializer {
 
         this.#store.endpointStores.assignNumber(endpoint);
 
-        endpoint.behaviors.require(DescriptorServer);
+        // DescriptorServer is mandatory but we don't include it in generated device types
+        if (!(DescriptorServer.id in endpoint.behaviors.supported)) {
+            endpoint.behaviors.inject(DescriptorServer);
+        }
     }
 
     async eraseDescendant(endpoint: Endpoint) {

package/src/node/server/ServerEnvironment.ts

@@ -5,12 +5,13 @@
  */
 
 import { limitNodeDataToAllowedFabrics } from "#behavior/cluster/FabricScopedDataHandler.js";
-import { EndpointInitializer } from "#endpoint/index.js";
-import { ServerEndpointInitializer } from "#endpoint/server/ServerEndpointInitializer.js";
+import { EndpointInitializer } from "#endpoint/properties/EndpointInitializer.js";
 import { Crypto, Observable } from "#general";
+import { ServerEndpointInitializer } from "#node/server/ServerEndpointInitializer.js";
 import type { ServerNode } from "#node/ServerNode.js";
-import { ServerNodeStore } from "#node/storage/ServerNodeStore.js";
 import { FabricManager, SessionManager } from "#protocol";
+import { NodeStore } from "#storage/NodeStore.js";
+import { ServerNodeStore } from "#storage/server/ServerNodeStore.js";
 import { IdentityService } from "./IdentityService.js";
 
 /**
@@ -24,7 +25,9 @@ export namespace ServerEnvironment {
         const { env } = node;
 
         // Install support services
-        env.set(ServerNodeStore, await ServerNodeStore.create(env, node.id));
+        const store = await ServerNodeStore.create(env, node.id);
+        env.set(NodeStore, store);
+        env.set(ServerNodeStore, store);
         env.set(EndpointInitializer, new ServerEndpointInitializer(env));
         env.set(IdentityService, new IdentityService(node));
 

package/src/node/server/ServerSubscription.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { NodeActivity } from "#behavior/context/NodeActivity.js";
 import { OnlineContext } from "#behavior/context/server/OnlineContext.js";
 import { Logger, MatterError, NetworkError, NoResponseTimeoutError, ObserverGroup, Time, Timer } from "#general";
 import { Specification } from "#model";
@@ -31,7 +32,6 @@ import {
     StatusCode,
     StatusResponseError,
 } from "#types";
-import { WithActivity, activityKey } from "./InteractionServer.js";
 
 const logger = Logger.get("ServerSubscription");
 
@@ -614,7 +614,7 @@ export class ServerSubscription extends Subscription {
         };
 
         const session = OnlineContext({
-            activity: (exchange as WithActivity)[activityKey],
+            activity: (exchange as NodeActivity.WithActivity)[NodeActivity.activityKey],
             fabricFiltered: request.isFabricFiltered,
             message: {} as Message,
             exchange,

package/src/node/server/index.ts

@@ -6,4 +6,5 @@
 
 export * from "./InteractionServer.js";
 export * from "./ProtocolService.js";
+export * from "./ServerEndpointInitializer.js";
 export * from "./ServerSubscription.js";

package/src/storage/EndpointStore.ts

@@ -0,0 +1,127 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Datasource } from "#behavior/state/managed/Datasource.js";
+import { StorageContext, SupportedStorageTypes } from "#general";
+import { Val } from "#protocol";
+import { DatasourceStore } from "./server/DatasourceStore.js";
+
+/**
+ * Persistence for state values associated with a specific endpoint.
+ */
+export class EndpointStore {
+    protected initialValues = {} as Record<string, Val.Struct>;
+
+    #storage: StorageContext;
+
+    #knownBehaviors = new Set<string>();
+
+    constructor(storage: StorageContext) {
+        this.#storage = storage;
+    }
+
+    /**
+     * Retrieve the primary key used to identify this store.
+     */
+    get id() {
+        return this.storage.thisContexts[this.storage.thisContexts.length - 1];
+    }
+
+    /**
+     * Create a {@link Datasource.Store} for a behavior.
+     */
+    createStoreForBehavior<T extends DatasourceStore.Type>(behaviorId: string, factory: T): ReturnType<T> {
+        const initialValues = this.initialValues[behaviorId];
+        if (initialValues !== undefined) {
+            delete this.initialValues[behaviorId];
+        }
+
+        return factory(this, behaviorId, initialValues) as ReturnType<T>;
+    }
+
+    /**
+     * Patch values.  Keyed by {@link Behavior.id} then property name.
+     *
+     * See {@link Datasource.Store.set} for the patch semantics the individual structs use.
+     */
+    async set(values: Record<string, undefined | Val.Struct>) {
+        for (const behaviorId in values) {
+            const behaviorValues = values[behaviorId];
+            const behaviorStorage = this.storage.createContext(behaviorId);
+
+            if (behaviorValues === undefined) {
+                if (this.knownBehaviors.has(behaviorId)) {
+                    await behaviorStorage.clearAll();
+                    this.knownBehaviors.delete(behaviorId);
+                }
+                continue;
+            }
+
+            if (!this.knownBehaviors.has(behaviorId)) {
+                this.knownBehaviors.add(behaviorId);
+            }
+
+            const toSave = {} as Record<string, SupportedStorageTypes>;
+            let keysToSave = 0;
+            for (const key in behaviorValues) {
+                const value = behaviorValues[key];
+                if (value === undefined) {
+                    await behaviorStorage.delete(key);
+                } else {
+                    toSave[key] = value as SupportedStorageTypes;
+                    keysToSave++;
+                }
+            }
+            if (keysToSave > 0) {
+                await behaviorStorage.set(toSave);
+            }
+        }
+    }
+
+    /**
+     * Description used in diagnostic messages.
+     */
+    toString() {
+        return `storage:${this.#storage.thisContexts.join(".")}`;
+    }
+
+    /**
+     * IDs for behaviors persisted in this store.
+     */
+    get knownBehaviors() {
+        return this.#knownBehaviors;
+    }
+
+    /**
+     * Load the store with persisted values.
+     */
+    async load() {
+        this.#knownBehaviors = new Set(await this.storage.contexts());
+
+        for (const behaviorId of this.#knownBehaviors) {
+            const behaviorValues = (this.initialValues[behaviorId] = {} as Val.Struct);
+            const behaviorStorage = this.storage.createContext(behaviorId);
+
+            const storedValues = await behaviorStorage.values();
+            for (const [key, value] of Object.entries(storedValues)) {
+                if (value !== undefined) {
+                    behaviorValues[key] = value;
+                }
+            }
+        }
+    }
+
+    /**
+     * Remove all persisted information for the {@link Endpoint}
+     */
+    erase() {
+        return this.storage.clearAll();
+    }
+
+    protected get storage() {
+        return this.#storage;
+    }
+}

package/src/storage/NodeStore.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Endpoint } from "#endpoint/Endpoint.js";
+import { Construction, MaybePromise, StorageContextFactory } from "#general";
+import type { Node } from "../node/Node.js";
+import { EndpointStore } from "./EndpointStore.js";
+
+/**
+ * Non-volatile state management for a {@link Node}.
+ *
+ * We eagerly load all available data from disk on startup.  This prevents storage from forcing asynchronous
+ * {@link Endpoint} initialization.  We then can initialize most behaviors synchronously.
+ */
+export abstract class NodeStore {
+    #storageFactory: StorageContextFactory;
+    #construction: Construction<NodeStore>;
+
+    get construction() {
+        return this.#construction;
+    }
+
+    constructor(storageFactory: StorageContextFactory) {
+        this.#storageFactory = storageFactory;
+        this.#construction = Construction(this);
+    }
+
+    toString() {
+        return "node store";
+    }
+
+    [Construction.construct]() {
+        return this.load();
+    }
+
+    abstract storeForEndpoint(endpoint: Endpoint): EndpointStore;
+
+    abstract erase(): MaybePromise<void>;
+
+    protected abstract load(): MaybePromise<void>;
+
+    protected createStorageContext(name: string) {
+        return this.#storageFactory.createContext(name);
+    }
+
+    protected get storageFactory() {
+        return this.#storageFactory;
+    }
+}