Skip to content

How It Works

Setting up Fusion for a composite schema is relatively straightforward, specially by using the capabilities the Suite CLI provides us.

Key Components

Fusion configures and interprets graphs through a set of configuration and composition files, each defined for a specific purpose:

  • subgraph-config.json allow to identify a subgraph by a name and where to reach it (by exposing a service address)
  • schema.graphql exposes the complete GraphQL schema of a subgraph. It is generated from the service's runtime types.
  • .fsp files take the schema.graphql, the subgraph config and any defined extension files as inputs to generate a schema composition file that is understandable from the gateway's perspective.
  • gateway.fgp contains the complete gateway graph, specifying each available field and which subgraph can be used to resolve it.

How these files are handled

Both .fsp files and gateway.fgp files are automatically generated as part of the CI/CD loop. This ensures that schemas are always up to date and makes the overall process less error-prone.

On the other hand, schema.graphql files are part of the source code and must be kept manually updated as part of the development loop. During PR builds, the schema.graphql file is compared against the changed source code to ensure no pending changes are left uncommitted to the GraphQL schema.

Configuring subgraphs

As it was previously stated, subgraphs are exposed by backend services as standalone, business-oriented schemas. Nonetheless, if we require to expose our source schema to a gateway we need to do some configuration.

Lets start by referencing our gateway from the backend service's application.yaml

application.yaml
1
2
3
4
5
6
7
8
spec:
    build:
        dotnet:
            graphql:
                publish:
                    - gateway: admin-center-bff
                      extensions:
                          - admin-center.fusion.extensions.graphql

This is enough for the suite tooling to discover and understand the relation between our subgraph and the specified gateway. Note that we can optionally specify extension files that will be only applied for that gateway, and multiple gateways can be specified as well.

From HotChocolate's perspective, we need to make our subgraph discoverable; this means giving it a well-known name and an address where we can reach it.

subgraph-config.json
1
2
3
4
{
    "subgraph": "addresses",
    "http": { "baseAddress": "http://addresses-service/graphql" }
}

Hint

subgraph-config.json can be generated by the suite CLI

Bash
1
suite app graphql config addresses

Exposing source schemas

Each subgraph's schema is exposed through a schema.graphql file. This is also easily generated by the suite CLI.

Bash
1
suite app graphql schema addresses

Running this command will actually do two things:

  • Generate the source schema file from the application's runtime.
  • Pack the subgraph for each gateway specified in the application.yaml file, including each extension files if any.

If we only want to generate our source schema without packing (this can be helpful specially during development time) we can do so by run ing

Bash
1
suite app graphql schema addresses --no-pack

Packing schemas

If we only need to pack the existing schemas we can do so by calling

Bash
1
suite app graphql pack addresses

Composing the gateway schema

Gateways can be composed through the compose command. A key characteristic about schema composition is that it is an additive process: it will take an existing gateway.fgp file and apply the changes provided by the newly generated .fsp package. In order to completely compose a schema from scratch, we should compose each of the subgraphs for the specified gateway.

Taking this into account, and considering that gateway.fgp files are not kept as part of the source code, its clear that we need a quick and cheap way for obtaining a gateway.fgp file before applying our changes.

This can be accomplished by calling:

Bash
1
suite app graphql compose addresses -g=<gateway-name>

Whenever a -g option value is passed along, the gateway schema file will be pulled from the corresponding docker image before applying any composition changes.