tez 0.0.3

A lightweight, ergonomic, and fast high-level HTTP client for Rust
Documentation
//! Host resolution and address connection policy.

use std::{
    collections::VecDeque,
    future::Future,
    net::{IpAddr, SocketAddr},
    pin::Pin,
    time::Duration,
};

use crate::{
    Error, Result,
    connection::Settings,
    runtime::{Connected, Connector, Deadline, SocketOptions, Timer},
};
use futures_util::{
    StreamExt as _,
    future::{Either, select},
    stream::FuturesUnordered,
};

const ATTEMPT_DELAY: Duration = Duration::from_millis(250);
const PARALLEL_ATTEMPTS: usize = 2;

/// A future resolving one host and port into socket addresses.
pub type Resolve<'a> = Pin<Box<dyn Future<Output = std::io::Result<Vec<SocketAddr>>> + Send + 'a>>;

/// Resolves host names for Tez connection attempts.
///
/// Implementations return every usable address without connecting. Tez keeps
/// address-family interleaving, staggered connection attempts, deadlines, and
/// socket configuration inside its transport layer.
pub trait Resolver: Send + Sync {
    /// Resolves `host` and `port` into candidate socket addresses.
    fn resolve<'a>(&'a self, host: &'a str, port: u16) -> Resolve<'a>;
}

/// The platform resolver used by default.
#[derive(Clone, Copy, Debug, Default)]
pub struct SystemResolver;

impl Resolver for SystemResolver {
    fn resolve<'a>(&'a self, host: &'a str, port: u16) -> Resolve<'a> {
        Box::pin(async move { async_net::resolve((host, port)).await })
    }
}

pub(crate) async fn connect(
    resolver: &dyn Resolver,
    connector: &dyn Connector,
    host: &str,
    port: u16,
    settings: Settings,
    deadline: Deadline,
) -> Result<Connected> {
    let addresses = deadline
        .run(async {
            resolver
                .resolve(host, port)
                .await
                .map_err(|_| Error::connect())
        })
        .await?;
    let stream = deadline
        .run(async {
            connect_resolved(addresses, connector, settings, deadline.timer())
                .await
                .map_err(|_| Error::connect())
        })
        .await?;
    Ok(stream)
}

async fn connect_resolved(
    addresses: Vec<SocketAddr>,
    connector: &dyn Connector,
    settings: Settings,
    timer: &Timer,
) -> std::io::Result<Connected> {
    let mut addresses = interleave(
        addresses
            .into_iter()
            .filter(|address| same_family(settings.local(), address.ip()))
            .collect(),
    );
    let mut attempts = FuturesUnordered::new();
    let mut last_error = None;

    loop {
        if attempts.is_empty() {
            let Some(address) = addresses.pop_front() else {
                return Err(last_error.unwrap_or_else(|| {
                    std::io::Error::new(std::io::ErrorKind::AddrNotAvailable, "no resolved address")
                }));
            };
            attempts.push(connect_address(address, connector, settings));
        }
        if addresses.is_empty() || attempts.len() == PARALLEL_ATTEMPTS {
            match attempts.next().await {
                Some(Ok(stream)) => return Ok(stream),
                Some(Err(error)) => last_error = Some(error),
                None => unreachable!("a connection attempt was queued"),
            }
            continue;
        }

        match select(attempts.next(), timer.after(ATTEMPT_DELAY)).await {
            Either::Left((Some(Ok(stream)), _)) => return Ok(stream),
            Either::Left((Some(Err(error)), _)) => last_error = Some(error),
            Either::Left((None, _)) => unreachable!("a connection attempt was queued"),
            Either::Right((_, pending)) => drop(pending),
        }
        if let Some(address) = addresses.pop_front() {
            attempts.push(connect_address(address, connector, settings));
        }
    }
}

fn interleave(addresses: Vec<SocketAddr>) -> VecDeque<SocketAddr> {
    let Some(first) = addresses.first() else {
        return VecDeque::new();
    };
    let first_is_ipv4 = first.is_ipv4();
    let (mut ipv4, mut ipv6): (VecDeque<_>, VecDeque<_>) =
        addresses.into_iter().partition(SocketAddr::is_ipv4);
    let mut interleaved = VecDeque::with_capacity(ipv4.len() + ipv6.len());
    let mut ipv4_next = first_is_ipv4;
    while !ipv4.is_empty() || !ipv6.is_empty() {
        let next = if ipv4_next {
            ipv4.pop_front().or_else(|| ipv6.pop_front())
        } else {
            ipv6.pop_front().or_else(|| ipv4.pop_front())
        };
        interleaved.push_back(next.expect("one address family is non-empty"));
        ipv4_next = !ipv4_next;
    }
    interleaved
}

async fn connect_address(
    address: SocketAddr,
    connector: &dyn Connector,
    settings: Settings,
) -> std::io::Result<Connected> {
    connector
        .connect(
            address,
            SocketOptions::new(
                settings.local().map(|address| SocketAddr::new(address, 0)),
                settings.uses_nodelay(),
                settings.keepalive_idle(),
            ),
        )
        .await
}

fn same_family(local: Option<IpAddr>, remote: IpAddr) -> bool {
    local.is_none_or(|local| local.is_ipv4() == remote.is_ipv4())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn resolved_addresses_alternate_families_without_reordering_them() {
        let ipv6_a = "[::1]:80".parse().unwrap();
        let ipv6_b = "[::2]:80".parse().unwrap();
        let ipv4_a = "127.0.0.1:80".parse().unwrap();
        let ipv4_b = "127.0.0.2:80".parse().unwrap();
        assert_eq!(
            interleave(vec![ipv6_a, ipv6_b, ipv4_a, ipv4_b]),
            VecDeque::from([ipv6_a, ipv4_a, ipv6_b, ipv4_b])
        );
    }

    #[test]
    fn a_local_address_selects_only_matching_destinations() {
        assert!(same_family(None, "127.0.0.1".parse().unwrap()));
        assert!(same_family(
            Some("127.0.0.2".parse().unwrap()),
            "127.0.0.1".parse().unwrap()
        ));
        assert!(!same_family(
            Some("::1".parse().unwrap()),
            "127.0.0.1".parse().unwrap()
        ));
    }
}