# 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

# Federation use cases

This page is intended as a complement to the [subgraph directives reference](/docs/federation/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/federation-directives#key) directive.

## Migrate fields between subgraphs

The [@override](/docs/federation/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/federation-directives#authenticated) and [@requiresScopes](/docs/federation/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/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

# Federated 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.

Currently, we only support JWT provider which validates JWT tokens.

## JWT Authorization

JWT authorization can be configured with as little as the following:

```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.

Control access to your federated graph by configuring an auth provider.

Federated Authorization

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

Errors

# Federation directives

Subgraphs are regular GraphQL APIs. 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.

Federation directives

# Federation

Grafbase supports GraphQL 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/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/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/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 can be used in two contexts: with a deployed
schema registry and in the [local development](../development) workflow. In
this page, we will concentrate on the regular workflow that interacts with the
Grafbase API.

The `grabfase 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](../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](../../schema-checks) are there to verify that publishing
your new or updated schema is safe.

Publishing a subgraph

# Composition in the Schema Registry

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

# Local development

The Grafbase dev server can act as a schema registry.

This is useful for experimenting with a few subgraphs or, if you can run all
your services locally, replicate a whole production deployment.

To start it, run `grafbase dev` in a federated graph project. This will start a
local schema registry that waits for subgraphs to be published with the
`grafbase publish --dev` command.

Whenever a subgraph is published, the dev server will compose it with the other
published subgraphs and serve the resulting federated API.

Local development

# 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
Grafbase federated graph and helping you evolve your APIs with [Schema Checks](../schema-checks).
You will interact with it through the CLI and the web 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

### In a federated graph

When you create 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.

### In a standalone graph

When you create a Schema Check with `grafbase check`, the Schema Registry
validates that the provided GraphQL schema is valid GraphQL so that it can be
deployed. More checks will follow in the near future.

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

# Logging and OpenTelemetry in the Grafbase Gateway

The Grafbase Gateway provides logs, traces, and metrics for monitoring gateway operations and errors. By default, it outputs logs to standard output. Additionally, the gateway can send monitoring data to an endpoint that implements the [OpenTelemetry](https://opentelemetry.io/) protocols.

## Level of Produced Information

You can define the level of information by setting the log level command line argument:

```
--log <LOG_LEVEL>
    Set the logging level, this applies to all spans, logs and trace events.

    Beware that *only* 'off', 'error', 'warn' and 'info' can be used safely in
    production. More verbose levels, such as 'debug', will include sensitive
    information like request variables, responses, etc.

    Possible values are: 'off', 'error', 'warn', 'info', 'debug', 'trace' or a
    custom string. In the last case, the string is passed on to
    [`tracing_subscriber::EnvFilter`] as is and is only meant for debugging
    purposes. No stability guarantee is made on the format.

    [env: GRAFBASE_LOG=]
    [default: info]
```

This setting affects both traces and logs. The default level is `info`. `debug` and `trace` will include sensitive details and should not be used in production.

If you want to silence all logs but still export them along with traces and metrics to an OpenTelemetry endpoint, direct standard output and standard error to `/dev/null`.

## Logs

By default, the system outputs logs to standard output. Logs can appear in two different formats:

```
--log-style <LOG_STYLE>
    Set the style of log output

    [env: GRAFBASE_LOG_STYLE=]
    [default: pretty]

    Possible values:
    - pretty: Pretty printed logs, used as the default in the terminal
    - text:   Standard text, used as the default when piping stdout to a file
    - json: JSON objects
```

The default style is `pretty`, inside a terminal, which provides ANSI-colored text for terminal output and a human-friendly formatting. When piping to a file, `text` will be used instead.The `json` format delivers logs in JSON format, which can be useful if the logging platform supports structured data.

Logs can also be sent to an OpenTelemetry endpoint by enabling the OpenTelemetry exporter in the configuration:

```toml
[telemetry.exporters.otlp]
enabled = true
endpoint = "http://localhost:1234"
```

You can send logs to a different endpoint than the global OpenTelemetry settings:

```toml
[telemetry.logs.exporters.otlp]
enabled = true
endpoint = "http://localhost:1235"
```

Read more about OpenTelemetry options in the [configuration section](#opentelemetry-configuration).

## Traces

Traces provide information on the request lifecycle and send data to the OpenTelemetry endpoint from the `info` level. You can define some important settings for traces:

```toml
[telemetry.tracing]
sampling = 1
parent_based_sampler = false
```

The `sampling` setting defines the percentage (a floating point from 0 to 1) of requests traced. For testing purposes or with low traffic, set this to `1`. If you expect high traffic, sampling every request can become expensive in terms of network, CPU, and storage. The default value is `0.15`, which samples 15% of all requests.

The `parent_based_sampler` option enables the [parent based sampler](https://opentelemetry.io/docs/specs/otel/trace/tracestate-probability-sampling/#parent-based-sampler) mechanism. When this is enabled, the gateway will look at the request headers to make trace sampling decisions, and fall back to its default sampling strategy when the request does not specify a sampling strategy. It is disabled by default, and should only be enabled if you control all the clients, as malicious actors could create more load by manipulating sampling.

The `collect` options define limits per span:

```toml
[telemetry.tracing.collect]
max_events_per_span = 128
max_attributes_per_span = 128
max_links_per_span = 128
max_attributes_per_event = 128
max_attributes_per_link = 128
```

- `max_events_per_span`: Maximum number of events recorded per span (default: `128`)
- `max_attributes_per_span`: Maximum number of attributes recorded per span (default: `128`)
- `max_links_per_span`: Maximum number of links recorded per span (default: `128`)
- `max_attributes_per_event`: Maximum number of attributes one event can have (default: `128`)
- `max_attributes_per_link`: Maximum number of attributes one link can have (default: `128`)

The `propagation` options define how tracing context (trace id, parent span id and extra context) are propagated, both when the router receives it in requests, and when it passes it down to subgraphs. Multiple common standards are supported. If you need support for additional formats, please contact us.

```toml
[telemetry.tracing.propagation]
trace_context = true
baggage = true
aws_xray = false
```

- `trace_context`: Enable [TraceContext](https://www.w3.org/TR/trace-context/) propagation through the `traceparent` header. This is the standard trace parent propagation mechanism in OpenTelemetry. Default: false.
- `baggage`: Enable [Baggage](https://opentelemetry.io/docs/concepts/signals/baggage/) context propagation through the `baggage` header. This is the standard context propagation mechanism in OpenTelemetry. Default: false.
- `aws_xray`: Enable [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader) propagation through the `x-amzn-trace-id` header. This is the builtin trace propagation mechanism in AWS X-Ray.

Traces can send to an OpenTelemetry endpoint by enabling the OpenTelemetry exporter in the configuration:

```toml
[telemetry.exporters.otlp]
enabled = true
endpoint = "http://localhost:1234"
```

You can also send traces to a different endpoint:

```toml
[telemetry.tracing.exporters.otlp]
enabled = true
endpoint = "http://localhost:1235"
```

Read more about OpenTelemetry options in the [configuration section](#opentelemetry-configuration).

Enable spans to write directly to standard output by turning on the global stdout exporter, which helps during evaluation and debugging:

```toml
[telemetry.exporters.stdout]
enabled = true
```

You can enable it only for tracing as well:

```toml
[telemetry.tracing.exporters.stdout]
enabled = true
```

## Metrics

The Grafbase Gateway delivers metrics for requests and operations to an OpenTelemetry endpoint. Metrics include counters, histograms, and gauges at various points in the system.

### Configuration

Enable the OpenTelemetry exporter in the configuration to send metrics to an OpenTelemetry endpoint:

```toml
[telemetry.exporters.otlp]
enabled = true
endpoint = "http://localhost:1234"
```

You can send metrics to a separate endpoint as well:

```toml
[telemetry.metrics.exporters.otlp]
enabled = true
endpoint = "http://localhost:1235"
```

Read more about OpenTelemetry options in the [configuration section](#opentelemetry-configuration).

You can also write spans directly to standard output by enabling the global stdout exporter for evaluation and debugging:

```toml
[telemetry.exporters.stdout]
enabled = true
```

Enable it only for metrics if needed:

```toml
[telemetry.metrics.exporters.stdout]
enabled = true
```

### Histograms as Counters

The exponential histograms include a `Count` field, which doubles any histogram as a counter metric. If you can't find a specific counter, check if any of the histograms can serve that purpose.

### HTTP Request Duration

**Metric Name:** `http.server.request.duration`

This exponential histogram measures the time in milliseconds for each HTTP request and helps you track the final response time for those requests. It includes the following attributes:

- `http.response.status_code`: The HTTP status code.
- `http.request.method`: The HTTP request method.
- `http.route`: The request path.
- `network.protocol.version`: The HTTP version of the request.
- `server.address`: The server's listen address.
- `server.port`: The server's listen port.
- `url.scheme`: Either `http` or `https`, depending on whether TLS is enabled in the gateway.
- `http.headers.x-grafbase-client-name`: The name of the client that triggered this request, if available.
- `http.headers.x-grafbase-client-version`: The version of the client that triggered this request, if available.
- `graphql.response.status`: Indicates whether the underlying GraphQL operation succeeded, if available.

### Connected Clients

**Metric Name:** `http.server.connected.clients`

This up/down counter tracks currently connected clients, incrementing on an incoming request and decrementing upon any response.

### Request Body Sizes

**Metric Name:** `http.server.request.body.size`

This exponential histogram measures request body sizes.

### Response Body Sizes

**Metric Name:** `http.server.response.body.size`

This exponential histogram measures response body sizes.

### GraphQL Operation Duration

**Metric Name:** `graphql.operation.duration`

This exponential histogram measures the time in milliseconds for every valid operation in the GraphQL engine. The metric includes the following attributes:

- `graphql.document`: The normalized query of this operation, stripped of all variables. This value cannot contain any private data.
- `graphql.operation.type`: The type of the operation (either `query`, `mutation`, or `subscription`).
- `graphql.operation.name`: The name of the operation, if provided.
- `graphql.response.status`: Indicates if the response succeeded.
- `http.headers.x-grafbase-client-name`: The name of the client that triggered this request, if available.
- `http.headers.x-grafbase-client-version`: The version of the client that triggered this request, if available.

### GraphQL Operation Errors

**Metric Name:** `graphql.operation.errors`

This counter tracks distinct GraphQL errors per request. The metric contains the following attributes:

- `graphql.response.error.code`: The error code returned to the user.
- `graphql.operation.name`: The name of the operation, if present.
- `http.headers.x-grafbase-client-name`: The name of the client, if present.
- `http.headers.x-grafbase-client-version`: The version of the client, if present.

### Request Batch Sizes

**Metric Name:** `graphql.operation.batch.size`

This exponential histogram measures the number of batched requests sent to the engine. It counts the total number of batched requests while measuring the number of requests in the batch.

### Subgraph Request Duration

**Metric Name:** `graphql.subgraph.request.duration`

This exponential histogram measures the time in milliseconds for every subgraph request. It helps track execution time and includes the following attributes:

- `graphql.subgraph.name`: The requested subgraph's name.
- `graphql.subgraph.response.status`: Indicates if the response succeeded.
- `http.response.status_code`: The HTTP status code.

### Subgraph Retries

**Metric Name:** `graphql.subgraph.request.retries`

This counter tracks retried subgraph requests. To enable this counter, you must [enable retries](/docs/self-hosted-gateway#gateway-configuration). The counter increments when a subgraph request fails and the engine retries it. The metric includes the following attributes:

- `graphql.subgraph.name`: The requested subgraph's name.
- `graphql.subgraph.aborted`: Indicates if the retries stopped and if the request became an error.

### Subgraph Request Sizes

**Metric Name:** `graphql.subgraph.request.body.size`

This exponential histogram measures subgraph request body sizes in bytes. The metric includes the following attribute:

- `graphql.subgraph.name`: The requested subgraph's name.

### Subgraph Response Sizes

**Metric Name:** `graphql.subgraph.response.body.size`

This exponential histogram measures successful subgraph response body sizes in bytes. The metric includes the following attribute:

- `graphql.subgraph.name`: The requested subgraph's name.

### Subgraph In-Flight Requests

**Metric Name:** `graphql.subgraph.request.inflight`

This up/down counter tracks in-flight subgraph requests. It increments when requesting a subgraph and decrements upon any response. The metric includes the following attribute:

- `graphql.subgraph.name`: The requested subgraph's name.

### Subgraph Cache Hits

**Metric Name:** `graphql.subgraph.request.cache.hit`

This counter tracks hits of subgraph entity caches. Enable this counter by [activating entity caching](/docs/self-hosted-gateway/entity-caching). The metric includes the following attribute:

- `graphql.subgraph.name`: The requested subgraph's name.

### Subgraph Cache Misses

**Metric Name:** `graphql.subgraph.request.cache.miss`

This counter tracks misses of subgraph entity caches. Enable this counter by [activating entity caching](/docs/self-hosted-gateway/entity-caching). The metric includes the following attribute:

- `graphql.subgraph.name`: The requested subgraph's name.

### Operation Cache Hits

**Metric Name:** `graphql.operation.cache.hit`

This counter tracks hits for operation plan caches.

### Operation Cache Misses

**Metric Name:** `graphql.operation.cache.miss`

This counter tracks misses for operation plan caches.

### Operation Preparation Duration

**Metric Name:** `graphql.operation.prepare.duration`

This exponential histogram measures the time in milliseconds taken to prepare an operation. This includes:

- Fetching a trusted document, if enabled and available.
- Fetching a query plan from the in-memory cache.
- If the plan is not cached, parsing the query into an AST and then determining the plan.

The metric includes the following attributes:

- `graphql.operation.name`: The name of the operation, if present.
- `graphql.document`: The normalized operation if parsing succeeds.
- `graphql.operation.success`: Indicates if the preparation finished successfully.

### Hook Duration

**Metric Name:** `grafbase.hook.duration`

This exponential histogram measures the time in milliseconds taken to execute a [hook](/docs/self-hosted-gateway/hooks). The metric includes the following attributes:

- `grafbase.name.hook`: The name of the hook function.
- `grafbase.hook.status`: Indicates if the hook call succeeded (`SUCCESS`), or if it failed due to errors from Grafbase code (`HOST_ERROR`), or from user code (`GUEST_ERROR`).

### Pending Access Logs

**Metric Name:** `grafbase.gateway.access_log.pending`

This counter measures the amount of access log events not yet written to the access log file. [Read more](/docs/self-hosted-gateway/hooks#access-logs-with-response-hooks) on access logs.

### Rate-Limit Duration

**Metric Name:** `grafbase.gateway.rate_limit.duration`

This exponential histogram measures the time in milliseconds taken to query the current request rate from Redis. This metric requires enabling the [Redis-based rate-limiting](/docs/self-hosted-gateway/rate-limiting#using-redis-for-rate-limiting).

### Graph Delivery Network Fetch Duration

**Metric Name:** `gdn.request.duration`

This exponential histogram measures the time in milliseconds to fetch a graph from the Graph Delivery Network. This metric only activates in [hybrid mode](/docs/self-hosted-gateway#hybrid-operation). The metric includes the following attributes:

- `server.address`: The Graph Delivery Network endpoint URL.
- `gdn.response.kind`: The response status kind, either `new`, `unchanged`, `http_error`, or `gdn_error`.
- `http.response.status_code`: The status code of the request.

## OpenTelemetry Configuration

Define OpenTelemetry settings in the `telemetry` block of your Gateway configuration:

```toml
[telemetry]
service_name = "grafbase-gateway"
```

The `service_name` appears in all traces, metrics, and logs and should be unique in your system.

Grafbase sends a standard set of resource attributes for every user. You can also define your own attributes, available in all logs, traces, and metrics:

```toml
[telemetry.resource_attributes]
custom_key = "custom_value"
other_key = "other_value"
```

### Global Exporters

You can define exporter settings globally for traces, logs, and metrics. If you need different settings for logs, tracing, or metrics, prefix the exporter settings with the appropriate word. For instance, custom settings for tracing use the key `telemetry.tracing.exporters.otlp`.

The traces and metrics can also be sent to standard output (logs will always be there):

```toml
[telemetry.exporters.stdout]
enabled = true
timeout = 60
```

- `enabled`: Enables the OpenTelemetry exporter (default: `false`).
- `timeout`: Time in seconds data remains in memory if the collector does not collect it promptly (default: `60`).

Send traces, metrics, and logs to an external OpenTelemetry collector:

```toml
[telemetry.exporters.otlp]
enabled = true
endpoint = "http://localhost:1234"
protocol = "grpc"
timeout = 60
```

- `enabled`: Enables the OpenTelemetry exporter (default: `false`).
- `endpoint`: Defines the URL for the OpenTelemetry collector.
- `protocol`: Either `grpc` or `http` (default: `grpc`).
- `timeout`: Time in seconds data remains in memory if the collector does not collect it promptly (default: `60`).

#### Batch Exporting

Avoid triggering a request for every single span, trace, and metric event. Instead, batch requests and send data at regular intervals. Configure the OpenTelemetry batch settings:

```toml
[telemetry.exporters.otlp.batch_export]
scheduled_delay = 5
max_queue_size = 2048
max_export_batch_size = 512
max_concurrent_exports = 1
```

- `scheduled_delay`: Time in seconds between consecutive requests (default: `5`).
- `max_queue_size`: Maximum queued items for delayed processing. If the queue fills, the system drops events (default: `2048`).
- `max_export_batch_size`: Maximum number of events in a single batch. If more events are collected before the scheduled delay, it queues them (default: `512`).
- `max_concurrent_exports`: Number of concurrent senders processing batches (default: `1`).

#### gRPC Settings

If using `grpc` as the `protocol`, the Gateway will use the following settings.

For collectors using TLS with a custom certificate, specify the TLS settings:

```toml
[telemetry.exporters.otlp.grpc.tls]
domain_name = "custom_name"
key = "/path/to/key.pem"
cert = "/path/to/cert.pem"
ca = "/path/to/ca.crt"
```

- `domain_name`: The domain name against which to verify the server's TLS certificate.
- `key`: Path to the secret key.
- `cert`: Path to the X509 certificate file in PEM format.
- `ca`: Path to the X509 CA certificate file in PEM format.

If needed, define custom headers for gRPC collectors:

```toml
[[telemetry.exporters.otlp.grpc.headers]]
authorization = "Bearer {{ env.GRPC_TOKEN }}"

[[telemetry.exporters.otlp.grpc.headers]]
custom = "static value"
```

#### HTTP Settings

If you set the `protocol` to `http`, the Gateway will use the following settings. Define custom headers to send with every request:

```toml
[[telemetry.exporters.otlp.http.headers]]
authorization = "Bearer {{ env.GRPC_TOKEN }}"

[[telemetry.exporters.otlp.http.headers]]
custom = "static value"
```

Currently, the `http` exporter does not support TLS. If you need TLS, use the `grpc` exporter.

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

# 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

# Self-hosted Gateway

Host federated graphs on your own infrastructure.

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

## Installation

To install the Grafbase Gateway, run the following command in your terminal:

```
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:

```
./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 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 `docker-compose.yml`:

```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 build and deploy federated GraphQL APIs.

Compose your unified graph 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',
    },
  ]}
/>