@matter/protocol 0.15.1 → 0.15.2-alpha.0-20250703-2e16aba2b

package/src/action/client/ClientSubscriptionHandler.ts

@@ -0,0 +1,137 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ReadResult } from "#action/response/ReadResult.js";
+import { DecodedDataReport } from "#interaction/DecodedDataReport.js";
+import { IncomingInteractionClientMessenger } from "#interaction/InteractionMessenger.js";
+import { SubscriptionId } from "#interaction/Subscription.js";
+import { MessageExchange } from "#protocol/MessageExchange.js";
+import { ProtocolHandler } from "#protocol/ProtocolHandler.js";
+import { DataReport, INTERACTION_PROTOCOL_ID, Status } from "#types";
+import { Diagnostic, InternalError, Logger } from "@matter/general";
+import { ClientSubscriptions } from "./ClientSubscriptions.js";
+import { InputChunk } from "./InputChunk.js";
+
+const logger = Logger.get("ClientSubscriptionHandler");
+
+/**
+ * A protocol handler that informs {@link ClientSubscriptions} of new exchanges.
+ */
+export class ClientSubscriptionHandler implements ProtocolHandler {
+    id = INTERACTION_PROTOCOL_ID;
+    requiresSecureSession = true;
+
+    #subscriptions: ClientSubscriptions;
+
+    constructor(subscriptions: ClientSubscriptions) {
+        this.#subscriptions = subscriptions;
+    }
+
+    async onNewExchange(exchange: MessageExchange) {
+        const messenger = new IncomingInteractionClientMessenger(exchange);
+        // Read the initial report
+        const reports = messenger.readDataReports();
+
+        const initialIteration = await reports.next();
+        if (initialIteration.done) {
+            throw new InternalError("Exchange initiated with no initial message");
+        }
+        const initialReport = initialIteration.value;
+
+        // Ensure there is a subscription ID present
+        const { subscriptionId } = initialReport;
+        if (subscriptionId === undefined) {
+            logger.debug("Ignoring unsolicited data report with no subscription ID");
+            await sendInvalid(messenger, undefined);
+            return;
+        }
+
+        // Ensure the subscription ID is valid
+        const subscription = this.#subscriptions.get(subscriptionId);
+        if (subscription === undefined) {
+            logger.debug("Ignoring data report for unknown subscription ID", Diagnostic.strong(subscriptionId));
+            await sendInvalid(messenger, subscriptionId);
+            return;
+        }
+
+        // If this is just a ping, only reset the timeout
+        if (!initialReport.attributeReports?.length && !initialReport.eventReports?.length) {
+            subscription.timeoutAtMs = undefined;
+            this.#subscriptions.resetTimer();
+            await exchange.close();
+            return;
+        }
+
+        // Pass the data to the recipient
+        try {
+            subscription.isReading = true;
+
+            if (subscription.request.updated) {
+                await subscription.request.updated(processReports(initialReport, reports, messenger));
+            } else {
+                // It doesn't make sense to have the callback undefined but we allow it in the type because they may
+                // be handled by intermediate interactables.  So we handle the case here too, but just iterate and throw
+                // away the reports
+                for await (const _chunk of reports);
+            }
+        } finally {
+            subscription.isReading = false;
+            subscription.timeoutAtMs = undefined;
+            this.#subscriptions.resetTimer();
+            await exchange.close();
+        }
+    }
+
+    async close() {}
+}
+
+async function sendInvalid(messenger: IncomingInteractionClientMessenger, subscriptionId?: SubscriptionId) {
+    await messenger.sendStatus(Status.InvalidSubscription, {
+        multipleMessageInteraction: true,
+        logContext: {
+            subId: subscriptionId,
+        },
+    });
+    await messenger.close();
+}
+
+/**
+ * Convert incoming data reports into a {@link ReadResult}.
+ *
+ * Parses incoming reports and validates subscription IDs.
+ */
+async function* processReports(
+    initialReport: DataReport,
+    otherReports: AsyncIterable<DataReport>,
+    messenger: IncomingInteractionClientMessenger,
+): ReadResult {
+    yield InputChunk(initialReport);
+
+    const { subscriptionId } = initialReport;
+
+    for await (const report of otherReports) {
+        const decoded = DecodedDataReport(report);
+
+        if (decoded.subscriptionId === undefined) {
+            logger.debug(
+                "Ignoring data report for incorrect subscription id",
+                Diagnostic.strong(decoded.subscriptionId),
+            );
+            await sendInvalid(messenger, decoded.subscriptionId);
+        }
+
+        if (decoded.subscriptionId !== subscriptionId) {
+            logger.debug(
+                "Ignoring data report for incorrect subscription id",
+                Diagnostic.strong(decoded.subscriptionId),
+            );
+            await sendInvalid(messenger, decoded.subscriptionId);
+            continue;
+        }
+
+        yield InputChunk(report);
+    }
+}

