Sign inDemoInstall

Package Overview
File Explorer

Install Socket

Protect your apps from supply chain attacks


Package graphql-go-tools is library to create GraphQL services using the go programming language. 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: 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: Created by Jens Neuse


Version published


# graphql-go-tools

[<p align="center"><img height="auto" src="./assets/logo.png"></p>](

## 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](/examples/federation).

## 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
- 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
    - query execution: takes a context object and executes an 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

## 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):
```shell script
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][jens-neuse-github] (Project Lead & Active Maintainer)
- [Mantas Vidutis][mantas-vidutis-github]
    - Contributions to the http proxy & the Context Middleware
- [Jonas Bergner][jonas-bergner-github]
    - Contributions to the initial version of the parser, contributions to the tests
    - Implemented Type Extension merging [#108](
- [Patric Vormstein][patric-vormstein-github] (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][sergey-petrunin-github] (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][vasyl-github]
    - 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.


Last updated on 12 Oct 2023

Did you know?

Socket installs a GitHub app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc