Iroh

https://docs.rs/iroh/latest/
Admin
Iroh is a Rust library for establishing direct peer-to-peer connectivity between endpoints using...
Tokens:1,325,993
Snippets:11,347
Trust Score:9.7
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Example: Using Preset with custom transport

Source: https://docs.rs/iroh/latest/iroh/endpoint/presets/trait.Preset.html?search=std%3A%3Avec

Shows how to apply a Preset (transport) to an Endpoint builder. The example creates a network, gets a transport, and binds the endpoint.

```rust
let network = TestNetwork::new();
let transport = network.create_transport(secret_key.public())?;
let ep = Endpoint::builder()
    .secret_key(secret_key)
    .preset(transport)
    .bind()
    .await?;
```

--------------------------------

### DNS Address Lookup Setup

Source: https://docs.rs/iroh/latest/iroh/address_lookup/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example showing how to enable DNS address lookup on an iroh Endpoint.

```APIDOC
## [Example] DNS Address Lookup Setup

### Description
This example demonstrates how to configure an `Endpoint` with DNS address lookup using `PkarrPublisher` and `address_lookup::DnsAddressLookup`.

### Code
```rust
use iroh::{
    Endpoint, SecretKey,
    address_lookup::{self, AddrFilter, PkarrPublisher},
    endpoint::{RelayMode, presets},
};

let ep = Endpoint::builder(presets::Minimal)
    .addr_filter(AddrFilter::relay_only())
    .address_lookup(PkarrPublisher::n0_dns())
    .address_lookup(address_lookup::DnsAddressLookup::n0_dns())
    .bind()
    .await?;
```
```

--------------------------------

### pub async fn connect_with_opts(&self, endpoint_addr: impl Into<EndpointAddr>, alpn: &[u8], options: ConnectOptions) -> Result<Connecting, ConnectWithOptsError>

Source: https://docs.rs/iroh/latest/iroh/endpoint/struct.Endpoint.html

Starts a connection attempt with a remote Endpoint, allowing advanced connection setup.

```APIDOC
## pub async fn connect_with_opts(&self, endpoint_addr: impl Into<EndpointAddr>, alpn: &[u8], options: ConnectOptions) -> Result<Connecting, ConnectWithOptsError>

### Description
Starts a connection attempt with a remote `Endpoint`. Like `Endpoint::connect` (see also its docs for general details), but allows for a more advanced connection setup with more customization in two aspects:
  1. The returned future resolves to a `Connecting`, which can be further processed into a `Connection` by awaiting, or alternatively allows connecting with 0-RTT via `Connecting::into_0rtt`. **Note:** Please read the documentation for `into_0rtt` carefully to assess security concerns.
  2. The `QuicTransportConfig` for the connection can be modified via the provided `ConnectOptions`. **Note:** Please be aware that changing transport config settings may have adverse effects on establishing and maintaining direct connections. Carefully test settings you use and consider this currently as still rather experimental.

### Parameters
- **endpoint_addr** (impl Into<EndpointAddr>) - Required - The remote endpoint address or endpoint ID.
- **alpn** (&[u8]) - Required - The application-level protocol identifier.
- **options** (ConnectOptions) - Required - Connection options for advanced setup.

### Returns
- **Result<Connecting, ConnectWithOptsError>** - A `Connecting` future or a connection error.
```

--------------------------------

### DNS Address Lookup Example

Source: https://docs.rs/iroh/latest/iroh/address_lookup/index.html

Example showing how to configure DNS address lookup with a PkarrPublisher and DnsAddressLookup.

```APIDOC
## [Example] Enabling DNS Address Lookup

### Description
A common setup for enabling DNS Address Lookup in iroh, which requires configuring both a `PkarrPublisher` and an `address_lookup::DnsAddressLookup`.

### Code
```rust
use iroh::{
    Endpoint, SecretKey,
    address_lookup::{self, AddrFilter, PkarrPublisher},
    endpoint::{RelayMode, presets},
};

