PROTOCOL.md

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:

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.