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
impl Proxy
Sourcepub fn from_env() -> Result<Vec<Self>>
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
impl Proxy
Sourcepub fn new(endpoint: impl AsRef<str>) -> Result<Self>
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.
Sourcepub fn with_schemes(self, schemes: ProxySchemes) -> Self
pub fn with_schemes(self, schemes: ProxySchemes) -> Self
Carry only origins with these schemes.
Sourcepub fn with_connect_header(
self,
name: impl Into<HeaderName<'static>>,
value: impl Into<HeaderValues>,
) -> Self
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.
Sourcepub fn except<I>(self, entries: I) -> Result<Self>
pub fn except<I>(self, entries: I) -> Result<Self>
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.
Sourcepub fn schemes(&self) -> ProxySchemes
pub fn schemes(&self) -> ProxySchemes
The origin schemes this proxy carries.
Sourcepub fn connect_headers(&self) -> &Headers
pub fn connect_headers(&self) -> &Headers
The headers sent to the proxy with CONNECT.