let ep = Endpoint::builder(presets::Minimal)
    .addr_filter(AddrFilter::relay_only())
    .address_lookup(PkarrPublisher::n0_dns())
    .address_lookup(address_lookup::DnsAddressLookup::n0_dns())
    .bind()
    .await?;
```
```

--------------------------------

### Url::as_str example

Source: https://docs.rs/iroh/latest/iroh/struct.RelayUrl.html

Example for the as_str method, which returns the serialization of the URL. This is fast because the serialization is already stored.

```rust
use url::Url;

let url_str = "https://example.net/";
let url = Url::parse(url_str)?;
assert_eq!(url.as_str(), url_str);
```

--------------------------------

### Enable DNS Address Lookup with PkarrPublisher and DnsAddressLookup

Source: https://docs.rs/iroh/latest/iroh/address_lookup/index.html?search=

Shows a common setup for enabling DNS address lookup on an iroh Endpoint. Requires the `iroh` crate and uses `AddrFilter::relay_only()` to restrict addresses. The example builds an endpoint with both a `PkarrPublisher` and a `DnsAddressLookup` using the n0 DNS service.

```rust
use iroh::{
    Endpoint, SecretKey,
    address_lookup::{self, AddrFilter, PkarrPublisher},
    endpoint::{RelayMode, presets},
};

let ep = Endpoint::builder(presets::Minimal)
    .addr_filter(AddrFilter::relay_only())
    .address_lookup(PkarrPublisher::n0_dns())
    .address_lookup(address_lookup::DnsAddressLookup::n0_dns())
    .bind()
    .await?;
```

--------------------------------

### Url::make_relative examples

Source: https://docs.rs/iroh/latest/iroh/struct.RelayUrl.html

Examples for the make_relative method, showing how to create a relative URL from a base URL. Returns None if the scheme, host, or port differ.

```rust
use url::Url;

let base = Url::parse("https://example.net/a/b.html")?;
let url = Url::parse("https://example.net/a/c.png")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("c.png"));

let base = Url::parse("https://example.net/a/b/")?;
let url = Url::parse("https://example.net/a/b/c.png")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("c.png"));

let base = Url::parse("https://example.net/a/b/")?;
let url = Url::parse("https://example.net/a/d/c.png")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("../d/c.png"));

let base = Url::parse("https://example.net/a/b.html?c=d")?;
let url = Url::parse("https://example.net/a/b.html?e=f")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("?e=f"));
```

--------------------------------

### Arc::strong_count example

Source: https://docs.rs/iroh/latest/iroh/protocol/type.IncomingFilter.html

Shows how to use Arc::strong_count to get the number of strong (Arc) pointers to an allocation. The example is deterministic because the Arc is not shared between threads.

```rust
use std::sync::Arc;

let five = Arc::new(5);
let _also_five = Arc::clone(&five);

// This assertion is deterministic because we haven't shared
// the `Arc` between threads.
assert_eq!(2, Arc::strong_count(&five));
```

--------------------------------

### Arc::weak_count example

Source: https://docs.rs/iroh/latest/iroh/protocol/type.IncomingFilter.html

Shows how to use Arc::weak_count to get the number of Weak pointers to an allocation. The example is deterministic because the Arc and Weak are not shared between threads.

```rust
use std::sync::Arc;

let five = Arc::new(5);
let _weak_five = Arc::downgrade(&five);

// This assertion is deterministic because we haven't shared
// the `Arc` or `Weak` between threads.
assert_eq!(1, Arc::weak_count(&five));
```

--------------------------------

### pub fn with_start_instant(self, start: Instant) -> QlogFileFactory

Source: https://docs.rs/iroh/latest/iroh/endpoint/struct.QlogFileFactory.html

Override the instant relative to which all events are recorded. If not set, events will be recorded relative to the start of the connection.

