@matter/node 0.16.0-alpha.0-20251108-514b3f69e → 0.16.0-alpha.0-20251110-c4c70a41b

package/src/node/client/ClientStructureEvents.ts

@@ -0,0 +1,97 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Behavior } from "#behavior/Behavior.js";
+import { ClusterBehavior } from "#behavior/cluster/ClusterBehavior.js";
+import { DescriptorClient } from "#behaviors/descriptor";
+import { Endpoint } from "#endpoint/Endpoint.js";
+import { EndpointType } from "#endpoint/type/EndpointType.js";
+import { Environment, Environmental, Observable } from "#general";
+import { DeviceTypeId } from "#types";
+
+/**
+ * An environmental service that manages events endpoint and behavior types.
+ */
+export class ClientStructureEvents {
+    #endpointEvents?: Map<DeviceTypeId, Observable<[Endpoint]>>;
+    #clusterEvents?: Map<
+        string,
+        Array<{
+            requestedType: Behavior.Type;
+            event: Observable<[Endpoint, Behavior.Type]>;
+        }>
+    >;
+
+    static [Environmental.create](env: Environment) {
+        const instance = new ClientStructureEvents();
+        env.set(ClientStructureEvents, instance);
+        return instance;
+    }
+
+    endpointInstalled<T extends EndpointType>(type: T): Observable<[endpoint: Endpoint<T>]> {
+        if (this.#endpointEvents === undefined) {
+            this.#endpointEvents = new Map();
+        }
+
+        let event = this.#endpointEvents.get(type.deviceType);
+        if (event === undefined) {
+            this.#endpointEvents.set(type.deviceType, (event = Observable()));
+        }
+
+        return event as Observable<[endpoint: Endpoint<T>]>;
+    }
+
+    clusterInstalled<T extends ClusterBehavior.Type>(type: T): Observable<[endpoint: Endpoint, type: T]> {
+        if (this.#clusterEvents === undefined) {
+            this.#clusterEvents = new Map();
+        }
+
+        let events = this.#clusterEvents.get(type.id);
+        if (events === undefined) {
+            this.#clusterEvents.set(type.id, (events = []));
+        }
+
+        for (const { requestedType, event } of events) {
+            if (requestedType.supports(type)) {
+                return event;
+            }
+        }
+
+        const event = Observable();
+        events.push({ requestedType: type, event });
+
+        return event;
+    }
+
+    emitEndpoint(endpoint: Endpoint) {
+        if (this.#endpointEvents && endpoint.behaviors.supported.descriptor) {
+            const deviceTypes = endpoint.stateOf(DescriptorClient).deviceTypeList;
+            for (const dt of deviceTypes) {
+                this.#endpointEvents.get(dt.deviceType)?.emit(endpoint);
+            }
+        }
+
+        for (const type of Object.values(endpoint.behaviors.supported)) {
+            this.emitCluster(endpoint, type);
+        }
+
+        for (const part of endpoint.parts) {
+            this.emitEndpoint(part);
+        }
+    }
+
+    emitCluster(endpoint: Endpoint, type: Behavior.Type) {
+        const events = this.#clusterEvents?.get(type.id);
+        if (!events) {
+            return;
+        }
+        for (const { requestedType, event } of events) {
+            if (type.supports(requestedType)) {
+                event.emit(endpoint, type);
+            }
+        }
+    }
+}

package/src/node/client/PeerBehavior.ts

@@ -6,11 +6,19 @@
 
 import { Behavior } from "#behavior/Behavior.js";
 import { ClusterBehavior } from "#behavior/cluster/ClusterBehavior.js";
+import { ClusterBehaviorType } from "#behavior/cluster/ClusterBehaviorType.js";
 import { camelize, capitalize, InternalError } from "#general";
