@matter/node 0.16.0-alpha.0-20251018-dd1ea6a8a → 0.16.0-alpha.0-20251020-3f6e46245

package/src/behaviors/general-commissioning/GeneralCommissioningServer.ts

@@ -99,7 +99,7 @@ export class GeneralCommissioningServer extends GeneralCommissioningBehavior {
                     sessions: this.env.get(SessionManager),
                     expiryLength: Seconds(expiryLengthSeconds),
                     maxCumulativeFailsafe: Seconds(this.state.basicCommissioningInfo.maxCumulativeFailsafeSeconds),
-                    associatedFabric: session.fabric,
+                    session,
                 });
 
                 // Note - this used to be async and wait for construction internally.  However that leads to race

package/src/node/ClientGroup.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ActionContext } from "#behavior/context/ActionContext.js";
+import { Interactable } from "#protocol";
+import { ServerNodeStore } from "#storage/index.js";
+import { ClientNode } from "./ClientNode.js";
+import { ClientGroupInteraction } from "./client/ClientGroupInteraction.js";
+
+export class ClientGroup extends ClientNode {
+    #interaction?: ClientGroupInteraction;
+
+    override get isGroup() {
+        return true;
+    }
+
+    override get interaction(): Interactable<ActionContext> {
+        if (this.#interaction === undefined) {
+            this.#interaction = new ClientGroupInteraction(this);
+        }
+
+        return this.#interaction;
+    }
+
+    protected override get store() {
+        return this.env.get(ServerNodeStore).clientStores.storeForGroup(this);
+    }
+}
+
+export namespace ClientGroup {
+    export function is(value: unknown): value is ClientGroup {
+        return value instanceof ClientGroup;
+    }
+}

package/src/node/ClientNode.ts

@@ -53,6 +53,10 @@ export class ClientNode extends Node<ClientNode.RootEndpoint> {
         this.#matter = options.matter ?? Matter;
     }
 
+    get isGroup() {
+        return false;
+    }
+
     /**
      * Model of Matter semantics understood by this node.
      *
@@ -66,8 +70,12 @@ export class ClientNode extends Node<ClientNode.RootEndpoint> {
         return new ClientNodeEndpoints(this);
     }
 
+    protected get store() {
+        return this.env.get(ServerNodeStore).clientStores.storeForNode(this);
+    }
+
     override initialize() {
-        const store = this.env.get(ServerNodeStore).clientStores.storeForNode(this);
+        const store = this.store;
 
         this.env.set(ClientNodeStore, store);
 
@@ -202,7 +210,7 @@ export class ClientNode extends Node<ClientNode.RootEndpoint> {
 
         // During early initialization commissioning state may not be loaded, so check directly in storage too
         if (!address) {
-            address = this.env.get(ClientNodeStore).storeForEndpoint(this).peerAddress as PeerAddress | undefined;
+            address = this.store.storeForEndpoint(this).peerAddress as PeerAddress | undefined;
         }
 
         // Use the peer address as a log identifier if present

package/src/node/client/ClientEndpointInitializer.ts

@@ -49,7 +49,7 @@ export class ClientEndpointInitializer extends EndpointInitializer {
     }
 
     override createBacking(endpoint: Endpoint, type: Behavior.Type): BehaviorBacking {
-        // Non-cluster behaviors are local operation the same server behaviors
+        // Non-cluster behaviors are local, operating the same server behaviors
         if ((type as ClusterBehavior.Type).cluster === undefined) {
             const store = this.structure.storeForLocal(endpoint, type);
             return new ServerBehaviorBacking(endpoint, type, store, endpoint.behaviors.optionsFor(type));

package/src/node/client/ClientGroupInteraction.ts

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { ActionContext } from "#behavior/index.js";
+import { ImplementationError } from "#general";
+import {
+    ClientInvoke,
+    DecodedInvokeResult,
+    Read,
+    ReadResult,
+    Subscribe,
+    SubscribeResult,
+    Write,
+    WriteResult,
+} from "#protocol";
+import { ClientNodeInteraction } from "./ClientNodeInteraction.js";
+
+export class InvalidGroupOperationError extends ImplementationError {}
+
+export class ClientGroupInteraction extends ClientNodeInteraction {
+    /** Groups do not support reading or subscribing to attributes */
+    override read(_request: Read, _context?: ActionContext): ReadResult {
+        throw new InvalidGroupOperationError("Groups do not support reading attributes");
+    }
+
+    /** Groups do not support reading or subscribing to attributes */
+    override async subscribe(_request: Subscribe, _context?: ActionContext): SubscribeResult {
+        throw new InvalidGroupOperationError("Groups do not support subscribing to attributes");
+    }
+
+    override async write<T extends Write>(
+        request: T,
+        context?: ActionContext,
+    ): WriteResult<T & { suppressResponse: true }> {
+        if (request.timedRequest) {
+            throw new InvalidGroupOperationError("Timed requests are not supported for group address writes.");
+        }
+
+        if (request.suppressResponse === false) {
+            // If flag was explicitly set to false, we cannot comply
+            throw new InvalidGroupOperationError("Writing attributes on a group address can not return a response.");
+        }
+
+        if (
+            request.writeRequests.some(
+                ({ path: { endpointId, clusterId, attributeId } }) =>
+                    endpointId !== undefined || clusterId === undefined || attributeId === undefined,
+            )
+        ) {
+            throw new InvalidGroupOperationError("Not all attribute write paths are valid for group address writes.");
+        }
+
+        // Writing to a group does not yield a response
+        return super.write({ ...request, suppressResponse: true }, context);
+    }
+
+    override invoke(request: ClientInvoke, context?: ActionContext): DecodedInvokeResult {
+        if (request.invokeRequests.some(({ commandPath: { endpointId } }) => endpointId !== undefined)) {
+            throw new InvalidGroupOperationError("Invoking a concrete command on a group address is not supported.");
+        }
+        if (request.timedRequest) {
+            throw new InvalidGroupOperationError("Timed requests are not supported for group address invokes.");
+        }
+
+        return super.invoke(request, context);
+    }
+}

