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

package/src/endpoint/Endpoint.ts

@@ -18,12 +18,13 @@ import {
     Lifecycle,
     Logger,
     MaybePromise,
+    toHex,
     UninitializedDependencyError,
 } from "#general";
 import { DataModelPath } from "#model";
+import { ProtocolService } from "#node/integration/ProtocolService.js";
 import type { Node } from "#node/Node.js";
 import { IdentityService } from "#node/server/IdentityService.js";
-import { ProtocolService } from "#node/server/ProtocolService.js";
 import { Val } from "#protocol";
 import { EndpointNumber } from "#types";
 import { RootEndpoint } from "../endpoints/root.js";
@@ -227,7 +228,7 @@ export class Endpoint<T extends EndpointType = EndpointType.Empty> {
 
                 await tx.addResources(behavior);
 
-                const patch = (behavior.constructor as Behavior.Type).supervisor.patch;
+                const patch = behavior.type.supervisor.patch;
 
                 if (typeof vals !== "object") {
                     throw new ImplementationError(
@@ -266,7 +267,7 @@ export class Endpoint<T extends EndpointType = EndpointType.Empty> {
             await tx.begin();
             await tx.addResources(behavior);
 
-            const patch = (behavior.constructor as Behavior.Type).supervisor.patch;
+            const patch = behavior.type.supervisor.patch;
 
             if (typeof values !== "object") {
                 throw new ImplementationError(`State values for ${type.id} must be an object, not ${typeof values}`);
@@ -835,9 +836,14 @@ export class Endpoint<T extends EndpointType = EndpointType.Empty> {
     }
 
     get #diagnosticProps() {
+        const type = this.type;
         return {
             "endpoint#": this.number,
-            type: `${this.type.name} (0x${this.type.deviceType.toString(16)})`,
+            type: `${type.name} (${
+                type.deviceType === EndpointType.UNKNOWN_DEVICE_TYPE
+                    ? "unknown"
+                    : `0x${toHex(type.deviceType)}${type.deviceRevision === EndpointType.UNKNOWN_DEVICE_REVISION ? "" : `, rev ${type.deviceRevision}`}`
+            })`,
         };
     }
 

package/src/endpoint/properties/Behaviors.ts

@@ -27,7 +27,7 @@ import {
     Transaction,
 } from "#general";
 import { FeatureSet } from "#model";
-import { ProtocolService } from "#node/server/ProtocolService.js";
+import { ProtocolService } from "#node/integration/ProtocolService.js";
 import { ClusterTypeProtocol, FabricManager, Val } from "#protocol";
 import { ClusterType, VoidSchema } from "#types";
 import type { Agent } from "../Agent.js";
@@ -63,6 +63,13 @@ export class Behaviors {
         return this.#supported;
     }
 
+    /**
+     * The list of active behaviors.
+     */
+    get active() {
+        return Object.values(this.#backings).map(backing => backing.type);
+    }
+
     get status() {
         const status = {} as Record<string, Lifecycle.Status>;
         for (const key in this.#supported) {
@@ -437,6 +444,12 @@ export class Behaviors {
         if (this.#supported === this.#endpoint.type.behaviors) {
             this.#supported = { ...this.#supported };
         }
+
+        // TODO how to better solve that?
+        if (this.#endpoint.env.has(EndpointInitializer)) {
+            type = this.#endpoint.env.get(EndpointInitializer).finalizeType(type);
+        }
+
         this.#supported[type.id] = type;
 
         this.#augmentEndpoint(type);
@@ -640,7 +653,7 @@ export class Behaviors {
         }
 
         const backing = this.#endpoint.env.get(EndpointInitializer).createBacking(this.#endpoint, myType);
-        this.#backings[type.id] = backing;
+        this.#backings[backing.type.id] = backing;
         if (!this.#protocol) {
             this.#protocol = this.#endpoint.env.get(ProtocolService);
         }

package/src/endpoint/properties/ClientNodeEndpoints.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Endpoint, EndpointType } from "#endpoint/index.js";
+import type { ClientNode } from "#node/ClientNode.js";
+import { Endpoints } from "./Endpoints.js";
+
+/**
+ * Access to all endpoints on a client node, including the root endpoint.
+ */
+export class ClientNodeEndpoints extends Endpoints {
+    /**
+     * For nodes where the behavior/cluster structure can not be initialized automatically (e.g. by a subscription) or
+     * when the subscription data misses special clusters, you can use this method to enable a cluster on a specific
+     * endpoint.
+     * The method adds the endpoint, if not existing.
+     */
+    require(endpointId: number, type: Partial<EndpointType> = {}) {
+        if (this.has(endpointId)) {
+            return this.for(endpointId);
+        }
+        const endpoint = new Endpoint({
+            id: `ep${endpointId}`,
+            number: endpointId,
+            type: EndpointType({
+                name: "ClientEndpoint",
+                deviceType: EndpointType.UNKNOWN_DEVICE_TYPE,
+                deviceRevision: EndpointType.UNKNOWN_DEVICE_REVISION,
+                ...type,
+            }),
+        });
+        (this.node as ClientNode).parts.add(endpoint);
+        return endpoint;
+    }
+}

package/src/endpoint/properties/EndpointInitializer.ts

@@ -41,4 +41,11 @@ export abstract class EndpointInitializer {
      * Invoked after behaviors are initialized but before the initialization transaction commits.
      */
     behaviorsInitialized(_agent: Agent) {}
+
+    /**
+     * Allows Initializer to manipulate the type before it is used to create a backing or behavior.
+     */
+    finalizeType(type: Behavior.Type): Behavior.Type {
+        return type;
+    }
 }

package/src/endpoint/properties/Endpoints.ts

@@ -21,6 +21,10 @@ export class Endpoints implements ImmutableSet<Endpoint> {
         this.#node = node;
     }
 
+    protected get node(): Node {
+        return this.#node;
+    }
+
     has(endpoint: Endpoint | number): boolean {
         if (endpoint === this.#node || endpoint === 0) {
             return true;

package/src/endpoint/type/EndpointType.ts

@@ -33,6 +33,9 @@ export function EndpointType<const T extends EndpointType.Options>(options: T) {
 }
 
 export namespace EndpointType {
+    export const UNKNOWN_DEVICE_TYPE = DeviceTypeId(-1, false);
+    export const UNKNOWN_DEVICE_REVISION = -1;
+
     /**
      * An endpoint type with no behaviors or requirements.
      */

package/src/node/ClientNode.ts

@@ -10,13 +10,14 @@ import { ClientNetworkRuntime } from "#behavior/system/network/ClientNetworkRunt
 import { NetworkClient } from "#behavior/system/network/NetworkClient.js";
 import { NetworkRuntime } from "#behavior/system/network/NetworkRuntime.js";
 import { Agent } from "#endpoint/Agent.js";
+import { ClientNodeEndpoints } from "#endpoint/properties/ClientNodeEndpoints.js";
 import { EndpointInitializer } from "#endpoint/properties/EndpointInitializer.js";
 import { Diagnostic, Identity, Lifecycle, Logger, MaybePromise } from "#general";
+import { Matter, MatterModel } from "#model";
 import { Interactable, OccurrenceManager, PeerAddress } from "#protocol";
 import { ClientNodeStore } from "#storage/client/ClientNodeStore.js";
 import { RemoteWriter } from "#storage/client/RemoteWriter.js";
 import { ServerNodeStore } from "#storage/server/ServerNodeStore.js";
-import { Matter, MatterModel } from "@matter/model";
 import { ClientEndpointInitializer } from "./client/ClientEndpointInitializer.js";
 import { ClientNodeInteraction } from "./client/ClientNodeInteraction.js";
 import { Node } from "./Node.js";
@@ -44,7 +45,7 @@ export class ClientNode extends Node<ClientNode.RootEndpoint> {
         super(opts);
 
         // Block the OccurrenceManager from parent environment so we don't attempt to record events from peers
-        this.env.block(OccurrenceManager);
+        this.env.close(OccurrenceManager);
 
         this.env.set(Node, this);
         this.env.set(ClientNode, this);
@@ -61,6 +62,10 @@ export class ClientNode extends Node<ClientNode.RootEndpoint> {
         return this.#matter;
     }
 
+    override get endpoints(): ClientNodeEndpoints {
+        return new ClientNodeEndpoints(this);
+    }
+
     override initialize() {
         const store = this.env.get(ServerNodeStore).clientStores.storeForNode(this);
 

package/src/node/Node.ts

@@ -28,7 +28,7 @@ import { Interactable } from "#protocol";
 import type { EndpointNumber } from "#types";
 import { RootEndpoint } from "../endpoints/root.js";
 import { NodeLifecycle } from "./NodeLifecycle.js";
-import { ProtocolService } from "./server/ProtocolService.js";
+import { ProtocolService } from "./integration/ProtocolService.js";
 
 const logger = Logger.get("Node");
 

package/src/node/NodeLifecycle.ts

@@ -15,7 +15,7 @@ import { AsyncObservable, Mutex, Observable } from "#general";
 export class NodeLifecycle extends EndpointLifecycle {
     #online = AsyncObservable<[context: ActionContext]>();
     #goingOffline = AsyncObservable<[context: ActionContext]>();
-    #offline = Observable<[context: ActionContext]>();
+    #offline = AsyncObservable<[context: ActionContext]>();
     #commissioned = Observable<[context: ActionContext]>();
     #decommissioned = Observable<[context: ActionContext]>();
     #initialized = Observable<[isCommissioned: boolean]>();

package/src/node/client/ClientEndpointInitializer.ts

@@ -11,9 +11,12 @@ import { ClientBehaviorBacking } from "#behavior/internal/ClientBehaviorBacking.
 import { ServerBehaviorBacking } from "#behavior/internal/ServerBehaviorBacking.js";
 import { Endpoint } from "#endpoint/Endpoint.js";
 import { EndpointInitializer } from "#endpoint/properties/EndpointInitializer.js";
+import { FeatureBitmap } from "#model";
+import { ClientBehavior } from "#node/client/ClientBehavior.js";
 import type { ClientNode } from "#node/ClientNode.js";
 import { ClientNodeStore } from "#storage/client/ClientNodeStore.js";
 import { NodeStore } from "#storage/NodeStore.js";
+import { AttributeId, CommandId } from "#types";
 import { ClientStructure } from "./ClientStructure.js";
 
 export class ClientEndpointInitializer extends EndpointInitializer {
@@ -57,6 +60,41 @@ export class ClientEndpointInitializer extends EndpointInitializer {
         return new ClientBehaviorBacking(endpoint, type, store, endpoint.behaviors.optionsFor(type));
     }
 
+    /** Convert the Cluster type to a ClientBehavior */
+    override finalizeType(type: Behavior.Type): Behavior.Type {
+        const cluster = (type as ClusterBehavior.Type).cluster;
+        if (cluster === undefined) {
+            return type;
+        }
+
+        const features: FeatureBitmap = {};
+        for (const f in cluster.features) {
+            features[f] = true;
+        }
+        const attributeNames = new Array<string>();
+        const attributes = new Array<AttributeId>();
+        for (const [name, attr] of Object.entries(cluster.attributes)) {
+            attributeNames.push(name);
+            attributes.push(attr.id);
+        }
+        const commandNames = new Array<string>();
+        const commands = new Array<CommandId>();
+        for (const [name, cmd] of Object.entries(cluster.commands)) {
+            commandNames.push(name);
+            commands.push(cmd.requestId);
+        }
+
+        return ClientBehavior({
+            id: cluster.id,
+            revision: cluster.revision,
+            features,
+            attributes,
+            commands,
+            attributeNames,
+            commandNames,
+        });
+    }
+
     get structure() {
         if (this.#structure === undefined) {
             this.#structure = new ClientStructure(this.#node);

package/src/node/client/ClientEventEmitter.ts

@@ -4,13 +4,13 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { ElementEvent, Events } from "#behavior/Events.js";
+import type { ElementEvent, Events } from "#behavior/Events.js";
 import { camelize, Logger } from "#general";
 import { ClusterModel, EventModel, MatterModel } from "#model";
-import { ClientNode } from "#node/ClientNode.js";
-import { ReadResult } from "#protocol";
-import { ClusterId, EndpointNumber, EventId } from "#types";
-import { ClientStructure } from "./ClientStructure.js";
+import type { ClientNode } from "#node/ClientNode.js";
+import type { ReadResult } from "#protocol";
+import type { ClusterId, EndpointNumber, EventId } from "#types";
+import type { ClientStructure } from "./ClientStructure.js";
 
 const logger = Logger.get("ClientEventEmitter");
 

package/src/node/client/ClientNodeInteraction.ts

@@ -60,6 +60,13 @@ export class ClientNodeInteraction implements Interactable<ActionContext> {
         return interaction.subscribe(intermediateRequest, context);
     }
 
+    cancelSubscription(id: number): void {
+        if (!this.#node.lifecycle.isOnline) {
+            return;
+        }
+        this.#node.env.get(ClientInteraction).cancelSubscription(id);
+    }
+
     async write<T extends Write>(request: T, context?: ActionContext): WriteResult<T> {
         return (await this.#connect()).write(request, context);
     }

package/src/node/client/ClientStructure.ts

@@ -30,8 +30,11 @@ export class ClientStructure {
     #nodeStore: ClientNodeStore;
     #endpoints: Record<EndpointNumber, EndpointStructure> = {};
     #emitEvent: ClientEventEmitter;
+    #node: ClientNode;
+    #subscribedFabricFiltered?: boolean;
 
     constructor(node: ClientNode) {
+        this.#node = node;
         this.#nodeStore = node.env.get(ClientNodeStore);
         this.#endpoints[node.number] = {
             endpoint: node,
@@ -143,9 +146,8 @@ export class ClientStructure {
                     case "event-value":
                         this.#emitEvent(change);
                         break;
-                }
-                if (change.kind !== "attr-value") {
-                    continue;
+
+                    // we ignore attr-status and event-status for now
                 }
             }
 
@@ -157,11 +159,27 @@ export class ClientStructure {
         }
     }
 
+    /** Reference to the default subscription used when the node was started. */
+    protected get subscribedFabricFiltered() {
+        if (this.#subscribedFabricFiltered === undefined) {
+            this.#subscribedFabricFiltered = this.#node.state.network.defaultSubscription?.isFabricFiltered ?? true;
+            this.#node.events.network.defaultSubscription$Changed.on(newSubscription => {
+                this.#subscribedFabricFiltered = newSubscription?.isFabricFiltered ?? true;
+            });
+        }
+        return this.#subscribedFabricFiltered;
+    }
+
     async #mutateAttribute(
         change: ReadResult.AttributeValue,
         scope: ReadScope,
         currentUpdates: undefined | AttributeUpdates,
     ) {
+        // We only store values when an initial subscription is defined and the fabric filter matches
+        if (this.subscribedFabricFiltered !== scope.isFabricFiltered) {
+            return currentUpdates;
+        }
+
         const { endpointId, clusterId, attributeId } = change.path;
 
         // If we are building updates to a cluster and the cluster/endpoint changes, apply the current update
@@ -343,8 +361,8 @@ export class ClientStructure {
                 number,
                 type: EndpointType({
                     name: "ClientEndpoint",
-                    deviceType: -1,
-                    deviceRevision: -1,
+                    deviceType: EndpointType.UNKNOWN_DEVICE_TYPE,
+                    deviceRevision: EndpointType.UNKNOWN_DEVICE_REVISION,
                 }),
             }),
             clusters: {},

package/src/node/client/Peers.ts

@@ -10,9 +10,11 @@ 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, Duration, Logger, Minutes, Seconds, Time, Timestamp } from "#general";
-import { PeerAddress, PeerAddressStore } from "#protocol";
+import { CancelablePromise, Duration, ImplementationError, Logger, Minutes, Seconds, Time, Timestamp } from "#general";
+import { InteractionServer } from "#node/index.js";
+import { FabricManager, PeerAddress, PeerAddressStore } from "#protocol";
 import { ServerNodeStore } from "#storage/server/ServerNodeStore.js";
+import { ClientSubscriptionHandler, ClientSubscriptions } from "@matter/protocol";
 import { ClientNode } from "../ClientNode.js";
 import type { ServerNode } from "../ServerNode.js";
 import { ClientNodeFactory } from "./ClientNodeFactory.js";
@@ -31,6 +33,7 @@ const EXPIRATION_INTERVAL = Minutes.one;
 export class Peers extends EndpointContainer<ClientNode> {
     #expirationInterval?: CancelablePromise;
     #expirationWorker?: Promise<void>;
+    #subscriptionHandler?: ClientSubscriptionHandler;
     #closed = false;
 
     constructor(owner: ServerNode) {
@@ -42,7 +45,9 @@ export class Peers extends EndpointContainer<ClientNode> {
 
         this.owner.env.set(PeerAddressStore, new NodePeerAddressStore(owner));
 
-        this.added.on(this.#manageExpiration.bind(this));
+        owner.env.applyTo(InteractionServer, this.#configureInteractionServer.bind(this));
+
+        this.added.on(this.#handlePeerAdded.bind(this));
         this.deleted.on(this.#manageExpiration.bind(this));
     }
 
@@ -92,7 +97,7 @@ export class Peers extends EndpointContainer<ClientNode> {
             const address = PeerAddress(id);
             for (const node of this) {
                 const nodeAddress = node.state.commissioning.peerAddress;
-                if (nodeAddress && PeerAddress(nodeAddress) === address) {
+                if (nodeAddress && PeerAddress.is(nodeAddress, address)) {
                     return node;
                 }
             }
@@ -112,8 +117,37 @@ export class Peers extends EndpointContainer<ClientNode> {
         super.add(node);
     }
 
+    /**
+     * Get or create a client node for the given peer address.
+     * This is mainly used to communicate to other known nodes on the fabric without having a formal commissioning
+     * process.
+     */
+    async forAddress(peerAddress: PeerAddress, options: Omit<ClientNode.Options, "owner"> = {}) {
+        if (!this.owner.env.get(FabricManager).has(peerAddress)) {
+            throw new ImplementationError("Cannot register a peer address for a fabric we do not belong to");
+        }
+
+        let node = this.get(peerAddress);
+        if (!node) {
+            // We do not have that node till now, also not persisted, so create it
+            const factory = this.owner.env.get(ClientNodeFactory);
+            node = factory.create(options);
+            await node.construction;
+            this.add(node);
+
+            // Nodes we do not commission are not auto-subscribed but enabled
+            // But we add the peer address
+            await node.set({
+                commissioning: { peerAddress: PeerAddress(peerAddress) },
+            });
+        }
+
+        return node;
+    }
+
     override async close() {
         this.#closed = true;
+        await this.#subscriptionHandler?.close();
         this.#cancelExpiration();
         await this.#expirationWorker;
         await super.close();
@@ -126,8 +160,40 @@ export class Peers extends EndpointContainer<ClientNode> {
         }
     }
 
+    #handlePeerAdded() {
+        if (this.owner.env.has(InteractionServer)) {
+            this.#configureInteractionServer();
+        }
+        this.#manageExpiration();
+    }
+
+    /**
+     * If required, installs a listener in the environment's {@link InteractionServer} to handle subscription responses.
+     */
+    #configureInteractionServer() {
+        if (this.#closed || this.size > 0 || !this.owner.env.has(InteractionServer)) {
+            return;
+        }
+
+        const subscriptions = this.owner.env.get(ClientSubscriptions);
+        const interactionServer = this.owner.env.get(InteractionServer);
+
+        if (!this.#subscriptionHandler) {
+            this.#subscriptionHandler = new ClientSubscriptionHandler(subscriptions);
+        }
+
+        interactionServer.clientHandler = this.#subscriptionHandler;
+    }
+
+    /**
+     * Enables or disables the expiration timer that culls expired uncommissioned nodes.
+     */
     #manageExpiration() {
-        if (this.#closed || this.#expirationWorker) {
+        if (this.#closed) {
+            return;
+        }
+
+        if (this.#expirationWorker) {
             return;
         }
 

package/src/node/index.ts

@@ -5,6 +5,7 @@
  */
 
 export * from "./client/index.js";
+export * from "./integration/index.js";
 export * from "./Node.js";
 export * from "./NodeLifecycle.js";
 export * from "./server/index.js";

package/src/node/integration/ChangeNotificationService.ts

@@ -0,0 +1,122 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Behavior } from "#behavior/Behavior.js";
+import type { BehaviorBacking } from "#behavior/internal/BehaviorBacking.js";
+import type { Endpoint } from "#endpoint/Endpoint.js";
+import { EndpointLifecycle } from "#endpoint/properties/EndpointLifecycle.js";
+import { InternalError, Observable, ObserverGroup } from "#general";
+import type { Node } from "#node/Node.js";
+import type { ServerNode } from "#node/ServerNode.js";
+
+/**
+ * High-level change notification service.
+ *
+ * This service provides an optimized path to detecting property changes for all endpoints associated with a node.  This
+ * includes endpoints on peers.
+ */
+export class ChangeNotificationService {
+    #change = new Observable<[changes: ChangeNotificationService.Change]>();
+    #observers = new Map<Node, ObserverGroup>();
+
+    constructor(node: ServerNode) {
+        this.#beginNodeObservation(node);
+
+        if (node.lifecycle.isReady) {
+            this.#beginPeerObservation(node);
+        } else {
+            node.lifecycle.ready.once(() => this.#beginPeerObservation(node));
+        }
+    }
+
+    /**
+     * Change event source.
+     */
+    get change() {
+        return this.#change;
+    }
+
+    /**
+     * Invoked by the {@link BehaviorBacking} when state changes.
+     */
+    broadcastUpdate(backing: BehaviorBacking, properties: string[]) {
+        const { endpoint, type: behavior } = backing;
+        this.#change.emit({
+            kind: "update",
+            endpoint,
+            behavior,
+            version: backing.datasource.version,
+            properties,
+        });
+    }
+
+    close() {
+        for (const observers of this.#observers.values()) {
+            observers.close();
+        }
+        this.#observers.clear();
+    }
+
+    #beginNodeObservation(node: Node) {
+        const observers = new ObserverGroup();
+        this.#observers.set(node, observers);
+
+        observers.on(node.lifecycle.changed, (type, endpoint) => {
+            switch (type) {
+                case EndpointLifecycle.Change.Destroyed:
+                    this.#change.emit({
+                        kind: "delete",
+                        endpoint,
+                    });
+                    if (endpoint == node) {
+                        observers.close();
+                        this.#observers.delete(node);
+                    }
+                    break;
+            }
+        });
+    }
+
+    #beginPeerObservation(node: ServerNode) {
+        const observers = this.#observers.get(node);
+
+        if (observers === undefined) {
+            throw new InternalError("Change notification initialization order is broken");
+        }
+
+        observers.on(node.peers.added, this.#beginNodeObservation.bind(this));
+    }
+}
+
+export namespace ChangeNotificationService {
+    export type Key = string | number;
+
+    /**
+     * Emits when state changes.
+     *
+     * If present, {@link properties} indicates the specific updated properties.  Otherwise the recipient should
+     * consider all properties.
+     */
+    export interface PropertyUpdate {
+        kind: "update";
+        endpoint: Endpoint;
+        behavior: Behavior.Type;
+        version: number;
+        properties?: string[];
+    }
+
+    /**
+     * Emits when endpoints/nodes are deleted.
+     *
+     * This indicates to the recipient to drop the associated data subtree.
+     */
+    export interface EndpointDelete {
+        kind: "delete";
+        endpoint: Endpoint;
+    }
+
+    export type Change = PropertyUpdate | EndpointDelete;
+}