package/src/action/client/ClientSubscriptions.ts

@@ -0,0 +1,172 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Subscribe } from "#action/request/Subscribe.js";
+import { ReadResult } from "#action/response/ReadResult.js";
+import { ActiveSubscription } from "#action/response/SubscribeResult.js";
+import {
+    BasicSet,
+    CanceledError,
+    Diagnostic,
+    Environment,
+    Environmental,
+    Logger,
+    Time,
+    TimeoutError,
+    Timer,
+} from "#general";
+import { SubscriptionId } from "#interaction/Subscription.js";
+import { SubscribeResponse } from "#types";
+import { ClientSubscription } from "./ClientSubscription.js";
+
+const logger = Logger.get("ClientSubscriptions");
+
+/**
+ * A managed set of {@link ClientSubscription} instances.
+ */
+export class ClientSubscriptions {
+    #subscriptions = new BasicSet<ClientSubscription>();
+    #timeout?: Timer;
+    #nextTimeoutAt?: number;
+
+    static [Environmental.create](env: Environment) {
+        const instance = new ClientSubscriptions();
+        env.set(ClientSubscriptions, instance);
+        return instance;
+    }
+
+    /**
+     * Register an active subscription.
+     */
+    add(request: Subscribe, response: SubscribeResponse): ActiveSubscription {
+        const subscription: ClientSubscription = {
+            ...response,
+            request,
+            close: () => this.#closeOne(subscription, new CanceledError()),
+            timeoutAtMs: undefined,
+            isClosed: false,
+            isReading: true,
+        };
+
+        this.#subscriptions.add(subscription);
+        this.resetTimer();
+
+        return subscription;
+    }
+
+    /**
+     * Retrieve a subscription by ID.
+     */
+    get(id: SubscriptionId) {
+        return this.#subscriptions.get("subscriptionId", id);
+    }
+
+    /**
+     * Iterate over active subscriptions.
+     */
+    [Symbol.iterator]() {
+        return this.#subscriptions[Symbol.iterator]();
+    }
+
+    /**
+     * Terminate all subscriptions.
+     */
+    async close() {
+        if (this.#timeout) {
+            this.#timeout.stop();
+            this.#timeout = undefined;
+        }
+        for (const subscription of this.#subscriptions) {
+            subscription.close();
+        }
+    }
+
+    /**
+     * Restart the timeout timer for the current set of active subscriptions.
+     */
+    resetTimer() {
+        const now = Time.nowMs();
+        let nextTimeoutAt: number | undefined;
+
+        // Process each subscription
+        for (const subscription of this.#subscriptions) {
+            // If reading data reports, ignore for timeout purposes
+            if (subscription.isReading) {
+                continue;
+            }
+
+            // Update timeout or expire if timed out
+            let { timeoutAtMs } = subscription;
+            if (timeoutAtMs === undefined) {
+                // Set timeout time
+                timeoutAtMs = subscription.timeoutAtMs = timeoutFor(subscription);
+            } else if (timeoutAtMs < now) {
+                // Timeout
+                this.#timeOut(subscription);
+                continue;
+            }
+
+            // If this is the earliest timeout, record
+            if (nextTimeoutAt === undefined || nextTimeoutAt > timeoutAtMs) {
+                nextTimeoutAt = timeoutAtMs;
+            }
+        }
+
+        // If no subscriptions require timeout, disable timer
+        if (nextTimeoutAt === undefined) {
+            this.#nextTimeoutAt = undefined;
+            this.#timeout?.stop();
+            return;
+        }
+
+        // Create or update timer if not set for correct interval
+        if (nextTimeoutAt !== this.#nextTimeoutAt) {
+            this.#nextTimeoutAt = nextTimeoutAt;
+            if (this.#timeout) {
+                this.#timeout?.stop();
+                this.#timeout.intervalMs = nextTimeoutAt - now;
+            } else {
+                this.#timeout = Time.getTimer("SubscriptionTimeout", nextTimeoutAt - now, this.resetTimer.bind(this));
+            }
+        }
+    }
+
+    #closeOne(subscription: ClientSubscription, cause: CanceledError | TimeoutError) {
+        if (subscription.isClosed) {
+            return;
+        }
+        subscription.isClosed = true;
+        this.#subscriptions.delete(subscription);
+
+        try {
+            subscription.request.closed?.(cause);
+        } catch (e) {
+            logger.error("Error canceling subscription", Diagnostic.strong(subscription.subscriptionId), e);
+        }
+    }
+
+    #timeOut(registration: ClientSubscription) {
+        logger.info(
+            "Subscription",
+            Diagnostic.strong(registration.subscriptionId),
+            "timed out after",
+            Diagnostic.strong(`${timeoutFor(registration)}ms`),
+        );
+
+        // TODO - rather than closing, put into dormant state and resubscribe when connection reestablishes
+        this.#closeOne(registration, new TimeoutError());
+    }
+}
+
+function timeoutFor(subscription: ClientSubscription) {
+    return subscription.maxInterval * 1000 + (subscription.request.maxPeerResponseTime ?? 0);
+}
+
+export namespace ClientSubscriptions {
+    export interface Listener {
+        (reports: AsyncIterable<ReadResult.Chunk>): Promise<void>;
+    }
+}

