Initial Save

node_modules/subscriptions-transport-ws/PROTOCOL.md

@@ -0,0 +1,110 @@
+# GraphQL over WebSocket Protocol
+
+## Client-server communication
+
+Each message has a `type` field, which defined in the protocol of this package, as well as associated fields inside `payload` field, depending on the message type, and `id` field so the client can identify each response from the server.
+
+Each WebSocket message is represented in JSON structure, and being stringified before sending it over the network.
+
+This is the structure of each message:
+
+```typescript
+export interface OperationMessage {
+  payload?: any;
+  id?: string;
+  type: string;
+}
+```
+
+### Client -> Server
+
+#### GQL_CONNECTION_INIT
+Client sends this message after plain websocket connection to start the communication with the server
+
+The server will response only with `GQL_CONNECTION_ACK` + `GQL_CONNECTION_KEEP_ALIVE` (if used) or `GQL_CONNECTION_ERROR` to this message.
+
+- `payload: Object` : optional parameters that the client specifies in `connectionParams`
+
+#### GQL_START
+Client sends this message to execute GraphQL operation
+- `id: string` : The id of the GraphQL operation to start
+- `payload: Object`:
+    * `query: string` : GraphQL operation as string or parsed GraphQL document node
+    * `variables?: Object` : Object with GraphQL variables
+    * `operationName?: string` : GraphQL operation name
+    
+#### GQL_STOP
+Client sends this message in order to stop a running GraphQL operation execution (for example: unsubscribe)
+- `id: string` : operation id
+    
+#### GQL_CONNECTION_TERMINATE
+Client sends this message to terminate the connection.    
+    
+### Server -> Client
+
+#### GQL_CONNECTION_ERROR
+The server may responses with this message to the `GQL_CONNECTION_INIT` from client, indicates the server rejected the connection.
+
+It server also respond with this message in case of a parsing errors of the message (which does not disconnect the client, just ignore the message).
+
+- `payload: Object`: the server side error
+
+#### GQL_CONNECTION_ACK
+The server may responses with this message to the `GQL_CONNECTION_INIT` from client, indicates the server accepted the connection.
+May optionally include a payload.
+
+
+#### GQL_DATA
+The server sends this message to transfter the GraphQL execution result from the server to the client, this message is a response for `GQL_START` message.
+
+For each GraphQL operation send with `GQL_START`, the server will respond with at least one `GQL_DATA` message.
+
+- `id: string` : ID of the operation that was successfully set up
+- `payload: Object` : 
+    * `data: any`: Execution result
+    * `errors?: Error[]` : Array of resolvers errors
+
+#### GQL_ERROR
+Server sends this message upon a failing operation, before the GraphQL execution, usually due to GraphQL validation errors (resolver errors are part of `GQL_DATA` message, and will be added as `errors` array)
+- `payload: Error` : payload with the error attributed to the operation failing on the server
+- `id: string` : operation ID of the operation that failed on the server
+
+#### GQL_COMPLETE
+Server sends this message to indicate that a GraphQL operation is done, and no more data will arrive for the specific operation.
+
+- `id: string` : operation ID of the operation that completed
+
+#### GQL_CONNECTION_KEEP_ALIVE
+Server message that should be sent right after each `GQL_CONNECTION_ACK` processed and then periodically to keep the client connection alive.
+
+The client starts to consider the keep alive message only upon the first received keep alive message from the server.
+
+### Messages Flow
+
+This is a demonstration of client-server communication, in order to get a better understanding of the protocol flow:
+
+#### Session Init Phase
+
+The phase initializes the connection between the client and server, and usually will also build the server-side `context` for the execution.
+
+- Client connected immediately, or stops and wait if using lazy mode (until first operation execution)
+- Client sends `GQL_CONNECTION_INIT` message to the server.
+- Server calls `onConnect` callback with the init arguments, waits for init to finish and returns it's return value with `GQL_CONNECTION_ACK` + `GQL_CONNECTION_KEEP_ALIVE` (if used), or `GQL_CONNECTION_ERROR` in case of `false` or thrown exception from `onConnect` callback.
+- Client gets `GQL_CONNECTION_ACK` + `GQL_CONNECTION_KEEP_ALIVE` (if used) and waits for the client's app to create subscriptions.
+
+#### Connected Phase
+
+This phase called per each operation the client request to execute:
+
+- App creates a subscription using `subscribe` or `query` client's API, and the `GQL_START` message sent to the server.
+- Server calls `onOperation` callback, and responds with `GQL_DATA` in case of zero errors, or `GQL_ERROR` if there is a problem with the operation (is might also return `GQL_ERROR` with `errors` array, in case of resolvers errors).
+- Client get `GQL_DATA` and handles it.
+- Server calls `onOperationDone` if the operation is a query or mutation (for subscriptions, this called when unsubscribing)
+- Server sends `GQL_COMPLETE` if the operation is a query or mutation (for subscriptions, this sent when unsubscribing)
+
+For subscriptions:
+- App triggers `PubSub`'s publication method, and the server publishes the event, passing it through the `subscribe` executor to create GraphQL execution result
+- Client receives `GQL_DATA` with the data, and handles it.
+- When client unsubscribe, the server triggers `onOperationDone` and sends `GQL_COMPLETE` message to the client.
+
+When client done with executing GraphQL, it should close the connection and terminate the session using `GQL_CONNECTION_TERMINATE` message.