Introduce RetryStrategy (#6764)

* RetryOnError: allow to customize what exceptions are considered recoverable

* Add RetryDelegate

* fix tests

* update docs

* Update libraries/apollo-runtime/src/commonMain/kotlin/com/apollographql/apollo/interceptor/RetryOnErrorInterceptor.kt

Co-authored-by: Benoit 'BoD' Lubek <BoD@JRAF.org>

* code review

* RetryDelegate -> RetryStrategy

* update apidump

* wording

---------

Co-authored-by: Benoit 'BoD' Lubek <BoD@JRAF.org>

Author: martinbonnin

docs/source/advanced/network-connectivity.mdx

@@ -2,11 +2,6 @@
 title: Monitor the network state to reduce latency
 ---
 
-<ExperimentalFeature>
-
-**Network Monitor APIs are currently [experimental](https://www.apollographql.com/docs/resources/product-launch-stages/#experimental-features) in Apollo Kotlin.** If you have feedback on them, please let us know via [GitHub issues](https://github.com/apollographql/apollo-kotlin/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md) or in the [Kotlin Slack community](https://slack.kotl.in/).
-
-</ExperimentalFeature> 
 
 Android and Apple targets provide APIs to monitor the network state of your device:
 
@@ -40,6 +35,7 @@ When a `NetworkMonitor` is configured, you can use `failFastIfOffline` to avoid
 // Opt-in `failFastIfOffline` on all queries
 val apolloClient = ApolloClient.Builder()
     .serverUrl("https://example.com/graphql")
+    .retryOnErrorInterceptor(RetryOnErrorInterceptor(networkMonitor))
     .failFastIfOffline(true)
     .build()
 
@@ -57,35 +53,20 @@ When a `NetworkMonitor` is configured, `retryOnError` uses `NetworkMonitor.waitF
 
 ### Customizing the retry algorithm
 
-You can customize the retry algorithm further by defining your own interceptor:
+To customize the retry algorithm, use a `RetryStrategy`. The following example shows a `RetryStrategy` that uses exponential backoff and gives up after four tries: 
 
 ```kotlin
 val apolloClient = ApolloClient.Builder()
-    .retryOnErrorInterceptor(MyRetryOnErrorInterceptor())
-    .build()
-
-class MyRetryOnErrorInterceptor : ApolloInterceptor {
-  object RetryException : Exception()
-
-  override fun <D : Operation.Data> intercept(request: ApolloRequest<D>, chain: ApolloInterceptorChain): Flow<ApolloResponse<D>> {
-    var attempt = 0
-    return chain.proceed(request).onEach {
-      if (request.retryOnError == true && it.exception != null && it.exception is ApolloNetworkException) {
-        throw RetryException
-      } else {
-        attempt = 0
-      }
-    }.retryWhen { cause, _ ->
-      if (cause is RetryException) {
-        attempt++
-        delay(2.0.pow(attempt).seconds)
-        true
-      } else {
-        // Not a RetryException, probably a programming error, pass it through
-        false
+    .retryOnErrorInterceptor(RetryOnErrorInterceptor(networkMonitor) { state, request, response,  ->
+      val exception = response.exception
+      if (exception == null) {
+        return@RetryOnErrorInterceptor false
       }
-    }
-  }
-}
+
+      delay(2.0.pow(state.attempt).seconds)
+      state.attempt++
+      return@RetryOnErrorInterceptor state.attempt < 4
+    })
+    .build()
 ```
 

libraries/apollo-api/api/apollo-api.api

@@ -1313,6 +1313,10 @@ public final class com/apollographql/apollo/exception/ApolloNetworkException : c
 	public final fun getPlatformCause ()Ljava/lang/Object;
 }
 
+public final class com/apollographql/apollo/exception/ApolloOfflineException : com/apollographql/apollo/exception/ApolloException {
+	public fun <init> ()V
+}
+
 public final class com/apollographql/apollo/exception/ApolloParseException : com/apollographql/apollo/exception/ApolloException {
 	public fun <init> ()V
 	public fun <init> (Ljava/lang/String;Ljava/lang/Throwable;)V

libraries/apollo-api/api/apollo-api.klib.api

@@ -1183,6 +1183,10 @@ final class com.apollographql.apollo.exception/ApolloNetworkException : com.apol
         final fun <get-platformCause>(): kotlin/Any? // com.apollographql.apollo.exception/ApolloNetworkException.platformCause.<get-platformCause>|<get-platformCause>(){}[0]
 }
 
+final class com.apollographql.apollo.exception/ApolloOfflineException : com.apollographql.apollo.exception/ApolloException { // com.apollographql.apollo.exception/ApolloOfflineException|null[0]
+    constructor <init>() // com.apollographql.apollo.exception/ApolloOfflineException.<init>|<init>(){}[0]
+}
+
 final class com.apollographql.apollo.exception/ApolloParseException : com.apollographql.apollo.exception/ApolloException { // com.apollographql.apollo.exception/ApolloParseException|null[0]
     constructor <init>(kotlin/String? = ..., kotlin/Throwable? = ...) // com.apollographql.apollo.exception/ApolloParseException.<init>|<init>(kotlin.String?;kotlin.Throwable?){}[0]
 }

libraries/apollo-api/src/commonMain/kotlin/com/apollographql/apollo/api/ApolloRequest.kt

@@ -37,9 +37,7 @@ private constructor(
     override val canBeBatched: Boolean?,
     override val ignoreUnknownKeys: Boolean?,
     val ignoreApolloClientHttpHeaders: Boolean?,
-    @ApolloExperimental
     val retryOnError: Boolean?,
-    @ApolloExperimental
     val failFastIfOffline: Boolean?,
     val sendEnhancedClientAwareness: Boolean,
 ) : ExecutionOptions {
@@ -90,10 +88,8 @@ private constructor(
       private set
     var ignoreApolloClientHttpHeaders: Boolean? = null
       private set
-    @ApolloExperimental
     var retryOnError: Boolean? = null
       private set
-    @ApolloExperimental
     var failFastIfOffline: Boolean? = null
       private set
     var sendEnhancedClientAwareness: Boolean = true
@@ -151,12 +147,10 @@ private constructor(
       this.ignoreUnknownKeys = ignoreUnknownKeys
     }
 
-    @ApolloExperimental
     fun retryOnError(retryOnError: Boolean?): Builder<D> = apply {
       this.retryOnError = retryOnError
     }
 
-    @ApolloExperimental
     fun failFastIfOffline(failFastIfOffline: Boolean?): Builder<D> = apply {
       this.failFastIfOffline = failFastIfOffline
     }

libraries/apollo-api/src/commonMain/kotlin/com/apollographql/apollo/exception/Exceptions.kt

@@ -1,6 +1,7 @@
 // This is in the `exception` package and not `api.exception` to keep some compatibility with 2.x
 package com.apollographql.apollo.exception
 
+import com.apollographql.apollo.annotations.ApolloDeprecatedSince
 import com.apollographql.apollo.annotations.ApolloExperimental
 import com.apollographql.apollo.annotations.ApolloInternal
 import com.apollographql.apollo.api.Error
@@ -44,6 +45,13 @@ class ApolloNetworkException(
 /**
  * The device has been detected as offline
  */
+class ApolloOfflineException: ApolloException("The device is offline")
+
+/**
+ * The device has been detected as offline
+ */
+@Deprecated("This exception is not used anymore, check for `ApolloOfflineException` instead.", level = DeprecationLevel.ERROR)
+@ApolloDeprecatedSince(ApolloDeprecatedSince.Version.v5_0_0)
 data object OfflineException: IOException("The device is offline")
 
 /**

libraries/apollo-runtime/api/android/apollo-runtime.api

@@ -142,6 +142,7 @@ public final class com/apollographql/apollo/ApolloClient$Builder : com/apollogra
 	public final fun networkTransport (Lcom/apollographql/apollo/network/NetworkTransport;)Lcom/apollographql/apollo/ApolloClient$Builder;
 	public final fun removeHttpInterceptor (Lcom/apollographql/apollo/network/http/HttpInterceptor;)Lcom/apollographql/apollo/ApolloClient$Builder;
 	public final fun removeInterceptor (Lcom/apollographql/apollo/interceptor/ApolloInterceptor;)Lcom/apollographql/apollo/ApolloClient$Builder;
+	public final fun retryOnError (Ljava/lang/Boolean;)Lcom/apollographql/apollo/ApolloClient$Builder;
 	public final fun retryOnError (Lkotlin/jvm/functions/Function1;)Lcom/apollographql/apollo/ApolloClient$Builder;
 	public final fun retryOnErrorInterceptor (Lcom/apollographql/apollo/interceptor/ApolloInterceptor;)Lcom/apollographql/apollo/ApolloClient$Builder;
 	public fun sendApqExtensions (Ljava/lang/Boolean;)Lcom/apollographql/apollo/ApolloClient$Builder;
@@ -232,6 +233,18 @@ public final class com/apollographql/apollo/interceptor/AutoPersistedQueryInterc
 
 public final class com/apollographql/apollo/interceptor/RetryOnErrorInterceptorKt {
 	public static final fun RetryOnErrorInterceptor (Lcom/apollographql/apollo/network/NetworkMonitor;)Lcom/apollographql/apollo/interceptor/ApolloInterceptor;
+	public static final fun RetryOnErrorInterceptor (Lcom/apollographql/apollo/network/NetworkMonitor;Lcom/apollographql/apollo/interceptor/RetryStrategy;)Lcom/apollographql/apollo/interceptor/ApolloInterceptor;
+}
+
+public final class com/apollographql/apollo/interceptor/RetryState {
+	public fun <init> (Lcom/apollographql/apollo/network/NetworkMonitor;)V
+	public final fun getAttempt ()I
+	public final fun getNetworkMonitor ()Lcom/apollographql/apollo/network/NetworkMonitor;
+	public final fun setAttempt (I)V
+}
+
+public abstract interface class com/apollographql/apollo/interceptor/RetryStrategy {
+	public abstract fun shouldRetry (Lcom/apollographql/apollo/interceptor/RetryState;Lcom/apollographql/apollo/api/ApolloRequest;Lcom/apollographql/apollo/api/ApolloResponse;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 }
 
 public final class com/apollographql/apollo/network/IncrementalDeliveryProtocol : java/lang/Enum {

libraries/apollo-runtime/api/apollo-runtime.klib.api

@@ -32,6 +32,10 @@ final enum class com.apollographql.apollo.network/IncrementalDeliveryProtocol :
     final fun values(): kotlin/Array<com.apollographql.apollo.network/IncrementalDeliveryProtocol> // com.apollographql.apollo.network/IncrementalDeliveryProtocol.values|values#static(){}[0]
 }
 
+abstract fun interface com.apollographql.apollo.interceptor/RetryStrategy { // com.apollographql.apollo.interceptor/RetryStrategy|null[0]
+    abstract suspend fun shouldRetry(com.apollographql.apollo.interceptor/RetryState, com.apollographql.apollo.api/ApolloRequest<*>, com.apollographql.apollo.api/ApolloResponse<*>): kotlin/Boolean // com.apollographql.apollo.interceptor/RetryStrategy.shouldRetry|shouldRetry(com.apollographql.apollo.interceptor.RetryState;com.apollographql.apollo.api.ApolloRequest<*>;com.apollographql.apollo.api.ApolloResponse<*>){}[0]
+}
+
 abstract interface <#A: com.apollographql.apollo.api/Operation.Data> com.apollographql.apollo.network.websocket/SubscriptionParser { // com.apollographql.apollo.network.websocket/SubscriptionParser|null[0]
     abstract fun parse(kotlin/Any?): com.apollographql.apollo.api/ApolloResponse<#A>? // com.apollographql.apollo.network.websocket/SubscriptionParser.parse|parse(kotlin.Any?){}[0]
 }
@@ -227,6 +231,17 @@ final class com.apollographql.apollo.interceptor/AutoPersistedQueryInterceptor :
     }
 }
 
+final class com.apollographql.apollo.interceptor/RetryState { // com.apollographql.apollo.interceptor/RetryState|null[0]
+    constructor <init>(com.apollographql.apollo.network/NetworkMonitor?) // com.apollographql.apollo.interceptor/RetryState.<init>|<init>(com.apollographql.apollo.network.NetworkMonitor?){}[0]
+
+    final val networkMonitor // com.apollographql.apollo.interceptor/RetryState.networkMonitor|{}networkMonitor[0]
+        final fun <get-networkMonitor>(): com.apollographql.apollo.network/NetworkMonitor? // com.apollographql.apollo.interceptor/RetryState.networkMonitor.<get-networkMonitor>|<get-networkMonitor>(){}[0]
+
+    final var attempt // com.apollographql.apollo.interceptor/RetryState.attempt|{}attempt[0]
+        final fun <get-attempt>(): kotlin/Int // com.apollographql.apollo.interceptor/RetryState.attempt.<get-attempt>|<get-attempt>(){}[0]
+        final fun <set-attempt>(kotlin/Int) // com.apollographql.apollo.interceptor/RetryState.attempt.<set-attempt>|<set-attempt>(kotlin.Int){}[0]
+}
+
 final class com.apollographql.apollo.network.http/ApolloClientAwarenessInterceptor : com.apollographql.apollo.network.http/HttpInterceptor { // com.apollographql.apollo.network.http/ApolloClientAwarenessInterceptor|null[0]
     constructor <init>(kotlin/String, kotlin/String) // com.apollographql.apollo.network.http/ApolloClientAwarenessInterceptor.<init>|<init>(kotlin.String;kotlin.String){}[0]
 
@@ -701,6 +716,7 @@ final class com.apollographql.apollo/ApolloClient : com.apollographql.apollo.api
         final fun networkTransport(com.apollographql.apollo.network/NetworkTransport?): com.apollographql.apollo/ApolloClient.Builder // com.apollographql.apollo/ApolloClient.Builder.networkTransport|networkTransport(com.apollographql.apollo.network.NetworkTransport?){}[0]
         final fun removeHttpInterceptor(com.apollographql.apollo.network.http/HttpInterceptor): com.apollographql.apollo/ApolloClient.Builder // com.apollographql.apollo/ApolloClient.Builder.removeHttpInterceptor|removeHttpInterceptor(com.apollographql.apollo.network.http.HttpInterceptor){}[0]
         final fun removeInterceptor(com.apollographql.apollo.interceptor/ApolloInterceptor): com.apollographql.apollo/ApolloClient.Builder // com.apollographql.apollo/ApolloClient.Builder.removeInterceptor|removeInterceptor(com.apollographql.apollo.interceptor.ApolloInterceptor){}[0]
+        final fun retryOnError(kotlin/Boolean?): com.apollographql.apollo/ApolloClient.Builder // com.apollographql.apollo/ApolloClient.Builder.retryOnError|retryOnError(kotlin.Boolean?){}[0]
         final fun retryOnError(kotlin/Function1<com.apollographql.apollo.api/ApolloRequest<*>, kotlin/Boolean>?): com.apollographql.apollo/ApolloClient.Builder // com.apollographql.apollo/ApolloClient.Builder.retryOnError|retryOnError(kotlin.Function1<com.apollographql.apollo.api.ApolloRequest<*>,kotlin.Boolean>?){}[0]
         final fun retryOnErrorInterceptor(com.apollographql.apollo.interceptor/ApolloInterceptor?): com.apollographql.apollo/ApolloClient.Builder // com.apollographql.apollo/ApolloClient.Builder.retryOnErrorInterceptor|retryOnErrorInterceptor(com.apollographql.apollo.interceptor.ApolloInterceptor?){}[0]
         final fun sendApqExtensions(kotlin/Boolean?): com.apollographql.apollo/ApolloClient.Builder // com.apollographql.apollo/ApolloClient.Builder.sendApqExtensions|sendApqExtensions(kotlin.Boolean?){}[0]
@@ -787,6 +803,7 @@ final fun (com.apollographql.apollo.network/NetworkTransport).com.apollographql.
 final fun (com.apollographql.apollo.network/NetworkTransport).com.apollographql.apollo.network.ws/closeConnection(kotlin/Throwable) // com.apollographql.apollo.network.ws/closeConnection|closeConnection@com.apollographql.apollo.network.NetworkTransport(kotlin.Throwable){}[0]
 final fun <#A: kotlin/Any?> (com.apollographql.apollo.api/MutableExecutionOptions<#A>).com.apollographql.apollo/conflateFetchPolicyInterceptorResponses(kotlin/Boolean): #A // com.apollographql.apollo/conflateFetchPolicyInterceptorResponses|conflateFetchPolicyInterceptorResponses@com.apollographql.apollo.api.MutableExecutionOptions<0:0>(kotlin.Boolean){0§<kotlin.Any?>}[0]
 final fun com.apollographql.apollo.interceptor/RetryOnErrorInterceptor(com.apollographql.apollo.network/NetworkMonitor): com.apollographql.apollo.interceptor/ApolloInterceptor // com.apollographql.apollo.interceptor/RetryOnErrorInterceptor|RetryOnErrorInterceptor(com.apollographql.apollo.network.NetworkMonitor){}[0]
+final fun com.apollographql.apollo.interceptor/RetryOnErrorInterceptor(com.apollographql.apollo.network/NetworkMonitor, com.apollographql.apollo.interceptor/RetryStrategy): com.apollographql.apollo.interceptor/ApolloInterceptor // com.apollographql.apollo.interceptor/RetryOnErrorInterceptor|RetryOnErrorInterceptor(com.apollographql.apollo.network.NetworkMonitor;com.apollographql.apollo.interceptor.RetryStrategy){}[0]
 final fun com.apollographql.apollo.network.http/DefaultHttpEngine(kotlin/Long = ...): com.apollographql.apollo.network.http/HttpEngine // com.apollographql.apollo.network.http/DefaultHttpEngine|DefaultHttpEngine(kotlin.Long){}[0]
 final fun com.apollographql.apollo.network.websocket/WebSocketEngine(): com.apollographql.apollo.network.websocket/WebSocketEngine // com.apollographql.apollo.network.websocket/WebSocketEngine|WebSocketEngine(){}[0]
 

libraries/apollo-runtime/api/jvm/apollo-runtime.api

@@ -142,6 +142,7 @@ public final class com/apollographql/apollo/ApolloClient$Builder : com/apollogra
 	public final fun networkTransport (Lcom/apollographql/apollo/network/NetworkTransport;)Lcom/apollographql/apollo/ApolloClient$Builder;
 	public final fun removeHttpInterceptor (Lcom/apollographql/apollo/network/http/HttpInterceptor;)Lcom/apollographql/apollo/ApolloClient$Builder;
 	public final fun removeInterceptor (Lcom/apollographql/apollo/interceptor/ApolloInterceptor;)Lcom/apollographql/apollo/ApolloClient$Builder;
+	public final fun retryOnError (Ljava/lang/Boolean;)Lcom/apollographql/apollo/ApolloClient$Builder;
 	public final fun retryOnError (Lkotlin/jvm/functions/Function1;)Lcom/apollographql/apollo/ApolloClient$Builder;
 	public final fun retryOnErrorInterceptor (Lcom/apollographql/apollo/interceptor/ApolloInterceptor;)Lcom/apollographql/apollo/ApolloClient$Builder;
 	public fun sendApqExtensions (Ljava/lang/Boolean;)Lcom/apollographql/apollo/ApolloClient$Builder;
@@ -232,6 +233,18 @@ public final class com/apollographql/apollo/interceptor/AutoPersistedQueryInterc
 
 public final class com/apollographql/apollo/interceptor/RetryOnErrorInterceptorKt {
 	public static final fun RetryOnErrorInterceptor (Lcom/apollographql/apollo/network/NetworkMonitor;)Lcom/apollographql/apollo/interceptor/ApolloInterceptor;
+	public static final fun RetryOnErrorInterceptor (Lcom/apollographql/apollo/network/NetworkMonitor;Lcom/apollographql/apollo/interceptor/RetryStrategy;)Lcom/apollographql/apollo/interceptor/ApolloInterceptor;
+}
+
+public final class com/apollographql/apollo/interceptor/RetryState {
+	public fun <init> (Lcom/apollographql/apollo/network/NetworkMonitor;)V
+	public final fun getAttempt ()I
+	public final fun getNetworkMonitor ()Lcom/apollographql/apollo/network/NetworkMonitor;
+	public final fun setAttempt (I)V
+}
+
+public abstract interface class com/apollographql/apollo/interceptor/RetryStrategy {
+	public abstract fun shouldRetry (Lcom/apollographql/apollo/interceptor/RetryState;Lcom/apollographql/apollo/api/ApolloRequest;Lcom/apollographql/apollo/api/ApolloResponse;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 }
 
 public final class com/apollographql/apollo/network/IncrementalDeliveryProtocol : java/lang/Enum {

libraries/apollo-runtime/src/commonMain/kotlin/com/apollographql/apollo/ApolloCall.kt

@@ -56,9 +56,8 @@ class ApolloCall<D : Operation.Data> internal constructor(
 
   val ignoreApolloClientHttpHeaders: Boolean? get() = requestBuilder.ignoreApolloClientHttpHeaders
 
-  @ApolloExperimental
   val retryOnError: Boolean? get() = requestBuilder.retryOnError
-  @ApolloExperimental
+
   val failFastIfOffline: Boolean? get() = requestBuilder.failFastIfOffline
 
   fun failFastIfOffline(failFastIfOffline: Boolean?) = apply {
@@ -105,7 +104,6 @@ class ApolloCall<D : Operation.Data> internal constructor(
     requestBuilder.ignoreUnknownKeys(ignoreUnknownKeys)
   }
 
-  @ApolloExperimental
   fun retryOnError(retryOnError: Boolean?): ApolloCall<D> = apply {
     requestBuilder.retryOnError(retryOnError)
   }
@@ -144,7 +142,6 @@ class ApolloCall<D : Operation.Data> internal constructor(
    *
    * The returned [Flow] has [kotlinx.coroutines.channels.Channel.UNLIMITED] buffering so that no response is missed in the case of a slow consumer. Use [kotlinx.coroutines.flow.buffer] to change that behaviour.
    *
-   * @see toFlowV3
    * @see ApolloClient.Builder.dispatcher
    */
   fun toFlow(): Flow<ApolloResponse<D>> {
@@ -178,7 +175,6 @@ class ApolloCall<D : Operation.Data> internal constructor(
    *
    * @throws ApolloException if the call returns zero or multiple valid GraphQL responses.
    *
-   * @see executeV3
    * @see ApolloClient.Builder.dispatcher
    */
   suspend fun execute(): ApolloResponse<D> {