```APIDOC
## pub fn with_start_instant(self, start: Instant) -> QlogFileFactory

### Description
Override the instant relative to which all events are recorded. If not set, events will be recorded relative to the start of the connection.

### Method
Builder method

### Parameters
- `start` (Instant) - Required - The instant to use as the reference for event timestamps.

### Returns
- `QlogFileFactory` - The updated qlog factory with the start instant set.

```

--------------------------------

### Get URL path with percent-encoding

Source: https://docs.rs/iroh/latest/iroh/struct.RelayUrl.html

Shows how to get the percent-encoded path of a URL. The path starts with '/' for hierarchical URLs and is empty for the root. Non-ASCII characters are percent-encoded.

```rust
use url::{Url, ParseError};

let url = Url::parse("https://example.com/api/versions?page=2")?;
assert_eq!(url.path(), "/api/versions");

let url = Url::parse("https://example.com")?;
assert_eq!(url.path(), "/");

let url = Url::parse("https://example.com/countries/việt nam")?;
assert_eq!(url.path(), "/countries/vi%E1%BB%87t%20nam");
```

--------------------------------

### Router::builder(endpoint).accept(b"/my/alpn", Echo).spawn()

Source: https://docs.rs/iroh/latest/iroh/protocol/index.html?search=

Builds a router with an endpoint and accepts a protocol on a given ALPN string, then spawns the accept loop.

```APIDOC
## Router::builder(endpoint).accept(b"/my/alpn", Echo).spawn()

### Description
Builds a router with an endpoint and accepts a protocol on a given ALPN string, then spawns the accept loop.

### Method
Builder method chain

### Endpoint
N/A (Rust SDK)

### Parameters
- **endpoint** (Endpoint) - Required - The endpoint to bind for accepting connections.
- **alpn** (bytes) - Required - The ALPN protocol identifier to accept (e.g., b"/my/alpn").
- **handler** (ProtocolHandler) - Required - The protocol handler implementation for the accepted protocol.

### Request Example
```rust
let endpoint = Endpoint::bind(presets::N0).await?;
let router = Router::builder(endpoint).accept(b"/my/alpn", Echo).spawn();
```

### Response
#### Success Response
Returns a `Router` that is spawned and running.

#### Response Example
```rust
let router = Router::builder(endpoint).accept(b"/my/alpn", Echo).spawn();
```
```

--------------------------------

### Arc::get_mut example

Source: https://docs.rs/iroh/latest/iroh/protocol/type.IncomingFilter.html

Shows how to get a mutable reference to the inner value of an Arc when it is unique. Returns None if other Arc or Weak pointers exist. The example mutates the value and checks uniqueness.

```rust
use std::sync::Arc;

let mut x = Arc::new(3);
*Arc::get_mut(&mut x).unwrap() = 4;
assert_eq!(*x, 4);

let _y = Arc::clone(&x);
assert!(Arc::get_mut(&mut x).is_none());
```

--------------------------------

### ConnectOptions::new

Source: https://docs.rs/iroh/latest/iroh/endpoint/struct.ConnectOptions.html?search=

Initializes new connection options with default settings, equivalent to Endpoint::connect.

```APIDOC
## ConnectOptions::new

### Description
Initializes new connection options. By default, the connection will use the same options as `Endpoint::connect`, e.g. a default `QuicTransportConfig`.

### Method
`pub fn new() -> Self`

### Parameters
None.

### Returns
- `Self` - A new `ConnectOptions` instance with default settings.

```

--------------------------------

### test_active_relay_reconnect test setup

Source: https://docs.rs/iroh/latest/src/iroh/socket/transports/relay/actor.rs.html?search=u32+-%3E+bool

Sets up a test for active relay reconnection. Creates channels, starts the relay actor, and sends a datagram to the echo endpoint.

