feat(client): allow configuring timeouts granularly (#470)

Note that previously the `timeout(Duration)` method on the client and `RequestOptions` corresponded to connect, read, write, and request timeout. Now it only corresponds to the request timeout. Use the new `timeout(Timeout)` method to configure other timeout values granularly.

Author: stainless-app[bot]

finch-java-client-okhttp/src/main/kotlin/com/tryfinch/api/client/okhttp/FinchOkHttpClient.kt

@@ -6,6 +6,7 @@ import com.fasterxml.jackson.databind.json.JsonMapper
 import com.tryfinch.api.client.FinchClient
 import com.tryfinch.api.client.FinchClientImpl
 import com.tryfinch.api.core.ClientOptions
+import com.tryfinch.api.core.Timeout
 import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.QueryParams
 import java.net.Proxy
@@ -27,8 +28,7 @@ class FinchOkHttpClient private constructor() {
 
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
         private var baseUrl: String = ClientOptions.PRODUCTION_URL
-        // The default timeout for the client is 1 minute.
-        private var timeout: Duration = Duration.ofSeconds(60)
+        private var timeout: Timeout = Timeout.default()
         private var proxy: Proxy? = null
 
         fun baseUrl(baseUrl: String) = apply {
@@ -120,7 +120,19 @@ class FinchOkHttpClient private constructor() {
             clientOptions.removeAllQueryParams(keys)
         }
 
-        fun timeout(timeout: Duration) = apply { this.timeout = timeout }
+        fun timeout(timeout: Timeout) = apply {
+            clientOptions.timeout(timeout)
+            this.timeout = timeout
+        }
+
+        /**
+         * Sets the maximum time allowed for a complete HTTP call, not including retries.
+         *
+         * See [Timeout.request] for more details.
+         *
+         * For fine-grained control, pass a [Timeout] object.
+         */
+        fun timeout(timeout: Duration) = timeout(Timeout.builder().request(timeout).build())
 
         fun maxRetries(maxRetries: Int) = apply { clientOptions.maxRetries(maxRetries) }
 

finch-java-client-okhttp/src/main/kotlin/com/tryfinch/api/client/okhttp/FinchOkHttpClientAsync.kt

@@ -6,6 +6,7 @@ import com.fasterxml.jackson.databind.json.JsonMapper
 import com.tryfinch.api.client.FinchClientAsync
 import com.tryfinch.api.client.FinchClientAsyncImpl
 import com.tryfinch.api.core.ClientOptions
+import com.tryfinch.api.core.Timeout
 import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.QueryParams
 import java.net.Proxy
@@ -27,8 +28,7 @@ class FinchOkHttpClientAsync private constructor() {
 
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
         private var baseUrl: String = ClientOptions.PRODUCTION_URL
-        // The default timeout for the client is 1 minute.
-        private var timeout: Duration = Duration.ofSeconds(60)
+        private var timeout: Timeout = Timeout.default()
         private var proxy: Proxy? = null
 
         fun baseUrl(baseUrl: String) = apply {
@@ -120,7 +120,19 @@ class FinchOkHttpClientAsync private constructor() {
             clientOptions.removeAllQueryParams(keys)
         }
 
-        fun timeout(timeout: Duration) = apply { this.timeout = timeout }
+        fun timeout(timeout: Timeout) = apply {
+            clientOptions.timeout(timeout)
+            this.timeout = timeout
+        }
+
+        /**
+         * Sets the maximum time allowed for a complete HTTP call, not including retries.
+         *
+         * See [Timeout.request] for more details.
+         *
+         * For fine-grained control, pass a [Timeout] object.
+         */
+        fun timeout(timeout: Duration) = timeout(Timeout.builder().request(timeout).build())
 
         fun maxRetries(maxRetries: Int) = apply { clientOptions.maxRetries(maxRetries) }
 

finch-java-client-okhttp/src/main/kotlin/com/tryfinch/api/client/okhttp/OkHttpClient.kt

@@ -1,6 +1,7 @@
 package com.tryfinch.api.client.okhttp
 
 import com.tryfinch.api.core.RequestOptions
+import com.tryfinch.api.core.Timeout
 import com.tryfinch.api.core.checkRequired
 import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.HttpClient
@@ -88,13 +89,12 @@ private constructor(private val okHttpClient: okhttp3.OkHttpClient, private val
             )
         }
 
-        val timeout = requestOptions.timeout
-        if (timeout != null) {
+        requestOptions.timeout?.let {
             clientBuilder
-                .connectTimeout(timeout)
-                .readTimeout(timeout)
-                .writeTimeout(timeout)
-                .callTimeout(if (timeout.seconds == 0L) timeout else timeout.plusSeconds(30))
+                .connectTimeout(it.connect())
+                .readTimeout(it.read())
+                .writeTimeout(it.write())
+                .callTimeout(it.request())
         }
 
         val client = clientBuilder.build()
@@ -195,23 +195,24 @@ private constructor(private val okHttpClient: okhttp3.OkHttpClient, private val
     class Builder internal constructor() {
 
         private var baseUrl: HttpUrl? = null
-        // The default timeout is 1 minute.
-        private var timeout: Duration = Duration.ofSeconds(60)
+        private var timeout: Timeout = Timeout.default()
         private var proxy: Proxy? = null
 
         fun baseUrl(baseUrl: String) = apply { this.baseUrl = baseUrl.toHttpUrl() }
 
-        fun timeout(timeout: Duration) = apply { this.timeout = timeout }
+        fun timeout(timeout: Timeout) = apply { this.timeout = timeout }
+
+        fun timeout(timeout: Duration) = timeout(Timeout.builder().request(timeout).build())
 
         fun proxy(proxy: Proxy?) = apply { this.proxy = proxy }
 
         fun build(): OkHttpClient =
             OkHttpClient(
                 okhttp3.OkHttpClient.Builder()
-                    .connectTimeout(timeout)
-                    .readTimeout(timeout)
-                    .writeTimeout(timeout)
-                    .callTimeout(if (timeout.seconds == 0L) timeout else timeout.plusSeconds(30))
+                    .connectTimeout(timeout.connect())
+                    .readTimeout(timeout.read())
+                    .writeTimeout(timeout.write())
+                    .callTimeout(timeout.request())
                     .proxy(proxy)
                     .build(),
                 checkRequired("baseUrl", baseUrl),

finch-java-core/src/main/kotlin/com/tryfinch/api/core/ClientOptions.kt

@@ -22,6 +22,7 @@ private constructor(
     @get:JvmName("headers") val headers: Headers,
     @get:JvmName("queryParams") val queryParams: QueryParams,
     @get:JvmName("responseValidation") val responseValidation: Boolean,
+    @get:JvmName("timeout") val timeout: Timeout,
     @get:JvmName("maxRetries") val maxRetries: Int,
     @get:JvmName("accessToken") val accessToken: String?,
     @get:JvmName("clientId") val clientId: String?,
@@ -50,6 +51,7 @@ private constructor(
         private var headers: Headers.Builder = Headers.builder()
         private var queryParams: QueryParams.Builder = QueryParams.builder()
         private var responseValidation: Boolean = false
+        private var timeout: Timeout = Timeout.default()
         private var maxRetries: Int = 2
         private var accessToken: String? = null
         private var clientId: String? = null
@@ -65,6 +67,7 @@ private constructor(
             headers = clientOptions.headers.toBuilder()
             queryParams = clientOptions.queryParams.toBuilder()
             responseValidation = clientOptions.responseValidation
+            timeout = clientOptions.timeout
             maxRetries = clientOptions.maxRetries
             accessToken = clientOptions.accessToken
             clientId = clientOptions.clientId
@@ -84,6 +87,8 @@ private constructor(
             this.responseValidation = responseValidation
         }
 
+        fun timeout(timeout: Timeout) = apply { this.timeout = timeout }
+
         fun maxRetries(maxRetries: Int) = apply { this.maxRetries = maxRetries }
 
         fun accessToken(accessToken: String?) = apply { this.accessToken = accessToken }
@@ -235,6 +240,7 @@ private constructor(
                 headers.build(),
                 queryParams.build(),
                 responseValidation,
+                timeout,
                 maxRetries,
                 accessToken,
                 clientId,

finch-java-core/src/main/kotlin/com/tryfinch/api/core/RequestOptions.kt

@@ -2,36 +2,45 @@ package com.tryfinch.api.core
 
 import java.time.Duration
 
-class RequestOptions private constructor(val responseValidation: Boolean?, val timeout: Duration?) {
-    fun applyDefaults(options: RequestOptions): RequestOptions {
-        return RequestOptions(
-            responseValidation = this.responseValidation ?: options.responseValidation,
-            timeout = this.timeout ?: options.timeout,
-        )
-    }
+class RequestOptions private constructor(val responseValidation: Boolean?, val timeout: Timeout?) {
 
     companion object {
 
         private val NONE = builder().build()
 
         @JvmStatic fun none() = NONE
 
+        @JvmSynthetic
+        internal fun from(clientOptions: ClientOptions): RequestOptions =
+            builder()
+                .responseValidation(clientOptions.responseValidation)
+                .timeout(clientOptions.timeout)
+                .build()
+
         @JvmStatic fun builder() = Builder()
     }
 
+    fun applyDefaults(options: RequestOptions): RequestOptions =
+        RequestOptions(
+            responseValidation = responseValidation ?: options.responseValidation,
+            timeout =
+                if (options.timeout != null && timeout != null) timeout.assign(options.timeout)
+                else timeout ?: options.timeout,
+        )
+
     class Builder internal constructor() {
 
         private var responseValidation: Boolean? = null
-        private var timeout: Duration? = null
+        private var timeout: Timeout? = null
 
         fun responseValidation(responseValidation: Boolean) = apply {
             this.responseValidation = responseValidation
         }
 
-        fun timeout(timeout: Duration) = apply { this.timeout = timeout }
+        fun timeout(timeout: Timeout) = apply { this.timeout = timeout }
 
-        fun build(): RequestOptions {
-            return RequestOptions(responseValidation, timeout)
-        }
+        fun timeout(timeout: Duration) = timeout(Timeout.builder().request(timeout).build())
+
+        fun build(): RequestOptions = RequestOptions(responseValidation, timeout)
     }
 }