package/src/action/client/InputChunk.ts

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ReadResult } from "#action/response/ReadResult.js";
+import { DecodedDataReport } from "#interaction/DecodedDataReport.js";
+import { DataReport, Status, TlvAny } from "#types";
+
+/**
+ * Converts a {@link DataReport} into a {@link ReadResult.Chunk}.
+ */
+export function* InputChunk(input: DataReport): ReadResult.Chunk {
+    const report = DecodedDataReport(input);
+
+    for (const attr of report.attributeReports) {
+        yield {
+            kind: "attr-value",
+            tlv: TlvAny,
+            ...attr,
+        };
+    }
+
+    if (report.attributeStatus) {
+        for (const attr of report.attributeStatus) {
+            yield {
+                kind: "attr-status",
+                path: attr.path,
+                status: attr.status ?? Status.Failure, // TODO - attr.status shouldn't be optional?
+                clusterStatus: attr.clusterStatus,
+            };
+        }
+    }
+
+    for (const event of report.eventReports) {
+        for (const occurrence of event.events) {
+            yield {
+                kind: "event-value",
+                path: event.path,
+                value: occurrence,
+                number: occurrence.eventNumber,
+                priority: occurrence.priority,
+                timestamp: Number(
+                    // TODO - this may not be useful, need to determine correct form
+                    occurrence.epochTimestamp ??
+                        occurrence.systemTimestamp ??
+                        occurrence.deltaEpochTimestamp ??
+                        occurrence.deltaSystemTimestamp ??
+                        0,
+                ),
+
+                // TODO - temporary, field will be removed
+                tlv: TlvAny,
+            };
+        }
+    }
+
+    if (report.eventStatus) {
+        for (const event of report.eventStatus) {
+            if (event.status !== undefined) {
+                yield {
+                    kind: "event-status",
+                    path: event.path,
+                    status: event.status,
+                    clusterStatus: event.clusterStatus,
+                };
+            }
+            if (event.clusterStatus !== undefined) {
+                yield {
+                    kind: "event-status",
+                    path: event.path,
+                    status: event.status ?? Status.Failure,
+                    clusterStatus: event.clusterStatus,
+                };
+            }
+        }
+    }
+}

