@matter/node 0.16.0-alpha.0-20251016-b56cf5683 → 0.16.0-alpha.0-20251020-3f6e46245

package/src/behaviors/access-control/AccessControlServer.ts

@@ -77,21 +77,14 @@ export class AccessControlServer extends AccessControlBehavior.with("Extension")
                 // Handle Backward compatibility to Matter.js before 0.9.1 and add the missing ACL entry if no entry was set
                 // so far by the controller
                 const fallbackAcl: AccessControlTypes.AccessControlEntry = {
-                    fabricIndex: fabric.fabricIndex,
                     privilege: AccessControlTypes.AccessControlEntryPrivilege.Administer,
                     authMode: AccessControlTypes.AccessControlEntryAuthMode.Case,
                     subjects: [fabric.rootNodeId],
                     targets: null, // entire node
+                    fabricIndex: fabric.fabricIndex,
                 };
                 this.state.acl.push(fallbackAcl);
                 fabricAcls.push(fallbackAcl);
-                logger.warn(
-                    "Added missing ACL entry for fabric",
-                    fabric.fabricIndex,
-                    "for Node ID",
-                    fabric.rootNodeId,
-                    ". This should only happen once after upgrading to matter.js 0.9.1",
-                );
             }
             fabric.accessControl.aclList = fabricAcls;
             fabric.accessControl.extensionEntryAccessCheck = this.extensionEntryAccessCheck.bind(this);

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/ClientBehavior.ts

@@ -10,14 +10,13 @@ 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 { ClientInteraction, Invoke } from "#protocol";
 import {
     Attribute,
     AttributeId,
     ClusterComposer,
     ClusterId,
     ClusterRegistry,
-    ClusterType,
     Command,
     CommandId,
     MutableCluster,
@@ -137,8 +136,7 @@ function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): Cluster
     // 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);
+        type.prototype[camelize(name, false)] = implementCommand(camelize(name));
     }
 
     return type;
@@ -152,33 +150,35 @@ function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): Cluster
         isCloned = true;
     }
 
