@matter/protocol 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/interaction/InteractionClient.ts

@@ -0,0 +1,1215 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    ImplementationError,
+    Logger,
+    MatterFlowError,
+    PromiseQueue,
+    Time,
+    Timer,
+    UnexpectedDataError,
+    isDeepEqual,
+} from "#general";
+import { Specification } from "#model";
+import { PeerAddress } from "#peer/PeerAddress.js";
+import { NodeCachedData } from "#peer/PeerSet.js";
+import {
+    Attribute,
+    AttributeId,
+    AttributeJsType,
+    ClusterId,
+    Command,
+    EndpointNumber,
+    Event,
+    EventId,
+    EventNumber,
+    INTERACTION_PROTOCOL_ID,
+    NodeId,
+    RequestType,
+    ResponseType,
+    StatusCode,
+    StatusResponseError,
+    TlvEventFilter,
+    TlvNoResponse,
+    TypeFromSchema,
+    resolveAttributeName,
+    resolveCommandName,
+    resolveEventName,
+} from "#types";
+import { ExchangeProvider } from "../protocol/ExchangeManager.js";
+import { MessageExchange } from "../protocol/MessageExchange.js";
+import { ProtocolHandler } from "../protocol/ProtocolHandler.js";
+import { DecodedAttributeReportValue, normalizeAndDecodeReadAttributeReport } from "./AttributeDataDecoder.js";
+import { DecodedEventData, DecodedEventReportValue, normalizeAndDecodeReadEventReport } from "./EventDataDecoder.js";
+import {
+    DataReport,
+    IncomingInteractionClientMessenger,
+    InteractionClientMessenger,
+    ReadRequest,
+} from "./InteractionMessenger.js";
+import { attributePathToId, clusterPathToId } from "./InteractionServer.js";
+
+const logger = Logger.get("InteractionClient");
+
+const REQUEST_ALL = [{}];
+const DEFAULT_TIMED_REQUEST_TIMEOUT_MS = 10_000; // 10 seconds
+const DEFAULT_MINIMUM_RESPONSE_TIMEOUT_WITH_FAILSAFE_MS = 30_000; // 30 seconds
+
+export interface AttributeStatus {
+    path: {
+        nodeId?: NodeId;
+        endpointId?: EndpointNumber;
+        clusterId?: ClusterId;
+        attributeId?: AttributeId;
+    };
+    status: StatusCode;
+}
+
+export class SubscriptionClient implements ProtocolHandler {
+    private readonly subscriptionListeners = new Map<number, (dataReport: DataReport) => void>();
+    private readonly subscriptionUpdateTimers = new Map<number, Timer>();
+
+    constructor() {}
+
+    getId() {
+        return INTERACTION_PROTOCOL_ID;
+    }
+
+    registerSubscriptionListener(subscriptionId: number, listener: (dataReport: DataReport) => void) {
+        this.subscriptionListeners.set(subscriptionId, listener);
+    }
+
+    removeSubscriptionListener(subscriptionId: number) {
+        this.subscriptionListeners.delete(subscriptionId);
+    }
+
+    registerSubscriptionUpdateTimer(subscriptionId: number, timer: Timer) {
+        this.subscriptionUpdateTimers.set(subscriptionId, timer);
+    }
+
+    removeSubscriptionUpdateTimer(subscriptionId: number) {
+        this.subscriptionUpdateTimers.get(subscriptionId)?.stop();
+        this.subscriptionUpdateTimers.delete(subscriptionId);
+    }
+
+    async onNewExchange(exchange: MessageExchange) {
+        const messenger = new IncomingInteractionClientMessenger(exchange);
+        const dataReport = await messenger.readDataReports(false);
+        const subscriptionId = dataReport.subscriptionId;
+        if (subscriptionId === undefined) {
+            await messenger.sendStatus(StatusCode.InvalidSubscription);
+            throw new UnexpectedDataError("Invalid Data report without Subscription ID");
+        }
+        const listener = this.subscriptionListeners.get(subscriptionId);
+        const timer = this.subscriptionUpdateTimers.get(subscriptionId);
+        if (listener === undefined) {
+            await messenger.sendStatus(StatusCode.InvalidSubscription);
+            logger.info(`Received data for unknown subscription ID ${subscriptionId}. Cancel this subscription.`);
+            if (timer !== undefined) {
+                // Should not happen but let's make sure to clean up
+                this.removeSubscriptionUpdateTimer(subscriptionId);
+            }
+            await messenger.close();
+            return;
+        }
+        await messenger.sendStatus(StatusCode.Success);
+        await messenger.close();
+
+        if (timer !== undefined) {
+            timer.stop().start(); // Restart timer because we received data
+        }
+        listener(dataReport);
+    }
+
+    async close() {
+        this.subscriptionListeners.clear();
+        this.subscriptionUpdateTimers.forEach(timer => timer.stop());
+        this.subscriptionUpdateTimers.clear();
+    }
+}
+
+export class InteractionClient {
+    readonly #cachedData: NodeCachedData = {
+        attributeValues: new Map(),
+        clusterDataVersions: new Map(),
+    };
+    private readonly ownSubscriptionIds = new Set<number>();
+    private readonly subscriptionClient: SubscriptionClient;
+    #queue?: PromiseQueue;
+
+    constructor(
+        private readonly exchangeProvider: ExchangeProvider,
+        readonly address: PeerAddress,
+        queue?: PromiseQueue,
+        cachedData?: NodeCachedData,
+    ) {
+        this.#queue = queue;
+
+        // With externally provided cache, we use this, else we at least have a local cache
+        if (cachedData !== undefined) {
+            this.#cachedData = cachedData;
+        }
+        if (this.exchangeProvider.hasProtocolHandler(INTERACTION_PROTOCOL_ID)) {
+            const client = this.exchangeProvider.getProtocolHandler(INTERACTION_PROTOCOL_ID);
+            if (!(client instanceof SubscriptionClient)) {
+                throw new ImplementationError(
+                    `Already existing protocol handler ${INTERACTION_PROTOCOL_ID} is not a SubscriptionClient.`,
+                );
+            }
+            this.subscriptionClient = client;
+        } else {
+            this.subscriptionClient = new SubscriptionClient();
+            this.exchangeProvider.addProtocolHandler(this.subscriptionClient);
+        }
+    }
+
+    registerSubscriptionListener(subscriptionId: number, listener: (dataReport: DataReport) => void) {
+        this.ownSubscriptionIds.add(subscriptionId);
+        this.subscriptionClient.registerSubscriptionListener(subscriptionId, listener);
+    }
+
+    removeSubscription(subscriptionId: number) {
+        this.ownSubscriptionIds.delete(subscriptionId);
+        this.subscriptionClient.removeSubscriptionListener(subscriptionId);
+        this.subscriptionClient.removeSubscriptionUpdateTimer(subscriptionId);
+    }
+
+    async getAllAttributes(
+        options: {
+            dataVersionFilters?: { endpointId: EndpointNumber; clusterId: ClusterId; dataVersion: number }[];
+            enrichCachedAttributeData?: boolean;
+            isFabricFiltered?: boolean;
+            executeQueued?: boolean;
+        } = {},
+    ): Promise<DecodedAttributeReportValue<any>[]> {
+        return (
+            await this.getMultipleAttributesAndEvents({
+                attributes: REQUEST_ALL,
+                ...options,
+            })
+        ).attributeReports;
+    }
+
+    async getAllEvents(
+        options: {
+            eventFilters?: TypeFromSchema<typeof TlvEventFilter>[];
+            isFabricFiltered?: boolean;
+            executeQueued?: boolean;
+        } = {},
+    ): Promise<DecodedEventReportValue<any>[]> {
+        return (
+            await this.getMultipleAttributesAndEvents({
+                events: REQUEST_ALL,
+                ...options,
+            })
+        ).eventReports;
+    }
+
+    async getAllAttributesAndEvents(
+        options: {
+            dataVersionFilters?: {
+                endpointId: EndpointNumber;
+                clusterId: ClusterId;
+                dataVersion: number;
+            }[];
+            enrichCachedAttributeData?: boolean;
+            eventFilters?: TypeFromSchema<typeof TlvEventFilter>[];
+            isFabricFiltered?: boolean;
+            executeQueued?: boolean;
+        } = {},
+    ): Promise<{
+        attributeReports: DecodedAttributeReportValue<any>[];
+        eventReports: DecodedEventReportValue<any>[];
+    }> {
+        return this.getMultipleAttributesAndEvents({
+            attributes: REQUEST_ALL,
+            events: REQUEST_ALL,
+            ...options,
+        });
+    }
+
+    async getMultipleAttributes(
+        options: {
+            attributes?: { endpointId?: EndpointNumber; clusterId?: ClusterId; attributeId?: AttributeId }[];
+            dataVersionFilters?: { endpointId: EndpointNumber; clusterId: ClusterId; dataVersion: number }[];
+            enrichCachedAttributeData?: boolean;
+            isFabricFiltered?: boolean;
+            executeQueued?: boolean;
+        } = {},
+    ): Promise<DecodedAttributeReportValue<any>[]> {
+        return (await this.getMultipleAttributesAndEvents(options)).attributeReports;
+    }
+
+    async getMultipleEvents(
+        options: {
+            events?: { endpointId?: EndpointNumber; clusterId?: ClusterId; eventId?: EventId }[];
+            eventFilters?: TypeFromSchema<typeof TlvEventFilter>[];
+            isFabricFiltered?: boolean;
+            executeQueued?: boolean;
+        } = {},
+    ): Promise<DecodedEventReportValue<any>[]> {
+        return (await this.getMultipleAttributesAndEvents(options)).eventReports;
+    }
+
+    async getMultipleAttributesAndEvents(
+        options: {
+            attributes?: { endpointId?: EndpointNumber; clusterId?: ClusterId; attributeId?: AttributeId }[];
+            dataVersionFilters?: { endpointId: EndpointNumber; clusterId: ClusterId; dataVersion: number }[];
+            enrichCachedAttributeData?: boolean;
+            events?: { endpointId?: EndpointNumber; clusterId?: ClusterId; eventId?: EventId }[];
+            eventFilters?: TypeFromSchema<typeof TlvEventFilter>[];
+            isFabricFiltered?: boolean;
+            executeQueued?: boolean;
+        } = {},
+    ): Promise<{
+        attributeReports: DecodedAttributeReportValue<any>[];
+        eventReports: DecodedEventReportValue<any>[];
+    }> {
+        const {
+            attributes: attributeRequests,
+            dataVersionFilters,
+            executeQueued,
+            events: eventRequests,
+            enrichCachedAttributeData,
+            eventFilters,
+        } = options;
+        if (attributeRequests === undefined && eventRequests === undefined) {
+            throw new ImplementationError("When reading attributes and events, at least one must be specified.");
+        }
+
+        const readPathsCount = (attributeRequests?.length ?? 0) + (eventRequests?.length ?? 0);
+        if (readPathsCount > 9) {
+            logger.debug(
+                "Read interactions with more then 9 paths might be not allowed by the device. Consider splitting then into several read requests.",
+            );
+        }
+
+        logger.debug(
+            `Sending read request: attributes: ${attributeRequests
+                ?.map(path => resolveAttributeName(path))
+                .join(", ")} and events: ${eventRequests?.map(path => resolveEventName(path)).join(", ")}`,
+        );
+        if (dataVersionFilters !== undefined && dataVersionFilters?.length > 0) {
+            logger.debug(
+                `Using data version filters: ${dataVersionFilters
+                    .map(({ endpointId, clusterId, dataVersion }) => `${endpointId}/${clusterId}=${dataVersion}`)
+                    .join(", ")}`,
+            );
+        }
+        if (eventFilters !== undefined && eventFilters?.length > 0) {
+            logger.debug(
+                `Using event filters: ${eventFilters
+                    .map(({ nodeId, eventMin }) => `${nodeId}=${eventMin}`)
+                    .join(", ")}`,
+            );
+        }
+
+        return this.withMessenger<{
+            attributeReports: DecodedAttributeReportValue<any>[];
+            eventReports: DecodedEventReportValue<any>[];
+        }>(async messenger => {
+            const { isFabricFiltered = true } = options;
+            const result = await this.processReadRequest(messenger, {
+                attributeRequests,
+                dataVersionFilters: dataVersionFilters?.map(({ endpointId, clusterId, dataVersion }) => ({
+                    path: { endpointId, clusterId },
+                    dataVersion,
+                })),
+                eventRequests,
+                eventFilters,
+                isFabricFiltered,
+                interactionModelRevision: Specification.INTERACTION_MODEL_REVISION,
+            });
+
+            if (dataVersionFilters !== undefined && dataVersionFilters.length > 0 && enrichCachedAttributeData) {
+                this.#enrichCachedAttributeData(result.attributeReports, dataVersionFilters);
+            }
+
+            return result;
+        }, executeQueued);
+    }
+
+    async getAttribute<A extends Attribute<any, any>>(options: {
+        endpointId: EndpointNumber;
+        clusterId: ClusterId;
+        attribute: A;
+        isFabricFiltered?: boolean;
+        alwaysRequestFromRemote?: boolean;
+        executeQueued?: boolean;
+    }): Promise<AttributeJsType<A> | undefined> {
+        const { alwaysRequestFromRemote = false } = options;
+        const response = await this.getAttributeWithVersion({
+            ...options,
+            alwaysRequestFromRemote,
+        });
+        return response?.value;
+    }
+
+    async getAttributeWithVersion<A extends Attribute<any, any>>(options: {
+        endpointId: EndpointNumber;
+        clusterId: ClusterId;
+        attribute: A;
+        isFabricFiltered?: boolean;
+        alwaysRequestFromRemote?: boolean;
+        executeQueued?: boolean;
+    }): Promise<{ value: AttributeJsType<A>; version: number } | undefined> {
+        const {
+            endpointId,
+            clusterId,
+            attribute,
+            alwaysRequestFromRemote = false,
+            isFabricFiltered,
+            executeQueued,
+        } = options;
+        const { id: attributeId } = attribute;
+        if (!alwaysRequestFromRemote) {
+            const value = this.#cachedData.attributeValues.get(
+                attributePathToId({ endpointId, clusterId, attributeId }),
+            )?.value;
+            const version = this.#cachedData.clusterDataVersions.get(
+                clusterPathToId({ endpointId, clusterId }),
+            )?.dataVersion;
+            if (value !== undefined && version !== undefined) {
+                return { value, version } as { value: AttributeJsType<A>; version: number };
+            }
+        }
+
+        const { attributeReports } = await this.getMultipleAttributesAndEvents({
+            attributes: [{ endpointId, clusterId, attributeId }],
+            isFabricFiltered,
+            executeQueued,
+        });
+
+        if (attributeReports.length === 0) {
+            return undefined;
+        }
+        if (attributeReports.length > 1) {
+            throw new UnexpectedDataError("Unexpected response with more then one attribute");
+        }
+        return { value: attributeReports[0].value, version: attributeReports[0].version };
+    }
+
+    async getEvent<T, E extends Event<T, any>>(options: {
+        endpointId: EndpointNumber;
+        clusterId: ClusterId;
+        event: E;
+        minimumEventNumber?: EventNumber;
+        isFabricFiltered?: boolean;
+        executeQueued?: boolean;
+    }): Promise<DecodedEventData<T>[] | undefined> {
+        const { endpointId, clusterId, event, minimumEventNumber, isFabricFiltered = true, executeQueued } = options;
+        const { id: eventId } = event;
+        const response = await this.getMultipleAttributesAndEvents({
+            events: [{ endpointId, clusterId, eventId }],
+            eventFilters: minimumEventNumber !== undefined ? [{ eventMin: minimumEventNumber }] : undefined,
+            isFabricFiltered,
+            executeQueued,
+        });
+        return response?.eventReports[0]?.events;
+    }
+
+    private async processReadRequest(
+        messenger: InteractionClientMessenger,
+        request: ReadRequest,
+    ): Promise<{ attributeReports: DecodedAttributeReportValue<any>[]; eventReports: DecodedEventReportValue<any>[] }> {
+        const { attributeRequests, eventRequests } = request;
+        logger.debug(
+            `Sending read request to ${messenger.getExchangeChannelName()} for attributes ${attributeRequests
+                ?.map(path => resolveAttributeName(path))
+                .join(", ")} and events ${eventRequests?.map(path => resolveEventName(path)).join(", ")}`,
+        );
+        // Send read request and combine all (potentially chunked) responses
+        const response = await messenger.sendReadRequest(request);
+
+        // Normalize and decode the response
+        const normalizedResult = {
+            attributeReports: normalizeAndDecodeReadAttributeReport(response.attributeReports ?? []),
+            eventReports: normalizeAndDecodeReadEventReport(response.eventReports ?? []),
+        };
+        logger.debug(
+            `Received read response with attributes ${normalizedResult.attributeReports
+                .map(({ path, value }) => `${resolveAttributeName(path)} = ${Logger.toJSON(value)}`)
+                .join(", ")} and events ${normalizedResult.eventReports
+                .map(({ path, events }) => `${resolveEventName(path)} = ${Logger.toJSON(events)}`)
+                .join(", ")}`,
+        );
+        return normalizedResult;
+    }
+
+    async setAttribute<T>(options: {
+        attributeData: {
+            endpointId: EndpointNumber;
+            clusterId: ClusterId;
+            attribute: Attribute<T, any>;
+            value: T;
+            dataVersion?: number;
+        };
+        asTimedRequest?: boolean;
+        timedRequestTimeoutMs?: number;
+        suppressResponse?: boolean;
+        executeQueued?: boolean;
+    }): Promise<void> {
+        const { attributeData, asTimedRequest, timedRequestTimeoutMs, suppressResponse, executeQueued } = options;
+        const { endpointId, clusterId, attribute, value, dataVersion } = attributeData;
+        const response = await this.setMultipleAttributes({
+            attributes: [{ endpointId, clusterId, attribute, value, dataVersion }],
+            asTimedRequest,
+            timedRequestTimeoutMs,
+            suppressResponse,
+            executeQueued,
+        });
+
+        // Response contains Status error if there was an error on write
+        if (response.length) {
+            const {
+                path: { endpointId, clusterId, attributeId },
+                status,
+            } = response[0];
+            if (status !== undefined && status !== StatusCode.Success) {
+                throw new StatusResponseError(
+                    `Error setting attribute ${endpointId}/${clusterId}/${attributeId}`,
+                    status,
+                );
+            }
+        }
+    }
+
+    async setMultipleAttributes(options: {
+        attributes: {
+            endpointId: EndpointNumber;
+            clusterId: ClusterId;
+            attribute: Attribute<any, any>;
+            value: any;
+            dataVersion?: number;
+        }[];
+        asTimedRequest?: boolean;
+        timedRequestTimeoutMs?: number;
+        suppressResponse?: boolean;
+        executeQueued?: boolean;
+    }): Promise<AttributeStatus[]> {
+        const { executeQueued } = options;
+        return this.withMessenger<AttributeStatus[]>(async messenger => {
+            const {
+                attributes,
+                asTimedRequest,
+                timedRequestTimeoutMs = DEFAULT_TIMED_REQUEST_TIMEOUT_MS,
+                suppressResponse = false, // TODO needs to be TRUE for Group writes
+            } = options;
+            logger.debug(
+                `Sending write request: ${attributes
+                    .map(
+                        ({ endpointId, clusterId, attribute: { id }, value, dataVersion }) =>
+                            `${resolveAttributeName({ endpointId, clusterId, attributeId: id })} = ${Logger.toJSON(
+                                value,
+                            )} (version=${dataVersion})`,
+                    )
+                    .join(", ")}`,
+            );
+            const writeRequests = attributes.map(
+                ({ endpointId, clusterId, attribute: { id, schema }, value, dataVersion }) => ({
+                    path: { endpointId, clusterId, attributeId: id },
+                    data: schema.encodeTlv(value, { forWriteInteraction: true }),
+                    dataVersion,
+                }),
+            );
+            const timedRequest =
+                attributes.some(({ attribute: { timed } }) => timed) ||
+                asTimedRequest === true ||
+                options.timedRequestTimeoutMs !== undefined;
+            if (timedRequest) {
+                await messenger.sendTimedRequest(timedRequestTimeoutMs);
+            }
+            const response = await messenger.sendWriteCommand({
+                suppressResponse,
+                timedRequest,
+                writeRequests,
+                moreChunkedMessages: false,
+                interactionModelRevision: Specification.INTERACTION_MODEL_REVISION,
+            });
+            if (response === undefined) {
+                if (!suppressResponse) {
+                    throw new MatterFlowError(`No response received from write interaction but expected.`);
+                }
+                return [];
+            }
+            return response.writeResponses
+                .flatMap(
+                    ({ status: { status, clusterStatus }, path: { nodeId, endpointId, clusterId, attributeId } }) => {
+                        return {
+                            path: { nodeId, endpointId, clusterId, attributeId },
+                            status: status ?? clusterStatus ?? StatusCode.Failure,
+                        };
+                    },
+                )
+                .filter(({ status }) => status !== StatusCode.Success);
+        }, executeQueued);
+    }
+
+    async subscribeAttribute<A extends Attribute<any, any>>(options: {
+        endpointId: EndpointNumber;
+        clusterId: ClusterId;
+        attribute: A;
+        minIntervalFloorSeconds: number;
+        maxIntervalCeilingSeconds: number;
+        isFabricFiltered?: boolean;
+        knownDataVersion?: number;
+        keepSubscriptions?: boolean;
+        listener?: (value: AttributeJsType<A>, version: number) => void;
+        updateTimeoutHandler?: Timer.Callback;
+        executeQueued?: boolean;
+    }): Promise<void> {
+        const { executeQueued } = options;
+        return this.withMessenger<void>(async messenger => {
+            const {
+                endpointId,
+                clusterId,
+                attribute,
+                minIntervalFloorSeconds,
+                maxIntervalCeilingSeconds,
+                isFabricFiltered = true,
+                listener,
+                knownDataVersion,
+                keepSubscriptions = true,
+                updateTimeoutHandler,
+            } = options;
+            const { id: attributeId } = attribute;
+
+            logger.debug(
+                `Sending subscribe request for attribute: ${resolveAttributeName({
+                    endpointId,
+                    clusterId,
+                    attributeId,
+                })}${knownDataVersion !== undefined ? ` (knownDataVersion=${knownDataVersion})` : ""}`,
+            );
+            const {
+                report,
+                subscribeResponse: { subscriptionId, maxInterval },
+            } = await messenger.sendSubscribeRequest({
+                interactionModelRevision: Specification.INTERACTION_MODEL_REVISION,
+                attributeRequests: [{ endpointId, clusterId, attributeId }],
+                dataVersionFilters:
+                    knownDataVersion !== undefined
+                        ? [{ path: { endpointId, clusterId }, dataVersion: knownDataVersion }]
+                        : undefined,
+                keepSubscriptions,
+                minIntervalFloorSeconds,
+                maxIntervalCeilingSeconds,
+                isFabricFiltered,
+            });
+
+            const subscriptionListener = (dataReport: DataReport) => {
+                if (!Array.isArray(dataReport.attributeReports) || !dataReport.attributeReports.length) {
+                    logger.debug("Subscription result empty");
+                    return;
+                }
+
+                const data = normalizeAndDecodeReadAttributeReport(dataReport.attributeReports);
+
+                if (data.length === 0) {
+                    throw new MatterFlowError("Subscription result reporting undefined/no value not specified");
+                }
+                if (data.length > 1) {
+                    throw new UnexpectedDataError("Unexpected response with more then one attribute");
+                }
+                const {
+                    path: { endpointId, clusterId, attributeId, attributeName },
+                    value,
+                    version,
+                } = data[0];
+                if (value === undefined)
+                    throw new MatterFlowError("Subscription result reporting undefined value not specified.");
+
+                this.#cachedData.attributeValues.set(attributePathToId({ endpointId, clusterId, attributeId }), {
+                    endpointId,
+                    clusterId,
+                    attributeId,
+                    attributeName,
+                    value,
+                });
+                this.#cachedData.clusterDataVersions.set(clusterPathToId({ endpointId, clusterId }), {
+                    endpointId,
+                    clusterId,
+                    dataVersion: version,
+                });
+                listener?.(value, version);
+            };
+            this.registerSubscriptionListener(subscriptionId, subscriptionListener);
+            if (updateTimeoutHandler !== undefined) {
+                this.registerSubscriptionUpdateTimer(messenger, subscriptionId, maxInterval, updateTimeoutHandler);
+            }
+            subscriptionListener(report);
+            return;
+        }, executeQueued);
+    }
+
+    async subscribeEvent<T, E extends Event<T, any>>(options: {
+        endpointId: EndpointNumber;
+        clusterId: ClusterId;
+        event: E;
+        minIntervalFloorSeconds: number;
+        maxIntervalCeilingSeconds: number;
+        isUrgent?: boolean;
+        minimumEventNumber?: EventNumber;
+        isFabricFiltered?: boolean;
+        listener?: (value: DecodedEventData<T>) => void;
+        updateTimeoutHandler?: Timer.Callback;
+        executeQueued?: boolean;
+    }): Promise<void> {
+        const { executeQueued } = options;
+        return this.withMessenger<void>(async messenger => {
+            const {
+                endpointId,
+                clusterId,
+                event,
+                minIntervalFloorSeconds,
+                maxIntervalCeilingSeconds,
+                isUrgent,
+                minimumEventNumber,
+                isFabricFiltered = true,
+                listener,
+                updateTimeoutHandler,
+            } = options;
+            const { id: eventId } = event;
+            logger.debug(
+                `Sending subscribe request for event: ${resolveEventName({ endpointId, clusterId, eventId })}`,
+            );
+            const {
+                report,
+                subscribeResponse: { subscriptionId, maxInterval },
+            } = await messenger.sendSubscribeRequest({
+                interactionModelRevision: Specification.INTERACTION_MODEL_REVISION,
+                eventRequests: [{ endpointId, clusterId, eventId, isUrgent }],
+                eventFilters: minimumEventNumber !== undefined ? [{ eventMin: minimumEventNumber }] : undefined,
+                keepSubscriptions: true,
+                minIntervalFloorSeconds,
+                maxIntervalCeilingSeconds,
+                isFabricFiltered,
+            });
+
+            const subscriptionListener = (dataReport: DataReport) => {
+                if (!Array.isArray(dataReport.eventReports) || !dataReport.eventReports.length) {
+                    logger.debug("Subscription result empty");
+                    return;
+                }
+
+                const data = normalizeAndDecodeReadEventReport(dataReport.eventReports);
+
+                if (data.length === 0) {
+                    throw new MatterFlowError("Received empty subscription result value.");
+                }
+                if (data.length > 1) {
+                    throw new UnexpectedDataError("Unexpected response with more then one attribute.");
+                }
+                const { events } = data[0];
+                if (events === undefined)
+                    throw new MatterFlowError("Subscription result reporting undefined value not specified.");
+
+                events.forEach(event => listener?.(event));
+            };
+            this.registerSubscriptionListener(subscriptionId, subscriptionListener);
+            if (updateTimeoutHandler !== undefined) {
+                this.registerSubscriptionUpdateTimer(messenger, subscriptionId, maxInterval, updateTimeoutHandler);
+            }
+            subscriptionListener(report);
+            return;
+        }, executeQueued);
+    }
+
+    async subscribeAllAttributesAndEvents(options: {
+        minIntervalFloorSeconds: number;
+        maxIntervalCeilingSeconds: number;
+        attributeListener?: (
+            data: DecodedAttributeReportValue<any>,
+            valueChanged?: boolean,
+            oldValue?: unknown,
+        ) => void;
+        eventListener?: (data: DecodedEventReportValue<any>) => void;
+        isUrgent?: boolean;
+        keepSubscriptions?: boolean;
+        isFabricFiltered?: boolean;
+        eventFilters?: TypeFromSchema<typeof TlvEventFilter>[];
+        dataVersionFilters?: { endpointId: EndpointNumber; clusterId: ClusterId; dataVersion: number }[];
+        enrichCachedAttributeData?: boolean;
+        updateTimeoutHandler?: Timer.Callback;
+        executeQueued?: boolean;
+    }): Promise<{
+        attributeReports?: DecodedAttributeReportValue<any>[];
+        eventReports?: DecodedEventReportValue<any>[];
+    }> {
+        const { isUrgent } = options;
+        return this.subscribeMultipleAttributesAndEvents({
+            ...options,
+            attributes: REQUEST_ALL,
+            events: [{ isUrgent }],
+        });
+    }
+
+    async subscribeMultipleAttributesAndEvents(options: {
+        attributes: { endpointId?: EndpointNumber; clusterId?: ClusterId; attributeId?: AttributeId }[];
+        events: { endpointId?: EndpointNumber; clusterId?: ClusterId; eventId?: EventId; isUrgent?: boolean }[];
+        minIntervalFloorSeconds: number;
+        maxIntervalCeilingSeconds: number;
+        keepSubscriptions?: boolean;
+        isFabricFiltered?: boolean;
+        attributeListener?: (data: DecodedAttributeReportValue<any>, valueChanged?: boolean, oldValue?: any) => void;
+        eventListener?: (data: DecodedEventReportValue<any>) => void;
+        eventFilters?: TypeFromSchema<typeof TlvEventFilter>[];
+        dataVersionFilters?: { endpointId: EndpointNumber; clusterId: ClusterId; dataVersion: number }[];
+        enrichCachedAttributeData?: boolean;
+        updateTimeoutHandler?: Timer.Callback;
+        executeQueued?: boolean;
+    }): Promise<{
+        attributeReports?: DecodedAttributeReportValue<any>[];
+        eventReports?: DecodedEventReportValue<any>[];
+    }> {
+        const { attributes: attributeRequests, events: eventRequests, executeQueued } = options;
+
+        const subscriptionPathsCount = (attributeRequests?.length ?? 0) + (eventRequests?.length ?? 0);
+        if (subscriptionPathsCount > 3) {
+            logger.debug("Subscribe interactions with more then 3 paths might be not allowed by the device.");
+        }
+
+        return this.withMessenger<{
+            attributeReports?: DecodedAttributeReportValue<any>[];
+            eventReports?: DecodedEventReportValue<any>[];
+        }>(async messenger => {
+            const {
+                minIntervalFloorSeconds,
+                maxIntervalCeilingSeconds,
+                keepSubscriptions = true,
+                isFabricFiltered = true,
+                attributeListener,
+                eventListener,
+                eventFilters,
+                dataVersionFilters,
+                updateTimeoutHandler,
+                enrichCachedAttributeData,
+            } = options;
+
+            logger.debug(
+                `Sending subscribe request: attributes: ${attributeRequests
+                    .map(path => resolveAttributeName(path))
+                    .join(", ")} and events: ${eventRequests.map(path => resolveEventName(path)).join(", ")}`,
+            );
+            if (dataVersionFilters !== undefined && dataVersionFilters?.length > 0) {
+                logger.debug(
+                    `Using data version filters: ${dataVersionFilters
+                        .map(({ endpointId, clusterId, dataVersion }) => `${endpointId}/${clusterId}=${dataVersion}`)
+                        .join(", ")}`,
+                );
+            }
+            if (eventFilters !== undefined && eventFilters?.length > 0) {
+                logger.debug(
+                    `Using event filters: ${eventFilters
+                        .map(({ nodeId, eventMin }) => `${nodeId}=${eventMin}`)
+                        .join(", ")}`,
+                );
+            }
+            const {
+                report,
+                subscribeResponse: { subscriptionId, maxInterval },
+            } = await messenger.sendSubscribeRequest({
+                interactionModelRevision: Specification.INTERACTION_MODEL_REVISION,
+                attributeRequests,
+                eventRequests,
+                keepSubscriptions,
+                minIntervalFloorSeconds,
+                maxIntervalCeilingSeconds,
+                isFabricFiltered,
+                eventFilters,
+                dataVersionFilters: dataVersionFilters?.map(({ endpointId, clusterId, dataVersion }) => ({
+                    path: { endpointId, clusterId },
+                    dataVersion,
+                })),
+            });
+            logger.info(
+                `Subscription successfully initialized with ID ${subscriptionId} and maxInterval ${maxInterval}s.`,
+            );
+
+            const subscriptionListener = (dataReport: {
+                attributeReports?: DecodedAttributeReportValue<any>[];
+                eventReports?: DecodedEventReportValue<any>[];
+            }) => {
+                if (
+                    (!Array.isArray(dataReport.attributeReports) || !dataReport.attributeReports.length) &&
+                    (!Array.isArray(dataReport.eventReports) || !dataReport.eventReports.length)
+                ) {
+                    logger.debug("Subscription result empty");
+                    return;
+                }
+                const { attributeReports, eventReports } = dataReport;
+
+                if (attributeReports !== undefined) {
+                    attributeReports.forEach(data => {
+                        const {
+                            path: { endpointId, clusterId, attributeId, attributeName },
+                            value,
+                            version,
+                        } = data;
+                        logger.debug(
+                            `Received attribute update: ${resolveAttributeName({
+                                endpointId,
+                                clusterId,
+                                attributeId,
+                            })} = ${Logger.toJSON(value)} (version=${version})`,
+                        );
+                        if (value === undefined) throw new MatterFlowError("Received empty subscription result value.");
+                        const attributeKey = attributePathToId({ endpointId, clusterId, attributeId });
+                        const oldValue = this.#cachedData.attributeValues.get(attributeKey)?.value;
+                        this.#cachedData.attributeValues.set(attributeKey, {
+                            endpointId,
+                            clusterId,
+                            attributeId,
+                            attributeName,
+                            value,
+                        });
+                        this.#cachedData.clusterDataVersions.set(clusterPathToId({ endpointId, clusterId }), {
+                            endpointId,
+                            clusterId,
+                            dataVersion: version,
+                        });
+                        attributeListener?.(
+                            data,
+                            oldValue !== undefined ? !isDeepEqual(oldValue, value) : undefined,
+                            oldValue,
+                        );
+                    });
+                }
+
+                if (eventReports !== undefined) {
+                    eventReports.forEach(data => {
+                        logger.debug(
+                            `Received event update: ${resolveEventName(data.path)}: ${Logger.toJSON(data.events)}`,
+                        );
+                        const { events } = data;
+
+                        this.#cachedData.maxEventNumber =
+                            events.length === 1
+                                ? events[0].eventNumber
+                                : events.reduce(
+                                      (max, { eventNumber }) => (max < eventNumber ? eventNumber : max),
+                                      this.#cachedData.maxEventNumber ?? events[0].eventNumber,
+                                  );
+                        eventListener?.(data);
+                    });
+                }
+            };
+            this.registerSubscriptionListener(subscriptionId, dataReport => {
+                subscriptionListener({
+                    attributeReports:
+                        dataReport.attributeReports !== undefined
+                            ? normalizeAndDecodeReadAttributeReport(dataReport.attributeReports)
+                            : undefined,
+                    eventReports:
+                        dataReport.eventReports !== undefined
+                            ? normalizeAndDecodeReadEventReport(dataReport.eventReports)
+                            : undefined,
+                });
+            });
+
+            if (updateTimeoutHandler !== undefined) {
+                this.registerSubscriptionUpdateTimer(messenger, subscriptionId, maxInterval, updateTimeoutHandler);
+            }
+
+            const seedReport = {
+                attributeReports:
+                    report.attributeReports !== undefined
+                        ? normalizeAndDecodeReadAttributeReport(report.attributeReports)
+                        : undefined,
+                eventReports:
+                    report.eventReports !== undefined
+                        ? normalizeAndDecodeReadEventReport(report.eventReports)
+                        : undefined,
+            };
+            subscriptionListener(seedReport);
+
+            if (dataVersionFilters !== undefined && dataVersionFilters.length > 0 && enrichCachedAttributeData) {
+                this.#enrichCachedAttributeData(seedReport.attributeReports ?? [], dataVersionFilters);
+            }
+
+            return seedReport;
+        }, executeQueued);
+    }
+
+    async invoke<C extends Command<any, any, any>>(options: {
+        endpointId: EndpointNumber;
+        clusterId: ClusterId;
+        request: RequestType<C>;
+        command: C;
+        asTimedRequest?: boolean;
+        timedRequestTimeoutMs?: number;
+        useExtendedFailSafeMessageResponseTimeout?: boolean;
+        executeQueued?: boolean;
+    }): Promise<ResponseType<C>> {
+        const { executeQueued } = options;
+
+        return this.withMessenger<ResponseType<C>>(async messenger => {
+            const {
+                endpointId,
+                clusterId,
+                request,
+                command: { requestId, requestSchema, responseId, responseSchema, optional, timed },
+                asTimedRequest,
+                timedRequestTimeoutMs = DEFAULT_TIMED_REQUEST_TIMEOUT_MS,
+                useExtendedFailSafeMessageResponseTimeout = false,
+            } = options;
+            const timedRequest = timed || asTimedRequest === true || options.timedRequestTimeoutMs !== undefined;
+
+            logger.debug(
+                `Invoking command: ${resolveCommandName({
+                    endpointId,
+                    clusterId,
+                    commandId: requestId,
+                })} with ${Logger.toJSON(request)}`,
+            );
+
+            requestSchema.validate(request);
+
+            const commandFields = requestSchema.encodeTlv(request);
+
+            if (timedRequest) {
+                await messenger.sendTimedRequest(timedRequestTimeoutMs);
+            }
+
+            const invokeResponse = await messenger.sendInvokeCommand(
+                {
+                    invokeRequests: [{ commandPath: { endpointId, clusterId, commandId: requestId }, commandFields }],
+                    timedRequest,
+                    suppressResponse: false,
+                    interactionModelRevision: Specification.INTERACTION_MODEL_REVISION,
+                },
+                useExtendedFailSafeMessageResponseTimeout
+                    ? DEFAULT_MINIMUM_RESPONSE_TIMEOUT_WITH_FAILSAFE_MS
+                    : undefined,
+            );
+            if (invokeResponse === undefined) {
+                throw new MatterFlowError("No response received from invoke interaction but expected.");
+            }
+            const { invokeResponses } = invokeResponse;
+            if (invokeResponses.length === 0) {
+                throw new MatterFlowError("Received invoke response with no invoke results.");
+            }
+            const { command, status } = invokeResponses[0];
+            if (status !== undefined) {
+                const resultCode = status.status.status;
+                if (resultCode !== StatusCode.Success)
+                    throw new StatusResponseError(
+                        `Received non-success result: ${resultCode}`,
+                        resultCode ?? StatusCode.Failure,
+                        status.status.clusterStatus,
+                    );
+                if ((responseSchema as any) !== TlvNoResponse)
+                    throw new MatterFlowError("A response was expected for this command.");
+                return undefined as unknown as ResponseType<C>; // ResponseType is void, force casting the empty result
+            }
+            if (command !== undefined) {
+                const {
+                    commandPath: { commandId },
+                    commandFields,
+                } = command;
+                if (commandId !== responseId) {
+                    throw new MatterFlowError(
+                        `Received invoke response with unexpected command ID ${commandId}, expected ${responseId}.`,
+                    );
+                }
+                if (commandFields === undefined) {
+                    if ((responseSchema as any) !== TlvNoResponse)
+                        throw new MatterFlowError(`A response was expected for command ${requestId}.`);
+                    return undefined as unknown as ResponseType<C>; // ResponseType is void, force casting the empty result
+                }
+                const response = responseSchema.decodeTlv(commandFields);
+                logger.debug(
+                    `Received invoke response: ${resolveCommandName({
+                        endpointId,
+                        clusterId,
+                        commandId: requestId,
+                    })} with ${Logger.toJSON(response)})}`,
+                );
+                return response;
+            }
+            if (optional) {
+                return undefined as ResponseType<C>; // ResponseType allows undefined for optional commands
+            }
+            throw new MatterFlowError("Received invoke response with no result nor response.");
+        }, executeQueued);
+    }
+
+    // TODO Add to ClusterClient when needed/when Group communication is implemented
+    async invokeWithSuppressedResponse<C extends Command<any, any, any>>(options: {
+        endpointId: EndpointNumber;
+        clusterId: ClusterId;
+        request: RequestType<C>;
+        command: C;
+        asTimedRequest?: boolean;
+        timedRequestTimeoutMs?: number;
+        executeQueued?: boolean;
+    }): Promise<void> {
+        const { executeQueued } = options;
+
+        return this.withMessenger<void>(async messenger => {
+            const {
+                endpointId,
+                clusterId,
+                request,
+                command: { requestId, requestSchema, timed },
+                asTimedRequest,
+                timedRequestTimeoutMs = DEFAULT_TIMED_REQUEST_TIMEOUT_MS,
+            } = options;
+            const timedRequest = timed || asTimedRequest === true || options.timedRequestTimeoutMs !== undefined;
+            logger.debug(
+                `Invoking command with suppressedResponse: ${resolveCommandName({
+                    endpointId,
+                    clusterId,
+                    commandId: requestId,
+                })} with ${Logger.toJSON(request)}`,
+            );
+            const commandFields = requestSchema.encodeTlv(request);
+
+            if (timedRequest) {
+                await messenger.sendTimedRequest(timedRequestTimeoutMs);
+            }
+
+            const invokeResponse = await messenger.sendInvokeCommand({
+                invokeRequests: [{ commandPath: { endpointId, clusterId, commandId: requestId }, commandFields }],
+                timedRequest,
+                suppressResponse: true,
+                interactionModelRevision: Specification.INTERACTION_MODEL_REVISION,
+            });
+            if (invokeResponse !== undefined) {
+                throw new MatterFlowError(
+                    "Response received from invoke interaction but none expected because response is suppressed.",
+                );
+            }
+
+            logger.debug(
+                `Invoke successful: ${resolveCommandName({
+                    endpointId,
+                    clusterId,
+                    commandId: requestId,
+                })}`,
+            );
+        }, executeQueued);
+    }
+
+    private async withMessenger<T>(
+        invoke: (messenger: InteractionClientMessenger) => Promise<T>,
+        executeQueued = false,
+    ): Promise<T> {
+        const messenger = new InteractionClientMessenger(this.exchangeProvider);
+        try {
+            if (executeQueued) {
+                if (this.#queue === undefined) {
+                    throw new ImplementationError("Cannot execute queued operation without a queue.");
+                }
+                return await this.#queue.add(() => invoke(messenger));
+            }
+            return await invoke(messenger);
+        } finally {
+            await messenger.close();
+        }
+    }
+
+    private registerSubscriptionUpdateTimer(
+        messenger: InteractionClientMessenger,
+        subscriptionId: number,
+        maxIntervalS: number,
+        updateTimeoutHandler: Timer.Callback,
+    ) {
+        if (!this.ownSubscriptionIds.has(subscriptionId)) {
+            throw new MatterFlowError(
+                `Cannot register update timer for subscription ${subscriptionId} because it is not owned by this client.`,
+            );
+        }
+        const maxIntervalMs = maxIntervalS * 1000 + messenger.calculateMaximumPeerResponseTime();
+
+        const timer = Time.getTimer("Subscription retry", maxIntervalMs, () => {
+            logger.info(`Subscription ${subscriptionId} timed out after ${maxIntervalMs}ms ...`);
+            this.removeSubscription(subscriptionId);
+            updateTimeoutHandler();
+        }).start();
+        this.subscriptionClient.registerSubscriptionUpdateTimer(subscriptionId, timer);
+    }
+
+    close() {
+        for (const subscriptionId of this.ownSubscriptionIds) {
+            this.removeSubscription(subscriptionId);
+        }
+        this.#cachedData.attributeValues.clear();
+        this.#cachedData.clusterDataVersions.clear();
+    }
+
+    get session() {
+        return this.exchangeProvider.session;
+    }
+
+    get channelType() {
+        return this.exchangeProvider.channelType;
+    }
+
+    /** Enrich cached data to get complete responses when data version filters were used. */
+    #enrichCachedAttributeData(
+        attributeReports: DecodedAttributeReportValue<any>[],
+        dataVersionFilters: { endpointId: EndpointNumber; clusterId: ClusterId; dataVersion: number }[],
+    ) {
+        // Collect the Endpoints and clusters to potentially enrich data from the cache
+        const candidates = new Map<EndpointNumber, Map<ClusterId, number>>();
+        dataVersionFilters.forEach(({ endpointId, clusterId, dataVersion }) => {
+            if (!candidates.has(endpointId)) {
+                candidates.set(endpointId, new Map());
+            }
+            candidates
+                .get(endpointId)
+                ?.set(
+                    clusterId,
+                    this.#cachedData.clusterDataVersions.get(clusterPathToId({ endpointId, clusterId }))?.dataVersion ??
+                        dataVersion,
+                );
+        });
+
+        // Remove all where data were returned because there the versions did not match
+        attributeReports.forEach(({ path: { endpointId, clusterId } }) => {
+            if (candidates.has(endpointId)) {
+                candidates.get(endpointId)?.delete(clusterId);
+            }
+        });
+
+        // Enrich the data from the cache for all Endpoints and clusters that are left
+        this.#cachedData.attributeValues.forEach(({ endpointId, clusterId, attributeId, attributeName, value }) => {
+            const version = candidates.get(endpointId)?.get(clusterId);
+            if (version !== undefined) {
+                logger.debug(`Enriching cached data for ${endpointId}/${clusterId}/${attributeId}=`, value);
+                attributeReports.push({
+                    path: { endpointId, clusterId, attributeId, attributeName },
+                    value,
+                    version,
+                });
+            }
+        });
+    }
+
+    /**
+     * Returns the list (optionally filtered by endpointId and/or clusterId) of the dataVersions of the currently cached
+     * values to use them as knownDataVersion for read or subscription requests.
+     */
+    getCachedClusterDataVersions(filter?: {
+        endpointId?: EndpointNumber;
+        clusterId?: ClusterId;
+    }): { endpointId: EndpointNumber; clusterId: ClusterId; dataVersion: number }[] {
+        const { endpointId: filterEndpointId, clusterId: filterClusterId } = filter ?? {};
+        return [...this.#cachedData.clusterDataVersions.values()]
+            .filter(
+                ({ endpointId, clusterId }) =>
+                    (filterEndpointId === undefined || filterEndpointId === endpointId) &&
+                    (filterClusterId === undefined || filterClusterId === clusterId),
+            )
+            .map(({ endpointId, clusterId, dataVersion }) => ({ endpointId, clusterId, dataVersion }));
+    }
+
+    get maxKnownEventNumber() {
+        return this.#cachedData.maxEventNumber;
+    }
+}