/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import type { ExchangeManager } from "#protocol/ExchangeManager.js"; import type { MessageExchange } from "#protocol/MessageExchange.js"; import type { NodeSession } from "#session/NodeSession.js"; import type { Session } from "#session/Session.js"; import type { SessionManager } from "#session/SessionManager.js"; import { Bytes, Channel, ChannelType, Duration, Lifetime, Observable, ServerAddressIp, ServerAddressUdp } from "@matter/general"; import { NetworkProfile, NetworkProfiles } from "./NetworkProfile.js"; import type { Peer } from "./Peer.js"; import { PeerTimingParameters } from "./PeerTimingParameters.js"; /** * Identifies who triggered an MRP exchange restart kick. * * - `"discover"` — triggered by DNS-SD address discovery (mDNS resolution completed) * - `"connect"` — triggered explicitly via `peer.kick()` or `Peer.ConnectOptions.kick` */ export type KickOrigin = "discover" | "connect"; /** * Establishes a CASE session with a peer. * * Returns a session or undefined if aborted. * * Logic is as follows: * * - The last address we connected to is considered a "fallback" address * * - Other "discovered" addresses may be known via DNS-SD discovery * * - Discovery occurs via {@link Peer#service}; this is active if there are no discovered or connectable addresses and * passive if there are discovered addresses * * - If there is a fallback address but no discovered addresses, either because discovery has not completed or because * all discovered addresses have expired, we attempt to connect to the fallback address * * - If there are no discovered addresses, we trigger active solicitation of new addresses * * - If there are discovered addresses, attempts to connect to each discovered address in order of priority as defined * by {@link ServerAddressSet.compareDesirability}, with a configurable delay between attempts * * - The connection to the fallback address aborts if the fallback address is not discovered * * - Attempts continue until the address expires or connects successfully * * - Each address sends Sigma1 by its {@link InitialContactSchedule}: MRP retransmits one Sigma1 with a configurable * max delay between messages, and after a while continues with fresh Sigma1 messages on new exchanges * * - Starting a new attempt does not cancel previously running attempts; we thus rely on the MRP backoff of each * schedule to ensure we are sending a reasonable number of packets * * - Once a session is established, any outstanding attempts abort and the function returns * * - We use various hardcoded timeouts (see above) in response to exceptions during connection attempts. The idea is to * recover from transient errors without being too aggressive */ export declare function PeerConnection(peer: Peer, context: PeerConnection.Context, options?: PeerConnection.Options): Promise; export declare namespace PeerConnection { interface Context extends Lifetime.Owner { sessions: SessionManager; exchanges: ExchangeManager; networks: NetworkProfiles; /** * Open byte channel to a specific address. */ openSocket(address: ServerAddressIp, abort: AbortSignal): Promise | undefined>; timing: PeerTimingParameters; /** * Optional hook to customize error handling during connection attempts. * * Invoked for errors that would result in a delay-and-retry (not for Busy, resumption-clearing, or a Sigma1 that * is never acknowledged and is replaced by a fresh one). If the hook returns a {@link Duration}, that overrides * the default delay. If it returns undefined, the default delay is used. If it throws, the connection is aborted * with the thrown error as a fatal error. */ handleError?: (error: Error) => Duration | void; } interface Options { abort?: AbortSignal; network?: string; /** * Per-call override for the peer-medium MRP retransmission margin. When omitted the margin derives from * the peer's network medium, independent of any {@link network} throttle override. */ additionalMrpDelay?: Duration; kicker?: Observable<[KickOrigin]>; /** See {@link Peer.ConnectOptions.requiredTransport}. */ requiredTransport?: ChannelType; /** See {@link Peer.ConnectOptions.preferredTransport}. */ preferredTransport?: ChannelType; /** * Per-call overrides for timing parameters. * * Merged on top of the global {@link PeerConnection.Context.timing} for this connection only. * Other concurrent or future connections are not affected. */ timing?: Partial; /** * Per-call error handler, overrides {@link Context.handleError} for this connection only. */ handleError?: (error: Error) => Duration | void; } interface ExchangeOptions { /** MRP backoff addition for the peer's medium. */ peerAdditionalMrpDelay?: Duration; /** Default: the secure channel protocol. */ protocol?: number; /** Destination for this exchange's messages instead of the session's address. */ addressOverride?: ServerAddressUdp; /** Notified of the exchange's messages after the peer's own bookkeeping. */ observer?: Pick; } function createExchange(peer: Peer, exchanges: ExchangeManager, session: Session, network: NetworkProfile, options?: ExchangeOptions): MessageExchange; } //# sourceMappingURL=PeerConnection.d.ts.map