tez 0.0.2

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
/// environment and supported operating-system proxy 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(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 or HTTPS origin without a path, query,
    /// or fragment. User information is allowed for proxy credentials. The
    /// explicit policy ignores process proxy settings, including `NO_PROXY`.
    #[must_use]
    pub fn all(url: impl AsRef<str>) -> Self {
        Self(Kind::All(url.as_ref().to_owned()))
    }

    /// Discovers proxy routing from conventional environment and supported
    /// operating-system settings.
    ///
    /// 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(_) => formatter.write_str("Policy::All"),
            #[cfg(feature = "system-proxy")]
            Kind::System => formatter.write_str("Policy::System"),
        }
    }
}