Merge branch 'feature/OpenSourcePrep' into 'master'

Open Source Prep

See merge request PassiveLogic/platform/graphqltransportws!5

Author: Austinpayne

README.md

@@ -1,18 +1,136 @@
 # GraphQLTransportWS
 
 This implements the [graphql-transport-ws WebSocket subprotocol](https://github.com/enisdenjo/graphql-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: "[email protected]:PassiveLogic/platform/GraphQLTransportWS.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 GraphQLTransportWS
+
+/// 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 = GraphQLTransportWS.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 = GraphQLTransportWS.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/GraphQLTransportWS/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?
 
@@ -110,7 +110,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/GraphQLTransportWS/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/GraphQLTransportWS/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/GraphQLTransportWS/Requests.swift

@@ -15,24 +15,14 @@ import GraphQL
 /// ```
 
 /// A general request. This object's type is used to triage to other, more specific request objects.
-public struct Request: Equatable, JsonEncodable {
+struct Request: Equatable, JsonEncodable {
     let type: RequestMessageType
 }
 
 /// A websocket `connection_init` request from the client to the server
-public struct ConnectionInitRequest: Equatable, JsonEncodable {
+struct ConnectionInitRequest<InitPayload: Codable & Equatable>: Equatable, JsonEncodable {
     var type = RequestMessageType.connectionInit
-    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 `subscribe` request from the client to the server

Sources/GraphQLTransportWS/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 }
 
@@ -64,7 +66,7 @@ public class Server {
 
             switch request.type {
                 case .connectionInit:
-                    guard let connectionInitRequest = try? self.decoder.decode(ConnectionInitRequest.self, from: data) else {
+                    guard let connectionInitRequest = try? self.decoder.decode(ConnectionInitRequest<InitPayload>.self, from: data) else {
                         self.error(.invalidRequestFormat(messageType: .connectionInit))
                         return
                     }
@@ -89,7 +91,7 @@ public class Server {
 
     /// Define the callback run during `connection_init` resolution that allows authorization using the `payload`.
     /// Throw 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
     }
 
@@ -105,14 +107,14 @@ public class Server {
         self.onMessage = callback
     }
 
-    private func onConnectionInit(_ connectionInitRequest: ConnectionInitRequest) {
+    private func onConnectionInit(_ connectionInitRequest: ConnectionInitRequest<InitPayload>) {
         guard !initialized else {
             self.error(.tooManyInitializations())
             return
         }
 
         do {
-            try self.auth(connectionInitRequest)
+            try self.auth(connectionInitRequest.payload)
         }
         catch {
             self.error(.unauthorized())

Tests/GraphQLTransportWSTests/GraphQLTransportWSTests.swift

@@ -11,20 +11,20 @@ import XCTest
 class GraphqlTransportWSTests: 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 GraphqlTransportWSTests: 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 GraphqlTransportWSTests: 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: ""
             )
         )
@@ -107,7 +107,7 @@ class GraphqlTransportWSTests: XCTestCase {
         var messages = [String]()
         let completeExpectation = XCTestExpectation()
 
-        let client = Client(messenger: clientMessenger)
+        let client = Client<TokenInitPayload>(messenger: clientMessenger)
         client.onConnectionAck { _, client in
             client.sendStart(
                 payload: GraphQLRequest(
@@ -131,7 +131,7 @@ class GraphqlTransportWSTests: XCTestCase {
         }
 
         client.sendConnectionInit(
-            payload: ConnectionInitAuth(
+            payload: TokenInitPayload(
                 authToken: ""
             )
         )
@@ -154,7 +154,7 @@ class GraphqlTransportWSTests: 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(
@@ -191,7 +191,7 @@ class GraphqlTransportWSTests: XCTestCase {
         }
 
         client.sendConnectionInit(
-            payload: ConnectionInitAuth(
+            payload: TokenInitPayload(
                 authToken: ""
             )
         )

Tests/GraphQLTransportWSTests/TestAPI.swift renamed to Tests/GraphQLTransportWSTests/Utils/TestAPI.swift

@@ -10,7 +10,6 @@ import Foundation
 class TestMessenger: Messenger {
     weak var other: TestMessenger?
     var onRecieve: (String) -> Void = { _ in }
-    var onClose: () -> Void = { }
     let queue: DispatchQueue = .init(label: "Test messenger")
 
     init() {}
@@ -30,16 +29,11 @@ class TestMessenger: Messenger {
         self.onRecieve = callback
     }
 
-    func onClose(callback: @escaping () -> Void) {
-        self.onClose = callback
-    }
-    
     func error(_ message: String, code: Int) {
         self.send("\(code): \(message)")
     }
 
     func close() {
         // This is a testing no-op
-        self.onClose()
     }
 }