```rust
#[tokio::test]
    #[traced_test]
    async fn test_active_relay_reconnect() -> Result {
        let (_relay_map, relay_url, _server) = test_utils::run_relay_server().await?;
        let (peer_endpoint, _echo_endpoint_task) = start_echo_endpoint(relay_url.clone());

        let secret_key = SecretKey::from_bytes(&[1u8; 32]);
        let (datagram_recv_tx, mut datagram_recv_rx) = mpsc::channel(16);
        let (send_datagram_tx, send_datagram_rx) = mpsc::channel(16);
        let (_prio_inbox_tx, prio_inbox_rx) = mpsc::channel(8);
        let (inbox_tx, inbox_rx) = mpsc::channel(16);
        let cancel_token = CancellationToken::new();
        let metrics = Arc::new(SocketMetrics::default());
        let task = start_active_relay_actor(
            secret_key,
            cancel_token.clone(),
            relay_url.clone(),
            prio_inbox_rx,
            inbox_rx,
            send_datagram_rx,
            datagram_recv_tx.clone(),
            metrics.clone(),
            info_span!("actor-under-test"),
        );

        // Send a datagram to our echo endpoint.
        info!("first echo");
        let hello_send_item = RelaySendItem {
            remote_endpoint: peer_endpoint,
            url: relay_url.clone(),
            datagrams: Datagrams::from(b"hello"),
        };
        send_recv_echo(
            hello_send_item.clone(),
            &send_datagram_tx,
            &mut datagram_recv_rx,
        )
        .await?;

        // Now ask to check the connection, triggering a ping but no reconnect.
        let (tx, rx) = oneshot::channel();
```

--------------------------------

### Arc::into_raw example

Source: https://docs.rs/iroh/latest/iroh/protocol/type.IncomingFilter.html

Demonstrates consuming an Arc with Arc::into_raw to get a raw pointer, and asserting the pointed-to value is correct using unsafe dereference.

```rust
use std::sync::Arc;

let x = Arc::new("hello".to_owned());
let x_ptr = Arc::into_raw(x);
assert_eq!(unsafe { &*x_ptr }, "hello");
```

--------------------------------

### Router accept loop example

Source: https://docs.rs/iroh/latest/src/iroh/protocol.rs.html?search=std%3A%3Avec

Shows how to create a Router with a custom Echo protocol handler that echoes back any bytes received on a connection. The example includes the Router::builder call and the ProtocolHandler implementation for the Echo struct.

```rust
```no_run
# #[cfg(with_crypto_provider)]
# use iroh::{
#     endpoint::{BindError, presets},
#     protocol::Router,
#     Endpoint,
# };
# use iroh::{
#     endpoint::Connection,
#     protocol::{AcceptError, ProtocolHandler},
# };
#
# #[cfg(with_crypto_provider)]
# async fn test_compile() -> Result<(), BindError> {
let endpoint = Endpoint::bind(presets::N0).await?;

let router = Router::builder(endpoint).accept(b"/my/alpn", Echo).spawn();
# Ok(())
# }

// The protocol definition:
#[derive(Debug, Clone)]
struct Echo;

impl ProtocolHandler for Echo {
    async fn accept(&self, connection: Connection) -> Result<(), AcceptError> {
        let (mut send, mut recv) = connection.accept_bi().await?;

        // Echo any bytes received back directly.
        let bytes_sent = tokio::io::copy(&mut recv, &mut send).await?;

        send.finish()?;
        connection.closed().await;

        Ok(())
    }
}
```
```

--------------------------------

### Using Box::leak to get a static mutable reference

Source: https://docs.rs/iroh/latest/iroh/dns/type.BoxIter.html

This example shows how to use Box::leak to consume a Box and obtain a mutable reference with a chosen lifetime, often 'static. It is useful for data that lives for the remainder of the program. The example increments the leaked value and asserts the result.

```rust
let x = Box::new(41);
let static_ref: &'static mut usize = Box::leak(x);
*static_ref += 1;
assert_eq!(*static_ref, 42);
```

