Add graphql-ws protocol support

Sources/ApolloWebSocket/DefaultImplementation/WebSocket.swift

@@ -68,8 +68,11 @@ public final class WebSocket: NSObject, WebSocketClient, StreamDelegate, WebSock
     public let code: Int
   }
 
+  /// The WebSocket sub-protocols supported.
   public enum WSProtocol: CustomStringConvertible {
+    /// Protocol implemented by the graphql-ws library.
     case graphql_ws
+    /// Protocol implemented by the subscriptions-transport-ws libary - considered legacy.
     case graphql_transport_ws
 
     public var description: String {

docs/source/subscriptions.md

@@ -19,6 +19,20 @@ There are two different classes which conform to the [`NetworkTransport` protoco
 
 Typically, you'll want to use `SplitNetworkTransport`, since this allows you to retain the single `NetworkTransport` setup and avoids any potential issues of using multiple client objects. 
 
+## GraphQL over WebSocket Protocols
+
+There are two WebSocket sub-protocols that apollo-ios supports:
+1. [graphql-transport-ws](https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md) which is implemented in the [graphql-ws](https://github.com/enisdenjo/graphql-ws) package. This is a modern, actively maintained package and is our recommendation to use in your server.
+2. [graphql-ws](https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md) which is implemented in the [subscriptions-transport-ws](https://github.com/apollographql/subscriptions-transport-ws) package. This is considered a legacy implementation and is not recommended for new server builds.
+
+It is important to note that the two libraries and protocols are not cross-compatible. You will need to know which sub-protocol is implemented in the server you're connecting to.
+
+There are a number of ways to specify which sub-protocol apollo-ios should use:
+1. Manually specify the protocol in the `Sec-WebSocket-Protocol` header of a `URLRequest`. This must be done before initializing a WebSocket using `WebSocket(request:)` as apollo-ios will look for the header key and if found it will use that protocol otherwise it will default to using the `graphql-transport-ws`. See `WebSocket.WSProtocol` for the header values.
+2. Use one of the convenience initializers `WebSocket(url:webSocketProtocol:)` or `WebSocket(url:writeQueueQOS:webSocketProtocol:)` where you can specify the protocol on initialization.
+
+Using `graphql-transport-ws` as the default may seem odd since it's considered a legacy protocol but this was done to not force a breaking change to pre-existing apps using apollo-ios.
+
 ## Sample subscription-supporting initializer 
 
 Here is an example of setting up a singleton similar to the [Example Advanced Client Setup](initialization/#advanced-client-creation), but which uses a `SplitNetworkTransport` to support both subscriptions and queries: 
@@ -36,8 +50,7 @@ class Apollo {
   /// A web socket transport to use for subscriptions  
   private lazy var webSocketTransport: WebSocketTransport = {
     let url = URL(string: "ws://localhost:8080/websocket")!
-    let request = URLRequest(url: url)
-    let webSocketClient = WebSocket(request: request)
+    let webSocketClient = WebSocket(url: url, webSocketProtocol: .graphql_ws)
     return WebSocketTransport(websocket: webSocketClient)
   }()
 
@@ -161,8 +174,7 @@ class Apollo {
   // initializes the connection as an authorized channel.
   private lazy var webSocketTransport: WebSocketTransport = {
     let url = URL(string: "ws://localhost:8080/websocket")!
-    let request = URLRequest(url: url)
-    let webSocketClient = WebSocket(request: request)
+    let webSocketClient = WebSocket(url: url, webSocketProtocol: .graphql_ws)
     let authPayload = ["authToken": magicToken]
     return WebSocketTransport(websocket: webSocketClient, connectingPayload: authPayload)
   }()

docs/source/tutorial/tutorial-subscriptions.md

@@ -73,14 +73,19 @@ Next, in the lazy declaration of the `apollo` variable, immediately after `trans
 
 ```swift:title=Network.swift
 // 1
-let webSocket = WebSocket(url: URL(string: "wss://apollo-fullstack-tutorial.herokuapp.com/graphql")!)
+let webSocket = WebSocket(
+  url: URL(string: "wss://apollo-fullstack-tutorial.herokuapp.com/graphql")!,
+  webSocketProtocol: .graphql_ws
+)
 
 // 2
 let webSocketTransport = WebSocketTransport(websocket: webSocket)
 
 // 3
-let splitTransport = SplitNetworkTransport(uploadingNetworkTransport: transport,
-                                                   webSocketNetworkTransport: webSocketTransport)
+let splitTransport = SplitNetworkTransport(
+  uploadingNetworkTransport: transport,
+  webSocketNetworkTransport: webSocketTransport
+)
 
 // 4
 return ApolloClient(networkTransport: splitTransport, store: store)