Adds documentation and scoping

Author: NeedleInAJayStack

README.md

@@ -1,3 +1,9 @@
 # GraphQLWS
 
-A description of this package.
+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.
+
+Features:
+- Server implementation that implements defined protocol conversations
+- Client and Server types that wrap messengers
+- Codable Server and Client message structures

Sources/GraphQLWS/Client.swift

@@ -3,9 +3,8 @@
 import Foundation
 import GraphQL
 
-/// Adds client-side [graphql-ws protocol](https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md)
-/// support, namely parsing and adding callbacks for each type of server respose.
-class Client {
+/// 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 {
     let messenger: Messenger
 
     var onConnectionError: (ConnectionErrorResponse, Client) -> Void = { _, _ in }
@@ -23,7 +22,7 @@ class Client {
     ///
     /// - Parameters:
     ///   - messenger: The messenger to bind the client to.
-    init(
+    public init(
         messenger: Messenger
     ) {
         self.messenger = messenger
@@ -107,48 +106,48 @@ class Client {
 
     /// Define the callback run on receipt of a `connection_error` message
     /// - Parameter callback: The callback to assign
-    func onConnectionError(_ callback: @escaping (ConnectionErrorResponse, Client) -> Void) {
+    public func onConnectionError(_ callback: @escaping (ConnectionErrorResponse, Client) -> Void) {
         self.onConnectionError = callback
     }
 
     /// Define the callback run on receipt of a `connection_ack` message
     /// - Parameter callback: The callback to assign
-    func onConnectionAck(_ callback: @escaping (ConnectionAckResponse, Client) -> Void) {
+    public func onConnectionAck(_ callback: @escaping (ConnectionAckResponse, Client) -> Void) {
         self.onConnectionAck = callback
     }
 
     /// Define the callback run on receipt of a `connection_ka` message
     /// - Parameter callback: The callback to assign
-    func onConnectionKeepAlive(_ callback: @escaping (ConnectionKeepAliveResponse, Client) -> Void) {
+    public func onConnectionKeepAlive(_ callback: @escaping (ConnectionKeepAliveResponse, Client) -> Void) {
         self.onConnectionKeepAlive = callback
     }
 
     /// Define the callback run on receipt of a `data` message
     /// - Parameter callback: The callback to assign
-    func onData(_ callback: @escaping (DataResponse, Client) -> Void) {
+    public func onData(_ callback: @escaping (DataResponse, Client) -> Void) {
         self.onData = callback
     }
 
     /// Define the callback run on receipt of an `error` message
     /// - Parameter callback: The callback to assign
-    func onError(_ callback: @escaping (ErrorResponse, Client) -> Void) {
+    public func onError(_ callback: @escaping (ErrorResponse, Client) -> Void) {
         self.onError = callback
     }
 
     /// Define the callback run on receipt of any message
     /// - Parameter callback: The callback to assign
-    func onComplete(_ callback: @escaping (CompleteResponse, Client) -> Void) {
+    public func onComplete(_ callback: @escaping (CompleteResponse, Client) -> Void) {
         self.onComplete = callback
     }
 
     /// Define the callback run on receipt of a `complete` message
     /// - Parameter callback: The callback to assign
-    func onMessage(_ callback: @escaping (String, Client) -> Void) {
+    public func onMessage(_ callback: @escaping (String, Client) -> Void) {
         self.onMessage = callback
     }
 
     /// Send a `connection_init` request through the messenger
-    func sendConnectionInit(payload: ConnectionInitAuth?) {
+    public func sendConnectionInit(payload: ConnectionInitAuth?) {
         messenger.send(
             ConnectionInitRequest(
                 payload: payload
@@ -157,7 +156,7 @@ class Client {
     }
 
     /// Send a `start` request through the messenger
-    func sendStart(payload: GraphQLRequest, id: String) {
+    public func sendStart(payload: GraphQLRequest, id: String) {
         messenger.send(
             StartRequest(
                 payload: payload,
@@ -167,7 +166,7 @@ class Client {
     }
 
     /// Send a `stop` request through the messenger
-    func sendStop(id: String) {
+    public func sendStop(id: String) {
         messenger.send(
             StopRequest(
                 id: id
@@ -176,7 +175,7 @@ class Client {
     }
 
     /// Send a `connection_terminate` request through the messenger
-    func sendConnectionTerminate() {
+    public func sendConnectionTerminate() {
         messenger.send(
             ConnectionTerminateRequest().toJSON(encoder)
         )

Sources/GraphQLWS/Messenger.swift

@@ -4,7 +4,7 @@ import Foundation
 import NIO
 
 /// Protocol for an object that can send and recieve messages
-protocol Messenger {
+public protocol Messenger {
     func send<S>(_ message: S) -> Void where S: Collection, S.Element == Character
     func onRecieve(callback: @escaping (String) -> Void) -> Void
     func close() -> Void

Sources/GraphQLWS/Requests.swift

@@ -3,8 +3,6 @@
 import Foundation
 import GraphQL
 
-/// Reference for graphql-ws protocol: https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md
-///
 /// We also require that an 'authToken' field is provided in the 'payload' during the connection
 /// init message. For example:
 /// ```
@@ -22,14 +20,15 @@ struct Request: Equatable, JsonEncodable {
 }
 
 /// A websocket `connection_init` request from the client to the server
-struct ConnectionInitRequest: Equatable, JsonEncodable {
+public struct ConnectionInitRequest: Equatable, JsonEncodable {
     var type = RequestMessageType.GQL_CONNECTION_INIT
-    let payload: ConnectionInitAuth?
+    public let payload: ConnectionInitAuth?
 }
 
+// TODO: Make this structure user-defined
 /// Authorization format for a websocket `connection_init` request from the client to the server
-struct ConnectionInitAuth: Equatable, JsonEncodable {
-    let authToken: String
+public struct ConnectionInitAuth: Equatable, JsonEncodable {
+    public let authToken: String
 }
 
 /// A websocket `start` request from the client to the server

Sources/GraphQLWS/Responses.swift

@@ -3,17 +3,15 @@
 import Foundation
 import GraphQL
 
-/// Reference for graphql-ws protocol: https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md
-
 /// A general response. This object's type is used to triage to other, more specific response objects.
-struct Response: Equatable, JsonEncodable {
+public struct Response: Equatable, JsonEncodable {
     let type: ResponseMessageType
 }
 
 /// A websocket `connection_ack` response from the server to the client
-struct ConnectionAckResponse: Equatable, JsonEncodable {
+public struct ConnectionAckResponse: Equatable, JsonEncodable {
     let type: ResponseMessageType
-    let payload: [String: Map]?
+    public let payload: [String: Map]?
 
     init(_ payload: [String: Map]? = nil) {
         self.type = .GQL_CONNECTION_ACK
@@ -22,9 +20,9 @@ struct ConnectionAckResponse: Equatable, JsonEncodable {
 }
 
 /// A websocket `connection_error` response from the server to the client
-struct ConnectionErrorResponse: Equatable, JsonEncodable {
+public struct ConnectionErrorResponse: Equatable, JsonEncodable {
     let type: ResponseMessageType
-    let payload: [String: Map]?
+    public let payload: [String: Map]?
 
     init(_ payload: [String: Map]? = nil) {
         self.type = .GQL_CONNECTION_ERROR
@@ -33,9 +31,9 @@ struct ConnectionErrorResponse: Equatable, JsonEncodable {
 }
 
 /// A websocket `ka` response from the server to the client
-struct ConnectionKeepAliveResponse: Equatable, JsonEncodable {
+public struct ConnectionKeepAliveResponse: Equatable, JsonEncodable {
     let type: ResponseMessageType
-    let payload: [String: Map]?
+    public let payload: [String: Map]?
 
     init(_ payload: [String: Map]? = nil) {
         self.type = .GQL_CONNECTION_KEEP_ALIVE
@@ -44,10 +42,10 @@ struct ConnectionKeepAliveResponse: Equatable, JsonEncodable {
 }
 
 /// A websocket `data` response from the server to the client
-struct DataResponse: Equatable, JsonEncodable {
+public struct DataResponse: Equatable, JsonEncodable {
     let type: ResponseMessageType
-    let payload: GraphQLResult?
-    let id: String
+    public let payload: GraphQLResult?
+    public let id: String
 
     init(_ payload: GraphQLResult? = nil, id: String) {
         self.type = .GQL_DATA
@@ -57,9 +55,9 @@ struct DataResponse: Equatable, JsonEncodable {
 }
 
 /// A websocket `complete` response from the server to the client
-struct CompleteResponse: Equatable, JsonEncodable {
+public struct CompleteResponse: Equatable, JsonEncodable {
     let type: ResponseMessageType
-    let id: String
+    public let id: String
 
     init(_: GraphQLResult? = nil, id: String) {
         self.type = .GQL_COMPLETE
@@ -68,10 +66,10 @@ struct CompleteResponse: Equatable, JsonEncodable {
 }
 
 /// A websocket `error` response from the server to the client
-struct ErrorResponse: Equatable, JsonEncodable {
+public struct ErrorResponse: Equatable, JsonEncodable {
     let type: ResponseMessageType
-    let payload: [GraphQLError]
-    let id: String
+    public let payload: [GraphQLError]
+    public let id: String
 
     init(_ errors: [Error], id: String) {
         let graphQLErrors = errors.map { error -> GraphQLError in

Sources/GraphQLWS/Server.swift

@@ -6,9 +6,8 @@ import GraphQLRxSwift
 import NIO
 import RxSwift
 
-/// Adds server-side [graphql-ws subprotocol](https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md)
-/// support. This handles the majority of query processing according to the procol definition, allowing a few callbacks for customization.
-class Server {
+/// Server implements the server-side portion of the protocol, allowing a few callbacks for customization.
+public class Server {
     let messenger: Messenger
 
     let onExecute: (GraphQLRequest) -> EventLoopFuture<GraphQLResult>
@@ -30,7 +29,7 @@ class Server {
     ///   - messenger: The messenger to bind the server to.
     ///   - onExecute: Callback run during `start` resolution for non-streaming queries. Typically this is `API.execute`.
     ///   - onSubscribe: Callback run during `start` resolution for streaming queries. Typically this is `API.subscribe`.
-    init(
+    public init(
         messenger: Messenger,
         onExecute: @escaping (GraphQLRequest) -> EventLoopFuture<GraphQLResult>,
         onSubscribe: @escaping (GraphQLRequest) -> EventLoopFuture<SubscriptionResult>
@@ -111,19 +110,19 @@ 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
-    func auth(_ callback: @escaping (ConnectionInitRequest) throws -> Void) {
+    public func auth(_ callback: @escaping (ConnectionInitRequest) throws -> Void) {
         self.auth = callback
     }
 
     /// Define the callback run when the communication is shut down, either by the client or server
     /// - Parameter callback: The callback to assign
-    func onExit(_ callback: @escaping () -> Void) {
+    public func onExit(_ callback: @escaping () -> Void) {
         self.onExit = callback
     }
 
     /// Define the callback run on receipt of any message
     /// - Parameter callback: The callback to assign
-    func onMessage(_ callback: @escaping (String) -> Void) {
+    public func onMessage(_ callback: @escaping (String) -> Void) {
         self.onMessage = callback
     }