wsgraphql

README

An implementation of apollo graphql websocket protocol for graphql-go.

Inspired by graphqlws

Key features:

• Subscription support
• Callbacks at every stage of communication process for easy customization
• Supports both websockets and plain http queries
• Mutable context allowing to keep request-scoped connection/authentication data and operation-scoped state

Documentation

Overview

Package wsgraphql provides interfaces for server and client

Index

• Constants
• Variables
• func ContextAST(ctx context.Context) *ast.Document
• func ContextHTTPRequest(ctx context.Context) *http.Request
• func ContextHTTPResponseWriter(ctx context.Context) http.ResponseWriter
• func ContextOperationStopped(ctx context.Context) bool
• func ContextSubscription(ctx context.Context) bool
• func OperationContext(ctx context.Context) (mutctx mutable.Context)
• func RequestContext(ctx context.Context) (mutctx mutable.Context)
• func WriteError(ctx context.Context, w http.ResponseWriter, err error)
• type Callbacks
• type Conn
  • func ContextWebsocketConnection(ctx context.Context) Conn
• type Server
  • func NewServer(schema graphql.Schema, rootObject map[string]interface{}, ...) (Server, error)
• type ServerOption
  • func WithCallbacks(callbacks Callbacks) ServerOption
  • func WithKeepalive(interval time.Duration) ServerOption
  • func WithUpgrader(upgrader Upgrader) ServerOption
  • func WithoutHTTPQueries() ServerOption
• type Upgrader

Constants

const WebsocketSubprotocol = apollows.WebsocketSubprotocol

WebsocketSubprotocol defines websocket subprotocol expected by this implementation by default

Variables

var (
	// ContextKeyRequestContext used to store HTTP request-scoped mutable.Context
	ContextKeyRequestContext = contextKeyRequestContextT{}

	// ContextKeyOperationContext used to store graphql operation-scoped mutable.Context
	ContextKeyOperationContext = contextKeyOperationContextT{}

	// ContextKeyAST used to store operation's ast.Document (abstract syntax tree)
	ContextKeyAST = contextKeyAstT{}

	// ContextKeySubscription used to store operation subscription flag
	ContextKeySubscription = contextKeySubscriptionT{}

	// ContextKeyHTTPRequest used to store HTTP request
	ContextKeyHTTPRequest = contextKeyHTTPRequestT{}

	// ContextKeyHTTPResponseWriter used to store HTTP response
	ContextKeyHTTPResponseWriter = contextKeyHTTPResponseWriterT{}

	// ContextKeyWebsocketConnection used to store websocket connection
	ContextKeyWebsocketConnection = contextKeyWebsocketConnectionT{}

	// ContextKeyOperationStopped indicates the operation was stopped on client request
	ContextKeyOperationStopped = contextKeyOperationStoppedT{}
)

Functions

func ContextAST

func ContextAST(ctx context.Context) *ast.Document

ContextAST returns operation's abstract syntax tree document

func ContextHTTPRequest

func ContextHTTPRequest(ctx context.Context) *http.Request

ContextHTTPRequest returns http request stored in a context

func ContextHTTPResponseWriter

func ContextHTTPResponseWriter(ctx context.Context) http.ResponseWriter

ContextHTTPResponseWriter returns http response writer stored in a context

func ContextOperationStopped

func ContextOperationStopped(ctx context.Context) bool

ContextOperationStopped returns true if user requested operation stop

func ContextSubscription

func ContextSubscription(ctx context.Context) bool

ContextSubscription returns operation's subscription flag

func OperationContext

func OperationContext(ctx context.Context) (mutctx mutable.Context)

OperationContext returns graphql operation-scoped mutable context from provided context or nil if none present

func RequestContext

func RequestContext(ctx context.Context) (mutctx mutable.Context)

RequestContext returns HTTP request-scoped mutable context from provided context or nil if none present

func WriteError

func WriteError(ctx context.Context, w http.ResponseWriter, err error)

WriteError helper function writing an error to http.ResponseWriter

Types

type Callbacks

type Callbacks struct {
	// OnRequest called once HTTP request is received, before attempting to do websocket upgrade or plain request
	// execution, consequently before OnConnect as well.
	OnRequest func(reqctx mutable.Context, r *http.Request, w http.ResponseWriter) error

	// OnRequestDone called once HTTP request is finished, regardless of request type, with error occurred during
	// request execution (if any).
	// By default, if error is present, will write error text and return 400 code.
	OnRequestDone func(reqctx mutable.Context, r *http.Request, w http.ResponseWriter, err error)

	// OnConnect is called once per HTTP request, after websocket upgrade and init message received in case of
	// websocket request, or before execution in case of plain request
	OnConnect func(reqctx mutable.Context, init apollows.PayloadInit) error

	// OnOperation is called before each operation with original payload, allowing to modify it or terminate
	// the operation by returning an error
	OnOperation func(opctx mutable.Context, payload *apollows.PayloadOperation) error

	// OnOperationResult is called after operation result is received, allowing to postprocess it or terminate the
	// operation before returning the result with error
	OnOperationResult func(opctx mutable.Context, payload *apollows.PayloadOperation, result *graphql.Result) error

	// OnOperationDone is called once operation is finished, with error occurred during the execution (if any)
	// error returned from this handler will close the websocket / terminate HTTP request with error response.
	// By default, will pass through any error occurred
	OnOperationDone func(opctx mutable.Context, payload *apollows.PayloadOperation, err error) error
}

Callbacks supported by the server use wsgraphql.ContextHTTPRequest / wsgraphql.ContextHTTPResponseWriter to access underlying http.Request and http.ResponseWriter

type Conn

type Conn interface {
	ReadJSON(v interface{}) error
	WriteJSON(v interface{}) error
	Close() error
}

Conn interface is used to abstract connection returned from Upgrader signature based on github.com/gorilla/websocket.Conn, but decouples from specific implementation

func ContextWebsocketConnection

func ContextWebsocketConnection(ctx context.Context) Conn

ContextWebsocketConnection returns websocket connection stored in a context

type Server

type Server interface {
	http.Handler
}

Server implements graphql http handler with websocket support (if upgrader is provided with WithUpgrader)

func NewServer

func NewServer(schema graphql.Schema, rootObject map[string]interface{}, options ...ServerOption) (Server, error)

NewServer returns new Server instance

type ServerOption

type ServerOption func(config *serverConfig) error

ServerOption to configure Server

func WithCallbacks

func WithCallbacks(callbacks Callbacks) ServerOption

WithCallbacks option sets callbacks handling various stages of requests

func WithKeepalive

func WithKeepalive(interval time.Duration) ServerOption

WithKeepalive enabled sending keepalive messages with provided intervals

func WithUpgrader

func WithUpgrader(upgrader Upgrader) ServerOption

WithUpgrader option sets Upgrader (interface in image of gorilla websocket upgrader)

func WithoutHTTPQueries

func WithoutHTTPQueries() ServerOption

WithoutHTTPQueries option prevents HTTP queries from being handled, allowing only websocket queries

type Upgrader

type Upgrader interface {
	Upgrade(w http.ResponseWriter, r *http.Request, responseHeader http.Header) (Conn, error)
}

Upgrader interface used to upgrade HTTP request/response pair into a Conn signature based on github.com/gorilla/websocket.Upgrader, but decouples from specific implementation