wsgraphql

package
v1.2.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 12, 2022 License: MIT Imports: 17 Imported by: 3

Documentation

Overview

Package wsgraphql provides interfaces for server and client

Index

Constants

View Source
const WebsocketSubprotocol = apollows.WebsocketSubprotocol

WebsocketSubprotocol defines websocket subprotocol expected by this implementation by default

Variables

View Source
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 v1.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 v1.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, origerr 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

	// OnDisconnect is called once per HTTP request, before OnRequestDone, without responsibility to handle errors
	OnDisconnect func(reqctx mutable.Context, origerr error) 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, origerr error) error
}

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

Sequence:
OnRequest -> OnConnect -> [ OnOperation -> OnOperationResult -> OnOperationDone ]* -> OnDisconnect -> OnRequestDone
                          [     may be repeared for subscriptions or be none    ]

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

Directories

Path Synopsis
Package apollows provides implementation of GraphQL over WebSocket Protocol as defined by apollo graphql see https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md for reference
Package apollows provides implementation of GraphQL over WebSocket Protocol as defined by apollo graphql see https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md for reference
compat
gorillaws
Package gorillaws provides compatibility for gorilla websocket upgrader
Package gorillaws provides compatibility for gorilla websocket upgrader
examples
minimal command
simpleserver command
Package mutable provides v1.mutable context, that can store multiple values and be updated after creation
Package mutable provides v1.mutable context, that can store multiple values and be updated after creation

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL