Experimental websockets

Historically, WebSockets have been one of the most complex and error-prone parts of Apollo Kotlin because:

1. The WebSocket transport protocol has no official specification and different implementations have different behaviours.
2. WebSockets are stateful and making them work using the old Kotlin native memory model was challenging.
3. Because WebSockets are long-lived connections, they are more exposed to errors and knowing when (or if) to retry is hard.
4. Not all subscriptions happen on WebSockets. Some use HTTP multipart for an example.

Starting with 4.0.0, Apollo Kotlin provides a new com.apollographql.apollo3.network.websocket package containing new WebSocketNetworkTransport and WebSocketEngine implementations (instead of com.apollographql.apollo3.network.ws for the current implementations).

The com.apollographql.apollo3.network.websocket implementation provides the following:

1. Defaults to the graphql-ws protocol, which has become the de facto standard. Using the other protocols is still possible but having a main, specified, protocol ensures we can write a good and solid test suite.
2. Does not inherit from the old memory model design, making the code considerably simpler. In particular, WebSocketEngine is now event based and no attempt at flow control is done. If you buffers grow too much, your subscription fails.
3. Plays nicely with the ApolloClient retryOnError API.
4. Handles different Subscription transports more consistently.

Status

While they are @ApolloExperimental, we believe the new .websocket APIS to be more robust than the non-experimental .ws ones. They are safe to use in non-lib use cases.

The "experimental" tag is to account for required API breaking changes based on community feedback. Ideally no change is needed.

After a feedback phase, the current .ws APIs will become deprecated and the .websocket one promoted to stable by removing the @ApolloExperimental annotations.

Migration guide

In simple cases where you did not configure the underlying WsProtocol or retry logic, the migration should be about replacing com.apollographql.apollo3.network.ws with com.apollographql.apollo3.network.websocket everywhere:

1
// Replace
2
import com.apollographql.apollo3.network.ws.WebSocketNetworkTransport
3
import com.apollographql.apollo3.network.ws.WebSocketEngine
4
// etc...
5

6
// With
7
import com.apollographql.apollo3.network.websocket.WebSocketNetworkTransport
8
import com.apollographql.apollo3.network.websocket.WebSocketEngine
9
// etc...

Because we can't remove the current APIs just yet, the ApolloClient.Builder shortcut APIs are still pointing to the .ws implementations. To use the newer .websocket implementation, pass a websocket.WebSocketNetworkTransport directly:

1
// Replace
2
val apolloClient = ApolloClient.Builder()
3
    .serverUrl(serverUrl)
4
    .webSocketServerUrl(webSocketServerUrl)
5
    .webSocketEngine(myWebSocketEngine)
6
    .webSocketIdleTimeoutMillis(10_000)
7
    .build()
8

9
// With
10
import com.apollographql.apollo3.network.websocket.*
11
    
12
// [...]
13

14
ApolloClient.Builder()
15
    .serverUrl(serverUrl)
16
    .subscriptionNetworkTransport(
17
        WebSocketNetworkTransport.Builder()
18
            .serverUrl(webSocketServerUrl)
19
            // If you didn't set a WsProtocol before, make sure to include this 
20
            .wsProtocol(SubscriptionWsProtocol())
21
            // If you were already using GraphQLWsProtocol, this is now the default
22
            //.wsProtocol(GraphQLWsProtocol())
23
            .webSocketEngine(myWebSocketEngine)
24
            .idleTimeoutMillis(10_000)
25
            .build()
26
    )
27
    .build()

To account for non-websocket transports, like multipart subscriptions, the retry is now handled on the ApolloClient instead of the NetworkTransport.

1
// Replace
2
val apolloClient = ApolloClient.Builder()
3
    .subscriptionNetworkTransport(
4
        WebSocketNetworkTransport.Builder()
5
            .serverUrl(url)
6
            .reopenWhen { _, _ ->
7
              delay(1000)
8
              true
9
            }
10
            .build()
11
    )
12

13
// With
14
val apolloClient = ApolloClient.Builder()
15
    .subscriptionNetworkTransport(
16
        WebSocketNetworkTransport.Builder()
17
            .serverUrl(url)
18
            .build()
19
    )
20
    // Only retry subscriptions
21
    .retryOnError { it.operation is Subscription }

The above uses the default retry algorithm:

• Wait until the network is available if you configured a NetworkMonitor.
• Or use exponential backoff else.

To customize the retry logic more, use addRetryOnErrorInterceptor:

1
val apolloClient = ApolloClient.Builder()
2
    .subscriptionNetworkTransport(
3
        WebSocketNetworkTransport.Builder()
4
            .serverUrl(url)
5
            .build()
6
    )
7
    .addRetryOnErrorInterceptor { apolloRequest, exception, attempt -> 
8
      // retry logic here
9
      
10
      // return true to retry or false to terminate the Flow
11
      true
12
    }