@matter/protocol 0.16.0-alpha.0-20251030-e9ca79f93 → 0.16.0-alpha.0-20251101-70c8d51d7

package/src/action/client/subscription/ClientSubscription.ts

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Subscribe } from "#action/request/Subscribe.js";
+import type { ActiveSubscription } from "#action/response/SubscribeResult.js";
+import { Abort, Diagnostic, Logger } from "#general";
+import { PeerAddress } from "#peer/PeerAddress.js";
+import { ClientSubscribe } from "./ClientSubscribe.js";
+
+const logger = Logger.get("ClientSubscription");
+
+/**
+ * The client view of an established Matter subscription.
+ */
+export abstract class ClientSubscription implements ActiveSubscription {
+    readonly request: Subscribe;
+    readonly peer: PeerAddress;
+    abstract subscriptionId: number;
+    abstract maxInterval: number;
+    abstract interactionModelRevision: number;
+
+    /**
+     * If the subscription has an async worker, this is the promise associated with the worker.
+     */
+    done?: Promise<void>;
+
+    readonly #closed: () => void;
+    readonly #abort: Abort;
+    #isClosed = false;
+
+    constructor({ request, peer, closed, abort }: ClientSubscription.Configuration) {
+        this.request = request;
+        this.peer = peer;
+        this.#closed = closed;
+        this.#abort = new Abort({
+            abort,
+            handler: this.close.bind(this),
+        });
+    }
+
+    close() {
+        if (this.#isClosed) {
+            return;
+        }
+        this.#isClosed = true;
+
+        this.#abort();
+        this.#closed();
+
+        const unhandledError = (e: unknown) => {
+            this.logger.error("Unhandled error in subscription to", Diagnostic.strong(this.peer.toString()), e);
+        };
+
+        if (this.done) {
+            this.done
+                .finally(() => {
+                    this.request.closed?.();
+                })
+                .catch(unhandledError);
+        } else {
+            try {
+                this.request.closed?.();
+            } catch (e) {
+                unhandledError(e);
+            }
+        }
+    }
+
+    protected get abort() {
+        return this.#abort;
+    }
+
+    protected get logger() {
+        return logger;
+    }
+}
+
+export namespace ClientSubscription {
+    export interface Configuration {
+        request: ClientSubscribe;
+        peer: PeerAddress;
+        closed: () => void;
+        abort?: AbortSignal;
+    }
+}

package/src/action/client/{ClientSubscriptionHandler.ts → subscription/ClientSubscriptionHandler.ts}

@@ -11,9 +11,10 @@ import { IncomingInteractionClientMessenger } from "#interaction/InteractionMess
 import { SubscriptionId } from "#interaction/Subscription.js";
 import { MessageExchange } from "#protocol/MessageExchange.js";
 import { ProtocolHandler } from "#protocol/ProtocolHandler.js";
+import { SecureSession } from "#session/SecureSession.js";
 import { DataReport, INTERACTION_PROTOCOL_ID, Status } from "#types";
+import { InputChunk } from "../InputChunk.js";
 import { ClientSubscriptions } from "./ClientSubscriptions.js";
-import { InputChunk } from "./InputChunk.js";
 
 const logger = Logger.get("ClientSubscriptionHandler");
 
@@ -50,7 +51,9 @@ export class ClientSubscriptionHandler implements ProtocolHandler {
         }
 
         // Ensure the subscription ID is valid
