Skip to main content

Proxy

Struct Proxy 

Source
pub struct Proxy(/* private fields */);
Expand description

An outbound HTTP proxy: where to send requests, which origin schemes it carries, and which origins bypass it.

Install with Client::with_proxy, alone or as part of a ProxyRouter. Plain HTTP requests are forwarded to the proxy. HTTPS requests, and HTTP requests that need the origin’s own connection — upgrades such as WebSocket, HTTP/2 prior knowledge, and CONNECT — go through a CONNECT tunnel instead. A proxied request never falls back to a direct connection.

A Proxy-Authorization CONNECT header, including one derived from the endpoint URL’s user information, is sent with both forwarded requests and tunnels; other CONNECT headers are sent only with CONNECT. While a router is installed, a Proxy-Authorization header set on an individual request is removed, including on requests sent directly. Installing a proxy does not change which certificates the TLS connector trusts.

use trillium_client::{Proxy, ProxySchemes};

let proxy = Proxy::new("http://user:pass@proxy.example:8080")?
    .with_schemes(ProxySchemes::Https)
    .except(["localhost", "127.0.0.0/8", "[::1]", ".internal.example"])?;

Implementations§

Source§

impl Proxy

Source

pub fn from_env() -> Result<Vec<Self>>

The proxies configured by a snapshot of the process environment, as a list to install with Client::with_proxy.

Reads http_proxy/HTTP_PROXY, https_proxy/HTTPS_PROXY, all_proxy/ALL_PROXY, and no_proxy/NO_PROXY. Lowercase variables take precedence, including when empty. A missing or empty per-scheme proxy uses the all-proxy fallback. Uppercase HTTP_PROXY is ignored when REQUEST_METHOD is set: CGI, which always sets REQUEST_METHOD, passes a request’s Proxy header to the program as HTTP_PROXY.

The result is what the equivalent code would build: a Proxy::new for each configured endpoint, narrowed with Proxy::with_schemes to the scheme it serves (or left carrying both when only the all-proxy fallback is set), with the no_proxy list added to each through Proxy::except. An environment that configures no proxy produces an empty list, which connects directly, and so does a no_proxy entry of *, without reading the proxy variables it overrides.

The all-proxy fallback is only read when a scheme actually falls back to it, so an unusable all_proxy alongside usable per-scheme proxies is not an error. Ordinary client construction does not read these variables, and this method does not read certificate environment variables or change TLS trust.

§Errors

Returns io::ErrorKind::InvalidInput for non-Unicode values, malformed or unsupported proxy endpoints, or malformed bypass entries. The error names the variable the value came from, and identifies the offending entry for a bypass list.

Source§

impl Proxy

Source

pub fn new(endpoint: impl AsRef<str>) -> Result<Self>

A proxy at endpoint, carrying both HTTP and HTTPS origins.

endpoint is an http:// or https:// URL; without a scheme, http:// is assumed. URL user information becomes a Basic Proxy-Authorization CONNECT header, percent escapes decoded, and is removed from the stored endpoint. The path, query, and fragment don’t affect connections.

§Errors

Returns io::ErrorKind::InvalidInput for a malformed URL, an unsupported scheme, a URL without a host, or a username containing :. The error never includes the credentials.

Source

pub fn with_schemes(self, schemes: ProxySchemes) -> Self

Carry only origins with these schemes.

Source

pub fn with_connect_header( self, name: impl Into<HeaderName<'static>>, value: impl Into<HeaderValues>, ) -> Self

Send this header to the proxy with CONNECT, replacing any values it already has.

Proxy-Authorization is also sent with forwarded requests. Opening a tunnel fails if the CONNECT headers include Host, Content-Length, Transfer-Encoding, Connection, or Upgrade: the client writes Host itself, and a CONNECT request has no body and upgrades nothing.

Source

pub fn except<I>(self, entries: I) -> Result<Self>
where I: IntoIterator, I::Item: AsRef<str>,

Connect directly to origins matching any of these bypass entries, in addition to any already added.

Each entry is one domain name, IP address, or CIDR network, written exactly. Entries are matched against the URL host without resolving DNS. A domain matches itself and its subdomains at label boundaries, so example.com matches a.example.com but not notexample.com; a leading . or *. is optional, and case and trailing dots are ignored. An optional :port limits an entry to that effective URL port; bracket an IPv6 literal that has a port, as in [::1]:8080. IP addresses and networks match IP-literal URLs, not addresses a domain resolves to.

§Errors

Returns io::ErrorKind::InvalidInput, naming the entry, for one that is malformed, empty, has surrounding whitespace, or contains a comma, and for *, which would leave the proxy carrying nothing.

Source

pub fn endpoint(&self) -> &Url

The proxy’s URL, without credentials.

Source

pub fn schemes(&self) -> ProxySchemes

The origin schemes this proxy carries.

Source

pub fn connect_headers(&self) -> &Headers

The headers sent to the proxy with CONNECT.

Trait Implementations§

Source§

impl Clone for Proxy

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Proxy

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl ProxyRouter for Proxy

Source§

fn route(&self, url: &Url) -> Option<Proxy>

The proxy for a request to url, or None to connect directly.

Auto Trait Implementations§

§

impl Forget for Proxy

§

impl Freeze for Proxy

§

impl RefUnwindSafe for Proxy

§

impl Send for Proxy

§

impl Sync for Proxy

§

impl Unpin for Proxy

§

impl UnsafeUnpin for Proxy

§

impl UnwindSafe for Proxy

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more