tez 0.0.3

A lightweight, ergonomic, and fast high-level HTTP client for Rust
Documentation
//! Runtime capabilities used by Tez without choosing an application runtime.
//!
//! A runtime supplies scheduling, time, name resolution, and TCP connections
//! as one coherent value. The portable default uses the Smol ecosystem's
//! `async-io` building blocks. Optional first-party adapters let applications
//! keep the complete I/O path on their existing runtime.

mod connector;
mod deadline;
mod executor;
mod io;
mod timer;

#[cfg(feature = "runtime-smol")]
mod smol;
#[cfg(feature = "runtime-tokio")]
mod tokio;

use std::{fmt, sync::Arc};

pub use connector::{AsyncIoConnector, Connect, Connected, Connector, SocketOptions};
pub use executor::Executor;
pub use io::Io;
#[cfg(feature = "runtime-smol")]
pub use smol::Smol;
pub use timer::{Sleep, Timer};
#[cfg(feature = "runtime-tokio")]
pub use tokio::Tokio;

pub(crate) use connector::SharedConnector;
pub(crate) use deadline::{Deadline, DeadlineBody};
pub(crate) use io::PrefixedIo;

use crate::dns::{Resolver, SystemResolver};

/// The runtime capabilities used by one Tez client.
#[derive(Clone)]
pub struct Runtime {
    executor: Executor,
    timer: Timer,
    resolver: Arc<dyn Resolver>,
    connector: SharedConnector,
}

impl Runtime {
    /// Starts a runtime configuration with Tez's portable defaults.
    #[must_use]
    pub fn builder() -> RuntimeBuilder {
        RuntimeBuilder::default()
    }

    /// Replaces the executor while retaining this runtime's timer, resolver,
    /// and connector.
    ///
    /// This supports applications that want native socket integration from
    /// one runtime while driving Tez connection tasks on another compatible
    /// executor.
    #[must_use]
    pub fn with_executor(mut self, executor: Executor) -> Self {
        self.executor = executor;
        self
    }

    pub(crate) fn executor(&self) -> &Executor {
        &self.executor
    }

    pub(crate) fn timer(&self) -> &Timer {
        &self.timer
    }

    pub(crate) fn resolver(&self) -> &dyn Resolver {
        self.resolver.as_ref()
    }

    pub(crate) fn connector(&self) -> &dyn Connector {
        &self.connector
    }

    /// Resolves a host through this runtime's configured resolver.
    pub fn resolve<'a>(&'a self, host: &'a str, port: u16) -> crate::dns::Resolve<'a> {
        self.resolver.resolve(host, port)
    }

    /// Connects one resolved address through this runtime's TCP connector.
    pub fn connect(&self, address: std::net::SocketAddr, options: SocketOptions) -> Connect<'_> {
        self.connector.connect(address, options)
    }

    pub(crate) fn set_executor(&mut self, executor: Executor) {
        self.executor = executor;
    }

    pub(crate) fn set_resolver(&mut self, resolver: impl Resolver + 'static) {
        self.resolver = Arc::new(resolver);
    }
}

impl Default for Runtime {
    fn default() -> Self {
        Self::builder().build()
    }
}

impl fmt::Debug for Runtime {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("Runtime")
            .field("executor", &self.executor)
            .field("timer", &self.timer)
            .field("connector", &self.connector)
            .finish_non_exhaustive()
    }
}

/// Builds a coherent set of asynchronous runtime capabilities.
pub struct RuntimeBuilder {
    executor: Executor,
    timer: Timer,
    resolver: Arc<dyn Resolver>,
    connector: SharedConnector,
}

impl RuntimeBuilder {
    /// Replaces the executor used for connection drivers.
    #[must_use]
    pub fn executor(mut self, executor: Executor) -> Self {
        self.executor = executor;
        self
    }

    /// Replaces the timer used for deadlines, retries, and HTTP/2 liveness.
    #[must_use]
    pub fn timer(mut self, timer: Timer) -> Self {
        self.timer = timer;
        self
    }

    /// Replaces DNS resolution while retaining the other runtime capabilities.
    #[must_use]
    pub fn resolver(mut self, resolver: impl Resolver + 'static) -> Self {
        self.resolver = Arc::new(resolver);
        self
    }

    /// Replaces TCP connection establishment.
    #[must_use]
    pub fn connector(mut self, connector: impl Connector + 'static) -> Self {
        self.connector = SharedConnector::new(connector);
        self
    }

    /// Finishes the runtime capability bundle.
    #[must_use]
    pub fn build(self) -> Runtime {
        Runtime {
            executor: self.executor,
            timer: self.timer,
            resolver: self.resolver,
            connector: self.connector,
        }
    }
}

impl Default for RuntimeBuilder {
    fn default() -> Self {
        Self {
            executor: Executor::default(),
            timer: Timer::default(),
            resolver: Arc::new(SystemResolver),
            connector: SharedConnector::new(AsyncIoConnector),
        }
    }
}