doc: Adds protocol docs and readme usage examples

Author: NeedleInAJayStack

README.md

@@ -1,18 +1,136 @@
 # GraphQLWS
 
 This implements the [graphql-ws WebSocket subprotocol](https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md).
-It is mainly intended for Server support, but there is a basic client implementation included.
+It is mainly intended for server support, but there is a basic client implementation included.
 
 Features:
 - Server implementation that implements defined protocol conversations
 - Client and Server types that wrap messengers
 - Codable Server and Client message structures
+- Custom authentication support
+
+## Usage
+
+To use this package, include it in your `Package.swift` dependencies:
+
+```swift
+.package(url: "git@gitlab.com:PassiveLogic/platform/GraphQLWS.git", from: "<version>"),
+```
+
+Then create a class to implement the `Messenger` protocol. Here's an example using
+[`WebSocketKit`](https://github.com/vapor/websocket-kit):
+
+```swift
+import WebSocketKit
+import GraphQLWS
+
+/// Messenger wrapper for WebSockets
+class WebSocketMessenger: Messenger {
+    private weak var websocket: WebSocket?
+    private var onRecieve: (String) -> Void = { _ in }
+    
+    init(websocket: WebSocket) {
+        self.websocket = websocket
+        websocket.onText { _, message in
+            self.onRecieve(message)
+        }
+    }
+    
+    func send<S>(_ message: S) where S: Collection, S.Element == Character {
+        guard let websocket = websocket else { return }
+        websocket.send(message)
+    }
+    
+    func onRecieve(callback: @escaping (String) -> Void) {
+        self.onRecieve = callback
+    }
+    
+    func error(_ message: String, code: Int) {
+        guard let websocket = websocket else { return }
+        websocket.send("\(code): \(message)")
+    }
+    
+    func close() {
+        guard let websocket = websocket else { return }
+        _ = websocket.close()
+    }
+}
+```
+
+Next create a `Server`, provide the messenger you just defined, and wrap the API `execute` and `subscribe` commands:
+
+```swift
+routes.webSocket(
+    "graphqlSubscribe",
+    onUpgrade: { request, websocket in
+        let messenger = WebSocketMessenger(websocket: websocket)
+        let server = GraphQLWS.Server<EmptyInitPayload?>(
+            messenger: messenger,
+            onExecute: { graphQLRequest in
+                api.execute(
+                    request: graphQLRequest.query,
+                    context: context,
+                    on: self.eventLoop,
+                    variables: graphQLRequest.variables,
+                    operationName: graphQLRequest.operationName
+                )
+            },
+            onSubscribe: { graphQLRequest in
+                api.subscribe(
+                    request: graphQLRequest.query,
+                    context: context,
+                    on: self.eventLoop,
+                    variables: graphQLRequest.variables,
+                    operationName: graphQLRequest.operationName
+                )
+            }
+        )
+    }
+)
+```
+
+### Authentication
+
+This package exposes authentication hooks on the `connection_init` message. To perform custom authentication,
+provide a codable type to the Server init and define an `auth` callback on the server. For example:
+
+```swift
+struct UsernameAndPasswordInitPayload: Equatable & Codable {
+    let username: String
+    let password: String
+}
+
+let server = GraphQLWS.Server<UsernameAndPasswordInitPayload>(
+    messenger: messenger,
+    onExecute: { ... },
+    onSubscribe: { ... }
+)
+server.auth { payload in
+    guard payload.username == "admin" else {
+        throw Abort(.unauthorized)
+    }
+}
+```
+
+This example would require `connection_init` message from the client to look like this:
+
+```json
+{
+    "type": "connection_init",
+    "payload": {
+        "username": "admin",
+        "password": "supersafe"
+    }
+}
+```
+
+If the `payload` field is not required on your server, you may make Server's generic declaration optional like `Server<Payload?>`
 
 ## Memory Management
 
-Memory ownership among the Server, Client, and Messager may seem a little backwards. This is because the Swift/Vapor WebSocket 
+Memory ownership among the Server, Client, and Messenger may seem a little backwards. This is because the Swift/Vapor WebSocket 
 implementation persists WebSocket objects long after their callback and they are expected to retain strong memory references to the 
-objects required for responses. In order to align cleanly and avoid memory cycles, Server and Client are injected strongly into Messager
-callbacks, and only hold weak references to their Messager. This means that Messager objects (or their enclosing WebSocket) must
-be persisted to have the connected Server or Client objects function. That is, if a Server's Messager falls out of scope and deinitializes,
+objects required for responses. In order to align cleanly and avoid memory cycles, Server and Client are injected strongly into Messenger
+callbacks, and only hold weak references to their Messenger. This means that Messenger objects (or their enclosing WebSocket) must
+be persisted to have the connected Server or Client objects function. That is, if a Server's Messenger falls out of scope and deinitializes,
 the Server will no longer respond to messages.

Sources/GraphQLWS/Messenger.swift

@@ -3,11 +3,23 @@
 import Foundation
 import NIO
 
-/// Protocol for an object that can send and recieve messages
+/// Protocol for an object that can send and recieve messages. This allows mocking in tests
 public protocol Messenger: AnyObject {
     // AnyObject compliance requires that the implementing object is a class and we can reference it weakly
+    
+    /// Send a message through this messenger
+    /// - Parameter message: The message to send
     func send<S>(_ message: S) -> Void where S: Collection, S.Element == Character
+    
+    /// Set the callback that should be run when a message is recieved
     func onRecieve(callback: @escaping (String) -> Void) -> Void
+    
+    /// Close the messenger
     func close() -> Void
+    
+    /// Indicate that the messenger experienced an error.
+    /// - Parameters:
+    ///   - message: The message describing the error
+    ///   - code: An error code
     func error(_ message: String, code: Int) -> Void
 }

Sources/GraphQLWS/Server.swift

@@ -7,6 +7,8 @@ import NIO
 import RxSwift
 
 /// Server implements the server-side portion of the protocol, allowing a few callbacks for customization.
+///
+/// By default, there are no authorization checks
 public class Server<InitPayload: Equatable & Codable> {
     // We keep this weak because we strongly inject this object into the messenger callback
     weak var messenger: Messenger?

Tests/GraphQLWSTests/GraphQLWSTests.swift

@@ -14,9 +14,9 @@ class GraphqlWsTests: XCTestCase {
     var server: Server<TokenInitPayload>!
 
     override func setUp() {
+        // Point the client and server at each other
         clientMessenger = TestMessenger()
         serverMessenger = TestMessenger()
-        
         clientMessenger.other = serverMessenger
         serverMessenger.other = clientMessenger