-        const subscription = this.#subscriptions.get(subscriptionId);
+        const { session } = exchange.channel;
+        SecureSession.assert(session);
+        const subscription = this.#subscriptions.getPeer(session.peerAddress, subscriptionId);
         if (subscription === undefined) {
             logger.debug("Ignoring data report for unknown subscription ID", Diagnostic.strong(subscriptionId));
             await sendInvalid(messenger, subscriptionId);

package/src/action/client/subscription/ClientSubscriptions.ts

@@ -0,0 +1,150 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ReadResult } from "#action/response/ReadResult.js";
+import type { ActiveSubscription } from "#action/response/SubscribeResult.js";
+import { BasicSet, Environment, Environmental, Millis, Time, Timer, Timestamp } from "#general";
+import { SubscriptionId } from "#interaction/Subscription.js";
+import { PeerAddress } from "#peer/PeerAddress.js";
+import { ClientSubscription } from "./ClientSubscription.js";
+import type { PeerSubscription } from "./PeerSubscription.js";
+
+/**
+ * A managed set of {@link ActiveSubscription} instances.
+ */
+export class ClientSubscriptions {
+    #active = new BasicSet<ClientSubscription>();
+    #peers = new Map<PeerAddress, Map<number, PeerSubscription>>();
+    #timeout?: Timer;
+
+    static [Environmental.create](env: Environment) {
+        const instance = new ClientSubscriptions();
+        env.set(ClientSubscriptions, instance);
+        return instance;
+    }
+
+    /**
+     * Register a user-facing {@link ClientSubscription}.
+     */
+    addActive(subscription: ClientSubscription) {
+        this.#active.add(subscription);
+    }
+
+    /**
+     * Register a {@link PeerSubscription}.
+     */
+    addPeer(subscription: PeerSubscription) {
+        let forPeer = this.#peers.get(subscription.peer);
+        if (forPeer === undefined) {
+            this.#peers.set(subscription.peer, (forPeer = new Map()));
+        }
+        forPeer.set(subscription.subscriptionId, subscription);
+
+        this.resetTimer();
+    }
+
+    /**
+     * Retrieve a {@link PeerSubscription} by ID.
+     */
+    getPeer(address: PeerAddress, id: SubscriptionId) {
+        return this.#peers.get(address)?.get(id);
+    }
+
+    /**
+     * Unregister a {@link PeerSubscription}.
+     */
+    delete(subscription: ClientSubscription) {
+        const forPeer = this.#peers.get(subscription.peer);
+        if (forPeer?.delete(subscription.subscriptionId)) {
+            if (!forPeer.size) {
+                this.#peers.delete(subscription.peer);
+            }
+        }
+        this.#active.delete(subscription);
+    }
+
+    /**
+     * Iterate over active subscriptions.
+     */
+    [Symbol.iterator]() {
+        return this.#active[Symbol.iterator]();
+    }
+
+    /**
+     * Terminate all subscriptions.
+     */
+    async close() {
+        if (this.#timeout) {
+            this.#timeout.stop();
+            this.#timeout = undefined;
+        }
+
+        for (const subscription of this.#active) {
+            subscription.close();
+        }
+
+        await this.#active.empty;
+    }
+
+    /**
+     * Restart the timeout timer for the current set of active subscriptions.
+     */
+    resetTimer() {
+        const now = Time.nowMs;
+        let nextTimeoutAt: Timestamp | undefined;
+
+        // Process each subscription
+        for (const peer of this.#peers.values()) {
+            for (const subscription of peer.values()) {
+                // If reading data reports, ignore for timeout purposes
+                if (subscription.isReading) {
+                    continue;
+                }
+
+                // Update timeout or expire if timed out
+                let { timeoutAt } = subscription;
+                if (timeoutAt === undefined) {
+                    // Set timeout time
+                    timeoutAt = subscription.timeoutAt = Timestamp(now + subscription.timeout);
+                } else if (timeoutAt < now) {
+                    // Timeout
+                    subscription.timedOut();
+                    continue;
+                }
+
+                // If this is the earliest timeout, record
+                if (nextTimeoutAt === undefined || nextTimeoutAt > timeoutAt) {
+                    nextTimeoutAt = timeoutAt;
+                }
+            }
+        }
+
+        // If no subscriptions require timeout, disable timer
+        if (nextTimeoutAt === undefined) {
+            this.#timeout?.stop();
+            return;
+        }
+
+        // Create or update timer if not set for correct interval
+        if (this.#timeout) {
+            this.#timeout?.stop();
+            this.#timeout.interval = Millis(nextTimeoutAt - now);
+        } else {
+            this.#timeout = Time.getTimer(
+                "Subscription timeout",
+                Millis(nextTimeoutAt - now),
+                this.resetTimer.bind(this),
+            );
+        }
+        this.#timeout.start();
+    }
+}
+
+export namespace ClientSubscriptions {
+    export interface Listener {
+        (reports: AsyncIterable<ReadResult.Chunk>): Promise<void>;
+    }
+}

