Merge branch 'feature/OpenSourcePrep' into 'master'

Open Source Prep

See merge request PassiveLogic/platform/graphqlws!4

Author: Austinpayne

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/Client.swift

@@ -4,7 +4,7 @@ import Foundation
 import GraphQL
 
 /// Client is an open-ended implementation of the client side of the protocol. It parses and adds callbacks for each type of server respose.
-public class Client {
+public class Client<InitPayload: Equatable & Codable> {
     // We keep this weak because we strongly inject this object into the messenger callback
     weak var messenger: Messenger?
 
@@ -136,7 +136,7 @@ public class Client {
     }
 
     /// Send a `connection_init` request through the messenger
-    public func sendConnectionInit(payload: ConnectionInitAuth?) {
+    public func sendConnectionInit(payload: InitPayload) {
         guard let messenger = messenger else { return }
         messenger.send(
             ConnectionInitRequest(

Sources/GraphQLWS/InitPayloads.swift

@@ -0,0 +1,9 @@
+// Contains convenient `connection_init` payloads for users of this package
+
+/// `connection_init` `payload` that is empty
+public struct EmptyInitPayload: Equatable & Codable { }
+
+/// `connection_init` `payload` that includes an `authToken` field
+public struct TokenInitPayload: Equatable & Codable {
+    let authToken: String
+}

Sources/GraphQLWS/Messenger.swift

@@ -3,12 +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
-    func onClose(callback: @escaping () -> 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/Requests.swift

@@ -20,19 +20,9 @@ struct Request: Equatable, JsonEncodable {
 }
 
 /// A websocket `connection_init` request from the client to the server
-public struct ConnectionInitRequest: Equatable, JsonEncodable {
+public struct ConnectionInitRequest<InitPayload: Codable & Equatable>: Equatable, JsonEncodable {
     var type = RequestMessageType.GQL_CONNECTION_INIT
-    public let payload: ConnectionInitAuth?
-}
-
-// TODO: Make this structure user-defined
-/// Authorization format for a websocket `connection_init` request from the client to the server
-public struct ConnectionInitAuth: Equatable, JsonEncodable {
-    public let authToken: String
-    
-    public init(authToken: String) {
-        self.authToken = authToken
-    }
+    let payload: InitPayload
 }
 
 /// A websocket `start` request from the client to the server

Sources/GraphQLWS/Server.swift

@@ -7,14 +7,16 @@ import NIO
 import RxSwift
 
 /// Server implements the server-side portion of the protocol, allowing a few callbacks for customization.
-public class Server {
+///
+/// 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?
 
     let onExecute: (GraphQLRequest) -> EventLoopFuture<GraphQLResult>
     let onSubscribe: (GraphQLRequest) -> EventLoopFuture<SubscriptionResult>
 
-    var auth: (ConnectionInitRequest) throws -> Void = { _ in }
+    var auth: (InitPayload) throws -> Void = { _ in }
     var onExit: () -> Void = { }
     var onMessage: (String) -> Void = { _ in }
 
@@ -66,7 +68,7 @@ public class Server {
 
             switch request.type {
                 case .GQL_CONNECTION_INIT:
-                    guard let connectionInitRequest = try? self.decoder.decode(ConnectionInitRequest.self, from: json) else {
+                    guard let connectionInitRequest = try? self.decoder.decode(ConnectionInitRequest<InitPayload>.self, from: json) else {
                         self.error(.invalidRequestFormat(messageType: .GQL_CONNECTION_INIT))
                         return
                     }
@@ -96,9 +98,9 @@ public class Server {
     }
 
     /// Define the callback run during `connection_init` resolution that allows authorization using the `payload`.
-    /// Throw to indicate that authorization has failed.
+    /// Throw from this closure to indicate that authorization has failed.
     /// - Parameter callback: The callback to assign
-    public func auth(_ callback: @escaping (ConnectionInitRequest) throws -> Void) {
+    public func auth(_ callback: @escaping (InitPayload) throws -> Void) {
         self.auth = callback
     }
 
@@ -114,14 +116,14 @@ public class Server {
         self.onMessage = callback
     }
 
-    private func onConnectionInit(_ connectionInitRequest: ConnectionInitRequest, _ messenger: Messenger) {
+    private func onConnectionInit(_ connectionInitRequest: ConnectionInitRequest<InitPayload>, _ messenger: Messenger) {
         guard !initialized else {
             self.error(.tooManyInitializations())
             return
         }
 
         do {
-            try self.auth(connectionInitRequest)
+            try self.auth(connectionInitRequest.payload)
         }
         catch {
             self.error(.unauthorized())

Tests/GraphQLWSTests/GraphQLWSTests.swift

@@ -11,20 +11,20 @@ import XCTest
 class GraphqlWsTests: XCTestCase {
     var clientMessenger: TestMessenger!
     var serverMessenger: TestMessenger!
-    var server: Server!
+    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
 
         let eventLoop = MultiThreadedEventLoopGroup(numberOfThreads: 1).next()
         let api = TestAPI()
         let context = TestContext()
 
-        server = Server(
+        server = Server<TokenInitPayload>(
             messenger: serverMessenger,
             onExecute: { graphQLRequest in
                 api.execute(
@@ -48,7 +48,7 @@ class GraphqlWsTests: XCTestCase {
         var messages = [String]()
         let completeExpectation = XCTestExpectation()
 
-        let client = Client(messenger: clientMessenger)
+        let client = Client<TokenInitPayload>(messenger: clientMessenger)
         client.onMessage { message, _ in
             messages.append(message)
             completeExpectation.fulfill()
@@ -81,14 +81,14 @@ class GraphqlWsTests: XCTestCase {
         var messages = [String]()
         let completeExpectation = XCTestExpectation()
 
-        let client = Client(messenger: clientMessenger)
+        let client = Client<TokenInitPayload>(messenger: clientMessenger)
         client.onMessage { message, _ in
             messages.append(message)
             completeExpectation.fulfill()
         }
 
         client.sendConnectionInit(
-            payload: ConnectionInitAuth(
+            payload: TokenInitPayload(
                 authToken: ""
             )
         )
@@ -100,14 +100,15 @@ class GraphqlWsTests: XCTestCase {
         )
     }
 
+    /// Test single op message flow works as expected
     func testSingleOp() throws {
         let id = UUID().description
 
         // Test single-op conversation
         var messages = [String]()
         let completeExpectation = XCTestExpectation()
 
-        let client = Client(messenger: clientMessenger)
+        let client = Client<TokenInitPayload>(messenger: clientMessenger)
 
         client.onConnectionAck { _, client in
             client.sendStart(
@@ -131,7 +132,7 @@ class GraphqlWsTests: XCTestCase {
             messages.append(message)
         }
 
-        client.sendConnectionInit(payload: ConnectionInitAuth(authToken: ""))
+        client.sendConnectionInit(payload: TokenInitPayload(authToken: ""))
 
         wait(for: [completeExpectation], timeout: 2)
         XCTAssertEqual(
@@ -141,6 +142,7 @@ class GraphqlWsTests: XCTestCase {
         )
     }
 
+    /// Test streaming message flow works as expected
     func testStreaming() throws {
         let id = UUID().description
 
@@ -151,7 +153,7 @@ class GraphqlWsTests: XCTestCase {
         var dataIndex = 1
         let dataIndexMax = 3
 
-        let client = Client(messenger: clientMessenger)
+        let client = Client<TokenInitPayload>(messenger: clientMessenger)
         client.onConnectionAck { _, client in
             client.sendStart(
                 payload: GraphQLRequest(
@@ -187,7 +189,7 @@ class GraphqlWsTests: XCTestCase {
             messages.append(message)
         }
 
-        client.sendConnectionInit(payload: ConnectionInitAuth(authToken: ""))
+        client.sendConnectionInit(payload: TokenInitPayload(authToken: ""))
 
         wait(for: [completeExpectation], timeout: 2)
         XCTAssertEqual(