package/src/action/client/ReadScope.ts

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Read } from "#action/request/Read.js";
+import { ClusterId, EndpointNumber } from "#types";
+
+/**
+ * This utility tells you whether a given endpoint/cluster is in scope for a read.
+ */
+export interface ReadScope {
+    /**
+     * Is a cluster included in the read?
+     *
+     * This is useful to determine if the read should include a version filter.
+     */
+    isRelevant(endpoint: EndpointNumber, cluster: ClusterId): boolean;
+
+    /**
+     * Are all attributes in a cluster included in a read?
+     *
+     * This is useful to determine if the cluster's version should be updated in response to a read.
+     */
+    isWildcard(endpoint: EndpointNumber, cluster: ClusterId): boolean;
+}
+
+interface Check {
+    (endpoint: EndpointNumber, cluster: ClusterId): boolean;
+}
+
+export function ReadScope(read: Read): ReadScope {
+    return {
+        isRelevant(endpoint, cluster) {
+            this.isRelevant = generateScopeTester(read, "any");
+            return this.isRelevant(endpoint, cluster);
+        },
+
+        isWildcard(endpoint, cluster) {
+            this.isWildcard = generateScopeTester(read, "all");
+            return this.isWildcard(endpoint, cluster);
+        },
+    };
+}
+
+function generateScopeTester(read: Read, attrRequirement: "any" | "all"): Check {
+    if (!read.attributeRequests?.length) {
+        return isNever;
+    }
+
+    let wildcardEndpointClusters: undefined | Set<ClusterId>;
+    let specificEndpointClusters: undefined | Record<EndpointNumber, true | Set<ClusterId>>;
+
+    for (const { endpointId, clusterId, attributeId } of read.attributeRequests) {
+        // Ignore path if it addresses a specific attribute and we are only interested in wildcard attributes
+        if (attributeId !== undefined && attrRequirement === "all") {
+            continue;
+        }
+
+        // Wildcard endpoint
+        if (endpointId === undefined) {
+            // Full wildcard read; short-circuit all subsequent logic
+            if (clusterId === undefined) {
+                return isAlways;
+            }
+
+            // Wildcard cluster across all endpoints
+            (wildcardEndpointClusters ??= new Set()).add(clusterId);
+            continue;
+        }
+
+        // Specific endpoint with wildcard cluster cases
+        if (clusterId === undefined) {
+            (specificEndpointClusters ??= {})[endpointId] = true;
+            continue;
+        }
+
+        // Specific endpoint and cluster
+        if (attributeId === undefined) {
+            let ep = specificEndpointClusters?.[endpointId];
+            if (ep === true) {
+                continue;
+            }
+            if (ep === undefined) {
+                ep = (specificEndpointClusters ??= {})[endpointId] = new Set();
+            }
+            ep.add(clusterId);
+        }
+    }
+
+    return (endpoint, cluster) => {
+        if (wildcardEndpointClusters?.has(cluster)) {
+            return true;
+        }
+        const ep = specificEndpointClusters?.[endpoint];
+        return ep === true || !!ep?.has(cluster);
+    };
+}
+
+function isNever() {
+    return false;
+}
+
+function isAlways() {
+    return true;
+}

package/src/action/client/index.ts

@@ -5,3 +5,8 @@
  */
 
 export * from "./ClientInteraction.js";
+export * from "./ClientSubscription.js";
+export * from "./ClientSubscriptionHandler.js";
+export * from "./ClientSubscriptions.js";
+export * from "./InputChunk.js";
+export * from "./ReadScope.js";

package/src/action/request/Read.ts

@@ -23,11 +23,6 @@ import { Specifier } from "./Specifier.js";
  */
 export interface Read extends ReadRequest {}
 
-/**
- * Formulate a read request using Matter numeric IDs.
- */
-export function Read(options: Read.Options): Read;
-
 /**
  * Formulate a read request with extended options and name-based IDs.
  */

package/src/action/request/Subscribe.ts

@@ -4,7 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { UINT16_MAX } from "#general";
+import type { ReadResult } from "#action/response/ReadResult.js";
+import { CanceledError, TimeoutError, UINT16_MAX } from "#general";
 import { MalformedRequestError } from "./MalformedRequestError.js";
 import { Read } from "./Read.js";
 