package/src/action/client/subscription/PeerSubscription.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Diagnostic, Duration, Millis, Seconds, Timestamp } from "#general";
+import type { SubscribeResponse } from "#types";
+import { ClientSubscription } from "./ClientSubscription.js";
+
+/**
+ * A Matter protocol-level subscription established with a peer.
+ */
+export class PeerSubscription extends ClientSubscription {
+    readonly interactionModelRevision: number;
+    readonly maxInterval: number;
+    readonly subscriptionId: number;
+    isReading = false;
+
+    timeoutAt?: Timestamp;
+
+    constructor(config: PeerSubscription.Configuration) {
+        super(config);
+
+        const { subscriptionId, interactionModelRevision, maxInterval } = config.response;
+        this.subscriptionId = subscriptionId;
+        this.interactionModelRevision = interactionModelRevision;
+        this.maxInterval = maxInterval;
+    }
+
+    get timeout() {
+        return Millis(Seconds(this.maxInterval) + (this.request.maxPeerResponseTime ?? 0));
+    }
+
+    timedOut() {
+        this.logger.info(
+            "Subscription",
+            Diagnostic.strong(this.subscriptionId),
+            "timed out after",
+            Diagnostic.strong(Duration.format(this.timeout)),
+        );
+
+        this.close();
+    }
+}
+
+export namespace PeerSubscription {
+    export interface Configuration extends ClientSubscription.Configuration {
+        response: SubscribeResponse;
+    }
+}

package/src/action/client/subscription/SustainedSubscription.ts

@@ -0,0 +1,199 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Subscribe } from "#action/request/Subscribe.js";
+import type { ActiveSubscription } from "#action/response/SubscribeResult.js";
+import {
+    asError,
+    AsyncObservableValue,
+    Diagnostic,
+    Duration,
+    Hours,
+    ImplementationError,
+    Logger,
+    RetrySchedule,
+    Seconds,
+    Time,
+} from "#general";
+import { Specification } from "#model";
+import { SubscribeResponse } from "#types";
+import type { ClientSubscribe } from "./ClientSubscribe.js";
+import { ClientSubscription } from "./ClientSubscription.js";
+import { PeerSubscription } from "./PeerSubscription.js";
+
+const logger = Logger.get("ClientSubscription");
+
+/**
+ * An {@link ActiveSubscription} that remains active regardless of the state of the peer.
+ *
+ * This class performs retries in response to connection errors and timeouts.  The underlying Matter subscription and
+ * thus {@link ActiveSubscription#subscriptionId} may change if the peer goes offline or experiences transient errors.
+ *
+ * TODO - need to make underlying exchange provider abortable and work out how the retry schedule at this level
+ *   interacts with the MDNS and secure protocol retries.  Will require some refactoring at lower levels.  Leaving
+ *   retries at this level relatively conservative for now
+ */
+export class SustainedSubscription extends ClientSubscription {
+    #request: ClientSubscribe;
+    #subscription?: ActiveSubscription;
+    #retries: RetrySchedule;
+    #subscribe: (request: Subscribe) => Promise<PeerSubscription>;
+    #active = AsyncObservableValue(false);
+    #inactive = AsyncObservableValue(true);
+
+    constructor(config: SustainedSubscription.Configuration) {
+        super(config);
+
+        const { request, retries, subscribe } = config;
+
+        this.#request = request;
+        this.#retries = retries;
+        this.#subscribe = subscribe;
+        this.done = this.#run();
+    }
+
+    /**
+     * Emits when active state changes.
+     */
+    get active() {
+        return this.#active;
+    }
+
+    /**
+     * Emits when inactive state changes.
+     */
+    get inactive() {
+        return this.#inactive;
+    }
+
+    async #run() {
+        const updated = this.#request.updated?.bind(this.#request);
+
+        while (true) {
+            // Create request and promise that will inform us when the underlying subscription closes
+            const request = { ...this.#request, updated };
+            if (this.#request.updated) {
+                request.updated = this.#request.updated.bind(request);
+            }
+            const closed = new Promise<void>(resolve => {
+                request.closed = () => {
+                    this.#subscription = undefined;
+                    resolve();
+                };
+            });
+
+            // Subscribe
+            for (const retry of this.#retries) {
+                try {
+                    this.#subscription = await this.#subscribe(request);
+                    break;
+                } catch (e) {
+                    if (this.abort.aborted) {
+                        return;
+                    }
+
+                    logger.error(
+                        `Failed to establish subscription to ${this.peer}, retry in ${Duration.format(retry)}:`,
+                        Diagnostic.errorMessage(asError(e)),
+                    );
+                }
+
+                const readyForRetry = Time.sleep("subscription retry", retry);
+                await this.abort.race(readyForRetry);
+                readyForRetry.cancel();
+                if (this.abort.aborted) {
+                    break;
+                }
+            }
+
+            // Notify listeners of active subscription
+            await this.#inactive.emit(false);
+            await this.#active.emit(true);
+            if (this.abort.aborted) {
+                break;
+            }
+
+            // Wait for the subscription to close
+            await closed;
+
+            // Notify listeners of inactive subscription
+            await this.#active.emit(false);
+            await this.#inactive.emit(true);
+            if (this.abort.aborted) {
+                break;
+            }
+
+            // If aborted then we're done
+            if (this.abort.aborted) {
+                break;
+            }
+
+            // If we aren't aborted then we are here due to timeout
+            logger.error(`Replacing subscription to ${this.peer} due to timeout`);
+        }
+
+        // We only arrive here when closed
+        this.#request.closed?.();
+    }
+
+    get interactionModelRevision() {
+        return this.#subscription?.interactionModelRevision ?? Specification.INTERACTION_MODEL_REVISION;
+    }
+
+    get maxInterval() {
+        return this.#subscription?.maxInterval ?? Hours.one;
+    }
+
+    get subscriptionId() {
+        return this.#subscription?.subscriptionId ?? SustainedSubscription.NO_SUBSCRIPTION;
+    }
+}
+
+export namespace SustainedSubscription {
+    /**
+     * Configuration for {@link SustainedSubscription}.
+     */
+    export interface Configuration extends ClientSubscription.Configuration {
+        /**
+         * Function to establish underlying subscription.
+         */
+        subscribe: (request: Subscribe) => Promise<PeerSubscription>;
+
+        /**
+         * The schedule we use for retrying subscription connections.
+         *
+         * We handle reconnection separately at the exchange level.  This retry schedule only applies to establishing a
+         * subscription once we have an active exchange.  Exchange reconnection is handled by lower-level components.
+         */
+        retries: RetrySchedule;
+    }
+
+    export function assert(subscription: SubscribeResponse): asserts subscription is SustainedSubscription {
+        if (!(subscription instanceof SustainedSubscription)) {
+            throw new ImplementationError(`Non-sustained subscription provided where sustained subscription required`);
+        }
+    }
+
+    export const NO_SUBSCRIPTION = -1;
+
+    export const DefaultRetrySchedule: RetrySchedule.Configuration = {
+        // Protocol-level level happens at the exchange level and is faster; this is an application-level retry.  Retry
+        // more slowly so we do not hammer devices that are experiencing transient errors
+        initialInterval: Seconds(15),
+
+        // Similarly, we have an exchange.  If a device repeatedly fails to establish a subscription, give it plenty of
+        // time to recover.  It's even possible our subscription attempt is invalid for some reason, in which case we
+        // an aggressive interval would be particularly bad form
+        maximumInterval: Hours(1),
+
+        // No timeout; we run until aborted
+        timeout: undefined,
+
+        backoffFactor: 2,
+
+        jitterFactor: 0.25,
+    };
+}

