Skip to content


Repository files navigation

Go Report Card GoDoc build codecov Mentioned in Awesome Go


A WebSocket client and server for GraphQL.

gws implements Apollos' "GraphQL over WebSocket" protocol, which can be found in It provides an RPC-like API for both client and server usage.

Getting Started

gws provides both a client and server implementation for the "GraphQL over Websocket" protocol.


To create a client, you must first dial the server like:

conn, err := gws.Dial(context.TODO(), "ws://")
// Don't forget to handle the error

gws.Dial will return high-level abstraction around the underlying connection. This is very similar to gRPCs' behaviour. After dialing the server, now simply wrap the return conn and begin performing queries, like:

client := gws.NewClient(conn)

resp, err := client.Query(context.TODO(), &gws.Request{Query: "{ hello { world } }"})
// Don't forget to handle the error

var data struct{
  Hello struct{
    World string
err = json.Unmarshal(resp.Data, &data)


The server implementation provided isn't actually a standalone server but instead just a specially configured http.Handler. This is because the underlying protocol is simply WebSocket, which runs on top of HTTP. Creating a bare bones handler is as simple as the following:

msgHandler := func(s *Stream, req *Request) error {
  // Handle request
  return nil

http.ListenAndServe(":8080", gws.NewHandler(gws.HandlerFunc(msgHandler)))