--------------------------------

### domain() example

Source: https://docs.rs/iroh/latest/iroh/struct.RelayUrl.html

Shows domain() returning None for IP addresses and cannot-be-a-base URLs like mailto:rms@example.net, and Some for domain names.

```rust
use url::Url;

let url = Url::parse("https://127.0.0.1/")?;
assert_eq!(url.domain(), None);

let url = Url::parse("mailto:rms@example.net")?;
assert_eq!(url.domain(), None);

let url = Url::parse("https://example.com/")?;
assert_eq!(url.domain(), Some("example.com"));

let url = Url::parse("https://subdomain.example.com/")?;
assert_eq!(url.domain(), Some("subdomain.example.com"));
```

--------------------------------

### Test endpoint bidirectional send/receive setup

Source: https://docs.rs/iroh/latest/src/iroh/endpoint.rs.html?search=u32+-%3E+bool

Starts a test for bidirectional send/receive over an endpoint. Creates an endpoint with a memory address lookup and minimal presets, binding to a local address.

```rust
    #[tokio::test]
    #[traced_test]
    async fn endpoint_bidi_send_recv() -> Result {
        let disco = MemoryLookup::new();
        let ep1 = Endpoint::builder(presets::Minimal)
            .address_lookup(disco.clone())
            .alpns(vec![TEST_ALPN.to_vec()])
            .bind()
            .await?;
```

--------------------------------

### host() example

Source: https://docs.rs/iroh/latest/iroh/struct.RelayUrl.html

Shows host() returning Some for URLs with a host and None for cannot-be-a-base URLs like unix:/run/foo.socket and data:text/plain,Stuff.

```rust
use url::Url;

let url = Url::parse("https://127.0.0.1/index.html")?;
assert!(url.host().is_some());

let url = Url::parse("ftp://rms@example.com")?;
assert!(url.host().is_some());

let url = Url::parse("unix:/run/foo.socket")?;
assert!(url.host().is_none());

let url = Url::parse("data:text/plain,Stuff")?;
assert!(url.host().is_none());
```

--------------------------------

### Get strong count from raw pointer with Arc::strong_count_from_raw

Source: https://docs.rs/iroh/latest/iroh/protocol/type.IncomingFilter.html

Demonstrates the nightly-only `Arc::strong_count_from_raw` API, which requires the `arc_raw_get_strong` feature gate. The example clones an `Arc`, gets a raw pointer, and checks the strong count from the raw pointer. The pointer must point to a live `Arc` allocation and the strong count can change concurrently.

```rust
#![feature(arc_raw_get_strong)]
use std::sync::Arc;

let five = Arc::new(5);
let _also_five = Arc::clone(&five);
let ptr = Arc::into_raw(five);

unsafe {
    // This assertion is deterministic because we haven't shared
    // the `Arc` between threads.
    assert_eq!(2, Arc::strong_count_from_raw(ptr));

    // Convert back to an `Arc` to avoid leaking memory.
    let five = Arc::from_raw(ptr);
    assert_eq!(2, Arc::strong_count(&five));
}
```

--------------------------------

### take

Source: https://docs.rs/iroh/latest/iroh/endpoint/struct.RecvStream.html

Creates an adaptor which reads at most `limit` bytes from it.

```APIDOC
## take

### Description
Creates an adaptor which reads at most `limit` bytes from it.

### Method
take

### Parameters
- **self** (Self) - Required - The reader to adapt.
- **limit** (u64) - Required - The maximum number of bytes to read.

### Returns
- **Take<Self>** - An adaptor that reads at most `limit` bytes.

### Example
```rust
let limited = stream.take(1024);
```
```

--------------------------------

### Manually create Box from scratch using global allocator

Source: https://docs.rs/iroh/latest/iroh/dns/type.BoxIter.html

Example for `Box::from_raw` that manually allocates memory and constructs a `Box` from a raw pointer.

