tez 0.0.3

A lightweight, ergonomic, and fast high-level HTTP client for Rust
Documentation
//! Routing policies for HTTP(S) proxies.

use std::fmt;

/// The proxy-routing policy for a client.
///
/// Clients connect directly by default. Use [`Policy::all`] to route every
/// HTTP and HTTPS request through one explicit proxy. With Tez's optional
/// `system-proxy` Cargo feature, `Policy::system()` opts into conventional
/// proxy environment discovery.
///
/// Policy values retain proxy URLs without validating them. Invalid URLs are
/// reported by [`crate::ClientBuilder::build`] without exposing credentials.
#[derive(Clone)]
pub struct Policy(Kind);

#[derive(Clone)]
pub(crate) enum Kind {
    Direct,
    All {
        url: String,
        bypass: Vec<String>,
    },
    #[cfg(feature = "system-proxy")]
    System,
}

impl Policy {
    /// Connects directly without a proxy.
    ///
    /// This is the default. It is useful when application configuration
    /// selects a proxy policy dynamically.
    #[must_use]
    pub const fn direct() -> Self {
        Self(Kind::Direct)
    }

    /// Routes every HTTP and HTTPS request through one explicit proxy.
    ///
    /// `url` must be an absolute HTTP, HTTPS, or `socks5h` origin without a
    /// path, query, or fragment. `socks5h` delegates destination DNS to the
    /// proxy. User information is allowed for proxy credentials. The explicit
    /// policy ignores process proxy settings; use [`Policy::exclude`] for its
    /// bypass list.
    #[must_use]
    pub fn all(url: impl AsRef<str>) -> Self {
        Self(Kind::All {
            url: url.as_ref().to_owned(),
            bypass: Vec::new(),
        })
    }

    /// Bypasses an explicit proxy for matching hosts, domains, addresses, or
    /// CIDR networks.
    ///
    /// Entries use `NO_PROXY` syntax and may include a port. This has no effect
    /// on direct or system proxy policies; system policies use `NO_PROXY`.
    #[must_use]
    pub fn exclude<I, S>(mut self, entries: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: AsRef<str>,
    {
        if let Kind::All { bypass, .. } = &mut self.0 {
            bypass.extend(
                entries
                    .into_iter()
                    .map(|entry| entry.as_ref().trim().to_ascii_lowercase())
                    .filter(|entry| !entry.is_empty()),
            );
        }
        self
    }

    /// Discovers proxy routing from conventional process environment.
    ///
    /// This reads `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and `NO_PROXY`,
    /// along with their lowercase forms, when [`crate::ClientBuilder::build`]
    /// is called. The resulting client does not observe later changes.
    #[cfg(feature = "system-proxy")]
    #[must_use]
    pub const fn system() -> Self {
        Self(Kind::System)
    }

    pub(crate) fn into_kind(self) -> Kind {
        self.0
    }
}

impl Default for Policy {
    fn default() -> Self {
        Self::direct()
    }
}

impl fmt::Debug for Policy {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match &self.0 {
            Kind::Direct => formatter.write_str("Policy::Direct"),
            Kind::All { bypass, .. } => formatter
                .debug_struct("Policy::All")
                .field("bypass_count", &bypass.len())
                .finish_non_exhaustive(),
            #[cfg(feature = "system-proxy")]
            Kind::System => formatter.write_str("Policy::System"),
        }
    }
}