feat(client): expose sleeper option

fix(client): ensure single timer is created per client

Author: stainless-app[bot]

inty-kotlin-client-okhttp/src/main/kotlin/com/inty/api/client/okhttp/IntyOkHttpClient.kt

@@ -6,6 +6,7 @@ import com.fasterxml.jackson.databind.json.JsonMapper
 import com.inty.api.client.IntyClient
 import com.inty.api.client.IntyClientImpl
 import com.inty.api.core.ClientOptions
+import com.inty.api.core.Sleeper
 import com.inty.api.core.Timeout
 import com.inty.api.core.http.Headers
 import com.inty.api.core.http.HttpClient
@@ -103,6 +104,17 @@ class IntyOkHttpClient private constructor() {
          */
         fun jsonMapper(jsonMapper: JsonMapper) = apply { clientOptions.jsonMapper(jsonMapper) }
 
+        /**
+         * The interface to use for delaying execution, like during retries.
+         *
+         * This is primarily useful for using fake delays in tests.
+         *
+         * Defaults to real execution delays.
+         *
+         * This class takes ownership of the sleeper and closes it when closed.
+         */
+        fun sleeper(sleeper: Sleeper) = apply { clientOptions.sleeper(sleeper) }
+
         /**
          * The clock to use for operations that require timing, like retries.
          *

inty-kotlin-client-okhttp/src/main/kotlin/com/inty/api/client/okhttp/IntyOkHttpClientAsync.kt

@@ -6,6 +6,7 @@ import com.fasterxml.jackson.databind.json.JsonMapper
 import com.inty.api.client.IntyClientAsync
 import com.inty.api.client.IntyClientAsyncImpl
 import com.inty.api.core.ClientOptions
+import com.inty.api.core.Sleeper
 import com.inty.api.core.Timeout
 import com.inty.api.core.http.Headers
 import com.inty.api.core.http.HttpClient
@@ -103,6 +104,17 @@ class IntyOkHttpClientAsync private constructor() {
          */
         fun jsonMapper(jsonMapper: JsonMapper) = apply { clientOptions.jsonMapper(jsonMapper) }
 
+        /**
+         * The interface to use for delaying execution, like during retries.
+         *
+         * This is primarily useful for using fake delays in tests.
+         *
+         * Defaults to real execution delays.
+         *
+         * This class takes ownership of the sleeper and closes it when closed.
+         */
+        fun sleeper(sleeper: Sleeper) = apply { clientOptions.sleeper(sleeper) }
+
         /**
          * The clock to use for operations that require timing, like retries.
          *

inty-kotlin-core/src/main/kotlin/com/inty/api/core/ClientOptions.kt

@@ -38,6 +38,16 @@ private constructor(
      * needs to be overridden.
      */
     val jsonMapper: JsonMapper,
+    /**
+     * The interface to use for delaying execution, like during retries.
+     *
+     * This is primarily useful for using fake delays in tests.
+     *
+     * Defaults to real execution delays.
+     *
+     * This class takes ownership of the sleeper and closes it when closed.
+     */
+    val sleeper: Sleeper,
     /**
      * The clock to use for operations that require timing, like retries.
      *
@@ -129,6 +139,7 @@ private constructor(
         private var httpClient: HttpClient? = null
         private var checkJacksonVersionCompatibility: Boolean = true
         private var jsonMapper: JsonMapper = jsonMapper()
+        private var sleeper: Sleeper? = null
         private var clock: Clock = Clock.systemUTC()
         private var baseUrl: String? = null
         private var headers: Headers.Builder = Headers.builder()
@@ -142,6 +153,7 @@ private constructor(
             httpClient = clientOptions.originalHttpClient
             checkJacksonVersionCompatibility = clientOptions.checkJacksonVersionCompatibility
             jsonMapper = clientOptions.jsonMapper
+            sleeper = clientOptions.sleeper
             clock = clientOptions.clock
             baseUrl = clientOptions.baseUrl
             headers = clientOptions.headers.toBuilder()
@@ -182,6 +194,17 @@ private constructor(
          */
         fun jsonMapper(jsonMapper: JsonMapper) = apply { this.jsonMapper = jsonMapper }
 
+        /**
+         * The interface to use for delaying execution, like during retries.
+         *
+         * This is primarily useful for using fake delays in tests.
+         *
+         * Defaults to real execution delays.
+         *
+         * This class takes ownership of the sleeper and closes it when closed.
+         */
+        fun sleeper(sleeper: Sleeper) = apply { this.sleeper = PhantomReachableSleeper(sleeper) }
+
         /**
          * The clock to use for operations that require timing, like retries.
          *
@@ -361,6 +384,7 @@ private constructor(
          */
         fun build(): ClientOptions {
             val httpClient = checkRequired("httpClient", httpClient)
+            val sleeper = sleeper ?: PhantomReachableSleeper(DefaultSleeper())
             val apiKey = checkRequired("apiKey", apiKey)
 
             val headers = Headers.builder()
@@ -384,11 +408,13 @@ private constructor(
                 httpClient,
                 RetryingHttpClient.builder()
                     .httpClient(httpClient)
+                    .sleeper(sleeper)
                     .clock(clock)
                     .maxRetries(maxRetries)
                     .build(),
                 checkJacksonVersionCompatibility,
                 jsonMapper,
+                sleeper,
                 clock,
                 baseUrl,
                 headers.build(),
@@ -413,5 +439,6 @@ private constructor(
      */
     fun close() {
         httpClient.close()
+        sleeper.close()
     }
 }

inty-kotlin-core/src/main/kotlin/com/inty/api/core/DefaultSleeper.kt

@@ -0,0 +1,14 @@
+package com.inty.api.core
+
+import java.time.Duration
+import kotlin.time.toKotlinDuration
+import kotlinx.coroutines.delay
+
+class DefaultSleeper : Sleeper {
+
+    override fun sleep(duration: Duration) = Thread.sleep(duration.toMillis())
+
+    override suspend fun sleepAsync(duration: Duration) = delay(duration.toKotlinDuration())
+
+    override fun close() {}
+}

inty-kotlin-core/src/main/kotlin/com/inty/api/core/PhantomReachableSleeper.kt

@@ -0,0 +1,21 @@
+package com.inty.api.core
+
+import java.time.Duration
+
+/**
+ * A delegating wrapper around a [Sleeper] that closes it once it's only phantom reachable.
+ *
+ * This class ensures the [Sleeper] is closed even if the user forgets to do it.
+ */
+internal class PhantomReachableSleeper(private val sleeper: Sleeper) : Sleeper {
+
+    init {
+        closeWhenPhantomReachable(this, sleeper)
+    }
+
+    override fun sleep(duration: Duration) = sleeper.sleep(duration)
+
+    override suspend fun sleepAsync(duration: Duration) = sleeper.sleepAsync(duration)
+
+    override fun close() = sleeper.close()
+}

inty-kotlin-core/src/main/kotlin/com/inty/api/core/Sleeper.kt

@@ -0,0 +1,17 @@
+package com.inty.api.core
+
+import java.time.Duration
+
+/**
+ * An interface for delaying execution for a specified amount of time.
+ *
+ * Useful for testing and cleaning up resources.
+ */
+interface Sleeper : AutoCloseable {
+
+    /** Synchronously pauses execution for the given [duration]. */
+    fun sleep(duration: Duration)
+
+    /** Asynchronously pauses execution for the given [duration]. */
+    suspend fun sleepAsync(duration: Duration)
+}

inty-kotlin-core/src/main/kotlin/com/inty/api/core/http/RetryingHttpClient.kt

@@ -1,6 +1,8 @@
 package com.inty.api.core.http
 
+import com.inty.api.core.DefaultSleeper
 import com.inty.api.core.RequestOptions
+import com.inty.api.core.Sleeper
 import com.inty.api.core.checkRequired
 import com.inty.api.errors.IntyIoException
 import com.inty.api.errors.IntyRetryableException
@@ -16,8 +18,6 @@ import java.util.concurrent.ThreadLocalRandom
 import java.util.concurrent.TimeUnit
 import kotlin.math.min
 import kotlin.math.pow
-import kotlin.time.toKotlinDuration
-import kotlinx.coroutines.delay
 
 class RetryingHttpClient
 private constructor(
@@ -113,7 +113,10 @@ private constructor(
         }
     }
 
-    override fun close() = httpClient.close()
+    override fun close() {
+        httpClient.close()
+        sleeper.close()
+    }
 
     private fun isRetryable(request: HttpRequest): Boolean =
         // Some requests, such as when a request body is being streamed, cannot be retried because
@@ -218,21 +221,14 @@ private constructor(
     class Builder internal constructor() {
 
         private var httpClient: HttpClient? = null
-        private var sleeper: Sleeper =
-            object : Sleeper {
-
-                override fun sleep(duration: Duration) = Thread.sleep(duration.toMillis())
-
-                override suspend fun sleepAsync(duration: Duration) =
-                    delay(duration.toKotlinDuration())
-            }
+        private var sleeper: Sleeper? = null
         private var clock: Clock = Clock.systemUTC()
         private var maxRetries: Int = 2
         private var idempotencyHeader: String? = null
 
         fun httpClient(httpClient: HttpClient) = apply { this.httpClient = httpClient }
 
-        internal fun sleeper(sleeper: Sleeper) = apply { this.sleeper = sleeper }
+        fun sleeper(sleeper: Sleeper) = apply { this.sleeper = sleeper }
 
         fun clock(clock: Clock) = apply { this.clock = clock }
 
@@ -243,17 +239,10 @@ private constructor(
         fun build(): HttpClient =
             RetryingHttpClient(
                 checkRequired("httpClient", httpClient),
-                sleeper,
+                sleeper ?: DefaultSleeper(),
                 clock,
                 maxRetries,
                 idempotencyHeader,
             )
     }
-
-    internal interface Sleeper {
-
-        fun sleep(duration: Duration)
-
-        suspend fun sleepAsync(duration: Duration)
-    }
 }

inty-kotlin-core/src/test/kotlin/com/inty/api/core/http/RetryingHttpClientTest.kt

@@ -6,6 +6,7 @@ import com.github.tomakehurst.wiremock.junit5.WireMockTest
 import com.github.tomakehurst.wiremock.stubbing.Scenario
 import com.inty.api.client.okhttp.OkHttpClient
 import com.inty.api.core.RequestOptions
+import com.inty.api.core.Sleeper
 import com.inty.api.errors.IntyRetryableException
 import java.io.InputStream
 import java.time.Duration
@@ -289,11 +290,13 @@ internal class RetryingHttpClientTest {
                 .httpClient(failingHttpClient)
                 .maxRetries(2)
                 .sleeper(
-                    object : RetryingHttpClient.Sleeper {
+                    object : Sleeper {
 
                         override fun sleep(duration: Duration) {}
 
                         override suspend fun sleepAsync(duration: Duration) {}
+
+                        override fun close() {}
                     }
                 )
                 .build()
@@ -327,11 +330,13 @@ internal class RetryingHttpClientTest {
             .httpClient(httpClient)
             // Use a no-op `Sleeper` to make the test fast.
             .sleeper(
-                object : RetryingHttpClient.Sleeper {
+                object : Sleeper {
 
                     override fun sleep(duration: Duration) {}
 
                     override suspend fun sleepAsync(duration: Duration) {}
+
+                    override fun close() {}
                 }
             )