```rust
use std::alloc::{alloc, Layout};

unsafe {
    let ptr = alloc(Layout::new::<i32>()) as *mut i32;
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `ptr`, though for this
    // simple example `*ptr = 5` would have worked as well.
    ptr.write(5);
    let x = Box::from_raw(ptr);
}
```

--------------------------------

### endpoint_relay_connect_loop test setup

Source: https://docs.rs/iroh/latest/src/iroh/endpoint.rs.html?search=

Starts a relay server and initializes test parameters for a loop test with 5 clients, 2 chunks per client, and a chunk size of 100. Uses a seeded `ChaCha8Rng` for deterministic randomness.

```rust
#[tokio::test]
#[traced_test]
async fn endpoint_relay_connect_loop() -> Result {
    let test_start = Instant::now();
    let n_clients = 5;
    let n_chunks_per_client = 2;
    let chunk_size = 100;
    let mut rng = rand_chacha::ChaCha8Rng::seed_from_u64(42);
    let (relay_map, relay_url, _relay_guard) = run_relay_server().await.unwrap();
```

--------------------------------

### run_relay_server_with

Source: https://docs.rs/iroh/latest/iroh/test_utils/fn.run_relay_server_with.html

Documentation for the `run_relay_server_with` function, which runs a relay server with optional QUIC support.

```APIDOC
## Function `run_relay_server_with`

### Description
Runs a relay server. If `quic` is set to `true`, it will make the appropriate `QuicConfig` from the generated TLS certificates and run the QUIC server at a random free port. The return value is similar to `run_relay_server`.

### Signature
```rust
pub async fn run_relay_server_with(
    quic: bool,
) -> Result<(RelayMap, RelayUrl, Server), SpawnError>
```

### Parameters
- **quic** (bool) - Required - If `true`, runs the QUIC server with generated TLS certificates.

### Returns
- **Result<(RelayMap, RelayUrl, Server), SpawnError>** - A tuple containing the relay map, relay URL, and server instance, or a spawn error.

### Availability
Available on **crate features `test-utils`** only.
```

--------------------------------

### Test active relay reconnect setup and first echo

Source: https://docs.rs/iroh/latest/src/iroh/socket/transports/relay/actor.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Sets up a relay server and echo endpoint, then starts an active relay actor with test channels and metrics. Sends a 'hello' datagram through the actor and verifies the echo response, preparing to test reconnection behavior.

```rust
#[tokio::test]
#[traced_test]
async fn test_active_relay_reconnect() -> Result {
    let (_relay_map, relay_url, _server) = test_utils::run_relay_server().await?;
    let (peer_endpoint, _echo_endpoint_task) = start_echo_endpoint(relay_url.clone());

    let secret_key = SecretKey::from_bytes(&[1u8; 32]);
    let (datagram_recv_tx, mut datagram_recv_rx) = mpsc::channel(16);
    let (send_datagram_tx, send_datagram_rx) = mpsc::channel(16);
    let (_prio_inbox_tx, prio_inbox_rx) = mpsc::channel(8);
    let (inbox_tx, inbox_rx) = mpsc::channel(16);
    let cancel_token = CancellationToken::new();
    let metrics = Arc::new(SocketMetrics::default());
    let task = start_active_relay_actor(
        secret_key,
        cancel_token.clone(),
        relay_url.clone(),
        prio_inbox_rx,
        inbox_rx,
        send_datagram_rx,
        datagram_recv_tx.clone(),
        metrics.clone(),
        info_span!("actor-under-test"),
    );

    // Send a datagram to our echo endpoint.
    info!("first echo");
    let hello_send_item = RelaySendItem {
        remote_endpoint: peer_endpoint,
        url: relay_url.clone(),
        datagrams: Datagrams::from(b"hello"),
    };
    send_recv_echo(
        hello_send_item.clone(),
        &send_datagram_tx,
        &mut datagram_recv_rx,
    )
    .await?;

    // Now ask to check the connection, triggering a ping but no reconnect.
    let (tx, rx) = oneshot::channel();
```

