rust-http-client

Rust HTTP クライアント

送信 HTTP はリソースであり、信頼境界でもあるものとして扱います。設定済みのクライアントを再利用し、すべての段階に上限を設け、プロトコルエラーを保持し、リトライ、認証情報、プロキシ、宛先のポリシーを明示します。

適用範囲と振り分け

HTTP/1.1、HTTP/2、オプションの HTTP/3 サポート、リクエストの構築、接続プール、DNS、プロキシ、TLS、リダイレクト、リトライ、ストリーミング、クライアント側のテストには、このスキルを使用します。

受信側のルーターやハンドラーは rust-web に、SSRF と認証情報のポリシーは rust-web-security に、タスクのライフサイクルと大量の並行処理は rust-concurrency に、テレメトリーは rust-observability に振り分けます。生の TCP/UDP やプロトコルの実装は、後続のネットワークプロトコル用スキルに振り分けます。

ワークフロー

1. リモートとの契約を定義する

ベース URL、メソッド、パスとクエリのエンコーディング、ヘッダー、認証、リクエストとレスポンスのスキーマ、ステータスの意味、冪等性、本文の上限、ページネーション、レート制限、タイムアウトの予算、リトライポリシー、プロキシと TLS の要件、サポート対象プラットフォームを記録します。ロックファイルに記載された依存関係のバージョンと有効な機能を確認します。

2. 設定済みのクライアントを作成して再利用する

通常のアプリケーション HTTP には reqwest::Client を使用します。接続プーリングを維持するために再利用します。最適化できそうだというだけではなく、より低レベルの接続、本文、またはプロトコル制御が実際に必要な場合は Hyper を使用します。

use std::time::Duration;

let client = reqwest::Client::builder()
    .connect_timeout(Duration::from_secs(3))
    .timeout(Duration::from_secs(15))
    .redirect(reqwest::redirect::Policy::limited(3))
    .build()?;

リクエストごとにクライアントを作成しないでください。システムプロキシ、リダイレクト、Cookie、圧縮、ネイティブのルート証明書、カスタムルート証明書を許可するかどうかを慎重に決めます。クライアントの設定とトランスポートを参照してください。

3. リクエストとレスポンスに上限を設ける

• サポートされる場合は、全体のデッドラインに加えて、段階ごとの制限を適用します。
• 大きな本文を割り当てる前に、同時に処理するリクエスト数に上限を設けます。
• 信頼できないコンテンツをバッファリングせず、アップロードとダウンロードをストリーミングします。
• 通知された本文サイズと、実際にデコードされた本文サイズの両方を制限します。Content-Length がない場合や、誤解を招く値の場合もあります。
• ページネーション、リダイレクト、展開、リトライ、エラー本文の取得に上限を設けます。
• リクエストの future を破棄するか、future を対象とした選択処理を行うことでキャンセルを保持し、呼び出し元の境界でクリーンアップを確認します。

4. 安全な操作だけをリトライする

操作が冪等であるか、冪等性キーで保護されている場合に限り、トランスポート障害や選択したステータスをリトライします。試行回数に上限を設け、ジッターを加えた指数バックオフ、全体のデッドライン、有効な場合は Retry-After などのサーバーからのヒントを使用します。認証失敗や、すべての 5xx を無条件にリトライしないでください。タイムアウト、リトライ、同時実行数制限、レート制限、負荷抑制、サーキットブレーカーのポリシーを、順序を明記して配置します。レジリエンスとバックプレッシャーを参照してください。

5. 信頼境界を適用する

• url で宛先を解析します。信頼できない URL を連結しないでください。
• ユーザーが制御する宛先では、スキーム、ホスト、ポート、リダイレクト先、DNS の結果、プライベートアドレスやリンクローカル範囲を制限します。
• 認証情報の適用先を承認済みのオリジンに限定し、オリジンをまたぐリダイレクトでは機密ヘッダーを削除します。
• TLS 検証を有効に保ちます。カスタムルート証明書、クライアント証明書、SNI、ALPN、鍵ログを確認します。
• 環境変数で設定されたプロキシを信頼するかどうかを決めます。必要に応じて no_proxy または明示的なプロキシルールを使用します。

セキュリティポリシーについては rust-web-security と調整してください。

6. 複数の境界でテストする

• リクエストの構築、URL エンコーディング、認証の選択、リトライの判断、レスポンスのマッピングを単体テストします。
• モックサーバーを使用し、ステータス、ヘッダー、遅延、リダイレクト、途中で切れた本文、不正なペイロードをテストします。
• ソケット、ストリーミング、キャンセル、プーリング、プロキシ、TLS の動作には、実際のローカルサーバーを使用します。
• CI で安定して実行でき、かつ許可されている場合に限り、小規模な外部サンドボックスまたはプロバイダーの契約テストを使用します。

HTTP クライアントのテストを参照してください。

完了条件

• 明示的な機能、プロキシ、リダイレクト、DNS、TLS のポリシーを設定してクライアントを再利用します。
• デッドライン、並行数、リトライ、リダイレクト、ページネーション、本文サイズに上限を設定します。
• トランスポート、プロトコル、デコード、アプリケーションの各エラーを構造化された状態で保持します。
• リプレイ可能であることが実証された操作のみをリトライします。
• 宛先やリダイレクトを通じた認証情報の漏えいと SSRF を防ぎます。
• 成功、タイムアウト、過負荷、リダイレクト、大きな本文、不正なレスポンス、キャンセルの各経路をテストします。

リソース

• クライアントの設定とトランスポート
• レジリエンスとバックプレッシャー
• HTTP クライアントのテスト
• 実行シナリオ
• examples/golden-http-client/：ローカルサーバーを対象とする、コンパイル済みの上限制御付きブロッキングクライアントです。

上流ソース

• reqwest
• Hyper
• Tower
• rustls
• url

データプライバシー

このスキルはユーザーデータを収集、保存、送信しません。明示的な許可なく、テスト中に実際の認証情報、顧客のペイロード、非公開のエンドポイントを送信しないでください。