package/src/node/client/ClientNodeFactory.ts

@@ -7,6 +7,7 @@
 import type { RemoteDescriptor } from "#behavior/system/commissioning/RemoteDescriptor.js";
 import type { ImmutableSet } from "#general";
 import type { ClientNode } from "#node/ClientNode.js";
+import type { PeerAddress } from "#protocol";
 
 /**
  * Create a new client node.
@@ -16,6 +17,6 @@ import type { ClientNode } from "#node/ClientNode.js";
  */
 export abstract class ClientNodeFactory {
     abstract find(descriptor: RemoteDescriptor): ClientNode | undefined;
-    abstract create(options: ClientNode.Options): ClientNode;
+    abstract create(options: ClientNode.Options, peerAddress?: PeerAddress): ClientNode;
     abstract nodes: ImmutableSet<ClientNode>;
 }

package/src/node/client/Peers.ts

@@ -11,6 +11,7 @@ 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, ImplementationError, Logger, Minutes, Seconds, Time, Timestamp } from "#general";
+import { ClientGroup } from "#node/ClientGroup.js";
 import { InteractionServer } from "#node/index.js";
 import { FabricManager, PeerAddress, PeerAddressStore } from "#protocol";
 import { ServerNodeStore } from "#storage/server/ServerNodeStore.js";
@@ -58,6 +59,7 @@ export class Peers extends EndpointContainer<ClientNode> {
         const factory = this.owner.env.get(ClientNodeFactory);
 
         const clientStores = this.owner.env.get(ServerNodeStore).clientStores;
+        // Group nodes have an in-memory only store, so all nodes restored here are ClientNode
         for (const id of clientStores.knownIds) {
             this.add(
                 factory.create({
@@ -131,7 +133,7 @@ export class Peers extends EndpointContainer<ClientNode> {
         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);
+            node = factory.create(options, peerAddress);
             await node.construction;
             this.add(node);
 
@@ -278,20 +280,33 @@ export class Peers extends EndpointContainer<ClientNode> {
 
 class Factory extends ClientNodeFactory {
     #owner: Peers;
+    #groupIdCounter = 0;
 
     constructor(owner: Peers) {
         super();
         this.#owner = owner;
     }
 
-    create(options: ClientNode.Options) {
-        if (options.id === undefined) {
-            options.id = this.#owner.owner.env.get(ServerNodeStore).clientStores.allocateId();
+    create(options: ClientNode.Options, peerAddress?: PeerAddress) {
+        let node: ClientNode;
+        if (peerAddress !== undefined && PeerAddress.isGroup(peerAddress)) {
+            if (options.id === undefined) {
+                options.id = `group${++this.#groupIdCounter}`;
+            }
+            node = new ClientGroup({
+                ...options,
+                owner: this.#owner.owner,
+            });
+        } else {
+            if (options.id === undefined) {
+                options.id = this.#owner.owner.env.get(ServerNodeStore).clientStores.allocateId();
+            }
+            node = new ClientNode({
+                ...options,
+                owner: this.#owner.owner,
+            });
         }
-        const node = new ClientNode({
-            ...options,
-            owner: this.#owner.owner,
-        });
+
         node.construction.start();
         return node;
     }

package/src/storage/client/ClientNodeStores.ts

@@ -4,7 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Construction, MatterAggregateError, StorageContext } from "#general";
+import { Construction, MatterAggregateError, StorageBackendMemory, StorageContext, StorageManager } from "#general";
+import type { ClientGroup } from "#node/ClientGroup.js";
 import type { ClientNode } from "#node/ClientNode.js";
 import type { Node } from "#node/Node.js";
 import { ClientNodeStore } from "./ClientNodeStore.js";
@@ -86,6 +87,17 @@ export class ClientNodeStores {
         return this.#createNodeStore(node.id);
     }
 
+    storeForGroup(node: ClientGroup): ClientNodeStore {
+        this.#construction.assert();
+
+        const store = this.#stores[node.id];
+        if (store) {
+            return store;
+        }
+
+        return this.#createGroupStore(node.id);
+    }
+
     /**
      * List all nodes present.
      */
@@ -99,6 +111,18 @@ export class ClientNodeStores {
         await this.construction;
     }
 
+    /**
+     * Group stores are always created with a memory backend as they are transient.
+     */
+    #createGroupStore(id: string) {
+        const manager = new StorageManager(new StorageBackendMemory());
+        manager.initialize();
+        const store = new ClientNodeStore(id, manager.createContext(id));
+        store.construction.start();
+        this.#stores[id] = store;
+        return store;
+    }
+
     #createNodeStore(id: string) {
         const store = new ClientNodeStore(id, this.#storage.createContext(id));
         store.construction.start();