feat(iroh)!: Configurable path selection by rklaehn · Pull Request #4232 · n0-computer/iroh

rklaehn · 2026-05-05T16:08:42Z

Description

An attempt to make path selection more flexible for complex custom transport use cases.

Path selection is now via a dynable trait PathSelector. The only fn select takes a PathSelectionContext that has the current path as well as a way to iterate over a flat list of PathSelectionData structs.

PathSelectionData currently just has the address and the stats, but in the future could be extended to contain more detailed information such as the congestion controller metrics noq_proto::ControllerMetrics etc. I think cc metrics would be quite helpful to make good decisions about path selection.

select returns a PathSelection struct that is at this time a newtype over an Option. add is first writer wins, all subsequent calls will ignore the addr and emit a warning. But we can change this in the future to allow multiple addrs.

The entire mechanism is only pub under the unstable-custom-transports flag, so we can change it in the future. But there are some additive changes we could do without breakage. For example we could allow PathSelection to also keep track of paths to be closed.

Breaking Changes

Removes some public methods on the endpoint builder that are too opinionated if you want to make path selection fully generic:

endpoint::Builder::transport_bias(kind, bias): removed
endpoint::transports::TransportBias: removed

And some changes involving the unstable_custom_transport API.

Notes & open questions

Note: the new signature tries to anticipate that in the future we might want to select multiple transports, but as of now it will just ignore these.

Change checklist

github-actions · 2026-05-06T07:23:53Z

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

Last updated: 2026-05-06T10:15:36Z

github-actions · 2026-05-06T07:25:19Z

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: 11eceea

…ection

rklaehn · 2026-05-06T09:20:48Z

@mcginty could you take a look at this? The current path selection is a bit limited especially once you have custom transports, but really also if you have more complex scenarios involving just ip and relay transports.

This is my attempt to make the selection API more flexible.

Frando · 2026-05-06T10:24:22Z

-        // Apply our new path
-        if let Some((addr, rtt)) = selected_path {
+        // Apply the selector's primary path.  Multi-path selection is not yet
+        // supported on the lifecycle side; only the primary is honoured.


The comment sounds a bit weird with "lifecycle side", let's just say we only support a single selected path atm.

Frando · 2026-05-06T10:25:08Z

+/// has chosen.  When iroh wants to make this configurable per non-relay transport, this
+/// will move to a method on [`PathSelector`] with a default body that matches the rule
+/// here.
+fn path_status_for(addr: &transports::Addr) -> noq_proto::PathStatus {


I still think this is the wrong logic, see #4233

Frando · 2026-05-06T10:25:36Z

+
+#[cfg_attr(not(feature = "unstable-custom-transports"), allow(unreachable_pub))]
+impl<'a> PathSelectionContext<'a> {
+    /// Module-private — only `select_path` in this file builds one, and the parameter


Remove the comment, we never do comments like this

Frando · 2026-05-06T10:26:05Z

+    }
+
+    /// The path currently considered the preferred path to the remote endpoint, if any.
+    pub fn current(&self) -> Option<&'a transports::Addr> {


Maybe call this previous? not sure, current works too I guess.

Frando · 2026-05-06T10:30:30Z

+    ///
+    /// The same address may appear more than once when it is a path on multiple
+    /// connections to the remote.  Selectors that care should aggregate as appropriate.
+    pub fn paths(&self) -> impl Iterator<Item = PathSelectionData<'a>> + '_ {


So this iterates over all connections, then over all paths, and yield PathSelectionData for each. This is a bit weird, you can get the same path multiple times with different stats but no further details. Maybe we should just deduplicate and take the min RTT among all path stats for a transport addr?

Frando · 2026-05-06T10:31:18Z

+#[cfg_attr(not(feature = "unstable-custom-transports"), allow(unreachable_pub))]
+impl<'a> PathSelectionData<'a> {
+    /// The address of the candidate path.
+    pub fn addr(&self) -> &'a transports::Addr {


We usually expose this as TransportAddr but then we'd have to clone, so it's fine I think.

Frando · 2026-05-06T10:31:28Z

+    }
+}
+
+impl std::fmt::Debug for PathSelectionData<'_> {


use derive_more::Debug

Frando · 2026-05-06T10:32:28Z

+        self.addr
+    }
+
+    /// QUIC path statistics: rtt, cwnd, loss, mtu, etc.


Let's not have this list of abbreviations there, instead link to [PathStats]

Frando · 2026-05-06T10:33:31Z

+/// in real networks is non-trivial.
+#[cfg_attr(not(feature = "unstable-custom-transports"), allow(unreachable_pub))]
+pub trait PathSelector: Send + Sync + std::fmt::Debug + 'static {
+    /// Picks a path among the candidates known for a remote endpoint.


"Pick the selected path to carry application data among the currently open network paths to the remote endpoint"

Frando · 2026-05-06T10:34:08Z

+
+/// The set of paths a [`PathSelector`] has chosen.
+///
+/// Today this holds at most one path.  Build via [`PathSelection::default`] +


"Currently only one path is supported. Additional paths will be ignored and emit a warn log" or such.

Frando · 2026-05-06T10:34:51Z

+    }
+
+    /// All paths in this selection (today: 0 or 1).
+    #[allow(dead_code)] // only reached via the public re-export behind the unstable feature


