tez 0.0.3

A lightweight, ergonomic, and fast high-level HTTP client for Rust
Documentation
use std::{fmt, net::SocketAddr, time::Duration};

use crate::{
    Body, Limits, Request, Result, Timeouts,
    proxy::Policy as ProxyPolicy,
    runtime::{Deadline, Executor, Runtime},
    tls::{TlsBuilder, Version as TlsVersion},
    transport::Transport,
};

use super::{Pool, Settings};

/// A pooled HTTP/1.1 and HTTP/2 client without high-level request policy.
///
/// This is Tez's low-level exchange layer. It accepts a complete standard HTTP
/// request, owns connection establishment and reuse, and returns a standard
/// HTTP response carrying a Tez [`Body`]. Authentication, default headers,
/// cookies, redirects, retries, decompression, and status policy belong to the
/// high-level [`crate::Client`].
#[derive(Clone)]
pub struct Client {
    pool: Pool,
    total_timeout: Option<Duration>,
}

/// Builds a low-level connection client.
#[derive(Default)]
pub struct ClientBuilder {
    runtime: Runtime,
    proxy: ProxyPolicy,
    tls: TlsBuilder,
    settings: Settings,
    limits: Limits,
    timeouts: Timeouts,
}

/// Metadata describing the connection that produced a response.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Info {
    remote_addr: SocketAddr,
}

impl Info {
    /// Returns the peer address of the physical connection.
    #[must_use]
    pub const fn remote_addr(self) -> SocketAddr {
        self.remote_addr
    }
}

impl Client {
    /// Creates a low-level client with portable runtime and transport defaults.
    ///
    /// # Errors
    ///
    /// Returns a configuration error if the default TLS or executor setup
    /// cannot be initialized.
    pub fn new() -> Result<Self> {
        Self::builder().build()
    }

    /// Starts a low-level client with portable runtime and transport defaults.
    #[must_use]
    pub fn builder() -> ClientBuilder {
        ClientBuilder::default()
    }

    /// Sends one HTTP exchange without applying high-level request policy.
    ///
    /// The request URI must be absolute. Tez validates HTTP framing, selects
    /// HTTP/1.1 or HTTP/2, applies connection deadlines, and returns response
    /// metadata in [`Info`] through the response extensions map.
    ///
    /// # Errors
    ///
    /// Returns an error for invalid request framing or targets, failed
    /// connection establishment, protocol failures, or expired deadlines.
    pub async fn send(&self, request: Request) -> Result<http::Response<Body>> {
        crate::client::validate_framing(request.headers(), request.body())?;
        let received = self
            .send_with_deadline(request, Deadline::after(self.total_timeout, self.timer())?)
            .await?;
        let mut response = http::Response::from_parts(received.parts, received.body);
        response.extensions_mut().insert(Info {
            remote_addr: received.remote_addr,
        });
        Ok(response)
    }

    pub(crate) fn from_parts(
        transport: Transport,
        runtime: Runtime,
        settings: Settings,
        limits: Limits,
        timeouts: Timeouts,
    ) -> Self {
        let pool = Pool::new(
            transport,
            runtime,
            settings,
            limits,
            timeouts.connect_timeout(),
            timeouts.idle_connection_timeout(),
            timeouts.read_timeout(),
        );
        Self {
            pool,
            total_timeout: timeouts.total_timeout(),
        }
    }

    pub(crate) async fn send_with_deadline(
        &self,
        request: Request,
        deadline: Deadline,
    ) -> Result<super::pool::Received> {
        self.pool.send(request, deadline).await
    }

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

impl ClientBuilder {
    /// Uses one coherent asynchronous runtime integration.
    #[must_use]
    pub fn runtime(mut self, runtime: Runtime) -> Self {
        self.runtime = runtime;
        self
    }

    /// Replaces only the connection-driver executor.
    #[must_use]
    pub fn executor(mut self, executor: Executor) -> Self {
        self.runtime.set_executor(executor);
        self
    }

    /// Replaces only DNS resolution.
    #[must_use]
    pub fn resolver(mut self, resolver: impl crate::dns::Resolver + 'static) -> Self {
        self.runtime.set_resolver(resolver);
        self
    }

    /// Replaces socket and HTTP/2 connection settings.
    #[must_use]
    pub const fn settings(mut self, settings: Settings) -> Self {
        self.settings = settings;
        self
    }

    /// Replaces connection and response resource limits.
    #[must_use]
    pub const fn limits(mut self, limits: Limits) -> Self {
        self.limits = limits;
        self
    }

    /// Replaces connection, read, idle, and exchange deadlines.
    #[must_use]
    pub const fn timeouts(mut self, timeouts: Timeouts) -> Self {
        self.timeouts = timeouts;
        self
    }

    /// Replaces proxy selection policy.
    #[must_use]
    pub fn proxy(mut self, proxy: ProxyPolicy) -> Self {
        self.proxy = proxy;
        self
    }

    /// Replaces platform trust roots with a PEM certificate bundle.
    #[must_use]
    pub fn trust_pem(mut self, bundle: impl AsRef<[u8]>) -> Self {
        self.tls.roots(bundle.as_ref());
        self
    }

    /// Adds PEM roots while retaining the platform verifier.
    #[must_use]
    pub fn add_root_pem(mut self, bundle: impl AsRef<[u8]>) -> Self {
        self.tls.add_roots(bundle.as_ref());
        self
    }

    /// Sets a client certificate chain and private key from combined PEM.
    #[must_use]
    pub fn identity_pem(mut self, identity: impl AsRef<[u8]>) -> Self {
        self.tls.identity(identity.as_ref());
        self
    }

    /// Sets the oldest accepted TLS protocol version.
    #[must_use]
    pub fn minimum_tls_version(mut self, version: TlsVersion) -> Self {
        self.tls.minimum_version(version);
        self
    }

    /// Sets the newest accepted TLS protocol version.
    #[must_use]
    pub fn maximum_tls_version(mut self, version: TlsVersion) -> Self {
        self.tls.maximum_version(version);
        self
    }

    /// Builds the low-level client without opening a connection.
    ///
    /// # Errors
    ///
    /// Returns an error when resource, deadline, protocol, proxy, TLS, or
    /// runtime configuration is invalid.
    pub fn build(self) -> Result<Client> {
        self.limits.validate()?;
        self.timeouts.validate()?;
        self.settings.validate()?;
        self.runtime.executor().prepare()?;
        let transport = Transport::new(self.tls, self.proxy, self.runtime.clone(), self.settings)?;
        Ok(Client::from_parts(
            transport,
            self.runtime,
            self.settings,
            self.limits,
            self.timeouts,
        ))
    }
}

impl fmt::Debug for Client {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("connection::Client")
            .finish_non_exhaustive()
    }
}

impl fmt::Debug for ClientBuilder {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("connection::ClientBuilder")
            .field("runtime", &self.runtime)
            .field("proxy", &self.proxy)
            .field("settings", &self.settings)
            .field("limits", &self.limits)
            .field("timeouts", &self.timeouts)
            .finish_non_exhaustive()
    }
}

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

    #[test]
    fn low_level_builder_rejects_invalid_resource_policy() {
        let error = Client::builder()
            .limits(Limits::default().connections_per_origin(0))
            .build()
            .unwrap_err();
        assert!(error.is_request());
    }
}