Skip to content

feat: Implement user transports#3707

Closed
rklaehn wants to merge 40 commits intomainfrom
feat-user-transport
Closed

feat: Implement user transports#3707
rklaehn wants to merge 40 commits intomainfrom
feat-user-transport

Conversation

@rklaehn
Copy link
Copy Markdown
Contributor

@rklaehn rklaehn commented Nov 27, 2025

Description

Adds user defined transports.

Transports have to impl a dynable trait, currently named UserTransport. Implementing this requires implementing another dynable trait UserSender. Creating a transport requires implementing yet another dynable trait UserTransportConfig (possibly to be renamed to UserTransportFactory?, it's not a config).

An user addr is just an opaque blob with an u64 tranport id. Small blobs will be inlined, but that is an implementation detail.

Breaking Changes

Notes & open questions

Open questions:

  • should all transports be user transports? Currently we have ip and relay as special cases, which complicates the code a lot. Maybe this is needed, but maybe not.
  • the whole mechanism to figure out the local addr needs to be extended to user addrs. I did a bit in this direction, but it is not done yet.

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:

@github-actions
Copy link
Copy Markdown

github-actions bot commented Nov 27, 2025

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

Last updated: 2025-12-10T16:22:19Z

@rklaehn rklaehn force-pushed the feat-user-transport branch from c792b95 to 5eea792 Compare November 27, 2025 14:53
@rklaehn rklaehn changed the base branch from feat-multipath to feat-bind-interfaces November 27, 2025 14:54
@n0bot n0bot bot added this to iroh Nov 27, 2025
@github-project-automation github-project-automation bot moved this to 🏗 In progress in iroh Nov 27, 2025
@rklaehn rklaehn force-pushed the feat-user-transport branch from a7a4e2c to e6b3aab Compare November 27, 2025 15:09
@rklaehn rklaehn changed the title Feat user transport feat: Implement user transports Nov 27, 2025
@flub flub added this to the iroh: v1.0.0-rc.0 milestone Dec 22, 2025
Base automatically changed from feat-bind-interfaces to main January 9, 2026 08:07
@rklaehn rklaehn closed this Jan 13, 2026
@github-project-automation github-project-automation bot moved this from 🏗 In progress to ✅ Done in iroh Jan 13, 2026
github-merge-queue bot pushed a commit that referenced this pull request Mar 5, 2026
## Description

Adds user defined transports.

Transports have to impl a dynable trait, currently named
CustomTransport. Implementing this requires implementing another dynable
trait CustomSender. Creating a transport requires implementing yet
another dynable trait CustomTransportFactory.

A custom addr is just an opaque blob with an u64 tranport id. Small
blobs will be inlined, but that is an implementation detail.

Formatting currently is "<id hex>-<data hex>"

Replaces #3707

## Breaking Changes

<!-- Optional, if there are any breaking changes document them,
including how to migrate older code. -->

## Notes & open questions

- Question: encoding of custom addrs in DNS records.
- Option 1: addr=1_a1b2c3 (tries to parse first as SocketAddr then as
custom addr)
   - Option 2: custom=1_a1b2c3 (separate IrohAttr::Custom)

- ~~Question: Feature gate or not? User transports require exposing a
bit more of the guts, e.g. transmit fields, so we might want to put this
behind a feature flag that is documented to be not part of the stable
API.~~

- ~~Question: Path selection.~~

~~Currently in select_best_path we never select an user path. For some
reason it still works, but we probably should put in some logic there.~~

    ```rust
        Some((transports::Addr::User(_), _)) => {
            // todo: when should we select an user path?
            None
        }
    ```

- DRY the different mapped addrs?
    
~~We could DRY the 2 differnet mapped addrs a bit more. But once you
start with this you get into a rabbit hole. Should relay transports just
be a special kind of custom transport? If we could abstract the logic
when to choose the relay, this might work. Maybe this is best left for
later.~~

Update: path selection is now taken care of. Basically each path gets a
2-tuple consisting of primary/secondary and biased rtt, then sort and
take the best. There is an API to add a bias for each addr type and also
to configure for each transport if it is a transport of last resort.

Here is how to bias a transport:

```rust
Endpoint::builder()
    .transport_bias(
        AddrKind::Custom(TEST_TRANSPORT_ID),
        TransportBias::primary().with_rtt_advantage(CUSTOM_TRANSPORT_RTT_ADVANTAGE))
    .build().await?;
```

I also added some tests to make sure custom transports work if the ip
transport is enabled.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: ✅ Done

Development

Successfully merging this pull request may close these issues.

4 participants