feat(iroh)!: Configurable path selection

[rklaehn]

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

• Self-review.
• Documentation updates following the style guide, if relevant.
• Tests if relevant.
• All breaking changes documented.
  • List all breaking changes in the above "Breaking Changes" section.
  • Open an issue or PR on any number0 repos that are affected by this breaking change. Give guidance on how the updates should be handled or do the actual updates themselves. The major ones are:
    • quic-rpc
    • iroh-gossip
    • iroh-blobs
    • dumbpipe
    • sendme

[github-actions]

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-22T15:17:32Z

[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: bebf141

[rklaehn]

@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]

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

[rklaehn]

Yeah, we can merge this one after yours. This just has to live somewhere to make it self-contained for now.

[Frando]

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?

[rklaehn]

That is how it worked before, but then you make the assumption of min RTT is best before giving the items to the filter/selector, and the whole point of this mechanism is to not make such assumptions.

[dignifiedquire]

ci and merge conflicts are very sad

[rklaehn]

I added a bit of code to write tests for a selector easy without a full endpoint, just to test the selection logic in isolation:

PathSource::Test / StatsSource::Test

Not entirely happy with this rube goldberg machine, but I don't see a way to avoid it that isn't either involving dynamic dispatch and/or boxing. And it is not in the public API, so maybe it's fine?

Without this you would be unable to test a path selector in isolation.

[rklaehn]

One more thing: we could simplify the BiasedRttPathSelector now that it is no longer supposed to be generic, e.g. hardcore the IPV6 bias again. But if we do it it has time for a subsequent PR.

[matheus23]

This is the output diff between cargo public-api -p iroh --features unstable-custom-transports -sss runs I can see between main and this PR (the diff is purely added lines)

pub struct iroh::endpoint::transports::PathSelection
impl iroh::endpoint::transports::PathSelection
pub fn iroh::endpoint::transports::PathSelection::none() -> Self
pub fn iroh::endpoint::transports::PathSelection::set(&mut self, path: &iroh::endpoint::transports::PathSelectionData<'_>)
pub struct iroh::endpoint::transports::PathSelectionContext<'a>
impl<'a> iroh::endpoint::transports::PathSelectionContext<'a>
pub fn iroh::endpoint::transports::PathSelectionContext<'a>::current(&self) -> core::option::Option<&iroh::socket::transports::FourTuple>
pub fn iroh::endpoint::transports::PathSelectionContext<'a>::paths(&self) -> alloc::boxed::Box<(dyn core::iter::traits::iterator::Iterator<Item = iroh::endpoint::transports::PathSelectionData<'a>> + '_)>
pub struct iroh::endpoint::transports::PathSelectionData<'a>
impl<'a> iroh::endpoint::transports::PathSelectionData<'a>
pub fn iroh::endpoint::transports::PathSelectionData<'a>::network_path(&self) -> &iroh::socket::transports::FourTuple
pub fn iroh::endpoint::transports::PathSelectionData<'a>::stats(&self) -> core::option::Option<noq_proto::connection::stats::PathStats>
pub trait iroh::endpoint::transports::PathSelector: core::marker::Send + core::marker::Sync + core::fmt::Debug + 'static
pub fn iroh::endpoint::transports::PathSelector::select(&self, ctx: &iroh::endpoint::transports::PathSelectionContext<'_>) -> iroh::endpoint::transports::PathSelection
pub fn iroh::endpoint::Builder::path_selector(self, selector: alloc::sync::Arc<dyn iroh::endpoint::transports::PathSelector>) -> Self