@matter/protocol 0.13.0-alpha.0-20250318-c1aa38b08 → 0.13.0-alpha.0-20250323-770919c6a

package/src/interaction/InteractionClient.ts

@@ -5,6 +5,7 @@
  */
 
 import {
+    Diagnostic,
     Environment,
     Environmental,
     ImplementationError,
@@ -31,7 +32,9 @@ import {
     Event,
     EventId,
     EventNumber,
+    FabricIndex,
     NodeId,
+    ObjectSchema,
     RequestType,
     ResponseType,
     StatusCode,
@@ -46,10 +49,11 @@ import {
     resolveCommandName,
     resolveEventName,
 } from "#types";
+import { MessageChannel } from "../protocol/ExchangeManager.js";
 import { ExchangeProvider, ReconnectableExchangeProvider } from "../protocol/ExchangeProvider.js";
-import { DecodedAttributeReportValue } from "./AttributeDataDecoder.js";
+import { DecodedAttributeReportStatus, DecodedAttributeReportValue } from "./AttributeDataDecoder.js";
 import { DecodedDataReport } from "./DecodedDataReport.js";
-import { DecodedEventData, DecodedEventReportValue } from "./EventDataDecoder.js";
+import { DecodedEventData, DecodedEventReportStatus, DecodedEventReportValue } from "./EventDataDecoder.js";
 import { DataReport, InteractionClientMessenger, ReadRequest } from "./InteractionMessenger.js";
 import { RegisteredSubscription, SubscriptionClient } from "./SubscriptionClient.js";
 
@@ -103,6 +107,17 @@ export class InteractionClientProvider {
         return this.getInteractionClient(address, discoveryOptions);
     }
 
+    async getInteractionClientForChannel(channel: MessageChannel): Promise<InteractionClient> {
+        const exchangeProvider = await this.#peers.exchangeProviderFor(channel);
+
+        return new InteractionClient(
+            exchangeProvider,
+            this.#peers.subscriptionClient,
+            undefined,
+            this.#peers.interactionQueue,
+        );
+    }
+
     async getInteractionClient(address: PeerAddress, discoveryOptions: DiscoveryOptions) {
         let client = this.#clients.get(address);
         if (client !== undefined) {
@@ -141,11 +156,12 @@ export class InteractionClient {
     readonly #ownSubscriptionIds = new Set<number>();
     readonly #subscriptionClient: SubscriptionClient;
     readonly #queue?: PromiseQueue;
+    readonly #address?: PeerAddress;
 
     constructor(
         exchangeProvider: ExchangeProvider,
         subscriptionClient: SubscriptionClient,
-        readonly address: PeerAddress,
+        address?: PeerAddress,
         queue?: PromiseQueue,
         nodeStore?: PeerDataStore,
     ) {
@@ -153,6 +169,18 @@ export class InteractionClient {
         this.#nodeStore = nodeStore;
         this.#subscriptionClient = subscriptionClient;
         this.#queue = queue;
+        this.#address = address;
+    }
+
+    get address() {
+        if (this.#address === undefined) {
+            throw new ImplementationError("This InteractionClient is not bound to a specific peer.");
+        }
+        return this.#address;
+    }
+
+    get isReconnectable() {
+        return this.#exchangeProvider instanceof ReconnectableExchangeProvider;
     }
 
     get channelUpdated() {
@@ -233,6 +261,22 @@ export class InteractionClient {
         return (await this.getMultipleAttributesAndEvents(options)).attributeReports;
     }
 
+    async getMultipleAttributesAndStatus(
+        options: {
+            attributes?: { endpointId?: EndpointNumber; clusterId?: ClusterId; attributeId?: AttributeId }[];
+            dataVersionFilters?: { endpointId: EndpointNumber; clusterId: ClusterId; dataVersion: number }[];
+            enrichCachedAttributeData?: boolean;
+            isFabricFiltered?: boolean;
+            executeQueued?: boolean;
+        } = {},
+    ): Promise<{
+        attributeData: DecodedAttributeReportValue<any>[];
+        attributeStatus?: DecodedAttributeReportStatus[];
+    }> {
+        const { attributeReports, attributeStatus } = await this.getMultipleAttributesAndEvents(options);
+        return { attributeData: attributeReports, attributeStatus };
+    }
+
     async getMultipleEvents(
         options: {
             events?: { endpointId?: EndpointNumber; clusterId?: ClusterId; eventId?: EventId }[];
@@ -244,6 +288,18 @@ export class InteractionClient {
         return (await this.getMultipleAttributesAndEvents(options)).eventReports;
     }
 
+    async getMultipleEventsAndStatus(
+        options: {
+            events?: { endpointId?: EndpointNumber; clusterId?: ClusterId; eventId?: EventId }[];
+            eventFilters?: TypeFromSchema<typeof TlvEventFilter>[];
+            isFabricFiltered?: boolean;
+            executeQueued?: boolean;
+        } = {},
+    ): Promise<{ eventData: DecodedEventReportValue<any>[]; eventStatus?: DecodedEventReportStatus[] }> {
+        const { eventReports, eventStatus } = await this.getMultipleAttributesAndEvents(options);
+        return { eventData: eventReports, eventStatus };
+    }
+
     async getMultipleAttributesAndEvents(
         options: {
             attributes?: { endpointId?: EndpointNumber; clusterId?: ClusterId; attributeId?: AttributeId }[];
@@ -405,12 +461,23 @@ export class InteractionClient {
 
         // Normalize and decode the response
         const normalizedResult = DecodedDataReport(response);
+        const { attributeReports, attributeStatus, eventReports, eventStatus } = normalizedResult;
+
+        const logData = Array<string>();
+        if (attributeReports.length > 0) {
+            logData.push(`attributes ${attributeReports.map(({ path }) => resolveAttributeName(path)).join(", ")}`);
+        }
+        if (eventReports.length > 0) {
+            logData.push(`events ${eventReports.map(({ path }) => resolveEventName(path)).join(", ")}`);
+        }
+        if (attributeStatus !== undefined && attributeStatus.length > 0) {
+            logData.push(`attributeErrors ${attributeStatus.map(({ path }) => resolveAttributeName(path)).join(", ")}`);
+        }
+        if (eventStatus !== undefined && eventStatus.length > 0) {
+            logData.push(`eventErrors ${eventStatus.map(({ path }) => resolveEventName(path)).join(", ")}`);
+        }
         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(", ")}`,
+            logData.length ? `Received read response with ${logData.join(", ")}` : "Received empty read response",
         );
         return normalizedResult;
     }
@@ -483,7 +550,7 @@ export class InteractionClient {
             `Sending write request: ${attributes
                 .map(
                     ({ endpointId, clusterId, attribute: { id }, value, dataVersion }) =>
-                        `${resolveAttributeName({ endpointId, clusterId, attributeId: id })} = ${Logger.toJSON(
+                        `${resolveAttributeName({ endpointId, clusterId, attributeId: id })} = ${Diagnostic.json(
                             value,
                         )} (version=${dataVersion})`,
                 )
@@ -893,11 +960,11 @@ export class InteractionClient {
             eventReports?: DecodedEventReportValue<any>[];
             subscriptionId?: number;
         }) => {
-            updateReceived?.();
             if (
                 (!Array.isArray(dataReport.attributeReports) || !dataReport.attributeReports.length) &&
                 (!Array.isArray(dataReport.eventReports) || !dataReport.eventReports.length)
             ) {
+                updateReceived?.();
                 return;
             }
             const { attributeReports, eventReports } = dataReport;
@@ -907,7 +974,7 @@ export class InteractionClient {
                 let maxEventNumber = this.#nodeStore?.maxEventNumber ?? eventReports[0].events[0].eventNumber;
                 eventReports.forEach(data => {
                     logger.debug(
-                        `Received event update: ${resolveEventName(data.path)}: ${Logger.toJSON(data.events)}`,
+                        `Received event update: ${resolveEventName(data.path)}: ${Diagnostic.json(data.events)}`,
                     );
                     const { events } = data;
 
@@ -935,7 +1002,7 @@ export class InteractionClient {
                             endpointId,
                             clusterId,
                             attributeId,
-                        })} = ${Logger.toJSON(value)} (version=${version})`,
+                        })} = ${Diagnostic.json(value)} (version=${version})`,
                     );
                     if (value === undefined) throw new MatterFlowError("Received empty subscription result value.");
                     const { value: oldValue } =
@@ -948,6 +1015,7 @@ export class InteractionClient {
                     attributeListener?.(data, changed, oldValue);
                 }
             }
+            updateReceived?.();
         };
 
         const seedReport = DecodedDataReport(report);
@@ -977,33 +1045,59 @@ export class InteractionClient {
         clusterId: ClusterId;
         request: RequestType<C>;
         command: C;
+
+        /** Send as timed request. If no timedRequestTimeoutMs is provided the default of 10s will be used. */
         asTimedRequest?: boolean;
+
+        /** Use this timeout and send the request as Timed Request. If this is specified the above parameter is implied. */
         timedRequestTimeoutMs?: number;
+
+        /** Use an extended Message Response Timeout as defined for FailSafe cases which is 30s. */
         useExtendedFailSafeMessageResponseTimeout?: boolean;
+
+        /** Execute this request queued - mainly used to execute invokes sequentially for thread devices. */
         executeQueued?: boolean;
+
+        /** Skip request data validation. Use this only when you know that your data is correct and validation would return an error. */
+        skipValidation?: boolean;
     }): Promise<ResponseType<C>> {
         const { executeQueued } = options;
 
         const {
             endpointId,
             clusterId,
-            request,
             command: { requestId, requestSchema, responseId, responseSchema, optional, timed },
             asTimedRequest,
             timedRequestTimeoutMs = DEFAULT_TIMED_REQUEST_TIMEOUT_MS,
             useExtendedFailSafeMessageResponseTimeout = false,
+            skipValidation,
         } = options;
-        const timedRequest = timed || asTimedRequest === true || options.timedRequestTimeoutMs !== undefined;
+        let { request } = options;
+        const timedRequest =
+            (timed && !skipValidation) || asTimedRequest === true || options.timedRequestTimeoutMs !== undefined;
+
+        if (requestSchema instanceof ObjectSchema) {
+            if (request === undefined) {
+                // If developer did not provide a request object, create an empty one if it needs to be an object
+                // This can happen when all object properties are optional
+                request = {} as RequestType<C>;
+            }
+            if (requestSchema.isFabricScoped && request.fabricIndex === undefined) {
+                request.fabricIndex = FabricIndex.NO_FABRIC;
+            }
+        }
 
         logger.debug(
             `Invoking command: ${resolveCommandName({
                 endpointId,
                 clusterId,
                 commandId: requestId,
-            })} with ${Logger.toJSON(request)}`,
+            })} with ${Diagnostic.json(request)}`,
         );
 
-        requestSchema.validate(request);
+        if (!skipValidation) {
+            requestSchema.validate(request);
+        }
 
         const commandFields = requestSchema.encodeTlv(request);
 
@@ -1067,7 +1161,7 @@ export class InteractionClient {
                     endpointId,
                     clusterId,
                     commandId: requestId,
-                })} with ${Logger.toJSON(response)})}`,
+                })} with ${Diagnostic.json(response)})}`,
             );
             return response;
         }
@@ -1103,7 +1197,7 @@ export class InteractionClient {
                 endpointId,
                 clusterId,
                 commandId: requestId,
-            })} with ${Logger.toJSON(request)}`,
+            })} with ${Diagnostic.json(request)}`,
         );
         const commandFields = requestSchema.encodeTlv(request);
 