-import { AttributeModel, ClusterModel, CommandModel, Conformance, FeatureBitmap, Matter } from "#model";
-import type { ClientNode } from "#node/ClientNode.js";
-import { Node } from "#node/Node.js";
-import { ClientInteraction, Invoke } from "#protocol";
+import {
+    AttributeModel,
+    ClusterModel,
+    CommandModel,
+    Conformance,
+    EncodedBitmap,
+    EventModel,
+    FeatureBitmap,
+    Matter,
+    type ValueModel,
+} from "#model";
 import {
     Attribute,
     AttributeId,
@@ -20,24 +28,77 @@ import {
     Command,
     CommandId,
     MutableCluster,
-    Status,
-    StatusResponseError,
     TlvAny,
     TlvNoResponse,
 } from "#types";
+import { ClientCommandMethod } from "./ClientCommandMethod.js";
 
 const BIT_BLOCK_SIZE = Math.log2(Number.MAX_SAFE_INTEGER);
 
-const cache = {} as Record<string, ClusterBehavior.Type>;
+const discoveredCache = {} as Record<string, ClusterBehavior.Type>;
+const knownCache = new WeakMap<ClusterBehavior.Type, ClusterBehavior.Type>();
+
+const isPeer = Symbol("is-peer");
 
 /**
  * Obtain a {@link ClusterBehavior.Type} for a remote cluster.
  */
 export function PeerBehavior(shape: PeerBehavior.ClusterShape): ClusterBehavior.Type {
-    const analysis = ShapeAnalysis(shape);
+    let type: ClusterBehavior.Type;
+
+    switch (shape.kind) {
+        case "known":
+            if (Object.hasOwn(shape.behavior, isPeer)) {
+                return shape.behavior;
+            }
+            type = instrumentKnownShape(shape);
+            break;
+
+        case "discovered":
+            type = instrumentDiscoveredShape(shape);
+            break;
+
+        default:
+            throw new InternalError(`Unknown cluster shape kind ${(shape as any).kind}`);
+    }
+
+    (type as any)[isPeer] = true;
+
+    return type;
+}
+
+export namespace PeerBehavior {
+    export type ClusterShape = DiscoveredClusterShape | KnownClusterShape;
+
+    /**
+     * A cluster shape that we assemble using a combination of Matter standards and metadata discovered by reading from
+     * a peer.
+     */
+    export interface DiscoveredClusterShape {
+        kind: "discovered";
+        id: ClusterId;
+        revision: number;
+        features: FeatureBitmap | number;
+        attributes: AttributeId[];
+        commands: CommandId[];
+        attributeNames: Record<AttributeId, string>;
+        commandNames: Record<CommandId, string>;
+    }
+
+    /**
+     * A known cluster shape that we instrument as is.
+     */
+    export interface KnownClusterShape {
+        kind: "known";
+        behavior: ClusterBehavior.Type;
+    }
+}
+
+function instrumentDiscoveredShape(shape: PeerBehavior.DiscoveredClusterShape) {
+    const analysis = DiscoveredShapeAnalysis(shape);
 
     const fingerprint = createFingerprint(analysis);
-    let type = cache[fingerprint];
+    let type = discoveredCache[fingerprint];
     if (type) {
         return type;
     }
@@ -50,31 +111,41 @@ export function PeerBehavior(shape: PeerBehavior.ClusterShape): ClusterBehavior.
         baseType = ClusterBehavior;
     }
 
-    type = cache[fingerprint] = generateType(analysis, baseType);
+    type = discoveredCache[fingerprint] = generateDiscoveredType(analysis, baseType);
 
     return type;
 }
 
