Document NO_PROXY and set_proxy_from_env in cookbook c16-proxy

Replaces the now-incorrect Note at the bottom of c16-proxy ("cpp-httplib
does not read HTTP_PROXY...") with the actual API.

JA is the master per the project's translation workflow; the EN
translation lands in the same PR. Both pages remain `status: "draft"`
for normal review.

Adds two sections:

  - Bypass the proxy for specific hosts (set_no_proxy):
    pattern syntax, dot-boundary rule, case-insensitivity, IP
    normalization via inet_pton, port-specific-entries unsupported,
    malformed entries dropped.

  - Read proxy settings from the environment (set_proxy_from_env):
    which variables are read, lowercase-only http_proxy with an
    inline httpoxy / CVE-2016-5385 explanation, threading caveat.
This commit is contained in:
yhirose
2026-05-08 23:23:14 +09:00
parent da2621ed9f
commit 26569b42fa
2 changed files with 80 additions and 2 deletions

View File

@@ -49,4 +49,43 @@ cli.set_bearer_token_auth("api-token"); // エンドサーバー向け
プロキシには`Proxy-Authorization`、エンドサーバーには`Authorization`ヘッダーが送られます。
> **Note:** 環境変数の`HTTP_PROXY`や`HTTPS_PROXY`は自動的には読まれません。必要ならアプリケーション側で読み取って`set_proxy()`に渡してください。
## 特定のホストだけプロキシをバイパスする
社内エンドポイントなどはプロキシを経由させたくないことがあります。`set_no_proxy()`で除外リストを指定できます。
```cpp
cli.set_proxy("proxy.internal", 8080);
cli.set_no_proxy({"internal.corp", "10.0.0.0/8", "*.dev.local"});
```
エントリは次のいずれかです。
- `*` — すべてのホストでバイパス
- ホスト名サフィックス(例: `example.com`)— `example.com`本体と任意のサブドメイン(`foo.example.com`)にマッチ。先頭にドットを付けても同じ意味です(`.example.com`)。
- 単一のIPリテラル例: `192.168.1.1``::1`
- CIDRブロック例: `10.0.0.0/8``fe80::/10`
ホスト名のマッチは大文字小文字を区別せず、ドット境界でしか一致しません。たとえば`example.com`というエントリは`evilexample.com`にはマッチしません。IPの比較は`inet_pton`で正規化されるので、`127.0.0.1``127.000.000.001`のような別表記でバイパスすることはできません。マッチした場合、`Proxy-Authorization`ヘッダーも自動的に外れます。
不正な書式のエントリは黙って捨てられます。`example.com:8080`のようなポート指定エントリはサポート外ですcpp-httplibの他のホストキーAPIもホスト名のみを扱う設計のため
## 環境変数からプロキシ設定を読み込む
`set_proxy_from_env()`を呼ぶと、起動時の環境変数からプロキシ設定をまとめて取り込めます。
```cpp
httplib::Client cli("https://api.example.com");
cli.set_proxy_from_env();
```
読み込まれる変数:
- `https_proxy` / `HTTPS_PROXY` — HTTPSクライアントが使用
- `http_proxy`**小文字のみ**、後述)— HTTPクライアントが使用
- `no_proxy` / `NO_PROXY` — カンマ区切りのバイパスリスト
少なくとも1つの変数が見つかって適用されたら`true`を返します。
> **Security Note:** 大文字の`HTTP_PROXY`は意図的に**読まれません**。CGI/FastCGI環境では`HTTP_*`という名前空間がHTTPリクエストヘッダーの公開に使われており、攻撃者が`Proxy:`リクエストヘッダーで任意のプロキシURLを差し込めてしまうためです[CVE-2016-5385 / "httpoxy"](https://httpoxy.org/)。curl・Go・Python `requests`と同じく、cpp-httplibも小文字の`http_proxy`しか採用しません。`HTTPS_PROXY`や`NO_PROXY`は名前が`HTTP_`で始まらないので、どちらの大文字小文字でも安全です。
> **Note:** `set_proxy_from_env()`は同期的に`getenv`を呼ぶだけなので、起動時に1回呼ぶことを想定しています。他スレッドが同時に`setenv`しているケースは未定義です。