Merge pull request #1180 from zino-hofmann/macros/docs_ws

improve grapphql ws protocol docs

Author: vincenzopalazzo

packages/graphql/lib/src/links/websocket_link/websocket_client.dart

@@ -141,10 +141,37 @@ class SocketClientConfig {
   }
 }
 
+/// All the protocol supported by the library
+@Deprecated(
+    "`SocketSubProtocol`is deprecated and will be removed in the version 5.2.0, consider to use `GraphQLProtocol`")
 class SocketSubProtocol {
   SocketSubProtocol._();
 
+  /// graphql-ws: The new  (not to be confused with the graphql-ws library).
+  /// NB. This protocol is it no longer maintained, please consider
+  /// to use `SocketSubProtocol.graphqlTransportWs`.
+  static const String graphqlWs = GraphQLProtocol.graphqlWs;
+
+  /// graphql-transport-ws: New ws protocol used by most Apollo Server instances
+  /// with subscriptions enabled use this library.
+  /// N.B: not to be confused with the graphql-ws library that implement the
+  /// old ws protocol.
+  static const String graphqlTransportWs = GraphQLProtocol.graphqlWs;
+}
+
+/// ALL protocol supported by the library
+class GraphQLProtocol {
+  GraphQLProtocol._();
+
+  /// graphql-ws: The new  (not to be confused with the graphql-ws library).
+  /// NB. This protocol is it no longer maintained, please consider
+  /// to use `SocketSubProtocol.graphqlTransportWs`.
   static const String graphqlWs = "graphql-ws";
+
+  /// graphql-transport-ws: New ws protocol used by most Apollo Server instances
+  /// with subscriptions enabled use this library.
+  /// N.B: not to be confused with the graphql-ws library that implement the
+  /// old ws protocol.
   static const String graphqlTransportWs = "graphql-transport-ws";
 }
 
@@ -159,7 +186,7 @@ class SocketSubProtocol {
 class SocketClient {
   SocketClient(
     this.url, {
-    this.protocol = SocketSubProtocol.graphqlWs,
+    this.protocol = GraphQLProtocol.graphqlWs,
     this.config = const SocketClientConfig(),
     @visibleForTesting this.randomBytesForUuid,
     @visibleForTesting this.onMessage,
@@ -247,14 +274,14 @@ class SocketClient {
           await config.connect(uri: Uri.parse(url), protocols: [protocol]);
       socketChannel = connection.forGraphQL();
 
-      if (protocol == SocketSubProtocol.graphqlTransportWs) {
+      if (protocol == GraphQLProtocol.graphqlTransportWs) {
         _connectionStateController.add(SocketConnectionState.handshake);
       } else {
         _connectionStateController.add(SocketConnectionState.connected);
       }
       print('Initialising connection');
       _write(initOperation);
-      if (protocol == SocketSubProtocol.graphqlTransportWs) {
+      if (protocol == GraphQLProtocol.graphqlTransportWs) {
         // wait for ack
         // this blocks to prevent ping from being called before ack is recieved
         await _messages.firstWhere(
@@ -263,10 +290,10 @@ class SocketClient {
       }
 
       if (config.inactivityTimeout != null) {
-        if (protocol == SocketSubProtocol.graphqlWs) {
+        if (protocol == GraphQLProtocol.graphqlWs) {
           _disconnectOnKeepAliveTimeout(_messages);
         }
-        if (protocol == SocketSubProtocol.graphqlTransportWs) {
+        if (protocol == GraphQLProtocol.graphqlTransportWs) {
           _enqueuePing();
         }
       }
@@ -277,7 +304,7 @@ class SocketClient {
             onMessage!(message);
           }
 
-          if (protocol == SocketSubProtocol.graphqlTransportWs) {
+          if (protocol == GraphQLProtocol.graphqlTransportWs) {
             if (message.type == 'ping') {
               _write(PongMessage());
             } else if (message.type == 'pong') {
@@ -494,7 +521,7 @@ class SocketClient {
             id,
             serialize(payload),
           );
-          if (protocol == SocketSubProtocol.graphqlTransportWs) {
+          if (protocol == GraphQLProtocol.graphqlTransportWs) {
             operation = SubscribeOperation(
               id,
               serialize(payload),
@@ -512,7 +539,7 @@ class SocketClient {
       _subscriptionInitializers.remove(id);
 
       sub?.cancel();
-      if (protocol == SocketSubProtocol.graphqlWs &&
+      if (protocol == GraphQLProtocol.graphqlWs &&
           _connectionStateController.value == SocketConnectionState.connected &&
           socketChannel != null) {
         _write(StopOperation(id));

packages/graphql/lib/src/links/websocket_link/websocket_link.dart

@@ -16,7 +16,7 @@ class WebSocketLink extends Link {
   WebSocketLink(
     this.url, {
     this.config = const SocketClientConfig(),
-    this.subProtocol = SocketSubProtocol.graphqlWs,
+    this.subProtocol = GraphQLProtocol.graphqlWs,
   });
 
   final String url;

packages/graphql/test/websocket_test.dart

@@ -18,7 +18,7 @@ SocketClient getTestClient({
   bool autoReconnect = true,
   Map<String, dynamic>? customHeaders,
   Duration delayBetweenReconnectionAttempts = const Duration(milliseconds: 1),
-  String protocol = SocketSubProtocol.graphqlWs,
+  String protocol = GraphQLProtocol.graphqlWs,
 }) =>
     SocketClient(
       wsUrl,
@@ -340,7 +340,7 @@ Future<void> main() async {
       controller = StreamController(sync: true);
       socketClient = getTestClient(
         controller: controller,
-        protocol: SocketSubProtocol.graphqlTransportWs,
+        protocol: GraphQLProtocol.graphqlTransportWs,
         wsUrl: wsUrl,
       );
     }));