@project-chip/matter.js 0.13.1-alpha.0-20250520-d699cd56d → 0.14.0-alpha.0-20250524-51a7e1721

package/src/cluster/server/ClusterDatasource.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { SupportedStorageTypes } from "#general";
+import { Fabric, OccurrenceManager } from "#protocol";
+
+export interface ClusterDatasource {
+    readonly version: number;
+    readonly eventHandler?: OccurrenceManager;
+    readonly fabrics: Fabric[];
+    increaseVersion(): number;
+    changed(key: string, value: SupportedStorageTypes): void;
+}

package/src/cluster/server/ClusterServer.ts

@@ -6,14 +6,7 @@
 
 import { capitalize, Diagnostic, ImplementationError, InternalError, Logger, MaybePromise } from "#general";
 import { AccessLevel } from "#model";
-import {
-    ClusterServer as BaseClusterServer,
-    ClusterDatasource,
-    CommandServer,
-    createAttributeServer,
-    createEventServer,
-    Fabric,
-} from "#protocol";
+import { Fabric } from "#protocol";
 import {
     AttributeId,
     BitSchema,
@@ -26,6 +19,8 @@ import {
     TypeFromPartialBitSchema,
 } from "#types";
 import { Endpoint } from "../../device/Endpoint.js";
+import { createAttributeServer } from "./AttributeServer.js";
+import { ClusterDatasource } from "./ClusterDatasource.js";
 import {
     AttributeInitialValues,
     AttributeServers,
@@ -35,6 +30,8 @@ import {
     EventServers,
     SupportedEventsList,
 } from "./ClusterServerTypes.js";
+import { CommandServer } from "./CommandServer.js";
+import { createEventServer } from "./EventServer.js";
 
 const logger = Logger.get("ClusterServer");
 
@@ -53,7 +50,7 @@ function isConditionMatching<F extends BitSchema, SF extends TypeFromPartialBitS
 /**
  * A collection of servers for a cluster's attributes, commands and events.
  */
-export interface ClusterServer<T extends ClusterType = ClusterType> extends BaseClusterServer {
+export interface ClusterServer<T extends ClusterType = ClusterType> {
     /**
      * Cluster ID
      */

package/src/cluster/server/ClusterServerTypes.ts

@@ -5,17 +5,7 @@
  */
 
 import { Merge } from "#general";
-import {
-    AnyEventServer,
-    AttributeServer,
-    ClusterClientObj,
-    CommandServer,
-    Fabric,
-    FabricScopedAttributeServer,
-    FixedAttributeServer,
-    Message,
-    Session,
-} from "#protocol";
+import { ClusterClientObj, Fabric, Message, Session } from "#protocol";
 import {
     Attribute,
     AttributeId,
@@ -48,7 +38,10 @@ import {
     WritableFabricScopedAttribute,
 } from "#types";
 import { Endpoint } from "../../device/Endpoint.js";
+import { AttributeServer, FabricScopedAttributeServer, FixedAttributeServer } from "./AttributeServer.js";
 import { type ClusterServer } from "./ClusterServer.js";
+import { CommandServer } from "./CommandServer.js";
+import { AnyEventServer } from "./EventServer.js";
 
 /** Cluster attributes accessible on the cluster server */
 type MandatoryAttributeServers<A extends Attributes> = Omit<

package/src/cluster/server/CommandServer.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Endpoint } from "#device/Endpoint.js";
+import { Diagnostic, Logger } from "#general";
+import { AccessLevel, FabricIndex } from "#model";
+import { Message, SecureSession, Session } from "#protocol";
+import { CommandId, StatusCode, TlvSchema, TlvStream } from "#types";
+
+const logger = Logger.get("CommandServer");
+
+export class CommandServer<RequestT = any, ResponseT = any> {
+    readonly #invokeAcl: AccessLevel;
+
+    constructor(
+        readonly invokeId: CommandId,
+        readonly responseId: CommandId,
+        readonly name: string,
+        readonly requestSchema: TlvSchema<RequestT>,
+        readonly responseSchema: TlvSchema<ResponseT>,
+        readonly requiresTimedInteraction: boolean,
+        invokeAcl: AccessLevel,
+        protected readonly handler: (
+            request: RequestT,
+            session: Session,
+            message: Message,
+            endpoint: Endpoint,
+        ) => Promise<ResponseT> | ResponseT,
+    ) {
+        this.#invokeAcl = invokeAcl;
+    }
+
+    async invoke(
+        session: Session,
+        args: TlvStream,
+        message: Message,
+        endpoint: Endpoint,
+    ): Promise<{
+        /** Primary StatusCode of the invoke request  as defined by Interaction proptocol. */
+        code: StatusCode;
+
+        /** Cluster specific StatusCode of the invoke request if required */
+        clusterCode?: number;
+
+        /** ID of the response */
+        responseId: CommandId;
+
+        /** Response data */
+        response: TlvStream;
+    }> {
+        let request = this.requestSchema.decodeTlv(args);
+
+        // Inject fabric index into structures in general if undefined, if set it will be used
+        if (session.isSecure) {
+            const fabric = (session as SecureSession).fabric;
+            if (fabric) {
+                request = this.requestSchema.injectField(
+                    request,
+                    <number>FabricIndex.id,
+                    session.associatedFabric.fabricIndex,
+                    () => true, // Noone should send any index and if we simply SHALL ignore it
+                );
+            }
+        }
+
+        this.requestSchema.validate(request);
+        this.debug(`Invoke ${this.name} with data ${Diagnostic.json(request)}`);
+        const response = await this.handler(request, session, message, endpoint);
+        this.debug(`Invoke ${this.name} response : ${Diagnostic.json(response)}`);
+        return {
+            code: StatusCode.Success,
+            responseId: this.responseId,
+            response: this.responseSchema.encodeTlv(response),
+        };
+    }
+
+    debug(message: string) {
+        logger.debug(message);
+    }
+
+    get invokeAcl() {
+        return this.#invokeAcl ?? AccessLevel.Operate; // or View?? Re "Read/Invoke" in Access table
+    }
+}

package/src/cluster/server/EventServer.ts

@@ -0,0 +1,198 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Endpoint } from "#device/Endpoint.js";
+import {
+    ImplementationError,
+    InternalError,
+    isObject,
+    MatterAggregateError,
+    MaybePromise,
+    Storage,
+    StorageOperationResult,
+    Time,
+} from "#general";
+import { AccessLevel, ClusterModel, EventModel, MatterModel } from "#model";
+import { Message, NumberedOccurrence, Occurrence, OccurrenceManager, SecureSession, Session } from "#protocol";
+import {
+    Attributes,
+    BitSchema,
+    Cluster,
+    ClusterId,
+    Commands,
+    Event,
+    EventId,
+    EventPriority,
+    Events,
+    FabricIndex,
+    TlvEventFilter,
+    TlvSchema,
+    TypeFromPartialBitSchema,
+    TypeFromSchema,
+} from "#types";
+
+export type AnyEventServer<T = any, S extends Storage = any> = EventServer<T, S> | FabricSensitiveEventServer<T, S>;
+
+export function createEventServer<
+    T,
+    F extends BitSchema,
+    SF extends TypeFromPartialBitSchema<F>,
+    A extends Attributes,
+    C extends Commands,
+    E extends Events,
+    S extends Storage,
+>(
+    clusterDef: Cluster<F, SF, A, C, E>,
+    eventDef: Event<T, F>,
+    eventName: string,
+    schema: TlvSchema<T>,
+    priority: EventPriority,
+    readAcl: AccessLevel | undefined,
+): EventServer<T, S> {
+    let fabricSensitive = false;
+    const clusterFromModel = MatterModel.standard.get(ClusterModel, clusterDef.id);
+    if (clusterFromModel !== undefined) {
+        const eventModel = clusterFromModel.get(EventModel, eventDef.id);
+        if (eventModel !== undefined) {
+            fabricSensitive = eventModel.fabricSensitive;
+        }
+    }
+    if (fabricSensitive) {
+        return new FabricSensitiveEventServer(eventDef.id, clusterDef.id, eventName, schema, priority, readAcl);
+    }
+    return new EventServer(eventDef.id, clusterDef.id, eventName, schema, priority, readAcl);
+}
+
+export class EventServer<T = any, S extends Storage = any> {
+    private eventList = new Array<Occurrence>();
+    private readonly listeners = new Array<(event: NumberedOccurrence) => void>();
+    protected endpoint?: Endpoint;
+    protected eventHandler?: OccurrenceManager;
+    #readAcl: AccessLevel | undefined;
+    hasFabricSensitiveData = false;
+
+    constructor(
+        readonly id: EventId,
+        readonly clusterId: ClusterId,
+        readonly name: string,
+        readonly schema: TlvSchema<T>,
+        readonly priority: EventPriority,
+        readAcl: AccessLevel | undefined,
+    ) {
+        this.#readAcl = readAcl;
+    }
+
+    get readAcl() {
+        return this.#readAcl ?? AccessLevel.View; // ???
+    }
+
+    assignToEndpoint(endpoint: Endpoint) {
+        this.endpoint = endpoint;
+    }
+
+    // TODO Try to get rid of that late binding and simply things again
+    //      potentially with refactoring out MatterDevice and MatterController
+    bindToEventHandler(eventHandler: OccurrenceManager) {
+        this.eventHandler = eventHandler;
+        // Send all stored events to the new listener
+        const promises = new Array<PromiseLike<void>>();
+        for (const event of this.eventList) {
+            const finalEvent = this.eventHandler.add(event);
+            if (finalEvent !== undefined && MaybePromise.is(finalEvent)) {
+                promises.push(finalEvent.then(e => this.listeners.forEach(listener => listener(e))));
+            } else {
+                this.listeners.forEach(listener => listener(finalEvent));
+            }
+        }
+        this.eventList = [];
+        if (promises.length > 0) {
+            return MatterAggregateError.allSettled(promises, "Error binding events to the event handlers").then(
+                () => {},
+            ) as StorageOperationResult<S>;
+        }
+        return undefined as StorageOperationResult<S>;
+    }
+
+    triggerEvent(data: T) {
+        if (this.endpoint === undefined || this.endpoint.number === undefined) {
+            throw new InternalError("Endpoint not assigned");
+        }
+        const occurrence: Occurrence = {
+            eventId: this.id,
+            clusterId: this.clusterId,
+            endpointId: this.endpoint.number,
+            epochTimestamp: Time.nowMs(),
+            priority: this.priority,
+            payload: data,
+        };
+        if (this.eventHandler === undefined) {
+            // As long as we have no occurrence manager, we store the events
+            this.eventList.push(occurrence);
+        } else {
+            const finalEvent = this.eventHandler.add(occurrence);
+            return MaybePromise.then(finalEvent, e => {
+                this.listeners.forEach(listener => listener(e));
+            }) as StorageOperationResult<S>;
+        }
+        return undefined as StorageOperationResult<S>;
+    }
+
+    addListener(listener: (event: NumberedOccurrence) => void) {
+        this.listeners.push(listener);
+    }
+
+    removeListener(listener: (event: NumberedOccurrence) => void) {
+        const entryIndex = this.listeners.indexOf(listener);
+        if (entryIndex !== -1) {
+            this.listeners.splice(entryIndex, 1);
+        }
+    }
+
+    get(
+        session: Session,
+        isFabricFiltered: boolean,
+        _message?: Message,
+        filters?: TypeFromSchema<typeof TlvEventFilter>[],
+    ) {
+        if (this.eventHandler === undefined) {
+            throw new InternalError("EventServer not bound to OccurrenceManager");
+        }
+        if (this.endpoint === undefined) {
+            throw new InternalError("EventServer not bound to Endpoint");
+        }
+
+        return this.eventHandler.query(
+            { endpointId: this.endpoint.number, clusterId: this.clusterId, eventId: this.id },
+            filters,
+            // When request is fabric filtered or the event is Fabric sensitive then filter the events for the fabrics
+            isFabricFiltered ? ((session as SecureSession).fabric?.fabricIndex ?? FabricIndex.NO_FABRIC) : undefined,
+        );
+    }
+}
+
+export class FabricSensitiveEventServer<T, S extends Storage> extends EventServer<T, S> {
+    override hasFabricSensitiveData = true;
+
+    override get(
+        session: Session,
+        _isFabricFiltered: boolean,
+        message?: Message,
+        filters?: TypeFromSchema<typeof TlvEventFilter>[],
+    ) {
+        // because the event is fabric sensitive it is always filtered out when another fabric tries to access it
+        return super.get(session, true, message, filters);
+    }
+
+    override triggerEvent(data: T) {
+        if (!isObject(data) || data === null) {
+            throw new ImplementationError("FabricSensitive events need to have an object as data.");
+        }
+        if (!("fabricIndex" in data)) {
+            throw new InternalError("FabricSensitive events requires fabricIndex in data.");
+        }
+        return super.triggerEvent(data);
+    }
+}

package/src/cluster/server/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./AttributeServer.js";
+export * from "./ClusterDatasource.js";
+export * from "./ClusterServer.js";
+export * from "./CommandServer.js";
+export * from "./EventServer.js";

package/src/device/Endpoint.ts

@@ -7,12 +7,11 @@
 import {
     BasicInformationCluster,
     BridgedDeviceBasicInformationCluster,
-    DescriptorCluster,
     FixedLabelCluster,
     UserLabelCluster,
 } from "#clusters";
-import { AtLeastOne, ImplementationError, InternalError, NotImplementedError } from "#general";
-import { ClusterClientObj, EndpointInterface } from "#protocol";
+import { AtLeastOne, Diagnostic, ImplementationError, InternalError, NotImplementedError } from "#general";
+import { ClusterClientObj, SupportedAttributeClient, UnknownSupportedAttributeClient } from "#protocol";
 import {
     Attributes,
     BitSchema,
@@ -35,7 +34,7 @@ export interface EndpointOptions {
     uniqueStorageKey?: string;
 }
 
-export class Endpoint implements EndpointInterface {
+export class Endpoint {
     private readonly clusterServers = new Map<ClusterId, ClusterServerObj>();
     private readonly clusterClients = new Map<ClusterId, ClusterClientObj>();
     private readonly childEndpoints: Endpoint[] = [];
@@ -46,8 +45,6 @@ export class Endpoint implements EndpointInterface {
         /** noop until officially set **/
     };
 
-    private descriptorCluster: ClusterServerObj<typeof DescriptorCluster>;
-
     /**
      * Create a new Endpoint instance.
      *
@@ -58,20 +55,6 @@ export class Endpoint implements EndpointInterface {
         protected deviceTypes: AtLeastOne<DeviceTypeDefinition>,
         options: EndpointOptions = {},
     ) {
-        this.descriptorCluster = ClusterServer(
-            DescriptorCluster,
-            {
-                deviceTypeList: deviceTypes.map(deviceType => ({
-                    deviceType: deviceType.code,
-                    revision: deviceType.revision,
-                })),
-                serverList: [],
-                clientList: [],
-                partsList: [],
-            },
-            {},
-        );
-        this.addClusterServer(this.descriptorCluster);
         this.setDeviceTypes(deviceTypes);
 
         if (options.endpointId !== undefined) {
@@ -158,9 +141,6 @@ export class Endpoint implements EndpointInterface {
             asClusterServerInternal(currentCluster)._close();
         }
         asClusterServerInternal(cluster)._assignToEndpoint(this);
-        if (cluster.id === DescriptorCluster.id) {
-            this.descriptorCluster = cluster as unknown as ClusterServerObj<typeof DescriptorCluster>;
-        }
 
         // In ts4 the cast to "any" here was unnecessary.  In TS5 the fact that
         // the string index signature in Attributes and Events doesn't allow
@@ -174,15 +154,10 @@ export class Endpoint implements EndpointInterface {
         // assertions everywhere those interfaces are used.  I'm treating that
         // as low priority for now
         this.clusterServers.set(cluster.id, cluster as any);
-
-        this.descriptorCluster.attributes.serverList.init(Array.from(this.clusterServers.keys()).sort((a, b) => a - b));
-        this.structureChangedCallback(); // Inform parent about structure change
     }
 
     addClusterClient(cluster: ClusterClientObj) {
         this.clusterClients.set(cluster.id, cluster);
-        this.descriptorCluster.attributes.clientList.init(Array.from(this.clusterClients.keys()).sort((a, b) => a - b));
-        this.structureChangedCallback(); // Inform parent about structure change
     }
 
     // TODO cleanup with id number vs ClusterId
@@ -238,17 +213,9 @@ export class Endpoint implements EndpointInterface {
         deviceTypes.forEach(deviceType => deviceTypeList.set(deviceType.code, deviceType));
         this.deviceTypes = Array.from(deviceTypeList.values()) as AtLeastOne<DeviceTypeDefinition>;
         this.name = deviceTypes[0].name;
-
-        // Update descriptor cluster
-        this.descriptorCluster.attributes.deviceTypeList.init(
-            this.deviceTypes.map(deviceType => ({
-                deviceType: deviceType.code,
-                revision: deviceType.revision,
-            })),
-        );
     }
 
-    addChildEndpoint(endpoint: EndpointInterface): void {
+    addChildEndpoint(endpoint: Endpoint): void {
         if (!(endpoint instanceof Endpoint)) {
             throw new Error("Only supported EndpointInterface implementation is Endpoint");
         }
@@ -360,8 +327,137 @@ export class Endpoint implements EndpointInterface {
             newPartsList.push(...childPartsList);
         }
 
-        this.descriptorCluster.attributes.partsList.setLocal(newPartsList);
-
         return newPartsList;
     }
+
+    /**
+     * Hierarchical diagnostics of endpoint and children.
+     */
+    get [Diagnostic.value](): unknown[] {
+        return [
+            Diagnostic.strong(this.name),
+            Diagnostic.dict({
+                "endpoint#": this.number,
+                type: this.deviceTypes.map(
+                    ({ name, code, revision }) => `${name} (0x${code.toString(16)}, ${revision})`,
+                ),
+            }),
+            Diagnostic.list([...this.#clusterDiagnostics(), ...this.getChildEndpoints()]),
+        ];
+    }
+
+    #clusterDiagnostics(): unknown[] {
+        const clusterDiagnostics = new Array<unknown>();
+
+        const clients = this.getAllClusterClients();
+        if (clients.length) {
+            clusterDiagnostics.push([
+                Diagnostic.strong("clients"),
+                Diagnostic.list(clients.map(client => this.#clusterClientDiagnostics(client))),
+            ]);
+        }
+
+        const servers = this.getAllClusterServers();
+        if (servers.length) {
+            clusterDiagnostics.push([
+                Diagnostic.strong("servers"),
+                Diagnostic.list(servers.map(server => this.#clusterServerDiagnostics(server))),
+            ]);
+        }
+
+        const childs = this.getChildEndpoints();
+        if (childs.length) {
+            clusterDiagnostics.push([Diagnostic.strong("childs"), Diagnostic.list([])]);
+        }
+
+        return clusterDiagnostics;
+    }
+
+    #clusterClientDiagnostics(client: ClusterClientObj) {
+        const result = [
+            Diagnostic.strong(client.name),
+            Diagnostic.dict({
+                id: Diagnostic.hex(client.id),
+                rev: client.revision,
+                flags: Diagnostic.asFlags({
+                    unknown: client.isUnknown,
+                }),
+            }),
+        ];
+        const elementDiagnostic = Array<unknown>();
+
+        const { supportedFeatures: features } = client;
+        const supportedFeatures = new Array<string>();
+        for (const featureName in features) {
+            if (features[featureName] === true) supportedFeatures.push(featureName);
+        }
+        if (supportedFeatures.length) {
+            elementDiagnostic.push([Diagnostic.strong("features"), supportedFeatures]);
+        }
+
+        if (Object.keys(client.attributes).length) {
+            const clusterData = new Array<unknown>();
+            for (const attributeName in client.attributes) {
+                const attribute = client.attributes[attributeName];
+                if (attribute === undefined || !(attribute instanceof SupportedAttributeClient)) continue;
+
+                clusterData.push([
+                    attribute.name,
+                    Diagnostic.dict({
+                        id: Diagnostic.hex(attribute.id),
+                        val: attribute.getLocal(),
+                        flags: Diagnostic.asFlags({
+                            unknown: attribute instanceof UnknownSupportedAttributeClient,
+                            fabricScoped: attribute.fabricScoped,
+                        }),
+                    }),
+                ]);
+            }
+            if (clusterData.length) {
+                elementDiagnostic.push([Diagnostic.strong("attributes"), Diagnostic.list(clusterData)]);
+            }
+        }
+
+        if (Object.keys(client.commands).length) {
+            const clusterData = new Array<unknown>();
+            for (const commandName in client.commands) {
+                if (commandName.match(/^\d+$/)) continue;
+                const command = client.commands[commandName];
+                if (command === undefined || !client.isCommandSupportedByName(commandName)) continue;
+
+                clusterData.push([commandName]);
+            }
+            if (clusterData.length) {
+                elementDiagnostic.push([Diagnostic.strong("commands"), Diagnostic.list(clusterData)]);
+            }
+        }
+
+        if (Object.keys(client.events).length) {
+            const clusterData = new Array<unknown>();
+            for (const eventName in client.events) {
+                const event = client.events[eventName];
+                if (event === undefined) continue;
+
+                clusterData.push([
+                    event.name,
+                    Diagnostic.dict({
+                        id: Diagnostic.hex(event.id),
+                    }),
+                ]);
+            }
+            if (clusterData.length) {
+                elementDiagnostic.push([Diagnostic.strong("events"), Diagnostic.list(clusterData)]);
+            }
+        }
+
+        if (elementDiagnostic.length) {
+            result.push(Diagnostic.list(elementDiagnostic));
+        }
+
+        return result;
+    }
+
+    #clusterServerDiagnostics(server: ClusterServerObj) {
+        return [Diagnostic.strong(server.name)];
+    }
 }