@matter/protocol 0.13.1-alpha.0-20250515-a4c61c546 → 0.13.1-alpha.0-20250516-6288f3c54

package/src/action/client/ClientInteraction.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Interactable } from "#action/Interactable.js";
+import { Interactable, InteractionSession } from "#action/Interactable.js";
 import { Invoke } from "#action/request/Invoke.js";
 import { Read } from "#action/request/Read.js";
 import { Subscribe } from "#action/request/Subscribe.js";
@@ -13,13 +13,11 @@ import { InvokeResult } from "#action/response/InvokeResult.js";
 import { ReadResult } from "#action/response/ReadResult.js";
 import { SubscribeResult } from "#action/response/SubscribeResult.js";
 import { WriteResult } from "#action/response/WriteResult.js";
-import { AccessControl } from "#action/server/AccessControl.js";
-import { CancelablePromise, Environment, Environmental, NotImplementedError, PromiseQueue } from "#general";
+import { Environment, Environmental, NotImplementedError, PromiseQueue } from "#general";
 import { InteractionClientMessenger } from "#interaction/InteractionMessenger.js";
 import { SubscriptionClient } from "#interaction/SubscriptionClient.js";
 import { InteractionQueue } from "#peer/InteractionQueue.js";
 import { ExchangeProvider } from "#protocol/ExchangeProvider.js";
