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
• 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)
• 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
}

OpenTracing

OpenTracing spans are automatically added for each field of the GraphQL query, except those with trivial resolvers that have no context.Context argument, no field arguments and no error result. This is to avoid unnecessary clutter in the trace.

Documentation

Index

• Variables
• func RunTest(t *testing.T, test *Test)
• func RunTests(t *testing.T, tests []*Test)
• func SchemaToJSON(schemaString string) ([]byte, error)
• type ID
• type Response
• type ScalarConfig
• type Schema
  • func MustParseSchema(schemaString string, resolver interface{}) *Schema
  • func ParseSchema(schemaString string, resolver interface{}) (*Schema, error)
  • func (s *Schema) Exec(ctx context.Context, queryString string, operationName string, ...) *Response
• type SchemaBuilder
  • func New() *SchemaBuilder
  • func (b *SchemaBuilder) AddCustomScalar(name string, scalar *ScalarConfig)
  • func (b *SchemaBuilder) ApplyResolver(resolver interface{}) (*Schema, error)
  • func (b *SchemaBuilder) Parse(schemaString string) error
• type Test

Variables

var Time = &ScalarConfig{
	ReflectType: reflect.TypeOf(time.Time{}),
	CoerceInput: func(input interface{}) (interface{}, error) {
		switch input := input.(type) {
		case time.Time:
			return input, nil
		case string:
			t, err := time.Parse(time.RFC3339, input)
			return t, err
		case int:
			return time.Unix(int64(input), 0), nil
		default:
			return nil, fmt.Errorf("wrong type")
		}
	},
}

Functions

func RunTest

func RunTest(t *testing.T, test *Test)

func RunTests

func RunTests(t *testing.T, tests []*Test)

func SchemaToJSON

func SchemaToJSON(schemaString string) ([]byte, error)

Types

type ID

type ID string

type Response

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

type ScalarConfig

type ScalarConfig struct {
	ReflectType reflect.Type
	CoerceInput func(input interface{}) (interface{}, error)
}

type Schema

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

func MustParseSchema

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

func ParseSchema

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

func (*Schema) Exec

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

type SchemaBuilder

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

func New

func New() *SchemaBuilder

func (*SchemaBuilder) AddCustomScalar

func (b *SchemaBuilder) AddCustomScalar(name string, scalar *ScalarConfig)

func (*SchemaBuilder) ApplyResolver

func (b *SchemaBuilder) ApplyResolver(resolver interface{}) (*Schema, error)

func (*SchemaBuilder) Parse

func (b *SchemaBuilder) Parse(schemaString string) error

type Test

type Test struct {
	Schema         *Schema
	Query          string
	OperationName  string
	Variables      map[string]interface{}
	ExpectedResult string
}