mirror of
https://github.com/yhirose/cpp-httplib.git
synced 2026-06-11 09:07:15 +00:00
Document set_no_proxy and set_proxy_from_env in README
Adds two subsections under "Proxy server support":
- "Bypass the proxy for specific hosts (NO_PROXY)" — set_no_proxy,
pattern syntax, dot-boundary rule, IP normalization, limitations
(no port-specific entries, no v4-mapped v6 cross-match, replace
semantics).
- "Read proxy settings from the environment" — set_proxy_from_env,
which variables are read, the lowercase-only http_proxy rule with
an inline httpoxy / CVE-2016-5385 explanation, threading
expectations.
Documentation only. Closes the doc gap from #2446.
This commit is contained in:
70
README.md
70
README.md
@@ -1178,6 +1178,76 @@ cli.set_proxy_bearer_token_auth("pass");
|
||||
> [!NOTE]
|
||||
> OpenSSL is required for Digest Authentication.
|
||||
|
||||
#### Bypass the proxy for specific hosts (`NO_PROXY`)
|
||||
|
||||
`set_no_proxy` configures a bypass list. Each pattern is one of:
|
||||
|
||||
- `*` — bypass the proxy for every target
|
||||
- a hostname suffix, e.g. `example.com` — matches `example.com` and any
|
||||
subdomain (`foo.example.com`). A leading dot (`.example.com`) is
|
||||
permitted but informational; both forms are equivalent.
|
||||
- a single IP literal, e.g. `192.168.1.1`, `::1`
|
||||
- a CIDR block, e.g. `10.0.0.0/8`, `fe80::/10`
|
||||
|
||||
```cpp
|
||||
cli.set_proxy("proxy.corp", 3128);
|
||||
cli.set_no_proxy({"internal.corp", "10.0.0.0/8", "*.dev.local"});
|
||||
```
|
||||
|
||||
When a NO_PROXY entry matches the target host, the request is sent
|
||||
directly and the corresponding `Proxy-Authorization` header is
|
||||
suppressed.
|
||||
|
||||
Hostname matching is **case-insensitive** and uses a dot-boundary rule,
|
||||
so `evilexample.com` does **not** match an entry of `example.com`. IP
|
||||
comparisons are normalized through `inet_pton`, so `127.0.0.1` cannot
|
||||
be bypassed via alternate string forms (e.g. leading-zero octets or
|
||||
decimal-form integers). Malformed entries are silently dropped.
|
||||
|
||||
Limitations:
|
||||
|
||||
- Port-specific entries (`example.com:8080`) are not supported. cpp-httplib's
|
||||
other host-keyed APIs (e.g. `set_hostname_addr_map`) are also keyed on
|
||||
hostname only; supporting host:port for NO_PROXY alone would be
|
||||
inconsistent.
|
||||
- IPv4-mapped IPv6 addresses (`::ffff:1.2.3.4`) are not cross-matched
|
||||
against IPv4 NO_PROXY entries.
|
||||
- `set_no_proxy` replaces any previously configured list; there is no
|
||||
append API.
|
||||
|
||||
#### Read proxy settings from the environment
|
||||
|
||||
`set_proxy_from_env` configures the client from proxy-related
|
||||
environment variables.
|
||||
|
||||
```cpp
|
||||
httplib::Client cli("https://api.example.com");
|
||||
cli.set_proxy_from_env();
|
||||
```
|
||||
|
||||
Variables read:
|
||||
|
||||
- `https_proxy` / `HTTPS_PROXY` — used by HTTPS clients (`SSLClient`)
|
||||
- `http_proxy` (lowercase only — see security note below) — used by HTTP clients
|
||||
- `no_proxy` / `NO_PROXY` — comma-separated list of bypass patterns
|
||||
|
||||
Returns `true` if at least one variable was found and applied.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The uppercase `HTTP_PROXY` is intentionally ignored to mitigate the
|
||||
> "httpoxy" class of bugs ([CVE-2016-5385](https://httpoxy.org/)). In
|
||||
> CGI / FastCGI environments the variable name collides with the
|
||||
> `HTTP_*` namespace used to expose request headers, allowing a remote
|
||||
> attacker to set the proxy URL via the `Proxy:` request header.
|
||||
> cpp-httplib follows curl, Go, and Python `requests` in honoring only
|
||||
> the lowercase `http_proxy`. `HTTPS_PROXY` and `NO_PROXY` are safe in
|
||||
> either case because their names do not begin with `HTTP_`.
|
||||
|
||||
> [!NOTE]
|
||||
> `set_proxy_from_env` reads `getenv` synchronously. Call it once at
|
||||
> startup before issuing any requests; concurrent `setenv` from other
|
||||
> threads is undefined.
|
||||
|
||||
### Range
|
||||
|
||||
```cpp
|
||||
|
||||
Reference in New Issue
Block a user