-export namespace PeerBehavior {
-    export interface ClusterShape {
-        id: ClusterId;
-        revision: number;
-        features: FeatureBitmap | number;
-        attributes: AttributeId[];
-        commands: CommandId[];
-        attributeNames: Record<AttributeId, string>;
-        commandNames: Record<CommandId, string>;
+function instrumentKnownShape(shape: PeerBehavior.KnownClusterShape) {
+    let type = knownCache.get(shape.behavior);
+    if (type) {
+        return type;
     }
+
+    const base = shape.behavior;
+
+    type = ClusterBehaviorType({
+        base,
+        cluster: base.cluster,
+        schema: base.schema,
+        name: `${base.schema.name}Client`,
+        forClient: true,
+        commandFactory: ClientCommandMethod,
+    });
+
+    knownCache.set(shape.behavior, type);
+
+    return type;
 }
 
-function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): ClusterBehavior.Type {
+function generateDiscoveredType(analysis: DiscoveredShapeAnalysis, baseType: Behavior.Type): ClusterBehavior.Type {
     // Ensure the input type is a ClusterBehavior
     if (!ClusterBehavior.is(baseType)) {
-        throw new InternalError(`Base Behavior for cluster ${analysis.schema.name} is not a ClusterBehavior`);
+        throw new InternalError(`Base for cluster ${analysis.schema.name} is not a ClusterBehavior`);
     }
 
     let { schema } = analysis;
-    let isCloned = false;
+    let isExtended = false;
     const { attrSupportOverrides, extraAttrs, commandSupportOverrides, extraCommands } = analysis;
 
     // Obtain a ClusterType.  This provides TLV for known elements
@@ -99,7 +170,7 @@ function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): Cluster
         .map(([k]) => k);
     if (featureNames.length) {
         // Update ClusterModel
-        cloneSchema();
+        extendSchema();
 
         // Update the cluster.  Note that we do not validate feature combinations.  What the device sends we work with
         cluster = new ClusterComposer(cluster, true).compose(featureNames.map(capitalize));
@@ -111,10 +182,10 @@ function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): Cluster
         schema.revision !== analysis.shape.revision ||
         extraAttrs.size ||
         extraCommands.size ||
-        Object.keys(attrSupportOverrides).length ||
-        Object.keys(commandSupportOverrides).length
+        attrSupportOverrides.size ||
+        commandSupportOverrides.size
     ) {
-        cloneSchema();
+        extendSchema();
 
         cluster = {
             ...cluster,
@@ -123,7 +194,7 @@ function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): Cluster
             commands: { ...cluster.commands },
         };
 
-        if (attrSupportOverrides) {
+        if (attrSupportOverrides.size) {
             for (const [attr, isSupported] of attrSupportOverrides.entries()) {
                 schema.children.push(attr.extend({ operationalIsSupported: isSupported }));
             }
@@ -135,7 +206,7 @@ function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): Cluster
             schema.children.push(new AttributeModel({ id, name, type: "any" }));
         }
 
-        if (commandSupportOverrides) {
+        if (commandSupportOverrides.size) {
             for (const [command, isSupported] of commandSupportOverrides.entries()) {
                 schema.children.push(command.extend({ operationalIsSupported: isSupported }));
             }
@@ -149,72 +220,47 @@ function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): Cluster
     }
 
     // Specialize for the specific cluster and schema
-    const type = baseType.for(cluster, schema, `${schema.name}Client`);
-
-    // Add command implementations
-    for (const id of analysis.shape.commands) {
-        const name = schema.get(CommandModel, id)?.name ?? createUnknownName("command", id);
-        type.prototype[camelize(name, false)] = implementCommand(camelize(name));
-    }
-
-    return type;
-
-    function cloneSchema() {
-        if (isCloned) {
+    return ClusterBehaviorType({
+        base: baseType,
+        cluster,
+        schema,
+        name: `${schema.name}Client`,
+        forClient: true,
+        commandFactory: ClientCommandMethod,
+    });
+
+    function extendSchema() {
+        if (isExtended) {
             return;
         }
-        schema = schema.clone();
+        schema = schema.extend();
         schema.supportedFeatures = featureNames;
-        isCloned = true;
-    }
-
-    function implementCommand(command: string) {
-        return async function (this: ClusterBehavior, fields?: {}) {
-            const node = this.env.get(Node) as ClientNode;
-
-            // TODO when implementing TCP add needed logic for Large messages
-            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) {
-                    // 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);
-                            }
-                            return;
-
-                        case "cmd-response":
-                            return entry.data;
-                    }
-                }
-            }
-        };
+        isExtended = true;
     }
 }
 
 /**
  * Create a compact string that uniquely identifies a shape for matching purposes.
  */
