/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { Diagnostic, Duration } from "@matter/general"; import { Specification } from "@matter/model"; import { ArraySchema, AttributeData, AttributeId, ClusterId, TlvOfModel, WriteRequest } from "@matter/types"; import { AccessControl } from "@matter/types/clusters/access-control"; import { MalformedRequestError } from "./MalformedRequestError.js"; import { resolvePathForSpecifier, Specifier } from "./Specifier.js"; const AclClusterId = AccessControl.id; const AclAttributeId = AccessControl.attributes.acl.id; const AclExtensionAttributeId = AccessControl.attributes.extension.id; /** * Whether the path is the ACL or Extension attribute of the Access Control cluster, the only lists a WriteRequest may * replace with a non-empty array. * * @see {@link MatterSpecification.v161.Core} § 10.6.4.3.1 */ export function isAclOrExtensionPath(path: { clusterId?: ClusterId; attributeId?: AttributeId }) { const { clusterId, attributeId } = path; return clusterId === AclClusterId && (attributeId === AclAttributeId || attributeId === AclExtensionAttributeId); } export interface Write extends WriteRequest { /** Timeout only relevant for Client Interactions with a required TimedRequest flagging */ timeout?: Duration; } /** * 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 { if (optionsOrData === undefined) { throw new MalformedRequestError(`Write action must have options or data`); } let options; if ("kind" in optionsOrData) { data = [optionsOrData, ...data]; options = {}; } else { options = optionsOrData; } const { writes: writeRequests = [], timed, timeout, chunkLists = true, // Should be true currently to stay in sync with chip sdk, see below suppressResponse, interactionModelRevision = Specification.INTERACTION_MODEL_REVISION, } = options; for (const { path, dataVersion } of writeRequests) { // Spec 1.6 §8.9.2.8.1: DataVersion SHALL NOT accompany a group or wildcard write path. if (dataVersion !== undefined && path.endpointId === undefined) { throw new MalformedRequestError(`Write action with a DataVersion must target a concrete endpoint`); } } let chunked = false; const result = { timedRequest: !!timed || !!timeout, timeout, writeRequests, moreChunkedMessages: false, suppressResponse, interactionModelRevision, [Diagnostic.value]: () => { const items = data.flatMap(entry => { const { version, value, endpoint, cluster, attributes } = entry; const valueString = Diagnostic.json(value); const list = Array.isArray(attributes) ? attributes : [attributes]; const versionString = version !== undefined ? `(version=${version})` : ""; return list.map(attribute => Diagnostic.squash( Diagnostic.strong(resolvePathForSpecifier({ endpoint, cluster, attribute })), ` = ${valueString}${versionString}`, ), ); }); if (chunked) { return [Diagnostic.asFlags({ chunked: true }), Diagnostic.list(items)]; } return Diagnostic.list(items); }, } as Write; 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; // Spec 1.6 §8.9.2.8.1: DataVersion SHALL NOT accompany a group or wildcard write path. if (dataVersion !== undefined && endpoint === undefined) { throw new MalformedRequestError(`Write action with a DataVersion must target a concrete endpoint`); } // Configure base AttributePath const prototype: Omit = { path: { endpointId: endpoint !== undefined ? Specifier.endpointIdOf(data) : undefined, clusterId: cluster.id, attributeId: undefined, }, dataVersion, }; for (const specifier of attributes) { const clusterId = cluster.id; const attribute = Specifier.attributeFor(cluster, specifier); const { id: attributeId } = attribute; const tlv = TlvOfModel(attribute); if ( chunkLists && // As implemented for Matter 1.4.2 in https://github.com/project-chip/connectedhomeip/pull/38263 // Acl writes will no longer be chunked by default, all others still // Will be streamlined later ... see https://github.com/project-chip/connectedhomeip/issues/38270 Array.isArray(value) && tlv instanceof ArraySchema && !isAclOrExtensionPath({ clusterId, attributeId }) ) { chunked = true; writeRequests.push( ...tlv .encodeAsChunkedArray(value, { forWriteInteraction: true }) .map(({ element: data, listIndex }) => ({ path: { ...prototype.path, attributeId: attribute.id, listIndex, }, data, dataVersion, })), ); } else { writeRequests.push({ ...prototype, path: { ...prototype.path, attributeId: attribute.id, }, data: tlv?.encodeTlv(value, { forWriteInteraction: true }), }); } result.timedRequest ||= attribute.schema.effectiveAccess.timed === true; } } } export namespace Write { export interface Options { writes?: AttributeData[]; /** Whether this is sent as a timed request, if no timeout is specified a default is used */ timed?: boolean; /** Timeout when sent as a timed request; a non-zero timeout sets the timed flag automatically */ timeout?: Duration; interactionModelRevision?: number; chunkLists?: boolean; suppressResponse?: boolean; } /** * Selects attributes to Write. Limits fields to legal permutations per the Matter specification. */ export type Attribute = ( | Attribute.Concrete | Attribute.WildcardEndpoint ) & { kind: "attribute"; value: any; version?: number; }; export function Attribute(data: Omit, "kind">): Attribute { return { kind: "attribute", ...data, }; } export namespace Attribute { export interface Concrete { endpoint: Specifier.Endpoint; cluster: C; attributes: Specifier.Attribute> | Specifier.Attribute>[]; } export interface WildcardEndpoint { endpoint?: undefined; cluster: C; attributes: Specifier.Attribute> | Specifier.Attribute>[]; } } }