package/src/action/client/subscription/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./ClientSubscribe.js";
+export * from "./ClientSubscription.js";
+export * from "./ClientSubscriptionHandler.js";
+export * from "./ClientSubscriptions.js";
+export * from "./PeerSubscription.js";
+export * from "./SustainedSubscription.js";

package/src/action/errors.ts

@@ -10,7 +10,7 @@ import { Status, StatusResponseError } from "#types";
 export { SchemaImplementationError } from "#model";
 
 /**
- * Thrown due operational schema violations.
+ * Thrown due operational schema violation.
  */
 export class SchemaViolationError extends StatusResponseError {
     constructor(prefix: string, path: SchemaErrorPath, message: string, code: Status) {
@@ -80,6 +80,15 @@ export class ConstraintError extends ValidateError {
     }
 }
 
+/**
+ * Thrown when a numeric value can't fit in an integer type.
+ */
+export class IntegerRangeError extends ValidateError {
+    constructor(path: SchemaErrorPath, message: string) {
+        super(path, message, Status.ConstraintError);
+    }
+}
+
 /**
  * Thrown when an enum value is not known based on Matter specification
  */
@@ -107,11 +116,7 @@ export class ConformanceError extends ValidateError {
 /**
  * Thrown when an enum value is not valid based on conformance definitions
  */
-export class EnumValueConformanceError extends ConformanceError {
-    constructor(schema: Schema, path: SchemaErrorPath, message: string) {
-        super(schema, path, message);
-    }
-}
+export class EnumValueConformanceError extends ConformanceError {}
 
 /**
  * Thrown for access attempts against a managed value that is no longer valid.

package/src/action/request/Subscribe.ts

@@ -5,7 +5,7 @@
  */
 
 import type { ReadResult } from "#action/response/ReadResult.js";
-import { CanceledError, Duration, Seconds, TimeoutError, UINT16_MAX } from "#general";
+import { Duration, Seconds, UINT16_MAX } from "#general";
 import { MalformedRequestError } from "./MalformedRequestError.js";
 import { Read } from "./Read.js";
 
@@ -29,7 +29,7 @@ export interface Subscribe extends Read {
     /**
      * Invoked when the subscription is no longer active.
      */
-    closed?: (cause: CanceledError | TimeoutError) => void;
+    closed?: () => void;
 }
 
 export function Subscribe(options: Subscribe.Options, ...selectors: Read.Selector[]): Subscribe {

package/src/action/response/ReadResult.ts

@@ -28,7 +28,7 @@ import type {
  * Iteration occurs in chunks for performance reasons.  A chunk is an iterable of reports, one per output attribute or
  * event.
  */
-export interface ReadResult<Chunk = ReadResult.Chunk> extends AsyncIterable<ReadResult.Chunk> {}
+export interface ReadResult<Chunk = ReadResult.Chunk> extends AsyncIterableIterator<ReadResult.Chunk> {}
 
 export namespace ReadResult {
     export type Chunk = Iterable<Report>;

package/src/action/response/SubscribeResult.ts

@@ -4,10 +4,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { MaybePromise } from "#general";
 import { SubscribeResponse } from "#types";
 
 export type SubscribeResult = Promise<ActiveSubscription>;
 
 export interface ActiveSubscription extends SubscribeResponse {
-    close(): void;
+    close(): MaybePromise<void>;
 }

package/src/action/server/ServerInteraction.ts

@@ -65,11 +65,6 @@ export class ServerInteraction<SessionT extends InteractionSession = Interaction
         throw new NotImplementedError();
     }
 
-    cancelSubscription(_id: number): void {
-        // TODO
-        throw new NotImplementedError();
-    }
-
     write<T extends Write>(request: T, session: SessionT): WriteResult<T> {
         // TODO - validate request
 

package/src/bdx/flow/InboundFlow.ts

@@ -34,7 +34,7 @@ export abstract class InboundFlow extends Flow {
         // Method to be used by main close() method to make sure all streams are correctly closed or cancelled
         this.#closeStreams = async (error?: unknown) => {
             if (writeController !== undefined) {
-                if (error != undefined) {
+                if (error !== undefined) {
                     // When this is called, we are either done successfully or failed, error the write controller in error case
                     writeController.error(error);
                     try {

package/src/interaction/SubscriptionClient.ts

@@ -4,7 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Duration, Environment, Environmental, Logger, MaybePromise, Millis, Time, Timer } from "#general";
+import type { ClientSubscriptionHandler } from "#action/client/subscription/ClientSubscriptionHandler.js";
+import { Duration, Logger, MaybePromise, Millis, Time, Timer } from "#general";
 import { DecodedDataReport } from "#interaction/DecodedDataReport.js";
 import { MessageExchange } from "#protocol/MessageExchange.js";
 import { ProtocolHandler } from "#protocol/ProtocolHandler.js";
@@ -25,6 +26,8 @@ export interface RegisteredSubscription {
  * A simple protocol handler that handles exchanges starting with data reports.
  *
  * Incoming data reports must match to a subscription registered with {@link add} or the exchange is invalid.
+ *
+ * @deprecated new code uses {@link ClientSubscriptionHandler}
  */
 export class SubscriptionClient implements ProtocolHandler {
     readonly id = INTERACTION_PROTOCOL_ID;
@@ -32,14 +35,6 @@ export class SubscriptionClient implements ProtocolHandler {
     readonly #listeners = new Map<number, (dataReport: DecodedDataReport) => MaybePromise<void>>();
     readonly #timeouts = new Map<number, Timer>();
 
-    constructor() {}
-
-    static [Environmental.create](env: Environment) {
-        const client = new SubscriptionClient();
-        env.set(SubscriptionClient, client);
-        return client;
-    }
-
     /**
      * Register a subscription.
      */

package/src/protocol/MessageExchange.ts

@@ -687,7 +687,7 @@ export class MessageExchange {
     }
 
     get via() {
-        if (this.session == undefined || !this.session.isSecure) {
+        if (this.session === undefined || !this.session.isSecure) {
             return this.channel.name; // already formatted as "via"
         }