wsgraphql

package
v1.5.1 Latest Latest
Warning

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

Go to latest
Published: Aug 5, 2023 License: MIT Imports: 19 Imported by: 2

Documentation

Overview

Package wsgraphql provides interfaces for server and client

Index

Constants

View Source
const WebsocketSubprotocolGraphqlTransportWS = apollows.WebsocketSubprotocolGraphqlTransportWS

WebsocketSubprotocolGraphqlTransportWS websocket subprotocol expected by graphql-ws implementations

View Source
const WebsocketSubprotocolGraphqlWS = apollows.WebsocketSubprotocolGraphqlWS

WebsocketSubprotocolGraphqlWS websocket subprotocol expected by subscriptions-transport-ws implementations

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{}

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

	// ContextKeyOperationExecuted indicates the operation was executed
	ContextKeyOperationExecuted = contextKeyOperationExecutedT{}

	// ContextKeyOperationID indicates the operation ID
	ContextKeyOperationID = contextKeyOperationIDT{}

	// ContextKeyOperationParams used to store operation params
	ContextKeyOperationParams = contextKeyOperationParamsT{}

	// 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{}

	// ContextKeyHTTPResponseStarted used to indicate HTTP response already has headers sent
	ContextKeyHTTPResponseStarted = contextKeyHTTPResponseStartedT{}

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

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 ContextHTTPResponseStarted added in v1.3.0

func ContextHTTPResponseStarted(ctx context.Context) bool

ContextHTTPResponseStarted returns true if HTTP response has already headers sent

func ContextHTTPResponseWriter

func ContextHTTPResponseWriter(ctx context.Context) http.ResponseWriter

ContextHTTPResponseWriter returns http response writer stored in a context

func ContextOperationExecuted added in v1.5.0

func ContextOperationExecuted(ctx context.Context) bool

ContextOperationExecuted returns true if user requested operation stop

func ContextOperationID added in v1.3.0

func ContextOperationID(ctx context.Context) string

ContextOperationID returns operaion ID stored in the context

func ContextOperationParams added in v1.5.0

func ContextOperationParams(ctx context.Context) (res *graphql.Params)

ContextOperationParams returns operation params stored in the 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 FormatError added in v1.5.0

func FormatError(err error) gqlerrors.FormattedError

FormatError returns error formatted as graphql error

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

	// OnOperationValidation is called after parsing an operation payload with any immediate validation result, if
	// available. AST will be available in context with ContextAST if parsing succeeded.
	OnOperationValidation func(opctx mutable.Context, payload *apollows.PayloadOperation, result *graphql.Result) error

	// OnOperationResult is called after operation result is received, allowing to postprocess it or terminate the
	// operation before returning the result with error. AST is available in context with ContextAST.
	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. AST will be available in context with ContextAST if can be
	// parsed.
	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 -> OnOperationValidation -> OnOperationResult -> OnOperationDone ]* -> OnDisconnect -> OnRequestDone Deprecated: use Interceptors / ResultProcessor

type Conn

type Conn interface {
	ReadJSON(v interface{}) error
	WriteJSON(v interface{}) error
	Close(code int, message string) error
	Subprotocol() string
}

Conn interface is used to abstract connection returned from Upgrader

func ContextWebsocketConnection

func ContextWebsocketConnection(ctx context.Context) Conn

ContextWebsocketConnection returns websocket connection stored in a context

type HandlerHTTPRequest added in v1.5.0

type HandlerHTTPRequest func(ctx context.Context, w http.ResponseWriter, r *http.Request) error

HandlerHTTPRequest handler

type HandlerInit added in v1.5.0

type HandlerInit func(ctx context.Context, init apollows.PayloadInit) error

HandlerInit handler

type HandlerOperation added in v1.5.0

type HandlerOperation func(ctx context.Context, payload *apollows.PayloadOperation) error

HandlerOperation handler

type HandlerOperationExecute added in v1.5.0

type HandlerOperationExecute func(ctx context.Context, payload *apollows.PayloadOperation) (chan *graphql.Result, error)

HandlerOperationExecute handler

type HandlerOperationParse added in v1.5.0

type HandlerOperationParse func(ctx context.Context, payload *apollows.PayloadOperation) error

HandlerOperationParse handler

type InterceptorHTTPRequest added in v1.5.0

type InterceptorHTTPRequest func(
	ctx context.Context,
	w http.ResponseWriter,
	r *http.Request,
	handler HandlerHTTPRequest,
) error

InterceptorHTTPRequest interceptor

func InterceptorHTTPRequestChain added in v1.5.0

func InterceptorHTTPRequestChain(interceptors ...InterceptorHTTPRequest) InterceptorHTTPRequest

