Promote experimental websockets to stable (#6774)

* Promote experimental websockets to stable

* AI code review

* Update docs/source/migration/5.0.mdx

Co-authored-by: Benoit 'BoD' Lubek <[email protected]>

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

Co-authored-by: Benoit 'BoD' Lubek <[email protected]>

* Update wording

---------

Co-authored-by: Benoit 'BoD' Lubek <[email protected]>

Author: martinbonnin

docs/source/migration/5.0.mdx

@@ -126,6 +126,105 @@ query GetUser {
 You can read more in the ["handling nullability" page](https://www.apollographql.com/docs/kotlin/advanced/nullability).
 
 
+## `apollo-runtime`
+
+### New WebSockets
+
+In Apollo Kotlin 5, the WebSocket code has been rewritten to simplify it and clarify the error and retry semantics. 
+
+All the classes in the `com.apollographql.apollo.network.ws` package have been deprecated and a new implementation is available in `com.apollographql.apollo.network.websocket`. 
+
+To migrate, replace all your instances of `com.apollographql.apollo.network.ws` with `com.apollographql.apollo.network.websocket`:
+
+```kotlin
+// Replace 
+import com.apollographql.apollo.network.ws.AppSyncWsProtocol
+import com.apollographql.apollo.network.ws.WebSocketNetworkTransport
+
+// With
+import com.apollographql.apollo.network.websocket.AppSyncWsProtocol
+import com.apollographql.apollo.network.websocket.WebSocketNetworkTransport
+```
+
+Some shorthand methods on `ApolloClient.Builder` have been deprecated and replaced by explicit configuration. In those cases, you can use `subscriptionNetworkTransport` directly.
+
+For an example, you can replace `ApolloClient.Builder.webSocketEngine()` as follows:
+
+```kotlin
+// Replace
+ApolloClient.Builder()
+    .webSocketEngine(webSocketEngine) 
+    .build()
+// With
+ApolloClient.Builder()
+    .subscriptionNetworkTransport(
+        WebSocketNetworkTransport.Builder()
+            .webSocketEngine(webSocketEngine)
+            .build()
+    )
+    .build()
+```
+
+The default WebSocket protocol has changed to [graphql-ws](https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md).
+
+If you were already using it before, you may remove the call to `protocol()` or define it explicitly using `subscriptionNetworkTransport()`:
+
+```kotlin
+// Replace
+val apolloClient = ApolloClient.Builder()
+    .protocol(GraphQLWsProtocol.Factory())
+    .build()
+    
+// With
+val apolloClient = ApolloClient.Builder()
+    .subscriptionNetworkTransport(
+        WebSocketNetworkTransport.Builder()
+            .serverUrl(url)
+            .wsProtocol(GraphQLWsProtocol())
+            .build()
+    )
+    .build()
+
+```
+
+If you are still relying on [the (now deprecated) transport](https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md), you can use `SubscriptionWsProtocol`:
+
+```kotlin
+val apolloClient = ApolloClient.Builder()
+    .subscriptionNetworkTransport(
+        WebSocketNetworkTransport.Builder()
+            .serverUrl(url)
+            .wsProtocol(SubscriptionsWsProtocol())
+            .build()
+    )
+    .build()
+```
+
+The retry management is now moved to `retryOnErrorInterceptor`:   
+
+```kotlin
+// Replace
+val apolloClient = ApolloClient.Builder()
+    .webSocketServerUrl("http://localhost:8080/subscriptions")
+    .webSocketReopenWhen { e, attempt ->
+      delay(2.0.pow(attempt.toDouble()).toLong())
+      // retry after the delay
+      true
+    }
+
+// With
+val apolloClient = ApolloClient.Builder()
+    .webSocketServerUrl("http://localhost:8080/subscriptions")
+    .retryOnErrorInterceptor(RetryOnErrorInterceptor { context ->
+      if (context.request.operation is Subscription<*>) {
+        delay(2.0.pow(context.attempt.toDouble()).toLong())
+        true
+      } else {
+        false
+      }
+    })
+```
+
 ## `apollo-http-cache`
 
 `apollo-http-cache` is now deprecated. Instead, it uses the existing OkHttp cache using [cacheUrlOverride](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-request/-builder/cache-url-override.html).

libraries/apollo-engine-tests/src/commonMain/kotlin/com/apollographql/apollo/engine/tests/WebSocketEngineTest.kt

@@ -1,3 +1,4 @@
+@file:Suppress("DEPRECATION")
 package com.apollographql.apollo.engine.tests
 
 import com.apollographql.apollo.annotations.ApolloInternal

libraries/apollo-engine-tests/src/commonMain/kotlin/com/apollographql/apollo/engine/tests/all-tests.kt

@@ -1,3 +1,4 @@
+@file:Suppress("DEPRECATION")
 package com.apollographql.apollo.engine.tests
 
 import com.apollographql.apollo.annotations.ApolloInternal

libraries/apollo-engine-tests/src/commonTest/kotlin/AllTests.kt

@@ -1,3 +1,5 @@
+@file:Suppress("DEPRECATION")
+
 import com.apollographql.apollo.engine.tests.Platform
 import com.apollographql.apollo.engine.tests.platform
 import com.apollographql.apollo.engine.tests.runAllTests

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

@@ -231,20 +231,25 @@ public final class com/apollographql/apollo/interceptor/AutoPersistedQueryInterc
 public final class com/apollographql/apollo/interceptor/AutoPersistedQueryInterceptor$Companion {
 }
 
+public final class com/apollographql/apollo/interceptor/RetryContext {
+	public fun <init> (Lcom/apollographql/apollo/network/NetworkMonitor;Lcom/apollographql/apollo/api/ApolloRequest;)V
+	public final fun getAttempt ()I
+	public final fun getNetworkMonitor ()Lcom/apollographql/apollo/network/NetworkMonitor;
+	public final fun getRequest ()Lcom/apollographql/apollo/api/ApolloRequest;
+	public final fun getResponse ()Lcom/apollographql/apollo/api/ApolloResponse;
+	public final fun resetAttempt ()V
+}
+
 public final class com/apollographql/apollo/interceptor/RetryOnErrorInterceptorKt {
+	public static final fun RetryOnErrorInterceptor ()Lcom/apollographql/apollo/interceptor/ApolloInterceptor;
 	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 static synthetic fun RetryOnErrorInterceptor$default (Lcom/apollographql/apollo/network/NetworkMonitor;Lcom/apollographql/apollo/interceptor/RetryStrategy;ILjava/lang/Object;)Lcom/apollographql/apollo/interceptor/ApolloInterceptor;
+	public static final fun getDefaultRetryStrategy ()Lcom/apollographql/apollo/interceptor/RetryStrategy;
 }
 
 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 abstract fun shouldRetry (Lcom/apollographql/apollo/interceptor/RetryContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 }
 
 public final class com/apollographql/apollo/network/IncrementalDeliveryProtocol : java/lang/Enum {
@@ -538,6 +543,7 @@ public abstract interface class com/apollographql/apollo/network/websocket/WebSo
 }
 
 public final class com/apollographql/apollo/network/websocket/WebSocketEngine_jvmKt {
+	public static final fun DefaultWebSocketEngine (Lokhttp3/WebSocket$Factory;)Lcom/apollographql/apollo/network/websocket/WebSocketEngine;
 	public static final fun WebSocketEngine ()Lcom/apollographql/apollo/network/websocket/WebSocketEngine;
 	public static final fun WebSocketEngine (Lkotlin/jvm/functions/Function0;)Lcom/apollographql/apollo/network/websocket/WebSocketEngine;
 	public static final fun WebSocketEngine (Lokhttp3/WebSocket$Factory;)Lcom/apollographql/apollo/network/websocket/WebSocketEngine;
@@ -556,16 +562,19 @@ public final class com/apollographql/apollo/network/websocket/WebSocketNetworkTr
 	public final fun closeConnection (Lcom/apollographql/apollo/exception/ApolloException;)V
 	public fun dispose ()V
 	public fun execute (Lcom/apollographql/apollo/api/ApolloRequest;)Lkotlinx/coroutines/flow/Flow;
+	public final fun getSubscriptionCount ()Lkotlinx/coroutines/flow/StateFlow;
 }
 
 public final class com/apollographql/apollo/network/websocket/WebSocketNetworkTransport$Builder {
 	public fun <init> ()V
 	public final fun build ()Lcom/apollographql/apollo/network/websocket/WebSocketNetworkTransport;
 	public final fun connectionAcknowledgeTimeout-BwNAW2A (Lkotlin/time/Duration;)Lcom/apollographql/apollo/network/websocket/WebSocketNetworkTransport$Builder;
 	public final fun idleTimeout-BwNAW2A (Lkotlin/time/Duration;)Lcom/apollographql/apollo/network/websocket/WebSocketNetworkTransport$Builder;
+	public final fun idleTimeoutMillis (Ljava/lang/Long;)Lcom/apollographql/apollo/network/websocket/WebSocketNetworkTransport$Builder;
 	public final fun incrementalDeliveryProtocol (Lcom/apollographql/apollo/network/IncrementalDeliveryProtocol;)Lcom/apollographql/apollo/network/websocket/WebSocketNetworkTransport$Builder;
 	public final fun parserFactory (Lcom/apollographql/apollo/network/websocket/SubscriptionParserFactory;)Lcom/apollographql/apollo/network/websocket/WebSocketNetworkTransport$Builder;
 	public final fun pingInterval-BwNAW2A (Lkotlin/time/Duration;)Lcom/apollographql/apollo/network/websocket/WebSocketNetworkTransport$Builder;
+	public final fun protocol (Lcom/apollographql/apollo/network/websocket/WsProtocol;)Lcom/apollographql/apollo/network/websocket/WebSocketNetworkTransport$Builder;
 	public final fun serverUrl (Ljava/lang/String;)Lcom/apollographql/apollo/network/websocket/WebSocketNetworkTransport$Builder;
 	public final fun webSocketEngine (Lcom/apollographql/apollo/network/websocket/WebSocketEngine;)Lcom/apollographql/apollo/network/websocket/WebSocketNetworkTransport$Builder;
 	public final fun wsProtocol (Lcom/apollographql/apollo/network/websocket/WsProtocol;)Lcom/apollographql/apollo/network/websocket/WebSocketNetworkTransport$Builder;