@matter/node 0.16.0-alpha.0-20251004-92135c7df → 0.16.0-alpha.0-20251011-d8942d7d5

package/src/behavior/internal/BehaviorBacking.ts

@@ -4,12 +4,14 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { OnlineEvent } from "#behavior/Events.js";
 import { Migration } from "#behavior/state/migrations/Migration.js";
 import type { Agent } from "#endpoint/Agent.js";
 import type { Endpoint } from "#endpoint/Endpoint.js";
 import { BehaviorInitializationError } from "#endpoint/errors.js";
 import type { SupportedElements } from "#endpoint/properties/Behaviors.js";
 import {
+    camelize,
     Construction,
     Crypto,
     EventEmitter,
@@ -19,8 +21,10 @@ import {
     Logger,
     MaybePromise,
     Observable,
+    ObserverGroup,
 } from "#general";
-import { ProtocolService } from "#node/server/ProtocolService.js";
+import { ChangeNotificationService } from "#node/integration/ChangeNotificationService.js";
+import { ProtocolService } from "#node/integration/ProtocolService.js";
 import type { ClusterId } from "#types";
 import type { Behavior } from "../Behavior.js";
 import { Reactor } from "../Reactor.js";
@@ -36,12 +40,16 @@ const logger = Logger.get("BehaviorBacking");
 export abstract class BehaviorBacking {
     #endpoint: Endpoint;
     #type: Behavior.Type;
+    #protocol: ProtocolService;
+    #changeTracking: ChangeNotificationService;
     #internal?: object;
     #events?: EventEmitter;
     #options?: Behavior.Options;
     #datasource?: Datasource;
     #reactors?: Reactors;
     #construction: Construction<BehaviorBacking>;
+    #suppressedChanges?: Set<string>;
+    #quietObservers?: ObserverGroup;
 
     get construction() {
         return this.#construction;
@@ -50,9 +58,13 @@ export abstract class BehaviorBacking {
     constructor(endpoint: Endpoint, type: Behavior.Type, store: Datasource.Store, options?: Behavior.Options) {
         this.#endpoint = endpoint;
         this.#type = type;
+        this.#protocol = endpoint.env.get(ProtocolService);
+        this.#changeTracking = endpoint.env.get(ChangeNotificationService);
         this.store = store;
         this.#options = options;
 
+        this.#configureEventSuppression();
+
         this.#construction = Construction(this);
         this.#construction.onError(error => {
             // The endpoint reports errors during initialization.  For errors occurring later we report the error
@@ -96,7 +108,7 @@ export abstract class BehaviorBacking {
 
             // Perform actual initialization
             const promise = this.invokeInitializer(behavior, this.#options);
-            return MaybePromise.then(promise, () => this.#endpoint.env.get(ProtocolService).addCluster(this), crash);
+            return MaybePromise.then(promise, () => this.#protocol.addCluster(this), crash);
         } catch (e) {
             crash(e);
         }
@@ -124,6 +136,8 @@ export abstract class BehaviorBacking {
         }
 
         return this.construction.close(() => {
+            this.#quietObservers?.close();
+
             let result = MaybePromise.then(
                 () => this.#reactors?.close(),
                 () => {
@@ -210,6 +224,7 @@ export abstract class BehaviorBacking {
             defaults: this.#endpoint.behaviors.defaultsFor(this.type),
             store: this.store,
             owner: this.#endpoint,
+            onChange: this.#onChange.bind(this),
         };
     }
 
@@ -289,6 +304,50 @@ export abstract class BehaviorBacking {
         await this.#reactors.remove(selector);
     }
 
+    /**
+     * We handle events in bulk via {@link Datasource.Options.onChange}, but "quieter" and "changesOmitted" events
+     * require special handling.  Those we ignore in the change handler and instead report only when emitted by the
+     * corresponding {@link OnlineEvent}.
+     */
+    #configureEventSuppression() {
+        const { schema } = this.type;
+        if (!schema) {
+            return;
+        }
+
+        for (const property of schema.conformant.properties) {
+            const { changesOmitted, quieter } = property.effectiveQuality;
+
+            if (!changesOmitted && !quieter) {
+                continue;
+            }
+
+            const name = camelize(property.name);
+
+            if (!this.#suppressedChanges) {
+                this.#suppressedChanges = new Set();
+            }
+            this.#suppressedChanges.add(name);
+
+            if (!quieter) {
+                continue;
+            }
+
+            const event = (this.events as unknown as Record<string, OnlineEvent>)[`${name}$Changed`];
+            if (event === undefined) {
+                continue;
+            }
+
+            if (event.isQuieter) {
+                if (!this.#quietObservers) {
+                    this.#quietObservers = new ObserverGroup();
+                }
+
+                this.#quietObservers.on(event.quiet, () => this.#broadcastChanges([name]));
+            }
+        }
+    }
+
     /**
      * Invoke {@link Behavior.destroy} to clean up application logic.
      */
@@ -322,4 +381,25 @@ export abstract class BehaviorBacking {
         const behavior = this.createBehavior(agent, this.#type);
         return behavior;
     }
+
+    #onChange(props: string[]) {
+        if (this.#suppressedChanges) {
+            props = props.filter(name => !this.#suppressedChanges!.has(name));
+        }
+        this.#broadcastChanges(props);
+    }
+
+    /**
+     * We provide two forms of optimized change tracking.
+     *
+     * {@link ProtocolService} offers a low-level service that supports the Matter protocol.
+     *
+     * {@link ChangeNotificationService} is a higher-level service that supports state synchronization use cases.
+     *
+     * This method informs these services of changes.
+     */
+    #broadcastChanges(props: string[]) {
+        this.#protocol.handleChange(this, props);
+        this.#changeTracking.broadcastUpdate(this, props);
+    }
 }

package/src/behavior/state/managed/Datasource.ts

@@ -26,8 +26,6 @@ const logger = Logger.get("Datasource");
 
 const FEATURES_KEY = "__features__";
 
-const changed = Symbol("changed");
-
 const viewTx = Transaction.open("offline-view", "ro");
 
 /**
@@ -63,11 +61,6 @@ export interface Datasource<T extends StateType = StateType> extends Transaction
      */
     location: AccessControl.Location;
 
-    /**
-     * Event that gets emitted when the state changes.
-     */
-    changed: Observable<[changes: string[], version: number], MaybePromise>;
-
     /**
      * Events registered for this Datasource
      */
@@ -105,10 +98,6 @@ export function Datasource<const T extends StateType = StateType>(options: Datas
             return internals.location;
         },
 
-        get changed() {
-            return internals.events[changed];
-        },
-
         get events() {
             return internals.events;
         },
@@ -145,10 +134,6 @@ export namespace Datasource {
         [K in `${string}$Changing` | `${string}$Changed`]: Observable<Parameters<ValueObserver>, MaybePromise>;
     };
 
-    export type InternalEvents = Events & {
-        [changed]: Observable<[changes: string[], version: number], MaybePromise>;
-    };
-
     /**
      * Datasource configuration options.
      */
@@ -204,6 +189,11 @@ export namespace Datasource {
          * For structs we also support the other key (id or name) for input, but always write using the preferred key.
          */
         primaryKey?: "name" | "id";
+
+        /**
+         * Optional callback, invoked when properties change.
+         */
+        onChange?: (attrs: string[]) => MaybePromise<void>;
     }
 
     /**
@@ -275,7 +265,7 @@ interface Internals extends Datasource.Options {
     sessions?: Map<ValueSupervisor.Session, SessionContext>;
     featuresKey?: string;
     interactionObserver(session?: ValueSupervisor.Session): MaybePromise<void>;
-    events: Datasource.InternalEvents;
+    events: Datasource.Events;
     changedEventFor(key: string): undefined | Datasource.Events[any];
     persistentFields: Set<string>;
 }
@@ -328,10 +318,9 @@ function configure(options: Datasource.Options): Internals {
     // Location affects security so make it immutable
     Object.freeze(options.location);
 
-    const events = (options.events ?? {}) as Datasource.InternalEvents;
-    events[changed] = new Observable();
+    const events = options.events ?? {};
 
-    let changedEventIndex: undefined | Map<string, undefined | Datasource.InternalEvents[`${string}$Changed`]>;
+    let changedEventIndex: undefined | Map<string, undefined | Datasource.Events[`${string}$Changed`]>;
 
     const persistentFields = options.supervisor.persistentKeys(options.primaryKey);
 
@@ -443,7 +432,15 @@ function configureExternalChanges(internals: Internals) {
             }
         }
 
-        const iterator = Object.keys(changes)[Symbol.iterator]();
+        const changedProps = Object.keys(changes);
+
+        const onChangePromise = internals.onChange?.(Array.from(changedProps));
+
+        const iterator = changedProps[Symbol.iterator]();
+
+        if (onChangePromise) {
+            return onChangePromise.then(emitChanged);
+        }
 
         return emitChanged();
 
@@ -856,13 +853,10 @@ function createReference(resource: Transaction.Resource, internals: Internals, s
             }
         }
 
-        const changeSetResult = internals.events[changed]?.emit(
-            Array.from(changes.changeList.values()),
-            internals.version,
-        );
+        const onChangePromise = internals.onChange?.([...changes.changeList]);
 
-        if (MaybePromise.is(changeSetResult)) {
-            return changeSetResult.then(emitChanged);
+        if (onChangePromise) {
+            return onChangePromise.then(emitChanged);
         }
 
         return emitChanged();

package/src/behavior/state/managed/NameResolver.ts

@@ -7,7 +7,7 @@
 import { RootSupervisor } from "#behavior/supervision/RootSupervisor.js";
 import { camelize } from "#general";
 import type { Schema } from "#model";
-import { ClusterModel, Model, ValueModel } from "#model";
+import { ClusterModel, Model, ValueModel, type FieldValue } from "#model";
 import { Val } from "#protocol";
 import { Internal } from "./Internal.js";
 

package/src/behavior/state/managed/values/ValueCaster.ts

@@ -12,21 +12,37 @@ import { RootSupervisor } from "../../../supervision/RootSupervisor.js";
 import { ValueSupervisor } from "../../../supervision/ValueSupervisor.js";
 
 /**
- * Obtain a {@link ValueSupervisor.Caster} function for the given schema.
+ * Obtain a {@link ValueSupervisor.Cast} function for the given schema.
  */
-export function ValueCaster(schema: Schema, owner: RootSupervisor) {
+export function ValueCaster(schema: Schema, owner: RootSupervisor): ValueSupervisor.Cast {
     const metatype = schema.effectiveMetatype ?? Metatype.any;
 
+    let cast: ValueSupervisor.Cast;
     switch (metatype) {
         case Metatype.object:
-            return StructCaster(schema, owner);
+            cast = StructCaster(schema, owner);
+            break;
 
         case Metatype.array:
-            return ListCaster(schema as ValueModel, owner);
+            cast = ListCaster(schema as ValueModel, owner);
+            break;
 
         default:
-            return Metatype.cast[metatype];
+            cast = Metatype.cast[metatype];
+            break;
     }
+
+    if (schema.quality.nullable) {
+        return value => {
+            if (value === null) {
+                return value;
+            }
+
+            return cast(value);
+        };
+    }
+
+    return cast;
 }
 
 function StructCaster(schema: ValueModel | ClusterModel, owner: RootSupervisor) {

package/src/behavior/supervision/RootSupervisor.ts

@@ -8,11 +8,11 @@ import { camelize, InternalError } from "#general";
 import {
     AttributeModel,
     ClusterModel,
-    ElementTag,
     FeatureMap,
     FeatureSet,
     Matter,
     Model,
+    ModelIndex,
     Schema,
     Scope,
     ValueModel,
@@ -59,7 +59,7 @@ export class RootSupervisor implements ValueSupervisor {
     #rootSchema: Schema;
     #root: ValueSupervisor;
     #memberNames?: Set<string>;
-    #attributeNamesToIds?: Map<string, AttributeId>; // Whenever we need more than Attributes and Fields, we need to generalize
+    #propertyNamesAndIds?: Map<string, AttributeId | undefined>;
 
     /**
      * Create a new supervisor.
@@ -86,12 +86,20 @@ export class RootSupervisor implements ValueSupervisor {
     /**
      * Obtain the supervisor for schema.  The result is cached.
      */
-    static for(schema: Schema) {
+    static for<T extends Schema | undefined>(
+        schema: T,
+    ): T extends undefined ? RootSupervisor | undefined : RootSupervisor {
+        if (!schema) {
+            return undefined as any;
+        }
+
         if (cache.has(schema)) {
             return cache.get(schema)!;
         }
+
         const supervisor = new RootSupervisor(schema);
         cache.set(schema, supervisor);
+
         return supervisor;
     }
 
@@ -168,17 +176,14 @@ export class RootSupervisor implements ValueSupervisor {
         return persistent;
     }
 
-    get attributeNamesToIds() {
-        let names = this.#attributeNamesToIds;
+    get propertyNamesAndIds() {
+        let names = this.#propertyNamesAndIds;
         if (!names) {
             names = new Map();
             for (const member of this.#members) {
-                if (member.id === undefined || member.tag !== ElementTag.Attribute) {
-                    continue;
-                }
-                names.set(camelize(member.name), AttributeId(member.id));
+                names.set(camelize(member.name), member.id as AttributeId | undefined);
             }
-            this.#attributeNamesToIds = names;
+            this.#propertyNamesAndIds = names;
         }
         return names;
     }
@@ -188,7 +193,7 @@ export class RootSupervisor implements ValueSupervisor {
      *
      * The {@link Scope.ConformanceMode} defaults to "deconflicted" if you do not override.
      */
-    membersOf<T extends Schema>(schema: T, options: Scope.MemberOptions = {}): Model.ChildOf<T>[] {
+    membersOf<T extends Schema>(schema: T, options: Scope.MemberOptions = {}): ModelIndex<Model.ChildOf<T>> {
         if (options.conformance === undefined) {
             options = { ...options, conformance: "deconflicted" };
         }

package/src/behavior/supervision/ValueSupervisor.ts

@@ -54,7 +54,7 @@ export interface ValueSupervisor {
     readonly manage: ValueSupervisor.Manage;
 
     /**
-     * Apply changes.  Does not validate perform validation.
+     * Apply changes.  Does not perform validation.
      */
     readonly patch: ValueSupervisor.Patch;
 

package/src/behavior/system/commissioning/CommissioningClient.ts

@@ -11,6 +11,7 @@ import {
     Diagnostic,
     Duration,
     ImplementationError,
+    isIpNetworkChannel,
     Logger,
     NotImplementedError,
     Observable,
@@ -23,6 +24,7 @@ import type { ClientNode } from "#node/ClientNode.js";
 import type { Node } from "#node/Node.js";
 import { IdentityService } from "#node/server/IdentityService.js";
 import {
+    ChannelManager,
     CommissioningMode,
     ControllerCommissioner,
     DiscoveryData,
@@ -156,7 +158,11 @@ export class CommissioningClient extends Behavior {
         await this.context.transaction.commit();
 
         const network = this.agent.get(NetworkClient);
-        network.state.startupSubscription = opts.startupSubscription;
+        network.state.defaultSubscription = opts.defaultSubscription;
+        if (opts.autoSubscribe || opts.autoSubscribe === undefined) {
+            // Nodes we commission are auto-subscribed by default, unless disabled explicitly
+            network.state.autoSubscribe = opts.autoSubscribe ?? true;
+        }
         network.state.caseAuthenticatedTags = opts.caseAuthenticatedTags;
 
         logger.notice(
@@ -233,6 +239,20 @@ export class CommissioningClient extends Behavior {
         const node = this.endpoint as ClientNode;
 
         if (addr) {
+            const channels = node.env.get(ChannelManager);
+            if (channels.hasChannel(addr)) {
+                const channel = channels.getChannel(addr).channel;
+                const operationalAddress = isIpNetworkChannel(channel) ? channel.networkAddress : undefined;
+                if (operationalAddress) {
+                    if (this.state.addresses === undefined) {
+                        this.state.addresses = [];
+                    }
+                    if (!this.state.addresses.some(a => ServerAddress.isEqual(ServerAddress(a), operationalAddress))) {
+                        this.state.addresses.push(ServerAddress.definitionOf(operationalAddress));
+                    }
+                }
+            }
+
             node.lifecycle.commissioned.emit(this.context);
         } else {
             node.lifecycle.decommissioned.emit(this.context);
@@ -436,9 +456,9 @@ export namespace CommissioningClient {
         discoveryCapabilities?: TypeFromPartialBitSchema<typeof DiscoveryCapabilitiesBitmap>;
 
         /**
-         * The initial read used to populate node data.
+         * The initial read/subscription used to populate node data.
          *
-         * By default matter.js reads all attributes on the node.  This allows us to efficiently initialize the complete
+         * By default, matter.js reads all attributes on the node.  This allows us to efficiently initialize the complete
          * node structure.
          *
          * If you only require a subset of attributes you can replace this with a more discriminative read.  For
@@ -447,7 +467,7 @@ export namespace CommissioningClient {
          *
          * ```js
          * {
-         *     startupSubscription: Read(
+         *     defaultSubscription: Read(
          *         Read.Attribute({ endpoint: 0 }),
          *         Read.Attribute({ cluster: OnOffCluster })
          *     )
@@ -455,9 +475,17 @@ export namespace CommissioningClient {
          * ```
          *
          * Note that certain clusters like Descriptor and Basic Information contain critical operational data. If your
-         * read omits them then the node will only be partially functional once initialized.
+         * read omits them then the node will only be partially functional once initialized or relevant clusters and
+         * endpoints need to be enabled manually.
+         */
+        defaultSubscription?: Subscribe;
+
+        /**
+         * By default, nodes we commission are automatically subscribed to using the {@link defaultSubscription} (or a
+         * full wildcard subscription if that is undefined).
+         * When set to false, the node will not be automatically subscribed.
          */
-        startupSubscription?: Subscribe | null;
+        autoSubscribe?: boolean;
 
         /**
          * Case Authenticated Tags (CATs) to use for operational CASE sessions with this node.

package/src/behavior/system/commissioning/CommissioningServer.ts

@@ -6,6 +6,7 @@
 
 import { SubscriptionsBehavior } from "#behavior/system/subscriptions/SubscriptionsServer.js";
 import { Endpoint } from "#endpoint/Endpoint.js";
+import { EndpointType } from "#endpoint/type/EndpointType.js";
 import {
     AsyncObservable,
     Bytes,
@@ -343,9 +344,7 @@ export class CommissioningServer extends Behavior {
     }
 
     get #hasAdvertisableDeviceType() {
-        return (
-            this.agent.get(ProductDescriptionServer).state.deviceType !== ProductDescriptionServer.UNKNOWN_DEVICE_TYPE
-        );
+        return this.agent.get(ProductDescriptionServer).state.deviceType !== EndpointType.UNKNOWN_DEVICE_TYPE;
     }
 }
 

package/src/behavior/system/controller/ControllerBehavior.ts

@@ -8,10 +8,8 @@ import { Behavior } from "#behavior/Behavior.js";
 import { BasicInformationBehavior } from "#behaviors/basic-information";
 import { ConnectionlessTransportSet, ImplementationError } from "#general";
 import { Node } from "#node/Node.js";
-import { InteractionServer } from "#node/server/InteractionServer.js";
 import {
     Ble,
-    ClientSubscriptionHandler,
     ClientSubscriptions,
     Fabric,
     FabricAuthority,
@@ -23,6 +21,7 @@ import {
     Scanner,
     ScannerSet,
 } from "#protocol";
+import { FabricId } from "@matter/types";
 import type { CommissioningClient } from "../commissioning/CommissioningClient.js";
 import { CommissioningServer } from "../commissioning/CommissioningServer.js";
 import { NetworkServer } from "../network/NetworkServer.js";
@@ -48,6 +47,7 @@ export class ControllerBehavior extends Behavior {
             throw new ImplementationError("adminFabricLabel must be set for ControllerBehavior.");
         }
         const adminFabricLabel = this.state.adminFabricLabel;
+        const adminFabricId = this.state.adminFabricId;
 
         // Configure discovery transports
         if (this.state.ip === undefined) {
@@ -77,6 +77,10 @@ export class ControllerBehavior extends Behavior {
                     override get adminFabricLabel() {
                         return adminFabricLabel;
                     }
+
+                    get fabricId() {
+                        return adminFabricId;
+                    }
                 })(),
             );
         }
@@ -115,11 +119,6 @@ export class ControllerBehavior extends Behavior {
             netTransports.add(this.env.get(Ble).centralInterface);
         }
 
-        // Install handler to receive data reports for subscriptions
-        const subscriptions = this.env.get(ClientSubscriptions);
-        const interactionServer = this.env.get(InteractionServer);
-        interactionServer.clientHandler = new ClientSubscriptionHandler(subscriptions);
-
         // Clean up as the node goes offline
         const node = Node.forEndpoint(this.endpoint);
         this.reactTo(node.lifecycle.goingOffline, this.#nodeGoingOffline);
@@ -185,5 +184,12 @@ export namespace ControllerBehavior {
          * Contains the label of the admin fabric which is set for all commissioned devices
          */
         adminFabricLabel = "matter.js";
+
+        /**
+         * Contains the FabricId of the admin fabric when a defined number needs to be used because special Certificates
+         * are used.
+         * If not provided, a random FabricId will be generated.
+         */
+        adminFabricId?: FabricId = undefined;
     }
 }