InterceptorHTTPRequestChain returns interceptor composed of the provided list

type InterceptorInit added in v1.5.0

type InterceptorInit func(
	ctx context.Context,
	init apollows.PayloadInit,
	handler HandlerInit,
) error

InterceptorInit interceptor

func InterceptorInitChain added in v1.5.0

func InterceptorInitChain(interceptors ...InterceptorInit) InterceptorInit

InterceptorInitChain returns interceptor composed of the provided list

type InterceptorOperation added in v1.5.0

type InterceptorOperation func(
	ctx context.Context,
	payload *apollows.PayloadOperation,
	handler HandlerOperation,
) error

InterceptorOperation interceptor

func InterceptorOperationChain added in v1.5.0

func InterceptorOperationChain(interceptors ...InterceptorOperation) InterceptorOperation

InterceptorOperationChain returns interceptor composed of the provided list

type InterceptorOperationExecute added in v1.5.0

type InterceptorOperationExecute func(
	ctx context.Context,
	payload *apollows.PayloadOperation,
	handler HandlerOperationExecute,
) (chan *graphql.Result, error)

InterceptorOperationExecute interceptor

func InterceptorOperationExecuteChain added in v1.5.0

func InterceptorOperationExecuteChain(interceptors ...InterceptorOperationExecute) InterceptorOperationExecute

InterceptorOperationExecuteChain returns interceptor composed of the provided list

type InterceptorOperationParse added in v1.5.0

type InterceptorOperationParse func(
	ctx context.Context,
	payload *apollows.PayloadOperation,
	handler HandlerOperationParse,
) error

InterceptorOperationParse interceptor

func InterceptorOperationParseChain added in v1.5.0

func InterceptorOperationParseChain(interceptors ...InterceptorOperationParse) InterceptorOperationParse

InterceptorOperationParseChain returns interceptor composed of the provided list

type Interceptors added in v1.5.0

type Interceptors struct {
	HTTPRequest      InterceptorHTTPRequest
	Init             InterceptorInit
	Operation        InterceptorOperation
	OperationParse   InterceptorOperationParse
	OperationExecute InterceptorOperationExecute
}

Interceptors allow to customize request processing Sequence: HTTPRequest -> Init -> [ Operation -> OperationParse -> OperationExecute ]*

type ResultError added in v1.5.0

type ResultError struct {
	*graphql.Result
}

ResultError passes error result as error

func (ResultError) Error added in v1.5.0

func (r ResultError) Error() string

Error implementation

type ResultProcessor added in v1.5.0

type ResultProcessor func(
	ctx context.Context,
	payload *apollows.PayloadOperation,
	result *graphql.Result,
) *graphql.Result

ResultProcessor allows to post-process resolved values

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,
	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 Deprecated: use WithInterceptors / WithResultProcessor

func WithConnectTimeout added in v1.3.0

func WithConnectTimeout(timeout time.Duration) ServerOption

WithConnectTimeout option sets duration within which client is allowed to initialize the connection before being disconnected

func WithExtraInterceptors added in v1.5.0

func WithExtraInterceptors(interceptors Interceptors) ServerOption

WithExtraInterceptors option appends interceptors instead of replacing them

func WithInterceptors added in v1.5.0

func WithInterceptors(interceptors Interceptors) ServerOption

WithInterceptors option sets interceptors around various stages of requests

func WithKeepalive

func WithKeepalive(interval time.Duration) ServerOption

WithKeepalive enabled sending keepalive messages with provided intervals

func WithProtocol added in v1.3.0

func WithProtocol(protocol apollows.Protocol) ServerOption

WithProtocol option sets protocol for this sever to use. May be specified multiple times.

func WithResultProcessor added in v1.5.0

func WithResultProcessor(proc ResultProcessor) ServerOption

WithResultProcessor provides ResultProcessor to post-process resolved values

func WithRootObject added in v1.3.0

func WithRootObject(rootObject map[string]interface{}) ServerOption

WithRootObject provides root object that will be used in root resolvers

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

Directories

Path Synopsis
Package apollows provides implementation of GraphQL over WebSocket Protocol as defined by https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md [GWS] https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md [GTWS]
Package apollows provides implementation of GraphQL over WebSocket Protocol as defined by https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md [GWS] https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md [GTWS]
compat
gorillaws
Package gorillaws provides compatibility for gorilla websocket upgrader
Package gorillaws provides compatibility for gorilla websocket upgrader
otelwsgraphql
Package otelwsgraphql provides opentelemetry instrumentation for wsgraphql
Package otelwsgraphql provides opentelemetry instrumentation for wsgraphql
examples
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