Skip to content

README.md

Latest commit

 

History

History
3444 lines (2478 loc) · 112 KB

README.md

File metadata and controls

3444 lines (2478 loc) · 112 KB
Raw

HiveRouterConfig

Properties

Name Type Description Required
authorization object Default: {"directives":{"enabled":true,"unauthorized":{"mode":"filter"}}}
 yes
cors object Configuration for CORS (Cross-Origin Resource Sharing).
Default: {"allow_any_origin":false,"allow_credentials":false,"enabled":false,"policies":[]}
 yes
csrf object Configuration for CSRF prevention.
Default: {"enabled":false,"required_headers":[]}
headers object Configuration for the headers.
Default: {}
http object Configuration for the HTTP server/listener.
Default: {"graphql_endpoint":"/graphql","host":"0.0.0.0","port":4000}
introspection Configuration to enable or disable introspection queries.
jwt object Configuration for JWT authentication plugin.
 yes
laboratory object Configuration for the Hive Laboratory interface.
Default: {"enabled":true}
limits object Configuration for checking the limits such as query depth, complexity, etc.
Default: {"max_request_body_size":"2 MB"}
log object The router logger configuration.
Default: {"filter":null,"format":"json","level":"info"}
override_labels object Configuration for overriding labels.
override_subgraph_urls object Configuration for overriding subgraph URLs.
Default: {}
persisted_documents object Configuration for persisted documents extraction and resolution.
Default: {"enabled":false,"log_missing_id":false,"require_id":false,"selectors":null,"storage":null}
plugins object Configuration for custom plugins
query_planner object Query planning configuration.
Default: {"allow_expose":false,"timeout":"10s"}
subscriptions object Configuration for subscriptions.
Default: {"broadcast_capacity":0,"enabled":false}
supergraph object Configuration for the Federation supergraph source. By default, the router will use a local file-based supergraph source (./supergraph.graphql).
telemetry object Default: {"client_identification":{"name_header":"graphql-client-name","version_header":"graphql-client-version"},"hive":null,"metrics":{"exporters":[],"instrumentation":{"common":{"histogram":{"aggregation":"explicit","bytes":{"buckets":[128,512,1024,2048,4096,8192,16384,32768,65536,131072,262144,524288,1048576,2097152,3145728,4194304,5242880],"record_min_max":false},"seconds":{"buckets":[0.005,0.01,0.025,0.05,0.075,0.1,0.25,0.5,0.75,1,2.5,5,7.5,10],"record_min_max":false}}},"instruments":{}}},"resource":{"attributes":{}},"tracing":{"collect":{"max_attributes_per_event":16,"max_attributes_per_link":32,"max_attributes_per_span":128,"max_events_per_span":128,"parent_based_sampler":false,"sampling":1},"exporters":[],"instrumentation":{"spans":{"mode":"spec_compliant"}},"propagation":{"b3":false,"baggage":false,"jaeger":false,"trace_context":true}}}
traffic_shaping object Configuration for the traffic-shaping of the executor. Use these configurations to control how requests are being executed to subgraphs.
Default: {"all":{"allow_only_http2":false,"circuit_breaker":null,"dedupe_enabled":true,"pool_idle_timeout":"50s","request_timeout":"30s"},"max_connections_per_host":100,"router":{"dedupe":{"enabled":false,"headers":"all"},"max_long_lived_clients":128,"request_timeout":"1m"}}
websocket object Configuration of router's WebSocket server.
Default: {"enabled":false,"headers":{"persist":false,"source":"connection"},"path":null}

Additional Properties: not allowed
Example

authorization:
  directives:
    enabled: true
    unauthorized:
      mode: filter
cors:
  allow_any_origin: false
  allow_credentials: false
  enabled: true
  max_age: 120
  methods:
    - GET
    - POST
    - OPTIONS
  policies:
    - origins:
        - https://example.com
        - https://another.com
csrf:
  enabled: true
  required_headers:
    - x-csrf-token
headers:
  all:
    request:
      - propagate:
          named: Authorization
      - remove:
          matching: ^x-legacy-.*
      - insert:
          name: x-router
          value: hive-router
  subgraphs:
    accounts:
      request:
        - propagate:
            default: unknown
            named: x-tenant-id
            rename: x-acct-tenant
http:
  graphql_endpoint: /graphql
  host: 0.0.0.0
  port: 4000
jwt:
  allowed_algorithms:
    - HS256
    - HS384
    - HS512
    - RS256
    - RS384
    - RS512
    - ES256
    - ES384
    - PS256
    - PS384
    - PS512
    - EdDSA
  enabled: false
  forward_claims_to_upstream_extensions:
    enabled: false
    field_name: jwt
  lookup_locations:
    - name: authorization
      prefix: Bearer
      source: header
laboratory:
  enabled: true
limits:
  max_request_body_size: 2 MB
log:
  filter: null
  format: json
  level: info
override_labels: {}
override_subgraph_urls:
  accounts:
    url: https://accounts.example.com/graphql
  products:
    url:
      expression: |2-

                if .request.headers."x-region" == "us-east" {
                    "https://products-us-east.example.com/graphql"
                } else if .request.headers."x-region" == "eu-west" {
                    "https://products-eu-west.example.com/graphql"
                } else {
                  .default
                }
            
persisted_documents:
  enabled: false
  log_missing_id: false
  require_id: false
  selectors: null
  storage: null
plugins: {}
query_planner:
  allow_expose: false
  timeout: 10s
subscriptions:
  broadcast_capacity: 0
  enabled: false
supergraph: {}
telemetry:
  client_identification:
    name_header: graphql-client-name
    version_header: graphql-client-version
  hive: null
  metrics:
    exporters: []
    instrumentation:
      common:
        histogram:
          aggregation: explicit
          bytes:
            buckets:
              - 128
              - 512
              - 1024
              - 2048
              - 4096
              - 8192
              - 16384
              - 32768
              - 65536
              - 131072
              - 262144
              - 524288
              - 1048576
              - 2097152
              - 3145728
              - 4194304
              - 5242880
            record_min_max: false
          seconds:
            buckets:
              - 0.005
              - 0.01
              - 0.025
              - 0.05
              - 0.075
              - 0.1
              - 0.25
              - 0.5
              - 0.75
              - 1
              - 2.5
              - 5
              - 7.5
              - 10
            record_min_max: false
      instruments: {}
  resource:
    attributes: {}
  tracing:
    collect:
      max_attributes_per_event: 16
      max_attributes_per_link: 32
      max_attributes_per_span: 128
      max_events_per_span: 128
      parent_based_sampler: false
      sampling: 1
    exporters: []
    instrumentation:
      spans:
        mode: spec_compliant
    propagation:
      b3: false
      baggage: false
      jaeger: false
      trace_context: true
traffic_shaping:
  all:
    allow_only_http2: false
    circuit_breaker: null
    dedupe_enabled: true
    pool_idle_timeout: 50s
    request_timeout: 30s
  max_connections_per_host: 100
  router:
    dedupe:
      enabled: false
      headers: all
    max_long_lived_clients: 128
    request_timeout: 1m
websocket:
  enabled: false
  headers:
    persist: false
    source: connection
  path: null

authorization: object

Properties

Name Type Description Required
directives object yes

Additional Properties: not allowed
Example

directives:
  enabled: true
  unauthorized:
    mode: filter

authorization.directives: object

Properties

Name Type Description Required
enabled boolean Default: true
unauthorized object Default: {"mode":"filter"}

Additional Properties: not allowed
Example

enabled: true
unauthorized:
  mode: filter

authorization.directives.unauthorized: object

Properties

Name Type Description Required
mode string Default: "filter"
Enum: "filter", "reject"

Additional Properties: not allowed
Example

mode: filter

cors: object

Configuration for CORS (Cross-Origin Resource Sharing).

Properties

Name Type Description Required
allow_any_origin boolean Set to true to allow any origin. If true, the origins and match_origin fields are ignored.
Default: false
 no
allow_credentials boolean Set to true to allow credentials (cookies, authorization headers, or TLS client certificates) in cross-origin requests.
This will set the Access-Control-Allow-Credentials header to true.
Default: false
 no
allow_headers string[] List of headers that the server allows the client to send in a cross-origin request.
 no
enabled boolean Default: false
 no
expose_headers string[] List of headers that the client is allowed to access from the response.
 no
max_age integer, null The maximum time (in seconds) that the results of a preflight request can be cached by the client.
This will set the Access-Control-Max-Age header.
If not set, the browser will not cache the preflight response.
Example: 86400 (24 hours)
Format: "uint64"
Minimum: 0
 no
methods string[] List of methods that the server allows for cross-origin requests.
 no
policies object[] List of CORS policies. The first policy that matches the request origin will be applied.
 yes

Example

allow_any_origin: false
allow_credentials: false
enabled: true
max_age: 120
methods:
  - GET
  - POST
  - OPTIONS
policies:
  - origins:
      - https://example.com
      - https://another.com

Example

allow_any_origin: true
allow_credentials: false
enabled: true
policies: []

cors.allow_headers[]: array,null

List of headers that the server allows the client to send in a cross-origin request. This will set the Access-Control-Allow-Headers header. If not set, the server will reflect the headers specified in the Access-Control-Request-Headers request header. Example: ["Content-Type", "Authorization"]

Items

Item Type: string

cors.expose_headers[]: array,null

List of headers that the client is allowed to access from the response. This will set the Access-Control-Expose-Headers header. If not set, no additional headers are exposed to the client. Example: ["X-Custom-Header", "X-Another-Header"]

Items

Item Type: string

cors.methods[]: array,null

List of methods that the server allows for cross-origin requests. This will set the Access-Control-Allow-Methods header. If not set, the server will reflect the method specified in the Access-Control-Request-Method request header. Example: ["GET", "POST", "OPTIONS"]

Items

Item Type: string

cors.policies[]: array

List of CORS policies. The first policy that matches the request origin will be applied. If no policies match, the request will be rejected. If allow_any_origin is true, this field is ignored. This allows you to define different CORS settings for different origins. For example, you might want to allow credentials for some origins but not others. If multiple policies match, the first one in the list will be applied.

Example:

allow_credentials: false
policies:
  - match_origin: ["^https://.*\.credentials-example\.com$"]
    allow_credentials: true
  - match_origin: ["^https://.*\.example\.com$"]

In this example, requests from any subdomain of credentials-example.com will be allowed to include credentials, while requests from any subdomain of example.com will not be allowed to include credentials. Requests from origins not matching either pattern will be rejected.

Policy Inheritance Rules

Each policy defined in the policies array can provide its own CORS settings. If a setting is not specified within a policy, the corresponding global CORS setting is used as a fallback.

Here's a breakdown of how inheritance works for each field:

  • allow_credentials and max_age: If a policy omits a value for these settings, it automatically uses the value from the global configuration.
  • allow_headers and expose_headers: A policy's behavior for these header lists depends on the value provided:
    • If a list with specific headers is provided (e.g., ["Content-Type"]), it completely overrides the global list.
    • If an empty list ([]) is provided, the policy will inherit the headers from the global configuration.
  • methods: This setting has three distinct states for inheritance:
    • If methods is not specified at all (null), the policy inherits the global methods.
    • If an empty list ([]) is provided, no methods are allowed for that policy.
    • If the list contains specific methods (e.g., ["GET", "POST"]), only those methods are used, overriding the global list.

Items

Item Properties

Name Type Description Required
allow_credentials boolean, null Set to true to allow credentials (cookies, authorization headers, or TLS client certificates) in cross-origin requests.
This will set the Access-Control-Allow-Credentials header to true.
allow_headers string[] List of headers that the server allows the client to send in a cross-origin request.
expose_headers string[] List of headers that the client is allowed to access from the response.
match_origin string[] List of regex patterns to match allowed origins. If allow_any_origin is true, this field is ignored.
max_age integer, null The maximum time (in seconds) that the results of a preflight request can be cached by the client.
This will set the Access-Control-Max-Age header.
If not set, the browser will not cache the preflight response.
Example: 86400 (24 hours)
Format: "uint64"
Minimum: 0
methods string[] List of methods that the server allows for cross-origin requests.
origins string[] List of allowed origins. If allow_any_origin is true, this field is ignored.

Example

- {}

cors.policies[].allow_headers[]: array,null

List of headers that the server allows the client to send in a cross-origin request. This will set the Access-Control-Allow-Headers header. If not set, the server will reflect the headers specified in the Access-Control-Request-Headers request header. Example: ["Content-Type", "Authorization"]

Items

Item Type: string

cors.policies[].expose_headers[]: array,null

List of headers that the client is allowed to access from the response. This will set the Access-Control-Expose-Headers header. If not set, no additional headers are exposed to the client. Example: ["X-Custom-Header", "X-Another-Header"]

Items

Item Type: string

cors.policies[].match_origin[]: array,null

List of regex patterns to match allowed origins. If allow_any_origin is true, this field is ignored. If both origins and match_origin are set, the request origin must match one of the values in either list to be allowed. Each pattern should be a valid regex. Example: "^https://.*.example.com$", "^http://localhost:\d+$"

Items

Item Type: string

cors.policies[].methods[]: array,null

List of methods that the server allows for cross-origin requests. This will set the Access-Control-Allow-Methods header. If not set, the server will reflect the method specified in the Access-Control-Request-Method request header. Example: ["GET", "POST", "OPTIONS"]

Items

Item Type: string

cors.policies[].origins[]: array,null

List of allowed origins. If allow_any_origin is true, this field is ignored. If both origins and match_origin are set, the request origin must match one of the values in either list to be allowed. An origin is a combination of scheme, host, and port (if specified). Example: "https://example.com", "http://localhost:3000"

Items

Item Type: string

csrf: object

Configuration for CSRF prevention.

Properties

Name Type Description Required
enabled boolean Enables CSRF prevention.

By enabling CSRF prevention, the router will check for the presence of specific headers in incoming requests to the /graphql endpoint.
If the required headers are not present, the router will reject the request with a 403 Forbidden response.
This triggers the preflight checks in browsers, preventing the request from being sent.
So you can ensure that only requests from trusted origins are processed.

When CSRF prevention is enabled, the router only executes operations if one of the following conditions is true;

- The incoming request includes a Content-Type header other than a value of
- text/plain
- application/x-www-form-urlencoded
- multipart/form-data

- The incoming request includes at least one of the headers specified in the required_headers configuration.
Default: true
required_headers string[] A list of required header names for CSRF protection.
Default:

Example

enabled: true
required_headers:
  - x-csrf-token

csrf.required_headers[]: array

A list of required header names for CSRF protection.

Header names are case-insensitive.

Items

A valid HTTP header name, according to RFC 7230.

