pebbles

README

buildbuildio/pebbles

pebbles is a GraphQL federation gateway.

How it works

It binds different GraphQL services via Relay Global Object Identification. This means that any global object must have unique id. For example, Human object may have id human_1, and Animal object -- animal_1, so when resolving Node interface in each service you could know by only id what object client is querying. In order to bind two types which spreads across multiple services, they must implement Node interface, ie

# Service A
interface Node {
	id: ID!
}

type Human implements Node {
	id: ID!
	name: String!
}

type Query {
	node(id: ID!): Node
	getHumans: [Human!]!
}

type Mutation {
	saveHuman(name: String!): Human!
}

# Service B
interface Node {
	id: ID!
}

type Human implements Node {
	id: ID!
	phone: String!
}

type Animal {
	name: String!
	owner: Human!
}

type Query {
	node(id: ID!): Node
	getAnimals: [Animal!]!
}

type Subscription {
	animalAdded: Animal!
}

# Pebbles resulting Schema
interface Node {
	id: ID!
}

type Human implements Node {
	id: ID!
	name: String!
	phone: String!
}

type Animal {
	name: String!
	owner: Human!
}

type Query {
	node(id: ID!): Node
	getHumans: [Human!]!
	getAnimals: [Animal!]!
}

type Mutation {
	saveHuman(name: String!): Human!
}

type Subscription {
	animalAdded: Animal!
}

Why use pebbles?

Our main goals are simple:

1. Work with every valid schema, even with most complicated ones;
2. Provide extendable schemas -- extend types, interfaces, directives and etc without unnecessary duplication;
3. Support for Subscription queries (experimental);
4. Customize as you grow -- all our building blocks are interfaces, so you can write your own.

Example

package main

import (
	"fmt"
	"net/http"

	"github.com/buildbuildio/pebbles"
)

func main() {
	urls := []string{
		"http://localhost:3000",
	}

	gw, err := pebbles.NewGateway(
		urls,
		pebbles.WithDefaultPlayground(),
	)
	if err != nil {
		panic(err)
	}

	sm := http.NewServeMux()

	sm.HandleFunc("/graphql", gw.Handler)

	server := http.Server{
		Addr:    fmt.Sprintf("0.0.0.0:%d", 8000),
		Handler: sm,
	}

	fmt.Println("Starting server...")
	if err = server.ListenAndServe(); err != nil {
		panic(err)
	}
}

Special thanks

Thanks to nautilus/gateway and movio/bramble for inspiration to write this project. Check them, they're both great in their own way ;)

Documentation

Index

• type Gateway
  • func NewGateway(urls []string, options ...GatewayOption) (*Gateway, error)
  • func (g *Gateway) Handler(w http.ResponseWriter, r *http.Request)
• type GatewayOption
  • func WithDefaultPlayground() GatewayOption
  • func WithExecutor(e executor.Executor) GatewayOption
  • func WithGetParentTypeFromIDFunc(fn executor.GetParentTypeFromIDFunc) GatewayOption
  • func WithMerger(m merger.Merger) GatewayOption
  • func WithPlanner(p planner.Planner) GatewayOption
  • func WithPlaygroundProvider(pp playground.PlaygroundProvider) GatewayOption
  • func WithQueryerFactory(f QueryerFactory) GatewayOption
  • func WithRemoteSchemaIntrospector(i introspection.RemoteSchemaIntrospector) GatewayOption
• type QueryerFactory
• type Result
• type Results
  • func (rs Results) Emit(w http.ResponseWriter, isBatch bool)

Types

type Gateway

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

func NewGateway

func NewGateway(urls []string, options ...GatewayOption) (*Gateway, error)

func (*Gateway) Handler

func (g *Gateway) Handler(w http.ResponseWriter, r *http.Request)

type GatewayOption

type GatewayOption func(*Gateway)

func WithDefaultPlayground

func WithDefaultPlayground() GatewayOption

func WithExecutor

func WithExecutor(e executor.Executor) GatewayOption

func WithGetParentTypeFromIDFunc

func WithGetParentTypeFromIDFunc(fn executor.GetParentTypeFromIDFunc) GatewayOption

func WithMerger

func WithMerger(m merger.Merger) GatewayOption

func WithPlanner

func WithPlanner(p planner.Planner) GatewayOption

func WithPlaygroundProvider

func WithPlaygroundProvider(pp playground.PlaygroundProvider) GatewayOption

func WithQueryerFactory

func WithQueryerFactory(f QueryerFactory) GatewayOption

func WithRemoteSchemaIntrospector

func WithRemoteSchemaIntrospector(i introspection.RemoteSchemaIntrospector) GatewayOption

type QueryerFactory

type QueryerFactory func(*planner.PlanningContext, string) queryer.Queryer

type Result

type Result struct {
	Errors gqlerrors.ErrorList    `json:"errors,omitempty"`
	Data   map[string]interface{} `json:"data"`
	// contains filtered or unexported fields
}

type Results

type Results []*Result

func (Results) Emit

func (rs Results) Emit(w http.ResponseWriter, isBatch bool)