graphql

README

graphql-go

Status

The project is under heavy development. It is stable enough so we use it in production at Sourcegraph, but expect changes.

Goals

• full support of GraphQL spec (October 2016)
  • propagation of null on resolver errors
  • everything else
• minimal API
• support for context.Context and OpenTracing
• early error detection at application startup by type-checking if the given resolver matches the schema
• resolvers are purely based on method sets (e.g. it's up to you if you want to resolve a GraphQL interface with a Go interface or a Go struct)
• nice error messages (no internal panics, even with an invalid schema or resolver; please file a bug if you see an internal panic)
  • nice errors on resolver validation
  • nice errors on all invalid schemas
  • nice errors on all invalid queries
• panic handling (a panic in a resolver should not take down the whole app)
• parallel execution of resolvers

(Some) Documentation

Resolvers

A resolver must have one method for each field of the GraphQL type it resolves. The method name has to be exported and match the field's name in a non-case-sensitive way.

The method has up to two arguments:

• Optional context.Context argument.
• Mandatory *struct { ... } argument if the corresponding GraphQL field has arguments. The names of the struct fields have to be exported and have to match the names of the GraphQL arguments in a non-case-sensitive way.

The method has up to two results:

• The GraphQL field's value as determined by the resolver.
• Optional error result.

Example for a simple resolver method:

func (r *helloWorldResolver) Hello() string {
	return "Hello world!"
}

The following signature is also allowed:

func (r *helloWorldResolver) Hello(ctx context.Context) (string, error) {
	return "Hello world!", nil
}

Documentation

Index

• type ID
  • func (_ ID) ImplementsGraphQLType(name string) bool
  • func (id ID) MarshalJSON() ([]byte, error)
  • func (id *ID) UnmarshalGraphQL(input interface{}) error
• type Response
• type Schema
  • func MustParseSchema(schemaString string, resolver interface{}, opts ...SchemaOpt) *Schema
  • func ParseSchema(schemaString string, resolver interface{}, opts ...SchemaOpt) (*Schema, error)
  • func (s *Schema) Exec(ctx context.Context, queryString string, operationName string, ...) *Response
  • func (s *Schema) Inspect() *introspection.Schema
  • func (s *Schema) ToJSON() ([]byte, error)
  • func (s *Schema) Validate(queryString string) []*errors.QueryError
• type SchemaOpt
  • func Logger(logger log.Logger) SchemaOpt
  • func MaxParallelism(n int) SchemaOpt
  • func Tracer(tracer trace.Tracer) SchemaOpt
• type Time
  • func (_ Time) ImplementsGraphQLType(name string) bool
  • func (t *Time) UnmarshalGraphQL(input interface{}) error

Types

type ID

type ID string

ID represents GraphQL's "ID" scalar type. A custom type may be used instead.

func (ID) ImplementsGraphQLType

func (_ ID) ImplementsGraphQLType(name string) bool

func (ID) MarshalJSON

func (id ID) MarshalJSON() ([]byte, error)

func (*ID) UnmarshalGraphQL

func (id *ID) UnmarshalGraphQL(input interface{}) error

type Response

type Response struct {
	Data       json.RawMessage        `json:"data,omitempty"`
	Errors     []*errors.QueryError   `json:"errors,omitempty"`
	Extensions map[string]interface{} `json:"extensions,omitempty"`
}

Response represents a typical response of a GraphQL server. It may be encoded to JSON directly or it may be further processed to a custom response type, for example to include custom error data.

type Schema

type Schema struct {
	// contains filtered or unexported fields
}

Schema represents a GraphQL schema with an optional resolver.

func MustParseSchema

func MustParseSchema(schemaString string, resolver interface{}, opts ...SchemaOpt) *Schema

MustParseSchema calls ParseSchema and panics on error.

func ParseSchema

func ParseSchema(schemaString string, resolver interface{}, opts ...SchemaOpt) (*Schema, error)

ParseSchema parses a GraphQL schema and attaches the given root resolver. It returns an error if the Go type signature of the resolvers does not match the schema. If nil is passed as the resolver, then the schema can not be executed, but it may be inspected (e.g. with ToJSON).

func (*Schema) Exec

func (s *Schema) Exec(ctx context.Context, queryString string, operationName string, variables map[string]interface{}) *Response

Exec executes the given query with the schema's resolver. It panics if the schema was created without a resolver. If the context get cancelled, no further resolvers will be called and a the context error will be returned as soon as possible (not immediately).

func (*Schema) Inspect

func (s *Schema) Inspect() *introspection.Schema

Inspect allows inspection of the given schema.

func (*Schema) ToJSON

func (s *Schema) ToJSON() ([]byte, error)

ToJSON encodes the schema in a JSON format used by tools like Relay.

func (*Schema) Validate

func (s *Schema) Validate(queryString string) []*errors.QueryError

Validate validates the given query with the schema.

type SchemaOpt

type SchemaOpt func(*Schema)

SchemaOpt is an option to pass to ParseSchema or MustParseSchema.

func Logger

func Logger(logger log.Logger) SchemaOpt

Logger is used to log panics durring query execution. It defaults to exec.DefaultLogger.

func MaxParallelism

func MaxParallelism(n int) SchemaOpt

MaxParallelism specifies the maximum number of resolvers per request allowed to run in parallel. The default is 10.

func Tracer

func Tracer(tracer trace.Tracer) SchemaOpt

Tracer is used to trace queries and fields. It defaults to trace.OpenTracingTracer.

type Time

type Time struct {
	time.Time
}

Time is a custom GraphQL type to represent an instant in time. It has to be added to a schema via "scalar Time" since it is not a predeclared GraphQL type like "ID".

func (Time) ImplementsGraphQLType

func (_ Time) ImplementsGraphQLType(name string) bool

func (*Time) UnmarshalGraphQL

func (t *Time) UnmarshalGraphQL(input interface{}) error