/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import type { MRP } from "#protocol/MRP.js"; import { Duration, Environment, Environmental, MatterError, Semaphore } from "@matter/general"; import { Peer } from "./Peer.js"; /** * Thrown when a named network profile does not exist. */ export declare class UnknownNetworkProfileError extends MatterError { } export interface ConcreteNetworkProfile { /** * The ID of the NetworkProfile used to register with {@link NetworkProfiles}. */ id: string; /** * A {@link Semaphore} that limits communications for this particular profile. */ semaphore: Semaphore; /** * Additive margin applied to MRP retransmission backoff for exchanges on this profile. * * Compensates for network latency not reflected in the peer's advertised SAI/SII. Combined * with the local "own" profile margin via max at send time. */ additionalMrpDelay: Duration; /** * The additive MRP margins for this profile, by traffic class. * * Precomputed because it is read on the send path; {@link MRP.Margins.bdx} is {@link additionalMrpDelay} unless * the medium needs bulk transfer paced differently from normal messaging. */ mrpMargins: MRP.Margins; } /** * A single logical Matter networking segment. * * A "network profile" is a logical grouping of nodes that share rate limits. By default matter.js selects a network * based on medium, falling back to {@link NetworkProfiles.conservative} if the medium is unknown. * * TODO - record latency and packet loss to support dynamic rate limits */ export interface NetworkProfile extends ConcreteNetworkProfile { /** * An additional profile that applies only to the establishment of new CASE sessions. */ connect?: ConcreteNetworkProfile; /** * An additional profile that applies only to address probe reads. */ probeAddress?: ConcreteNetworkProfile; } /** * Controls how we interact with peers based on the network in which the peer resides. */ export declare class NetworkProfiles { #private; constructor(options?: NetworkProfiles.Options); set defaults(options: NetworkProfiles.PartialOptions); static [Environmental.create](env: Environment): NetworkProfiles; select(peer: Peer, id?: string): NetworkProfile; /** * Retrieve the named network profile. * * @param id one of the standard {@link NetworkProfiles.Templates} or any previously configured identifier */ get(id: string): NetworkProfile; configure(id: string, limits: NetworkProfiles.Limits, parentDelay?: Duration): NetworkProfile; forPeer(peer: Peer): NetworkProfile; } export declare namespace NetworkProfiles { interface Options extends Partial { } /** * Like {@link Options} but allows partially specifying individual profiles, including nested connect limits. */ type PartialOptions = { [K in keyof Templates]?: Partial> & { connect?: Partial; probeAddress?: Partial; }; }; interface ConcreteLimits { /** * Maximum number of concurrent exchanges. */ exchanges: number; /** * Delay between new exchanges. */ delay?: Duration; /** * Maximum timeout for one exchange before trying the next in any case. */ timeout?: Duration; /** * Additive MRP retransmission margin for this medium. Defaults to 0 unless the template sets one. */ additionalMrpDelay?: Duration; } /** * Parameters that control exchange throttling for a specific medium. */ interface Limits extends ConcreteLimits { /** * {@link additionalMrpDelay} for bulk transfer (BDX) exchanges, which sustain many round trips over one path. * * Defaults to {@link additionalMrpDelay}. Values above roughly 7s are inert: a BDX retransmission interval is * capped so the whole schedule fits the peer's response budget. */ bdxAdditionalMrpDelay?: Duration; /** * Overrides specifically for establishing new sessions. * * If present, any values here act as limits specifically for CASE session establishment. */ connect?: ConcreteLimits; /** * Overrides specifically for address probe reads. * * If present, any values here act as limits specifically for probing peer addresses. */ probeAddress?: ConcreteLimits; } /** * Standard profiles, selected automatically based on transfer medium. */ interface Templates { /** * Limit for "fast" networks. * * We use this value for ethernet. */ fast: Limits; /** * Limit for WiFi networks. * * Matches {@link fast} concurrency but adds an MRP retransmission margin: WiFi power-save can delay delivery * beyond the peer's advertised SAI/SII, and retransmitting too eagerly wastes airtime. */ wifi: Limits; /** * Limit for thread networks, by channel. * * Each channel has a separate network, plus an additional one for devices that do not report their channel. * If the device indicates thread is disabled then we use {@link fast}. */ thread: Limits; /** * Conservative limits used as the base for constrained networks. */ conservative: Limits; /** * Limits for peers with unknown physical properties. * * Defaults to {@link conservative}. Note that this template is automatically overwritten at startup for * device nodes based on the node's network capabilities. Manually setting this may have no effect. To * adjust limits, override {@link fast}, {@link thread} or {@link conservative} instead. */ unknown: Limits; /** * Limit for "unlimited" networks. * * Interactions only use this profile if you specify explicitly. */ unlimited: Limits; /** * Priority profile for interactions with an await-mode (LIT) ICD. * * Applies no concurrency throttle, so a check-in-triggered interaction is not queued behind bulk traffic and * can land inside the peer's brief active window. MRP timing is unaffected: it derives from the peer's medium * profile, so selecting this profile swaps only the throttle semaphore. */ icdLit: Limits; } /** * The fallback used for unknown network IDs or mediums. */ const conservative: Limits; const defaults: Templates; } //# sourceMappingURL=NetworkProfile.d.ts.map