# Migrating from Apollo

Grafbase and Apollo GraphOS both implement the GraphQL Federation v2 spec. This means you can run a federated graph composed from the same subgraphs using either the Grafbase Gateway or Apollo Router. This guide will assist you in migrating from Apollo to Grafbase.

The major components are comparable:

| Component       | Apollo        | Grafbase          |
| --------------- | ------------- | ----------------- |
| Gateway         | Apollo Router | Grafbase Gateway  |
| Schema Registry | GraphOS       | Grafbase Platform |
| CLI             | Rover         | Grafbase CLI      |

Additionally, the Grafbase Platform can be fully self-hosted in your own infrastructure for maximum security and control. [Contact sales](/contact/sales) if you want to learn more about the Grafbase Enterprise Platform.

We will explore two scenarios: first, how to run the Grafbase Gateway without migrating any of your GraphOS setup, and second, how to migrate over your federated graph from GraphOS to Grafbase.

## Trying Grafbase Gateway only

If you want to try Grafbase Gateway without migrating your GraphOS setup, you can do so by starting Grafbase Gateway with your existing Federated Graph.

First, you need to [install Grafbase Gateway](/docs/self-hosted-gateway#installation):

```bash
curl -fsSL https://grafbase.com/downloads/gateway | bash
```

Next, you will need the schema of your federated graph. You can download it from the GraphOS Studio UI or via the `rover` CLI:

```bash
rover supergraph fetch my-graph@my-variant > federated.graphql
```

Now you can start the Grafbase Gateway with your Federated Graph:

```bash
grafbase-gateway --schema federated.graphql
```

You are now up and running! You can send queries to the Grafbase Gateway and see it work with your Federated Graph. To explore all the features and configuration options of the gateway, check out the [relevant documentation](/docs/self-hosted-gateway).

When you are ready for a full migration, you can proceed to the next section. We're also happy to provide assistance, just [contact us](/contact)!

## Migrating a Federated Graph from Apollo GraphOS to Grafbase

This part of the guide will walk you through setting up your Federated Graph on Grafbase, assuming you already have running subgraphs that have been published to GraphOS.

### Step 1: Exporting your subgraph schemas

First, you will need the [Grafbase CLI](https://grafbase.com/cli). You can either use `npx grafbase` or install it with the following command:

```bash
curl -fsSL https://grafbase.com/downloads/cli | bash
```

You can list all your subgraphs as shown in the following example:

```bash
rover subgraph list Spotify-Demo-Graph-4m8tpk@current --format=plain
Listing subgraphs for Spotify-Demo-Graph-4m8tpk@current using credentials from the default profile.
┌──────────┬──────────────────────────────────────────────┬────────────────────────────┐
│   Name   │                 Routing Url                  │        Last Updated        │
├──────────┼──────────────────────────────────────────────┼────────────────────────────┤
│ spotify  │ https://showcase-spotify.apollographql.com/  │ 2024-05-06 15:21:54 +02:00 │
├──────────┼──────────────────────────────────────────────┼────────────────────────────┤
│ playback │ https://showcase-playback.apollographql.com/ │ 2024-05-06 15:21:54 +02:00 │
└──────────┴──────────────────────────────────────────────┴────────────────────────────┘
```

You can pick the subgraphs you want to migrate and publish them manually, or automate the process with a small script.

To publish manually, you can use `rover subgraph fetch` to download the schema of a subgraph, then `grafbase publish` to publish it:

```bash
rover subgraph fetch Spotify-Demo-Graph-4m8tpk@current > spotify.graphql
npx grafbase publish --schema spotify.graphql --url=https://showcase-spotify.apollographql.com/ --name=spotify
```

To automate the process, you can use a script like the following:

```bash
GRAPHOS_GRAPH_REF=Spotify-Demo-Graph-4m8tpk@current
GRAFBASE_GRAPH_REF=my-account/my-graph@main

rover subgraph list $GRAPHOS_GRAPH_REF --format=json | jq -c '.data.subgraphs[] | {name: .name, url: .url}' > subgraphs.json

while IFS= read -r line; do
  name=$(echo "$line" | jq -r '.name')
  url=$(echo "$line" | jq -r '.url')
  rover subgraph fetch $GRAPHOS_GRAPH_REF --name "$name" > "$name.graphql"
  grafbase publish $GRAFBASE_GRAPH_REF --name "$name" --url "$url" --schema "$name.graphql"
done < subgraphs.json
```

This takes care of the initial setup.

### Step 2: Setting up subgraph publishing

You should also make sure that you also publish to Grafbase in your release process wherever you already publish to GraphOS with `rover subgraph publish`. Read more on `grafbase publish` on [the dedicated docs page](/docs/schema-registry/publish). This will ensure your subgraphs are up to date on both platforms for the duration of your migration.

### Step 3: Setting up schema checks

Similarly, you should set up schema checks on Grafbase. You can use the `grafbase check` command to check your schema against the Grafbase Platform. Read more on `grafbase check` on [the dedicated docs page](/docs/schema-registry/check).

### Step 4: Setting up Grafbase Gateway

Whether you use the binary directly, the [official Docker image](https://github.com/grafbase/grafbase/pkgs/container/gateway), or your own preferred deployment method, you can start the Grafbase Gateway with the Federated Graph SDL directly, as in the previous section, or use the graph reference for your gateway to automatically pick up the latest Federated Graph schema whenever it gets published:

```bash
GRAFBASE_ACCESS_TOKEN=token ./grafbase-gateway \
  --config grafbase.toml \
  --graph-ref graph@branch
```

The `--config` argument is optional, but to start the gateway with a graph ref, the access token is mandatory. You can get an access token from the Grafbase dashboard.

For more information on the features, configuration options, and ways to run the gateway, see the dedicated [docs section](/docs/self-hosted-gateway).

You now have the schema registry populated and the gateway set up. You are running your Federated Graph on Grafbase!

## Common workflows

### Publishing a subgraph

Rover:

```bash
rover subgraph publish my-graph@my-variant --name my-subgraph --schema ./my-subgraph.graphql --routing-url https://my-subgraph.example.comjk
```

Grafbase:

```bash
npx grafbase publish my-graph@branch-name --name my-subgraph --schema ./my-subgraph.graphql --url https://my-subgraph.example.com
```

### Running schema checks

Rover:

```bash
rover subgraph check my-graph@my-variant --name my-subgraph --schema ./my-subgraph.graphql
```

Grafbase:

```bash
npx grafbase check my-graph@branch-name --name my-subgraph --schema ./my-subgraph.graphql
```

Migrating from Apollo

# Guides

- [Migrating from Apollo](/docs/guides/migrating-from-apollo)

Guides

# Grafbase API

The [Grafbase Dashboard](/dashboard) is powered by the Grafbase API. This same API is available for users to manage their account and projects programmatically.

Everything you have access to do inside the Grafbase Dashboard can be done using the Grafbase API.

**This API is always changing and may introduce breaking changes at any point.**

## Endpoint

You make GraphQL requests to: `https://api.grafbase.com/graphql`

## Auth

You will need a valid [Access Token](/docs/accounts/access-tokens) that you will need to pass as an `Authorization` header.

The header should the Bearer authentication format:

`Authorization: Bearer TOKEN`

## Schema

The Grafbase API endpoint has introspection enabled so you can use any GraphQL Playground (Postman, Insomnia, GraphiQL) to view the schema documentation.

Grafbase API

# Use cases

This page is intended as a complement to the [subgraph directives reference](/docs/federation/directives). We will If you want to read about the use cases for Federation in general, the [overview](/docs/federation) is a better starting point.

## Extend a type from another subgraph

Whenever you want to add fields to a type that exists in another subgraph, the answer is defining an [entity](/docs/federation#entities) with the [@key](/docs/federation/directives#key) directive.

## Migrate fields between subgraphs

The [@override](/docs/federation/directives#override) directive lets you define an existing field in another subgraph and redirect part of all the traffic from the overriden subgraph for that field all at once, or in a progressive manner. Read the directive documentation for more details.

## Access control

The [@authenticated](/docs/federation/directives#authenticated) and [@requiresScopes](/docs/federation/directives#requiresScopes) directives allow you to restrict access to parts of your API based on the authentication state (JWT presence and scopes).

The [@inaccessible](/docs/federation/directives#inaccessible) directive lets you hide parts of your subgraphs completely.

## Other use cases

If you have a concrete use case that you want to address with Federation, please talk to us on [Discord](https://discord.gg/grafbase).

Use cases

# Authorization

By default, the federated graph is publicly available. It is up to subgraphs to check whether a user has the proper credentials. Alternatively, a federated graph can also validate whether users have proper credentials before the request execution through a authorization provider. Multiple authorization providers can be configured, only one needs to authorize the user.

## JWT Authorization

JWT authorization can be configured as follows:

```toml
[authentication.providers.jwt.jwks]
url = "https://example.com/.well-known/jwks.json"
```

We follow the JWT ([RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519)) specification for JWT validation and validate its signature with the JWKs ([RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517)) provided at `jwks.url`. The validation consists of the following steps:

1. The signature of the JWT must be valid with one of the specified JWK.
2. if the `exp` claim is present, it must be in the future with a leeway of 60s.
3. if the `nbf` claim is present, it must be in the past with a leeway of 60s.
4. if the `iss` claim is present and `issuer` is specified, they must match.
5. if the `aud` claim is present and the `audience` is specified, they must match. If `aud` is an array `audience` must be part of it.

While not required, it is **strongly recommended** to at least specify the `audience` (`aud` claim). Otherwise JWTs which weren't meant for your project would still be accepted.

Here is the full configuration with optional fields:

```toml
[authentication.providers.jwt]
name = "my-authenticator"

[authentication.providers.jwt.jwks]
url = "https://example.com/.well-known/jwks.json"
issuer = "example.com"
audience = "my-project"
poll_interval = 60

[authentication.providers.jwt.header]
name = "Authorization"
value_prefix = "Bearer "
```

The `poll_internal` value defines how often the JWKs will be refreshed. It is best left to its default value.

Authorization

List of error codes used in GraphQL errors by a federated graph

Errors

# Directives

Composition works without intervention if the subgraphs are independent from another and do not share types and fields. But composition can also act as much more than schema stitching: federation directives allow each subgraph to declaratively specify what it can resolve and how it fits with other subgraphs in the federated graph, so the router can expose a consistent whole with connections that span across subgraphs, with minimal coordination between the teams owning each subgraph. Read on to understand what directives exist and what they do, or read the [Use cases](/docs/federation/use-cases).

## @key

```graphql
directive @key(
  fields: FieldSet!
  resolvable: Boolean = true
) repeatable on OBJECT | INTERFACE
```

The `@key` directive is how entities are defined. Entities are types with a key that exist in multiple subgraphs. This is the main mechanism that connects subgraphs together in Federation. It can be thought of as a primary key.

When you make a type an entity with the `@key` directive, your [Federation compatible GraphQL framework of choice](https://www.apollographql.com/docs/federation/building-supergraphs/supported-subgraphs) will also require that you define an _entity resolver_ for that type. This is simply a resolver that will be used in the Federation-specific `Query._entities` field to fetch

Arguments:

- `fields`: a string containing GraphQL selection set for the fields included in the key. The selection can be nested (e.g. `@key(fields: "a { b } c d")`) but it cannot include field arguments (e.g. `@key(fields: "id(type: UUID) { bytes }")` is not valid).
- `resolvable`: when false, indicates that the subgraph references an entity — often by returning its key — but cannot resolve it through `Query._entities`. In other words, there is no entity resolver for that entity in this subgraph. This is useful when a subgraph has the key for an entity — for example an `author_id` on a blog post — but does not contribute fields to that entity.

### Example

Let us use a fictitious e-commerce website to showcase what you can do with entities. First we define an `inventory` subgraph:

```graphql
type Product @key(fields: "id") @key(fields: "sku") {
  id: ID!
  itemsInStock: Int!
  sku: String!
}
```

The second `@key` simply means that the `inventory` subgraph can also resolve a Product from its SKU.

Then a `reviews` subgraph for product reviews:

```graphql
type Product @key(fields: "id") {
  id: ID!
  reviews: [Review!]
}
```

And finally a `search` subgraph that can find products based on a query:

```graphql
type Query {
  findProducts(searchQuery: String!): [Product!]
}

type Product @key(fields: "id") {
  id: ID!
}
```

After composition, the API of the federated graph will look like this:

```graphql
type Query {
  findProducts(searchQuery: String!): [Product!]
}

type Product {
  id: ID!
  reviews: [Review!]
  itemsInStock: Int!
  sku: String!
}
```

From an API client's perspective, there is a single Product type. Each subgraph contributed fields to it transparently and without coordination.

## @interfaceObject

```graphql
directive @interfaceObject on OBJECT
```

Expresses that an object type is part of an Entity Interface. See the section on [Entity Interfaces](/docs/federation#entity-interfaces) for details and examples.

## @shareable

```graphql
directive @shareable on FIELD_DEFINITION | OBJECT
```

Declares a type or a field as shared between subgraphs. Unlike an entity defined with `@key`, shareable types and fields must be resolvable in all subgraphs. A good example would be a Color type:

```graphql
type Color @shareable {
  red: Int!
  green: Int!
  blue: Int!
}
```

Every subgraph that can return a `Color` is expected to provide all the fields. Another way to think about shareable types is to consider them like value types that are always available as a whole.

Annotating a type like `Color` in the example above is the same as annotating every field of that type with `@shareable`.

## @requires

```graphql
directive @requires(fields: FieldSet!) on FIELD_DEFINITION
```

Expresses the idea that a field requires other fields from the parent type that may be resolved _in other subgraphs_. For example, let us say that your hotel booking has a subgraph responsible for managing room service, but that subgraph does not have specific hotels in its database, it knows what room service is available depending on the location and category of the hotel, but it does not have a hotels database. We could use `@requires` in the following way.

In the Hotels subgraph:

```graphql
type Hotel @key(fields: "id") {
  id: ID!
  category: Int
  countryCode: String
}
```

and in the RoomService subgraph:

```graphql
type Hotel @key(fields: "id") {
  id: ID!
  category: Int @external
  countryCode: String @external
  roomServiceOffering: [String!]! @requires(fields: "category countryCode")
}
```

In this last snippet, the RoomService subgraph expresses that it can resolve `Hotel.roomServiceOffering`, but to do so, it needs the `category` and `countryCode` fields, resolved by an other subgraph. The dependency on the `category` and `countryCode` fields is expressed with `@requires`, and the fact that the subgraph cannot resolve them itself is expressed by `@external`. The required fields must be defined on the type, and they must be annotated with `@external`.

At runtime, when the gateway must resolve a query that selects `Hotel.roomServiceOffering`, it will know that it must first query the Hotels subgraph in order to pass them to the RoomService subgraph when resolving `roomServiceOffering` for that hotel. Diving a bit deeper, the mechanism by which the gateway does that is by passing the two previously retrieved fields to the entity resolver (`Query._entities`) on the RoomService subgraph.

Note that the fields marked with `@external` can be resolved by any number of other subgraphs: zero is valid but will make the field with `@requires` impossible to query, one if the fields are regular fields on the entity, or potentially more if the fields are `@shareable`.

Remember: `@requires` is only allowed on fields of entities, and only used in combination with [`@external`](#external).

## @provides

```graphql
directive @provides(fields: FieldSet!) on FIELD_DEFINITION
```

Written on a field, `@provides` communicates to the gateway that whenever the field is resolved, a set of other fields on the same object can also be resolved by the same subgraph, as an optimization. The other fields must be annotated with `@external`, because they cannot be resolved in the subgraph unless the field annotated with `@provides` is also resolved. You can think of this directive as a more restricted version of `@shareable`. Shareable fields can always be resolved, whereas fields marked with `@external` and provided with `@provides` are only resolvable when the providing field is also resolved.

### Example

A `Farms` subgraph:

```graphql {5}
type Farm @key(fields: "id") {
  id: ID!
  name: String!
  location: String
  vegetables: [Vegetable] @provides(fields: "name")
}

type Vegetable @key(fields: "id") {
  id: ID!
  name: String! @external
}

extend type Query {
  farm(id: ID!): Farm
  vegetablesInSeason(date: Date!): [Vegetable!]
}
```

And a `Veggies` subgraph:

```graphql
type Vegetable @key(fields: "id") {
  id: ID!
  name: String!
  scientificName: String!
  nutritionInfo: NutritionInfo
  marketPriceEur: Int
}
```

Now let us look at what `@provides` does with two example queries.

```graphql
query {
  farm(id: "6058691a-2d0a-47f1-95b3-1632f9ad16f9") {
    id
    name
  }
}
```

Since the `Query.farm` field _provides_ `name`, the gateway can resolve the whole query only talking to the `Farms` subgraph. On the other hand, in this second query:

```graphql
query {
  vegetablesInSeason(date: "2023-10-03") {
    id
    name
  }
}
```

the gateway will have to fetch the vegetable name from the `Veggies` subgraph. Note that this is transparent to the client: from an API consumer's perspective, there is only one Vegetable type with all the fields defined across all the subgraphs.

## @external

```graphql
directive @external on FIELD_DEFINITION | OBJECT
```

On a field, expresses that a field is present in the subgraph's schema, but the subgraph cannot resolve it. This directive is only meaningful in combination with `@provides` and `@requires`.

Writing `@external` on an object is equivalent to writing `@external` on each of the object's fields.

## @override

```graphql
directive @override(from: String!, label: String) on FIELD_DEFINITION
```

The use case for `@override` is migrating a field from one subgraph to another subgraph. Before you can remove the field from the first subgraph, you have to define it in the second subgraph, but the rules of composition will prevent you from defining the same field in two subgraphs. If you define the field as `@shareable`, it must be resolvable in all subgraphs, not only these two. You could mark the new field as `@inaccessible` at first, but you cannot switch the field over from the old to the new subgraph without coordination and downtime.

So another solution is needed, and the `@override` directive is that solution. When you annotate a field with `@override(from: "other-subgraph")`, the gateway will route requests for that field to the subgraph that defines the override and ignore that the field still exists in `other-subgraph`. That way, teams can deploy at their own pace with the following workflow (each bullet point is a `publish`):

- Deploy the new field with `@override` in the overriding subgraph. That change can easily be reverted if the field does not behave as well in the next subgraph. Once the change is reverted, the gateway will go back to simply resolving the field in the original subgraph.
- Remove the old field in the overriden subgraph.
- Remove the `@override` directive in the overriding subgraph.

### Example

Imagine you are splitting the handling of comments away from your blog engine monolith into its own service, with its own subgraph. The `Post` type looks like this on the monolith:

```graphql
type Post @key(fields: "id") {
  id: ID!
  title: String
  comments: [Comment!]
  publishedAt: DateTime
  author: User
}
```

Migrating the `Post.comments` field to the new comments service can be achieved by adding the following to the comments subgraph's schema:

```graphql
type Post @key(fields: "id") {
  id: ID!
  comments: [Comment!] @override(from: "monolith")
}
```

After deploying this addition, all the traffic for `Post.comments` will be routed to the comments subgraph.

### Arguments

- `from`: the name of the subgraph where the field is also defined, and which will be overriden by the field annotated with `@override`. Note that this is not validated to enable the following workflow: 1. define the overriding field with `@override`, 2. deploy, 3. remove the overriden field, 4. remove the `@override` on the new field. If composition validated that the field is also defined in the subgraph referenced in `from`, the migration would break at step (3.), since subgraphs are published independently.
- `label`: allows partial or progressive overriding. The `label` argument takes a string of the form "percent(n)" where "n" is an integer from 0 to 100 specifying a percentage of the traffic for the field that the gateway should route to the overriding subgraph. In other words, `@override(from: "inventory", label: "percent(0)"")` will not change how the field is resolved, and `@override(from: "inventory", label: "percent(100)")` would be equivalent to `@override(from: "inventory")` without `label` argument.

## @composeDirective

```graphql
directive @composeDirective(name: String!) repeatable on SCHEMA
```

By default, only some built-in (`@deprecated`) and Federation directives (e.g. `@inaccessible`) defined on subgraphs will be passed on by composition into the Federated Schema.

The `@composeDirective` directive is a signal for composition to preserve instances of a specific directive in the final API schema of the Federated Graph.

Arguments:

- `name`: the name of the directive to compose.

Example:

```
extend schema @composeDirective(name: "myCustomDirective")

type Test @myCustomDirective {
  id: ID!
}
```

## @authenticated

```graphql
directive @authenticated on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM
```

Restrict access to the annotated item to successfully authenticated users. For more granularity, use [@requiresScopes](#requiresScopes).

## @requiresScopes

```graphql
directive @requiresScopes(
  scopes: [[String!]!]!
) on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM
```

Restrict access to the annotated item to users having a matching `scope` claim in their JWT access token. The `scope` claim is expected to be a string of space-separated scope names.
The directive `scopes` argument is an array of arrays that should be understood as a list of combinations of scopes. Each inner array is a combination of scopes where all scopes must be present (`AND`). The outer array is a list of accepted alternative combinations of scopes (`OR`). The order is not relevant.

### Example

For example, imagine you want to restrict access to the view count for a blog post to either users with the `editor` and `analytics` scope, or admins:

```graphql {5,5}
type BlogPost {
  id: ID!
  title: String!
  author: User
  viewCount: Int @requiresScopes(scopes: [["admin"], ["editor", "analytics"]])
  content: String
}
```

## @inaccessible

```graphql
directive @inaccessible on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION
```

Parts of the schema that are marked as `@inaccessible` will not be part of the composed API schema exposed by the gateway. It only takes one `@inaccessible` in one subgraph to exclude an item from the composed API, even if the same item is not inaccessible in other subgraphs.

### Example 1: hiding information

```graphql
type PersonalDetails @inaccessible {
  age: Int
  heightCm: Int
  birday: Date
}

type User @key(fields: "id") @key(fields: "socialSecurityNumber") {
  id: ID!
  # socialSecurityNumber is a key to enable fetching users by social security number, but we do not want the field to be queryable.
  socialSecurityNumber: String! @inaccessible

  # This field must be marked as inaccessible because the field type is inaccessible.
  details: PersonalDetails @inaccessible
}
```

### Example 2: adding fields to a shareable type

Imagine you have an RGB color type shared across multiple subgraphs. Since the type is `@shareable`, every subgraph must be able to return all of its fields. Now you want to add a new field to that type, so you start adding it to a first subgraph, and then publish. This will lead to a composition error: one subgraph has the new field, but not others. You can accept this fact and publish all your subgraphs in close succession, accepting that your federated graph will not compose in the intermediate states. That works, but it scales poorly if you have many subgraphs managed by different teams. A better solution can be implemented with `@inaccessible`. You can publish the first subgraph adding the new field like this:

```graphql
type Color @shareable {
  red: Int!
  green: Int!
  blue: Int!
  opacity: Int! @inaccessible
}
```

Since `opacity` is inaccessible, it does not trigger a composition error, even if `opacity` is not defined in other subgraphs. You can progressively add the field to other subgraphs, and once they all define it, remove the `@inaccessible`. All the intermediate states compose cleanly.

## @authorized

```graphql
directive @authorized(
  arguments: InputValueSet
  metadata: _Any
) repeatable on OBJECT | INTERFACE | FIELD_DEFINITION
```

The `authorized` directive is for authorizing resource access based on attribute data. The directive is available only in the self-hosted [Grafbase Gateway](/docs/self-hosted-gateway) together with the [authorization hooks](/docs/self-hosted-gateway/hooks#authorization). The idea of the directive is to utilize the [gateway hook](/docs/self-hosted-gateway/hooks#gateway-request) to parse information from the request headers to the context object, and to use this information together with the authorization data to decide should the data be sent back to the user or not.

If an authorization hook responds an error, the requested data will be `null` together with a custom error message.

### Edge level pre-execution hook

In Grafbase Gateway version 0.4.0, the directive can be written to an edge definition:

```graphql
schema {
  query: QueryRoot
}

type Query {
  getUser(id: Int!): User
    @authorized(arguments: "id", metadata: { accessLevel: "user" })
}

type User {
  id: Int!
  name: String!
}
```

When the user runs a query that accesses the getUser edge:

```graphql
query {
  getUser(id: 1) {
    id
    name
  }
}
```

It calls the `authorize-edge-pre-execution` WebAssembly hook with an `edge-definition` of:

```rust
EdgeDefinition {
    parent_type_name: "Query",
    field_name: "getUser",
}
```

With the arguments:

```json
{ "id": 1 }
```

And with the metadata:

```json
{ "accessLevel": "user" }
```

Together with custom headers, the hook function can make a decision should it allow running the query or not.

### Edge level post-execution hooks

In Grafbase Gateway version 0.4.0+, the directive can be written to an edge definition:

```graphql
schema {
  query: QueryRoot
}

type Query {
  users: User @authorized(node: "id", metadata: { accessLevel: "user" })
}

type User {
  id: Int!
  name: String!
  address: String!
    @authorized(fields: "id", metadata: { accessLevel: "user:address" })
}
```

When the user runs a query that accesses the getUser edge:

```graphql
query {
  users {
    id
    name
    address
  }
}
```

It first calls the `authorize-parent-edge-post-execution` WebAssembly hook with the following arguments:

```js
{
    context: ..., // The context object
    definition: {
        parent_type_name: "Query",
        field_name: "users",
    },
    nodes: [
        '{"id": 1}',
        '{"id": 2}',
    ],
    metadata: '{"accessLevel": "user"}',
}
```

Any unauthorized nodes will raise an error.

Then the second hook `authorize-edge-nost-post-execution` is called with the following arguments:

```js
{
    context: ..., // The context object
    definition: {
        parent_type_name: "Query",
        field_name: "users",
    },
    parents: [
        '{"id": 1}',
        '{"id": 2}',
    ],
    metadata: '{"accessLevel": "user:address"}',
}
```

Any unauthorized fields will raise an error.

### Node level pre-execution hook

In Grafbase Gateway version 0.4.0, the directive can be written to a node definition:

```graphql
type User @authorized(metadata: { accessLevel: "user" }) {
  id: Int! @join__field(graph: USERS)
  name: String! @join__field(graph: USERS)
}
```

When the user runs a query that accesses the User type:

```graphql
query {
  getUser(id: 1) {
    id
    name
  }
}
```

It calls the `authorize-node-pre-execution` WebAssembly hook with an `node-definition` of:

```rust
NodeDefinition {
    type_name: "User",
}
```

And with the metadata:

```json
{ "accessLevel": "user" }
```

Together with parsing the data in the custom headers to the hook context objects, the hook funtion can make a decision should it allow responding with fields from the `User` type.

Directives

# Federation

The purpose of Federation is to create a single, unified graph from many subgraphs. Some form of this idea has been around for a long time under the name "schema stitching", but Federation goes further by letting the federated GraphQL APIs — called "subgraphs" — declaratively extend each other and share parts of their API surface, in a way that is seamless and transparent for consumers of the Federated graph.

## Composition

Composition is the process of combining the schemas of all the subgraphs in a federated graphs into a single federated schema. The subgraphs can evolve independently most of the time, but composition has rules on what is valid or not.

Composition happens in the schema registry whenever you [publish a subgraph](/docs/schema-registry/publish) or run a [schema check](/docs/schema-checks).

Without [subgraph directives](/docs/federation/directives), the following basic rules apply:

**Object types** can be defined in any number of subgraphs, but each of their fields can only be defined in a single subgraph (the same field cannot be defined in two subgraphs). That each field belongs to a single subgraph that is responsible for resolving it.

The same rule applies to **interfaces**.

When the same **input type** is present in multiple subgraphs, composition will reduce it to the fields that are defined in all subgraphs, and exclude any field that is defined in some subgraphs but not others. If any nonnullable field is excluded, that triggers a composition errors. The same rule applies to field arguments.

**Enums** are composed based on how they are used:

- For enums that are used only in input types and field arguments, composition will only preserve the values of the enum that are common between all subgraphs
- For enums that are used only as output field types, composition will preserve all values from all subgraphs
- Enums that are used both in input and output position must match exactly between subgraphs, else that will be a composition error.

Composition will accumulate and merge all members for each **union** across all subgraphs.

**Directives** are not preserved in the composed schema except for built-ins like `@deprecated`.

This set of rules is of course very limiting in how much subgraphs can evolve together and integrate into a coherent, unified API. Read the following section entities and the [subgraph directives](/docs/federation/directives) page to understand how subgraphs can be better integrated.

## Runtime

At runtime, a federated setup is made up of three components:

- The subgraphs. They are regular GraphQL APIs that can use federation directives to interact with composition
- The [schema registry](/docs/schema-registry), responsible for storing and composing published subgraph schemas
- The gateway, that serves the Federated Graph based on the schema composed by the schema registry

In the context of Grafbase, the subgraphs will be your standalone graphs or regular GraphQL APIs hosted on Grafbase or somewhere else. The schema registry is part of the platform; you interact with it through the web dashboard and the Grafbase CLI. The gateway can be part of the managed Grafbase deployment or [self-hosted](https://grafbase.com/docs/self-hosted-gateway).

## Entities

The most important mechanism for subgraphs to combine with each other.

An entity is defined as an object annotated with the [`@key` directive](/docs/federation/directives#key):

```graphql
type Product @key(fields: "id") {
  id: String!
  name: String!
  createdAt: DateTime!
}
```

The fields in `@key` uniquely identify the object across subgraphs, similar to the primary key in a database. When you use a GraphQL library compatible with federation to define a subgraph, each object annotated with `@key` will require that you write an entity resolver that can retrieve the object based on that key. For example in Apollo Server:

```js
const resolvers = {
  User: {
    __resolveReference(object) {
      return fetchUserById(object.id) // fetchUserById is a hypothetical function that retrieves a User by their ID
    },
  },
}
```

The gateway knows which subgraphs can resolve which fields on each entity, so for example, if you have a comments subgraph for a blog API with the following API:

```graphql
type BlogPost @key(fields: "id") {
  id: ID!
  comments: [Comment!]
}
```

and a search subgraph with the following:

```graphql
type BlogPost @key(fields: "id") {
  id: ID!
}

type Query {
  findBlogPosts(filters: Filters): [BlogPost!]
}
```

you can query the gateway with queries that bridge the subgraphs transparently:

```graphql
query {
  findBlogPosts(filters: [...]) {
    id
    comments {
      id
      title
      author { name }
      text
    }
  }
}
```

## Entity interfaces

Additionally, Federation also allows [Entity Interfaces](./entity-interfaces). They are also entities, and the same mental model applies, but they are defined slightly differently and exhibit some extra behaviour due to being interfaces, compared to regular object interfaces.

In a nutshell, an interface entity is an entity that is defined as an interface with a key in one subgraph, and a regular object entity with the addition of the `@interfaceObject` directive in other subgraphs.

The value proposition for interface entities is that objects that implement the entity interface (like they would implement any other interface) will automatically be extended with the fields contributed by the other subgraphs to the entity.

Federation

# Publishing a subgraph

The federated graph's schema is not managed directly: the schema registry
produces it by [composing](../composition) the schemas of subgraphs. You
compose the federated graph's schema by publishing subgraphs.

## CLI

The `grafbase publish` command takes the following arguments:

- a [graph reference](#graph-reference) positional argument (required)
- `--schema` (optional): the file path of the GraphQL schema you want to
  publish. If the argument is not provided, the CLI will try to read the schema
  from stdin.
- `--url` (optional): the url of the endpoint serving the subgraph you are
  publishing. This argument is only required the first time a subgraph is
  published. If not provided, the url is assumed to be the same as the
  currently published version's.
- `--name` (required): the [name](../) of the subgraph to publish.

## Graph reference

A graph reference is a string of the form `account/graph@branch`. The
branch is optional. So if your account name is `jdoe`, and your graph is
called `blog-example`, then `jdoe/blog-example` is a valid graph reference.

When the branch is left out, the CLI assumes you mean the production branch, so
in the previous example, the graph reference may be equivalent to
`jdoe/blog-example@main`.

The CLI commands that interact with the schema registry all take a project
reference as a first argument.

## Workflow

It generally makes sense to publish a subgraph schema every time you deploy a
new version of the subgraph. Publishing an already published schema again
without changes is safe, it has no side effects.

As described in [Composition](/docs/schema-registry/composition) however, publishing an updated
subgraph schema has side effects:

- Composition may fail, and the federated graph's schema will not be updated
  until you fix the composition errors.
- Composition succeeds, and the federated graph's schema is updated, but your
  changes break existing client (for example, when you remove a field or change
  its type).

To avoid disruption, [Schema Checks](/docs/schema-checks) are there to verify that publishing
your new or updated schema is safe.

Publishing a subgraph

# Composition

When you [publish](../publish) a subgraph, the registry will attempt to
compose it with all the other subgraphs published in the branch.

If composition succeeds, the result is a new federated graph schema. The
router picks up that schema, and it becomes the new public facing API for the
federated graph.

If composition fails, the federated graph is not updated, it keeps running with
the previously working federated schema. The branch is now in a state where the
subgraphs do not compose. You will see the composition errors and hints on how
to fix them on each new publish and check invocation, until the subgraphs
schemas compose together again without error.

<CardWidget>

Publishing still succeeds even when that results in composition errors and a
branch that is in a failing state, because valid migration workflows depend on
that behaviour.

For example, assume you want to move a type from subgraph A to subgraph B.
There is a zero downtime, non-breaking migration path that involves the
subgraphs on the branch not composing during the migration:

1. Add the type to subgraph B.
2. Publish and deploy subgraph B.
3. Delete the type from subgraph A.
4. Publish and deploy subgraph A.

In the time between (2.) and (4.), the branch will fail to compose because the
type is not owned by a single subgraph, but subgraph A will still serve queries
for the type.

</CardWidget>

Composition

# Listing and inspecting

You can list subgraphs in a given branch and inspect the schema of subgraphs
and federated graphs using the Grafbase CLI.

## Listing subgraphs

The `grafbase subgraphs` command lets you list the currently published
subgraphs in a branch. It takes a [project
reference](../publish#project-reference) as its only argument.

Example:

```bash
$ npx -y grafbase subgraphs tomhoule/schema-check-action-federated-graph-example@main
Grafbase CLI 0.48.1

Subgraphs:

-  manufacturing
-  retail
```

## Inspecting schemas

The `grafbase schema` command lets you inspect subgraph and federated graph schemas.

With the `--name` argument, the command will print the GraphQL schema of the subgraph with the given name:

```
$  npx -y grafbase schema tomhoule/schema-check-action-federated-graph-example@main --name retail
# < prints the whole GraphQL schema >
```

Without the `--name` argument, the CLI prints the composed schema of the federated graph.

Listing and inspecting

# Changelog

The Schema Registry tracks changes to your schemas and displays the changes
made to the public API of your graph in the Changelog tab of the dashboard.
This view lets you keep a concise overview of changes to your GraphQL API
schema for each deployment.

![Changelog tab in the dashboard](/images/docs/schema-registry/changelog.png)

Changelog

# Schema Registry

The Schema Registry is responsible for keeping track of published schemas and helping you evolve your APIs with [Schema Checks](../schema-checks).
You will interact with the registry through the CLI and the Grafbase dashboard.

## Managing a federated graph

In a federated graph, the schema registry is responsible for keeping track of
which subgraphs are published. The schema registry needs that knowledge to
fulfill its purposes:

- Composing the subgraph schemas into a federated graph schema.
- Assisting you in evolving these schemas individually and as a group (see
  [Schema checks](../schema-checks)).

Each branch of a federated graph has its own set of subgraphs. Each
subgraph is a live, deployed GraphQL endpoint that can be managed on Grafbase
or deployed anywhere else.

From the schema registry's perspective, each subgraph can be thought of as a
record with the following properties:

- `name`: the identifier for a subgraph within a branch. It corresponds
  to the `--name` argument in the CLI publish and check commands. The schema,
  and where the url of the subgraph can changed, but its name does not.
- `url`: the endpoint where the subgraph is deployed. It corresponds to the
  `--url` argument of the CLI publish command.
- `schema`: the GraphQL schema of the subgraph. It corresponds to the
  `--schema` argument of the cli command.

The schema registry keeps track of published subgraphs, their names, urls and
schemas. On every change, it tries to _compose_ the subgraphs together into a
federated graph.

Schema Registry

# Operation Checks

APIs evolve. Most of the time, changes are additive: a new mutation, a new field on a type, or new input objects for filtering collections, for example. These changes changes can be safely made without breaking consumers of the API.

Other changes, however, will break clients that send queries written for a previous version of the API. Common examples would be the removal of a field, or adding a required argument on a field. These changes are disruptive, because all GraphQL servers will reject invalid GraphQL queries that cannot be executed on the present version of the schema.

Operation Checks are [Schema Checks](/docs/schema-checks) that exist to help you avoid breaking clients when making changes to your GraphQL schema. Concretely, they are rules that can manifest breaking changes as errors when you run `grafbase check`.

For a change to be breaking, two criteria must be met:

- The change is theoretically breaking. See [list of breaking changes](#list-of-breaking-changes).
- The part of the schema that changed or disappeared is in use by clients.

Without the second criterion, Operation Checks would be too strict. You would not be free to iterate on any part of your schema that has ever been published, even when it is not used yet or not used anymore. Operation checks take advantage of request analytics to only take into account the actual usage of your API, and not only theoretically breaking changes.

## Configuration

Operation Checks are opt-in. They are configured in the dashboard.

![Operation Checks configuration screen](/images/docs/operation-checks-configuration-screen.png)

You can enable them for your whole graph, on only for specific branches. You can select how many queries are required to use a part of your schema for it to be used, and in which time frame.

You can exclude specific operations by name. For example, in the following GraphQL document, the operation name is "JapaneseProducts":

```graphql
query JapaneseProducts {
  products(filter: { madeIn: "JP" }) {
    id
    name
  }
}
```

Specific clients can also be excluded. The client name is identified by the value of the custom `x-grafbase-client-name` header, and self-reported by clients. You can include the client name as a regular HTTP header in your GraphQL client of choice and it will simply work.

## Running Operation Checks

As a part of schema checks, they are run whenever you use the [`grafbase check` command](/docs/schema-checks). The checks errors will point out breaking changes that would result from deploying the schema you passed to `grafbase check` to the branch you check against. The real-world client usage data is the usage data collected for the target branch.

## List of breaking changes

Below is a list of the changes considered as potentially breaking:

- Removal of a root query, mutation or subscription type.
- Removal of an object, interface or input object field.
- Removal of a field argument.
- Removal of an interface from `implements`.
- Removal of a member type in a union.
- Removal of a value of an enum.
- Addition of a nonnullable argument on a field.
- Addition of a nonnullable field on an input object.
- Change of a field's type.
  - Either change of the _inner_ type: `String` becoming `Int` for example,
  - or a change of wrapping types making the field nullable: `String!` to `String` or `[String!]` to `[String]` for example. The client would not expect null here.
- Change of a field argument's type.
  - Either change of the _inner_ type: `String` becoming `Int` for example,
  - or a change of wrapping types making the argument nonnullable: `String` to `String!` or `[String]` to `[String!]` for example. The client could be passing null.
- Removal of a field argument's default, if the argument is required.

For all of these, we check actual usage before triggering an Operation Check error.

Operation Checks

# Lint Checks

Lint checks are a layer of our schema checks suite that statically analyzes your schema and finds various issues that aren't hard compilation errors but are likely to be mistakes, oversights or behaviors you've chosen to disallow.

## Rules

- Naming conventions
  - Types: `PascalCase`
    - Forbidden prefixes: `"Type"`
    - Forbidden suffixes: `"Type"`
  - Fields: `camelCase`
  - Input values: `camelCase`
  - Arguments: `camelCase`
  - Directives: `camelCase`
  - Enums: `PascalCase`
    - Forbidden prefixes: `"Enum"`
    - Forbidden suffixes: `"Enum"`
  - Unions
    - Forbidden prefixes: `"Union"`
    - Forbidden suffixes: `"Union"`
  - Enum values: `SCREAMING_SNAKE_CASE`
  - Interfaces
    - Forbidden prefixes: `"Interface"`
    - Forbidden suffixes: `"Interface"`
  - Query fields
    - Forbidden prefixes: `["query", "get", "list"]`
    - Forbidden suffixes: `"Query"`
  - Mutation fields
    - Forbidden prefixes: `["mutation", "put", "post", "patch"]`
    - Forbidden suffixes: `"Mutation"`
  - Subscription fields
    - Forbidden prefixes: `"subscription"`
    - Forbidden suffixes: `"Subscription"`
- Usage of the `@deprecated` directive requires specifying the `reason` argument

## Where lints run

- When running schema checks in the CLI via the `grafbase check` command or viewing schema checks in the dashboard, lint checks are run if validation and composition checks pass
- The CLI `grafbase lint` command will run lint checks locally on a provided SDL schema

Lint Checks

# Schema Checks

The Schema Registry can a run a suite of checks on a schema.

In a federated graph, you can check a subgraph schema before publishing.

## CLI

Schema Checks are run with the `grafbase check` command. It takes the following arguments:

- a required [graph reference](/docs/schema-registry/publish#graph-reference) positional
  argument
- `--name`: the name of the subgraph. It is required in federated graph
  projects, and invalid in standalone graph projects.
- `--schema`: the path to the GraphQL schema file. If this argument is not
  provided, the CLI will attempt to read the schema from stdin.

On successful check, the command returns with a successful exit code (0).

If there are any check errors, the command returns with a non-zero exit code and
prints the errors. This makes the command suitable for use in scripts and CI
pipelines.

### Examples

Introspect the schema of a local graph and check it:

```bash
$ grafbase introspect --dev | grafbase check myaccount/mygraph@main --name mysubgraph
```

## Dashboard

To see past schema checks, you can visit the `Checks` tab in the
Grafbase dashboard.

![Schema Checks tab in the dashboardd](/images/docs/schema-checks/schema-checks-view.png)

## Using `grafbase check` in CI

_If you use GitHub Actions for CI, there is a pre-packaged and documented
[grafbase-schema-check action](https://github.com/marketplace/actions/grafbase-schema-check-action)
that uses the same approach as the description below._.

The command can be used in scripts. You only need to provide the same arguments
as you would interactively.

The main difference will be authentication. Instead of following the
interactive login flow with `grafbase login`, you must provide a Grafbase
access token. You can generate an access token from the dashboard:

![Access tokens view in the dashboard](/images/docs/schema-checks/access-tokens-view.png)

In Grafbase projects, `grafbase introspect --dev` command is the most
convenient way to generate the GraphQL schema file to pass to the `--schema`
argument of `grafbase check`. You can see an example in the [GitHub
workflow](https://github.com/tomhoule/grafbase-schema-check-action-single-graph-example/blob/main/.github/workflows/check.yml)
of the [example
repository](https://github.com/tomhoule/grafbase-schema-check-action-single-graph-example/tree/main)
for checks in CI. There is also a [federated graph example](https://github.com/tomhoule/grafbase-schema-check-action-federated-graph-example).

## Schema checks in more detail

When you initiate a schema check with `grafbase check`, the Schema Registry:

1. Gathers all subgraph schemas for the branch
2. Validates that each schema is a valid GraphQL schema on its own
3. Tries to compose all the subgraph schemas together, with the new version of the named subgraph that was passed to check

If any error happens in step 2. or 3., the Schema Check fails.

Schema Checks

# Deploying to AWS Lambda

The Grafbase Gateway can be deployed to the AWS Lambda platform as a serverless
function. For every release of the gateway, we provide a separate build specifically
targeting the Lambda platform. This has some differences from running
the gateway binary in a normal server environment. It is important to
choose the builds for Lambda; the normal builds will not work in the AWS
Lambda platform.

## Lambda size selection

The Grafbase Lambda Gateway uses a minimal amount of memory: the common
memory usage is below hundred megabytes. The Lambda memory setting has
an effect how much CPU is allocated for the function, so even when the
Grafbase Lambda Gateway does not need the memory, choosing a higher base
memory amount can have an effect on cold start times and general
performance.

## Lambda binary selection

The [gateway release](https://github.com/grafbase/grafbase/releases)
includes two different binaries targeted for Lambda:

- `grafbase-gateway-lambda-aarch64-unknown-linux-musl` is for Amazon
  Graviton platform, targeting the 64-bit ARM architecture.
- `grafbase-gateway-lambda-x86_64-unknown-linux-musl` targets the 64-bit
  x86 platform.

The binaries _will not work_ if deployed to a wrong CPU architecture.
The aarch64 version is a few megabytes smaller, so if Graviton is
available in your region, it can lead to faster cold starts due to the
smaller size.

The binaries targeted for common Linux deployments will not work in
Lambda, and the Lambda binaries only work either in the AWS Lambda
platform, or a specific docker image emulating the Lambda platform. The
Lambda binaries are optimized for size over runtime speed, minimizing
the cold start time to the minimum.

## Setting up Lambda for the Grafbase Lambda Gateway

The Lambda function can be configured as needed. Gateway execution
settings are handled through environment variables:

- `GRAFBASE_CONFIG_PATH` sets the path for the Grafbase configuration
  file. The default value is `./grafbase.toml`, which tries to look for
  the configuration from the Lambda root directory.
- `GRAFBASE_SCHEMA_PATH` is the path to the federated schema. The default
  value is `./federated.graphql`, again looking for the file from the
  Lambda root directory.
- `GRAFBASE_LOG` sets the log level. Allowed values: `error`, `warn`, `info`,
  `debug`, `trace` or `off`. Defaults is `info`.
- `GRAFBASE_LOG_STYLE` allows setting the style of the log messages. Either
  `text` or `json` and the default is `text`.

## Deployment

A common deployment strategy for Grafbase Lambda Gateway is to package
it together with the gateway configuration and a federated graph. In
comparison to to a full server, a Lambda function freezes if not serving any
traffic, meaning we cannot run a graph updater in the background. Therefore
after successfully publishing a new subgraph, the deployment should execute
the following steps:

- [Download](https://github.com/grafbase/grafbase/releases) the preferred
  version of the Grafbase Lambda Gateway
- Rename the binary to `bootstrap`
- Copy the
  [configuration](/docs/self-hosted-gateway#configuration) to the
  same directory
- Get the latest federated graph from the Grafbase API

A deployment should contain following files:

```bash
.
├── bootstrap
├── grafbase.toml
└── federated.graphql
```

Continue deploying in your preferred way, following the [AWS
documentation](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-package.html).

## Differences in configuration

The Grafbase Lambda Gateway is configured with the same configuration
file as the binary, with the following changes:

- The network settings are not respected. The listen address and the
  port is defined by AWS.
- Transport layer security is handled by AWS, and the settings for TLS
  in the Grafbase configuration do nothing.
- OpenTelemetry settings work almost the same, but batching has no
  effect in Lambda.
- CORS can be either set from the Gateway configuration, or from Lambda
  settings.

## OpenTelemetry

It is adviced to use the [AWS X-Ray](https://aws.amazon.com/xray/)
platform for OpenTelemetry tracing in Lambda. The Grafbase Lambda
Gateway will propagate the span IDs in the X-Ray format, and will
connect the trace from the Lambda invoking to the traces from the
Gateway.

Due to the limitation of the function sleeping if not serving any
traffic, we must flush all traces before responding to a request. This
adds to the response times, so a good practice is to run an OLPC
collector in the same datacenter as the Lambda function is running. A
good way to do this is installing the [AWS distro for OpenTelemetry
Collector](https://aws-otel.github.io/docs/setup/ec2) in Amazon Elastic
Computer Cloud. The EC2 instance should be in the same region, and in
the same virtual private network for best performance.

When the OpenTelemetry collector is functional, the Grafbase Lambda
Gateway must be configured to send the traces to the collector:

```toml
[telemetry]
service_name = "my-federated-graph"

[telemetry.tracing]
enabled = true
sampling = 1
filter = "grafbase=info,off"

[telemetry.tracing.exporters.otlp]
enabled = true
endpoint = "http://<IP>:4317"
protocol = "grpc"
timeout = 5
```

Lambda

Hooks

Telemetry

# Rate limiting

The Grafbase Gateway offers ways to limit the number of requests per time window either globally or per subgraph. You can define the limit in memory per gateway instance or utilize a Redis backend to share the limit state with multiple gateway instances.

You can set up global rate limiting to apply to every incoming request. The configuration involves two parameters: a limit to cap the number of requests allowed for a given duration.

```toml
[gateway.rate_limit.global]
limit = 1000
duration = "10s"
```

You can also define a rate limit per subgraph:

```toml
[subgraphs.products.rate_limit]
limit = 100
duration = "10s"
```

The default rate limiter uses the [generic cell rate algorithm](https://en.wikipedia.org/wiki/Generic_cell_rate_algorithm), a leaky bucket type scheduling algorithm. This method is very accurate and can limit sudden bursts of requests even if the current time window has not yet reached its limit. It is also the fastest method because the engine does not need to trigger any network requests per GraphQL operation. The rate limit data will be empty when restarting the gateway with the in-memory rate limiter.

## Using Redis for rate limiting

To run multiple gateways and share the rate limit data with all of them, configure the gateway to use Redis as the rate limiter backend.

```toml
[gateway.rate_limit]
storage = "redis"

[gateway.rate_limit.redis]
url = "redis://localhost:6379"
key_prefix = "my_gateway"
```

- **storage**: The storage to use for rate limiting. Either `memory`, the default, or `redis`, which uses the Redis algorithm.
- **url**: The Redis endpoint URL. Use `redis://` for plain text protocol, or `rediss://` if connecting with TLS (default: `redis://localhost:6379`).
- **key_prefix**: A string the rate limiter uses to prefix the counters in Redis (default: `grafbase`).

To connect using TLS, the Redis URL must start with `rediss://`. If the server CA certificate is not in the system certificates or if you want to use mTLS, define paths to these files in the TLS configuration.

```toml
[gateway.rate_limit.redis.tls]
cert = "/path/to/user.crt"
key = "/path/to/user.key"
ca = "/path/to/ca.crt"
```

- **cert**: The path to the mTLS user certificate file.
- **key**: The path to the mTLS user private key file. Must be defined together with the `cert`.
- **ca**: The path to the server CA certificate file.

All files must be in PEM format. The `cert` and `key` are not needed if the server is not set up to use mTLS. The `ca` is not needed if the certificate is added to the system certificate storage. The certificates must be of version 3 and the server must use TLS version 1.3; everything else will be rejected by the TLS library.

Using TLS with Redis increases response times, and the Redis server will be called at least once for every request. Consider placing the Redis server as close as possible to the gateway instances and not using TLS for the counters.

The Redis algorithm uses an averaging fixed window rate limiting, the fastest possible algorithm, adding about 0.4 milliseconds to the requests. The algorithm uses two Redis keys:

- `{key_prefix}:{subgraph:subgraph_name || global}:{current_time_bucket}`
- `{key_prefix}:{subgraph:subgraph_name || global}:{previous_time_bucket}`

Both keys contain a counter value stored as an integer string. The buckets will expire soon after the time window ends and will be deleted from the database. The algorithm differs from the in-memory one. We increment the counter in the current time bucket and load the previous bucket value in a single pipelined Redis request. The algorithm calculates an averaged request count with the following formula:

1. Load the value in the previous bucket.
2. Count the percentage of how far we are in the current time window.
3. Multiply the previous value with the percentage based on the percentage in the current window.
4. Add the current counter to the averaged previous value.

The averaging prevents spikes at the window border, with an accuracy of a few percent. Set the limit slightly higher than the estimated traffic to avoid false negatives.

Rate limiting

# Trusted Documents

GraphQL APIs provide clients with considerable flexibility to query any data they need. This flexibility represents one of GraphQL's major strengths, but it also introduces vulnerabilities. When any client can query any data, malicious or careless queries can create excessive load on the server. Trusted Documents solve this problem.

The concept has existed since the early days of GraphQL, using terms like _persisted queries_ or _persisted operations_. An API that uses Trusted Documents accepts only GraphQL documents (queries, operations) submitted (trusted) at development or deployment time. Instead of sending the whole document, clients send a more compact _document id_. This approach enhances security by rejecting malicious queries and improves performance by transmitting only the document id, similar to what occurs in [Automatic Persisted Queries](/docs/self-hosted-gateway/automatic-persisted-queries).

## Overview

Adopting Trusted Documents places constraints primarily on API clients. To enforce trusted documents in a Grafbase API, you simply set a single option in `grafbase.toml` (see below).

We will begin by exploring the more complex aspects of adopting Trusted Documents and then explain how to enforce them.

## Trusting Documents: Upload a Manifest

The purpose of Trusted Documents is to accept only queries on an allow-list. Start by generating and communicating that list. We call the allow-list document a **manifest**, and it takes the form of a JSON file. Your GraphQL client setup of choice creates the manifest.

The two most common setups for generating a trusted documents manifest are [Relay Persisted Queries](https://relay.dev/docs/guides/persisted-queries/#local-persisted-queries) and Apollo Client operation manifests ([JS](https://www.apollographql.com/docs/react/api/link/persisted-queries/#1-generate-operation-manifests), [Kotlin](https://www.apollographql.com/docs/kotlin/advanced/persisted-queries/), [iOS](https://www.apollographql.com/docs/ios/fetching/persisted-queries/#2-generate-operation-manifest)). Grafbase natively supports both Relay and Apollo Client manifest formats. If you need support for another setup or manifest format, please [contact us](/contact).

After you create a manifest JSON file that includes the GraphQL documents your application needs and the associated document IDs, submit the manifest using the `grafbase` CLI:

```bash
$ grafbase trust my-account/my-graph@main --manifest manifest.json --client-name ios-client
```

Let's break down the arguments:

- `grafbase trust my-account/graph-name@main`: Like many other CLI commands, `trust` requires a graph reference in the format `<account>/<graph>@<branch>`. Remember that you must include the branch name to avoid defaulting to the production branch, which can introduce security risks.
- `--manifest manifest.json`: Provide the file path to the JSON file generated by your client of choice.
- `--client-name`: Each client of an API using trusted documents must identify itself with a client name using the `x-grafbase-client-name` HTTP header. Read on for more details.

After you submit the manifest, the API trusts the GraphQL documents in the manifest, associating them with their corresponding document IDs. **The trust command applies to a single branch and a single client name**. To enforce trusted documents across multiple branches or clients, you must trust the relevant documents for each combination.

## Trusted Documents in the Client: Runtime Components

In the previous section, we uploaded the trusted document manifests. Now, our API knows which documents to expect. Our GraphQL client needs to change its requests to the API in two ways:

1. Send the `x-grafbase-client-name` header with the same name used when submitting the manifest with `grafbase trust`.
2. Send the trusted document IDs instead of the document body in GraphQL requests.

For example [in Relay](https://relay.dev/docs/guides/persisted-queries/#network-layer-changes):

```ts
function fetchQuery(operation, variables) {
  return fetch('/graphql', {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-grafbase-client-name': 'ios-app',
    },
    body: JSON.stringify({
      // `doc_id` is also accepted.
      documentId: operation.id, // NOTE: pass md5 hash to the server
      // query: operation.text, // this is now obsolete because text is null
      variables,
    }),
  }).then(response => {
    return response.json()
  })
}
```

or with [Apollo Client](https://www.apollographql.com/docs/react/api/link/persisted-queries/#persisted-queries-implementation):

```ts
import { ApolloClient, HttpLink, InMemoryCache } from '@apollo/client'
import { createPersistedQueryLink } from '@apollo/client/link/persisted-queries'
import { generatePersistedQueryIdsFromManifest } from '@apollo/persisted-query-lists'

const httpLink = new HttpLink({
  uri: 'http://localhost:4000/graphql',
  headers: {
    'x-grafbase-client-name': 'ios-app',
  },
})

const persistedQueryLink = createPersistedQueryLink(
  generatePersistedQueryIdsFromManifest({
    loadManifest: () => import('./path/to/persisted-query-manifest.json'),
  }),
)

const client = new ApolloClient({
  cache: new InMemoryCache(),
  link: persistedQueriesLink.concat(httpLink),
})
```

## Enforcing Trusted Documents with the Self-hosted Grafbase Gateway

On the server side, the process is straightforward. You will find one relevant section in `grafbase.toml`:

```toml
[trusted_documents]
enabled = true # default: false
bypass_header_name = "my-header-name" # default null
bypass_header_value = "my-secret-value" # default null
```

Let’s review the options:

- `enabled`: Set this to `true` to enable trusted documents. The gateway fetches the graph associated with a branch when it starts. The router recognizes Trusted Documents that you submit (with `grafbase trust`) for that branch only.
- `bypass_header_name` and `bypass_header_value`: If both values are not null, the router accepts arbitrary GraphQL documents whenever you pass the configured HTTP header.

Register an allow-list of GraphQL operations for security and performance

Trusted documents

# Operation Limits

One of the most common attacks malicious actors do to GraphQL APIs is sending complex and deeply nested queries to overload the server. Operation Limits allow you to protect your GraphQL API from these types of attacks.

## Depth

Limits the deepest nesting of selection sets in an operation, including fields in fragments.

Here's how depth is calculated:

```graphql
query GetProduct {
  product(id: "123") {
    # depth 1
    title # depth 2
    brand {
      name # depth 3
    }
  }
}
```

To configure depth, add the following to your `grafbase.toml` file:

```toml
[operation_limits]
depth = 3
```

## Height

Limits the number of unique fields included in an operation, including fields of fragments. If a particular field is included multiple times via aliases, it's counted only once.

Here's how height is calculated:

```graphql
query GetProduct {
  product(id: "123") {
    # height 1
    id # height 2
    name # height 3
    title: name # aliases don't count
  }
}
```

To configure height, add the following to your `grafbase.toml` file:

```toml
[operation_limits]
height = 20
```

## Aliases

Limits the total number of aliased fields in an operation, including fields of fragments.

Here's how aliases are calculated:

```graphql
query GetProduct {
  product(id: "123") {
    title: name # alias 1
    something: name # alias 2
    else: name # alias 3
  }
}
```

To configure aliases, add the following to your `grafbase.toml` file:

```toml
[operation_limits]
aliases = 10
```

## Root Fields

Limits the number of root fields in an operation, including root fields in fragments. If a particular root field is included multiple times via aliases, each usage is counted.

Here's how root fields are calculated:

```graphql
query GetProducts {
  topBooks {
    # root field 1
    id
  }
  topMovies {
    # root field 2
    id
  }
  topGames {
    # root field 3
    id
  }
}
```

To configure root fields, add the following to your `grafbase.toml` file:

```toml
[operation_limits]
root_fields = 10
```

## Complexity

Complexity takes the number of fields as well as the depth and any pagination arguments into account. Every scalar field adds 1 point, every nested field adds 2 points, and every pagination argument multiplies the nested objects score by the number of records fetched.

Here's how root fields are calculated:

```graphql
query {
  # total: 18
  products(limit: 2) {
    # (Nested: 2 + 1 + 1 + 1 + (author: 2 + 1 + 1)) * limit: 2 = 18
    id # scalar: 1
    title # scalar: 1
    price # scalar: 1
    brand {
      # nested: 4 (2 + 1 + 1)
      id # scalar: 1
      name # scalar: 1
    }
  }
}
```

To configure complexity, add the following to your `grafbase.toml` file:

```toml
[operation_limits]
complexity = 100
```

Protect your GraphQL API from attacks like complex and deeply nested queries that overload the server and/or database.

Operation limits

# Message Signatures

The Grafbase Gateway can sign subgraph HTTP requests following [RFC 9421][rfc9421].

This can be enabled globally:

```toml
[gateway.message_signatures]
enabled = true
key.file = "key.json"
```

Or only for a single subgraph:

```toml
[subgraphs.products.message_signatures]
enabled = true
key.file = "products-key.json"
```

All options documented on this page can be provided globally or for a specific
subgraph. If an option is not provided for a subgraph it will inherit from the
global configuration.

## Keys

A key file should be provided in the config. This key file should be one of:

1. A JSON file containing a JWK.
2. A PEM file containing a PKCS#8 private key.

### Key ID

A key ID will be included as a signature parameter when signing. If possible
this ID will be determined from the provided key file, but it can also be
provided with the `key.id` field:

```toml
[gateway.message_signatures]
enabled = true
key.file = "key.json"
key.id = "my-key"
```

### Algorithms

We'll choose which algorithm to use based on the key file provided, but a
specific algoithm can be provided in the `algorithm` field:

```toml
[gateway.message_signatures]
enabled = true
key.file = "key.json"
algorithm = "ed25519"
```

The available algorithms are:

- `hmac-sha256`
- `ed25519`
- `ecdsa-p256-sha256`
- `ecdsa-p384-sha384`

If the provided key & algorithm don't match the gateway will refuse to start.

The algorithm you use for singing can have an impact on the latency of your
subgraph requests. The list above is in performance order, from most
performant to least performant. We recommend testing your chosen algorithm &
settings if this is a concern - a message signing span will be output in
tracing that can be used to determine the impact of your settings.

## Controlling Signing

The Grafbase Gateway allows you to control which parts of a subgrah request are
used as input to message signing. There are several settings for this:

- The `headers` key can control which headers are included or excluded. It has
  two sub-keys:
  1. `include` should be a list of headers to include in the signature.
     If not present, all headers will be included.
  2. `exclude` should be a list of headers to exclude from the signature.
     This setting takes precedence over `include`
- The `derived_components` key allows you to control which "derived
  components" are included. This defaults to `["request_target"]`. The
  following options are available:
  - `method` the HTTP method.
  - `target_uri` the full URL of the request
  - `authority` the hostname of the requests target URL
  - `scheme` the scheme of the requests target URL
  - `request_target` the [request target](request-target) of the request.
  - `path` the absolute path of the request URL
- The `signature_parameters` key is a list of additional signature parameters
  to include. It currently only has one setting:
  - `nonce` can be provided to include a random nonce in every requests
    signature.
- `expiry` can be set to a duration string. (e.g. `"30s"` for 30 seconds). If
  provided, signatures will expire after this duration.

Here is an example of these settings:

```toml
[gateway.message_signatures]
headers.include = ["content-type", "content-length"]
derived_components = ["method", "target_uri"]
expiry = "10s"

[subgraphs.product.message_signatures]
headers.exclude = ["content-type"]
signature_parameters = ["nonce"]
expiry = "5m"
```

[rfc9421]: https://datatracker.ietf.org/doc/html/rfc9421
[request-target]: https://datatracker.ietf.org/doc/html/rfc9421#name-request-target

Enforce subgraph request integrity using HTTP message signatures

Message signatures

# Entity caching

The Grafbase Gateway offers caching on requests to subgraphs, known as entity caching.

You can enable caching globally via the `entity_caching` config section:

```toml
[entity_caching]
enabled = true
ttl = "60s"
```

You can also configure different settings per subgraph:

```toml
[subgraphs.products.entity_caching]
ttl = "60s"
```

Cached data is scoped to avoid any data leaks between users. Currently, all the headers sent
to the subgraph are used to compute the scope.

## Using Redis for entity caching

By default entity caching uses an in memory cache to store its data. To run
multiple gateways and share the cache with all of them, configure the
gateway to use Redis as the caching backend.

```toml
[entity_caching]
storage = "redis"

[entity_caching.redis]
url = "redis://localhost:6379"
key_prefix = "my_gateway"
```

- **storage**: The cache storage to use. Either `memory`, the default, or
  `redis`.
- **url**: The Redis endpoint URL. Use `redis://` for plain text protocol, or
  `rediss://` if connecting with TLS (default: `redis://localhost:6379`).
- **key_prefix**: A string the cache uses to prefix keys in Redis (default:
  `grafbase-cache`).

To connect using TLS, the Redis URL must start with `rediss://`. If the server
CA certificate is not in the system certificates or if you want to use mTLS,
define paths to these files in the TLS configuration.

```toml
[entity_caching.redis.tls]
cert = "/path/to/user.crt"
key = "/path/to/user.key"
ca = "/path/to/ca.crt"
```

- **cert**: The path to the mTLS user certificate file.
- **key**: The path to the mTLS user private key file. Must be defined together
  with the `cert`.
- **ca**: The path to the server CA certificate file.

All files must be in PEM format. The `cert` and `key` are not needed if the
server is not set up to use mTLS. The `ca` is not needed if the certificate is
added to the system certificate storage. The certificates must be of version 3
and the server must use TLS version 1.3; everything else will be rejected by
the TLS library.

Using TLS with Redis increases response times, and the Redis server will be
called at least once for every request. Consider placing the Redis server as
close as possible to the gateway instances and not using TLS for the counters.

Entity caching

# Automatic Persisted Queries

Automatic Persisted Queries let you avoid sending the query string each time and help prepare the execution. First, associate a query with a unique identifier: the SHA-256 hash of the query string:

```text
# SHA-256
4ef8d269e7944ef2cd6554ecb3d73164546945cf935806933448905abec554e5
```

```graphql
query {
  __typename
}
```

You can persist the query at any time. Send the following payload, and the system caches it for a day:

```json
{
  "query": "query { __typename }",
  "extensions": {
    "persistedQuery": {
      "version": 1,
      "sha256Hash": "4ef8d269e7944ef2cd6554ecb3d73164546945cf935806933448905abec554e5"
    }
  }
}
```

The next time you execute the same query, omit the query field as follows:

```json
{
  "extensions": {
    "persistedQuery": {
      "version": 1,
      "sha256Hash": "4ef8d269e7944ef2cd6554ecb3d73164546945cf935806933448905abec554e5"
    }
  }
}
```

If Grafbase does not find the query, it returns the following error:

```json
{
  "errors": [
    {
      "message": "Persisted query not found",
      "extensions": {
        "code": "PERSISTED_QUERY_NOT_FOUND"
      }
    }
  ]
}
```

In this case, send the request with the full query string.

## Using GET requests

Grafbase also supports executing GET HTTP requests. You must pass fields as query parameters, encoding their values in JSON format first. To execute a persisted query:

```bash
curl --get 'http://localhost:4000/graphql' \
  --data-urlencode 'extensions={"persistedQuery":{"version":1,"sha256Hash":"4ef8d269e7944ef2cd6554ecb3d73164546945cf935806933448905abec554e5"}}'
```

To register a query:

```bash
curl --get 'http://localhost:4000/graphql' \
  --data-urlencode 'query=query { __typename }' \
  --data-urlencode 'extensions={"persistedQuery":{"version":1,"sha256Hash":"4ef8d269e7944ef2cd6554ecb3d73164546945cf935806933448905abec554e5"}}'
```

Improve performance by sending smaller request payloads.

Automatic persisted queries

# Gateway request lifecycle

When you send a request to the Grafbase Gateway, it follows these steps:

1. Call the [on-gateway-request hook](/docs/self-hosted-gateway/hooks#gateway-request).
2. [Authenticate](/docs/self-hosted-gateway#authentication) the client.
3. Apply the global [rate limit](/docs/self-hosted-gateway/rate-limiting).
4. Execute the [authorization pre-hooks](/docs/self-hosted-gateway/hooks#authorization).

![Operation plan workflow](/images/docs/self-host/request-lifecycle1.png)

After this point, all subgraphs within the request are handled in parallel tasks.

1. Call the [on-subgraph-request hook](/docs/self-hosted-gateway/hooks#subgraph-request).
2. Apply the subgraph [rate limit](/docs/self-hosted-gateway/rate-limiting).
3. Request the subgraph endpoint, with possible [retries](/docs/self-hosted-gateway#subgraph-retries).

![Subgraph request workflow](/images/docs/self-host/request-lifecycle2.png)

The main thread waits for all subgraph responses, combines them, and then continues.

1. Execute the [authorization post-hooks](/docs/self-hosted-gateway/hooks#authorization).
2. Send the response to the client.

![Response collect workflow](/images/docs/self-host/request-lifecycle3.png)

Request lifecycle

# Deploy to Kubernetes

Deploying the gateway is flexible through different options tailored to diverse infrastructure needs.
Users can choose from a [multi-platform binary](https://github.com/grafbase/grafbase/releases?q=gateway), allowing for
installation directly on various operating systems, or opt for a [Docker image](https://github.com/grafbase/grafbase/pkgs/container/gateway)
that integrates seamlessly into containerized environments like Kubernetes. This flexibility enables teams to deploy
the gateway in ways that best fit their workflow, whether running on local machines, cloud platforms, or hybrid infrastructures.

## Kubernetes

Kubernetes is a popular option for container orchestration and is widely adopted for its scalability, reliability, and
powerful ecosystem. This ecosystem includes tools like Helm, which greatly simplifies the deployment and management of
Kubernetes workloads by offering a templated, versioned, and reusable configuration framework. Helm enables users to
package applications into charts, streamlining the deployment of complex workloads consistently across environments.

### Gateway Helm chart

Grafbase offers an off-the-shelf Helm chart to simplify deploying the gateway. It is hosted on the GitHub Container Registry
and adheres to [Open Container Initiative (OCI)](https://helm.sh/docs/topics/registries/). You can find the chart and its
versions in the following location:

```bash
https://ghcr.io/grafbase/helm-charts/gateway
```

## Deploying

The chart comes with a default installation configuration, allowing you to quickly get the gateway up and running with
minimal setup. This setup, although functional and easy to start with, requires fine-tuning to accommodate real use cases.

In the following steps, we will start by installing the default configuration and proceed with customizations to include
specific settings for:

1. Number of replicas
2. Auto-scaling
3. Compute resources
4. External federated schema
5. External configuration

### Setup

Before we begin deploying and customizing the deployment, ensure the following prerequisites are met:

1. _Kubernetes Cluster:_ Access to a Kubernetes cluster to deploy the gateway. If you don’t have one available, you can
   set up a local cluster (e.g: [kind](https://kind.sigs.k8s.io/)).
2. _helm:_ Should be installed. Get started [here](https://helm.sh/docs/intro/quickstart/).
3. _kubectl:_ Should be installed and pointing to the intended cluster. Get started [here](https://kubernetes.io/docs/tasks/tools/#kubectl).

### Basic deployment

To get started with running the gateway we can simply do the following:

```bash
helm install test oci://ghcr.io/grafbase/helm-charts/gateway --version <version>
```

Once the above complete, verify the gateway is running doing:

```bash
kubectl get pods
```

If everything went accordingly, you should see a pod running with the name `test-gateway`.

### Customize deployment

Now that we have a running a gateway, lets leverage a Helm [values file](https://helm.sh/docs/chart_template_guide/values_files/)
to customize the deployment to our needs.

```yaml
# 1. number of desired replicas running
replicaCount: 2

# 2. auto-scaling behaviour
autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 70

# 3. compute resources
resources:
  limits:
    cpu: 2
    memory: 2Gi
  requests:
    cpu: 1
    memory: 1Gi

# 4. and 5. External schema and configuration from cluster configmaps
gateway:
  externalConfig: true
  externalSchema: true
  args:
    - --config
    - /etc/grafbase/config/config.toml
    - --schema
    - /etc/grafbase/schema/schema.sdl
volumes:
  - name: configuration
    configMap:
      name: grafbase-gateway-configuration
  - name: schema
    configMap:
      name: grafbase-gateway-schema
volumeMounts:
  - name: configuration
    mountPath: /etc/grafbase/config
  - name: schema
    mountPath: /etc/grafbase/schema
```

The above will:

1. Instruct the deployment to always keep 2 replicas of the gateway running
2. Configure auto-scaling to a minimum of 2 instances and maximum 10, scaling upwards when the deployment experiences 70% of cpu or memory usage across all running replicas.
3. Configure each running replica with at least 1CPU and 1GB of memory with ability to scale up a max of 2CPU and 2GB of memory.
4. Leverage existing cluster configmaps with the desired gateway configuration and federated schema. These are mounted on each running replica, in the configured paths, and made available via arguments when executing the gateway binary.

In order to view all values that can be customized, run the following command:

```bash
helm show values oci://ghcr.io/grafbase/helm-charts/gateway --version <version>
```

In order to reflect our desired customization, we should upgrade our running deployment. Store the customization in a file
and run the following:

```
helm upgrade test oci://ghcr.io/grafbase/helm-charts/gateway --version <version> -f custom-values.yaml
```

Lets verify our deployment using helm:

```bash
helm list

kubectl get pods
```

Kubernetes

# Self-hosted Gateway

The Grafbase Gateway allows you to run a federated graph within your own infrastructure. The gateway operates by either polling the latest graph from the Grafbase API or by passing the federated schema, enabling air-gapped operation.

## Installation

To install the Grafbase Gateway, run the following command:

```bash
curl -fsSL https://grafbase.com/downloads/gateway | bash
```

## Hybrid operation

In hybrid mode, the gateway fetches the current federated graph from the Grafbase platform. Create a federated graph in the Grafbase API, publish the subgraphs, and the gateway will always have the current graph running.

Start the gateway in hybrid mode with the graph reference and an organization access token:

```bash
GRAFBASE_ACCESS_TOKEN=token ./grafbase-gateway \
  --config grafbase.toml \
  --graph-ref graph@branch
```

`graph-ref` points to a graph created in the Grafbase API and its branch. If the branch is empty, the gateway uses the production branch by default.

Create the organization access token in the account settings under "Access Tokens" and ensure it has permission to read the graph.

The gateway polls for graph changes every ten seconds.

## Air-gapped operation

In air-gapped mode, the gateway never calls the Grafbase API. You must provide the federated graph SDL as a file.

Start the gateway in self-hosted mode:

```bash
./grafbase-gateway \
  --config /path/to/grafbase.toml \
  --schema /path/to/federated-schema.graphql \
  --listen-address 127.0.0.1:4000
```

## Configuration

Define the configuration using the TOML file format.

The gateway loads the configuration at startup, and you can hot-reload parts of it during runtime with the `--hot-reload` flag. The gateway polls for configuration changes every two seconds when provided a path to the configuration file.

### Graph configuration

```toml
[graph]
path = "/graphql"
introspection = false
```

- `path`: The URL path where the GraphQL API is available. Defaults to `/graphql`.
- `introspection`: Enables or disables GraphQL introspection. Defaults to `false`.

### Network configuration

```toml
[network]
listen_address = "127.0.0.1:5000"
```

- `listen_address`: The address to bind to. Defaults to `127.0.0.1:5000`. Can be set in the configuration or via the command line interface using the `--listen-address` argument.

### Gateway configuration

Set gateway server settings in this section:

```toml
[gateway]
timeout = "30s"
subgraph_timeout = "4s"
```

- `timeout`: Timeout for slow requests and responses. Default: `30s`.
- `subgraph_timeout`: A global timeout for all subgraph requests. A subgraph [can override](#subgraph-configuration) this setting.

#### Rate Limiting

Read more about [rate limiting](/docs/self-hosted-gateway/rate-limiting).

```toml
[gateway.rate_limit.global]
limit = 100
duration = "10s"
```

You can hot-reload the subgraph rate limit and duration settings.

Read more about [rate limit specific for a subgraph](#subgraph-rate-limit).

#### Query Batching

The Grafbase Gateway requires configuration to enable query batching. Be aware that a large batch of queries can trigger a denial of service attack on the subgraph service or the gateway itself.

```toml
[gateway.batching]
enabled = true
limit = 5
```

- `enabled`: Enables query batching. Defaults to `false`.
- `limit`: The maximum number of queries in a batch. If not set, the gateway does not limit the number of queries in a batch.

#### Retries

The retry configuration lets you define how a failing subgraph request gets handled. The subgraph request can fail if the subgraph service times out, returns an error code, or the rate limit is reached.

```toml
[gateway.retry]
enabled = true
min_per_second = 10
ttl = "1s"
retry_percent = 0.1
retry_mutations = false
```

The retries are based on a budget logic. Each successful request to the subgraph stores a deposit to the budget, and each failing request withdraws from the budget.

- `enabled`: Enables retries for the given subgraph. Defaults to `false`.
- `min_per_second`: How many retries are available per second, at a minimum. Defaults to `10`.
- `ttl`: Each successful request to the subgraph adds to the retry budget. This setting controls how long the budget remembers successful requests. Defaults to `10s`.
- `retry_percent`: The fraction of the successful requests budget that can be used for retries. Defaults to `0.2`.
- `retry_mutations`: Whether mutations should be retried at all. Enable this setting only if mutations are idempotent. Defaults to `false`.

If you enable subgraph retries, they will execute with an exponential backoff. The first retry occurs after 100 milliseconds, the second after 200 milliseconds, the third after 400 milliseconds, and so on. The engine will add jitter to the times to prevent the thundering herd problem of having too many requests reaching the subgraph at once. A jitter multiplier between 0.0 to 2.0 is added to the retry backoff.

Read more on [retries specific for a subgraph](#subgraph-retries).

#### Access Logs

Read more about [access logs](/docs/self-hosted-gateway/hooks#access-logs-with-response-hooks) to implement the required hooks.

```toml
[gateway.access_logs]
enabled = true
path = "/path/to/logs"
rotate = "daily"
mode = "blocking"
```

- `enabled`: Enables the access log writer.
- `path`: Specifies the log directory.
- `rotate`: Defines a rotation strategy, after which a new log file is created, and the previous one gets archived; options include `never`, `minutely`, `hourly`, or `daily`.
- `rotate.size`: Defines a size-based rotation strategy. The value is in bytes; the log file rotates when it reaches or exceeds this limit.
- `mode`: Specifies how the system behaves when the log queue is full and the writer can't write to the file quickly enough. Options include `blocking`, which blocks the caller, or `non_blocking`, which returns an error while sending the data back to the caller.

The current log filename will be `access.log`, saved to the specified path. If you enable rotation, the current log file is `access.log`, and archived files will include a timestamp suffix. The timestamp is from the moment the logger started writing to the file.

### Cross-Site Request Forgery Prevention

Enable CSRF protection if the graph is accessible over the internet with a browser.

If enabled, you must provide a special header `x-grafbase-csrf-protection: 1` in every request not `OPTIONS`. The server returns `403 Forbidden` if the header is not found.

```toml
[csrf]
enabled = true
```

- `enabled`: Enables CSRF protection. Defaults to `false`.

### Cross-Origin Resource Sharing

Configure CORS to prevent unauthorized browser requests.

```toml
[cors]
allow_credentials = false
allow_origins = ["https://app.grafbase.com"]
max_age = "60s"
allow_methods = ["GET", "POST"]
allow_headers = ["Content-Type"]
expose_headers = ["Access-Control-Allow-Origin"]
allow_private_network = false
```

- `allow_credentials`: Enables or disables credential sending. Defaults to `false`.
- `allow_origins`: List of allowed domains or “any”. Defaults to no domains if CORS is enabled.
- `max_age`: Duration for caching preflight `OPTIONS` request results. Default: none.
- `allow_methods`: List of allowed HTTP methods or “any”. Defaults to none if CORS is enabled.
- `allow_headers`: List of allowed headers or “any”. Defaults to no headers if CORS is enabled.
- `expose_headers`: Headers a preflight request can return to the client. Default: no headers if CORS is enabled.
- `allow_private_network`: Allows private network requests. Defaults to `false`.

### Transport Layer Security

```toml
[tls]
certificate = "/path/to/cert.pem"
key = "/path/to/key.pem"
```

The gateway can serve HTTPS traffic without a reverse proxy. If no `tls` section is defined, the server operates in plain HTTP mode.

- `certificate`: Path to the certificate file in PEM format.
- `key`: Path to the private key file in PEM format.

### Operation Limits

```toml
[operation_limits]
depth = 10
height = 12
aliases = 5
root_fields = 6
complexity = 2
```

Read more about [Operation Limits](/docs/self-hosted-gateway/operation-limits).

### Trusted Documents

```toml
[trusted_documents]
enabled = true
bypass_header_name = "my-header-name"
bypass_header_value = "my-secret-value"
```

Read more about [Trusted Documents](/docs/self-hosted-gateway/trusted-documents).

### Authentication

The gateway supports JWT authentication, configurable through the TOML file:

```toml
[authentication.providers.jwt]
name = "my-authenticator"

[authentication.providers.jwt.jwks]
url = "https://example.com/.well-known/jwks.json"
issuer = "example.com"
audience = "my-project"
poll_interval = 60

[authentication.providers.jwt.header]
name = "Authorization"
value_prefix = "Bearer "
```

Read more about [Federated Authorization](/docs/federation/auth).

### Global Header Configuration

Define headers as rules executed in order. Use `forward`, `insert`, `rename_duplicate` or `remove` to manage headers sent to subgraphs:

```toml
[[headers]]
rule = "forward"
name = "authorization"

[[headers]]
rule = "forward"
name = "x-custom-header"
rename = "y-custom-header"

[[headers]]
rule = "forward"
name = "x-possible-empty"
default = "default-value"
```

You can forward multiple headers using a [regular expression](https://docs.rs/regex/latest/regex/#syntax).

The headers the engine is matching against are in lowercase, so either write the regular expression all in lowercase, or [provide a flag](https://docs.rs/regex/latest/regex/#grouping-and-flags) in the expression to match lower and uppercase letters.

```toml
[[headers]]
rule = "forward"
pattern = "^x-custom*"
```

Insert header values with the `insert` rule:

```toml
[[headers]]
rule = "insert"
name = "authorization"
value = "Bearer secret-token"
```

You can insert headers values from environment variables:

```toml
[[headers]]
rule = "insert"
name = "authorization"
value = "Bearer {{ env.AUTHORIZATION_TOKEN }}"
```

Use the `remove` rule to prevent forwarding of selected headers when using patterns:

```toml
[[headers]]
rule = "remove"
name = "x-custom-secret"
```

The `rename_duplicate` rule is to forward the defined header value and a copy of the value with the given rename to the subgraphs.

```toml
[[headers]]
rule = "rename_duplicate"
name = "x-custom-value"
default = "the value was missing"
rename = "y-custom-value"
```

This will forward two headers to the subgraph, both with the same value. One with the name `x-custom-value` and the other with the name `y-custom-value`. If the header `x-custom-value` is missing in the request, by defining the `default` the gateway will create two headers with the given default. If the default is omitted, the gateway will not forward the header or create a duplicate.

<CardWidget>

The following headers cannot be controlled through header rules:

- `Accept`
- `Accept-Charset`
- `Accept-Encoding`
- `Accept-Ranges`
- `Connection`
- `Content-Length`
- `Content-Type`
- `Keep-Alive`
- `Proxy-Authenticate`
- `Proxy-Authorization`
- `TE`
- `Trailer`
- `Transfer-Encoding`
- `Upgrade`

</CardWidget>

Read more on [subgraph header rules](#subgraph-header-rules).

### Health Checks

Enable the gateway to expose a health check endpoint:

```toml
[health]
enabled = true
listen = "0.0.0.0:9668"
path = "/health"
```

- `enabled`: Whether to expose the health check endpoint. Defaults to `true`.
- `path`: The request path for the endpoint. Defaults to `"/health"`.
- `listen`: Address and port to bind for health requests. If omitted, uses the main GraphQL endpoint's socket and port.

The health check endpoint returns a status code 200 with with a body of `{"status": "healthy"}` when the gateway is in a healthy state. It will reply with a status code 503 when it can determine that the gateway is not healthy.

The TLS configuration from `tls` in your configuration also applies to the health check endpoint.

## Subgraph Configuration

You can define settings per subgraph. These settings will either add to or override the global settings.

Define per-subgraph options such as the WebSocket URL and timeouts:

```toml
[subgraphs.products]
websocket_url = "https://example.com/"
timeout = "4s"
```

### Subgraph URL Override

You can override the URL for a subgraph. If set, the gateway will use the provided URL instead of the one from the schema registry.

```toml
[subgraphs.products]
url = "https://example.com/graphql"
```

### Subgraph Header Rules

Define header rules per subgraph. They execute after the global rules.

```toml
[[subgraphs.products.headers]]
rule = "forward"
name = "content-type"
```

Read more on [global header rules](#global-header-configuration).

### Subgraph Rate Limit

You can define rate limit per subgraph, which is checked before issuing a request. Read more about [rate limiting](/docs/self-hosted-gateway/rate-limiting).

```toml
[subgraphs.products.rate_limit]
limit = 100
duration = "10s"
```

You can hot-reload the subgraph rate limit and duration settings.

A rate limit [global rate limit](#gateway-configuration).

### Subgraph Retries

You can override the retry budget for the specific subgraph.

```toml
[subgraphs.products.retry]
enabled = true
min_per_second = 10
ttl = "1s"
retry_percent = 0.1
retry_mutations = false
```

Read more about [retries](#gateway-configuration).

## Internal Operation

The server is written in Rust and consists of several components:

- `axum` web server
- Tokio runtime for async operations, running one worker per CPU core
- Rustls for encryption, backed by the ring and BoringTLS libraries
- Reqwest HTTP client, using Hyper and Rustls for encryption

In hybrid mode, the gateway validates the access token and fetches the latest federated graph from the CDN every ten seconds. It updates the graph and replaces the GraphQL engine as needed.

## Run Grafbase Gateway Using a Container Image

Example `compose.yaml`:

```yaml
version: '3'
services:
  grafbase:
    image: ghcr.io/grafbase/gateway:latest
    restart: always
    volumes:
      - ./grafbase.toml:/etc/grafbase.toml
    environment:
      GRAFBASE_GRAPH_REF: 'graph-ref@branch'
      GRAFBASE_ACCESS_TOKEN: 'ACCESS_TOKEN_HERE'
    ports:
      - '5000:5000'
```

Host federated graphs in your own infrastructure

Self-hosted Gateway

# Documentation

Grafbase is the easiest way to manage large scale federated graphs.

Compose your unified GraphQL API from multiple subgraphs in just a few minutes with the Grafbase CLI.

## Get Started

Start building your federated graph in a few easy steps.

<CardGridWidget
  items={[
    {
      title: 'Federation',
      subtitle: 'Get started building your first federated graph.',
      href: '/docs/federation',
    },
    {
      title: 'Schema Registry',
      subtitle: 'Learn how the schema registry works and how to use it.',
      href: '/docs/schema-registry',
    },
    {
      title: 'Schema Checks',
      subtitle:
        'Run a suite of checks on your schema to avoid breaking changes.',
      href: '/docs/schema-checks',
    },
    {
      title: 'Self-hosted Gateway',
      subtitle: 'Get started with Grafbase using a pre-built schema blueprint.',
      href: '/docs/self-hosted-gateway',
    },
  ]}
/>

HTTP Status code	Description
400	Ill-formed GraphQL-over-http request ex: invalid JSON
401	Unauthenticated
406	Missing or unsupported `Accept` header
429	Rate limited
500	Internal server error

Error Code	Description	HTTP status code
BAD_REQUEST	Bad request	400
TRUSTED_DOCUMENT_ERROR	Trusted document could not be loaded or doesn't exist	400
PERSISTED_QUERY_ERROR	Automatic persisted query failed	400
PERSISTED_QUERY_NOT_FOUND	Automatic persisted query was not found and must be provided	400
OPERATION_PARSING_ERROR	Operation parsing failed	400
OPERATION_VALIDATION_ERROR	Operation validation failed	400
OPERATION_PLANNING_ERROR	Operation planning failed	400
UNAUTHENTICATED	User is not authenticated	401
UNAUTHORIZED	User is not authorized	403
RATE_LIMITED	Request was rate limited	429
INTERNAL_SERVER_ERROR	Internal server error	500
HOOK_ERROR	Hook failed or returned an error	500
SUBGRAPH_ERROR	GraphQL error coming from the subgraph	502
SUBGRAPH_INVALID_RESPONSE_ERROR	Subgraph returned an invalid response	502
SUBGRAPH_REQUEST_ERROR	Request to the subgraph failed	502
GATEWAY_TIMEOUT	Request execeed the global timeout	504