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.apollo.network.websocket package containing new WebSocketNetworkTransport and WebSocketEngine implementations (instead of com.apollographql.apollo.network.ws for the current implementations).

The com.apollographql.apollo.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 your 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 will be 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

Package name

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

1// Replace
2import com.apollographql.apollo.network.ws.WebSocketNetworkTransport
3import com.apollographql.apollo.network.ws.WebSocketEngine
4// etc...
5
6// With
7import com.apollographql.apollo.network.websocket.WebSocketNetworkTransport
8import com.apollographql.apollo.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
2val apolloClient = ApolloClient.Builder()
3    .serverUrl(serverUrl)
4    .webSocketServerUrl(webSocketServerUrl)
5    .webSocketEngine(myWebSocketEngine)
6    .webSocketIdleTimeoutMillis(10_000)
7    .build()
8
9// With
10import com.apollographql.apollo.network.websocket.*
11    
12// [...]
13
14ApolloClient.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()

Connection init payload

If you were using connectionPayload before, you can now pass it as an argument directly. There is no WsProtocol.Factory anymore:

1// Replace
2GraphQLWsProtocol.Factory(
3    connectionPayload = {
4        mapOf("Authorization" to token)
5    },
6)
7
8// With
9GraphQLWsProtocol(
10    connectionPayload = {
11      mapOf("Authorization" to token)
12    },
13)

Retrying on network errors

Apollo Kotlin 4 also comes with a default retryOnErrorInterceptor that uses a network monitor or exponential backoff to retry the subscription.

If you want your subscription to be restarted automatically when a network error happens, use retryOnError {}:

1// Replace
2val apolloClient = ApolloClient.Builder()
3    .serverUrl(serverUrl)
4    .subscriptionNetworkTransport(
5        WebSocketNetworkTransport.Builder()
6            .serverUrl(webSocketServerUrl)
7            .reopenWhen { _, attempt ->
8              // exponential backoff
9              delay(2.0.pow(attempt).seconds)
10              true
11            }
12            .build()
13    )
14    .build()
15
16// With 
17val apolloClient = ApolloClient.Builder()
18    .serverUrl(serverUrl)
19    .subscriptionNetworkTransport(/*..*/)
20    .retryOnError {
21      /*
22       * This is called for every GraphQL operation.
23       * Only retry subscriptions.
24       */
25      it.operation is Subscription
26    }
27    .build()

You can also customize the retry logic using retryOnErrorInterceptor. Read more about it in the network connectivity page.