Add APIs to configure the client's default call timeout.

okhttp-tests/src/test/java/okhttp3/OkHttpClientTest.java

@@ -53,6 +53,7 @@ public final class OkHttpClientTest {
 
   @Test public void durationDefaults() {
     OkHttpClient client = defaultClient();
+    assertEquals(0, client.callTimeoutMillis());
     assertEquals(10_000, client.connectTimeoutMillis());
     assertEquals(10_000, client.readTimeoutMillis());
     assertEquals(10_000, client.writeTimeoutMillis());
@@ -61,6 +62,10 @@ public final class OkHttpClientTest {
 
   @Test public void timeoutValidRange() {
     OkHttpClient.Builder builder = new OkHttpClient.Builder();
+    try {
+      builder.callTimeout(1, TimeUnit.NANOSECONDS);
+    } catch (IllegalArgumentException ignored) {
+    }
     try {
       builder.connectTimeout(1, TimeUnit.NANOSECONDS);
     } catch (IllegalArgumentException ignored) {
@@ -73,6 +78,10 @@ public final class OkHttpClientTest {
       builder.readTimeout(1, TimeUnit.NANOSECONDS);
     } catch (IllegalArgumentException ignored) {
     }
+    try {
+      builder.callTimeout(365, TimeUnit.DAYS);
+    } catch (IllegalArgumentException ignored) {
+    }
     try {
       builder.connectTimeout(365, TimeUnit.DAYS);
     } catch (IllegalArgumentException ignored) {

okhttp-tests/src/test/java/okhttp3/WholeOperationTimeoutTest.java

@@ -28,6 +28,7 @@
 import org.junit.Test;
 
 import static okhttp3.TestUtil.defaultClient;
+import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.assertTrue;
@@ -41,6 +42,27 @@ public final class WholeOperationTimeoutTest {
 
   private OkHttpClient client = defaultClient();
 
+  @Test public void defaultConfigIsNoTimeout() throws Exception {
+    Request request = new Request.Builder()
+        .url(server.url("/"))
+        .build();
+    Call call = client.newCall(request);
+    assertEquals(0, call.timeout().timeoutNanos());
+  }
+
+  @Test public void configureClientDefault() throws Exception {
+    Request request = new Request.Builder()
+        .url(server.url("/"))
+        .build();
+
+    OkHttpClient timeoutClient = client.newBuilder()
+        .callTimeout(456, TimeUnit.MILLISECONDS)
+        .build();
+
+    Call call = timeoutClient.newCall(request);
+    assertEquals(TimeUnit.MILLISECONDS.toNanos(456), call.timeout().timeoutNanos());
+  }
+
   @Test public void timeoutWritingRequest() throws Exception {
     server.enqueue(new MockResponse());
 

okhttp/src/main/java/okhttp3/Call.java

@@ -82,8 +82,11 @@ public interface Call extends Cloneable {
   boolean isCanceled();
 
   /**
-   * Returns a timeout that applies to the entire call: writing the request, server processing,
-   * and reading the response.
+   * Returns a timeout that spans the entire call: resolving DNS, connecting, writing the request
+   * body, server processing, and reading the response body. If the call requires redirects or
+   * retries all must complete within one timeout period.
+   *
+   * <p>Configure the client's default timeout with {@link OkHttpClient.Builder#callTimeout}.
    */
   Timeout timeout();
 

okhttp/src/main/java/okhttp3/OkHttpClient.java

@@ -221,6 +221,7 @@ public void apply(ConnectionSpec tlsConfiguration, SSLSocket sslSocket, boolean
   final boolean followSslRedirects;
   final boolean followRedirects;
   final boolean retryOnConnectionFailure;
+  final int callTimeout;
   final int connectTimeout;
   final int readTimeout;
   final int writeTimeout;
@@ -272,6 +273,7 @@ public OkHttpClient() {
     this.followSslRedirects = builder.followSslRedirects;
     this.followRedirects = builder.followRedirects;
     this.retryOnConnectionFailure = builder.retryOnConnectionFailure;
+    this.callTimeout = builder.callTimeout;
     this.connectTimeout = builder.connectTimeout;
     this.readTimeout = builder.readTimeout;
     this.writeTimeout = builder.writeTimeout;
@@ -295,6 +297,11 @@ private static SSLSocketFactory newSslSocketFactory(X509TrustManager trustManage
     }
   }
 
+  /** Default call timeout (in milliseconds). */
+  public int callTimeoutMillis() {
+    return callTimeout;
+  }
+
   /** Default connect timeout (in milliseconds). */
   public int connectTimeoutMillis() {
     return connectTimeout;
@@ -457,6 +464,7 @@ public static final class Builder {
     boolean followSslRedirects;
     boolean followRedirects;
     boolean retryOnConnectionFailure;
+    int callTimeout;
     int connectTimeout;
     int readTimeout;
     int writeTimeout;
@@ -482,6 +490,7 @@ public Builder() {
       followSslRedirects = true;
       followRedirects = true;
       retryOnConnectionFailure = true;
+      callTimeout = 0;
       connectTimeout = 10_000;
       readTimeout = 10_000;
       writeTimeout = 10_000;
@@ -512,18 +521,46 @@ public Builder() {
       this.followSslRedirects = okHttpClient.followSslRedirects;
       this.followRedirects = okHttpClient.followRedirects;
       this.retryOnConnectionFailure = okHttpClient.retryOnConnectionFailure;
+      this.callTimeout = okHttpClient.callTimeout;
       this.connectTimeout = okHttpClient.connectTimeout;
       this.readTimeout = okHttpClient.readTimeout;
       this.writeTimeout = okHttpClient.writeTimeout;
       this.pingInterval = okHttpClient.pingInterval;
     }
 
+    /**
+     * Sets the default timeout for complete calls. A value of 0 means no timeout, otherwise values
+     * must be between 1 and {@link Integer#MAX_VALUE} when converted to milliseconds.
+     *
+     * <p>The call timeout is spans the entire call: resolving DNS, connecting, writing the request
+     * body, server processing, and reading the response body. If the call requires redirects or
+     * retries all must complete within one timeout period.
+     */
+    public Builder callTimeout(long timeout, TimeUnit unit) {
+      callTimeout = checkDuration("timeout", timeout, unit);
+      return this;
+    }
+
+    /**
+     * Sets the default timeout for complete calls. A value of 0 means no timeout, otherwise values
+     * must be between 1 and {@link Integer#MAX_VALUE} when converted to milliseconds.
+     *
+     * <p>The call timeout is spans the entire call: resolving DNS, connecting, writing the request
+     * body, server processing, and reading the response body. If the call requires redirects or
+     * retries all must complete within one timeout period.
+     */
+    @IgnoreJRERequirement
+    public Builder callTimeout(Duration duration) {
+      callTimeout = checkDuration("timeout", duration.toMillis(), TimeUnit.MILLISECONDS);
+      return this;
+    }
+
     /**
      * Sets the default connect timeout for new connections. A value of 0 means no timeout,
      * otherwise values must be between 1 and {@link Integer#MAX_VALUE} when converted to
      * milliseconds.
      *
-     * <p>The connectTimeout is applied when connecting a TCP socket to the target host.
+     * <p>The connect timeout is applied when connecting a TCP socket to the target host.
      * The default value is 10 seconds.
      */
     public Builder connectTimeout(long timeout, TimeUnit unit) {
@@ -536,7 +573,7 @@ public Builder connectTimeout(long timeout, TimeUnit unit) {
      * otherwise values must be between 1 and {@link Integer#MAX_VALUE} when converted to
      * milliseconds.
      *
-     * <p>The connectTimeout is applied when connecting a TCP socket to the target host.
+     * <p>The connect timeout is applied when connecting a TCP socket to the target host.
      * The default value is 10 seconds.
      */
     @IgnoreJRERequirement

okhttp/src/main/java/okhttp3/RealCall.java

@@ -34,6 +34,7 @@
 import okio.AsyncTimeout;
 import okio.Timeout;
 
+import static java.util.concurrent.TimeUnit.MILLISECONDS;
 import static okhttp3.internal.platform.Platform.INFO;
 
 final class RealCall implements Call {
@@ -64,6 +65,7 @@ private RealCall(OkHttpClient client, Request originalRequest, boolean forWebSoc
         cancel();
       }
     };
+    this.timeout.timeout(client.callTimeoutMillis(), MILLISECONDS);
   }
 
   static RealCall newRealCall(OkHttpClient client, Request originalRequest, boolean forWebSocket) {