@matter/node 0.11.9 → 0.12.0-alpha.0-20241213-fcd71a96d

package/src/behavior/system/network/ServerNetworkRuntime.ts

@@ -310,6 +310,8 @@ export class ServerNetworkRuntime extends NetworkRuntime {
     }
 
     protected override async stop() {
+        this.blockNewActivity();
+
         this.#observers.close();
 
         await this.owner.env.close(DeviceCommissioner);
@@ -320,6 +322,10 @@ export class ServerNetworkRuntime extends NetworkRuntime {
 
         await this.#interactionServer?.[Symbol.asyncDispose]();
         this.#interactionServer = undefined;
+
+        // DeviceAdvertiser does this but we do so here just in case DeviceAdvertiser did not initialize for some reason
+        await this.#mdnsBroadcaster?.close();
+        this.#mdnsBroadcaster = undefined;
     }
 
     protected override blockNewActivity() {

package/src/behaviors/administrator-commissioning/AdministratorCommissioningServer.ts

@@ -201,16 +201,16 @@ export class AdministratorCommissioningServer extends AdministratorCommissioning
             );
         }
 
-        if (commissioningTimeout > MAXIMUM_COMMISSIONING_TIMEOUT_S) {
+        if (commissioningTimeout > this.internal.maximumCommissioningTimeoutS) {
             throw new StatusResponseError(
-                `Commissioning timeout must not exceed ${MAXIMUM_COMMISSIONING_TIMEOUT_S} seconds.`,
+                `Commissioning timeout must not exceed ${this.internal.maximumCommissioningTimeoutS} seconds.`,
                 StatusCode.InvalidCommand,
             );
         }
 
-        if (commissioningTimeout < MINIMUM_COMMISSIONING_TIMEOUT_S) {
+        if (commissioningTimeout < this.internal.minimumCommissioningTimeoutS) {
             throw new StatusResponseError(
-                `Commissioning timeout must not be lower then ${MINIMUM_COMMISSIONING_TIMEOUT_S} seconds.`,
+                `Commissioning timeout must not be lower then ${this.internal.minimumCommissioningTimeoutS} seconds.`,
                 StatusCode.InvalidCommand,
             );
         }
@@ -279,6 +279,16 @@ export namespace AdministratorCommissioningServer {
     export class Internal {
         commissioningWindowTimeout?: Timer;
         stopMonitoringFabricForRemoval?: () => void;
+
+        /**
+         * Mandated by spec; should only be modified in testing.
+         */
+        minimumCommissioningTimeoutS = MINIMUM_COMMISSIONING_TIMEOUT_S;
+
+        /**
+         * Mandated by spec; should only be modified in testing.
+         */
+        maximumCommissioningTimeoutS = MAXIMUM_COMMISSIONING_TIMEOUT_S;
     }
 
     export class State extends AdministratorCommissioningBehavior.State {

package/src/behaviors/general-diagnostics/GeneralDiagnosticsServer.ts

@@ -8,6 +8,7 @@ import { Val } from "#behavior/state/Val.js";
 import { ValueSupervisor } from "#behavior/supervision/ValueSupervisor.js";
 import { NetworkServer } from "#behavior/system/network/NetworkServer.js";
 import { NetworkCommissioningServer } from "#behaviors/network-commissioning";
+import { TimeSynchronizationBehavior } from "#behaviors/time-synchronization";
 import { GeneralDiagnostics } from "#clusters/general-diagnostics";
 import { Endpoint } from "#endpoint/Endpoint.js";
 import { Bytes, ImplementationError, ipv4ToBytes, Logger, Time, Timer } from "#general";
@@ -102,9 +103,20 @@ export class GeneralDiagnosticsServer extends Base {
 
     override timeSnapshot() {
         const time = Time.nowMs();
+
+        // TC_DGGEN_2_4.py fails us if we set this without TimeSynchronizationCluster support.  Spec is worded poorly
+        // but my read of "SHALL only if" is "may not unless" and not "SHALL if and only if".  But conforming to tests
+        // for now
+        const posixTimeMs =
+            this.agent.has(TimeSynchronizationBehavior) &&
+            this.agent.get(TimeSynchronizationBehavior).state.utcTime !== null
+                ? time
+                : null;
+
         return {
-            systemTimeMs: time - this.internal.bootUpTime,
-            posixTimeMs: time,
+            systemTimeMs: time - Time.startup.systemMs,
+
+            posixTimeMs,
         };
     }
 
@@ -280,7 +292,6 @@ export class GeneralDiagnosticsServer extends Base {
         );
 
         // Update the timestamps now that node is really online.
-        this.internal.bootUpTime = Time.nowMs();
         this.internal.lastTotalOperationalHoursCounterUpdateTime = Time.nowMs();
 
         this.internal.lastTotalOperationalHoursTimer = Time.getPeriodicTimer(
@@ -368,9 +379,6 @@ export class GeneralDiagnosticsServer extends Base {
 
 export namespace GeneralDiagnosticsServer {
     export class Internal {
-        /** Remember the bootUp time for the device. */
-        bootUpTime: number = Time.nowMs();
-
         /** Last time the total operational hours counter was updated. */
         lastTotalOperationalHoursCounterUpdateTime: number = Time.nowMs();
 
@@ -388,12 +396,11 @@ export namespace GeneralDiagnosticsServer {
         [Val.properties](endpoint: Endpoint, _session: ValueSupervisor.Session) {
             return {
                 /**
-                 * Dynamically calculate the upTime. This is ok because the attribute is not send out via subscriptions
+                 * Dynamically calculate the upTime. This is ok because the attribute is not sent via subscriptions
                  * anyway.
                  */
                 get upTime() {
-                    const bootUpTime = endpoint.behaviors.internalsOf(GeneralDiagnosticsServer).bootUpTime;
-                    return Math.round((Time.nowMs() - bootUpTime) / 1000);
+                    return Math.round((Time.nowMs() - Time.startup.systemMs) / 1000);
                 },
 
                 /**

package/src/behaviors/operational-credentials/OperationalCredentialsServer.ts

@@ -119,7 +119,7 @@ export class OperationalCredentialsServer extends OperationalCredentialsBehavior
 
         if (isForUpdateNoc && this.session.isPase) {
             throw new StatusResponseError(
-                "csrRequest for UpdateNoc received on a PASE session.",
+                "csrRequest for UpdateNoc received on a PASE session",
                 StatusCode.InvalidCommand,
             );
         }
@@ -128,7 +128,7 @@ export class OperationalCredentialsServer extends OperationalCredentialsBehavior
         const failsafeContext = commissioner.failsafeContext;
         if (failsafeContext.fabricIndex !== undefined) {
             throw new StatusResponseError(
-                `csrRequest received after ${failsafeContext.forUpdateNoc ? "UpdateNOC" : "AddNOC"} already invoked.`,
+                `csrRequest received after ${failsafeContext.forUpdateNoc ? "UpdateNOC" : "AddNOC"} already invoked`,
                 StatusCode.ConstraintError,
             );
         }
@@ -205,7 +205,7 @@ export class OperationalCredentialsServer extends OperationalCredentialsBehavior
 
         if (failsafeContext.fabricIndex !== undefined) {
             throw new StatusResponseError(
-                `addNoc received after ${failsafeContext.forUpdateNoc ? "UpdateNOC" : "AddNOC"} already invoked.`,
+                `AddNoc is illegal after ${failsafeContext.forUpdateNoc ? "UpdateNOC" : "AddNOC"} in the same failsafe context`,
                 StatusCode.ConstraintError,
             );
         }
@@ -213,20 +213,20 @@ export class OperationalCredentialsServer extends OperationalCredentialsBehavior
         if (!failsafeContext.hasRootCert) {
             return {
                 statusCode: OperationalCredentials.NodeOperationalCertStatus.InvalidNoc,
-                debugText: "Root certificate not found.",
+                debugText: "Root certificate not found",
             };
         }
 
         if (failsafeContext.csrSessionId !== this.session.id) {
             return {
                 statusCode: OperationalCredentials.NodeOperationalCertStatus.MissingCsr,
-                debugText: "CSR not found in failsafe context.",
+                debugText: "CSR not found in failsafe context",
             };
         }
 
         if (failsafeContext.forUpdateNoc) {
             throw new StatusResponseError(
-                `addNoc received after csr request was invoked for UpdateNOC.`,
+                `AddNoc is illegal after CsrRequest for UpdateNOC in same failsafe context`,
                 StatusCode.ConstraintError,
             );
         }
@@ -235,7 +235,7 @@ export class OperationalCredentialsServer extends OperationalCredentialsBehavior
         if (state.commissionedFabrics >= state.supportedFabrics) {
             return {
                 statusCode: OperationalCredentials.NodeOperationalCertStatus.TableFull,
-                debugText: `No more fabrics can be added because limit ${state.supportedFabrics} reached.`,
+                debugText: `No more fabrics can be added because limit ${state.supportedFabrics} reached`,
             };
         }
 
@@ -268,7 +268,7 @@ export class OperationalCredentialsServer extends OperationalCredentialsBehavior
 
         try {
             if (this.session.isPase) {
-                logger.debug(`Add Fabric ${fabric.fabricIndex} to PASE session ${this.session.name}.`);
+                logger.debug(`Add Fabric ${fabric.fabricIndex} to PASE session ${this.session.name}`);
                 this.session.addAssociatedFabric(fabric);
             }
 
@@ -277,7 +277,7 @@ export class OperationalCredentialsServer extends OperationalCredentialsBehavior
             const existingNocIndex = this.state.nocs.findIndex(n => n.fabricIndex === fabric.fabricIndex);
             if (existingFabricIndex !== -1 || existingNocIndex !== -1) {
                 throw new MatterFlowError(
-                    `FabricIndex ${fabric.fabricIndex} already exists in state. This should not happen.`,
+                    `FabricIndex ${fabric.fabricIndex} already exists in state. This should not happen`,
                 );
             }
         } catch (e) {
@@ -308,32 +308,35 @@ export class OperationalCredentialsServer extends OperationalCredentialsBehavior
 
         if (timedOp.fabricIndex !== undefined) {
             throw new StatusResponseError(
-                `updateNoc received after ${timedOp.forUpdateNoc ? "UpdateNOC" : "AddNOC"} already invoked.`,
+                `UpdateNoc is illegal after ${timedOp.forUpdateNoc ? "UpdateNOC" : "AddNOC"} in same failsafe context`,
                 StatusCode.ConstraintError,
             );
         }
 
-        if (timedOp.forUpdateNoc) {
+        if (timedOp.forUpdateNoc === false) {
             throw new StatusResponseError(
-                `addNoc received after csr request was invoked for UpdateNOC.`,
+                "UpdateNoc is illegal after CsrRequest for AddNOC in same failsafe context",
                 StatusCode.ConstraintError,
             );
         }
 
-        if (timedOp.hasRootCert) {
+        if (timedOp.rootCertSet) {
             throw new StatusResponseError(
-                "Trusted root certificate added in this session which is now allowed for UpdateNOC.",
+                "UpdateNoc is illegal after AddTrustedRootCertificate in same failsafe context",
                 StatusCode.ConstraintError,
             );
         }
 
-        if (!timedOp.forUpdateNoc) {
-            throw new StatusResponseError("csrRequest not invoked for UpdateNOC.", StatusCode.ConstraintError);
+        if (timedOp.forUpdateNoc === undefined) {
+            throw new StatusResponseError(
+                "UpdateNoc is illegal before CsrRequest in same failsafe context",
+                StatusCode.ConstraintError,
+            );
         }
 
         if (this.session.associatedFabric.fabricIndex !== timedOp.associatedFabric?.fabricIndex) {
             throw new StatusResponseError(
-                "Fabric of this session and the failsafe context do not match.",
+                "Fabric of this session and the failsafe context do not match",
                 StatusCode.ConstraintError,
             );
         }
@@ -395,16 +398,19 @@ export class OperationalCredentialsServer extends OperationalCredentialsBehavior
     override addTrustedRootCertificate({ rootCaCertificate }: OperationalCredentials.AddTrustedRootCertificateRequest) {
         const failsafeContext = this.#failsafeContext;
 
-        if (failsafeContext.hasRootCert) {
+        // TC_OPCREDS_3_4 fails if we don't allow set of the root certificate in updates, even though that's illegal and
+        // UpdateNoc will subsequently fail.  So we can't just test for presence of root certificate; we actually need
+        // to test if it's been set
+        if (failsafeContext.rootCertSet) {
             throw new StatusResponseError(
-                "Trusted root certificate already added in this FailSafe context.",
+                "Trusted root certificate already added in this FailSafe context",
                 StatusCode.ConstraintError,
             );
         }
 
         if (failsafeContext.fabricIndex !== undefined) {
             throw new StatusResponseError(
-                `Cannot add trusted root certificates after ${failsafeContext.forUpdateNoc ? "UpdateNOC" : "AddNOC"}.`,
+                `Cannot add trusted root certificates after ${failsafeContext.forUpdateNoc ? "UpdateNOC" : "AddNOC"}`,
                 StatusCode.ConstraintError,
             );
         }

package/src/endpoint/Agent.ts

@@ -101,7 +101,7 @@ export class Agent {
     /**
      * Trigger initialization of a supported {@link Behavior.Type}.
      *
-     * Functionally identical to {@link load} but has no return value and errors are logged rathjer than thrown.
+     * Functionally identical to {@link load} but has no return value and errors are logged rather than thrown.
      */
     activate(type: Behavior.Type) {
         this.#endpoint.behaviors.activate(type, this);

package/src/endpoint/index.ts

@@ -6,7 +6,7 @@
 
 export * from "./Agent.js";
 export * from "./Endpoint.js";
-export * from "./EndpointServer.js";
 export * from "./properties/index.js";
+export * from "./server/index.js";
 export * from "./storage/index.js";
 export * from "./type/index.js";

package/src/endpoint/properties/Behaviors.ts

@@ -6,7 +6,6 @@
 
 import { Behavior } from "#behavior/Behavior.js";
 import type { ClusterBehavior } from "#behavior/cluster/ClusterBehavior.js";
-import { ValidatedElements } from "#behavior/cluster/ValidatedElements.js";
 import { ActionContext } from "#behavior/context/ActionContext.js";
 import { ActionTracer } from "#behavior/context/ActionTracer.js";
 import { NodeActivity } from "#behavior/context/NodeActivity.js";
@@ -21,12 +20,10 @@ import {
     Diagnostic,
     EventEmitter,
     ImplementationError,
-    InternalError,
     Lifecycle,
     Logger,
     MaybePromise,
     ReadOnlyError,
-    UninitializedDependencyError,
 } from "#general";
 import { FeatureSet } from "#model";
 import { ClusterType } from "#types";
@@ -41,6 +38,12 @@ import type { SupportedBehaviors } from "./SupportedBehaviors.js";
 
 const logger = Logger.get("Behaviors");
 
+export interface SupportedElements {
+    attributes: Set<string>;
+    commands: Set<string>;
+    events: Set<string>;
+}
+
 /**
  * This class manages {@link Behavior} instances owned by a {@link Endpoint}.
  */
@@ -80,10 +83,9 @@ export class Behaviors {
                 return result;
             }
 
+            const elements = this.elementsOf(type);
             const elementDiagnostic = Array<unknown>();
 
-            const elements = new ValidatedElements(type as ClusterBehavior.Type);
-
             const features = new FeatureSet(cluster.supportedFeatures);
             if (features.size) {
                 elementDiagnostic.push([Diagnostic.strong("features"), features]);
@@ -148,7 +150,7 @@ export class Behaviors {
         }
 
         // Initialization action.  We initialize all behaviors in the same transaction
-        const initializeBehaviors = (context: ActionContext) => {
+        const initializeBehaviors = (context: ActionContext): MaybePromise => {
             const agent = context.agentFor(this.#endpoint);
 
             // Activate behaviors
@@ -161,7 +163,7 @@ export class Behaviors {
             }
 
             // Wait for all behaviors to initialize
-            return Construction.all(
+            let promise = Construction.all(
                 {
                     [Symbol.iterator]: () => {
                         return Object.values(this.#backings)[Symbol.iterator]();
@@ -170,6 +172,16 @@ export class Behaviors {
 
                 causes => new EndpointBehaviorsError(causes),
             );
+
+            // Notify other components that participate in initialization
+            const endpointInitializer = this.#endpoint.env.get(EndpointInitializer);
+            if (promise) {
+                promise = promise.then(() => endpointInitializer.behaviorsInitialized(agent));
+            } else {
+                promise = endpointInitializer.behaviorsInitialized(agent);
+            }
+
+            return promise;
         };
 
         // Initialize instrumentation
@@ -463,17 +475,36 @@ export class Behaviors {
      * does access to {@link Behavior.State} and {@link Behavior.Events}.
      */
     internalsOf<T extends Behavior.Type>(type: T) {
-        let backing = this.#backings[type.id];
-        if (!backing) {
-            this.#activateLate(type);
-            backing = this.#backings[type.id];
-            if (backing === undefined) {
-                throw new InternalError(`Behavior ${this.#endpoint}.${type.id} late activation did not create backing`);
-            }
-        }
+        const backing = this.#backingFor(type);
         return backing.getInternal() as InstanceType<T["Internal"]>;
     }
 
+    /**
+     * Obtain current data version of behavior.
+     */
+    versionOf(type: Behavior.Type) {
+        const backing = this.#backingFor(type);
+        return backing.datasource.version;
+    }
+
+    /**
+     * Access elements supported by a behavior.
+     */
+    elementsOf(type: Behavior.Type): SupportedElements {
+        if (!this.has(type)) {
+            throw new ImplementationError(`Endpoint ${this.#endpoint} does not support behavior ${type.id}`);
+        }
+
+        const elements = this.#backingFor(type).elements;
+        if (elements === undefined) {
+            throw new ImplementationError(
+                `Endpoint ${this.#endpoint} behavior ${type.id} elements accessed before initialization`,
+            );
+        }
+
+        return elements;
+    }
+
     #activateLate(type: Behavior.Type) {
         const result = OfflineContext.act("behavior-late-activation", this.#endpoint.env.get(NodeActivity), context =>
             this.activate(type, context.agentFor(this.#endpoint)),
@@ -495,29 +526,26 @@ export class Behaviors {
     }
 
     /**
-     * Obtain a backing for an endpoint shortcut.
+     * Obtain a backing for a behavior.
      */
-    #backingFor(container: string, type: Behavior.Type) {
+    #backingFor(type: Behavior.Type) {
+        // Crash if endpoint is not initialized
         if (this.#endpoint.construction.status !== Lifecycle.Status.Initializing) {
             this.#endpoint.construction.assert(this.#endpoint.toString(), `behavior ${type.id}`);
         }
 
+        // Obtain backing
         let backing = this.#backings[type.id];
+
+        // If backing is not already initialized, attempt late initialization
         if (!backing) {
-            try {
-                this.#activateLate(type);
-            } catch (e) {
-                logger.warn(`Cannot initialize ${container}.${type.id} until node is initialized: ${e}`);
-                throw new UninitializedDependencyError(
-                    `${container}.${type.id}`,
-                    "is not available until node is initialized, you may await node.construction to avoid this error",
-                );
-            }
+            this.#activateLate(type);
             backing = this.#backings[type.id];
             if (backing === undefined) {
-                throw new InternalError(`Behavior ${this.#endpoint}.${type.id} late activation did not create backing`);
+                throw new BehaviorInitializationError(`${this.#endpoint}.${type.id}`, "initialization failed");
             }
         }
+
         return backing;
     }
 
@@ -556,7 +584,7 @@ export class Behaviors {
     #augmentEndpoint(type: Behavior.Type) {
         Object.defineProperty(this.#endpoint.state, type.id, {
             get: () => {
-                return this.#backingFor("state", type).stateView;
+                return this.#backingFor(type).stateView;
             },
 
             set() {

package/src/endpoint/properties/EndpointInitializer.ts

@@ -4,9 +4,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Behavior } from "#behavior/Behavior.js";
-import { BehaviorBacking } from "#behavior/internal/BehaviorBacking.js";
-import { Endpoint } from "../Endpoint.js";
+import type { Behavior } from "#behavior/Behavior.js";
+import type { BehaviorBacking } from "#behavior/internal/BehaviorBacking.js";
+import type { Agent } from "#endpoint/Agent.js";
+import type { Endpoint } from "../Endpoint.js";
 
 /**
  * Base class for {@link Endpoint} initialization services.
@@ -35,4 +36,9 @@ export abstract class EndpointInitializer {
      * @returns a new {@link BehaviorBacking}
      */
     abstract createBacking(endpoint: Endpoint, type: Behavior.Type): BehaviorBacking;
+
+    /**
+     * Invoked after behaviors are initialized but before the initialization transaction commits.
+     */
+    behaviorsInitialized(_agent: Agent) {}
 }