feat: add retryable exception

Author: stainless-app[bot]

README.md

@@ -229,6 +229,8 @@ The SDK throws custom unchecked exception types:
 
 - [`OrbIoException`](orb-kotlin-core/src/main/kotlin/com/withorb/api/errors/OrbIoException.kt): I/O networking errors.
 
+- [`OrbRetryableException`](orb-kotlin-core/src/main/kotlin/com/withorb/api/errors/OrbRetryableException.kt): Generic error indicating a failure that could be retried by the client.
+
 - [`OrbInvalidDataException`](orb-kotlin-core/src/main/kotlin/com/withorb/api/errors/OrbInvalidDataException.kt): Failure to interpret successfully parsed data. For example, when accessing a property that's supposed to be required, but the API unexpectedly omitted it from the response.
 
 - [`OrbException`](orb-kotlin-core/src/main/kotlin/com/withorb/api/errors/OrbException.kt): Base class for all exceptions. Most errors will result in one of the previously mentioned ones, but completely generic errors may be thrown using the base class.

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

@@ -3,6 +3,7 @@ package com.withorb.api.core.http
 import com.withorb.api.core.RequestOptions
 import com.withorb.api.core.checkRequired
 import com.withorb.api.errors.OrbIoException
+import com.withorb.api.errors.OrbRetryableException
 import java.io.IOException
 import java.time.Clock
 import java.time.Duration
@@ -159,9 +160,10 @@ private constructor(
     }
 
     private fun shouldRetry(throwable: Throwable): Boolean =
-        // Only retry IOException and OrbIoException, other exceptions are not intended to be
-        // retried.
-        throwable is IOException || throwable is OrbIoException
+        // Only retry known retryable exceptions, other exceptions are not intended to be retried.
+        throwable is IOException ||
+            throwable is OrbIoException ||
+            throwable is OrbRetryableException
 
     private fun getRetryBackoffDuration(retries: Int, response: HttpResponse?): Duration {
         // About the Retry-After header:

orb-kotlin-core/src/main/kotlin/com/withorb/api/errors/OrbRetryableException.kt

@@ -0,0 +1,13 @@
+package com.withorb.api.errors
+
+/**
+ * Exception that indicates a transient error that can be retried.
+ *
+ * When this exception is thrown during an HTTP request, the SDK will automatically retry the
+ * request up to the maximum number of retries.
+ *
+ * @param message A descriptive error message
+ * @param cause The underlying cause of this exception, if any
+ */
+class OrbRetryableException constructor(message: String? = null, cause: Throwable? = null) :
+    OrbException(message, cause)

orb-kotlin-core/src/test/kotlin/com/withorb/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.withorb.api.client.okhttp.OkHttpClient
 import com.withorb.api.core.RequestOptions
+import com.withorb.api.errors.OrbRetryableException
 import java.io.InputStream
 import java.time.Duration
 import kotlinx.coroutines.runBlocking
@@ -250,6 +251,77 @@ internal class RetryingHttpClientTest {
         assertNoResponseLeaks()
     }
 
+    @ParameterizedTest
+    @ValueSource(booleans = [false, true])
+    fun execute_withRetryableException(async: Boolean) {
+        stubFor(post(urlPathEqualTo("/something")).willReturn(ok()))
+
+        var callCount = 0
+        val failingHttpClient =
+            object : HttpClient {
+                override fun execute(
+                    request: HttpRequest,
+                    requestOptions: RequestOptions,
+                ): HttpResponse {
+                    callCount++
+                    if (callCount == 1) {
+                        throw OrbRetryableException("Simulated retryable failure")
+                    }
+                    return httpClient.execute(request, requestOptions)
+                }
+
+                override suspend fun executeAsync(
+                    request: HttpRequest,
+                    requestOptions: RequestOptions,
+                ): HttpResponse {
+                    callCount++
+                    if (callCount == 1) {
+                        throw OrbRetryableException("Simulated retryable failure")
+                    }
+                    return httpClient.executeAsync(request, requestOptions)
+                }
+
+                override fun close() = httpClient.close()
+            }
+
+        val retryingClient =
+            RetryingHttpClient.builder()
+                .httpClient(failingHttpClient)
+                .maxRetries(2)
+                .sleeper(
+                    object : RetryingHttpClient.Sleeper {
+
+                        override fun sleep(duration: Duration) {}
+
+                        override suspend fun sleepAsync(duration: Duration) {}
+                    }
+                )
+                .build()
+
+        val response =
+            retryingClient.execute(
+                HttpRequest.builder()
+                    .method(HttpMethod.POST)
+                    .baseUrl(baseUrl)
+                    .addPathSegment("something")
+                    .build(),
+                async,
+            )
+
+        assertThat(response.statusCode()).isEqualTo(200)
+        verify(
+            1,
+            postRequestedFor(urlPathEqualTo("/something"))
+                .withHeader("x-stainless-retry-count", equalTo("1")),
+        )
+        verify(
+            0,
+            postRequestedFor(urlPathEqualTo("/something"))
+                .withHeader("x-stainless-retry-count", equalTo("0")),
+        )
+        assertNoResponseLeaks()
+    }
+
     private fun retryingHttpClientBuilder() =
         RetryingHttpClient.builder()
             .httpClient(httpClient)