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

package/src/node/{server → integration}/ProtocolService.ts

@@ -7,7 +7,6 @@
 import type { Behavior } from "#behavior/Behavior.js";
 import { ClusterBehavior } from "#behavior/cluster/ClusterBehavior.js";
 import { ActionContext } from "#behavior/context/ActionContext.js";
-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";
@@ -21,7 +20,6 @@ import {
     Logger,
     MaybePromise,
     Observable,
-    ObserverGroup,
     Transaction,
 } from "#general";
 import { AcceptedCommandList, AttributeList, ElementTag, GeneratedCommandList, Matter } from "#model";
@@ -55,10 +53,6 @@ import {
 
 const logger = Logger.get("ProtocolService");
 
-interface DisposableClusterProtocol extends ClusterProtocol {
-    [Symbol.dispose]: () => void;
-}
-
 /**
  * Protocol view of a {@link Node}
  *
@@ -74,6 +68,9 @@ export class ProtocolService {
         this.#state = new NodeState(node);
     }
 
+    /**
+     * Invoked by a backing when initialized.
+     */
     addCluster(backing: BehaviorBacking) {
         const { schema } = backing.type;
         if (schema?.tag !== ElementTag.Cluster || schema.id === undefined) {
@@ -83,12 +80,35 @@ export class ProtocolService {
         this.#state.stateFor(backing.endpoint).addCluster(backing);
     }
 
+    /**
+     * Invoked by a backing when closed.
+     */
     deleteCluster(backing: BehaviorBacking) {
         if (this.#state.hasEndpoint(backing.endpoint)) {
             this.#state.stateFor(backing.endpoint).deleteCluster(backing);
         }
     }
 
+    /**
+     * Invoked by a backing when there is a state change.
+     *
+     * This optimized path allows us to broadcast state changes without registering observers for every change.
+     */
+    handleChange(backing: BehaviorBacking, props: string[]) {
+        const clusterId = backing.type.schema?.id as ClusterId | undefined;
+        if (clusterId === undefined) {
+            return;
+        }
+
+        const namesToIds = backing.type.supervisor.propertyNamesAndIds;
+        const attrs = props.map(name => namesToIds.get(name)).filter(id => id !== undefined);
+
+        this.protocol.attrsChanged.emit(backing.endpoint.number, clusterId, attrs, backing.datasource.version);
+    }
+
+    /**
+     * The {@link NodeProtocol}.
+     */
     get protocol() {
         return this.#state.protocol;
     }
@@ -109,10 +129,6 @@ class NodeState {
     readonly protocol: NodeProtocol;
     readonly #endpoints = new Set<EndpointProtocol>();
     readonly #endpointStates = {} as Record<EndpointNumber, EndpointState>;
-    readonly #endpointStateObservers = new Map<
-        EndpointNumber,
-        (clusterId: ClusterId, changes: AttributeId[], version: number) => void
-    >();
 
     constructor(node: Node) {
         let fabrics: FabricManager | undefined;
@@ -137,7 +153,7 @@ class NodeState {
 
             [Symbol.iterator]: this.#endpoints[Symbol.iterator].bind(this.#endpoints),
 
-            stateChanged: new Observable<
+            attrsChanged: new Observable<
                 [endpointId: EndpointNumber, clusterId: ClusterId, changes: AttributeId[], version: number]
             >(),
 
@@ -166,11 +182,6 @@ class NodeState {
         this.protocol[number] = state.protocol;
         this.#endpoints.add(state.protocol);
         this.#endpointStates[number] = state;
-        const observer = (clusterId: ClusterId, changes: AttributeId[], version: number) => {
-            this.protocol.stateChanged.emit(number, clusterId, changes, version);
-        };
-        state.stateChanged.on(observer);
-        this.#endpointStateObservers.set(number, observer);
 
         return state;
     }
@@ -180,11 +191,6 @@ class NodeState {
     }
 
     deleteEndpoint(endpoint: EndpointProtocol) {
-        const observer = this.#endpointStateObservers.get(endpoint.id);
-        if (observer) {
-            this.#endpointStates[endpoint.id].stateChanged.off(observer);
-            this.#endpointStateObservers.delete(endpoint.id);
-        }
         delete this.protocol[endpoint.id];
         this.#endpoints.delete(endpoint);
         delete this.#endpointStates[endpoint.id];
@@ -195,9 +201,7 @@ class EndpointState {
     readonly protocol: EndpointProtocol;
     readonly #node: NodeState;
     readonly #activeClusters = new Set<ClusterId>();
-    readonly #clusters = new Set<DisposableClusterProtocol>();
-    readonly #clusterStateObservers = new Map<ClusterId, (changes: AttributeId[], version: number) => void>();
-    readonly stateChanged = new Observable<[clusterId: ClusterId, changes: AttributeId[], version: number]>();
+    readonly #clusters = new Set<ClusterProtocol>();
 
     constructor(node: NodeState, endpoint: Endpoint) {
         this.#node = node;
@@ -241,17 +245,12 @@ class EndpointState {
         this.#activeClusters.add(cluster.type.id);
         this.#clusters.add(cluster);
 
-        const stateObserver = (changes: AttributeId[], version: number) =>
-            this.stateChanged.emit(cluster.type.id, changes, version);
-        cluster.stateChanged.on(stateObserver);
-        this.#clusterStateObservers.set(cluster.type.id, stateObserver);
-
         // Cluster added, emit all attributes as changed
         const attrs = [...cluster.type.attributes]
-            .filter(attr => attr.limits.readable && !attr.changesOmitted && !attr.quieter)
+            .filter(attr => attr.limits.readable && !attr.changesOmitted)
             .map(attr => attr.id);
         if (attrs.length) {
-            this.stateChanged.emit(cluster.type.id, attrs, cluster.version);
+            this.#node.protocol.attrsChanged.emit(this.protocol.id, cluster.type.id, attrs, cluster.version);
         }
     }
 
@@ -266,17 +265,11 @@ class EndpointState {
             return;
         }
 
-        const stateObserver = this.#clusterStateObservers.get(id as ClusterId);
-        const protocol = this.protocol[id] as DisposableClusterProtocol;
+        const protocol = this.protocol[id];
         if (protocol) {
-            if (stateObserver) {
-                protocol.stateChanged.off(stateObserver);
-            }
-            protocol[Symbol.dispose]();
             this.#clusters.delete(protocol);
             delete this.protocol[id];
         }
-        this.#clusterStateObservers.delete(id as ClusterId);
 
         this.#activeClusters.delete(id as ClusterId);
 
@@ -290,12 +283,10 @@ class EndpointState {
     }
 }
 
-class ClusterState implements DisposableClusterProtocol {
+class ClusterState implements ClusterProtocol {
     readonly type: ClusterTypeProtocol;
     readonly #datasource: Datasource;
     readonly #endpointId: EndpointNumber;
-    readonly #stateChanged = new Observable<[changes: AttributeId[], version: number]>();
-    readonly #quieterObservers = new ObserverGroup();
     readonly commands: Record<CommandId, CommandInvokeHandler> = {};
 
     constructor(type: ClusterTypeProtocol, backing: BehaviorBacking) {
@@ -303,31 +294,6 @@ class ClusterState implements DisposableClusterProtocol {
         this.#datasource = backing.datasource;
         this.#endpointId = backing.endpoint.number;
 
-        const attributeNameToIdMap = backing.type.supervisor.propertyNamesAndIds;
-        // For quieter attributes, we need to use the online events to get real state changes
-        for (const attr of type.attributes) {
-            attributeNameToIdMap.set(attr.name, attr.id);
-            if (attr.quieter) {
-                this.#quieterObservers.on(
-                    (this.#datasource.events[`${attr.name}$Changed`] as unknown as QuietEvent).online,
-                    () => this.stateChanged.emit([attr.id], this.version),
-                );
-            }
-        }
-
-        // Emit all attributes as changed that are not omitted or quieter
-        this.#quieterObservers.on(this.#datasource.changed, (changes: string[], version: number) => {
-            const data = changes
-                .map(name => attributeNameToIdMap.get(name))
-                .filter(
-                    (id): id is AttributeId =>
-                        id !== undefined && !type.attributes[id]?.changesOmitted && !type.attributes[id]?.quieter,
-                );
-            if (data.length) {
-                this.stateChanged.emit(data, version);
-            }
-        });
-
         for (const cmd of type.commands) {
             this.commands[cmd.id] = (args, session) => invokeCommand(backing, cmd, args, session);
         }
@@ -345,10 +311,6 @@ class ClusterState implements DisposableClusterProtocol {
         return this.#datasource.reference(session as ValueSupervisor.Session);
     }
 
-    get stateChanged() {
-        return this.#stateChanged;
-    }
-
     async openForWrite(session: InteractionSession): Promise<Val.ProtocolStruct> {
         if (session.transaction === undefined) {
             throw new ImplementationError("Cluster protocol must be opened with a supervisor session");
@@ -365,10 +327,6 @@ class ClusterState implements DisposableClusterProtocol {
     inspect() {
         return this.toString();
     }
-
-    [Symbol.dispose]() {
-        this.#quieterObservers.close();
-    }
 }
 
 const behaviorCache = new WeakMap<Behavior.Type, Map<string, ClusterTypeProtocol | undefined>>();

package/src/node/integration/StateStream.ts

@@ -0,0 +1,474 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Behavior } from "#behavior/Behavior.js";
+import { Endpoint } from "#endpoint/Endpoint.js";
+import { Abort, deepCopy, Duration, Gate, Millis, Timer } from "#general";
+import { DatatypeModel, FieldElement } from "#model";
+import { Node } from "#node/Node.js";
+import { ServerNode } from "#node/ServerNode.js";
+import { Val } from "#protocol";
+import { EndpointNumber } from "#types";
+import { ChangeNotificationService } from "./ChangeNotificationService.js";
+
+/**
+ * The time from change to notification to change broadcast when transitioning from dormant state.
+ */
+export const DEFAULT_COALESCE_INTERVAL = Millis(250);
+
+/**
+ * A streaming view of node state.
+ *
+ * These streams offer a basic synchronization primitive, delivering state from scratch or from arbitrary version
+ * offsets.
+ *
+ * Each stream tracks a root {@link ServerNode} as well as any available state for known peers.
+ */
+export interface StateStream extends AsyncIterator<StateStream.Change> {}
+
+/**
+ * Open a new stream.
+ */
+export function StateStream(
+    node: ServerNode,
+    { nodes: nodeFilter, clusters: clusterFilter, versions, coalesceInterval, abort }: StateStream.Options = {},
+) {
+    const changeService = node.env.get(ChangeNotificationService);
+
+    // Notification
+    const gate = new Gate();
+    coalesceInterval ??= DEFAULT_COALESCE_INTERVAL;
+    let coalescenceTimer: Timer | undefined;
+
+    // State of each endpoint/behavior
+    const nodes = new Map<string, NodeState>();
+
+    // The linked list of queued updates.  Note that we only queue a given behavior instance once so this queue cannot
+    // grow unbounded
+    let queueHead: QueueEntry | undefined;
+    let queueTail: QueueEntry | undefined;
+
+    // Seed version filters
+    installInitialVersions();
+
+    // Generate filter function
+    const filter = generateFilter();
+
+    return stream();
+
+    /**
+     * Generate events.
+     */
+    async function* stream(): AsyncGenerator<StateStream.Change, void, void> {
+        try {
+            changeService.change.on(changeListener);
+
+            // Enqueue all applicable behaviors
+            for (const n of [node, ...node.peers]) {
+                for (const endpoint of n.endpoints) {
+                    for (const behavior of Object.values(endpoint.behaviors.supported)) {
+                        if (filter && !filter(endpoint.id, behavior.id)) {
+                            continue;
+                        }
+                        enqueue({ node: n, endpoint, behavior });
+                    }
+                }
+            }
+
+            // Send updates
+            while (true) {
+                await Abort.race(abort, gate);
+                if (Abort.is(abort)) {
+                    break;
+                }
+
+                while (queueHead) {
+                    // Yields in this loop are async; so need to check for abort on every iteration
+                    if (Abort.is(abort)) {
+                        break;
+                    }
+
+                    const { node, endpoint, behavior } = queueHead;
+                    dequeue(queueHead);
+
+                    // Endpoint delete
+                    if (!behavior) {
+                        yield { kind: "delete", node, endpoint };
+                        continue;
+                    }
+
+                    // Property update
+                    const state = stateOfBehavior(node.id, endpoint.number, behavior.id);
+                    state.queueEntry = undefined;
+                    let changes = endpoint.stateOf(behavior);
+                    if (state.dirty) {
+                        changes = Object.fromEntries(
+                            [...state.dirty].map(name => [name, (changes as Val.Struct)[name]]),
+                        );
+                        state.dirty = undefined;
+                    } else {
+                        changes = deepCopy(changes);
+                    }
+                    yield {
+                        kind: "update",
+                        node,
+                        endpoint,
+                        behavior,
+                        changes,
+                        version: (state.version = endpoint.behaviors.versionOf(behavior)),
+                    };
+                }
+                gate.close();
+            }
+        } finally {
+            changeService.change.off(changeListener);
+            coalescenceTimer?.stop();
+        }
+    }
+
+    /**
+     * Listener for {@link ChangeNotificationService}.
+     */
+    function changeListener(change: ChangeNotificationService.Change) {
+        switch (change.kind) {
+            case "update":
+                enqueueUpdate(change);
+                break;
+
+            case "delete":
+                enqueueDelete(change);
+                break;
+        }
+    }
+
+    /**
+     * Access an {@link EndpointState}.
+     */
+    function stateOfEndpoint(node: string, endpoint: number) {
+        let nodeState = nodes.get(node);
+        if (nodeState === undefined) {
+            nodes.set(node, (nodeState = new Map()));
+        }
+
+        let endpointState = nodeState.get(endpoint);
+        if (endpointState === undefined) {
+            nodeState.set(endpoint, (endpointState = { behaviors: new Map() }));
+        }
+
+        return endpointState;
+    }
+
+    /**
+     * Access a {@link BehaviorState}.
+     */
+    function stateOfBehavior(node: string, endpoint: number, behavior: string) {
+        const endpointState = stateOfEndpoint(node, endpoint);
+
+        let behaviorState = endpointState.behaviors.get(behavior);
+        if (behaviorState === undefined) {
+            endpointState.behaviors.set(behavior, (behaviorState = {}));
+        }
+
+        return behaviorState;
+    }
+
+    /**
+     * Pre-populate {@link BehaviorState}s with versions provided by caller.
+     */
+    function installInitialVersions() {
+        if (!versions) {
+            return;
+        }
+
+        for (const { node, endpoint, cluster, version } of versions) {
+            stateOfBehavior(node, endpoint, cluster).version = version;
+        }
+    }
+
+    /**
+     * Generate a filter function if the caller provided filters.
+     */
+    function generateFilter(): ((node: string, behavior?: string) => boolean) | undefined {
+        if (!nodeFilter && !clusterFilter) {
+            return;
+        }
+
+        const whitelistedNodes = nodeFilter ? new Set(nodeFilter) : undefined;
+        const whitelistedBehaviors = clusterFilter ? new Set(clusterFilter) : undefined;
+
+        if (whitelistedNodes) {
+            if (whitelistedBehaviors) {
+                return (node, behavior) =>
+                    whitelistedNodes.has(node) && (!behavior || whitelistedBehaviors.has(behavior));
+            }
+
+            return node => whitelistedNodes.has(node);
+        }
+
+        if (whitelistedBehaviors) {
+            return (_node, behavior) => !behavior || whitelistedBehaviors.has(behavior);
+        }
+    }
+
+    /**
+     * Process a property update notification.
+     */
+    function enqueueUpdate(change: ChangeNotificationService.PropertyUpdate) {
+        const { endpoint, behavior } = change;
+
+        const node = endpoint.env.get(Node);
+        if (filter && !filter(node.id, behavior.id)) {
+            return;
+        }
+
+        const behaviorState = stateOfBehavior(node.id, endpoint.number, behavior.id);
+
+        // Skip if version is already known
+        if (behaviorState.version === change.version) {
+            return;
+        }
+
+        // If already enqueued, just update state
+        if (behaviorState.queueEntry) {
+            if (change.properties) {
+                // dirty === undefined means that all properties are already enqueued
+                if (behaviorState.dirty) {
+                    for (const prop of change.properties) {
+                        // Subset of properties are dirty
+                        behaviorState.dirty.add(prop);
+                    }
+                }
+            } else {
+                // All properties are now enqueued
+                behaviorState.dirty = undefined;
+            }
+            behaviorState.version = change.version;
+            return;
+        }
+
+        // Newly queued; set state appropriately
+        behaviorState.dirty = change.properties ? new Set(change.properties) : undefined;
+        behaviorState.queueEntry = { endpoint, node, behavior };
+        enqueue(behaviorState.queueEntry);
+    }
+
+    /**
+     * Process a delete notification.
+     */
+    function enqueueDelete(change: ChangeNotificationService.EndpointDelete) {
+        const { endpoint } = change;
+
+        const node = endpoint.env.get(Node);
+        if (filter && !filter(node.id)) {
+            return;
+        }
+
+        const endpointState = stateOfEndpoint(node.id, endpoint.number);
+
+        // Dequeue all entries associated with the endpoint
+        for (const { queueEntry } of endpointState.behaviors.values()) {
+            if (queueEntry) {
+                dequeue(queueEntry);
+            }
+        }
+
+        // Delete state associated with the endpoint
+        if (endpoint === node) {
+            nodes.delete(node.id);
+        } else {
+            nodes.get(node.id)?.delete(endpoint.number);
+        }
+
+        // Enqueue for deletion
+        enqueue({ endpoint, node });
+    }
+
+    /**
+     * Add an entry to the queue.
+     */
+    function enqueue(entry: QueueEntry) {
+        if (queueTail) {
+            queueTail.next = entry;
+            entry.prev = queueTail;
+            queueTail = entry;
+        } else {
+            queueHead = queueTail = entry;
+        }
+
+        gate.open();
+    }
+
+    /**
+     * Remove an entry from the queue.
+     */
+    function dequeue(entry: QueueEntry) {
+        if (queueHead === entry) {
+            queueHead = entry.next;
+        }
+        if (queueTail === entry) {
+            queueTail = entry.prev;
+        }
+        if (entry.prev) {
+            entry.prev.next = entry.next;
+        }
+        if (entry.next) {
+            entry.next.prev = entry.prev;
+        }
+    }
+}
+
+interface QueueEntry {
+    node: Node;
+    endpoint: Endpoint;
+    behavior?: Behavior.Type;
+    prev?: QueueEntry;
+    next?: QueueEntry;
+}
+
+interface NodeState extends Map<number, EndpointState> {}
+
+interface EndpointState {
+    /**
+     * State for individual behaviors.
+     */
+    behaviors: Map<string, BehaviorState>;
+}
+
+interface BehaviorState {
+    /**
+     * Indicates the entry is queued for update.
+     */
+    queueEntry?: QueueEntry;
+
+    /**
+     * Current synced version.
+     */
+    version?: number;
+
+    /**
+     * Dirty properties.  If queued, these properties are dirty, or if undefined full update is required.
+     */
+    dirty?: Set<string>;
+}
+
+export namespace StateStream {
+    /**
+     * A single change event.
+     *
+     * Indicates either property updates or endpoint delete.
+     */
+    export type Change = Update | Delete;
+
+    /**
+     * A serializable version of {@link Change}.
+     */
+    export type WireChange = WireUpdate | WireDelete;
+
+    export type Key = string;
+
+    export interface Options {
+        abort?: Abort.Signal;
+        nodes?: Key[];
+        clusters?: Key[];
+        versions?: KnownVersion[];
+        coalesceInterval?: Duration;
+    }
+
+    export interface KnownVersion {
+        node: Key;
+        endpoint: EndpointNumber;
+        cluster: Key;
+        version: number;
+    }
+
+    export interface Update {
+        kind: "update";
+        node: Node;
+        endpoint: Endpoint;
+        version: number;
+        behavior: Behavior.Type;
+        changes: Record<Key, unknown>;
+    }
+
+    export interface Delete {
+        kind: "delete";
+        node: Node;
+        endpoint: Endpoint;
+    }
+
+    export interface WireUpdate {
+        kind: "update";
+        node: Key;
+        endpoint: number;
+        version: number;
+        behavior: Key;
+        changes: Record<Key, unknown>;
+    }
+
+    export interface WireDelete {
+        kind: "delete";
+        node: Key;
+        endpoint: number;
+    }
+
+    export function WireChange(change: Change): WireChange {
+        switch (change.kind) {
+            case "update":
+                return {
+                    kind: "update",
+                    node: change.node.id,
+                    endpoint: change.endpoint.number,
+                    version: change.version,
+                    behavior: change.behavior.id,
+                    changes: change.changes,
+                };
+
+            case "delete":
+                return {
+                    kind: "delete",
+                    node: change.node.id,
+                    endpoint: change.endpoint.number,
+                };
+        }
+    }
+
+    export const OptionsSchema = new DatatypeModel(
+        { name: "ChangeOptions", type: "struct", quality: "X" },
+
+        FieldElement({ name: "nodes", type: "list" }, FieldElement({ name: "entry", type: "string" })),
+        FieldElement({ name: "clusters", type: "list" }, FieldElement({ name: "entry", type: "string" })),
+        FieldElement(
+            { name: "versions", type: "list" },
+
+            FieldElement(
+                { name: "entry", type: "struct" },
+
+                FieldElement({ name: "node", type: "string", conformance: "M" }),
+                FieldElement({ name: "endpoint", type: "endpoint-no", conformance: "M" }),
+                FieldElement({ name: "cluster", type: "string", conformance: "M" }),
+                FieldElement({ name: "version", type: "data-ver", conformance: "M" }),
+            ),
+        ),
+        FieldElement({ name: "coalesceInterval", type: "duration" }),
+    );
+
+    export const WireUpdateSchema = new DatatypeModel(
+        { name: "UpdateNotification", type: "struct" },
+
+        FieldElement({ name: "node", type: "string" }),
+        FieldElement({ name: "endpoint", type: "endpoint-no" }),
+        FieldElement({ name: "version", type: "data-ver" }),
+        FieldElement({ name: "cluster", type: "string" }),
+        FieldElement({ name: "changes", type: "any" }),
+    );
+
+    export const WireDeleteSchema = new DatatypeModel(
+        { name: "DeleteNotification", type: "struct" },
+
+        FieldElement({ name: "node", type: "string" }),
+        FieldElement({ name: "endpoint", type: "endpoint-no" }),
+    );
+}