graphql

README

graphql-go

The goal of this project is to provide full support of the GraphQL draft specification with a set of idiomatic, easy to use Go packages.

While still under heavy development (internal APIs are almost certainly subject to change), this library is safe for production use.

Features

• minimal API
• support for context.Context
• support for the OpenTracing standard
• schema type-checking against resolvers
• resolvers are matched to the schema based on method sets (can resolve a GraphQL schema with a Go interface or Go struct).
• handles panics in resolvers
• parallel execution of resolvers
• subscriptions
  • sample WS transport

Roadmap

We're trying out the GitHub Project feature to manage graphql-go's development roadmap. Feedback is welcome and appreciated.

(Some) Documentation

Basic Sample

package main

import (
        "log"
        "net/http"

        graphql "github.com/JoinCAD/graphql-go"
        "github.com/JoinCAD/graphql-go/relay"
)

type query struct{}

func (_ *query) Hello() string { return "Hello, world!" }

func main() {
        s := `
                type Query {
                        hello: String!
                }
        `
        schema := graphql.MustParseSchema(s, &query{})
        http.Handle("/query", &relay.Handler{Schema: schema})
        log.Fatal(http.ListenAndServe(":8080", nil))
}

To test:

$ curl -XPOST -d '{"query": "{ hello }"}' localhost:8080/query

Resolvers

A resolver must have one method or field for each field of the GraphQL type it resolves. The method or field name has to be exported and match the schema's field's name in a non-case-sensitive way. You can use struct fields as resolvers by using SchemaOpt: UseFieldResolvers(). For example,

opts := []graphql.SchemaOpt{graphql.UseFieldResolvers()}
schema := graphql.MustParseSchema(s, &query{}, opts...)

When using UseFieldResolvers schema option, a struct field will be used only when:

• there is no method for a struct field
• a struct field does not implement an interface method
• a struct field does not have arguments

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
}

Custom Errors

Errors returned by resolvers can include custom extensions by implementing the ResolverError interface:

type ResolverError interface {
	error
	Extensions() map[string]interface{}
}

Example of a simple custom error:

type droidNotFoundError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

func (e droidNotFoundError) Error() string {
	return fmt.Sprintf("error [%s]: %s", e.Code, e.Message)
}

func (e droidNotFoundError) Extensions() map[string]interface{} {
	return map[string]interface{}{
		"code":    e.Code,
		"message": e.Message,
	}
}

Which could produce a GraphQL error such as:

{
  "errors": [
    {
      "message": "error [NotFound]: This is not the droid you are looking for",
      "path": [
        "droid"
      ],
      "extensions": {
        "code": "NotFound",
        "message": "This is not the droid you are looking for"
      }
    }
  ],
  "data": null
}

Community Examples

tonyghita/graphql-go-example - A more "productionized" version of the Star Wars API example given in this repository.

deltaskelta/graphql-go-pets-example - graphql-go resolving against a sqlite database.

OscarYuen/go-graphql-starter - A starter application integrated with dataloader, psql and basic authentication.

zaydek/graphql-go-walkthrough - A beginner friendly walkthrough for prospective developers.

Documentation

Index

• type ID
  • func (ID) ImplementsGraphQLType(name string) bool
  • func (id ID) MarshalJSON() ([]byte, error)
  • func (id *ID) UnmarshalGraphQL(input interface{}) error
• type LoggedField
• type LoggedOperation
• 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) Subscribe(ctx context.Context, queryString string, operationName string, ...) (<-chan interface{}, error)
  • func (s *Schema) ToJSON() ([]byte, error)
  • func (s *Schema) Validate(queryString string) []*errors.QueryError
  • func (s *Schema) ValidateAndLog(queryString string, variables map[string]interface{}) ([]*errors.QueryError, []LoggedOperation)
• type SchemaOpt
  • func DisableIntrospection() SchemaOpt
  • func Logger(logger log.Logger) SchemaOpt
  • func MaxDepth(n int) SchemaOpt
  • func MaxParallelism(n int) SchemaOpt
  • func Tracer(tracer trace.Tracer) SchemaOpt
  • func UseFieldResolvers() SchemaOpt
  • func UseStringDescriptions() SchemaOpt
  • func ValidationTracer(tracer trace.ValidationTracer) SchemaOpt
• type Time
  • func (Time) ImplementsGraphQLType(name string) bool
  • func (t Time) MarshalJSON() ([]byte, error)
  • 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 LoggedField

type LoggedField struct {
	Name      string
	Arguments map[string]string `json:",omitempty"`
}

LoggedField represents a summary of a field.

type LoggedOperation

type LoggedOperation struct {
	Name      string `json:",omitempty"`
	Type      query.OperationType
	Variables map[string]string `json:",omitempty"`
	Fields    []LoggedField     `json:",omitempty"`
}

LoggedOperation represents a summary of an operation suitable for concise telemetry, for example in a web server context.

type Response

type Response struct {
	Errors     []*errors.QueryError   `json:"errors,omitempty"`
	Data       json.RawMessage        `json:"data,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. Errors are intentionally serialized first based on the advice in https://github.com/facebook/graphql/commit/7b40390d48680b15cb93e02d46ac5eb249689876#diff-757cea6edf0288677a9eea4cfc801d87R107

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) Subscribe

func (s *Schema) Subscribe(ctx context.Context, queryString string, operationName string, variables map[string]interface{}) (<-chan interface{}, error)

Subscribe returns a response channel for the given subscription with the schema's resolver. It returns an error if the schema was created without a resolver. If the context gets cancelled, the response channel will be closed and no further resolvers will be called. The context error will be returned as soon as possible (not immediately).

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.

func (*Schema) ValidateAndLog

func (s *Schema) ValidateAndLog(queryString string, variables map[string]interface{}) ([]*errors.QueryError, []LoggedOperation)

ValidateAndLog validates the query and simultaneously produces a loggable summary of the operations it contains.

type SchemaOpt

type SchemaOpt func(*Schema)

SchemaOpt is an option to pass to ParseSchema or MustParseSchema.

func DisableIntrospection

func DisableIntrospection() SchemaOpt

DisableIntrospection disables introspection queries.

func Logger

func Logger(logger log.Logger) SchemaOpt

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

func MaxDepth

func MaxDepth(n int) SchemaOpt

MaxDepth specifies the maximum field nesting depth in a query. The default is 0 which disables max depth checking.

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.

func UseFieldResolvers

func UseFieldResolvers() SchemaOpt

UseFieldResolvers specifies whether to use struct field resolvers

func UseStringDescriptions

func UseStringDescriptions() SchemaOpt

UseStringDescriptions enables the usage of double quoted and triple quoted strings as descriptions as per the June 2018 spec https://facebook.github.io/graphql/June2018/. When this is not enabled, comments are parsed as descriptions instead.

func ValidationTracer

func ValidationTracer(tracer trace.ValidationTracer) SchemaOpt

ValidationTracer is used to trace validation errors. It defaults to trace.NoopValidationTracer.

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

ImplementsGraphQLType maps this custom Go type to the graphql scalar type in the schema.

func (Time) MarshalJSON

func (t Time) MarshalJSON() ([]byte, error)

MarshalJSON is a custom marshaler for Time

This function will be called whenever you query for fields that use the Time type

func (*Time) UnmarshalGraphQL

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

UnmarshalGraphQL is a custom unmarshaler for Time

This function will be called whenever you use the time scalar as an input