pub enum ProxyMode {
None,
Environment,
Explicit(String),
System,
SystemForUrl(String),
}Expand description
How requests reach the network.
Threat model. A direct connection is the strongest case: this crate resolves the
name, checks every address and connects to exactly those addresses. Through a proxy it
cannot: the proxy resolves the destination name itself, so the address a connection
reaches cannot be checked or pinned here. The guarantee through a proxy is therefore
name- and literal-based, and weaker than a direct connection. ProxyMode::None stays
the default for that reason.
With a proxy:
- The proxy endpoint is trusted (it is user or administrator configuration, often on a
private address such as
http://10.0.0.5:3128). It gets no address-class denial. Onlyhttpandhttpsproxies are accepted. - Every destination is still vetted: IP literals (and
localhost) by class, hostnames by the name rules (localhost,*.localhost,*.local,*.internaland single-label names are refused unless anallow_ifrule lists the host), cloud metadata names, and the first-party host pin.deny_rangesanddeny_ifapply to literals only, because a hostname’s address is not known. A hostname that resolves to a private address at the proxy is not caught. - Every redirect hop is vetted the same way.
- Hosts that match
NO_PROXYconnect directly and get the full direct-connection check. ClientConfig::proxy_bypass_first_partyskips the proxy for a first-party client.
The proxy is trusted: it sees destinations and can forward anywhere. Credentials in a
proxy URL never appear in Debug output or errors.
Variants§
None
No proxy. Environment proxy variables are ignored. This is the default.
Environment
ALL_PROXY, HTTPS_PROXY, HTTP_PROXY (first set, either case) and NO_PROXY.
Explicit(String)
A proxy URL such as http://proxy.corp:3128 or socks5://127.0.0.1:1080.
System
The proxy the operating system is configured with for the current user.
Windows: the static proxy and bypass list of the system proxy settings, resolved per
request URL (since 0.3.2): the scheme’s own endpoint (http=a:80;https=b:443, a
scheme with none connects directly) and the bypass list evaluated for that URL’s host,
including <local>, wildcards anywhere, .suffix and scheme-limited entries. This
applies to every hop, so a redirect to another host is routed on its own. Nothing is
refused for being per-scheme or per-host. A proxy auto-config script is still
HttpError::SystemProxyUnsupported and
nothing is sent (use ProxyMode::SystemForUrl for a PAC script). With one endpoint
for both schemes and a bypass list of plain hosts the client holds that one proxy, as
before; proxy_diagnostic is None when the choice is made per request.
“Automatically detect settings” (the Windows default) with no static
proxy and no PAC script is not an error: the environment proxy variables are used
when set and a direct connection otherwise, reported through Client::proxy_mode_used
and AsyncClient::proxy_mode_used (ProxyModeUsed::SystemFallbackEnvironment,
ProxyModeUsed::SystemFallbackDirect). With a static proxy the detection flag is
ignored. When nothing is configured, and on other systems, this is
ProxyMode::Environment. Android is one of those other systems: the proxy set in
Android’s Wi-Fi settings (ConnectivityManager) is not read, and a process on Android
normally has no proxy environment variables, so this is a direct connection unless the
app sets them. An app that must honour the device proxy passes it as
ProxyMode::Explicit.
SystemForUrl(String)
The proxy the operating system routes this URL through, resolved per URL when the client is built (since 0.3.2).
Windows: uses WinHTTP’s own resolver (WinHttpGetProxyForUrl) for the PAC script
and/or “Automatically detect settings” (WPAD), and otherwise the static proxy with its
bypass list evaluated exactly for this URL (<local>, wildcards, scheme-limited
entries, different proxies per scheme). Nothing is refused for being per-URL. The
result is one proxy (or none) for the client, so build one client per target host:
a redirect to another host reuses the decision made for this URL. A PAC script that
is set but cannot be evaluated is
HttpError::SystemProxyUnsupported; a
failed automatic detection alone (no WPAD on the network) falls back to the static
proxy, then the environment proxy variables, then a direct connection. The URL must be
http or https, otherwise the client fails closed with
HttpError::InvalidRequest. Reported through
proxy_mode_used as ProxyModeUsed::SystemForUrl (or a fallback). Other systems:
as ProxyMode::Environment.