It is a cached proxy for your GraphQL API with automatic purging.
- Deploy it in front of GraphQL API, and it will start caching all requests passing through it.
- Your cache gets automatically invalidated if anything changes in your application (when you send a
mutation) - Queries are only sent to origin if there is a cache MISS
Because all GraphQL requests are on a single endpoint and resources are differentiated based on what your request body looks like, we can't use HTTP caching methods for them (say goodbye to etags, 304s, etc.)
Currently the ecosystem solves for the problem in two ways, client side cache or a server side cache. Orbit GraphQL is a solution to setting up a server side cache for your GraphQL API.
You can find details on it is implemented here.
To build the project locally, you need to have Go installed on your machine - Installing Go
Once you have the project cloned,
- Run the following command in the project directory to install/download all dependencies
go mod tidy
- Update the configuration in the
config.tomlfile (add your origin URL, the port, etc.) - Run the command below to start the cache server
go run main.go
- That's it! You can start making requests to your cache server.
You can build the executable for the server by running the command below
go build -o orbitgraphql main.go
This will build the binary on your machine.
Please note, the build binary will need the config.toml file in the same directory if you're providing configuration in the file. You can also provide configuration for the server using envionment variables.
First thing you need to do is run the server. You can run it using Docker.
docker build . -t orbitgraphqldocker run -p 9090:9090 -e ORBIT_ORIGIN=http://localhost:8080/graphql orbitgraphqlAll requests to localhost:9090/ will be proxied to localhost:8080/graphql and requests which result in a cache HIT will be served directly.
There are a few integration tests (written by me) and a few unit tests (written by Github Copilot).
To run tests locally you will need to start the test Todo API.
go run test_api/todo/server.go
This will start the test origin server. There is a delay of 100ms added to every request so we can try to pretend like our origin API is slow.
Next up, start the cache server by running
go run main.go
That's it. Once both servers are up and running, run the command below to run the test suite.
go test ./... -v -count=1
You can start sending the same GraphQL requests you were sending to your origin API to the Orbit server on the /graphql path. If the server is running on localhost:9090, you can your requests to localhost:9090/graphql
The system also has few other endpoints to help you flush/purge the cache. You can details about all of them here.
You can configure the origin URL, the port the server runs on, the cache backend to use (currently in memory and redis are supported), and a few more things.
The system takes configuration in two ways,
- The
config.tomlfile in your project directory - Environment variables
The configuration is read from the config.toml file. You can also override the configuration using environment variables.
The details all options available can be found here: Configuration Options. You can also check out the sample config file here: Sample Config File
The code is licensed under FSL-1.1-Apache-2.0.
I built this because of an itch,
I wanted a cache in front of my API -> Went out looking for open source solutions -> Didn't find a great tool for my setup -> Started using Stellate (loved the product! <3) -> Still wanted to solve this problem (for fun)
This project is heavily inspired from,