by functionalfoundry

functionalfoundry / graphqlws

Implementation of the GraphQL over WebSocket protocol in Go.

135 Stars 20 Forks Last release: Not found MIT License 59 Commits 0 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Note: We're looking for a new maintainer for

. Please reach out via [email protected] if you're interested.


Implementation of the GraphQL over WebSocket protocol in Go. Brought to you by Functional Foundry.

API Documentation

Build Status Go Report

Getting started

  1. Install dependencies:
    go get
    go get
    go get
    go get
    go get
  2. Clone the repository:
    mkdir -p "$GOPATH/src/"
    cd "$GOPATH/src/"
    git clone
  3. Run the tests:
    cd graphqlws
    go test
  4. Run the example server:
    go run graphqlws/examples/server



package main

import ( "net/http"



func main() { // Create a GraphQL schema schema, err := graphql.NewSchema(...)

// Create a subscription manager
subscriptionManager := graphqlws.NewSubscriptionManager(&schema)

// Create a WebSocket/HTTP handler
graphqlwsHandler := graphqlws.NewHandler(graphqlws.HandlerConfig{
    // Wire up the GraphqL WebSocket handler with the subscription manager
    SubscriptionManager: subscriptionManager,

    // Optional: Add a hook to resolve auth tokens into users that are
    // then stored on the GraphQL WS connections
    Authenticate: func(authToken string) (interface{}, error) {
        // This is just a dumb example
        return "Joe", nil

// The handler integrates seamlessly with existing HTTP servers
http.Handle("/subscriptions", graphqlwsHandler)
http.ListenAndServe(":8080", nil)


Working with subscriptions

// This assumes you have access to the above subscription manager
subscriptions := subscriptionManager.Subscriptions()

for conn, _ := range subscriptions { // Things you have access to here: conn.ID() // The connection ID conn.User() // The user returned from the Authenticate function

for _, subscription := range subscriptions[conn] {
    // Things you have access to here:
    subscription.ID            // The subscription ID (unique per conn)
    subscription.OperationName // The name of the operation
    subscription.Query         // The subscription query/queries string
    subscription.Variables     // The subscription variables
    subscription.Document      // The GraphQL AST for the subscription
    subscription.Fields        // The names of top-level queries
    subscription.Connection    // The GraphQL WS connection

    // Prepare an execution context for running the query
    ctx := context.Context()

    // Re-execute the subscription query
    params := graphql.Params{
        Schema:         schema, // The GraphQL schema
        RequestString:  subscription.Query,
        VariableValues: subscription.Variables,
        OperationName:  subscription.OperationName,
        Context:        ctx,
    result := graphql.Do(params)

    // Send query results back to the subscriber at any point
    data := graphqlws.DataMessagePayload{
        // Data can be anything (interface{})
        Data:   result.Data,
        // Errors is optional ([]error)
        Errors: graphqlws.ErrorsFromGraphQLErrors(result.Errors),



uses logrus for logging. In the future we might remove those logs entirely to leave logging entirely to developers using
. Given the current solution, you can control the logging level of
by setting it through
import (
  log ""




Copyright © 2017-2019 Functional Foundry, LLC.

Licensed under the MIT License.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.