refactor(iroh)!: redesign path observation API

[Frando]

Depends on n0-computer/noq#617
Based on #4229

This replaces the current PathWatcher with a new combination of primitives.

• Connection::paths returns PathList<'conn>, a list of the currently-open paths. Iteration yields Path<'conn> with access to the remote address, selection state, and path stats. The PathList is a snapshot in time (ie., once returned from Connection::paths won't change for changes in the path list). It is also lifetime-bound to the Connection (which gives us unconditional access to path stats right out of the noq state).
• Connection::path_events() returns a PathEventStream of path events. This stream is lifetime-free, can be sent to other tasks, and does not keep the Connection alive. The subscription is registered immediately at call time so pairing it with a subsequent paths() read produces a race-free check-then-wait loop.
• Connection::path_updates returns a stream that yields PathList<'conn> whenever the path list changes (ie. on path open/close or selection change)

PathEvent has four variants: Opened, Closed (with last_stats inline), Selected, and a Lagged (with the missed count) to account for the (rare) case of a broadcast stream lag.

Closed paths are no longer retained in Paths. Consumers that need totals over the connection's lifetime accumulate from PathEvent:: Closed; the transfer.rs example's spawn_stats_collector demonstrates this pattern.

Internally, the path store splits into two handles sharing an Mutex<State>, containing a SmallVec of (PathId, TransportAddr) plus the selected path id. PathStateSender, owned by the RemoteStateActor, is the sole mutator and holds the broadcast Sender. PathStateReceiver, held by the Connection, reads via ArcSwap and subscribes via a WeakSender. When the ConnectionState is dropped, the broadcast Sender is dropped with it and outstanding event streams end naturally; new subscriptions on a closed connection where the remote state actor already dropped its state then yield an already-closed stream.

Final per-path statistics now come from noq::Closed::path_stats at connection close time, via n0-computer/noq#617.

Breaking Changes

• removed: iroh::endpoint::PathWatcher, iroh::endpoint::PathInfo, iroh::endpoint::PathInfoList, iroh::endpoint::PathInfoListIter.
• changed: Connection::paths returns PathList<'_> instead of PathWatcher. Path<'_> replaces PathInfo; Path::stats is now infallible
• changed: ConnectionInfo::paths is removed in favour of ConnectionInfo::path_events. ConnectionInfo::selected_path now returns Option<TransportAddr> instead of Option<PathInfo>.
• added: iroh::endpoint::Path, iroh::endpoint::Paths, iroh::endpoint::PathEvent (with Opened, Closed, Selected, Lagged variants), iroh::endpoint::PathEventStream, Connection::path_events, ConnectionInfo::path_events.

Change checklist

• Self-review.
• Documentation updates following the style guide.
• Tests updated.
• All breaking changes documented.

[github-actions]

Documentation for this PR has been generated and is available at: https://n0-computer.github.io/iroh/pr/4188/docs/iroh/

Last updated: 2026-05-05T13:40:21Z

[github-actions]

Netsim report & logs for this PR have been generated and is available at: LOGS
This report will remain available for 3 days.

Last updated for commit: 0c083d0

[dignifiedquire]

what exactly does this mean?