.NET の HttpClient の Timeout は何の時間切れを指しているのか

.NET プログラミングにおける、HTTP 要求送信に使われる、System.Net.Http 名前空間の HttpClient クラスの話。

HttpClient クラスには TimeSpan 型の "Timeout" というパブリックプロパティが設けられている。下記公式ドキュメントの説明に依れば「要求がタイムアウトするまで待機する期間を取得または設定」するプロパティであるとのこと。

しかし自分は、この HttpClient.Timeout プロパティによる "HTTP 要求のタイムアウト (時間切れ)" がどのように・何に対して機能するのかよくわかっていなかった。相手先サーバーとの TCP 接続が確立されるまでの時間なのだろうか? 接続が確立してから最初の応答バイト列が返ってくるまでの時間なのだろうか? ある程度応答が返ってきても、すべての応答が返却し終わる前に暫し応答が来なくなったらそれはタイムアウトになるのだろうか?

今までちゃんと理解しないで HttpClient を使ってきたので、今回、改めて調べてみることにした。なお、.NET ランタイムは GtHub 上でソースコードが公開されているので (下記リンク先)、ソースコードを確認すればこれら挙動について理解できることとも思う。

だが今回は実験方式で、 ASP.NET Core Minimal API による HTTP Web API サーバーと、その API サーバーに HttpClient を使って HTTP 要求を送信するコンソールアプリケーションとを C# でそれぞれ実装して、実際に実行して動作を観察してみた。

API サーバー側の C# ソースコードは以下。"/hello" の URL パスに HTTP GET 要求を送ると、"World!" の文字列が返却される。

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/hello", () => "World!");
app.Run();

コンソールアプリケーション側の C# ソースコードは以下。前述の API サーバーの "/hello" へ HTTP GET 要求で文字列取得を試みるコードだ。以下では HttpClient の Timeout には 3 秒を設定してある。

using var httpClient = new HttpClient {
    Timeout = TimeSpan.FromSeconds(3),
    BaseAddress = new Uri("http://localhost:****")
};
var message = await httpClient.GetStringAsync("hello");

Console.WriteLine($"message: [{message}]");

TCP 接続が確立できないとき

接続先のホスト上でこの API サーバーが起動していない場合や、指定した IP アドレスではホストが TCP ネットワーク上に存在しない場合など、そもそも TCP 接続が確立しない場合を確認してみた。

この場合、HttpClient の Timeout プロパティに指定した時間が経過したのち、TaskCanceledException 例外が発生した。

Unhandled exception. System.Threading.Tasks.TaskCanceledException:
The request was canceled due to the configured HttpClient.Timeout of 3 seconds elapsing.
 ---> System.TimeoutException: A task was canceled.
 ---> System.Threading.Tasks.TaskCanceledException: A task was canceled.

なお、HttpClient からの HTTP 要求送信開始後 (GetStringAsync 呼び出し後)、Timeout プロパティに指定した時間が経過してしまう前に、API サーバー側プロセスを起動するなどして TCP 確立が成功する状態にすると、例外は発生せずに要求は成功した。

TCP 接続は成功するが、最初の応答がすぐに返らないとき

API サーバー側実装を以下のように変え、最初の応答を返すまで指定時間待機するようにしてみた。

app.MapGet("/hello", async () => {
    await Task.Delay(4000); // 4秒待つ
    return "World!";
});

念のため curl コマンドで "curl -i http://localhost:***/hello" を実行し、応答ボディのみならず最初の応答ヘッダも含めて、Task.Delay() で指定した時間、何の応答も返らないことを確認する。

この状態でコンソールアプリ側を実行すると、HttpClient の Timeout プロパティに指定した時間が経過したのち、TaskCanceledException 例外が発生した。例外中のコールスタックが、そもそも TCP 接続が確立できなかった場合に比べて微妙に変わっている。

Unhandled exception. System.Threading.Tasks.TaskCanceledException:
The request was canceled due to the configured HttpClient.Timeout of 3 seconds elapsing.
 ---> System.TimeoutException: The operation was canceled.
 ---> System.Threading.Tasks.TaskCanceledException: The operation was canceled.
 ---> System.IO.IOException: Unable to read data from the transport connection: The I/O operation has been aborted because of either a thread exit or an application request.

TCP 接続は成功し、最初の応答もすぐ返るが、すべての応答に時間がかかるとき

さらに API サーバー側実装を以下のように変え、最初の応答はすぐに返るが、すべての応答を実施しきるまでに数百ミリ秒の待機を挟みながら、だらだら応答を続けるようにしてみる。

var utf8 = Encoding.UTF8;
app.MapGet("/hello", async (HttpResponse res) => {
    foreach (var term in new[] { "lorem", "ipsum", "dolor", "sit", "amet" })
    {
        await res.BodyWriter.WriteAsync(utf8.GetBytes(term + " "));
        await res.BodyWriter.FlushAsync();
        await Task.Delay(600);
    }
});

こちらも念のため curl コマンドで動作を確認しておく。

この状態でコンソールアプリ側を実行すると、この場合も同じく、HttpClient の Timeout プロパティに指定した時間が経過したのち、TaskCanceledException 例外が発生した。

Unhandled exception. System.Threading.Tasks.TaskCanceledException:
The request was canceled due to the configured HttpClient.Timeout of 3 seconds elapsing.
 ---> System.TimeoutException: The operation was canceled.
 ---> System.Threading.Tasks.TaskCanceledException: The operation was canceled.
 ---> System.IO.IOException: Unable to read data from the transport connection: The I/O operation has been aborted because of either a thread exit or an application request.

まとめ

以上の実験と観察結果を見ると、どうやら、HttpClient の Timeout プロパティに指定したタイムアウト時間というのは、「HTTP 要求を開始してから、すべての応答を受信し終わるまでの時間全体」を指しているらしい。

そもそも TCP 接続が確立できないままタイムアウト時間が経過した場合はもちろん、HTTP 応答が断片的に返って来続けている場合でも、Timeout プロパティに指定されたタイムアウト時間が経過してしまったら、TaskCanceledException 例外で中断されるようだ。また、タイムアウトが発生した場合は、発生理由の如何に依らず一律、TaskCanceledException 例外のスローという形で表現されることもわかった。

なお、今回は HttpClient の GetStringAsync メソッドに基づく実験だったが、GetStreamAsync で応答ストリームを入手してそのストリームから読み取りを繰り返すような場合は、もしかするともう少し違った挙動になるかもしれない。そうでないと、MJPEG をはじめ、HTTP 上でのストリーミング通信ができないのではないかと想像される。

今後要確認である。