@matter/node 0.11.9 → 0.12.0-alpha.0-20241211-6d80d8b5c

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) {}
 }

package/src/endpoint/server/BehaviorServer.ts

@@ -0,0 +1,387 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { AccessControl } from "#behavior/AccessControl.js";
+import { Behavior } from "#behavior/Behavior.js";
+import { ClusterBehavior } from "#behavior/cluster/ClusterBehavior.js";
+import { type ClusterEvents, Contextual, Resource } from "#behavior/index.js";
+import { StructManager } from "#behavior/state/managed/values/StructManager.js";
+import { Status } from "#behavior/state/transaction/Status.js";
+import { Val } from "#behavior/state/Val.js";
+import { Endpoint } from "#endpoint/Endpoint.js";
+import {
+    camelize,
+    Diagnostic,
+    ImplementationError,
+    InternalError,
+    isObject,
+    Logger,
+    MaybePromise,
+    Observable,
+    ObserverGroup,
+} from "#general";
+import { CommandModel, ElementTag } from "#model";
+import {
+    AttributeServer,
+    ClusterDatasource,
+    ClusterServer,
+    CommandServer,
+    createAttributeServer as ConstructAttributeServer,
+    EventServer,
+    FabricManager,
+    Message,
+    OccurrenceManager,
+    SecureSession,
+} from "#protocol";
+import { Attribute, Command, Event } from "#types";
+import type { EndpointServer } from "./EndpointServer.js";
+
+const logger = Logger.get("BehaviorServer");
+
+export interface BehaviorServer extends ClusterServer {
+    close(): void;
+}
+
+/**
+ * Create a {@link ClusterServer} for a {@link ClusterBehavior}.
+ *
+ * Note that we only create servers for cluster behaviors.  Other {@link Behavior} implementations do not have proper
+ * metadata to go online.
+ *
+ * TODO - refactor element server management after we remove the old API
+ */
+export function BehaviorServer(endpointServer: EndpointServer, type: ClusterBehavior.Type): BehaviorServer {
+    const { id, name, attributes, commands, events } = type.cluster;
+
+    const { endpoint } = endpointServer;
+    const datasource = createClusterDatasource(endpoint, type);
+    const observers = new ObserverGroup();
+
+    const clusterServer: BehaviorServer = {
+        id,
+        name,
+        datasource,
+        attributes: {},
+        commands: {},
+        events: {},
+        close() {
+            observers.close();
+        },
+    };
+
+    // Extract read-only state and observables for setup purposes
+    const stateView = endpoint.stateOf(type) as Val.Struct;
+    const observables = endpoint.eventsOf(type) as unknown as Record<string, Observable>;
+    const elements = endpointServer.endpoint.behaviors.elementsOf(type);
+
+    // Add attribute servers.  Include global attributes as well as cluster attributes
+    for (const name of elements.attributes) {
+        const attribute = attributes[name];
+
+        const server = createAttributeServer(
+            name,
+            attribute,
+            endpoint,
+            type,
+            datasource,
+            stateView,
+            observables,
+            observers,
+        );
+
+        clusterServer.attributes[name] = server;
+        server.assignToEndpoint(endpointServer);
+    }
+
+    // Add command servers
+    for (const name of elements.commands) {
+        const command = commands[name];
+
+        clusterServer.commands[name] = createCommandServer(name, command, endpoint, type);
+    }
+
+    // Event servers
+    for (const name of elements.events) {
+        const server = createEventServer(name, events[name], endpoint, type, observables, observers);
+
+        clusterServer.events[name] = server;
+        server.assignToEndpoint(endpointServer);
+    }
+
+    return clusterServer;
+}
+
+/**
+ * Create the {@link ClusterDatasource} that adapts the Behavior API to the AttributeServer API.
+ */
+function createClusterDatasource(endpoint: Endpoint, type: Behavior.Type): ClusterDatasource {
+    const env = endpoint.env;
+
+    return {
+        get version() {
+            return endpoint.behaviors.versionOf(type);
+        },
+
+        get eventHandler() {
+            return env.get(OccurrenceManager);
+        },
+
+        get fabrics() {
+            return env.get(FabricManager).fabrics;
+        },
+
+        // We handle change management ourselves
+        changed() {},
+
+        // We handle version management ourselves
+        increaseVersion() {
+            return this.version;
+        },
+    };
+}
+
+function createAttributeServer(
+    name: string,
+    definition: Attribute<any, any>,
+    endpoint: Endpoint,
+    type: ClusterBehavior.Type,
+    datasource: ClusterDatasource,
+    stateView: Val.Struct,
+    observables: Record<string, Observable>,
+    observers: ObserverGroup,
+) {
+    function getter(_session: any, _endpoint: any, _isFabricFiltered: any, message?: Message) {
+        if (!message) {
+            // If there is no message this is getLocal
+            return stateView[name];
+        }
+
+        const behavior = behaviorFor(endpoint, type, message);
+
+        behavior.context.activity?.frame(`read ${name}`);
+
+        const trace = behavior.context.trace;
+        if (trace) {
+            trace.path = endpoint.path.at(name);
+        }
+
+        logger.debug("Read", Diagnostic.strong(`${endpoint}.state.${name}`), "via", behavior.context.transaction.via);
+
+        const state = behavior.state as Val.Struct;
+
+        StructManager.assertDirectReadAuthorized(state, name);
+
+        if (trace) {
+            trace.output = state[name];
+        }
+
+        return state[name];
+    }
+
+    function setter(value: any, _session: any, _endpoint: any, message?: Message) {
+        const behavior = behaviorFor(endpoint, type, message);
+
+        behavior.context.activity?.frame(`write ${name}`);
+
+        logger.info("Write", Diagnostic.strong(`${endpoint}.state.${name}`), "via", behavior.context.transaction.via);
+
+        const trace = behavior.context.trace;
+        if (trace) {
+            trace.path = endpoint.path.at(name);
+            trace.input = value;
+        }
+
+        const state = behavior.state as Val.Struct;
+
+        state[name] = value;
+
+        // If the transaction is a write transaction, report that the attribute is updated
+        return behavior.context.transaction?.status === Status.Exclusive;
+    }
+
+    const server = ConstructAttributeServer(
+        type.cluster,
+        definition,
+        name,
+        stateView[name],
+        datasource,
+        getter,
+        setter,
+    );
+
+    // Wire events (FixedAttributeServer is not an AttributeServer so we skip that)
+    if (server instanceof AttributeServer) {
+        const observable = observables[`${name}$Changed`] as ClusterEvents.AttributeObservable;
+        if (observable !== undefined) {
+            observers.on(observable, (_value, _oldValue, context) => {
+                const session = context.session;
+                if (session instanceof SecureSession) {
+                    server.updated(session);
+                } else {
+                    server.updatedLocal();
+                }
+            });
+        }
+    }
+
+    return server;
+}
+
+function createCommandServer(
+    name: string,
+    definition: Command<any, any, any>,
+    endpoint: Endpoint,
+    type: ClusterBehavior.Type,
+) {
+    // TODO: Introduce nicer ways to get command incl caching and such, aka "make api suck less"
+    const schema = type.schema?.member(camelize(name, true), [ElementTag.Command]) as CommandModel;
+    if (schema === undefined) {
+        throw new ImplementationError(`There is no metadata for command ${name}`);
+    }
+    const access = AccessControl(schema);
+
+    const handler = (request: unknown, _session: unknown, message: Message) => {
+        let requestDiagnostic: unknown;
+        if (isObject(request)) {
+            requestDiagnostic = Diagnostic.dict(request);
+        } else if (request !== undefined) {
+            requestDiagnostic = request;
+        } else {
+            requestDiagnostic = Diagnostic.weak("(no payload)");
+        }
+
+        const behavior = behaviorFor(endpoint, type, message);
+
+        const path = endpoint.path.at(name);
+
+        const trace = behavior.context.trace;
+        if (trace) {
+            trace.path = endpoint.path.at(name);
+            trace.input = request;
+        }
+
+        logger.info("Invoke", Diagnostic.strong(path.toString()), behavior.context.transaction.via, requestDiagnostic);
+
+        access.authorizeInvoke(behavior.context, {
+            path,
+            cluster: behavior.cluster.id,
+        });
+
+        let isAsync = false;
+        let activity: undefined | Disposable;
+        let result: unknown;
+        try {
+            activity = behavior.context?.activity?.frame(`invoke ${name}`);
+
+            const invoke = (behavior as unknown as Record<string, (arg: unknown) => unknown>)[name].bind(behavior);
+
+            // Lock if necessary, then invoke
+            if ((behavior.constructor as ClusterBehavior.Type).lockOnInvoke) {
+                const tx = behavior.context.transaction;
+                if (Resource.isLocked(behavior)) {
+                    // Automatic locking with locked resource; requires async lock acquisition
+                    result = (async function invokeAsync() {
+                        await tx.addResources(behavior);
+                        await tx.begin();
+                        return invoke(request);
+                    })();
+                } else {
+                    // Automatic locking on unlocked resource; may proceed synchronously
+                    tx.addResourcesSync(behavior);
+                    tx.beginSync();
+                    result = invoke(request);
+                }
+            } else {
+                // Automatic locking disabled
+                result = invoke(request);
+            }
+
+            if (MaybePromise.is(result)) {
+                isAsync = true;
+                result = Promise.resolve(result)
+                    .then(result => {
+                        if (trace) {
+                            trace.output = result;
+                        }
+                        return result;
+                    })
+                    .finally(() => activity?.[Symbol.dispose]());
+            } else if (trace) {
+                trace.output = result;
+            }
+        } finally {
+            if (!isAsync) {
+                activity?.[Symbol.dispose]();
+            }
+        }
+
+        return result;
+    };
+
+    const server = new CommandServer(
+        definition.requestId,
+        definition.responseId,
+        name,
+        definition.requestSchema,
+        definition.responseSchema,
+        definition.timed,
+        definition.invokeAcl,
+        handler,
+    );
+
+    // Eliminate redundant diagnostic messages
+    server.debug = () => {};
+
+    return server;
+}
+
+function createEventServer(
+    name: string,
+    definition: Event<any, any>,
+    endpoint: Endpoint,
+    type: ClusterBehavior.Type,
+    observables: Record<string, Observable>,
+    observers: ObserverGroup,
+) {
+    const observable = observables[name] as ClusterEvents.EventObservable;
+
+    const server = new EventServer(
+        definition.id,
+        type.cluster.id,
+        name,
+        definition.schema,
+        definition.priority,
+        definition.readAcl,
+    );
+
+    if (observable !== undefined) {
+        observers.on(observable, (payload, _context) => {
+            const maybePromise = server.triggerEvent(payload);
+            if (MaybePromise.is(maybePromise)) {
+                endpoint.env.runtime.add(maybePromise);
+            }
+        });
+    }
+
+    const promise = server.bindToEventHandler(endpoint.env.get(OccurrenceManager));
+    if (MaybePromise.is(promise)) {
+        // Current code structure means this should never happen.  Refactor after removal of old API will resolve this
+        throw new InternalError("Event handler binding returned a promise");
+    }
+
+    return server;
+}
+
+function behaviorFor(endpoint: Endpoint, type: ClusterBehavior.Type, message: Message | undefined) {
+    const context = Contextual.contextOf(message);
+    if (!context) {
+        throw new InternalError("Message context not installed");
+    }
+
+    const agent = context.agentFor(endpoint);
+
+    return agent.get(type);
+}