package/src/interaction/InteractionMessenger.ts

@@ -14,6 +14,7 @@ import {
 } from "#general";
 import { Specification } from "#model";
 import {
+    ReceivedStatusResponseError,
     Status,
     StatusCode,
     StatusResponseError,
@@ -184,7 +185,10 @@ class InteractionMessenger {
         if (messageType !== MessageType.StatusResponse) return;
         const { status } = TlvStatusResponse.decode(payload);
         if (status !== StatusCode.Success)
-            throw new StatusResponseError(`Received error status: ${status}${logHint ? ` (${logHint})` : ""}`, status);
+            throw new ReceivedStatusResponseError(
+                `Received error status: ${status}${logHint ? ` (${logHint})` : ""}`,
+                status,
+            );
     }
 
     getExchangeChannelName() {
@@ -629,7 +633,7 @@ export class InteractionServerMessenger extends InteractionMessenger {
         const encodedMessage = TlvDataReportForSend.encode(dataReportToSend);
         if (encodedMessage.length > this.exchange.maxPayloadSize) {
             throw new MatterFlowError(
-                `DataReport with ${encodedMessage.length}bytes is too long to fit in a single chunk (${this.exchange.maxPayloadSize}bytes), This should not happen! Data: ${Logger.toJSON(
+                `DataReport with ${encodedMessage.length}bytes is too long to fit in a single chunk (${this.exchange.maxPayloadSize}bytes), This should not happen! Data: ${Diagnostic.json(
                     dataReportToSend,
                 )}`,
             );
@@ -680,7 +684,7 @@ export class IncomingInteractionClientMessenger extends InteractionMessenger {
         if (receivedMessageType !== messageType) {
             if (receivedMessageType === MessageType.StatusResponse) {
                 const statusCode = TlvStatusResponse.decode(message.payload).status;
-                throw new StatusResponseError(`Received status response ${statusCode}`, statusCode);
+                throw new ReceivedStatusResponseError(`Received status response ${statusCode}`, statusCode);
             }
             throw new MatterFlowError(
                 `Received unexpected message type ${receivedMessageType.toString(16)}. Expected ${messageType.toString(
@@ -852,7 +856,7 @@ export class InteractionClientMessenger extends IncomingInteractionClientMesseng
         });
         if (requestWithoutDataVersionFilters.length > this.exchange.maxPayloadSize) {
             throw new MatterFlowError(
-                `Request is too long to fit in a single chunk, This should not happen! Data: ${Logger.toJSON(request)}`,
+                `Request is too long to fit in a single chunk, This should not happen! Data: ${Diagnostic.json(request)}`,
             );
         }
 

package/src/interaction/InteractionServer.ts

@@ -4,7 +4,16 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Crypto, Diagnostic, InternalError, Logger, MatterFlowError, Observable, ServerAddressIp } from "#general";
+import {
+    Crypto,
+    Diagnostic,
+    InternalError,
+    Logger,
+    MatterError,
+    MatterFlowError,
+    Observable,
+    ServerAddressIp,
+} from "#general";
 import { AttributeModel, ClusterModel, CommandModel, GLOBAL_IDS, MatterModel, Specification } from "#model";
 import { PeerAddress } from "#peer/PeerAddress.js";
 import { SessionManager } from "#session/SessionManager.js";
@@ -19,6 +28,7 @@ import {
     EventNumber,
     INTERACTION_PROTOCOL_ID,
     NodeId,
+    ReceivedStatusResponseError,
     StatusCode,
     StatusResponseError,
     TlvAny,
@@ -355,7 +365,7 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
                         logger.debug(
                             `Read event from ${exchange.channel.name}: ${this.#endpointStructure.resolveEventName(
                                 path,
-                            )}=${Logger.toJSON(matchingEvents)}`,
+                            )}=${Diagnostic.json(matchingEvents)}`,
                         );
                         const { schema } = event;
                         reportsForPath.push(
@@ -513,7 +523,7 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
                         logger.debug(
                             `Read attribute from ${exchange.channel.name}: ${this.#endpointStructure.resolveAttributeName(
                                 path,
-                            )}=${Logger.toJSON(value)} (version=${version}) ignored because of dataVersionFilter`,
+                            )}=${Diagnostic.json(value)} (version=${version}) ignored because of dataVersionFilter`,
                         );
                         continue;
                     }
@@ -521,7 +531,7 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
                     logger.debug(
                         `Read attribute from ${exchange.channel.name}: ${this.#endpointStructure.resolveAttributeName(
                             path,
-                        )}=${Logger.toJSON(value)} (version=${version})`,
+                        )}=${Diagnostic.json(value)} (version=${version})`,
                     );
 
                     const { schema } = attribute;
@@ -868,7 +878,7 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
                     logger.debug(
                         `Handle write request from ${
                             exchange.channel.name
-                        } resolved to: ${this.#endpointStructure.resolveAttributeName(path)}=${Logger.toJSON(
+                        } resolved to: ${this.#endpointStructure.resolveAttributeName(path)}=${Diagnostic.json(
                             value,
                         )} (listIndex=${listIndex}, for-version=${dataVersion})`,
                     );
@@ -950,7 +960,7 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
                     ? `with following errors: ${errorResults
                           .map(
                               ({ path, statusCode }) =>
-                                  `${this.#endpointStructure.resolveAttributeName(path)}=${Logger.toJSON(statusCode)}`,
+                                  `${this.#endpointStructure.resolveAttributeName(path)}=${Diagnostic.json(statusCode)}`,
                           )
                           .join(", ")}`
                     : "without errors"
@@ -1115,12 +1125,12 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
                 exchange,
                 message,
             );
-        } catch (error: any) {
+        } catch (error) {
             logger.error(
                 `Subscription ${subscriptionId} for Session ${session.id}: Error while sending initial data reports`,
-                error,
+                error instanceof MatterError ? error.message : error,
             );
-            if (error instanceof StatusResponseError) {
+            if (error instanceof StatusResponseError && !(error instanceof ReceivedStatusResponseError)) {
                 logger.info(`Sending status response ${error.code} for interaction error: ${error.message}`);
                 await messenger.sendStatus(error.code, {
                     logContext: {

package/src/interaction/ServerSubscription.ts

@@ -6,6 +6,7 @@
 
 import { NumberedOccurrence } from "#events/Occurrence.js";
 import {
+    Diagnostic,
     InternalError,
     Logger,
     MatterAggregateError,
@@ -989,7 +990,7 @@ export class ServerSubscription extends Subscription {
                 `Subscription attribute changes for ID ${this.id}: ${attributes
                     .map(
                         ({ path, value, version }) =>
-                            `${this.#structure.resolveAttributeName(path)}=${Logger.toJSON(value)} (${version})`,
+                            `${this.#structure.resolveAttributeName(path)}=${Diagnostic.json(value)} (${version})`,
                     )
                     .join(", ")}`,
             ); // TODO Format path better using endpoint structure

package/src/mdns/MdnsScanner.ts

@@ -213,7 +213,7 @@ export class MdnsScanner implements Scanner {
                     if (dnsMessageDataToSend.answers.length === 0) {
                         // The first answer is already too big, log at least a warning
                         logger.warn(
-                            `MDNS Query with ${Logger.toJSON(
+                            `MDNS Query with ${Diagnostic.json(
                                 queries,
                             )} is too big to fit into a single MDNS message. Send anyway, but please report!`,
                         );
@@ -265,7 +265,7 @@ export class MdnsScanner implements Scanner {
             answers = this.#combineStructuredAnswers(activeExistingQuery.answers, answers);
         }
         this.#activeAnnounceQueries.set(queryId, { queries, answers });
-        logger.debug(`Set ${queries.length} query records for query ${queryId}: ${Logger.toJSON(queries)}`);
+        logger.debug(`Set ${queries.length} query records for query ${queryId}: ${Diagnostic.json(queries)}`);
         this.#queryTimer?.stop();
         this.#nextAnnounceIntervalSeconds = START_ANNOUNCE_INTERVAL_SECONDS; // Reset query interval
         this.#queryTimer = Time.getTimer("MDNS discovery", 0, () => this.#sendQueries()).start();

package/src/peer/ControllerCommissioner.ts

@@ -11,6 +11,8 @@ import { Fabric } from "#fabric/Fabric.js";
 import {
     Channel,
     ChannelType,
+    ClassExtends,
+    Diagnostic,
     Environment,
     Environmental,
     isIPv6,
@@ -55,6 +57,12 @@ export interface CommissioningOptions extends Partial<ControllerCommissioningFlo
      * not throw, the commissioner considers commissioning complete.
      */
     finalizeCommissioning?: (peerAddress: PeerAddress, discoveryData?: DiscoveryData) => Promise<void>;
+
+    /**
+     * Commissioning Flow Implementation as class that extends the official implementation to use for commissioning.
+     * Defaults to the matter.js default implementation {@link ControllerCommissioningFlow}.
+     */
+    commissioningFlowImpl?: ClassExtends<ControllerCommissioningFlow>;
 }
 
 /**
@@ -169,9 +177,11 @@ export class ControllerCommissioner {
     }
 
     /**
-     * Commission a node with discovery.
+     * Discover and establish a PASE channel with a device.
      */
-    async commissionWithDiscovery(options: DiscoveryAndCommissioningOptions): Promise<PeerAddress> {
+    async discoverAndEstablishPase(
+        options: DiscoveryAndCommissioningOptions,
+    ): Promise<{ paseSecureChannel: MessageChannel; discoveryData?: DiscoveryData }> {
         const {
             discovery: { timeoutSeconds = 30 },
             passcode,
@@ -211,9 +221,9 @@ export class ControllerCommissioner {
         const scannersToUse = this.#context.scanners.select(discoveryCapabilities);
 
         logger.info(
-            `Commissioning device with identifier ${Logger.toJSON(identifierData)} and ${
+            `Connecting to device with identifier ${Diagnostic.json(identifierData)} and ${
                 scannersToUse.length
-            } scanners and knownAddress ${Logger.toJSON(knownAddress)}`,
+            } scanners and knownAddress ${Diagnostic.json(knownAddress)}`,
         );
 
         // If we have a known address we try this first before we discover the device
@@ -251,6 +261,17 @@ export class ControllerCommissioner {
             paseSecureChannel = result;
         }
 
+        return { paseSecureChannel, discoveryData };
+    }
+
+    /**
+     * Commission a node with discovery.
+     */
+    async commissionWithDiscovery(options: DiscoveryAndCommissioningOptions): Promise<PeerAddress> {
+        // Establish PASE channel
+        const { paseSecureChannel, discoveryData } = await this.discoverAndEstablishPase(options);
+
+        // Commission the node
         return await this.#commissionConnectedNode(paseSecureChannel, options, discoveryData);
     }
 
@@ -266,7 +287,7 @@ export class ControllerCommissioner {
     ): Promise<MessageChannel> {
         let paseChannel: Channel<Uint8Array>;
         if (device !== undefined) {
-            logger.info(`Commissioning device`, MdnsScanner.discoveryDataDiagnostics(device));
+            logger.info(`Establish PASE to device`, MdnsScanner.discoveryDataDiagnostics(device));
         }
         if (address.type === "udp") {
             const { ip } = address;
@@ -347,7 +368,11 @@ export class ControllerCommissioner {
             ...options,
         };
 
-        const { fabric, finalizeCommissioning: performCaseCommissioning } = commissioningOptions;
+        const {
+            fabric,
+            finalizeCommissioning: performCaseCommissioning,
+            commissioningFlowImpl = ControllerCommissioningFlow,
+        } = commissioningOptions;
 
         // TODO: Create the fabric only when needed before commissioning (to do when refactoring MatterController away)
         // TODO also move certificateManager and other parts into that class to get rid of them here
@@ -381,7 +406,7 @@ export class ControllerCommissioner {
         logger.info(
             `Start commissioning of node ${address.nodeId} into fabric ${fabric.fabricId} (index ${address.fabricIndex})`,
         );
-        const commissioningManager = new ControllerCommissioningFlow(
+        const commissioningManager = new commissioningFlowImpl(
             // Use the created secure session to do the commissioning
             new InteractionClient(
                 new DedicatedChannelExchangeProvider(this.#context.exchanges, paseSecureMessageChannel),