-    function implementCommand(command: ClusterType.Command) {
+    function implementCommand(command: string) {
         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,
-                    }),
-                ),
+            const chunks = (node.interaction as ClientInteraction).invoke(
+                Invoke({
+                    commands: [
+                        Invoke.ConcreteCommandRequest<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?
+                    // We send only one command, so we only get one response back
                     switch (entry.kind) {
                         case "cmd-status":
                             if (entry.status !== Status.Success) {
                                 throw StatusResponseError.create(entry.status, undefined, entry.clusterStatus);
                             }
-                            break;
+                            return;
 
                         case "cmd-response":
-                            return command.responseSchema.decodeTlv(entry.data);
+                            return entry.data;
                     }
                 }
             }

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/ClientNodeInteraction.ts

@@ -7,10 +7,11 @@
 import type { ActionContext } from "#behavior/context/ActionContext.js";
 import { EndpointInitializer } from "#endpoint/properties/EndpointInitializer.js";
 import type { ClientNode } from "#node/ClientNode.js";
-import type {
+import {
+    ClientInteraction,
+    ClientInvoke,
+    DecodedInvokeResult,
     Interactable,
-    InvokeRequest,
-    InvokeResult,
     Read,
     ReadResult,
     Subscribe,
@@ -18,7 +19,6 @@ import type {
     Write,
     WriteResult,
 } from "#protocol";
-import { ClientInteraction } from "#protocol";
 import { ClientEndpointInitializer } from "./ClientEndpointInitializer.js";
 
 /**
@@ -31,6 +31,12 @@ export class ClientNodeInteraction implements Interactable<ActionContext> {
         this.#node = node;
     }
 
+    /**
+     * Read chosen attributes remotely from the node. Known data versions are automatically injected into the request to
+     * optimize the read.
+     * Therefore, the returned data only contains attributes that have changed since the last read or subscription.
+     * TODO: Allow control of data version injection and enrich response with attribute data missing in response due to data versioning.
+     */
     async *read(request: Read, context?: ActionContext): ReadResult {
         request = this.structure.injectVersionFilters(request);
         const interaction = await this.#connect();
@@ -38,6 +44,10 @@ export class ClientNodeInteraction implements Interactable<ActionContext> {
         yield* this.structure.mutate(request, response);
     }
 
+    /**
+     * Subscribe to chosen attributes remotely from the node. Data are automatically updated in the storage and not
+     * returned. The subscription response message with the subscription id and the maxInterval is returned.
+     */
     async subscribe(request: Subscribe, context?: ActionContext): SubscribeResult {
         const intermediateRequest: Subscribe = {
             ...this.structure.injectVersionFilters(request),
@@ -67,11 +77,15 @@ export class ClientNodeInteraction implements Interactable<ActionContext> {
         this.#node.env.get(ClientInteraction).cancelSubscription(id);
     }
 
+    /**
+     * Write chosen attributes remotely to the node.
+     * The returned attribute write status information is returned.
+     */
     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 {
+    async *invoke(request: ClientInvoke, context?: ActionContext): DecodedInvokeResult {
         yield* (await this.#connect()).invoke(request, context);
     }
 

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/node/integration/ProtocolService.ts

@@ -35,7 +35,14 @@ import type {
     InteractionSession,
     NodeProtocol,
 } from "#protocol";
-import { EventTypeProtocol, FabricManager, hasRemoteActor, OccurrenceManager, Val } from "#protocol";
+import {
+    EventTypeProtocol,
+    FabricManager,
+    hasRemoteActor,
+    OccurrenceManager,
+    toWildcardOrHexPath,
+    Val,
+} from "#protocol";
 import {
     AttributeId,
     AttributePath,
@@ -554,7 +561,7 @@ function invokeCommand(
     const context = session as ActionContext;
 
     logger.info(
-        "Invoke",
+        "Invoke «",
         Diagnostic.strong(`${path.toString()}.${command.name}`),
         session.transaction.via,
         requestDiagnostic,
@@ -629,13 +636,6 @@ function invokeCommand(
     return result as MaybePromise<Val.Struct | undefined>;
 }
 
-function toWildcardOrHex(name: string, value: number | bigint | undefined) {
-    if (value === undefined) {
-        return "*";
-    }
-    return `${name}:0x${value.toString(16)}`;
-}
-
 /**
  * Resolve a path into a human readable textual form for logging
  * TODO: Add a Diagnostic display formatter for this
@@ -656,35 +656,35 @@ function resolvePathForNode(node: NodeProtocol, path: AttributePath | EventPath
                 : undefined;
 
     if (endpointId === undefined) {
-        return `*.${toWildcardOrHex("", clusterId)}.${toWildcardOrHex("", elementId)}${postString}`;
+        return `*.${toWildcardOrHexPath("", clusterId)}.${toWildcardOrHexPath("", elementId)}${postString}`;
     }
 
     const endpoint = node[endpointId];
     if (endpoint === undefined) {
-        return `${toWildcardOrHex("?", endpointId)}.${toWildcardOrHex("", clusterId)}.${toWildcardOrHex("", elementId)}${postString}`;
+        return `${toWildcardOrHexPath("?", endpointId)}.${toWildcardOrHexPath("", clusterId)}.${toWildcardOrHexPath("", elementId)}${postString}`;
     }
-    const endpointName = toWildcardOrHex(endpoint.name, endpointId);
+    const endpointName = toWildcardOrHexPath(endpoint.name, endpointId);
 
     if (clusterId === undefined) {
-        return `${endpointName}.*.${toWildcardOrHex("", elementId)}${postString}`;
+        return `${endpointName}.*.${toWildcardOrHexPath("", elementId)}${postString}`;
     }
 
     const cluster = endpoint[clusterId];
     if (cluster === undefined) {
-        return `${endpointName}.${toWildcardOrHex("?", clusterId)}.${toWildcardOrHex("", elementId)}${postString}`;
+        return `${endpointName}.${toWildcardOrHexPath("?", clusterId)}.${toWildcardOrHexPath("", elementId)}${postString}`;
     }
-    const clusterName = toWildcardOrHex(cluster.type.name, clusterId);
+    const clusterName = toWildcardOrHexPath(cluster.type.name, clusterId);
 
     if (elementId !== undefined) {
         if ("eventId" in path) {
             const event = cluster.type.events[elementId];
-            return `${endpointName}.${clusterName}.${toWildcardOrHex(event?.name ?? "?", elementId)}${postString}`;
+            return `${endpointName}.${clusterName}.${toWildcardOrHexPath(event?.name ?? "?", elementId)}${postString}`;
         } else if ("attributeId" in path) {
             const attribute = cluster.type.attributes[elementId];
-            return `${endpointName}.${clusterName}.${toWildcardOrHex(attribute?.name ?? "?", elementId)}${postString}`;
+            return `${endpointName}.${clusterName}.${toWildcardOrHexPath(attribute?.name ?? "?", elementId)}${postString}`;
         } else if ("commandId" in path) {
             const command = cluster.type.commands[elementId];
-            return `${endpointName}.${clusterName}.${toWildcardOrHex(command?.name ?? "?", elementId)}${postString}`;
+            return `${endpointName}.${clusterName}.${toWildcardOrHexPath(command?.name ?? "?", elementId)}${postString}`;
         } else {
             throw new ImplementationError("Invalid path");
         }