Serverless GraphQL registry build with Cloudflare Worker & KV Storage

There should be a single source of truth for registering and tracking the graph.

Features

• Create multiple versions of the graph (for example, staging and production, or different development branches)
• Stores versioned schemas for all GraphQL-federated services
• Serves schema for GraphQL gateway based on provided services & their versions
• Validates new schema to be compatible with other running services
• Everywhere fast, secure and accessible due to Cloudflare infrastructure
• Global distributed, low-latency store for persisted queries with TTL (timestamp and duration).

Read more

Schema federation

GET - /graphs Returns all registered graphs.

GET - /schema/latest?graph_name=my_graph Returns the last registered schema definition of all services.

POST - /schema/push Creates a new graph and schema for a service.

Example Request

{
  "type_defs": "type Query { hello: String }",
  "version": "1",
  "graph_name": "my_graph",
  "service_name": "foo"
}

POST - /schema/compose Returns the last registered schema definition of all services based on passed services & their versions.

Example Request

{
  "graph_name": "my_graph",
  "services": [{ "name": "foo", "version": "1" }] // if versions can't be found it fails
}

PUT - /schema/deactivate Deactivates a schema by id. The schema will no longer be part of any result. You can re-activate it by register again.

Example Request

{
  "graph_name": "my_graph",
  "schemaId": "916348424"
}

Validation

POST - /schema/diff Returns the schema report of all services and the provided new schema.

Example Request

{
  "graph_name": "my_graph",
  "type_defs": "type Query { hello: String }",
  "name": "foo"
}

POST - /schema/validate Validate schema between provided and latest schemas.

Example Request

{
  "graph_name": "my_graph",
  "type_defs": "type Query { hello: String }",
  "name": "foo"
}

Persisted Queries

GET - /persisted_query?key=foo Looks up persisted query from KV Storage.

POST - /persisted_query Adds persisted query to the KV Storage.

Example Request

{
  "key": "apq:foo",
  "query": "query",
  "expiration": 1619269775623, // specific date as unix-timestamp
  "ttl": 600 // 5min
}

DELETE - /persisted_query Deletes persisted query from KV Storage.

Example Request

{
  "key": "foo"
}

Monitoring / Maintanance

POST - /schema/garbage_collect Removes all schemas except the most recent N of every service. Returns the removed schemas. This could be called by a trigger.

Example Request

{
  "num_schemas_keep": 10 // minimum is 10
}

GET - /health healthcheck endpoint.

Authentication

Clients authenticate via Basic-Auth. You have to set the cloudflare secret ALLOWED_CLIENT_SECRETS=secret1,secret2. The secret is used as user and pass combination.

wrangler secret put ALLOWED_CLIENT_SECRETS

Performance & Security

All data is stored in the Key-value Store of cloudflare. Cloudflare KV is eventually-consistent and was designed for high-read low-latency use-cases. All data is encrypted at rest with 256-bit AES-GCM.

Check How KV works to learn more about it.

Development & Deployment

npm run dev

Benchmark

Run a benchmark with:

docker run -e SECRET=<basic_auth_secret> -e URL=<worker_url> -i loadimpact/k6 run - < benchmark/composed-schema.js

Detailed logs

wrangler tail

Credits

• https://github.com/lukeed/worktop - We use it as web framework.
• https://github.com/pipedrive/graphql-schema-registry - Served as great inspiration of a schema registry in Node.js
• Icons made by Kiranshastry from www.flaticon.com