Item Type: string
Item Pattern: ^[A-Za-z0-9!#$%&'*+\-.^_\|~]+$`

headers: object

Configuration for the headers.

Properties

Name Type Description Required
all object, null Rules applied to all subgraphs (global defaults).
subgraphs object, null Rules applied to individual subgraphs.

Example

all:
  request:
    - propagate:
        named: Authorization
    - remove:
        matching: ^x-legacy-.*
    - insert:
        name: x-router
        value: hive-router
subgraphs:
  accounts:
    request:
      - propagate:
          default: unknown
          named: x-tenant-id
          rename: x-acct-tenant

headers.all: object,null

Rules applied to all subgraphs (global defaults).

Properties

Name Type Description Required
request array Rules that shape the request sent from the router to subgraphs.
response array Rules that shape the response sent from the router back to the client.

headers.all.request[]: array,null

Rules that shape the request sent from the router to subgraphs.

Items

Request-header rules (applied before sending to a subgraph).

 
Option 1 (alternative): Forward headers from the client request into the subgraph request.

  • If rename is set, the header is forwarded under the new name.
  • If none of the matched headers exist, default is used (when provided).

Order matters: You can propagate first and then remove or insert to refine the final output.

Properties

Name Type Description Required
propagate object Propagate headers from the client request to subgraph requests.
 yes

Additional Properties: not allowed
Example

propagate: {}

 
Option 2 (alternative): Remove headers before sending the request to a subgraph.

Useful to drop sensitive or irrelevant headers, or to undo a previous propagate/insert.

Properties

Name Type Description Required
remove object Remove headers matched by the specification.
 yes

Additional Properties: not allowed
Example

remove: {}

 
Option 3 (alternative): Add or overwrite a header with a static value.

  • For normal headers: replaces any existing value.
  • For never-join headers (e.g. set-cookie): appends another occurrence (multiple lines), never comma-joins.

Properties

Name Type Description Required
insert object Insert a header with a static value.
 yes

Additional Properties: not allowed
Example

insert: {}

Option 1: propagate: object

Propagate headers from the client request to subgraph requests.

Behavior

  • If rename is provided, forwarded under that name.
  • If none of the matched headers are present, default (when present) is used under rename (if set) or the first named header.

Examples

# Forward a specific header, but rename it per subgraph
propagate:
  named: x-tenant-id
  rename: x-acct-tenant

# Forward all x- headers except legacy ones
propagate:
  matching: "^x-.*"
  exclude: ["^x-legacy-.*"]

# If Authorization is missing, inject a default token for this subgraph
propagate:
  named: Authorization
  default: "Bearer test-token"

Properties

Name Type Description Required
default string, null If the header is missing, set a default value.
Applied only when none of the matched headers exist.
exclude string[] Exclude headers matching these regexes, applied after matching.
matching Match headers by regex pattern(s) (OR).
named Match headers by exact name (OR).
rename string, null Optionally rename the header when forwarding.

Option 1: propagate.exclude[]: array,null

Exclude headers matching these regexes, applied after matching.

Items

Item Type: string

Option 2: remove: object

Remove headers matched by the specification.

Properties

Name Type Description Required
exclude string[] Exclude headers matching these regexes, applied after matching.
matching Match headers by regex pattern(s) (OR).
named Match headers by exact name (OR).

Option 2: remove.exclude[]: array,null

Exclude headers matching these regexes, applied after matching.

Items

Item Type: string

Option 3: insert: object

Insert a header with a static value.

Examples

- insert:
    name: x-env
    value: prod
- insert:
    name: set-cookie
    value: "a=1; Path=/"
# If another Set-Cookie exists, this creates another header line (never joined)

Properties

Name Type Description Required
name string Header name to insert or overwrite (case-insensitive).
 yes

 
Option 1 (optional): Static value provided in the config.

Properties

Name Type Description Required
value string yes

 
Option 2 (optional): A dynamic value computed by a VRL expression.

This allows you to generate header values based on the incoming request, subgraph name, and (for response rules) subgraph response headers. The expression has access to a context object with .request, .subgraph, and .response fields.

For more information on the available functions and syntax, see the VRL documentation.

Example

# Insert a header with a value derived from another header.
- insert:
    name: x-auth-scheme
    expression: 'split(.request.headers.authorization, " ")[0] ?? "none"'

Properties

Name Type Description Required
expression string yes

headers.all.response[]: array,null

Rules that shape the response sent from the router back to the client.

Items

Response-header rules (applied before sending back to the client).

 
Option 1 (alternative): Forward headers from subgraph responses into the final client response.

  • If multiple subgraphs provide the same header, algorithm controls how values are merged.
  • If no subgraph provides a matching header, default is used (when provided).
  • If rename is set, the header is returned under the new name.

Never-join headers (e.g. set-cookie) are never comma-joined: multiple values are returned as separate header fields regardless of algorithm.

Properties

Name Type Description Required
propagate object Propagate headers from subgraph responses to the final client response.
 yes

Additional Properties: not allowed
Example

propagate: {}

 
Option 2 (alternative): Remove headers before sending the response to the client.

Properties

Name Type Description Required
remove object Remove headers matched by the specification.
 yes

Additional Properties: not allowed
Example

remove: {}

 
Option 3 (alternative): Add or overwrite a header in the response to the client.

For never-join headers, appends another occurrence (multiple lines).

Properties

Name Type Description Required
insert object Insert a header with a static value.
 yes

Additional Properties: not allowed
Example

insert: {}

Option 1: propagate: object

Propagate headers from subgraph responses to the final client response.

Behavior

  • If multiple subgraphs return the header, values are merged using algorithm. Never-join headers are never comma-joined.
  • If no subgraph returns a match, default (if set) is emitted.
  • If rename is set, the outgoing header uses the new name.

Examples

# Forward Cache-Control from whichever subgraph supplies it (last wins)
propagate:
  named: Cache-Control
  algorithm: last

# Combine list-valued headers
propagate:
  named: vary
  algorithm: append

# Ensure a fallback header is always present
propagate:
  named: x-backend
  algorithm: append
  default: unknown

Properties

Name Type Description Required
algorithm How to merge values across multiple subgraph responses.
 yes
default string, null If no subgraph returns the header, set this default value.
 no
exclude string[] Exclude headers matching these regexes, applied after matching.
 no
matching Match headers by regex pattern(s) (OR).
 no
named Match headers by exact name (OR).
 no
rename string, null Optionally rename the header when returning it to the client.
 no

Option 1: propagate.exclude[]: array,null

Exclude headers matching these regexes, applied after matching.

Items

Item Type: string

Option 2: remove: object

Remove headers matched by the specification.

Properties

Name Type Description Required
exclude string[] Exclude headers matching these regexes, applied after matching.
matching Match headers by regex pattern(s) (OR).
named Match headers by exact name (OR).

Option 2: remove.exclude[]: array,null

Exclude headers matching these regexes, applied after matching.

Items

Item Type: string

Option 3: insert: object

Insert a header with a static value.

Examples

- insert:
    name: x-env
    value: prod
- insert:
    name: set-cookie
    value: "a=1; Path=/"
# If another Set-Cookie exists, this creates another header line (never joined)

Properties

Name Type Description Required
algorithm How to merge values across multiple subgraph responses.
Default: Last (overwrite).
 no
name string Header name to insert or overwrite (case-insensitive).
 yes

 
Option 1 (optional): Static value provided in the config.

Properties

Name Type Description Required
value string yes

 
Option 2 (optional): A dynamic value computed by a VRL expression.

This allows you to generate header values based on the incoming request, subgraph name, and (for response rules) subgraph response headers. The expression has access to a context object with .request, .subgraph, and .response fields.

For more information on the available functions and syntax, see the VRL documentation.

Example

# Insert a header with a value derived from another header.
- insert:
    name: x-auth-scheme
    expression: 'split(.request.headers.authorization, " ")[0] ?? "none"'

Properties

Name Type Description Required
expression string yes

headers.subgraphs: object,null

Rules applied to individual subgraphs. Keys are subgraph names as defined in the supergraph schema.

Precedence: These are applied after all, and therefore can override the result of global rules for that subgraph.

Additional Properties

Name Type Description Required
Additional Properties object Rules for a single scope (global or per-subgraph).

headers.subgraphs.additionalProperties: object

Rules for a single scope (global or per-subgraph).

You can specify independent rule lists for request (to subgraphs) and response (to clients). Within each list, rules are applied in order.

Properties

Name Type Description Required
request array Rules that shape the request sent from the router to subgraphs.
response array Rules that shape the response sent from the router back to the client.

headers.subgraphs.additionalProperties.request[]: array,null

Rules that shape the request sent from the router to subgraphs.

Items

Request-header rules (applied before sending to a subgraph).

 
Option 1 (alternative): Forward headers from the client request into the subgraph request.

  • If rename is set, the header is forwarded under the new name.
  • If none of the matched headers exist, default is used (when provided).

Order matters: You can propagate first and then remove or insert to refine the final output.

Properties

Name Type Description Required
propagate object Propagate headers from the client request to subgraph requests.
 yes

Additional Properties: not allowed
Example

propagate: {}

 
Option 2 (alternative): Remove headers before sending the request to a subgraph.

Useful to drop sensitive or irrelevant headers, or to undo a previous propagate/insert.

Properties

Name Type Description Required
remove object Remove headers matched by the specification.
 yes

Additional Properties: not allowed
Example

remove: {}

 
Option 3 (alternative): Add or overwrite a header with a static value.

  • For normal headers: replaces any existing value.
  • For never-join headers (e.g. set-cookie): appends another occurrence (multiple lines), never comma-joins.

Properties

Name Type Description Required
insert object Insert a header with a static value.
 yes

Additional Properties: not allowed
Example

insert: {}

Option 1: propagate: object

Propagate headers from the client request to subgraph requests.

Behavior

  • If rename is provided, forwarded under that name.
  • If none of the matched headers are present, default (when present) is used under rename (if set) or the first named header.

Examples

# Forward a specific header, but rename it per subgraph
propagate:
  named: x-tenant-id
  rename: x-acct-tenant

# Forward all x- headers except legacy ones
propagate:
  matching: "^x-.*"
  exclude: ["^x-legacy-.*"]

# If Authorization is missing, inject a default token for this subgraph
propagate:
  named: Authorization
  default: "Bearer test-token"

Properties

Name Type Description Required
default string, null If the header is missing, set a default value.
Applied only when none of the matched headers exist.
exclude string[] Exclude headers matching these regexes, applied after matching.
matching Match headers by regex pattern(s) (OR).
named Match headers by exact name (OR).
rename string, null Optionally rename the header when forwarding.

Option 1: propagate.exclude[]: array,null

Exclude headers matching these regexes, applied after matching.

Items

Item Type: string

Option 2: remove: object

Remove headers matched by the specification.

Properties

Name Type Description Required
exclude string[] Exclude headers matching these regexes, applied after matching.
matching Match headers by regex pattern(s) (OR).
named Match headers by exact name (OR).

Option 2: remove.exclude[]: array,null

Exclude headers matching these regexes, applied after matching.

Items

Item Type: string

Option 3: insert: object

Insert a header with a static value.

Examples

- insert:
    name: x-env
    value: prod
- insert:
    name: set-cookie
    value: "a=1; Path=/"
# If another Set-Cookie exists, this creates another header line (never joined)

Properties

Name Type Description Required
name string Header name to insert or overwrite (case-insensitive).
 yes

 
Option 1 (optional): Static value provided in the config.

Properties

Name Type Description Required
value string yes

 
Option 2 (optional): A dynamic value computed by a VRL expression.

This allows you to generate header values based on the incoming request, subgraph name, and (for response rules) subgraph response headers. The expression has access to a context object with .request, .subgraph, and .response fields.

For more information on the available functions and syntax, see the VRL documentation.

Example

# Insert a header with a value derived from another header.
- insert:
    name: x-auth-scheme
    expression: 'split(.request.headers.authorization, " ")[0] ?? "none"'

Properties

Name Type Description Required
expression string yes

headers.subgraphs.additionalProperties.response[]: array,null

Rules that shape the response sent from the router back to the client.

Items

Response-header rules (applied before sending back to the client).

 
Option 1 (alternative): Forward headers from subgraph responses into the final client response.

  • If multiple subgraphs provide the same header, algorithm controls how values are merged.
  • If no subgraph provides a matching header, default is used (when provided).
  • If rename is set, the header is returned under the new name.

Never-join headers (e.g. set-cookie) are never comma-joined: multiple values are returned as separate header fields regardless of algorithm.

Properties

Name Type Description Required
propagate object Propagate headers from subgraph responses to the final client response.
 yes

Additional Properties: not allowed
Example

propagate: {}

 
Option 2 (alternative): Remove headers before sending the response to the client.

Properties

Name Type Description Required
remove object Remove headers matched by the specification.
 yes

Additional Properties: not allowed
Example

remove: {}

 
Option 3 (alternative): Add or overwrite a header in the response to the client.

For never-join headers, appends another occurrence (multiple lines).

Properties

Name Type Description Required
insert object Insert a header with a static value.
 yes

Additional Properties: not allowed
Example

insert: {}

Option 1: propagate: object

Propagate headers from subgraph responses to the final client response.

Behavior

  • If multiple subgraphs return the header, values are merged using algorithm. Never-join headers are never comma-joined.
  • If no subgraph returns a match, default (if set) is emitted.
  • If rename is set, the outgoing header uses the new name.

Examples

# Forward Cache-Control from whichever subgraph supplies it (last wins)
propagate:
  named: Cache-Control
  algorithm: last

# Combine list-valued headers
propagate:
  named: vary
  algorithm: append

# Ensure a fallback header is always present
propagate:
  named: x-backend
  algorithm: append
  default: unknown

Properties

Name Type Description Required
algorithm How to merge values across multiple subgraph responses.
 yes
default string, null If no subgraph returns the header, set this default value.
 no
exclude string[] Exclude headers matching these regexes, applied after matching.
 no
matching Match headers by regex pattern(s) (OR).
 no
named Match headers by exact name (OR).
 no
rename string, null Optionally rename the header when returning it to the client.
 no

Option 1: propagate.exclude[]: array,null

Exclude headers matching these regexes, applied after matching.

Items

Item Type: string

Option 2: remove: object

Remove headers matched by the specification.

Properties

Name Type Description Required
exclude string[] Exclude headers matching these regexes, applied after matching.
matching Match headers by regex pattern(s) (OR).
named Match headers by exact name (OR).

Option 2: remove.exclude[]: array,null

Exclude headers matching these regexes, applied after matching.

Items

Item Type: string

Option 3: insert: object

Insert a header with a static value.

Examples

- insert:
    name: x-env
    value: prod
- insert:
    name: set-cookie
    value: "a=1; Path=/"
# If another Set-Cookie exists, this creates another header line (never joined)

Properties

Name Type Description Required
algorithm How to merge values across multiple subgraph responses.
Default: Last (overwrite).
 no
name string Header name to insert or overwrite (case-insensitive).
 yes

 
Option 1 (optional): Static value provided in the config.

Properties

Name Type Description Required
value string yes

 
Option 2 (optional): A dynamic value computed by a VRL expression.

This allows you to generate header values based on the incoming request, subgraph name, and (for response rules) subgraph response headers. The expression has access to a context object with .request, .subgraph, and .response fields.

For more information on the available functions and syntax, see the VRL documentation.

Example

# Insert a header with a value derived from another header.
- insert:
    name: x-auth-scheme
    expression: 'split(.request.headers.authorization, " ")[0] ?? "none"'

Properties

Name Type Description Required
expression string yes

http: object

Configuration for the HTTP server/listener.

Properties

Name Type Description Required
graphql_endpoint string The endpoint to serve GraphQL requests. By default, /graphql is used.
Default: "/graphql"
host string The host address to bind the HTTP server to.

Can also be set via the HOST environment variable.
Default: "0.0.0.0"
port integer The port to bind the HTTP server to.

Can also be set via the PORT environment variable.

If you are running the router inside a Docker container, please ensure that the port is exposed correctly using -p <host_port>:<container_port> flag.
Default: 4000
Format: "uint16"
Minimum: 0
Maximum: 65535

Additional Properties: not allowed
Example

graphql_endpoint: /graphql
host: 0.0.0.0
port: 4000

jwt: object

Configuration for JWT authentication plugin.

Properties

Name Type Description Required
allowed_algorithms string[] List of allowed algorithms for verifying the JWT signature.
Default: "HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "ES256", "ES384", "PS256", "PS384", "PS512", "EdDSA"
 no
audiences string[] The list of JWT audiences are allowed to access.
 no
enabled boolean Default: false
 no
forward_claims_to_upstream_extensions object Forward the JWT claims to the upstream service using GraphQL's .extensions.
Default: {"enabled":false,"field_name":"jwt"}
 yes
issuers string[] Specify the principal that issued the JWT, usually a URL or an email address.
 no
jwks_providers array A list of JWKS providers to use for verifying the JWT signature.
 yes
lookup_locations array A list of locations to look up for the JWT token in the incoming HTTP request.
Default: {"name":"authorization","prefix":"Bearer","source":"header"}
 no
require_authentication boolean, null If set to true, the entire request will be rejected if the JWT token is not present in the request.
 no

Additional Properties: not allowed
Example

allowed_algorithms:
  - HS256
  - HS384
  - HS512
  - RS256
  - RS384
  - RS512
  - ES256
  - ES384
  - PS256
  - PS384
  - PS512
  - EdDSA
enabled: false
forward_claims_to_upstream_extensions:
  enabled: false
  field_name: jwt
lookup_locations:
  - name: authorization
    prefix: Bearer
    source: header

jwt.allowed_algorithms[]: array,null

List of allowed algorithms for verifying the JWT signature. If not specified, the default list of all supported algorithms in jsonwebtoken crate are used.

Items

Item Type: string
Example

- HS256
- HS384
- HS512
- RS256
- RS384
- RS512
- ES256
- ES384
- PS256
- PS384
- PS512
- EdDSA

jwt.audiences[]: array,null

The list of JWT audiences are allowed to access. If this field is set, the token's aud field must be one of the values in this list, otherwise the token's aud field is not checked.

Items

Item Type: string

jwt.forward_claims_to_upstream_extensions: object

Forward the JWT claims to the upstream service using GraphQL's .extensions.

Properties

Name Type Description Required
enabled boolean yes
field_name string yes

Example

enabled: false
field_name: jwt

jwt.issuers[]: array,null

Specify the principal that issued the JWT, usually a URL or an email address. If specified, it has to match the iss field in JWT, otherwise the token's iss field is not checked.

Items

Item Type: string

jwt.jwks_providers[]: array

A list of JWKS providers to use for verifying the JWT signature. Can be either a path to a local JSON of the file-system, or a URL to a remote JWKS provider.

Items

 
Option 1 (alternative): A local file on the file-system. This file will be read once on startup and cached.

Properties

Name Type Description Required
path string A path to a local file on the file-system. Relative to the location of the root configuration file.
Format: "path"
 yes
source string Constant Value: "file"
 yes

 
Option 2 (alternative): A remote JWKS provider. The JWKS will be fetched via HTTP/HTTPS and cached.

Properties

Name Type Description Required
polling_interval string How often the JWKS should be polled for updates.
Default: "10m"
 no
prefetch boolean, null If set to true, the JWKS will be fetched on startup and cached. In case of invalid JWKS, the error will be ignored and the plugin will try to fetch again when server receives the first request.
If set to false, the JWKS will be fetched on-demand, when the first request comes in.
 no
source string Constant Value: "remote"
 yes
url string The URL to fetch the JWKS key set from, via HTTP/HTTPS.
 yes

Example

polling_interval: 10m

jwt.lookup_locations[]: array

A list of locations to look up for the JWT token in the incoming HTTP request. The first one that is found will be used.

Items

 
Option 1 (alternative): Properties

Name Type Description Required
name string A valid HTTP header name, according to RFC 7230.
Pattern: ^[A-Za-z0-9!#$%&'*+\-.^_\|~]+$`
 yes
prefix string, null no
source string Constant Value: "header"
 yes

 
Option 2 (alternative): Properties

Name Type Description Required
name string yes
source string Constant Value: "cookies"
 yes

Example

- name: authorization
  prefix: Bearer
  source: header

laboratory: object

Configuration for the Hive Laboratory interface.

Properties

Name Type Description Required
enabled boolean Enables/disables the Hive Laboratory interface. By default, the Hive Laboratory interface is enabled.

You can override this setting by setting the LABORATORY_ENABLED environment variable to true or false.
Default: true

Additional Properties: not allowed
Example

enabled: true

limits: object

Configuration for checking the limits such as query depth, complexity, etc.

Properties

Name Type Description Required
max_aliases object, null Configuration of limiting the number of aliases in the incoming GraphQL operations.
 yes
max_depth object, null Configuration of limiting the depth of the incoming GraphQL operations.
 yes
max_directives object, null Configuration of limiting the number of directives in the incoming GraphQL operations.
 yes
max_request_body_size string Default: "2 MB"
max_tokens object, null Configuration of limiting the number of tokens in the incoming GraphQL operations.
 yes

Example

max_request_body_size: 2 MB

limits.max_aliases: object,null

Configuration of limiting the number of aliases in the incoming GraphQL operations. If not specified, alias limiting is disabled.

It is used to prevent too many aliases that could lead to overfetching or DOS attacks.

Properties

Name Type Description Required
n integer Aliases threshold
Format: "uint"
Minimum: 0
 yes

limits.max_depth: object,null

Configuration of limiting the depth of the incoming GraphQL operations. If not specified, depth limiting is disabled.

It is used to prevent too large queries that could lead to overfetching or DOS attacks.

Properties

Name Type Description Required
flatten_fragments boolean Flatten fragment spreads and inline fragments when calculating depth.
Default: false
 no
ignore_introspection boolean Ignore the depth of introspection queries.
Default: true
 no
n integer Depth threshold
Format: "uint"
Minimum: 0
 yes

limits.max_directives: object,null

Configuration of limiting the number of directives in the incoming GraphQL operations. If not specified, directive limiting is disabled.

It is used to prevent too many directives that could lead to overfetching or DOS attacks.

Properties

Name Type Description Required
n integer Directives threshold
Format: "uint"
Minimum: 0
 yes

limits.max_tokens: object,null

Configuration of limiting the number of tokens in the incoming GraphQL operations. If not specified, token limiting is disabled.

It is used to prevent too large queries that could lead to overfetching or DOS attacks.

Properties

Name Type Description Required
n integer Tokens threshold
Format: "uint"
Minimum: 0
 yes

log: object

The router logger configuration.

The router is configured to be mostly silent (info) level, and will print only important messages, warnings, and errors.

Properties

Name Type Description Required
filter string, null The filter to apply to log messages.

Can also be set via the LOG_FILTER environment variable.
format string The format of the log messages.

Can also be set via the LOG_FORMAT environment variable.
Default: "json"
Enum: "pretty-tree", "pretty-compact", "json"
level string The level of logging to use.

Can also be set via the LOG_LEVEL environment variable.
Default: "info"
Enum: "trace", "debug", "info", "warn", "error"

Additional Properties: not allowed
Example

filter: null
format: json
level: info

override_labels: object

Configuration for overriding labels.

Additional Properties

Name Type Description Required
Additional Properties Defines the value for a label override.

It can be a simple boolean,
or an object containing the expression that evaluates to a boolean.

override_subgraph_urls: object

Configuration for overriding subgraph URLs.

Additional Properties

Name Type Description Required
Additional Properties object yes

Example

accounts:
  url: https://accounts.example.com/graphql
products:
  url:
    expression: |2-

              if .request.headers."x-region" == "us-east" {
                  "https://products-us-east.example.com/graphql"
              } else if .request.headers."x-region" == "eu-west" {
                  "https://products-eu-west.example.com/graphql"
              } else {
                .default
              }

override_subgraph_urls.additionalProperties: object

Properties

Name Type Description Required
url Overrides for the URL of the subgraph.

For convenience, a plain string in your configuration will be treated as a static URL.

### Static URL Example
yaml<br/>url: "https://api.example.com/graphql"<br/>

### Dynamic Expression Example

The expression has access to the following variables:
- request: The incoming HTTP request, including headers and other metadata.
- default: The original URL of the subgraph (from supergraph sdl).

```yaml
url:
expression: |
if .request.headers."x-region" == "us-east" {
"https://products-us-east.example.com/graphql"
} else if .request.headers."x-region" == "eu-west" {
"https://products-eu-west.example.com/graphql"
} else {
.default
}
 yes

persisted_documents: object

Configuration for persisted documents extraction and resolution.

Properties

Name Type Description Required
enabled boolean Default: false
log_missing_id boolean Default: false
require_id boolean Default: false
selectors array
storage

Example

enabled: false
log_missing_id: false
require_id: false
selectors: null
storage: null

persisted_documents.selectors[]: array,null

Items

 
Option 1 (alternative): Properties

Name Type Description Required
path string yes
type string Constant Value: "json_path"
 yes

 
Option 2 (alternative): Properties

Name Type Description Required
template string yes
type string Constant Value: "url_path_param"
 yes

 
Option 3 (alternative): Properties

Name Type Description Required
name string yes
type string Constant Value: "url_query_param"
 yes

Example

{}

plugins: object

Configuration for custom plugins

Additional Properties

Name Type Description Required
Additional Properties object

plugins.additionalProperties: object

Properties

Name Type Description Required
config Default: {}
enabled boolean Default: true
warn_on_error boolean Default: false

Additional Properties: not allowed
Example

config: {}
enabled: true
warn_on_error: false

query_planner: object

Query planning configuration.

Properties

Name Type Description Required
allow_expose boolean A flag to allow exposing the query plan in the response.
When set to true and an incoming request has a hive-expose-query-plan: true header, the query plan will be exposed in the response, as part of extensions.
Default: false
timeout string The maximum time for the query planner to create an execution plan.
This acts as a safeguard against overly complex or malicious queries that could degrade server performance.
When the timeout is reached, the planning process is cancelled.

Default: 10s.
Default: "10s"

Additional Properties: not allowed
Example

allow_expose: false
timeout: 10s

subscriptions: object

Configuration for subscriptions.

Properties

Name Type Description Required
broadcast_capacity integer The capacity of the broadcast channel used to fan out subscription events to all active listeners.

Each active subscription has its own broadcast channel. This value controls how many events
can be buffered in that channel before slow consumers start lagging. If a consumer falls too
far behind and the buffer is full, it will skip the missed messages and continue from the
latest available event.

Subscription events are typically low-frequency, so the default of 32 is sufficient for most
use cases. Increase this value if you expect bursts of events or have slow consumers that
need more headroom to catch up.

Defaults to 32.
Default: 32
Format: "uint"
Minimum: 0
callback object, null Configuration for subgraphs using the HTTP Callback protocol.
 yes
enabled boolean Enables/disables subscriptions. By default, the subscriptions are disabled.

You can override this setting by setting the SUBSCRIPTIONS_ENABLED environment variable to true or false.
Default: false
websocket object, null Configuration for subgraphs using WebSocket protocol.

Additional Properties: not allowed
Example

broadcast_capacity: 0
enabled: false

subscriptions.callback: object,null

Configuration for subgraphs using the HTTP Callback protocol.

Properties

Name Type Description Required
heartbeat_interval string The interval at which the subgraph must send heartbeat messages.
If set to 0, heartbeats are disabled. Defaults to 5 seconds.
Default: "5s"
 no
listen string, null The IP address and port the router will listen on for subscription callbacks.
When set, the router will start a dedicated HTTP server bound to this address
for receiving callback messages from subgraphs, separate from the main GraphQL server.
When not set, the callback handler is registered on the main server.

Example: 0.0.0.0:4001
 no
path string The path of the router's callback endpoint.
Must be an absolute path starting with /. Defaults to /callback.
Default: "/callback"
Pattern: ^/
 no
public_url string The public URL that subgraphs will use to send callback messages to this router.

Your public_url must match the server address combined with the router's path.
Meaning, if your server is http://localhost:4000 and the path is /callback,
your public_url should be http://localhost:4000/callback.

Example: https://example.com:4000/callback
Format: "uri"
 yes
subgraphs string[] The list of subgraph names that use the HTTP callback protocol.
Default:
no

Additional Properties: not allowed

subscriptions.callback.subgraphs[]: array

The list of subgraph names that use the HTTP callback protocol.

Items

Item Type: string
Unique Items: yes

subscriptions.websocket: object,null

Configuration for subgraphs using WebSocket protocol.

Properties

Name Type Description Required
all object, null The default configuration that will be applied to all subgraphs using
subgraphs object Optional per-subgraph configurations that will override the default configuration for specific subgraphs.

Additional Properties: not allowed

subscriptions.websocket.all: object,null

The default configuration that will be applied to all subgraphs using WebSocket protocol, unless overridden by a specific subgraph configuration.

When specified, all subgraphs (not claimed by callback) will use the WebSocket protocol.

Properties

Name Type Description Required
path string, null Determines the URL path to use for the subscription endpoint:

- For WebSocket connections, the URL will be ws://<subgraph-url><path>.
- If path is not set, the default subgraph URL is used, with the scheme adjusted to ws
for WebSocket connections where applicable.

Note to always provide the absolute path starting with a /, e.g., /ws.

For example, if the subgraph URL is http://example.com/graphql and the path is set to /ws,
the resulting WebSocket URL will be ws://example.com/ws.
Pattern: ^/

Additional Properties: not allowed

subscriptions.websocket.subgraphs: object

Optional per-subgraph configurations that will override the default configuration for specific subgraphs.

Additional Properties

Name Type Description Required
Additional Properties object WebSocket configuration for a specific subgraph or the default for all subgraphs.

subscriptions.websocket.subgraphs.additionalProperties: object

WebSocket configuration for a specific subgraph or the default for all subgraphs.

Properties

Name Type Description Required
path string, null Determines the URL path to use for the subscription endpoint:

- For WebSocket connections, the URL will be ws://<subgraph-url><path>.
- If path is not set, the default subgraph URL is used, with the scheme adjusted to ws
for WebSocket connections where applicable.

Note to always provide the absolute path starting with a /, e.g., /ws.

For example, if the subgraph URL is http://example.com/graphql and the path is set to /ws,
the resulting WebSocket URL will be ws://example.com/ws.
Pattern: ^/

Additional Properties: not allowed
Example

path: null

supergraph: object

Configuration for the Federation supergraph source. By default, the router will use a local file-based supergraph source (./supergraph.graphql). Each source has a different set of configuration, depending on the source type.

 
Option 1 (alternative): Loads a supergraph from the filesystem. The path can be either absolute or relative to the router's working directory.

Properties

Name Type Description Required
path string, null The path to the supergraph file.

Can also be set using the SUPERGRAPH_FILE_PATH environment variable.
Format: "path"
 no
poll_interval string Optional interval at which the file should be polled for changes.
If not provided, the file will only be loaded once when the router starts.
 no
source string Constant Value: "file"
 yes

Additional Properties: not allowed
Example

poll_interval: null

 
Option 2 (alternative): Loads a supergraph from Hive Console CDN.

Properties

Name Type Description Required
accept_invalid_certs boolean Whether to accept invalid TLS certificates when connecting to the Hive Console CDN.
Default: false
 no
connect_timeout string Connect timeout for the Hive Console CDN requests.
Default: "10s"
 no
endpoint The CDN endpoint from Hive Console target.

Can also be set using the HIVE_CDN_ENDPOINT environment variable.
 no
key string, null The CDN Access Token with from the Hive Console target.

Can also be set using the HIVE_CDN_KEY environment variable.
 no
poll_interval string Interval at which the Hive Console should be polled for changes.

Can also be set using the HIVE_CDN_POLL_INTERVAL environment variable.
Default: "10s"
 no
request_timeout string Request timeout for the Hive Console CDN requests.
Default: "1m"
 no
retry_policy object Interval at which the Hive Console should be polled for changes.
Default: {"max_retries":10}
 yes
source string Constant Value: "hive"
 yes

Additional Properties: not allowed
Example

accept_invalid_certs: false
connect_timeout: 10s
poll_interval: 10s
request_timeout: 1m
retry_policy:
  max_retries: 10

Option 2: retry_policy: object

Interval at which the Hive Console should be polled for changes.

By default, an exponential backoff retry policy is used, with 10 attempts.

Properties

Name Type Description Required
max_retries integer The maximum number of retries to attempt.

Retry mechanism is based on exponential backoff, see https://docs.rs/retry-policies/latest/retry_policies/policies/struct.ExponentialBackoff.html for additional details.
Format: "uint32"
Minimum: 0
 yes

Example

max_retries: 10

telemetry: object

Properties

Name Type Description Required
client_identification object Default: {"name_header":"graphql-client-name","version_header":"graphql-client-version"}
hive object, null
metrics object Configures metrics collection, processing, and export.
Default: {"exporters":[],"instrumentation":{"common":{"histogram":{"aggregation":"explicit","bytes":{"buckets":[128,512,1024,2048,4096,8192,16384,32768,65536,131072,262144,524288,1048576,2097152,3145728,4194304,5242880],"record_min_max":false},"seconds":{"buckets":[0.005,0.01,0.025,0.05,0.075,0.1,0.25,0.5,0.75,1,2.5,5,7.5,10],"record_min_max":false}}},"instruments":{}}}
resource object Default: {"attributes":{}}
tracing object Default: {"collect":{"max_attributes_per_event":16,"max_attributes_per_link":32,"max_attributes_per_span":128,"max_events_per_span":128,"parent_based_sampler":false,"sampling":1},"exporters":[],"instrumentation":{"spans":{"mode":"spec_compliant"}},"propagation":{"b3":false,"baggage":false,"jaeger":false,"trace_context":true}}

Additional Properties: not allowed
Example

client_identification:
  name_header: graphql-client-name
  version_header: graphql-client-version
hive: null
metrics:
  exporters: []
  instrumentation:
    common:
      histogram:
        aggregation: explicit
        bytes:
          buckets:
            - 128
            - 512
            - 1024
            - 2048
            - 4096
            - 8192
            - 16384
            - 32768
            - 65536
            - 131072
            - 262144
            - 524288
            - 1048576
            - 2097152
            - 3145728
            - 4194304
            - 5242880
          record_min_max: false
        seconds:
          buckets:
            - 0.005
            - 0.01
            - 0.025
            - 0.05
            - 0.075
            - 0.1
            - 0.25
            - 0.5
            - 0.75
            - 1
            - 2.5
            - 5
            - 7.5
            - 10
          record_min_max: false
    instruments: {}
resource:
  attributes: {}
tracing:
  collect:
    max_attributes_per_event: 16
    max_attributes_per_link: 32
    max_attributes_per_span: 128
    max_events_per_span: 128
    parent_based_sampler: false
    sampling: 1
  exporters: []
  instrumentation:
    spans:
      mode: spec_compliant
  propagation:
    b3: false
    baggage: false
    jaeger: false
    trace_context: true

telemetry.client_identification: object

Properties

Name Type Description Required
name_header string Default: "graphql-client-name"
version_header string Default: "graphql-client-version"

Additional Properties: not allowed
Example

name_header: graphql-client-name
version_header: graphql-client-version

telemetry.hive: object,null

Properties

Name Type Description Required
target A target ID, this can either be a slug following the format “$organizationSlug/$projectSlug/$targetSlug” (e.g “the-guild/graphql-hive/staging”) or an UUID (e.g. “a0f4c605-6541-4350-8cfe-b31f21a4bf80”). To be used when the token is configured with an organization access token.
token Your Registry Access Token with write permission.
tracing object Default: {"batch_processor":{"max_concurrent_exports":1,"max_export_batch_size":500,"max_export_timeout":"5s","max_queue_size":20000,"max_spans_per_trace":1000,"max_traces_in_memory":30000,"scheduled_delay":"5s"},"enabled":false,"endpoint":"https://api.graphql-hive.com/otel/v1/traces"}
usage_reporting object Default: {"accept_invalid_certs":false,"buffer_size":1000,"connect_timeout":"5s","enabled":false,"endpoint":"https://app.graphql-hive.com/usage","exclude":[],"flush_interval":"5s","request_timeout":"15s","sample_rate":"100%"}

Additional Properties: not allowed
Example

{}

telemetry.hive.tracing: object

Properties

Name Type Description Required
batch_processor object Default: {"max_concurrent_exports":1,"max_export_batch_size":500,"max_export_timeout":"5s","max_queue_size":20000,"max_spans_per_trace":1000,"max_traces_in_memory":30000,"scheduled_delay":"5s"}
enabled boolean Default: false
endpoint Default: "https://api.graphql-hive.com/otel/v1/traces"

Additional Properties: not allowed
Example

batch_processor:
  max_concurrent_exports: 1
  max_export_batch_size: 500
  max_export_timeout: 5s
  max_queue_size: 20000
  max_spans_per_trace: 1000
  max_traces_in_memory: 30000
  scheduled_delay: 5s
enabled: false
endpoint: https://api.graphql-hive.com/otel/v1/traces

telemetry.hive.tracing.batch_processor: object

Properties

Name Type Description Required
max_concurrent_exports integer Maximum number of export tasks that can run concurrently.
Default: 1
Format: "uint32"
Minimum: 0
max_export_batch_size integer Maximum number of traces (not spans) to include in a single export batch.
Default: 500
Format: "uint32"
Minimum: 0
max_export_timeout string Maximum time to wait for the exporter to finish a batch export.
Default: "5s"
max_queue_size integer Capacity of the input channel (from on_end to the worker thread).
Default: 20000
Format: "uint32"
Minimum: 0
max_spans_per_trace integer Maximum number of spans to buffer per single trace.

If a trace exceeds this limit, subsequent spans for that trace will be dropped.
Default: 1000
Format: "uint32"
Minimum: 0
max_traces_in_memory integer Maximum number of unique traces to keep in memory simultaneously.

If this limit is reached, the processor will attempt to flush ready traces.
If no traces are ready, new spans for new traces will be dropped to preserve memory.
Spans for existing traces will still be accepted.
Default: 30000
Format: "uint32"
Minimum: 0
scheduled_delay string Maximum time to wait before exporting ready traces if the batch size
hasn't been reached.
Default: "5s"

Additional Properties: not allowed
Example

max_concurrent_exports: 1
max_export_batch_size: 500
max_export_timeout: 5s
max_queue_size: 20000
max_spans_per_trace: 1000
max_traces_in_memory: 30000
scheduled_delay: 5s

telemetry.hive.usage_reporting: object

Properties

Name Type Description Required
accept_invalid_certs boolean Accepts invalid SSL certificates
Default: false
Default: false
buffer_size integer A maximum number of operations to hold in a buffer before sending to Hive Console
Default: 1000
Default: 1000
Format: "uint"
Minimum: 0
connect_timeout string A timeout for only the connect phase of a request to Hive Console
Default: 5 seconds
Default: "5s"
enabled boolean Default: false
endpoint string For self-hosting, you can override /usage endpoint (defaults to https://app.graphql-hive.com/usage).
Default: "https://app.graphql-hive.com/usage"
exclude string[] A list of operations (by name) to be ignored by Hive.
Default:
flush_interval string Frequency of flushing the buffer to the server
Default: 5 seconds
Default: "5s"
request_timeout string A timeout for the entire request to Hive Console
Default: 15 seconds
Default: "15s"
sample_rate string Sample rate to determine sampling.
0% = never being sent
50% = half of the requests being sent
100% = always being sent
Default: 100%
Default: "100%"

Additional Properties: not allowed
Example

accept_invalid_certs: false
buffer_size: 1000
connect_timeout: 5s
enabled: false
endpoint: https://app.graphql-hive.com/usage
exclude: []
flush_interval: 5s
request_timeout: 15s
sample_rate: 100%

telemetry.hive.usage_reporting.exclude[]: array

A list of operations (by name) to be ignored by Hive. Example: ["IntrospectionQuery", "MeQuery"]

Items

Item Type: string

telemetry.metrics: object

Configures metrics collection, processing, and export.

Properties

Name Type Description Required
exporters array List of metrics exporters.
Default:
instrumentation object Controls metrics instrumentation behavior, such as histogram aggregation.
Default: {"common":{"histogram":{"aggregation":"explicit","bytes":{"buckets":[128,512,1024,2048,4096,8192,16384,32768,65536,131072,262144,524288,1048576,2097152,3145728,4194304,5242880],"record_min_max":false},"seconds":{"buckets":[0.005,0.01,0.025,0.05,0.075,0.1,0.25,0.5,0.75,1,2.5,5,7.5,10],"record_min_max":false}}},"instruments":{}}

Additional Properties: not allowed
Example

exporters: []
instrumentation:
  common:
    histogram:
      aggregation: explicit
      bytes:
        buckets:
          - 128
          - 512
          - 1024
          - 2048
          - 4096
          - 8192
          - 16384
          - 32768
          - 65536
          - 131072
          - 262144
          - 524288
          - 1048576
          - 2097152
          - 3145728
          - 4194304
          - 5242880
        record_min_max: false
      seconds:
        buckets:
          - 0.005
          - 0.01
          - 0.025
          - 0.05
          - 0.075
          - 0.1
          - 0.25
          - 0.5
          - 0.75
          - 1
          - 2.5
          - 5
          - 7.5
          - 10
        record_min_max: false
  instruments: {}

telemetry.metrics.exporters[]: array

List of metrics exporters.

Metrics are enabled when at least one exporter is configured and enabled.

Items

 
Option 1 (alternative): Properties

Name Type Description Required
enabled boolean Enables or disables this OTLP metrics exporter.

Default: true.
Default: true
 no
endpoint OTLP endpoint URL.

Can be a static value or an expression.
Default: ""
 no
grpc object, null gRPC-specific OTLP settings.
 no
http object, null HTTP-specific OTLP settings.
 no
interval string Interval between periodic metric export attempts.

Default: 60s.
Default: "1m"
 no
kind string Constant Value: "otlp"
 yes
max_export_timeout string Maximum time allowed for a single metrics export attempt.

Default: 5s.
Default: "5s"
 no
protocol string Transport protocol used for OTLP metrics export.
Enum: "grpc", "http"
 yes
temporality Aggregation temporality used for this OTLP exporter.

Default: cumulative.
Default: "cumulative"
 no

Additional Properties: not allowed
Example

enabled: true
endpoint: ''
grpc: null
http: null
interval: 1m
max_export_timeout: 5s
temporality: cumulative

 
Option 2 (alternative): Properties

Name Type Description Required
enabled boolean Default: true
 no
kind string Constant Value: "prometheus"
 yes
path string Default: "/metrics"
 no
port integer, null Format: "uint16"
Minimum: 0
Maximum: 65535
 no

Additional Properties: not allowed
Example

enabled: true
path: /metrics
port: null

Option 1: grpc: object,null

gRPC-specific OTLP settings.

Properties

Name Type Description Required
metadata object Default: {}
tls object Default: {"ca":null,"cert":null,"domain_name":null,"key":null}

Additional Properties: not allowed
Example

{}

Option 1: grpc.metadata: object

Additional Properties

Name Type Description Required
Additional Properties

Option 1: grpc.tls: object

Properties

Name Type Description Required
ca string, null The path to the Certificate Authority (CA) certificate file (PEM format) used to verify the server's certificate.
cert string, null The path to the client's certificate file (PEM format).
domain_name string, null The domain name used to verify the server's TLS certificate.
key string, null The path to the client's private key file.

Additional Properties: not allowed
Example

ca: null
cert: null
domain_name: null
key: null

Option 1: http: object,null

HTTP-specific OTLP settings.

Properties

Name Type Description Required
headers object Default: {}

Additional Properties: not allowed
Example

{}

Option 1: http.headers: object

Additional Properties

Name Type Description Required
Additional Properties

telemetry.metrics.instrumentation: object

Controls metrics instrumentation behavior, such as histogram aggregation.

Properties

Name Type Description Required
common object Default: {"histogram":{"aggregation":"explicit","bytes":{"buckets":[128,512,1024,2048,4096,8192,16384,32768,65536,131072,262144,524288,1048576,2097152,3145728,4194304,5242880],"record_min_max":false},"seconds":{"buckets":[0.005,0.01,0.025,0.05,0.075,0.1,0.25,0.5,0.75,1,2.5,5,7.5,10],"record_min_max":false}}}
instruments object Default: {}

Additional Properties: not allowed
Example

common:
  histogram:
    aggregation: explicit
    bytes:
      buckets:
        - 128
        - 512
        - 1024
        - 2048
        - 4096
        - 8192
        - 16384
        - 32768
        - 65536
        - 131072
        - 262144
        - 524288
        - 1048576
        - 2097152
        - 3145728
        - 4194304
        - 5242880
      record_min_max: false
    seconds:
      buckets:
        - 0.005
        - 0.01
        - 0.025
        - 0.05
        - 0.075
        - 0.1
        - 0.25
        - 0.5
        - 0.75
        - 1
        - 2.5
        - 5
        - 7.5
        - 10
      record_min_max: false
instruments: {}

telemetry.metrics.instrumentation.common: object

Properties

Name Type Description Required
histogram Default: {"aggregation":"explicit","bytes":{"buckets":[128,512,1024,2048,4096,8192,16384,32768,65536,131072,262144,524288,1048576,2097152,3145728,4194304,5242880],"record_min_max":false},"seconds":{"buckets":[0.005,0.01,0.025,0.05,0.075,0.1,0.25,0.5,0.75,1,2.5,5,7.5,10],"record_min_max":false}}

Additional Properties: not allowed
Example

histogram:
  aggregation: explicit
  bytes:
    buckets:
      - 128
      - 512
      - 1024
      - 2048
      - 4096
      - 8192
      - 16384
      - 32768
      - 65536
      - 131072
      - 262144
      - 524288
      - 1048576
      - 2097152
      - 3145728
      - 4194304
      - 5242880
    record_min_max: false
  seconds:
    buckets:
      - 0.005
      - 0.01
      - 0.025
      - 0.05
      - 0.075
      - 0.1
      - 0.25
      - 0.5
      - 0.75
      - 1
      - 2.5
      - 5
      - 7.5
      - 10
    record_min_max: false

telemetry.metrics.instrumentation.instruments: object

Additional Properties

Name Type Description Required
Additional Properties

telemetry.resource: object

Properties

Name Type Description Required
attributes object Default: {}

Additional Properties: not allowed
Example

attributes: {}

telemetry.resource.attributes: object

Additional Properties

Name Type Description Required
Additional Properties

telemetry.tracing: object

Properties

Name Type Description Required
collect object Default: {"max_attributes_per_event":16,"max_attributes_per_link":32,"max_attributes_per_span":128,"max_events_per_span":128,"parent_based_sampler":false,"sampling":1}
exporters array Default:
instrumentation object Default: {"spans":{"mode":"spec_compliant"}}
propagation object Default: {"b3":false,"baggage":false,"jaeger":false,"trace_context":true}

Additional Properties: not allowed
Example

collect:
  max_attributes_per_event: 16
  max_attributes_per_link: 32
  max_attributes_per_span: 128
  max_events_per_span: 128
  parent_based_sampler: false
  sampling: 1
exporters: []
instrumentation:
  spans:
    mode: spec_compliant
propagation:
  b3: false
  baggage: false
  jaeger: false
  trace_context: true

telemetry.tracing.collect: object

Properties

Name Type Description Required
max_attributes_per_event integer Default: 16
Format: "uint32"
Minimum: 0
max_attributes_per_link integer Default: 32
Format: "uint32"
Minimum: 0
max_attributes_per_span integer Default: 128
Format: "uint32"
Minimum: 0
max_events_per_span integer Default: 128
Format: "uint32"
Minimum: 0
parent_based_sampler boolean Default: false
sampling number Default: 1
Format: "double"

Additional Properties: not allowed
Example

max_attributes_per_event: 16
max_attributes_per_link: 32
max_attributes_per_span: 128
max_events_per_span: 128
parent_based_sampler: false
sampling: 1

telemetry.tracing.exporters[]: array

Items

 
Option 1 (alternative): Properties

Name Type Description Required
batch_processor object Default: {"max_concurrent_exports":1,"max_export_batch_size":512,"max_export_timeout":"5s","max_queue_size":2048,"scheduled_delay":"5s"}
 no
enabled boolean Default: true
 no
endpoint Default: ""
 no
grpc object, null no
http object, null no
kind string Constant Value: "otlp"
 yes
protocol string Enum: "grpc", "http"
 yes

Additional Properties: not allowed
Example

batch_processor:
  max_concurrent_exports: 1
  max_export_batch_size: 512
  max_export_timeout: 5s
  max_queue_size: 2048
  scheduled_delay: 5s
enabled: true
endpoint: ''
grpc: null
http: null

 
Option 2 (alternative): Properties

Name Type Description Required
batch_processor object Default: {"max_concurrent_exports":1,"max_export_batch_size":512,"max_export_timeout":"5s","max_queue_size":2048,"scheduled_delay":"5s"}
 no
enabled boolean Default: true
 no
kind string Constant Value: "stdout"
 yes

Additional Properties: not allowed
Example

batch_processor:
  max_concurrent_exports: 1
  max_export_batch_size: 512
  max_export_timeout: 5s
  max_queue_size: 2048
  scheduled_delay: 5s
enabled: true

Option 1: batch_processor: object

Properties

Name Type Description Required
max_concurrent_exports integer Default: 1
Format: "uint32"
Minimum: 0
max_export_batch_size integer Default: 512
Format: "uint32"
Minimum: 0
max_export_timeout string Default: "5s"
max_queue_size integer Default: 2048
Format: "uint32"
Minimum: 0
scheduled_delay string Default: "5s"

Additional Properties: not allowed
Example

max_concurrent_exports: 1
max_export_batch_size: 512
max_export_timeout: 5s
max_queue_size: 2048
scheduled_delay: 5s

Option 1: grpc: object,null

Properties

Name Type Description Required
metadata object Default: {}
tls object Default: {"ca":null,"cert":null,"domain_name":null,"key":null}

Additional Properties: not allowed
Example

{}

Option 1: grpc.metadata: object

Additional Properties

Name Type Description Required
Additional Properties

Option 1: grpc.tls: object

Properties

Name Type Description Required
ca string, null The path to the Certificate Authority (CA) certificate file (PEM format) used to verify the server's certificate.
cert string, null The path to the client's certificate file (PEM format).
domain_name string, null The domain name used to verify the server's TLS certificate.
key string, null The path to the client's private key file.

Additional Properties: not allowed
Example

ca: null
cert: null
domain_name: null
key: null

Option 1: http: object,null

Properties

Name Type Description Required
headers object Default: {}

Additional Properties: not allowed
Example

{}

Option 1: http.headers: object

Additional Properties

Name Type Description Required
Additional Properties

Option 2: batch_processor: object

Properties

Name Type Description Required
max_concurrent_exports integer Default: 1
Format: "uint32"
Minimum: 0
max_export_batch_size integer Default: 512
Format: "uint32"
Minimum: 0
max_export_timeout string Default: "5s"
max_queue_size integer Default: 2048
Format: "uint32"
Minimum: 0
scheduled_delay string Default: "5s"

Additional Properties: not allowed
Example

max_concurrent_exports: 1
max_export_batch_size: 512
max_export_timeout: 5s
max_queue_size: 2048
scheduled_delay: 5s

telemetry.tracing.instrumentation: object

Properties

Name Type Description Required
spans object Default: {"mode":"spec_compliant"}

Additional Properties: not allowed
Example

spans:
  mode: spec_compliant

telemetry.tracing.instrumentation.spans: object

Properties

Name Type Description Required
mode Controls which semantic conventions are emitted on spans.
Default: SpecCompliant (only stable attributes).
Default: "spec_compliant"

Additional Properties: not allowed
Example

mode: spec_compliant

telemetry.tracing.propagation: object

Properties

Name Type Description Required
b3 boolean Default: false
baggage boolean Default: false
jaeger boolean Default: false
trace_context boolean Default: true

Additional Properties: not allowed
Example

b3: false
baggage: false
jaeger: false
trace_context: true

traffic_shaping: object

Configuration for the traffic-shaping of the executor. Use these configurations to control how requests are being executed to subgraphs.

Properties

Name Type Description Required
all object The default configuration that will be applied to all subgraphs, unless overridden by a specific subgraph configuration.
Default: {"allow_only_http2":false,"circuit_breaker":null,"dedupe_enabled":true,"pool_idle_timeout":"50s","request_timeout":"30s"}
max_connections_per_host integer Limits the concurrent amount of requests/connections per host/subgraph.
Default: 100
Format: "uint"
Minimum: 0
router object Configuration for the router itself, e.g., for handling incoming requests, or other router-level traffic shaping configurations.
Default: {"dedupe":{"enabled":false,"headers":"all"},"max_long_lived_clients":128,"request_timeout":"1m"}
subgraphs object Optional per-subgraph configurations that will override the default configuration for specific subgraphs.

Additional Properties: not allowed
Example

all:
  allow_only_http2: false
  circuit_breaker: null
  dedupe_enabled: true
  pool_idle_timeout: 50s
  request_timeout: 30s
max_connections_per_host: 100
router:
  dedupe:
    enabled: false
    headers: all
  max_long_lived_clients: 128
  request_timeout: 1m

traffic_shaping.all: object

The default configuration that will be applied to all subgraphs, unless overridden by a specific subgraph configuration.

Properties

Name Type Description Required
allow_only_http2 boolean Forces HTTP/2 for requests to subgraphs.

For plain HTTP, it will use HTTP/2 cleartext (h2c).
For HTTPS, it also requires HTTP/2.
This will make the subgraph requests never fall back to HTTP/1.1,
and will fail if the subgraph doesn't support HTTP/2.
Default: false
circuit_breaker object, null Circuit Breaker configuration for all subgraphs.
dedupe_enabled boolean Enables/disables request deduplication to subgraphs.

When requests exactly matches the hashing mechanism (e.g., subgraph name, URL, headers, query, variables), and are executed at the same time, they will
be deduplicated by sharing the response of other in-flight requests.
Default: true
pool_idle_timeout string Timeout for idle sockets being kept-alive.
Default: "50s"
request_timeout Optional timeout configuration for requests to subgraphs.

Example with a fixed duration:
yaml<br/> timeout:<br/> duration: 5s<br/>

Or with a VRL expression that can return a duration based on the operation kind:
yaml<br/> timeout:<br/> expression: |<br/> if (.request.operation.type == "mutation") {<br/> "10s"<br/> } else {<br/> "15s"<br/> }<br/>
Default: "30s"
tls object, null

Additional Properties: not allowed
Example

allow_only_http2: false
circuit_breaker: null
dedupe_enabled: true
pool_idle_timeout: 50s
request_timeout: 30s

traffic_shaping.all.circuit_breaker: object,null

Circuit Breaker configuration for all subgraphs. When the circuit breaker is open, requests to the subgraph will be short-circuited and an error will be returned to the client. The circuit breaker will be triggered based on the error rate of requests to the subgraph, and will attempt to reset after a certain timeout.

Properties

Name Type Description Required
enabled boolean, null Enable or disable the circuit breaker for the subgraph.
Default: false (circuit breaker is disabled)

When unset on a subgraph-level configuration, the value falls back
to the value defined in the global (all) circuit breaker
configuration.
error_status_codes integer[] HTTP status codes returned by the subgraph that should be counted as
error_threshold string Percentage after what the circuit breaker should kick in.
Default: 50%
reset_timeout string The duration after which the circuit breaker will attempt to retry sending requests to the subgraph.
Default: 30s
volume_threshold integer, null Count of requests before starting evaluating.
Default: 5
Format: "uint"
Minimum: 0

Additional Properties: not allowed

traffic_shaping.all.circuit_breaker.error_status_codes[]: array,null

HTTP status codes returned by the subgraph that should be counted as failures by the circuit breaker.

Only responses whose status code is contained in this list will be recorded as failures. Responses with any other status code (including other 5xx codes) are treated as successes from the circuit breaker's point of view.

Default: [503]

Items

Item Type: integer
Item Minimum: 100
Item Maximum: 599
Unique Items: yes

traffic_shaping.all.tls: object,null

Properties

Name Type Description Required
cert_file
client_auth object, null yes
insecure_skip_ca_verification boolean Default: false

Additional Properties: not allowed

traffic_shaping.all.tls.client_auth: object,null

Properties

Name Type Description Required
cert_file yes
key_file string Format: "path"
 yes

Additional Properties: not allowed

traffic_shaping.router: object

Configuration for the router itself, e.g., for handling incoming requests, or other router-level traffic shaping configurations.

Properties

Name Type Description Required
dedupe object Default: {"enabled":false,"headers":"all"}
max_long_lived_clients integer Maximum number of concurrent long-lived clients (WebSocket connections and HTTP streaming responses).
Regular non-streaming requests are not counted toward this limit.
When the limit is reached, new WebSocket and streaming HTTP requests are rejected with 503.
If both WebSockets and Subscriptions are disabled, this setting has no effect.
Default: 128
Format: "uint"
Minimum: 0
request_timeout string Optional timeout configuration for incoming requests to the router.
It starts from the moment the request is received by the router,
and includes the entire processing of the request (validation, execution, etc.) until a response is sent back to the client.
If a request takes longer than the specified duration, it will be aborted and a timeout error will be returned to the client.
Default: "1m"
tls object, null yes

Additional Properties: not allowed
Example

dedupe:
  enabled: false
  headers: all
max_long_lived_clients: 128
request_timeout: 1m

traffic_shaping.router.dedupe: object

Properties

Name Type Description Required
enabled boolean Enables/disables in-flight request and active subscriptions deduplication at the router level.

When enabled, the router deduplicates both queries and subscriptions using the same
fingerprint key (method, path, selected headers, schema checksum, normalized operation
hash, variables, and extensions). The headers configuration below controls which
headers participate in that key for all operation types.

For queries, concurrent HTTP requests that produce the same fingerprint share a single
in-flight execution - only the first one runs, and the rest wait for and receive the
same result.

For subscriptions, the mechanism is broadcast-based rather than request-sharing. The
first client with a given fingerprint becomes the leader: it runs the upstream subscription
and its events are fanned out through a broadcast channel backed by an active subscriptions
registry. Any subsequent client that arrives with an identical fingerprint while that subscription
is still active joins as a listener on the same broadcast channel instead of starting a new upstream
connection. When all listeners have dropped and the leader finishes, the entry is removed from the
registry.

WebSocket connections participate in the same deduplication space as HTTP. Each
subscribe message is processed with a synthetic request assembled from the WebSocket
path and the headers derived from the websocket.headers config. The fingerprint is computed
from those synthetic headers using the same header policy, so a subscription started over HTTP
and an identical one started over WebSocket will deduplicate against each other.

The deduplication is transport agnostic. A query over WebSocket would get deduplicated with an
identical query over HTTP if they arrive at the same time and have the same fingerprint.

Note: content-type is part of the fingerprint when headers includes it (e.g. all).
Since HTTP streaming clients send different accept headers than WebSocket clients,
cross-transport deduplication for subscriptions only applies when content-type (and
transport-specific headers) are excluded from the key. Configure headers: none or
headers: { include: [] } (or exclude the relevant headers) to enable true cross-transport
deduplication, where a WebSocket subscription and an SSE subscription with the same operation
share a single upstream connection and the events are fanned out to both.
Default: false
headers Header configuration participating in the dedupe key.

Accepted forms:
- all
- none
- { include: ["authorization", "cookie"] }

Header names are case-insensitive and validated as standard HTTP header names.
Default: "all"

Additional Properties: not allowed
Example

enabled: false
headers: all

traffic_shaping.router.tls: object,null

Properties

Name Type Description Required
cert_file yes
client_auth object, null yes
key_file string Format: "path"
 yes

Additional Properties: not allowed

traffic_shaping.router.tls.client_auth: object,null

Properties

Name Type Description Required
cert_file yes
required boolean, null no

Additional Properties: not allowed

traffic_shaping.subgraphs: object

Optional per-subgraph configurations that will override the default configuration for specific subgraphs.

Additional Properties

Name Type Description Required
Additional Properties object

traffic_shaping.subgraphs.additionalProperties: object

Properties

Name Type Description Required
allow_only_http2 boolean, null Forces HTTP/2 for requests to subgraphs.

For plain HTTP, it will use HTTP/2 cleartext (h2c).
For HTTPS, it also requires HTTP/2.
This will make the subgraph requests never fall back to HTTP/1.1,
and will fail if the subgraph doesn't support HTTP/2.
circuit_breaker object, null Circuit Breaker configuration for the subgraph.
dedupe_enabled boolean, null Enables/disables request deduplication to subgraphs.

When requests exactly matches the hashing mechanism (e.g., subgraph name, URL, headers, query, variables), and are executed at the same time, they will
be deduplicated by sharing the response of other in-flight requests.
pool_idle_timeout string, null Timeout for idle sockets being kept-alive.
request_timeout Optional timeout configuration for requests to subgraphs.

Example with a fixed duration:
yaml<br/> timeout:<br/> duration: 5s<br/>

Or with a VRL expression that can return a duration based on the operation kind:
yaml<br/> timeout:<br/> expression: |<br/> if (.request.operation.type == "mutation") {<br/> "10s"<br/> } else {<br/> "15s"<br/> }<br/>
tls object, null

Additional Properties: not allowed

traffic_shaping.subgraphs.additionalProperties.circuit_breaker: object,null

Circuit Breaker configuration for the subgraph. When the circuit breaker is open, requests to the subgraph will be short-circuited and an error will be returned to the client. The circuit breaker will be triggered based on the error rate of requests to the subgraph, and will attempt to reset after a certain timeout.

Properties

Name Type Description Required
enabled boolean, null Enable or disable the circuit breaker for the subgraph.
Default: false (circuit breaker is disabled)

When unset on a subgraph-level configuration, the value falls back
to the value defined in the global (all) circuit breaker
configuration.
error_status_codes integer[] HTTP status codes returned by the subgraph that should be counted as
error_threshold string Percentage after what the circuit breaker should kick in.
Default: 50%
reset_timeout string The duration after which the circuit breaker will attempt to retry sending requests to the subgraph.
Default: 30s
volume_threshold integer, null Count of requests before starting evaluating.
Default: 5
Format: "uint"
Minimum: 0

Additional Properties: not allowed

traffic_shaping.subgraphs.additionalProperties.circuit_breaker.error_status_codes[]: array,null

HTTP status codes returned by the subgraph that should be counted as failures by the circuit breaker.

Only responses whose status code is contained in this list will be recorded as failures. Responses with any other status code (including other 5xx codes) are treated as successes from the circuit breaker's point of view.

Default: [503]

Items

Item Type: integer
Item Minimum: 100
Item Maximum: 599
Unique Items: yes

traffic_shaping.subgraphs.additionalProperties.tls: object,null

Properties

Name Type Description Required
cert_file
client_auth object, null yes
insecure_skip_ca_verification boolean Default: false

Additional Properties: not allowed

traffic_shaping.subgraphs.additionalProperties.tls.client_auth: object,null

Properties

Name Type Description Required
cert_file yes
key_file string Format: "path"
 yes

Additional Properties: not allowed

websocket: object

Configuration of router's WebSocket server.

Properties

Name Type Description Required
enabled boolean Enables/disables WebSocket connections.

By default, WebSockets are disabled.

You can override this setting by setting the WEBSOCKET_ENABLED environment variable to true or false.
Default: false
headers object Configuration for handling headers for WebSocket connections.
Default: {"persist":false,"source":"connection"}
 yes
path string, null The path to use for the WebSocket endpoint on the router.

Note to always provide the absolute path starting with a /, e.g., /ws.

By default, the WebSocket endpoint will be available at the http.graphql_endpoint (defaults to /graphql)
if no path is specified and the clients will connect using ws://<router-url>/<graphql_endpoint>.
Pattern: ^/

Additional Properties: not allowed
Example

enabled: false
headers:
  persist: false
  source: connection
path: null

websocket.headers: object

Configuration for handling headers for WebSocket connections.

Properties

Name Type Description Required
persist boolean Whether to persist merged headers for the duration of the WebSocket connection
when using the both source (headers are accepted from multiple sources).

Only has effect when source is set to both.

This is useful when dealing with authentication using tokens that expire, where the
initial connection might use one token, but subsequent operations might need to
provide updated tokens in the operation extensions and then use that for further authentication.

For example:

1. Client connects with connection init payload containing an Authorization header with a token.
2. Client sends a subscription operation with an updated Authorization header in the operation extensions.
3. If persist is enabled, the updated Authorization header will be stored and used for subsequent operations.
Default: false
 no
source The source(s) from which to accept headers for WebSocket connections.
 yes

Additional Properties: not allowed
Example

persist: false
source: connection