starptech/graphql-registry

GraphQL registry - single source of truth for registering and tracking your graph.

---

Note: Are you looking for a Complete API Management for GraphQL Federation? 🔎 Have a look at: WunderGraph Cosmo Includes Schema Registry, analytics, metrics, tracing, and routing. Available for 100% on-prem deployment or as a Managed Service. Apache 2.0 licensed, ensuring no vendor lock-in 🪄

---

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

Features

• Create multiple graphs (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
• Serves a supergraph schema for the GraphQL gateway
• Validates new schema to be compatible with other running services
• Validates that all client operations are supported by your schema
• Calculates a schema coverage report from GraphQL operations
• Validates if a schema update produce a breaking, dangerous or safe change
• Lightweight authorization concept based on JWT.

Read more

Examples

• Federation with Mercurius.
• Federation with Apollo Gateway.
• Managed Federation with Apollo Gateway.

API

Try all endpoints in insomnia or read the api documentation.

Development

Copy .env.example to .env

# Install project
npm install
# Start postgres
docker-compose up postgres
# Create db schema
npm run migrate:up
# Watch mode
npm run dev
# Run tests
npm run test

Benchmark

Run a benchmark with:

docker-compose up postgres
docker-compose up --build app
docker-compose run k6 run /benchmark/composed-schema.js

Our benchmark suite is running in the CI.

Deployment

GraphQL-Registry uses by default postgres as database.

# Bootstrap database
npm install && npm run migrate:up
# Run service
docker run -e DATABASE_URL="" starptech/graphql-registry:latest -p 3000:3000

Available environment variables.

Alpha version

GraphQL Registry is currently highly under development. It means that we are still working on essential features like production-ready schema management, graph metrics and development tooling. GraphQL Registry can be evaluated anytime. Every feature is covered by integration tests. We rely on your feedback and sponsorship. Feel free to open an issue or feature request!

Contributing

❤️ contributions!

I will happily accept your pull request if it:

• has tests
• looks reasonable
• follows the code of conduct

License

GraphQL Registry is open-source under the GNU Affero General Public License Version 3 (AGPLv3) or any later version. You can find it here. Why AGPLv3 and not MIT? Read the blog post from plausible to learn more about our motivations.

graphql-registry's Issues

Track deprecated fields

How many fields are deprecated? By whom?

Implement graphs

https://www.apollographql.com/docs/studio/org/graphs

CLI

Describe the problem/challenge you have

As an organization, I'd like to provide teams the possibility to work with the registry in DX friendly way.
This experience should be similar to https://www.apollographql.com/docs/rover/

• Validate schema updates
• Validate client operations
• Publish your graph's schema to the registry
• Compose a federated supergraph schema from multiple subgraphs
• Fetch schemas

---

Vote on this request

This is an invitation to the community to vote on issues, to help us prioritize our backlog. Use the "smiley face" up to the right of this comment to vote.

👍 "I would like to see this addressed as soon as possible"
👎 "There are other more important things to focus on right now"

We are also happy to receive and review Pull Requests if you want to help working on this issue.

Track client graphl documents for analytical purposes

Describe the problem/challenge you have

As an organization, I'd like to run analyzes on the graphql operations in conjunction with the current schema. This is especially useful when all clients are controlled by the same organization.

• How does the schema coverage look like of my unified schema across all deployed clients?
• When can a field be removed from the schema? (Assumes that we know which clients are deployed)
• Which fragments, directives, mutations, variables are used?
• Is an operation name used?
• What's the average query complexity?
• How many clients/teams consume the api?

Goal: These metrics can be provided without adding runtime complexity to the gateway.

What it can't handle

• GraphQL documents that are built dynamically.
• Make statements about schema usage at runtime.

---

Vote on this request

This is an invitation to the community to vote on issues, to help us prioritize our backlog. Use the "smiley face" up to the right of this comment to vote.

👍 "I would like to see this addressed as soon as possible"
👎 "There are other more important things to focus on right now"

We are also happy to receive and review Pull Requests if you want to help working on this issue.

Publish graphql-registry as a npm package

Hello guys.

Describe the problem/challenge you have
The graphql-registry uses the listen function to start the server what forces the user to deploy as a docker container or a traditional server. With that way, it's not possible to extends the graphql-registry with plugins, custom logic, or use in a serverless environment (which is my case) .

Describe the solution you'd like
Publish this repository as a npm package too.

The graphql-registry could be exported as a fastify middleware. With that, will be possible to extends the logic and use in another kind of environment like aws lambda, google cloud functions, azure functions or other else. Let the user decide the deployment type.

Anything else you would like to add:
I'm available to make a pull request for this feature, I will only need help to publish the package.

---

Vote on this request

This is an invitation to the community to vote on issues, to help us prioritize our backlog. Use the "smiley face" up to the right of this comment to vote.

👍 "I would like to see this addressed as soon as possible"
👎 "There are other more important things to focus on right now"

We are also happy to receive and review Pull Requests if you want to help working on this issue.

Implement GraphQL federation service-discovery

We need to track all registered GraphQL services to provide a list for the GraphQL Gateway.
This endpoint should deliver all available clients. This avoids that the gateway must be kept in sync manually.

More: https://www.apollographql.com/docs/federation/managed-federation/setup/#3-modify-the-gateway-if-necessary, https://www.apollographql.com/docs/studio/schema/schema-reporting/

Client Registry

Register clients routingUrl when pushing a schema. This URL is used for the service-discovery mechanisms. The routingUrl points to the graphql server of the client.

Try Cloudflare Cronjobs to clean KV Storage

https://developers.cloudflare.com/workers/runtime-apis/scheduled-event

Use cases:

• Calculate count of versions per service
• Clean old versions StarpTech/graphql-registry-MOVE#4

Web interface

Describe the problem/challenge you have
First of all, the project is great. Thank you for your work.
My question, do you have any plans to implement web interface?

---

Vote on this request

This is an invitation to the community to vote on issues, to help us prioritize our backlog. Use the "smiley face" up to the right of this comment to vote.

👍 "I would like to see this addressed as soon as possible"
👎 "There are other more important things to focus on right now"

We are also happy to receive and review Pull Requests if you want to help working on this issue.

Keep graphql metadata like directives

graphql/graphql-js#869

Evaluate graphql-tools

https://github.com/ardatan/graphql-tools

Can't seem to reference another federated graph

Hi, I'm trying out the service as the registry for an Apollo federation.

I need to register 2 schemas:

type Query {
  types: [Type]
  type(id: ID): Type
  reasons: [Reason]
  reason(id: ID): Reason
}

type Reason @key(fields: "id") {
  id: ID!
  description: String
}

type Type {
  id: ID!
  description: String
  caseReasonList: [Reason]
}

and

type GuidedHelpConfig {
  id: ID!
  key: String
  value: String
}

type GuidedHelp @key(fields: "id") {
  id: ID!
  caseReasonId: ID!
  caseTypeId: ID!
  configList: [GuidedHelpConfig]
}

type Query {
  guidedHelps: [GuidedHelp]
  guidedHelp(id: ID): GuidedHelp
}

extend type Reason @key(fields: "id") {
  id: ID! @external
  guidedHelps: [GuidedHelp!]
}

However, when trying to register the second schema I got the following 400 error:

{
    "success": false,
    "error": "[guided-help] Reason -> `Reason` is an extension type, but `Reason` is not defined in any service\n\nGraphQL request:33:1\n32 |\n33 | extend type Reason @key(fields: \"id\") {\n   | ^\n34 |   id: ID! @external"
}

It says that Reason is not defined, but it is defined in the first schema. Can someone help me find out what I am doing wrong?

For reference, I am making the requests in the following order:

POST /schema/push
{
  "typeDefs": "type Query {\r\n  types: [Type]\r\n  type(id: ID): Type\r\n  reasons: [Reason]\r\n  reason(id: ID): Reason\r\n}\r\n\r\ntype Reason @key(fields: \"id\") {\r\n  id: ID!\r\n  description: String\r\n}\r\n\r\ntype Type {\r\n  id: ID!\r\n  description: String\r\n  caseReasonList: [Reason]\r\n}\r\n",
  "graphName": "type-reason",
  "serviceName": "type-reason",
  "version": "1",
  "routingUrl": "http://guided-help.xxx"
}

POST /schema/push
{
  "typeDefs": "type GuidedHelpConfig {\r\n  id: ID!\r\n  key: String\r\n  value: String\r\n}\r\n\r\ntype GuidedHelp @key(fields: \"id\") {\r\n  id: ID!\r\n  caseReasonId: ID!\r\n  caseTypeId: ID!\r\n  configList: [GuidedHelpConfig]\r\n}\r\n\r\ntype Query {\r\n  guidedHelps: [GuidedHelp]\r\n  guidedHelp(id: ID): GuidedHelp\r\n}\r\n\r\nextend type Reason @key(fields: \"id\") {\r\n  id: ID! @external\r\n  guidedHelps: [GuidedHelp!]\r\n}\r\n",
  "graphName": "guided-help",
  "serviceName": "guided-help",
  "routingUrl": "http://guided-help.xxx"
}

Slack, Teams integration

Describe the problem/challenge you have

As an organization, I'd like to notify my teams about important events.

• Schema breaking changes
• Schema changes in general https://www.apollographql.com/docs/studio/schema-change-integration/
• New clients

Similar to https://graphql-inspector.com/docs/essentials/notifications

---

Vote on this request

This is an invitation to the community to vote on issues, to help us prioritize our backlog. Use the "smiley face" up to the right of this comment to vote.

👍 "I would like to see this addressed as soon as possible"
👎 "There are other more important things to focus on right now"

We are also happy to receive and review Pull Requests if you want to help working on this issue.

Validate schemas based on validation rules

Describe the problem/challenge you have
As an organization, I'd like to enforce rules about

• document complexity
• document depth
• schema conventions (camelCase fields, ...)

in a configuration as code approach.

---

Vote on this request

This is an invitation to the community to vote on issues, to help us prioritize our backlog. Use the "smiley face" up to the right of this comment to vote.

👍 "I would like to see this addressed as soon as possible"
👎 "There are other more important things to focus on right now"

We are also happy to receive and review Pull Requests if you want to help working on this issue.

Make parallel calls to KVS storage

,https://github.com/sindresorhus/p-limit, limit 6
https://developers.cloudflare.com/workers/platform/limits#simultaneous-open-connections

Nestjs support

Is it supported with nestjs?

Evaluate cloudflare durable objects

• global uniqueness
• transactional storage API

Normalize schemas before storing

• Field sorting
• Remove whitespaces

This ensures that no duplicates are stored in the database.

Use `kv.list` as replacement for `list` key

This solves the issue with concurrent writes on the list index. The search index like uid, serviceName are stored in the metadata field.

https://developers.cloudflare.com/workers/runtime-apis/kv#listing-by-prefix

Managed federation

Describe the problem/challenge you have

As an organization, I'd like to run my federation architecture fully managed. The registry must provide an endpoint to deliver the supergraph SDL.

https://www.apollographql.com/docs/rover/supergraphs
https://www.apollographql.com/docs/federation/managed-federation/overview/

Specs:

• https://specs.apollo.dev/core/v0.1
• https://specs.apollo.dev/join/v0.1

---

Vote on this request

This is an invitation to the community to vote on issues, to help us prioritize our backlog. Use the "smiley face" up to the right of this comment to vote.

👍 "I would like to see this addressed as soon as possible"
👎 "There are other more important things to focus on right now"

We are also happy to receive and review Pull Requests if you want to help working on this issue.

Getting error while doing migration

`migration failed with error: Unexpected token ;
/home/love/Documents/tempApollo/graphql-registry/graphql-registry/build/core/models/graphModel.js:5
id;
^

SyntaxError: Unexpected token ;
at Module._compile (internal/m`

Validating client operations

https://www.apollographql.com/docs/studio/validating-client-operations/

What kind of format we need to return for supergraphsdl .I am getting errro throw new Error("Expected ".concat((0, _inspect.default)(schema), " to be a GraphQL schema."));

GATEWAY.js######

const { ApolloServer } = require('apollo-server')
const { ApolloGateway } = require('@apollo/gateway')
const { get,post } = require('httpie')

async function getSupergraph() {
const res = await get(http://localhost:4007/graph)
console.log(res.data);
return {
supergraphSdl: res.data
}
}

async function startServer() {
const gateway = new ApolloGateway({
experimental_pollInterval: 30000,
async experimental_updateSupergraphSdl() {
return getSupergraph()
},
__exposeQueryPlanExperimental: false,
})

const server = new ApolloServer({
gateway,
engine: false,
subscriptions: false,
})

server.listen().then(({ url }) => {
console.log(🚀 Server ready at ${url})
})
}

startServer().catch((err) => {
console.error(err)
process.exit(1)
})
################
########Graph-api.js########

const express = require('express')
const app = express()
const port = 4007
const { readFileSync } = require('fs');
const supergraphSdl = readFileSync('./supergraph.graphql');

app.use(express.json());

app.get('/', (req, res) => {
res.end('Hello World!');
});

app.get("/graph", (req, res) => {
console.log(supergraphSdl.toString());
res.end(supergraphSdl);
});

app.listen(port, () => {
console.log(🚀Super graphAPI listening at http://localhost:${port})
});
##################
#########supergraph.graphql########

schema
@core(feature: "https://specs.apollo.dev/core/v0.2"),
@core(feature: "https://specs.apollo.dev/join/v0.1", for: EXECUTION)
{
query: Query
mutation: Mutation
}

directive @core(as: String, feature: String!, for: core__Purpose) repeatable on SCHEMA

directive @join__field(graph: join__Graph, provides: join__FieldSet, requires: join__FieldSet) on FIELD_DEFINITION

directive @join__graph(name: String!, url: String!) on ENUM_VALUE

directive @join__owner(graph: join__Graph!) on INTERFACE | OBJECT

directive @join__type(graph: join__Graph!, key: join__FieldSet) repeatable on INTERFACE | OBJECT

type AddStudentResponse {
code: Int!
message: String!
student: Student
success: Boolean!
}

type Mutation {
addStudent(gender: String!, name: String!): AddStudentResponse! @join__field(graph: STUDENTS)
}

type Query {
studentDetails: [Student!]! @join__field(graph: STUDENTS)
studentDetailsbyId(id: ID!): Student! @join__field(graph: STUDENTS)
}

type Student
@join__owner(graph: STUDENTS)
@join__type(graph: STUDENTS, key: "id")
{
gender: String @join__field(graph: STUDENTS)
id: ID @join__field(graph: STUDENTS)
name: String @join__field(graph: STUDENTS)
}

enum core__Purpose {
"""
EXECUTION features provide metadata necessary to for operation execution.
"""
EXECUTION

"""
SECURITY features provide metadata necessary to securely resolve fields.
"""
SECURITY
}

scalar join__FieldSet

enum join__Graph {
STUDENTS @join__graph(name: "students" url: "http://localhost:4004/")
}

Garbage collect schemas

Keep the N recent schemas in the store. Provide an endpoint to trigger the clean up.