package/src/endpoint/{EndpointServer.ts → server/EndpointServer.ts}

@@ -6,13 +6,11 @@
 
 import { Behavior } from "#behavior/Behavior.js";
 import { ClusterBehavior } from "#behavior/cluster/ClusterBehavior.js";
-import { BehaviorBacking } from "#behavior/internal/BehaviorBacking.js";
-import { ClusterServerBacking } from "#behavior/internal/ClusterServerBacking.js";
-import { ServerBehaviorBacking } from "#behavior/internal/ServerBehaviorBacking.js";
 import { ImplementationError, InternalError, NotImplementedError } from "#general";
 import { ClusterClientObj, ClusterServer, EndpointInterface } from "#protocol";
 import { ClusterId, ClusterType, EndpointNumber } from "#types";
-import { Endpoint } from "./Endpoint.js";
+import { Endpoint } from "../Endpoint.js";
+import { BehaviorServer } from "./BehaviorServer.js";
 
 const SERVER = Symbol("server");
 interface ServerEndpoint extends Endpoint {
@@ -25,7 +23,7 @@ interface ServerEndpoint extends Endpoint {
 export class EndpointServer implements EndpointInterface {
     #endpoint: Endpoint;
     #name = "";
-    readonly #clusterServers = new Map<ClusterId, ClusterServer>();
+    readonly #clusterServers = new Map<ClusterId, BehaviorServer>();
 
     get endpoint() {
         return this.#endpoint;
@@ -36,26 +34,24 @@ export class EndpointServer implements EndpointInterface {
     }
 
     constructor(endpoint: Endpoint) {
-        (endpoint as ServerEndpoint)[SERVER] = this;
+        // Sanity checks
+        if ((endpoint as ServerEndpoint)[SERVER] !== undefined) {
+            throw new InternalError(`Endpoint ${endpoint} cluster server is already initialized`);
+        }
+        endpoint.construction.assert();
+
         this.#endpoint = endpoint;
         this.#name = endpoint.type.name;
-    }
 
-    createBacking(type: Behavior.Type): BehaviorBacking {
-        let backing: BehaviorBacking;
-        if (type.prototype instanceof ClusterBehavior) {
-            const cluster = (type as ClusterBehavior.Type).cluster;
+        (endpoint as ServerEndpoint)[SERVER] = this;
 
-            // Sanity check
-            if (this.#clusterServers.has(cluster.id)) {
-                throw new InternalError(`${this.#endpoint}.${cluster.id} initialized multiple times`);
+        for (const type of Object.values(endpoint.behaviors.supported)) {
+            if (!(type.prototype instanceof ClusterBehavior)) {
+                continue;
             }
 
-            backing = new ClusterServerBacking(this, type as ClusterBehavior.Type);
-        } else {
-            backing = new ServerBehaviorBacking(this.#endpoint, type, this.#endpoint.behaviors.optionsFor(type));
+            this.#serve(type);
         }
-        return backing;
     }
 
     get number() {
@@ -66,6 +62,20 @@ export class EndpointServer implements EndpointInterface {
         return this.#name;
     }
 
+    updateServers() {
+        for (const type of Object.values(this.#endpoint.behaviors.supported)) {
+            if (!(type.prototype instanceof ClusterBehavior)) {
+                continue;
+            }
+
+            if (this.#clusterServers.has((type as ClusterBehavior.Type).cluster?.id)) {
+                continue;
+            }
+
+            this.#serve(type);
+        }
+    }
+
     getNumber(): EndpointNumber {
         if (this.number === undefined) {
             throw new InternalError("Endpoint ID has not been assigned yet");
@@ -103,7 +113,9 @@ export class EndpointServer implements EndpointInterface {
     }
 
     async [Symbol.asyncDispose]() {
-        // I believe the cluster servers are effectively disposed when the structure is emptied
+        for (const server of this.#clusterServers.values()) {
+            server.close();
+        }
         this.#clusterServers.clear();
         delete (this.#endpoint as ServerEndpoint)[SERVER];
         for (const endpoint of this.#endpoint.parts) {
@@ -118,7 +130,7 @@ export class EndpointServer implements EndpointInterface {
         // Unused, should move out of EndpointInterface
     }
 
-    addClusterServer(server: ClusterServer): void {
+    addClusterServer(server: BehaviorServer): void {
         this.#clusterServers.set(server.id, server);
     }
 
@@ -173,6 +185,24 @@ export class EndpointServer implements EndpointInterface {
         }
     }
 
+    /**
+     * Install a ClusterServer for a behavior.
+     */
+    #serve(type: Behavior.Type) {
+        // Sanity checks
+        const { cluster } = type as ClusterBehavior.Type;
+        if (cluster === undefined) {
+            throw new InternalError(`Cannot serve ${this.endpoint} behavior ${type.id}} because it is not a cluster`);
+        }
+        if (this.#clusterServers.has(cluster.id)) {
+            throw new ImplementationError(`Duplicate behaviors for ${this.endpoint} define cluster ${cluster.id}`);
+        }
+
+        // Create ClusterServer
+        const clusterServer = BehaviorServer(this, type as ClusterBehavior.Type);
+        this.#clusterServers.set(cluster.id, clusterServer);
+    }
+
     /**
      * Retrieve the server for an endpoint.
      */

package/src/{node → endpoint}/server/ServerEndpointInitializer.ts

@@ -6,12 +6,12 @@
 
 import { Behavior } from "#behavior/Behavior.js";
 import { BehaviorBacking } from "#behavior/internal/BehaviorBacking.js";
+import { ServerBehaviorBacking } from "#behavior/internal/ServerBehaviorBacking.js";
 import { Endpoint } from "#endpoint/Endpoint.js";
-import { EndpointServer } from "#endpoint/EndpointServer.js";
 import { EndpointInitializer } from "#endpoint/properties/EndpointInitializer.js";
 import { Environment, InternalError, Logger } from "#general";
 import { DescriptorServer } from "../../behaviors/descriptor/DescriptorServer.js";
-import { ServerNodeStore } from "../storage/ServerNodeStore.js";
+import { ServerNodeStore } from "../../node/storage/ServerNodeStore.js";
 
 const logger = Logger.get("BehaviorInit");
 
@@ -50,13 +50,13 @@ export class ServerEndpointInitializer extends EndpointInitializer {
     }
 
     /**
-     * If a {@link Endpoint} does not yet have a {@link EndpointServer}, create one now, then create a
-     * {@link BehaviorBacking} for a specific {@link Behavior}.
+     * Create the backing.
      *
-     * This is where we adapt endpoints and behaviors for a server role.
+     * If the behavior is a cluster behavior and the node is already initialized, create a server when the behavior
+     * initializes.
      */
-    createBacking(endpoint: Endpoint, behavior: Behavior.Type): BehaviorBacking {
-        return EndpointServer.forEndpoint(endpoint).createBacking(behavior);
+    createBacking(endpoint: Endpoint, type: Behavior.Type): BehaviorBacking {
+        return new ServerBehaviorBacking(endpoint, type, endpoint.behaviors.optionsFor(type));
     }
 
     /**

package/src/endpoint/server/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./EndpointServer.js";
+export * from "./ServerEndpointInitializer.js";

package/src/endpoint/type/MutableEndpoint.ts

@@ -75,6 +75,10 @@ export function MutableEndpoint<const T extends EndpointType.Options>(options: T
                 behaviors: SupportedBehaviors.extend(this.behaviors, behaviors),
             });
         },
+
+        withBehaviors(this: MutableEndpoint, ...behaviors: Behavior.Type[]) {
+            return this.with(...behaviors);
+        },
     } as unknown as MutableEndpoint.With<
         EndpointType.For<T>,
         T["behaviors"] extends SupportedBehaviors ? T["behaviors"] : {}

package/src/node/Node.ts

@@ -82,6 +82,10 @@ export abstract class Node<T extends Node.CommonRootEndpoint = Node.CommonRootEn
      * Bring the node online.
      */
     async start() {
+        await this.lifecycle.mutex.produce(this.startWithMutex.bind(this));
+    }
+
+    protected async startWithMutex() {
         this.env.runtime.add(this);
 
         try {
@@ -123,6 +127,10 @@ export abstract class Node<T extends Node.CommonRootEndpoint = Node.CommonRootEn
      * Once the node is offline you may use {@link start} to bring the node online again.
      */
     async cancel() {
+        await this.lifecycle.mutex.produce(this.cancelWithMutex.bind(this));
+    }
+
+    protected async cancelWithMutex() {
         if (!this.#runtime) {
             return;
         }
@@ -133,17 +141,27 @@ export abstract class Node<T extends Node.CommonRootEndpoint = Node.CommonRootEn
     }
 
     override async close() {
+        await this.lifecycle.mutex.produce(this.closeWithMutex.bind(this));
+    }
+
+    protected async closeWithMutex() {
         // The runtime is not designed to operate with a node that is shutting down so destroy it before performing
         // actual close
-        //
-        // TODO - this should probably block other functions like start()
         if (this.#runtime) {
-            await this.cancel();
+            await this.cancelWithMutex();
         }
 
         await super.close();
     }
 
+    override async reset() {
+        await this.lifecycle.mutex.produce(this.resetWithMutex.bind(this));
+    }
+
+    protected async resetWithMutex() {
+        return super.reset();
+    }
+
     /**
      * Create the network runtime.
      */
@@ -177,7 +195,7 @@ export abstract class Node<T extends Node.CommonRootEndpoint = Node.CommonRootEn
     }
 
     override async [Construction.destruct]() {
-        await this.cancel();
+        await this.cancelWithMutex();
         await super[Construction.destruct]();
         DiagnosticSource.delete(this);
     }

package/src/node/NodeLifecycle.ts

@@ -7,7 +7,7 @@
 import { ActionContext } from "#behavior/context/ActionContext.js";
 import { Endpoint } from "#endpoint/Endpoint.js";
 import { EndpointLifecycle } from "#endpoint/properties/EndpointLifecycle.js";
-import { AsyncObservable, Observable } from "#general";
+import { AsyncObservable, Mutex, Observable } from "#general";
 
 /**
  * Extended lifecycle information that only applies to root endpoints.
@@ -21,10 +21,13 @@ export class NodeLifecycle extends EndpointLifecycle {
     #initialized = Observable<[isCommissioned: boolean]>();
     #isOnline = false;
     #isCommissioned = false;
+    #mutex: Mutex;
 
     constructor(endpoint: Endpoint) {
         super(endpoint);
 
+        this.#mutex = new Mutex(endpoint);
+
         this.#online.on(() => {
             this.#isOnline = true;
         });
@@ -97,4 +100,17 @@ export class NodeLifecycle extends EndpointLifecycle {
     get decommissioned() {
         return this.#decommissioned;
     }
+
+    /**
+     * Mutex for protecting node lifecycle transitions.
+     *
+     * Methods that implement complex async lifecycle transitions use this mutex to ensure conflicting operations cannot
+     * intermingle.
+     *
+     * Generally methods that hold this mutex have a protected "*WithMutex" variant.  This allows for nesting of logic
+     * that requires the mutex without causing deadlock.
+     */
+    get mutex() {
+        return this.#mutex;
+    }
 }