graphql

README

GraphQL

Suggested Reading

• Introduction to GraphQL
• GraphQL IDL
• GraphQL Mutations

Covert from Protocol Buffer

In the case where you have a protocol buffer and want to create a GraphQL type to expose the data to our users you can take a short cut. The script proto2graphql.go found in the scripts folder will make a basic conversion of the file.

go run scripts/proto2graphql/proto2graphql.go ./types/user.proto ./backend/apid/graphql/schema

It's important to note that the script is only meant to be run once for each protocol buffer; if run multiple times it will overwrite any changes that were made to the target file.

Basic Usage

1. Add new type / field definition(s).

   # ./backend/apid/graphql/schema/dog.graphql
   
   """
   A Dog are the best pets.
   """
   type Dog implements Named {
     name: String!
     profilePicture(size: Size): String
     friends: [Pet]!
   }
   
   interface Named {
     name: String!
   }
   
   type Rabbit implements Named {
     name: String!
     friends: [Pet]!
     isFluffy: Boolean!
   }
   
   input Size {
     width: Int
     height: Int
     density: float
   }
   
   union Pet = Dog | Rabbit
   

2. Next you'll want to generate the Go code for these new types. To do this we use the gengraphql script.

   From the project root, run:

   go run ./scripts/gengraphql/gengraphql.go ./backend/apid/graphql/schema
   

3. Next we need to tell our service how the types themselves are implemented. To give an example, when a user selects a dog's friends, the service needs to know how to retrieve those details so that it can be display them to the user.

   An example implementation:

   // backend/apid/graphql/dog.go
   
   type dogFieldResolvers struct {
     // the autogenerated "aliases" use reflection under the hood to implement most
     // most the field resolvers; this allows us to write a bit less code with a
     // small runtime cost.
     *schema.DogAliases
   
     controller FriendsController
     logger     logrus.Entry
   }
   
   // Use controller to retrieve our dog's friends.
   func (fr *dogFieldResolvers) Friends(p graphql.ResolveParams) (interface{}, error) {
     dog := p.Source.(*types.Dog)
     ctx := p.Context
     friends, err := fr.controller.ListFriendos(ctx, dog)
     return friends, err
   }
   
   // IsTypeOf is used to determine if a given value is associated with the Dog type
   func (fr *dogFieldResolvers) IsTypeOf(s interface{}, p graphql.IsTypeOfParams) bool {
     _, ok := s.(*types.Dog)
     return ok
   }
   

4. Finally we need to register the new type(s) and any of the implementation details with our service.

   // backend/apid/graphql/service.go
   
   fund NewService(c Config) *Service {
     // ...
     dogImpl := dogFieldResolvers{controller: ..., logger: ...}
     // ...
   
     // ...
     schema.RegisterDog(svc, dogImpl) // include fieldresolvers.
     schema.RegisterSize(svc)         // unlike object type's inputs do not require any additonal implemtation details.
     // ...
   
     // configures registered types and implementations so that service is ready to
     // accept queries.
     service.Reconfigure()
     return service
   }
   

Mutations

Mutations are how the client modifies the server-side data.

• Reference

• Sensu follow's Relay's mutation conventions. Each mutation should consist of three elements. An input object type that describes the parameters to the mutation, an object type that describes the return values, and finally a field on the Mutation to be used as the entry point.

  # mutations.graphql
  type Mutation {
    # ...
    addRole(inputs: AddRoleInput) AddRolePayload
    # ...
  }
  
  input AddRoleInput {
    # Used by a client to keep track of in-flight mutations
    clientMutationId: String!
    userId: ID!
    roleId: ID!
  }
  
  type AddRolePayload {
    clientMutationId: String!
    user: User!
    role: Role!
  }
  

Deprecation

• Fields should not be removed until we can be confident that no clients are using the field.

• GraphQL supports @deprecated directive for marking a field as deprecated.

  type MyType {
    one: String! @deprecated
    two: String! @deprecated(reason: "Two is bad number.")
    three: String!
  }
  

File Conventions

• Type Definitions live in the schema package, and use the file extension .graphql.
  • When the type(s) they match an internal type defined in the types package the filenames should ideally match. (Eg. entity.go entity.graphql.)
  • Ideally all types and fields are
• FieldResolvers live in the graphql package.
  • Filenames should match the same name of the graphql file it is implementing.

Documentation

Index

• Variables
• func CheckFilters() map[string]filter.Filter
• func DefaultGlobalFilters() map[string]filter.Filter
• func DefaultSuggestSchema() suggest.Register
• func EntityFilters() map[string]filter.Filter
• func EventFilters() map[string]filter.Filter
• func HandlerFilters() map[string]filter.Filter
• func SilenceFilters() map[string]filter.Filter
• type ClientFactory
• type Commandable
• type InitHook
• type KVPairString
• type Service
  • func NewService(cfg ServiceConfig) (*Service, error)
  • func (svc *Service) Do(ctx context.Context, q string, vars map[string]interface{}) *gql.Result
• type ServiceConfig
• type Subscribable
• type Timeoutable

Variables

var GlobalFilters = DefaultGlobalFilters()

GlobalFilters are filters that are applied to all resolvers that accept filter statements.

var InitHooks = []InitHook{}

InitHooks allow consumers to hook into the initialization of the service and mutate the schema. Useful for product variants.

var (
	SuggestSchema = DefaultSuggestSchema()
)

Functions

func CheckFilters

func CheckFilters() map[string]filter.Filter

CheckFilters returns collection of filters used for matching resources.

func DefaultGlobalFilters

func DefaultGlobalFilters() map[string]filter.Filter

DefaultGlobalFilters returns the default set of global filters.

func DefaultSuggestSchema

func DefaultSuggestSchema() suggest.Register

func EntityFilters

func EntityFilters() map[string]filter.Filter

EntityFilters returns collection of filters used for matching resources.

func EventFilters

func EventFilters() map[string]filter.Filter

EventFilters returns collection of filters used for matching resources.

func HandlerFilters

func HandlerFilters() map[string]filter.Filter

HandlerFilters returns collection of filters used for matching resources.

func SilenceFilters

func SilenceFilters() map[string]filter.Filter

SilenceFilters returns collection of filters used for matching resources.

Types

type ClientFactory

type ClientFactory interface {
	NewWithContext(ctx context.Context) client.APIClient
}

ClientFactory instantiates new instances of the REST API client

type Commandable

type Commandable interface {
	GetCommand() string
}

type InitHook

type InitHook func(*graphql.Service, ServiceConfig)

type KVPairString

type KVPairString struct {
	Key string
	Val string
}

KVPairString pair of values&

type Service

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

Service describes the Sensu GraphQL service capable of handling queries.

func NewService

func NewService(cfg ServiceConfig) (*Service, error)

NewService instantiates new GraphQL service

func (*Service) Do

func (svc *Service) Do(
	ctx context.Context,
	q string,
	vars map[string]interface{},
) *gql.Result

Do executes given query string and variables

type ServiceConfig

type ServiceConfig struct {
	ClientFactory ClientFactory
}

ServiceConfig describes values required to instantiate service.

type Subscribable

type Subscribable interface {
	GetSubscriptions() []string
}

type Timeoutable

type Timeoutable interface {
	GetTimeout() uint32
}