Enforcing Operation Limits in the GraphOS Router

Set constraints on depth, height, aliases, and root fields

Want to learn about graph security in-person?

Don't miss the Securing your graph: A defense-in-depth strategy workshop at this year's GraphQL Summit.

This feature is only available with a GraphOS Enterprise plan.
You can test it out by signing up for a free Enterprise trial.

You can define operation limits in your router's configuration to reject potentially malicious requests. An operation that exceeds any specified limit is rejected (unless you run your router in warn_only mode).

Setup

To use operation limits, you must run v1.17 or later of the GraphOS Router. Download the latest version.

You define operation limits in your router's YAML config file, like so:

router.yaml

1
limits:
2
  max_depth: 100
3
  max_height: 200
4
  max_aliases: 30
5
  max_root_fields: 20
6

7
  # Uncomment to enable warn_only mode
8
  # warn_only: true

Each limit takes an integer value. You can define any combination of supported limits.

Supported limits

`max_depth`

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

The GetBook operation below has depth three:

1
query GetBook {
2
  book { # Depth 1 (root field)
3
    ...bookDetails
4
  }
5
}
6

7
fragment bookDetails on Book {
8
  details { # Depth 2 (nested under `book`)
9
    ... on ProductDetailsBook {
10
      country # Depth 3 (nested under `details`)
11
    }
12
  }
13
}

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

The GetUser operation below has height three:

1
query GetUser {
2
  user { # 1
3
    id   # 2
4
    name # 3
5
    username: name # Aliased duplicate (not counted)
6
  }
7
}

Each unique field increments an operation's height by one, regardless of that field's return type (scalar, object, or list).

`max_aliases`

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

The GetUser operation below includes three aliases:

1
query GetUser {
2
  user {
3
    nickname: name # 1
4
    username: name # 2
5
    handle: name   # 3
6
  }
7
}

Each aliased field increments the alias count by one, regardless of that field's return type (scalar, object, or list).

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

The following operation includes three root fields:

1
query GetTopProducts {
2
  topBooks { # 1
3
    id
4
  }
5
  topMovies { # 2
6
    id
7
  }
8
  topGames { # 3
9
    id
10
  }
11
}

`warn_only` mode

If you run your router in warn_only mode, operations that exceed defined limits are not rejected. Instead, the router processes these operations as usual and emits a WARN trace that notes all exceeded limits, like so:

1
2023-03-15T19:08:23.123456Z WARN apollo_router::operation_limits: max_depth exceeded, max_depth: 3, current_op_depth: 5, operation: "query GetOwnerLocation {cat {owner {location {postalCode}}}}"

Running in warn_only mode can be useful while you're testing to determine the most appropriate limits to set for your supergraph.

You can enable or disable warn_only mode in your router's YAML config file, like so:

router.yaml

1
limits:
2
  warn_only: true # warn_only mode always enabled

Response format for exceeded limits

Whenever your router rejects a request because it exceeds an operation limit, the router responds with a 400 HTTP status code and a standard GraphQL error response body:

1
# HTTP 400
2
{
3
  "data": {},
4
  "errors": [
5
    {
6
      "message": "Maximum height (field count) limit exceeded in this operation",
7
      "extensions": {
8
        "code": "MAX_HEIGHT_LIMIT"
9
      }
10
    }
11
  ]
12
}

If you run your router in warn_only mode, the router logs the limit violation but executes the operation as normal, returning a 200 status code with the expected response.

Using telemetry to set operation limits

Router telemetry can help you set operation limits, especially when you have a large number of existing operations. You can measure incoming operations over a fixed duration, then use the captured data as a baseline configuration.

Logging values

To log limit information about every operation, you can configure the router with a custom event to log the values of aliases, depth, height, and root_fields for each operation:

router.yaml

1
telemetry:
2
  instrumentation:
3
    events:
4
      supergraph:
5
        OPERATION_LIMIT_INFO:
6
          message: operation limit info
7
          on: response
8
          level: info
9
          attributes:
10
            graphql.operation.name: true
11
            query.aliases:
12
              query: aliases
13
            query.depth:
14
              query: depth
15
            query.height:
16
              query: height
17
            query.root_fields:
18
              query: root_fields

ⓘ NOTE

For a large amount of traffic, you may prefer to collect and export metrics to your APM instead.

Collecting metrics

To capture and view metrics to help set your operation limits, you can configure the router to collect custom metrics on the values of aliases, depth, height, and root_fields for each operation:

router.yaml

1
telemetry:
2
  exporters:
3
    metrics:
4
      common:
5
        views:
6
          # Define a custom view because operation limits are different than the default latency-oriented view of OpenTelemetry
7
          - name: oplimits.*
8
            aggregation:
9
              histogram:
10
                buckets:
11
                  - 0
12
                  - 5
13
                  - 10
14
                  - 25
15
                  - 50
16
                  - 100
17
                  - 500
18
                  - 1000
19
  instrumentation:
20
    instruments:
21
      supergraph:
22
        oplimits.aliases:
23
          value:
24
            query: aliases
25
          type: histogram
26
          unit: number
27
          description: "Aliases for an operation"
28
        oplimits.depth:
29
          value:
30
            query: depth
31
          type: histogram
32
          unit: number
33
          description: "Depth for an operation"
34
        oplimits.height:
35
          value:
36
            query: height
37
          type: histogram
38
          unit: number
39
          description: "Height for an operation"
40
        oplimits.root_fields:
41
          value:
42
            query: root_fields
43
          type: histogram
44
          unit: number
45
          description: "Root fields for an operation"

You should also configure the router to export metrics to your APM tool.

Subgraph Authentication

Safelisting with Persisted Queries