README
¶
graphql-go-tools
Sponsors
WunderGraph
Are you looking for a GraphQL e2e data fetching solution? Supports frameworks like NextJS, type safety with generated clients (e.g. TypeScript), authentication, edge caching, realtime streaming support, federation, schema stitching, etc...
Have a look at: https://wundergraph.com
WunderGraph allows you to treat APIs like packages. Install, share & integrate as simple as npm install.
Tyk
Need a full lifecycle Api Management solution with 1st Class GraphQL Support? Go check out https://tyk.io
Tyk is the best in class FLAPIM solution to manage all your APIs. Turn REST APIs into GraphQL using the GUI in no time thanks to tyk's Universal Data Graph.
Apollo Federation Gateway Replacement
This library can be used as a replacement for the Apollo Federation Gateway. It implements the Apollo Federation Specification.
In addition to the scope of other implementations, this one supports Subscriptions!
Check out the Demo.
Overview
This repository implements low level building blocks to write graphql services in Go.
With this library you could build tools like:
- proxies
- caches
- server/client implementations
- a WAF
- be creative! =)
Currently implemented:
- GraphQL AST as of https://graphql.github.io/graphql-spec/June2018
- Token lexing
- AST parsing: parse bytes/string into AST
- AST printing: print an AST to an io.Writer
- supports indentation
- AST validation:
- all rules from the spec implemented
- AST visitor:
- simple visitor: fastest implementation, without field type definition information
- visitor: a bit more overhead but has field type definitions and other quirks
- AST normalization
- remove unnecessary include/skip directives
- field deduplication
- field selection merging
- fragment definition removal
- fragment spread inlining
- inline fragment merging
- remove self aliasing
- type extension merging
- remove type extensions
- Introspection: transforms a graphql schema into a resolvable Data Source
- AST execution
- query planning: turns a Query AST into a cacheable execution plan
- supported DataSources:
- GraphQL (multiple GraphQL services can be combined)
- static (static embedded data)
- REST
- supported DataSources:
- query execution: takes a context object and executes an execution plan
- query planning: turns a Query AST into a cacheable execution plan
- Middleware:
- Operation Complexity: Calculates the complexity of an operation based on the GitHub algorithm
- OperationReport: Makes it easy to collect errors during all phases of a request and enables easy error printing according to the GraphQL spec
- Playground: Easy hosting of GraphQL Playground (no external dependencies, simple middleware)
- Import Statements: combine multiple GraphQL files into one single schema using #import statements
- Implements the Apollo Federation Specification: Replacement for Apollo Federation Gateway
Go version Info
This repos uses go modules so make sure to use the latest version of Go.
Docs
https://godoc.org/github.com/jensneuse/graphql-go-tools
Usage
Look into the docs. Other than that, tests definitely help understanding this library.
Testing
make test
Linting
make lint
Performance
Most hot path operations have 0 allocations. You should expect this library to exceed all alternatives in terms of performance. I've compared my implementation vs. others but why trust my numbers? Feel free to add comparisons via PR.
Benchmarks
Parse Kitchen Sink (1020 chars, example from Facebook):
pkg: github.com/jensneuse/graphql-go-tools/pkg/astparser
BenchmarkKitchenSink 189426 5652 ns/op 0 B/op 0 allocs/op
BenchmarkKitchenSink 198253 5526 ns/op 0 B/op 0 allocs/op
BenchmarkKitchenSink 199924 5553 ns/op 0 B/op 0 allocs/op
BenchmarkKitchenSink 212695 5804 ns/op 0 B/op 0 allocs/op
CPU and Memory consumption for lexing, parsing as well as most other operations is neglectable, even for larger queries.
Contributors
- Jens Neuse (Project Lead & Active Maintainer)
- Mantas Vidutis
- Contributions to the http proxy & the Context Middleware
- Jonas Bergner
- Contributions to the initial version of the parser, contributions to the tests
- Implemented Type Extension merging #108
- Patric Vormstein (Active Maintainer)
- Fixed lexer on windows #92
- Author of the graphql package to simplify the usage of the library
- Refactored the http package to simplify usage with http servers
- Author of the starwars package to enhance testing
- Sergey Petrunin (Active Maintainer)
- Helped cleaning up the API of the pipeline package #166
- Refactored the ast package into multiple files
- Author of the introspection converter (introspection JSON -> AST)
- Fixed various bugs in the parser & visitor & printer
- Refactored and enhanced the astimport package
- Vasyl Domanchuk
- Implemented the logic to generate a federation configuration
- Added federation example
Contributions
Feel free to file an issue in case of bugs. We're open to your ideas to enhance the repository.
You are open to contribute via PR's. Please open an issue to discuss your idea before implementing it so we can have a discussion. Make sure to comply with the linting rules. You must not add untested code.
Documentation
¶
Overview ¶
Package graphql-go-tools is library to create GraphQL services using the go programming language.
About GraphQL ¶
GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.
Source: https://graphql.org
About this library ¶
This library is intended to be a set of low level building blocks to write high performance and secure GraphQL applications. Use cases could range from writing layer seven GraphQL proxies, firewalls, caches etc.. You would usually not use this library to write a GraphQL server yourself but to build tools for the GraphQL ecosystem.
To achieve this goal the library has zero dependencies at its core functionality. It has a full implementation of the GraphQL AST and supports lexing, parsing, validation, normalization, introspection, query planning as well as query execution etc.
With the execution package it's possible to write a fully functional GraphQL server that is capable to mediate between various protocols and formats. In it's current state you can use the following DataSources to resolve fields: - Static data (embed static data into a schema to extend a field in a simple way) - HTTP JSON APIs (combine multiple Restful APIs into one single GraphQL Endpoint, nesting is possible) - GraphQL APIs (you can combine multiple GraphQL APIs into one single GraphQL Endpoint, nesting is possible) - Webassembly/WASM Lambdas (e.g. resolve a field using a Rust lambda)
If you're looking for a ready to use solution that has all this functionality packaged as a Gateway have a look at: https://github.com/jensneuse/graphql-gateway
Created by Jens Neuse
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
chat
Module
|
|
|
federation
Module
|
|
|
internal
|
|
|
pkg/unsafeparser
package unsafeparser is for testing purposes only when error handling is overhead and panics are ok
|
package unsafeparser is for testing purposes only when error handling is overhead and panics are ok |
|
pkg
|
|
|
ast
Package ast defines the GraphQL AST and offers helper methods to interact with the AST, mostly to get the necessary information from the ast.
|
Package ast defines the GraphQL AST and offers helper methods to interact with the AST, mostly to get the necessary information from the ast. |
|
astimport
Package astimport can be used to import Nodes manually into an AST.
|
Package astimport can be used to import Nodes manually into an AST. |
|
astnormalization
Package astnormalization helps to transform parsed GraphQL AST's into a easier to use structure.
|
Package astnormalization helps to transform parsed GraphQL AST's into a easier to use structure. |
|
astparser
Package astparser is used to turn raw GraphQL documents into an AST.
|
Package astparser is used to turn raw GraphQL documents into an AST. |
|
astprinter
Package astprinter takes a GraphQL document and prints it as a String with optional indentation.
|
Package astprinter takes a GraphQL document and prints it as a String with optional indentation. |
|
asttransform
Package asttransform contains a set of helper methods to make recursive ast transformations possible.
|
Package asttransform contains a set of helper methods to make recursive ast transformations possible. |
|
astvalidation
Package astvalidation implements the validation rules specified in the GraphQL specification.
|
Package astvalidation implements the validation rules specified in the GraphQL specification. |
|
astvisitor
Package astvisitor enables efficient and powerful traversal of GraphQL document AST's.
|
Package astvisitor enables efficient and powerful traversal of GraphQL document AST's. |
|
codegen
Package codegen generates code to make using this library easier You can currently use the code generator to generate go structs and Unmarshal methods for Directives and Input Objects type definitions This helps you interact very easily with configuration supplied by Directives which you can easily unmarshal into go structs
|
Package codegen generates code to make using this library easier You can currently use the code generator to generate go structs and Unmarshal methods for Directives and Input Objects type definitions This helps you interact very easily with configuration supplied by Directives which you can easily unmarshal into go structs |
|
escape
Package escape enables efficient JSON escaping on byte slices.
|
Package escape enables efficient JSON escaping on byte slices. |
|
execution
Code generated by graphql-go-tools gen, DO NOT EDIT.
|
Code generated by graphql-go-tools gen, DO NOT EDIT. |
|
graphql/federationtesting/accounts/graph
This file will not be regenerated automatically.
|
This file will not be regenerated automatically. |
|
graphql/federationtesting/gateway/http
Package http handles GraphQL HTTP Requests including WebSocket Upgrades.
|
Package http handles GraphQL HTTP Requests including WebSocket Upgrades. |
|
graphql/federationtesting/products/graph
This file will not be regenerated automatically.
|
This file will not be regenerated automatically. |
|
graphql/federationtesting/reviews/graph
This file will not be regenerated automatically.
|
This file will not be regenerated automatically. |
|
http
Package http handles GraphQL HTTP Requests including WebSocket Upgrades.
|
Package http handles GraphQL HTTP Requests including WebSocket Upgrades. |
|
imports
Package imports helps combining multiple GraphQL documents into one document using import comments.
|
Package imports helps combining multiple GraphQL documents into one document using import comments. |
|
introspection
Package introspection takes a GraphQL Schema and provides the introspection JSON to fulfill introspection queries.
|
Package introspection takes a GraphQL Schema and provides the introspection JSON to fulfill introspection queries. |
|
lexer
Package lexer contains the logic to turn an ast.Input into lexed tokens
|
Package lexer contains the logic to turn an ast.Input into lexed tokens |
|
lexer/identkeyword
Package identkeyword contains all possible keywords for GraphQL identifiers
|
Package identkeyword contains all possible keywords for GraphQL identifiers |
|
lexer/keyword
Package keyword contains all possible GraphQL keywords
|
Package keyword contains all possible GraphQL keywords |
|
lexer/literal
Package literal contains a selection of frequently used literals with GraphQL APIs
|
Package literal contains a selection of frequently used literals with GraphQL APIs |
|
lexer/position
Package position contains the objects and logic to properly describe the position of a token in a GraphQL document
|
Package position contains the objects and logic to properly describe the position of a token in a GraphQL document |
|
lexer/runes
Package runes contains all possible 'special' runes in a GraphQL document
|
Package runes contains all possible 'special' runes in a GraphQL document |
|
lexer/token
Package token contains the object and logic needed to describe a lexed token in a GraphQL document
|
Package token contains the object and logic needed to describe a lexed token in a GraphQL document |
|
middleware
Package middleware contains useful middleware components for GraphQL services, e.g.
|
Package middleware contains useful middleware components for GraphQL services, e.g. |
|
middleware/operation_complexity
package operation_complexity implements two common algorithms used by GitHub to calculate GraphQL query complexity 1.
|
package operation_complexity implements two common algorithms used by GitHub to calculate GraphQL query complexity 1. |
|
operationreport
Package operationreport helps generating the errors object for a GraphQL Operation.
|
Package operationreport helps generating the errors object for a GraphQL Operation. |
|
playground
Package playground is a http.Handler hosting the GraphQL Playground application.
|
Package playground is a http.Handler hosting the GraphQL Playground application. |
|
repair
Package repair helps fixing problems in GraphQL documents
|
Package repair helps fixing problems in GraphQL documents |