Remove dead code, and use allow(unreachable_pub) or gate the dead_code with cfg_attr

Frando · 2026-05-06T10:35:14Z

+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+enum TransportType {
+    /// A primary path: used whenever available.
+    Primary = 0,


Why the manual discriminators?

Frando · 2026-05-06T10:36:04Z

+        let mut best: Option<(&Addr, (TransportType, i128))> = None;
+        let mut current_key: Option<(TransportType, i128)> = None;
+
+        for psd in ctx.paths() {


What is psd, why not path

Frando · 2026-05-06T10:37:41Z

+    not(feature = "unstable-custom-transports"),
+    allow(unreachable_pub, unused_imports)
+)]
+pub use self::remote_state::{


Maybe do a pub use .. gated behind the feature flag and a use .. gated behind not(feature) instead, would be more explicit IMO

Frando · 2026-05-06T10:38:27Z

            hooks: Default::default(),
-            transport_bias: Default::default(),
+            path_selector: Arc::new(
+                crate::socket::biased_rtt_path_selector::BiasedRttPathSelector::default(),


import instead of full path at call site

Frando

I like it. This is cleaner and more extensible than the previous transport bias solution. Some comments inline, mostly nits.

rklaehn added 2 commits May 5, 2026 15:43

Remove the default path selector from the public api.

3e44d6b

Add the possibility to select multiple paths.

91ec1d1

n0bot Bot added this to iroh May 5, 2026

github-project-automation Bot moved this to 🚑 Needs Triage in iroh May 5, 2026

Merge branch 'main' into configurable-path-selection

4943844

rklaehn added 4 commits May 6, 2026 12:01

Avoid allocations for select_path

50e580e

Merge remote-tracking branch 'origin/main' into configurable-path-sel…

38d6a99

…ection

fmt

c205edd

Require an Arc<dyn PathSelector> in the builder.

4f718e4

rklaehn requested a review from Frando May 6, 2026 09:18

Merge remote-tracking branch 'origin/main' into configurable-path-sel…

a5474b7

…ection

rklaehn changed the title ~~feat(iroh)! Configurable path selection (WIP)~~ feat(iroh)! Configurable path selection May 6, 2026

Rename default path selector to type name

7f35601

rklaehn force-pushed the configurable-path-selection branch from 0a79c3c to 7f35601 Compare May 6, 2026 09:49

rklaehn changed the title ~~feat(iroh)! Configurable path selection~~ feat(iroh)!: Configurable path selection May 6, 2026

Remove too detailed comments

031f59d

Frando reviewed May 6, 2026

View reviewed changes

Conversation

rklaehn commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Breaking Changes

Notes & open questions

Change checklist

Uh oh!

github-actions Bot commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rklaehn commented May 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Frando left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rklaehn commented May 5, 2026 •

edited

Loading

github-actions Bot commented May 6, 2026 •

edited

Loading

github-actions Bot commented May 6, 2026 •

edited

Loading