/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import type { SustainedClientSubscribe } from "#action/client/subscription/ClientSubscribe.js"; import { Read } from "#action/request/Read.js"; import { Subscribe } from "#action/request/Subscribe.js"; import { EventNumberTracker } from "#action/response/EventNumberTracker.js"; import { ReadResult } from "#action/response/ReadResult.js"; import type { ActiveSubscription } from "#action/response/SubscribeResult.js"; import type { IcdPeerWakefulness } from "#icd/IcdPeerWakefulness.js"; import type { ExchangeLogContext } from "#protocol/MessageExchange.js"; import { AbortedError, asError, AsyncObservableValue, causedBy, Diagnostic, Duration, Hours, ImplementationError, Logger, MatterAggregateError, Observable, Observer, RetrySchedule, Seconds, Time, } from "@matter/general"; import { type EventNumber, type NodeId, SubscribeResponse } from "@matter/types"; 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. * * When a peer is a LIT (Long Idle Time) ICD operating in await mode, the subscription instead parks on the peer's wake * signal (a Check-In or any message from the peer) and (re)subscribes only when the peer becomes awake. Wakefulness * is read live via the {@link SustainedSubscription.Configuration#wakefulness} provider, so a peer registered after * construction is honored on the loop's next iteration. A runtime SIT⇄LIT operating-mode flip recreates the * subscription so its intervals are renegotiated for the new mode. * * Each replacement subscription requests only events above {@link maxEventNumber}. When our own processing of a * report fails, the failure is logged, the events pulled from the report before the failure count as seen and the * subscription continues. * * 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 { /** Bounded retry interval used only on the degraded path where a once-LIT peer no longer requires await. */ static readonly SIT_RETRY_INTERVAL = Seconds(15); #request: SustainedClientSubscribe; #subscription?: ActiveSubscription; #retries: RetrySchedule; #subscribe: (request: Subscribe, abort: AbortSignal) => Promise; #read: (request: Read, abort: AbortSignal, logContext?: ExchangeLogContext) => ReadResult; #probe: (abort: AbortSignal) => Promise; #wakefulness?: () => IcdPeerWakefulness | undefined; #peerFed?: () => Observable<[NodeId]> | undefined; #subscriptionHold?: Disposable; #active = AsyncObservableValue(false); #inactive = AsyncObservableValue(true); #maxEventNumber?: EventNumber; #localFailureLogged = false; constructor(config: SustainedSubscription.Configuration) { super(config); const { request, read, probe, retries, subscribe, wakefulness, peerFed } = config; this.#request = request; this.#retries = retries; this.#subscribe = subscribe; this.#read = read; this.#probe = probe; this.#wakefulness = wakefulness; this.#peerFed = peerFed; this.done = this.#run(); } /** * Emits when the active state changes. */ get active() { return this.#active; } /** * Emits when inactive state changes. */ get inactive() { return this.#inactive; } /** * The highest event number of the results this subscription processed, or undefined before the first event. An * event counts once {@link SustainedClientSubscribe.updated} pulled it and settled for its result. The number * never decreases. Until it is set, requests carry the `eventFilters` the request and its `refreshRequest` give. * * @see {@link MatterSpecification.v161.Core} § 8.9.3.1 */ get maxEventNumber() { return this.#maxEventNumber; } async #run() { // Do we trust the session to work? Initially yes let sessionTrusted = true; const consumer = this.#request.updated?.bind(this.#request); const updated = consumer && ((result: ReadResult) => this.#deliver(result, consumer)); let { bootstrapWithRead } = this.#request; const { refreshRequest } = this.#request; const refresh = (request: SustainedClientSubscribe) => this.#requestNewEvents(refreshRequest === undefined ? request : refreshRequest(request)); let needToRefreshRequest = false; // After a failed send to an await-mode LIT peer we must wait for a fresh wake signal rather than retry within // the current awake window, which would hammer a peer that has likely already gone back to sleep. let awaitFreshSignal = false; // A mode-flip recreate is time-critical: it must land inside the peer's brief active window. Carry a one-shot // flag so the recreate's subscribe bypasses the per-network throttle rather than queuing behind it. let recreateWithPriorityNetwork = false; const priorityNetwork = "icdLit"; try { while (true) { // Create a request and promise that will inform us when the underlying subscription closes let request: SustainedClientSubscribe = { ...this.#request, updated }; if (recreateWithPriorityNetwork) { request.network = priorityNetwork; recreateWithPriorityNetwork = false; } else if (request.network === undefined && this.#wakefulness?.()?.requiresAwait) { // Live each iteration, not captured at subscribe, so a peer that became LIT at runtime is // prioritized on its next park-resume too, not only on the mode-flip recreate above. request.network = priorityNetwork; } const closed = new Promise(resolve => { request.closed = () => { this.#subscription = undefined; this.subscriptionId = ClientSubscription.NO_SUBSCRIPTION; this.#releaseSubscriptionHold(); sessionTrusted = false; resolve(); }; }); // Reconcile each iteration so a peer registered after construction, or flipped SIT⇄LIT, is honored // live. const wakefulnessBefore = this.#wakefulness?.(); if (wakefulnessBefore?.requiresAwait) { // Gate on #isNotLive: on the initial park this await must be skipped, else the added microtask would // let a synchronous wake signal race ahead of the observer registration below. if (awaitFreshSignal) { if (!this.#isNotLive) { await this.#setLive(false); } await this.#nextWake(wakefulnessBefore); awaitFreshSignal = false; } else if (!wakefulnessBefore.awake.value) { if (!this.#isNotLive) { await this.#setLive(false); } // Re-check after the #setLive await: a wake that landed during it is the edge we would // park for, and #awaitAwake's observer only fires on the *next* emit, so skip the park. if (!wakefulnessBefore.awake.value) { await this.#awaitAwake(wakefulnessBefore); } } if (this.abort.aborted) { break; } } else { if (!sessionTrusted) { if (!(await this.#probe(this.abort))) { if (!this.abort.aborted) { // Probing failed, so we get a new session anyway sessionTrusted = true; logger.info( `Failed to probe reachability of peer ${this.peer}, resubscribe with new session`, ); } } if (this.abort.aborted) { return; } } } // Subscribe for (const retry of this.#retries) { try { if (needToRefreshRequest) { request = refresh(request); } needToRefreshRequest = true; // We do a read or subscription request now, so we might have got data, even partial if (bootstrapWithRead) { const response = this.#read(request, this.abort, Diagnostic.asFlags({ bootstrap: true })); if (request.updated) { await request.updated(response); } else { for await (const _chunk of response); } if (this.abort.aborted) { return; } bootstrapWithRead = false; request = refresh(request); } const subscription = await this.#subscribe(request, this.abort); this.#subscription = subscription; this.subscriptionId = subscription.subscriptionId; this.#releaseSubscriptionHold(); this.#subscriptionHold = this.#wakefulness?.()?.holdSubscription(); sessionTrusted = true; break; } catch (e) { if (!causedBy(e, AbortedError) || !this.abort.aborted) { // Subscription failed not by timeout but because could not be established, so we have a new session anyway sessionTrusted = true; } if (this.abort.aborted) { return; } // A mode-flip recreate whose subscribe failed is about to park/retry with no subscription held. if (!this.#isNotLive) { await this.#setLive(false); } // An await-mode LIT peer has no timed retry: park for the next fresh wake signal instead. if (this.#wakefulness?.()?.requiresAwait) { if (!causedBy(e, AbortedError)) { logger.info( `Failed to establish subscription to LIT peer ${this.peer}, parking until it wakes:`, Diagnostic.errorMessage(asError(e)), ); } awaitFreshSignal = true; break; } logger.info( `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; } } } if (this.abort.aborted) { break; } // A LIT park-failure exits the retry loop without a subscription; loop back to await the next wake // signal. if (awaitFreshSignal) { continue; } await this.#setLive(true); if (this.abort.aborted) { break; } const modeFlipped = await this.#awaitClosedOrModeFlip(closed); if (!modeFlipped) { // Genuine loss: report not-live so consumers re-establish. A deliberate mode-flip recreate keeps // active until it either re-establishes (no-op, no churn) or has to park/retry (reported there). await this.#setLive(false); } // If aborted, then we're done if (this.abort.aborted) { break; } if (modeFlipped) { const subscription = this.#subscription; this.#subscription = undefined; this.subscriptionId = ClientSubscription.NO_SUBSCRIPTION; this.#releaseSubscriptionHold(); // We tear this down deliberately; the CASE session is untouched, so keep it trusted and // re-subscribe without a probe. Detach the closed callback so its async fire cannot route this // deliberate close back through the loss handler and flip sessionTrusted. request.closed = undefined; sessionTrusted = true; if (subscription !== undefined) { await subscription.close(); } logger.info(`Recreating subscription to ${this.peer} after ICD operating mode change`); recreateWithPriorityNetwork = true; continue; } logger.info(`Replacing subscription to ${this.peer} after loss`); } } finally { const subscription = this.#subscription; this.#subscription = undefined; if (subscription !== undefined) { this.subscriptionId = ClientSubscription.NO_SUBSCRIPTION; this.#releaseSubscriptionHold(); await subscription.close(); } // Every exit, including an abort or observer failure while going live, leaves us not live. try { await this.#setLive(false); } catch (e) { // Logged, not thrown: this finally must not replace the outcome #run is already returning or throwing logger.warn(`Observer failed while ${this.peer} subscription stopped:`, e); } } } async #deliver(result: ReadResult, consumer: (result: ReadResult) => Promise) { const eventNumbers = new EventNumberTracker(); const report = new PeerReport(result); try { await consumer(eventNumbers.observe(report.read())); } catch (error) { if (report.failed) { throw error; } this.#logLocalFailure("Processing a report", error); } finally { await this.#raiseMaxEventNumber(eventNumbers.value); } } async #raiseMaxEventNumber(number: EventNumber | undefined) { if (number === undefined || (this.#maxEventNumber !== undefined && number <= this.#maxEventNumber)) { return; } this.#maxEventNumber = number; try { await this.#request.maxEventNumberChanged?.(number); } catch (error) { this.#logLocalFailure("Handling the event number of a report", error); } } /** * A peer can trigger a failure of our own processing with every report, so only the first one is a warning. */ #logLocalFailure(what: string, error: unknown) { const message = `${what} from ${this.peer} failed; the subscription continues:`; if (this.#localFailureLogged) { logger.debug(message, error); return; } this.#localFailureLogged = true; logger.warn(message, error); } #requestNewEvents(request: SustainedClientSubscribe): SustainedClientSubscribe { if (this.#maxEventNumber === undefined) { return request; } return { ...request, eventFilters: [{ eventMin: this.#maxEventNumber + 1n }] }; } /** True when {@link active} and {@link inactive} both report not live. */ get #isNotLive() { return !this.#active.value && !!this.#inactive.value; } /** * Update {@link active} and {@link inactive} together. An observable stores its new value before its observers * run, so an observer that throws does not undo that value. * * Going live emits both values even if already live, so a re-established subscription is announced again. It * stops at the first observer failure or when the subscription was closed meanwhile; #run then ends, and its * finally goes back to not live. * * Going not live emits only the values that change, and attempts both even if an observer fails. * * Observer failures are rethrown after the update, as one error or as a {@link MatterAggregateError}. */ async #setLive(live: boolean) { const errors = new Array(); if (live) { const steps: [AsyncObservableValue, boolean][] = [ [this.#inactive, false], [this.#active, true], ]; for (const [observable, value] of steps) { if (errors.length || this.abort.aborted) { break; } try { await observable.emit(value); } catch (e) { errors.push(e); } } } else { const steps: [AsyncObservableValue, boolean][] = [ [this.#active, false], [this.#inactive, true], ]; for (const [observable, value] of steps) { if (observable.value === value) { continue; } try { await observable.emit(value); } catch (e) { errors.push(e); } } } if (errors.length === 1) { throw errors[0]; } if (errors.length) { throw new MatterAggregateError( errors, `Observers failed while ${this.peer} subscription went ${live ? "live" : "not live"}`, ); } } #releaseSubscriptionHold() { this.#subscriptionHold?.[Symbol.dispose](); this.#subscriptionHold = undefined; } /** * Wait until the active subscription closes or the peer flips operating mode (SIT⇄LIT) at runtime, whichever * comes first, or until we abort. Returns true only when a mode flip won the race, signalling the caller to * recreate the subscription for the new mode. */ async #awaitClosedOrModeFlip(closed: Promise): Promise { const wakefulness = this.#wakefulness?.(); if (wakefulness === undefined) { // No wakefulness: the peer is not registered. Race the feed signal so a registration is not missed until a // later loss. const peerFed = this.#peerFed?.(); if (peerFed === undefined) { await this.abort.race(closed); return false; } let fed = false; let observer: Observer<[NodeId]> | undefined; const feed = new Promise(resolve => { observer = nodeId => { if (nodeId === this.peer.nodeId) { fed = true; resolve(); } }; peerFed.on(observer); }); try { await this.abort.race(Promise.race([closed, feed])); } finally { if (observer !== undefined) { peerFed.off(observer); } } return fed && !this.abort.aborted; } let flipped = false; let observer: Observer<[boolean]> | undefined; const flip = new Promise(resolve => { observer = () => { flipped = true; resolve(); }; wakefulness.operatingModeChanged.on(observer); }); try { await this.abort.race(Promise.race([closed, flip])); } finally { if (observer !== undefined) { wakefulness.operatingModeChanged.off(observer); } } return flipped && !this.abort.aborted; } /** * Resolve on the peer's next awake transition to true (a genuinely fresh wake signal), or when the subscription * aborts. Uses {@link Abort.race} so an already-aborted signal resolves immediately rather than stranding on an * awake edge that may never come (the peer is asleep). */ async #awaitAwake(wakefulness: IcdPeerWakefulness): Promise { let observer: Observer<[boolean]> | undefined; const awake = new Promise(resolve => { observer = value => { if (value) { resolve(); } }; wakefulness.awake.on(observer); }); try { await this.abort.race(awake); } finally { if (observer) { wakefulness.awake.off(observer); } } } /** * Resume after a failed send to an await-mode LIT peer by parking for the next wake signal. A peer no longer * requiring await (e.g. a runtime DSLS LIT→SIT flip) has no wake signal to park for, so it resumes after a * bounded delay instead of stranding on an awake edge that will never re-emit. */ async #nextWake(wakefulness: IcdPeerWakefulness): Promise { if (!wakefulness.requiresAwait) { const retry = Time.sleep("icd sit retry", SustainedSubscription.SIT_RETRY_INTERVAL); try { await this.abort.race(retry); } finally { retry.cancel(); } return; } await this.#awaitAwake(wakefulness); } get interactionModelRevision() { return this.#subscription?.interactionModelRevision; } get maxInterval() { return this.#subscription?.maxInterval ?? Seconds.of(Hours.one); } } export namespace SustainedSubscription { /** * Configuration for {@link SustainedSubscription}. */ export interface Configuration extends Omit { request: SustainedClientSubscribe; /** * Function to establish underlying subscription. */ subscribe: (request: Subscribe, abort: AbortSignal) => Promise; /** * Performs bootstrap read. */ read: (request: Read, abort: AbortSignal) => ReadResult; /** * Probe the peer with an empty read to verify session liveness. */ probe: (abort: AbortSignal) => Promise; /** * 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; /** * Live provider of the peer's {@link IcdPeerWakefulness}. Read on each loop decision so a peer registered after * construction, or flipped SIT⇄LIT at runtime, is honored on the next iteration. When it * returns a wakefulness in await mode (`requiresAwait`), the subscription parks on the wake signal instead of * probing/retrying; otherwise behavior is identical to a non-ICD sustained subscription. */ wakefulness?: () => IcdPeerWakefulness | undefined; /** * Live provider of the fabric ICD registry's "peer fed" signal, emitting the peer node ID whenever a peer's * registration starts. A subscription running without a wakefulness has no mode flip to observe, so it races * this signal and recreates through the normal mode-flip path once the peer is registered. */ peerFed?: () => Observable<[NodeId]> | undefined; } 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 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, }; } /** * A report as received from the peer, noting whether receiving or decoding it failed as opposed to processing it. */ class PeerReport { #result: ReadResult; failed = false; constructor(result: ReadResult) { this.#result = result; } async *read(): ReadResult { try { for await (const chunk of this.#result) { yield Symbol.iterator in chunk ? this.#readReports(chunk) : this.#readReportsAsync(chunk); } } catch (error) { this.failed = true; throw error; } } *#readReports(reports: Iterable) { try { yield* reports; } catch (error) { this.failed = true; throw error; } } async *#readReportsAsync(reports: AsyncIterable) { try { yield* reports; } catch (error) { this.failed = true; throw error; } } }