-function createFingerprint(analysis: ShapeAnalysis) {
-    const fingerprint = [analysis.shape.id] as (number | string)[];
+function createFingerprint(analysis: DiscoveredShapeAnalysis) {
+    const fingerprint = [analysis.shape.id] as (number | string | bigint)[];
+
+    if (analysis.featureBitmap) {
+        fingerprint.push("f", analysis.featureBitmap);
+    }
+
+    if (analysis.attrSupportOverrides.size) {
+        addSupportFingerprints("a", analysis.attrSupportOverrides);
+    }
 
     if (analysis.extraAttrs.size) {
         fingerprint.push("a", createElementFingerprint(analysis.extraAttrs));
     }
 
+    if (analysis.commandSupportOverrides.size) {
+        addSupportFingerprints("c", analysis.commandSupportOverrides);
+    }
+
     if (analysis.extraCommands.size) {
         fingerprint.push("c", createElementFingerprint(analysis.extraCommands));
     }
@@ -224,8 +270,8 @@ function createFingerprint(analysis: ShapeAnalysis) {
     /**
      * Create a fingerprint for a specific type of ACE element.
      *
-     * For elements we divide create series of bitmaps, one for each range of BIT_BLOCK_SIZE unique integers with an
-     * ID present.  Note that these bitmaps may not be consecutive due to gaps in IDs.  We then serialize all bitmaps
+     * For elements we create a series of bitmaps, one for each range of BIT_BLOCK_SIZE unique integers with an ID
+     * present.  Note that these bitmaps may not be consecutive due to gaps in IDs.  We then serialize all bitmaps
      * present as "<block index>:<bitmap value>" and concatenate to create a unique fingerprint.
      *
      * The goal is to efficiently create a compact unique identifier.
@@ -243,15 +289,53 @@ function createFingerprint(analysis: ShapeAnalysis) {
             .map(([block, map]) => (block ? `${block}:${map}` : map))
             .join(",");
     }
+
+    /**
+     * Add fingerprints for overrides of element support.
+     *
+     * This adds an "x-" component for unsupported elements and "x+" for supported elements.
+     */
+    function addSupportFingerprints(prefix: string, elements: Map<ValueModel, boolean>) {
+        let supported: Array<number> | undefined;
+        let unsupported: Array<number> | undefined;
+
+        for (const [{ id }, isSupported] of elements) {
+            if (id === undefined) {
+                continue;
+            }
+
+            if (isSupported) {
+                if (supported) {
+                    supported.push(id);
+                } else {
+                    supported = [id];
+                }
+            } else {
+                if (unsupported) {
+                    unsupported.push(id);
+                } else {
+                    unsupported = [id];
+                }
+            }
+        }
+
+        if (supported) {
+            fingerprint.push(`${prefix}+`, createElementFingerprint(supported));
+        }
+        if (unsupported) {
+            fingerprint.push(`${prefix}-`, createElementFingerprint(unsupported));
+        }
+    }
 }
 
 function createUnknownName(prefix: string, id: number) {
     return `${prefix}$${id.toString(16)}`;
 }
 
-interface ShapeAnalysis {
+interface DiscoveredShapeAnalysis {
     schema: ClusterModel & { id: ClusterId };
-    shape: PeerBehavior.ClusterShape;
+    featureBitmap: number | bigint;
+    shape: PeerBehavior.DiscoveredClusterShape;
     attrSupportOverrides: Map<AttributeModel, boolean>;
     extraAttrs: Set<number>;
     commandSupportOverrides: Map<CommandModel, boolean>;
@@ -259,31 +343,25 @@ interface ShapeAnalysis {
 }
 
 /**
- * Analyze the cluster shape to determine how we should override the behavior and schema.
+ * Analyze a discovered cluster shape to determine how we should override the behavior and schema.
  */
-function ShapeAnalysis(shape: PeerBehavior.ClusterShape): ShapeAnalysis {
+function DiscoveredShapeAnalysis(shape: PeerBehavior.DiscoveredClusterShape): DiscoveredShapeAnalysis {
     const standardCluster = Matter.get(ClusterModel, shape.id);
     const schema =
         standardCluster ??
         new ClusterModel({ id: shape.id, name: createUnknownName("Cluster", shape.id), revision: shape.revision });
 
+    let featureBitmap: bigint | number;
+    if (typeof shape.features === "number") {
+        featureBitmap = shape.features;
+    } else {
+        featureBitmap = EncodedBitmap(schema.featureMap, shape.features);
+    }
+
     const attrSupportOverrides = new Map<AttributeModel, boolean>();
     const extraAttrs = new Set<number>(shape.attributes);
     for (const attr of schema.attributes) {
         maybeOverrideSupport(standardCluster, attr, extraAttrs, attrSupportOverrides);
-        if (standardCluster) {
-            const supported = extraAttrs.has(attr.id);
-            const applicability = attr.conformance.applicabilityFor(standardCluster);
-            if (!supported) {
-                if (applicability) {
-                    attrSupportOverrides.set(attr, false);
-                }
-            } else {
-                if (applicability !== Conformance.Applicability.Mandatory) {
-                    attrSupportOverrides.set(attr, true);
-                }
-            }
-        }
         extraAttrs.delete(attr.id as AttributeId);
     }
 
@@ -296,6 +374,7 @@ function ShapeAnalysis(shape: PeerBehavior.ClusterShape): ShapeAnalysis {
 
     return {
         schema: schema as ClusterModel & { id: ClusterId },
+        featureBitmap,
         shape,
         attrSupportOverrides,
         extraAttrs,
@@ -313,24 +392,26 @@ function ShapeAnalysis(shape: PeerBehavior.ClusterShape): ShapeAnalysis {
  *
  * * the element is optional according to the standard and is implemented on the peer
  */
-function maybeOverrideSupport<T extends AttributeModel | CommandModel>(
+function maybeOverrideSupport<T extends AttributeModel | CommandModel | EventModel>(
     standardCluster: ClusterModel | undefined,
     element: T,
-    supported: Set<number>,
+    supported: Set<number> | true,
     overrides: Map<T, boolean>,
 ) {
     if (!standardCluster) {
         return;
     }
 
-    const isSupported = supported.has(element.id);
-    const applicability = element.conformance.applicabilityFor(standardCluster);
+    const isSupported = supported === true || supported.has(element.id);
+    const applicability = element.effectiveConformance.applicabilityFor(standardCluster);
     if (!isSupported) {
-        if (applicability) {
+        if (applicability === Conformance.Applicability.Mandatory) {
+            // We don't really pay attention to "unsupported mandatory attributes" but mark them anyway
             overrides.set(element, false);
         }
     } else {
         if (applicability !== Conformance.Applicability.Mandatory) {
+            // Indicate support for optional feature
             overrides.set(element, true);
         }
     }