--------------------------------

### Incoming::accept_with

Source: https://docs.rs/iroh/latest/iroh/endpoint/struct.Incoming.html?search=u32+-%3E+bool

Accepts this incoming connection using a custom configuration. Use the Endpoint::create_server_config_builder method to create a ServerConfigBuilder to customize a ServerConfig.

```APIDOC
## Incoming::accept_with

### Description
Accepts this incoming connection using a custom configuration. Use the Endpoint::create_server_config_builder method to create a ServerConfigBuilder to customize a ServerConfig.

### Method
accept_with

### Signature
pub fn accept_with(self, server_config: Arc<ServerConfig>) -> Result<Accepting, ConnectionError>

### Parameters
- self: Incoming - The incoming connection to accept.
- server_config: Arc<ServerConfig> - The custom server configuration to use.

### Returns
- Result<Accepting, ConnectionError> - The accepting state if successful, or a connection error.

### Notes
See accept() for more details.
```

--------------------------------

### Url::join examples

Source: https://docs.rs/iroh/latest/iroh/struct.RelayUrl.html

Examples for the join method, showing how to resolve relative URLs against a base URL. Note the significance of trailing slashes and how scheme-relative, base-relative, and absolute inputs are handled.

```rust
use url::Url;

// Base without a trailing slash
let base = Url::parse("https://example.net/a/b.html")?;
let url = base.join("c.png")?;
assert_eq!(url.as_str(), "https://example.net/a/c.png");  // Not /a/b.html/c.png

// Base with a trailing slash
let base = Url::parse("https://example.net/a/b/")?;
let url = base.join("c.png")?;
assert_eq!(url.as_str(), "https://example.net/a/b/c.png");

// Input as scheme relative special URL
let base = Url::parse("https://alice.com/a")?;
let url = base.join("//eve.com/b")?;
assert_eq!(url.as_str(), "https://eve.com/b");

// Input as base url relative special URL
let base = Url::parse("https://alice.com/a")?;
let url = base.join("/v1/meta")?;
assert_eq!(url.as_str(), "https://alice.com/v1/meta");

// Input as absolute URL
let base = Url::parse("https://alice.com/a")?;
let url = base.join("http://eve.com/b")?;
assert_eq!(url.as_str(), "http://eve.com/b");  // http instead of https
```

--------------------------------

### active_relay_handle: Get or create active relay handle

Source: https://docs.rs/iroh/latest/src/iroh/socket/transports/relay/actor.rs.html?search=std%3A%3Avec

This method returns a handle to an ActiveRelayActor for the given URL. If a handle already exists, it returns a clone. Otherwise, it starts a new active relay actor, optionally marks it as the home relay if it matches the configured home relay, and inserts it into the active_relays map.

```rust
fn active_relay_handle(&mut self, url: RelayUrl) -> ActiveRelayHandle {
    match self.active_relays.get(&url) {
        Some(e) => e.clone(),
        None => {
            let handle = self.start_active_relay(url.clone());
            if Some(&url) == self.config.my_relay.get().as_ref().map(RelayStatus::url)
                && let Err(err) = handle
                    .inbox_addr
                    .try_send(ActiveRelayMessage::SetHomeRelay(true))
            {
                error!("Home relay not set, send to new actor failed: {err:#}.");
            }
            self.active_relays.insert(url, handle.clone());
            self.log_active_relay();
            handle
        }
    }
}
```

--------------------------------

### Box::into_inner example

Source: https://docs.rs/iroh/latest/iroh/dns/type.BoxIter.html

Example for Box::into_inner, which consumes the box and returns the wrapped value.

```rust
#![feature(box_into_inner)]

let c = Box::new(5);

assert_eq!(Box::into_inner(c), 5);
```
Tokens:
Raw