-import { WriteResponse } from "#types";
 
 export interface ClientInteractableContext {
     exchanges: ExchangeProvider;
@@ -30,7 +28,7 @@ export interface ClientInteractableContext {
 /**
  * This is a WIP and currently largely a stub.
  */
-export class ClientInteraction<SessionT extends AccessControl.Session = AccessControl.Session>
+export class ClientInteraction<SessionT extends InteractionSession = InteractionSession>
     implements Interactable<SessionT>
 {
     readonly #exchanges: ExchangeProvider;
@@ -66,28 +64,38 @@ export class ClientInteraction<SessionT extends AccessControl.Session = AccessCo
         throw new NotImplementedError();
     }
 
-    write<T extends Write>(request: T, _session?: SessionT) {
-        return new CancelablePromise<void | WriteResponse>((resolve, reject) => {
-            InteractionClientMessenger.create(this.#exchanges).then(messenger => {
-                const send = messenger.sendWriteCommand(request);
-
-                let sendResolve;
-                if (request.suppressResponse) {
-                    sendResolve = send.then(() => {
-                        resolve();
-                    });
-                } else {
-                    sendResolve = send.then(resolve);
-                }
-
-                sendResolve.catch(reject);
-            }, reject);
-        }) as WriteResult<T>;
+    async write<T extends Write>(request: T, _session?: SessionT): WriteResult<T> {
+        const messenger = await InteractionClientMessenger.create(this.#exchanges);
+        const response = await messenger.sendWriteCommand(request);
+        if (request.suppressResponse) {
+            return undefined as Awaited<WriteResult<T>>;
+        }
+        if (!response || !response.writeResponses?.length) {
+            return new Array<WriteResult.AttributeStatus>() as Awaited<WriteResult<T>>;
+        } else {
+            return response.writeResponses.map(
+                ({
+                    path: { nodeId, endpointId, clusterId, attributeId, listIndex },
+                    status: { status, clusterStatus },
+                }) => ({
+                    kind: "attr-status",
+                    path: {
+                        nodeId,
+                        endpointId: endpointId!,
+                        clusterId: clusterId!,
+                        attributeId: attributeId!,
+                        listIndex,
+                    },
+                    status: status!,
+                    clusterStatus,
+                }),
+            ) as Awaited<WriteResult<T>>;
+        }
     }
 
     invoke<T extends Invoke>(request: Invoke, _session?: SessionT): InvokeResult<T> {
         if (request.suppressResponse) {
-            return new CancelablePromise<void>((resolve, reject) => {
+            return new Promise<void>((resolve, reject) => {
                 InteractionClientMessenger.create(this.#exchanges)
                     .then(messenger =>
                         messenger

package/src/action/protocols.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { InteractionSession } from "#action/Interactable.js";
 import { OccurrenceManager } from "#events/OccurrenceManager.js";
 import { MaybePromise, Observable } from "#general";
 import { DataModelPath, MatterModel } from "#model";
@@ -106,12 +107,17 @@ export interface ClusterProtocol {
     stateChanged: Observable<[changes: AttributeId[], version: number], MaybePromise>;
 
     /**
-     * Access a record of attribute values, keyed by attribute ID.
+     * Read-only state of the cluster
+     */
+    readState(session: InteractionSession): Val.ProtocolStruct;
+
+    /**
+     * Writeable record of attribute values, keyed by attribute ID.
      *
      * Note that current protocol implementations do not filter data within this responsibility based on the
      * session.  So doing is the responsibility of the node implementation.
      */
-    open(session: AccessControl.Session): Val.ProtocolStruct;
+    openForWrite(session: InteractionSession): Promise<Val.ProtocolStruct>;
 }
 
 /**

package/src/action/request/Write.ts

@@ -4,10 +4,133 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { WriteRequest } from "#types";
+import { FALLBACK_INTERACTIONMODEL_REVISION } from "#session/Session.js";
+import { AttributeData, ClusterType, WriteRequest } from "#types";
+import { MalformedRequestError } from "./MalformedRequestError.js";
+import { Specifier } from "./Specifier.js";
 
-export interface Write extends WriteRequest {
-    timeout?: number;
+export interface Write extends WriteRequest {}
+
+/**
+ * Formulate a write-request using Matter numeric IDs.
+ */
+export function Write(options: Write.Options): Write;
+
+/**
+ * Formulate a write-request with extended options and name-based IDs.
+ */
+export function Write(options: Write.Options, ...data: Write.Attribute[]): Write;
+
+/**
+ * Formulate a write-request with name-based IDs.
+ */
+export function Write(...data: Write.Attribute[]): Write;
+
+export function Write(optionsOrData: Write.Options | Write.Attribute, ...data: Write.Attribute[]): Write {
+    let options;
+    if ("kind" in optionsOrData) {
+        data = [optionsOrData, ...data];
+        options = {};
+    } else {
+        options = optionsOrData;
+    }
+    const { writes: writeRequests = [] } = options;
+
+    const result: Write = {
+        timedRequest: !!options.timed || !!options.timeout,
+        writeRequests,
+        interactionModelRevision: options.interactionModelRevision ?? FALLBACK_INTERACTIONMODEL_REVISION,
+    };
+
+    for (const entry of data) {
+        reifyData(entry);
+    }
+
+    if (!writeRequests.length) {
+        throw new MalformedRequestError(`Write action contains no attributes to write`);
+    }
+
+    return result;
+
+    function reifyData(data: Write.Attribute) {
+        const cluster = Specifier.clusterOf(data);
+
+        if (cluster === undefined) {
+            throw new MalformedRequestError(`Write action must specify a cluster`);
+        }
+
+        let { attributes } = data;
+        if (attributes === undefined) {
+            throw new MalformedRequestError(`Write action must specify an attribute`);
+        }
+        if (!Array.isArray(attributes)) {
+            attributes = [attributes];
+        }
+
+        const { endpoint, value, version: dataVersion } = data;
+
+        // Configure base AttributePath
+        const prototype: Omit<AttributeData, "data"> = {
+            path: {
+                endpointId: endpoint !== undefined ? Specifier.endpointIdOf(data) : undefined,
+                clusterId: cluster.id,
+                attributeId: undefined,
+            },
+            dataVersion,
+        };
+
+        for (const specifier of attributes) {
+            const attribute = Specifier.attributeFor(cluster, specifier);
+            writeRequests.push({
+                ...prototype,
+                path: {
+                    ...prototype.path,
+                    attributeId: attribute.id,
+                },
+                data: attribute.schema.encodeTlv(value, { forWriteInteraction: true }),
+            });
+        }
+    }
 }
 
-// TODO - write DSL
+export namespace Write {
+    export interface Options {
+        writes?: AttributeData[];
+        timed?: boolean;
+        timeout?: number;
+        interactionModelRevision?: number;
+    }
+
+    /**
+     * Selects attributes to Write.  Limits fields to legal permutations per the Matter specification.
+     */
+    export type Attribute<C extends Specifier.Cluster = Specifier.Cluster> = (
+        | Attribute.Concrete<C>
+        | Attribute.WildcardEndpoint<C>
+    ) & {
+        kind: "attribute";
+        value: any;
+        version?: number;
+    };
+
+    export function Attribute<const C extends ClusterType>(data: Omit<Attribute<C>, "kind">): Attribute<C> {
+        return {
+            kind: "attribute",
+            ...data,
+        };
+    }
+
+    export namespace Attribute {
+        export interface Concrete<C extends Specifier.Cluster> {
+            endpoint: Specifier.Endpoint;
+            cluster: C;
+            attributes: Specifier.Attribute<Specifier.ClusterFor<C>> | Specifier.Attribute<Specifier.ClusterFor<C>>[];
+        }
+
+        export interface WildcardEndpoint<C extends Specifier.Cluster> {
+            endpoint?: undefined;
+            cluster: C;
+            attributes: Specifier.Attribute<Specifier.ClusterFor<C>> | Specifier.Attribute<Specifier.ClusterFor<C>>[];
+        }
+    }
+}

package/src/action/response/InvokeResult.ts

@@ -6,10 +6,9 @@
 
 import type { Invoke } from "#action/request/Invoke.js";
 import type { CommandData } from "#types";
-import { CancelablePromise } from "@matter/general";
 
 export type InvokeResult<T extends Invoke> = T extends { suppressResponse: true }
-    ? CancelablePromise<void>
+    ? Promise<void>
     : AsyncIterable<InvokeResult.Chunk>;
 
 export namespace InvokeResult {

package/src/action/response/ReadResult.ts

@@ -33,13 +33,7 @@ export interface ReadResult<Chunk = ReadResult.Chunk> extends AsyncIterable<Read
 export namespace ReadResult {
     export type Chunk = Iterable<Report>;
 
-    export type Report =
-        | AttributeValue
-        | GlobalAttributeStatus
-        | ClusterAttributeStatus
-        | EventValue
-        | GlobalEventStatus
-        | ClusterEventStatus;
+    export type Report = AttributeValue | AttributeStatus | EventValue | EventStatus;
 
     export interface ConcreteAttributePath extends AttributePath {
         nodeId?: NodeId;
@@ -56,17 +50,11 @@ export namespace ReadResult {
         tlv: TlvSchema<unknown>;
     }
 
-    export interface GlobalAttributeStatus {
+    export interface AttributeStatus {
         kind: "attr-status";
         path: ConcreteAttributePath;
         status: StatusCode;
-    }
-
-    export interface ClusterAttributeStatus {
-        kind: "attr-cluster-status";
-        path: ConcreteAttributePath;
-        status: number;
-        clusterStatus: number;
+        clusterStatus?: number;
     }
 
     export interface ConcreteEventPath extends EventPath {
@@ -86,15 +74,10 @@ export namespace ReadResult {
         tlv: TlvSchema<unknown>;
     }
 
-    export interface GlobalEventStatus {
+    export interface EventStatus {
         kind: "event-status";
         path: ConcreteEventPath;
         status: Status;
-    }
-
-    export interface ClusterEventStatus {
-        kind: "event-cluster-status";
-        path: ConcreteEventPath;
-        clusterStatus: number;
+        clusterStatus?: number;
     }
 }

package/src/action/response/WriteResult.ts

@@ -4,10 +4,26 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type { Write } from "#action/request/Write.js";
-import type { CancelablePromise } from "#general";
-import type { WriteResponse } from "#types";
+import { Write } from "#action/request/Write.js";
+import type { AttributeId, AttributePath, ClusterId, EndpointNumber, NodeId, StatusCode } from "#types";
 
-export type WriteResult<T extends Write> = CancelablePromise<
-    T extends { suppressResponse: true } ? void : WriteResponse
+export type WriteResult<T extends Write> = Promise<
+    T extends { suppressResponse: true } ? void : WriteResult.AttributeStatus[]
 >;
+
+export namespace WriteResult {
+    export interface ConcreteAttributePath extends AttributePath {
+        nodeId?: NodeId;
+        endpointId: EndpointNumber;
+        clusterId: ClusterId;
+        attributeId: AttributeId;
+        listIndex?: number | null;
+    }
+
+    export interface AttributeStatus {
+        kind: "attr-status";
+        path: ConcreteAttributePath;
+        status: StatusCode;
+        clusterStatus?: number;
+    }
+}

package/src/action/server/AccessControl.ts

@@ -286,7 +286,7 @@ function dataEnforcerFor(schema: Schema): AccessControl {
                     );
                 }
 
-                if (location?.owningFabric && location.owningFabric !== session.fabric) {
+                if (location?.owningFabric !== undefined && location.owningFabric !== session.fabric) {
                     throw new ReadError(
                         location,
                         "Permission denied: Owning/accessing fabric mismatch",
@@ -307,7 +307,7 @@ function dataEnforcerFor(schema: Schema): AccessControl {
                 return false;
             }
 
-            if (location?.owningFabric && location.owningFabric !== session.fabric) {
+            if (location?.owningFabric !== undefined && location.owningFabric !== session.fabric) {
                 return false;
             }
 
@@ -323,7 +323,7 @@ function dataEnforcerFor(schema: Schema): AccessControl {
                 throw new WriteError(location, "Permission denied: No accessing fabric", StatusCode.UnsupportedAccess);
             }
 
-            if (location?.owningFabric && location.owningFabric !== session.fabric) {
+            if (location?.owningFabric !== undefined && location.owningFabric !== session.fabric) {
                 throw new WriteError(location, "Permission denied: Owning/accessing fabric mismatch");
             }
 
@@ -339,7 +339,7 @@ function dataEnforcerFor(schema: Schema): AccessControl {
                 return false;
             }
 
-            if (location?.owningFabric && location.owningFabric !== session.fabric) {
+            if (location?.owningFabric !== undefined && location.owningFabric !== session.fabric) {
                 return false;
             }
 

package/src/action/server/{AttributeResponse.ts → AttributeReadResponse.ts}

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { InteractionSession } from "#action/index.js";
 import { AttributeTypeProtocol, ClusterProtocol, EndpointProtocol, NodeProtocol } from "#action/protocols.js";
 import { Read } from "#action/request/Read.js";
 import { ReadResult } from "#action/response/ReadResult.js";
@@ -24,7 +25,7 @@ import {
 } from "#types";
 import { StatusCode } from "@matter/types";
 
-const logger = Logger.get("AttributeResponse");
+const logger = Logger.get("AttributeReadResponse");
 
 export const GlobalAttrIds = new Set(Object.values(GlobalAttributes({})).map(attr => attr.id));
 
@@ -33,14 +34,14 @@ export const GlobalAttrIds = new Set(Object.values(GlobalAttributes({})).map(att
  *
  * TODO - profile; ensure nested functions are properly JITed and/or inlined
  */
-export class AttributeResponse<
-    SessionT extends AccessControl.Session = AccessControl.Session,
+export class AttributeReadResponse<
+    SessionT extends InteractionSession = InteractionSession,
 > extends DataResponse<SessionT> {
     #versions?: Record<EndpointNumber, Record<ClusterId, number>>;
 
     // Each input AttributePathIB that does not have an error installs a producer.  Producers run after validation and
     // generate actual attribute data
-    #dataProducers?: Array<(this: AttributeResponse) => Iterable<ReadResult.Chunk>>;
+    #dataProducers?: Array<(this: AttributeReadResponse) => Iterable<ReadResult.Chunk>>;
 
     // The initial "chunk" may be a list of errors.  As producers execute it is a set of records associated with the
     // most recently touched endpoint.  When the endpoint changes the previous chunk emits
@@ -124,7 +125,7 @@ export class AttributeResponse<
     get counts() {
         return {
             status: this.#statusCount,
-            value: this.#valueCount,
+            success: this.#valueCount,
             existent: this.#valueCount + this.#filteredCount,
         };
     }
@@ -149,7 +150,7 @@ export class AttributeResponse<
         const wpf = wildcardPathFlags ? WildcardPathFlagsCodec.encode(wildcardPathFlags) : 0;
 
         if (endpointId === undefined) {
-            this.#addProducer(function* (this: AttributeResponse) {
+            this.#addProducer(function* (this: AttributeReadResponse) {
                 this.#wildcardPathFlags = wpf;
                 for (const endpoint of this.node) {
                     yield* this.readEndpointForWildcard(endpoint, path);
@@ -160,7 +161,7 @@ export class AttributeResponse<
 
         const endpoint = this.node[endpointId];
         if (endpoint) {
-            this.#addProducer(function (this: AttributeResponse) {
+            this.#addProducer(function (this: AttributeReadResponse) {
                 this.#wildcardPathFlags = wpf;
                 return this.readEndpointForWildcard(endpoint, path);
             });
@@ -263,12 +264,12 @@ export class AttributeResponse<
                 }
                 this.#currentEndpoint = endpoint;
                 this.#currentCluster = cluster;
-                this.#currentState = cluster.open(this.session);
+                this.#currentState = cluster.readState(this.session);
             } else if (this.#currentCluster !== cluster) {
                 this.#currentCluster = cluster;
-                this.#currentState = cluster.open(this.session);
+                this.#currentState = cluster.readState(this.session);
             } else if (this.#currentState === undefined) {
-                this.#currentState = cluster.open(this.session);
+                this.#currentState = cluster.readState(this.session);
             }
 
             const value = this.#currentState[attributeId];
@@ -386,7 +387,7 @@ export class AttributeResponse<
         }
 
         if (this.#currentState === undefined) {
-            this.#currentState = this.#guardedCurrentCluster.open(this.session);
+            this.#currentState = this.#guardedCurrentCluster.readState(this.session);
         }
         const value = this.#currentState[attribute.id];
         if (value === undefined) {
@@ -411,7 +412,7 @@ export class AttributeResponse<
     /**
      * Add a function that produces data.  These functions are run after validation of input paths.
      */
-    #addProducer(producer: (this: AttributeResponse) => Iterable<ReadResult.Chunk>) {
+    #addProducer(producer: (this: AttributeReadResponse) => Iterable<ReadResult.Chunk>) {
         if (this.#dataProducers) {
             this.#dataProducers.push(producer);
         } else {
@@ -435,7 +436,7 @@ export class AttributeResponse<
             () => `Error reading attribute ${this.node.inspectPath(path)}: Status=${StatusCode[status]}(${status})`,
         );
 
-        const report: ReadResult.GlobalAttributeStatus = {
+        const report: ReadResult.AttributeStatus = {
             kind: "attr-status",
             path,
             status,

package/src/action/server/AttributeSubscriptionResponse.ts

@@ -3,12 +3,12 @@
  * Copyright 2022-2025 Project CHIP Authors
  * SPDX-License-Identifier: Apache-2.0
  */
+import { InteractionSession } from "#action/index.js";
 import { AttributeTypeProtocol, ClusterProtocol, EndpointProtocol, NodeProtocol } from "#action/protocols.js";
 import { ReadResult } from "#action/response/ReadResult.js";
 import { InternalError } from "#general";
 import { AttributeId, AttributePath, ClusterId, EndpointNumber } from "#types";
-import { AccessControl } from "./AccessControl.js";
-import { AttributeResponse } from "./AttributeResponse.js";
+import { AttributeReadResponse } from "./AttributeReadResponse.js";
 
 type ClusterFilter = {
     [clusterId: ClusterId]: Set<AttributeId>;
@@ -18,12 +18,12 @@ export type AttributeResponseFilter = {
 };
 
 /**
- * AttributeSubscriptionResponse is a specialized version of AttributeResponse that processes a read/subscribe request
+ * AttributeSubscriptionResponse is a specialized version of AttributeReadResponse that processes a read/subscribe request
  * with a filter applied to the attributes. Only the attributes that match the filter will be processed.
  */
 export class AttributeSubscriptionResponse<
-    SessionT extends AccessControl.Session = AccessControl.Session,
-> extends AttributeResponse<SessionT> {
+    SessionT extends InteractionSession = InteractionSession,
+> extends AttributeReadResponse<SessionT> {
     #filter: AttributeResponseFilter;
     #currentEndpointFilter?: ClusterFilter;
     #currentClusterFilter?: Set<number>;