@@ -18,10 +19,21 @@ export interface Subscribe extends Read {
     keepSubscriptions: boolean;
     minIntervalFloorSeconds?: number;
     maxIntervalCeilingSeconds?: number;
+    maxPeerResponseTime?: number;
+
+    /**
+     * Invoked when subscribed data changes.
+     */
+    updated?: (data: ReadResult) => Promise<void>;
+
+    /**
+     * Invoked when the subscription is no longer active.
+     */
+    closed?: (cause: CanceledError | TimeoutError) => void;
 }
 
-export function Subscribe(options: Subscribe.Options): Subscribe {
-    const subscribe = Read(options) as unknown as Subscribe;
+export function Subscribe(options: Subscribe.Options, ...selectors: Read.Selector[]): Subscribe {
+    const subscribe = Read(options, ...selectors) as unknown as Subscribe;
 
     const { keepSubscriptions, minIntervalFloorSeconds, maxIntervalCeilingSeconds } = options;
     subscribe.keepSubscriptions = keepSubscriptions ?? true;
@@ -48,6 +60,8 @@ export namespace Subscribe {
         keepSubscriptions?: boolean;
         minIntervalFloorSeconds?: number;
         maxIntervalCeilingSeconds?: number;
+        update?: Subscribe["updated"];
+        closed?: Subscribe["closed"];
     }
 }
 

package/src/action/response/SubscribeResult.ts

@@ -5,10 +5,9 @@
  */
 
 import { SubscribeResponse } from "#types";
-import { ReadResult } from "./ReadResult.js";
 
-export interface SubscribeResult extends AsyncIterator<SubscribeResult.Chunk> {}
+export type SubscribeResult = Promise<ActiveSubscription>;
 
-export namespace SubscribeResult {
-    export type Chunk = ReadResult.Chunk | SubscribeResponse;
+export interface ActiveSubscription extends SubscribeResponse {
+    close(): void;
 }

package/src/common/FailsafeContext.ts

@@ -183,7 +183,6 @@ export abstract class FailsafeContext {
     }
 
     async close() {
-        await this.#construction;
         await this.#construction.close(async () => {
             if (this.#failsafe) {
                 await this.#failsafe.close();

package/src/fabric/FabricAuthority.ts

@@ -5,7 +5,16 @@
  */
 
 import { CertificateAuthority } from "#certificate/CertificateAuthority.js";
-import { Bytes, CRYPTO_SYMMETRIC_KEY_LENGTH, Environment, Environmental, ImplementationError, Logger } from "#general";
+import {
+    Bytes,
+    Construction,
+    CRYPTO_SYMMETRIC_KEY_LENGTH,
+    Environment,
+    Environmental,
+    ImplementationError,
+    Logger,
+    Observable,
+} from "#general";
 import { CaseAuthenticatedTag, FabricId, FabricIndex, NodeId, VendorId } from "#types";
 import { Fabric, FabricBuilder } from "./Fabric.js";
 import { FabricManager } from "./FabricManager.js";
@@ -48,14 +57,25 @@ export const DEFAULT_FABRIC_ID = FabricId(1);
  * Manages fabrics controlled locally associated with a specific CA.
  */
 export class FabricAuthority {
+    #construction: Construction<FabricAuthority>;
     #ca: CertificateAuthority;
     #fabrics: FabricManager;
     #config: FabricAuthorityConfiguration;
+    #fabricAdded = new Observable<[Fabric]>();
 
     constructor({ ca, fabrics, config }: FabricAuthorityContext) {
         this.#ca = ca;
         this.#fabrics = fabrics;
         this.#config = config;
+
+        this.#construction = Construction(this, async () => {
+            await this.#ca.construction;
+            await this.#fabrics.construction;
+        });
+    }
+
+    get construction() {
+        return this.#construction;
     }
 
     /**
@@ -89,6 +109,13 @@ export class FabricAuthority {
         return Array.from(this.#fabrics).filter(this.hasControlOf.bind(this));
     }
 
+    /**
+     * Emits after creating a new fabric.
+     */
+    get fabricAdded() {
+        return this.#fabricAdded;
+    }
+
     /**
      * Determine whether a fabric belongs to this authority.
      */
@@ -137,6 +164,7 @@ export class FabricAuthority {
         this.#fabrics.addFabric(fabric);
 
         logger.debug(`Created new controller fabric ${index}`);
+        this.#fabricAdded.emit(fabric);
 
         return fabric;
     }