Summary

The HTTP Client request timeout set via java.net.http.HttpRequest.Builder::timeout previously applied only until the response headers were received. Its scope has now been extended to also cover the consumption of the response body, if present.

Problem

When java.net.http.HttpRequest.Builder::timeout was first introduced, response body was intentionally excluded, as its retrieval and consumption could take significantly longer than receiving the headers. However, subsequent user feedback indicated that this behavior was counterintuitive to most users' expectations, and implementing a manual timeout for the response body consumption is proved to be non-trivial.

Solution

We have clarified the API specification around timeouts, and extended the scope of the JDK's implementation of java.net.http.HttpRequest.Builder::timeout to cover the consumption of the response body.

Specification

src/java.net.http/share/classes/java/net/http/HttpClient.java
@@ -308,10 +308,18 @@ public interface Builder {
          * need to be established, for example if a connection can be reused
          * from a previous request, then this timeout duration has no effect.
          *
+         * @implSpec
+         * When a connection timeout is configured, an {@link HttpClient}
+         * implementation applies it to the entire connection phase, from the
+         * moment a connection is requested until it is established. The
+         * elapsed time includes any SSL/TLS handshake.
+         *
          * @param duration the duration to allow the underlying connection to be
          *                 established
          * @return this builder
          * @throws IllegalArgumentException if the duration is non-positive
+         * @see HttpRequest.Builder#timeout(Duration) Configuring timeout for
+         * request execution
          */
         public Builder connectTimeout(Duration duration);

src/java.net.http/share/classes/java/net/http/HttpRequest.java
@@ -258,12 +258,29 @@ public interface Builder {
          * {@link HttpClient#sendAsync(java.net.http.HttpRequest,
          * java.net.http.HttpResponse.BodyHandler) HttpClient::sendAsync}
          * completes exceptionally with an {@code HttpTimeoutException}. The effect
-         * of not setting a timeout is the same as setting an infinite Duration,
-         * i.e. block forever.
+         * of not setting a timeout is the same as setting an infinite
+         * {@code Duration}, i.e., block forever.
+         *
+         * @implSpec
+         * When a timeout is configured, an {@link HttpClient} implementation
+         * should apply it over the duration measured from the instant the
+         * request execution starts to, <em>at least</em>, the instant an
+         * {@link HttpResponse} is constructed. The elapsed time includes
+         * obtaining a connection for transport and retrieving the response
+         * headers.
+         *
+         * @implNote
+         * When a timeout is configured, the JDK built-in implementation of the
+         * {@link HttpClient} applies it over the duration measured from the
+         * instant the request execution starts to <b>the instant the response
+         * body is consumed</b>, if present. This is implemented by stopping
+         * the timer after the response body subscriber completion.
          *
          * @param duration the timeout duration
          * @return this builder
          * @throws IllegalArgumentException if the duration is non-positive
+         * @see HttpClient.Builder#connectTimeout(Duration) Configuring
+         * timeout for connection establishment
          */
         public abstract Builder timeout(Duration duration);

src/java.net.http/share/classes/java/net/http/WebSocket.java
@@ -144,6 +144,12 @@ interface Builder {
          * {@link HttpTimeoutException}. If this method is not invoked then the
          * infinite timeout is assumed.
          *
+         * @implSpec
+         * When a connection timeout value is present, a {@link WebSocket}
+         * implementation should apply it over the duration measured from the
+         * instant a connection is requested to the instant that one is
+         * established. This duration includes SSL handshakes, if required.
+         *
          * @param timeout
          *         the timeout, non-{@linkplain Duration#isNegative() negative},
          *         non-{@linkplain Duration#ZERO ZERO}
          *
          * @return this builder
          */
         Builder connectTimeout(Duration timeout);