Configuration

Learn how to configure your router.

The router provides three different ways of customization:

  1. Configure the router runtime: You can specify a config.yaml for convenience or pass environment variables. In both ways, you can configure the global behavior of the router. For a full reference of all available options see below or use your IDE of choice.

  2. Configure how your graph is served: This file can be provided as config option or is pulled automatically from the cdn. It contains information on how to resolve your federated schema. The engine uses the information to build a highly optimized query planner. For more information see wgc router compose to build the file locally for development or wgc router fetch to download the latest production version.

  3. Customize the router programatically through Go modules. It is unlikely that we will provide every possible feature as an in-built functionality. For advanced use cases or more control, you can build Go modules and compile the Router in a few commands. If you are uncertain about if your use case should be implemented as a custom module, don't hesitate to open an issue. We might already have a plan for this or can assist you with the implementation.

Recommendation Create a config file and use environment variable expansion to avoid storing secrets on the file system.

Config file

For convenience, you can create a config.yaml to specify all router options. Start the router in the same directory or pass the path to the file as a CONFIG_PATH environment variable.

config.yaml
version: '1'

graph:
    token: "${GRAPH_API_TOKEN}"

Values specified in the config file have precedence over Environment variables. This also includes empty values so only specify values that should be overwritten. That means, you can see the config file as a single source of truth.

Expand Environment Variables

You can expand environment variables in the file like this:

config.yaml
version: '1'

log_level: "${LOG_LEVEL}"

This will replace the value of the environment variable LOG_LEVEL with the value of the key log_level in your config file. For numeric values, ensure quotes are omitted.

Config Validation & Auto-completion

We know configuration is hard, especially for a software component like the router that can be customized entirely to your needs. In order to simplify this, we use JSON schema to validate the router configuration. This comes with huge benefits, all right at your fingertips:

  • Auto-completion

  • Documentation (Usage, Examples)

  • Detect deprecated fields

  • Detect typos or invalid values.

Some options require the router to validate them. This requires starting the router. Once your router has started successfully, you can be sure that your configuration is valid.

IDE Configuration

  • VsCode: Install the YAML extension in your IDE.

  • JetBrains: Support out of the box but in some circumstances it conflicts with other default mappings. Go to Languages & Frameworks -> Schemas and DTDs -> JSON Schemas Mappings configure the mapping yourself.

As the next step, add the following line to the head of your config.yamlfile. This line informs your IDE, to download the correct JSON schema file to validate the config file.

config.yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/wundergraph/cosmo/main/router/pkg/config/config.schema.json

version: '1'

If you want to pin to a specific router version use the following URL:

config.yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/wundergraph/cosmo/router%400.67.0/router/pkg/config/config.schema.json

Now, you should get auto-completion 🌟 .

Environment Variables

Many configuration options can be set as environment variables. For a complete list of options, please look at the Router config tables.

Router

The following sections describe each configuration in detail with all available options and their defaults.

Intervals, timeouts, and delays are specified in Go duration syntax e.g 1s, 5m or 1h.

Sizes can be specified in 2MB, 1mib.

Environment VariableYAMLRequiredDescriptionDefault Value

LISTEN_ADDR

listen_addr

The server listener address.

localhost:3002

CONTROLPLANE_URL

controlplane_url

The controlplane url.

PLAYGROUND_ENABLED

playground_enabled

Enables the GraphQL playground on ($LISTEN_ADDR/)

true

PLAYGROUND_PATH

playground_path

The path where the playground is served

"/"

INTROSPECTION_ENABLED

introspection_enabled

true

LOG_LEVEL

log_level

debug / info / warning / error / fatal / panic

info

JSON_LOG

json_log

Render the log output in JSON format (true) or human readable (false)

true

SHUTDOWN_DELAY

shutdown_delay

Maximum time in seconds the server has to shutdown gracefully. Should be higher than GRACE_PERIOD

60s

GRACE_PERIOD

grace_period

Maximum time in seconds the server has between schema updates to gracefully close client connections. Should be smaller than SHUTDOWN_DELAY

30s

POLL_INTERVAL

poll_interval

The interval of how often the router should check for new schema updates

10s

HEALTH_CHECK_PATH

health_check_path

Health check path. Returns 200 when the router is alive

/health

READINESS_CHECK_PATH

readiness_check_path

Readiness check path. Return 200 when the router is ready to accept traffic, otherwise 503

/health/ready

LIVENESS_CHECK_PATH

liveness_check_path

Liveness check path. Return 200 when the router is alive

/health/live

GRAPHQL_PATH

graphql_path

The path where the GraphQL Handler is served

/graphql

PLAYGROUND_PATH

playground_path

The path where the playground is served

/

LOCALHOST_FALLBACK_INSIDE_DOCKER

localhost_fallback_inside_docker

Enable fallback for requests that fail to connect to localhost while running in Docker

true

DEV_MODE

dev_mode

Enables pretty log output and allows to use Advanced Request Tracing (ART) without further security protection.

false

INSTANCE_ID

If not specified, a new ID will be generated with each router start. A stable ID ensures that metrics with the same ID are grouped together and the same server can be identified on the platform.

Example configuration:

config.yaml
version: "1"
  
log_level: "info"
listen_addr: "localhost:3002"
controlplane_url: "https://cosmo-cp.wundergraph.com"
playground_enabled: true
playground_path: "/"
introspection_enabled: true
json_log: true
shutdown_delay: 15s
grace_period: 20s
poll_interval: 10s
health_check_path: "/health"
readiness_check_path: "/health/ready"
liveness_check_path: "/health/live"
router_config_path: ""

Graph

Overall configuration for the Graph that's configured for this Router.

Environment VariableYAMLRequiredDescriptionDefault Value

GRAPH_API_TOKEN

token

The token permits the router to communicate with the controlplane and export telemetry. Created with wgc router token create. (Can be empty when providing a static router configuration through ROUTER_CONFIG_PATHbut will disable the default telemetry stack)

Example YAML config:

config.yaml
version: "1"

graph:
  token: "<your-graph-token>"

TLS

The Router supports TLS and mTLS for secure communication with your clients and infrastructure components like load balancer.

Server TLS

Environment VariableYAMLRequiredDescriptionDefault Value

TLS_SERVER_ENABLED

enabled

Enables server TLS support.

false

TLS_SERVER_CERT_FILE

cert_file

The path to the server certificate file.

TLS_SERVER_KEY_FILE

key_file

The path to the server private key file.

Example YAML config:

config.yaml
version: "1"
 
tls:
  server:
    enabled: true
    key_file: ../your/key.pem
    cert_file: ../your/cert.pem

Client Authentication

Environment VariableYAMLRequiredDescriptionDefault Value

TLS_CLIENT_AUTH_CERT_FILE

cert_file

Enables client authentication support. The file to the certificate file used to authenthicate clients.

""

TLS_CLIENT_AUTH_REQUIRED

required

Enforces a valid client certificate to establish a connection.

false

Example YAML config:

config.yaml
version: "1"
 
tls:
  server:
    enabled: true # Required for client_auth
    key_file: ../your/key.pem
    cert_file: ../your/cert.pem
    client_auth:
      required: true
      cert_file: ../your/cert.pem

Compliance

The configuration for the compliance. Includes for example the configuration for the anonymization of the IP addresses.

IP Anonymization

Environment VariableYAMLRequiredDescriptionDefault Value

SECURITY_ANONYMIZE_IP_ENABLED

enabled

Enables IP anonymization in traces and logs.

true

SECURITY_ANONYMIZE_IP_METHOD

method

The metod to anonymize IP addresses. Can be "hash" or "redact".

"redact"

Example YAML config:

config.yaml
version: "1"
 
compliance:
  anonymize_ip:
    enabled: true
    method: redact # hash or redact

Cluster

Environment VariableYAMLRequiredDescriptionDefault Value

CLUSTER_NAME

name

Example YAML config:

config.yaml
version: "1"
 
# See "https://cosmo-docs.wundergraph.com/studio/cluster-management" for more information
cluster:
  name: "us-central1-cosmo-cloud "

Telemetry

Environment VariableYAMLRequiredDescriptionDefault Value

TELEMETRY_SERVICE_NAME

service_name

cosmo-router

Example YAML config:

config.yaml
version: "1"
 
# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  # Common options
  service_name: "cosmo-router"

Tracing

Environment VariableYAMLRequiredDescriptionDefault Value

TRACING_ENABLED

enabled

true

TRACING_SAMPLING_RATE

sampling_rate

min 0.0

max 1.0

1

TRACING_BATCH_TIMEOUT

The maximum delay allowed before spans are exported.

10s

TRACING_EXPORT_GRAPHQL_VARIABLES

export_graphql_variables

Export GraphQL variables as span attribute. Variables may contain sensitive data.

false

with_new_root

Starts the root span always at the router.

false

Example YAML config:

config.yaml
version: "1"
 
# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  # Common options
  service_name: "cosmo-router"
  # uses https://cosmo-otel.wundergraph.com for tracing and metrics

  # OpenTelemetry Tracing
  tracing:
    enabled: true
    sampling_rate: 1
    batch_timeout: '10s'
    export_graphql_variables: false
    with_new_root: false

Exporters

Environment VariableYAMLRequiredDescriptionDefault Value

disabled

bool

exporter

one of: http,grpc

endpoint

path

headers

Example YAML config:

config.yaml
version: "1"
 
# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  tracing:
    enabled: true
    exporters:
      # If no exporters are defined, the default one is used
      - exporter: http # or grpc
        disabled: false
        endpoint: https://my-otel-collector.example.com
        # headers: {Authorization: Bearer <my-token>}
        batch_timeout: 10s
        export_timeout: 30s

Propagation

Environment VariableYAMLRequiredDescriptionDefault Value

trace_context

true

jaeger

b3

baggage

Example YAML config:

config.yaml
version: "1"
 
# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  # OpenTelemetry Tracing
  tracing:
    propagation:
      # https://www.w3.org/TR/trace-context/
      trace_context: true
      # https://www.w3.org/TR/baggage/
      baggage: false
      # https://www.jaegertracing.io/ (compliant with opentracing)
      jaeger: false
      # https://github.com/openzipkin/b3-propagation (zipkin)
      b3: false

Metrics

OLTP

Environment VariableYAMLRequiredDescriptionDefault Value

METRICS_OTLP_ENABLED

enabled

Enables OTEL metrics instrumentation

true

METRICS_OTLP_ROUTER_RUNTIME

router_runtime

true

Example YAML config:

config.yaml
version: "1"

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  # OpenTelemetry Metrics
  metrics:
    otlp:
      enabled: true
      router_runtime: true

Prometheus

Environment VariableYAMLRequiredDescriptionDefault Value

PROMETHEUS_ENABLED

enabled

Enables prometheus metrics support

true

PROMETHEUS_HTTP_PATH

path

The HTTP path where metrics are exposed.

"/metrics"

PROMETHEUS_LISTEN_ADDR

listen_addr

The prometheus listener address

"127.0.0.1:8088"

PROMETHEUS_EXCLUDE_METRICS

exclude_metrics

PROMETHEUS_EXCLUDE_METRIC_LABELS

exclude_metric_labels

Example YAML config:

config.yaml
version: "1"

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:          
    # Expose OpenTelemetry metrics for scraping
    prometheus:
      enabled: true
      path: "/metrics"
      listen_addr: "127.0.0.1:8088"
      exclude_metrics: []
      exclude_metric_labels: []

Exporter

Environment VariableYAMLRequiredDescriptionDefault Value

disabled

exporter

one of: http,grpc

endpoint

path

headers

Example YAML config:

config.yaml
version: "1"

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  # Common options
  service_name: "cosmo-router"
  # uses https://cosmo-otel.wundergraph.com for tracing and metrics

  # OpenTelemetry Metrics
  metrics:
    otlp:
      enabled: true
      # If no exporters are defined, the default one is used
      exporters:
        - exporter: http # or grpc
          disabled: false
          endpoint: https://my-otel-collector.example.com
          # headers: {Authorization: Bearer <my-token>}
          
    # Expose OpenTelemetry metrics for scraping
    prometheus:
      enabled: true
      path: "/metrics"
      listen_addr: "127.0.0.1:8088"
      exclude_metrics: []
      exclude_metric_labels: []

GraphQL Metrics

Environment VariableYAMLRequiredDescriptionDefault Value

GRAPHQL_METRICS_ENABLED

enabled

true

GRAPHQL_METRICS_COLLECTOR_ENDPOINT

collector_endpoint

Default endpoint

Example YAML config:

config.yaml
version: "1"

graphql_metrics:
    enabled: true
    collector_endpoint: 'https://cosmo-metrics.wundergraph.com'

CORS

Environment VariableYAMLRequiredDescriptionDefault Value

CORS_ALLOW_ORIGINS

allow_origins

*

CORS_ALLOW_METHODS

allow_methods

HEAD,GET,POST

CORS_ALLOW_HEADERS

allow_headers

Origin,Content-Length,Content-Type

CORS_ALLOW_CREDENTIALS

allow_credentials

true

CORS_MAX_AGE

max_age

5m

Example YAML config:

config.yaml
version: "1"

cors:
  allow_origins: ["*"]
  allow_methods:
    - HEAD
    - GET
    - POST
  allow_headers:
    - Origin
    - Content-Length
    - Content-Type
  allow_credentials: true
  max_age_minutes: 5m

Custom Modules

Configure your custom Modules. More information on this feature can be found here: Custom Modules

Example YAML config:

config.yaml
version: "1"

modules:
  myModule:
    # Arbitrary values, unmarshalled by the module
    value: 1

Headers

Configure Header propagation rules for all Subgraphs or individual Subgraphs by name.

Global Header Rules

Apply to requests to "all" Subgraphs

Environment VariableYAMLRequiredDescriptionDefault Value

request

Example YAML config:

config.yaml
version: "1"

# Header manipulation
# See "https://cosmo-docs.wundergraph.com/router/proxy-capabilities" for more information
headers:
  all: # Header rules for all origin requests.
    request:
      - op: "propagate"
        named: X-Test-Header
      - op: "propagate"
        matching: (?i)^x-deprecated-.*

Request Header Rule

Apply to requests to specific Subgraphs.

Environment VariableYAMLRequiredDescriptionDefault Value

op

oneof=propagate

matching

matching is the regex to match the header name against

named

named is the exact header name to match

default

default is the default value to set if the header is not present

Example YAML config:

config.yaml
version: "1"

# Header manipulation
# See "https://cosmo-docs.wundergraph.com/router/proxy-capabilities" for more information
headers:
  subgraphs:
    product: # Header rules for the "product" Subgraph
      request:
        - op: "propagate"
          named: X-Test-Header

Traffic Shaping

Configure rules for traffic shaping like maximum request body size, timeouts, retry behavior, etc. For more info, check this section in the docs: Traffic shaping

Example YAML config:

version: "1"

# Traffic configuration
# See "https://cosmo-docs.wundergraph.com/router/traffic-shaping" for more information
traffic_shaping:
  # Apply to all requests from clients to the router
  router:
    # Is the maximum size of the request body in MB, mib
    max_request_body_size: 5MB
  all: # Rules are applied to all subgraph requests.
    # Subgraphs transport options
    request_timeout: 60s
    dial_timeout: 30s
    tls_handshake_timeout: 0s
    response_header_timeout: 0s
    expect_continue_timeout: 0s
    keep_alive_idle_timeout: 0s
    keep_alive_probe_interval: 30s
    # Retry
    retry: # Rule is only applied to GraphQL operations of type "query"
      enabled: true
      algorithm: "backoff_jitter"
      max_attempts: 5
      interval: 3s
      max_duration: 10s

Subgraph Request Rules

These rules apply to requests being made from the Router to all Subgraphs.

Environment VariableYAMLRequiredDescriptionDefault Value

retry

request_timeout

60s

dial_timeout

30s

response_header_timeout

0s

expect_continue_timeout

0s

tls_handshake_timeout

10s

keep_alive_idle_timeout

0s

keep_alive_probe_interval

30s

Jitter Retry

Environment VariableYAMLRequiredDescriptionDefault Value

RETRY_ENABLED

enabled

true

algorithm

backoff_jitter

backoff_jitter

max_attempts

max_duration

interval

Client Request Request Rules

These rules apply to requests being made from clients to the Router.

Environment VariableYAMLRequiredDescriptionDefault Value

max_request_body_size

5mb

WebSocket

Configure WebSocket handlers, protocols, and more.

WebSocket Configuration

Environment VariableYAMLRequiredDescriptionDefault Value

WEBSOCKETS_ENABLED

enabled

true

absinthe_protocol

WEBSOCKETS_FORWARD_UPGRADE_HEADERS

forward_upgrade_headers

Forward all useful Headers from the Upgrade Request, like User-Agent or Authorization in the extensions field when subscribing on a Subgraph

true

WEBSOCKETS_FORWARD_UPGRADE_QUERY_PARAMS

forward_upgrade_query_params

Forward all query parameters from the Upgrade Request in the extensions field when subscribing on a Subgraph

true

WEBSOCKETS_FORWARD_INITIAL_PAYLOAD

forward_initial_payload

Forward the initial payload from a client subscription in the extensions field when subscribing on a Subgraph

true

Absinthe Protocol Configuration

Legacy WebSocket clients that use the Absinthe protocol might not be able to send a Subprotocol Header. For such clients, you can use the Absinthe Endpoint which automatically chooses the Subprotocol for them so that no Subprotocol Header needs to be set.

Environment VariableYAMLRequiredDescriptionDefault Value

WEBSOCKETS_ABSINTHE_ENABLED

enabled

true

WEBSOCKETS_ABSINTHE_HANDLER_PATH

handler_path

The path to mount the Absinthe handler on

/absinthe/socket

Example WebSocket YAML config:

config.yaml
version: "1"

websocket:
  enabled: true
  absinthe_protocol:
    enabled: true
    handler_path: /absinthe/socket
  forward_initial_payload: true
  forward_upgrade_headers: true
  forward_upgrade_query_params: true

Authentication

Configure different authentication providers.

Provider

Environment VariableYAMLRequiredDescriptionDefault Value

name

Name of the provider

jwks

JWK Provider

JWK Provider

Environment VariableYAMLRequiredDescriptionDefault Value

url

header_names

header_value_prefixes

refresh_interval

1m

Example YAML config:

config.yaml
version: "1"

# Authentication and Authorization
# See https://cosmo-docs.wundergraph.com/router/authentication-and-authorization for more information  
authentication:
  providers:
    - name: My Auth Provider # Optional, used for error messages and diagnostics
      jwks: # JWKS provider configuration
        url: https://example.com/.well-known/jwks.json # URL to load the JWKS from
        header_name: Authorization # Optional
        header_value_prefix: Bearer # Optional

Authorization

Environment VariableYAMLRequiredDescriptionDefault Value

REQUIRE_AUTHENTICATION

require_authentication

Set to true to disallow unauthenticated requests

false

REJECT_OPERATION_IF_UNAUTHORIZED

reject_operation_if_unauthorized

If enabled, the Router will return 401 with no response data when the evaluation of field-based permissions (@authenticatedor @requiresScopesfails)

false

Example YAML config:

config.yaml
version: "1"

authorization:
  require_authentication: false
  reject_operation_if_unauthorized: false

CDN

Environment VariableYAMLRequiredDescriptionDefault Value

CDN_URL

url

The URL of the CDN where the Router will fetch its Config

CDN_CACHE_SIZE

cache_size

Cosmo Router caches responses from the CDN in memory, this defines the cache size.

100MB

Example YAML config:

config.yaml
version: "1"

cdn:
   url: https://cosmo-cdn.wundergraph.com
   cache_size: 100MB

Events

The Events section lets you define Event Sources for Event-Driven Federated Subscriptions (EDFS).

Currently, we only support to use a single Event Source (NATS) with more to come in the future.

config.yaml
version: "1"

events:
  sources:
    - provider: NATS
      url: "nats://localhost:4222"

Event Source

Environment VariableYAMLRequiredDescriptionDefault Value

provider

one of: NATS

url

The URL of the event source, e.g. "nats://localhost:4222"

Router Engine Configuration

Configure the GraphQL Execution Engine of the Router.

Environment VariableYAMLRequiredDescriptionDefault Value

ENGINE_ENABLE_SINGLE_FLIGHT

enable_single_flight

Deduplicate exactly the same in-flight origin request

true

ENGINE_ENABLE_REQUEST_TRACING

enable_request_tracing

Enable Advanced Request Tracing (ART)This config is not correlated to OTEL tracing.

true

ENGINE_ENABLE_EXECUTION_PLAN_CACHE_RESPONSE_HEADER

enable_execution_plan_cache_response_header

Usually only required for testing. When enabled, the Router sets the response Header "X-WG-Execution-Plan-Cache" to "HIT" or "MISS"

false

ENGINE_MAX_CONCURRENT_RESOLVERS

max_concurrent_resolvers

Use this to limit the concurrency in the GraphQL Engine. A high number will lead to more memory usage. A number too low will slow down your Router.

1024

ENGINE_ENABLE_WEBSOCKET_EPOLL_KQUEUE

enable_websocket_epoll_kqueue

Use Epoll/Kqueue to handle WebSocket connections efficiently.

true

ENGINE_EPOLL_KQUEUE_POLL_TIMEOUT

epoll_kqueue_poll_timeout

Define the polling timeout for Epoll / Kqueue.

1s

ENGINE_EPOLL_KQUEUE_CONN_BUFFER_SIZE

epoll_kqueue_conn_buffer_size

Epoll / Kqueue polling uses a buffer. This number should match the number of potential client messages per polling interval.

128

ENGINE_WEBSOCKET_READ_TIMEOUT

websocket_read_timeout

5s

ENGINE_EXECUTION_PLAN_CACHE_SIZE

execution_plan_cache_size

Define how many GraphQL Operations should be stored in the execution plan cache. A low number will lead to more frequent cache misses, which will lead to increased latency.

10000

Example YAML config:

config.yaml
version: "1"

engine:
  enable_single_flight: true
  enable_request_tracing: true
  enable_execution_plan_cache_response_header: false
  max_concurrent_resolvers: 1024
  enable_websocket_epoll_kqueue: true
  epoll_kqueue_poll_timeout: "1s"
  epoll_kqueue_conn_buffer_size: 128
  websocket_read_timeout: "1s"
  execution_plan_cache_size: 10000

Debug Configuration

Environment VariableYAMLRequiredDescriptionDefault Value

report_websocket_connections

Report the number of WebSocket Connections and active Subscriptions in regular intervals to the log

false

report_memory_usage

Report the Memory usage of Cosmo Router to the log in regular intervals

false

Example YAML config:

config.yaml
version: "1"

engine:
  debug:
    report_websocket_connections: false
    report_memory_usage: false

Rate Limiting

Configures a rate limiter on the outgoing subgraphs requests. When enabled, a rate of 10 req/s with a burst of 10 requests is configured.

The rate limiter requires Redis version 3.2 or newer since it relies on replicate_commands feature. ElastiCache for Redis only works in non-clustered mode. You can enable a failover instance to achieve high availability.

General Rate Limiting Configuration

Environment VariableYAMLRequiredDescriptionDefault Value

RATE_LIMIT_ENABLED

enabled

Enable / Disable rate limiting globally

false

RATE_LIMIT_STRATEGY

strategy

The rate limit strategy

simple

simple_strategy

The configuration for the simple strategy

storage

Redis connection settings.

Storage

Environment VariableYAMLRequiredDescriptionDefault Value

RATE_LIMIT_REDIS_URL

addr

The connection URL.

redis://localhost:6379

RATE_LIMIT_REDIS_KEY_PREFIX

key_prefix

This prefix is used to namespace the ratelimit keys

cosmo_rate_limit

Simple Strategy

Environment VariableYAMLRequiredDescriptionDefault Value

RATE_LIMIT_SIMPLE_RATE

rate

Allowed request rate (number)

10

RATE_LIMIT_SIMPLE_BURST

burst

Allowed burst rate (number) - max rate per one request

10

RATE_LIMIT_SIMPLE_PERIOD

period

The rate limiting period, e.g. "10s", "1m", etc...

1s

RATE_LIMIT_SIMPLE_REJECT_EXCEEDING_REQUESTS

reject_exceeding_requests

Reject the complete request if a sub-request exceeds the rate limit. If set to false, partial responses are possible.

false

Subgraph Error Propagation

The configuration for the subgraph error propagation. Errors can be exposed to the client in a "wrapped" form to hide Subgraph internals, or it's possible to "pass-through" Subgraph errors directly to the client.

Environment VariableYAMLRequiredDescriptionDefault Value

SUBGRAPH_ERROR_PROPAGATION_ENABLED

enabled

Enable error propagation. If the value is true (default: false), Subgraph errors will be propagated to the client.

false

SUBGRAPH_ERROR_PROPAGATION_MODE

mode

The mode of error propagation. The supported modes are 'wrapped' (default) and 'pass-through'. The 'wrapped' mode wraps the error in a custom error object to hide internals. The 'pass-through' mode returns the error as is from the Subgraph.

wrapped

SUBGRAPH_ERROR_PROPAGATION_REWRITE_PATHS

rewrite_paths

Rewrite the paths of the Subgraph errors. If the value is true (default), the paths of the Subgraph errors will be rewritten to match the Schema of the Federated Graph.

true

SUBGRAPH_ERROR_PROPAGATION_OMIT_LOCATIONS

omit_locations

Omit the location field of Subgraph errors. If the value is true (default), the location field of Subgraph errors will be omitted. This is useful because the locations of a Subgraph error is internal to the Subgraph and not relevant to the client.

true

SUBGRAPH_ERROR_PROPAGATION_OMIT_EXTENSIONS

omit_extensions

Omit the extensions field of Subgraph errors. If the value is true (default: false), the extensions field of Subgraph errors will be omitted. This is useful in case you want to avoid leaking internal information to the client. Some users of GraphQL leverage the errors.extensions.code field to implement error handling logic in the client, in which case you might want to set this to false.

false

SUBGRAPH_ERROR_PROPAGATION_STATUS_CODES

propagate_status_codes

Propagate Subgraph status codes. If the value is true (default: false), Subgraph Response status codes will be propagated to the client in the errors.extensions.code field.

false

Example YAML configuration:

version: "1"

subgraph_error_propagation:
    enabled: true
    propagate_status_codes: false
    mode: "wrapped"
    rewrite_paths: true
    omit_locations: true
    omit_extensions: false

Security

The configuration for the security. The security is used to configure the security settings for the Router.

Environment VariableYAMLRequiredDescriptionDefault Value

SECURITY_BLOCK_MUTATIONS

block_mutations

Block mutation Operations. If the value is true, the mutations are blocked.

false

SECURITY_BLOCK_SUBSCRIPTIONS

block_subscriptions

Block subscription Operations. If the value is true, the subscriptions are blocked.

false

SECURITY_BLOCK_NON_PERSISTED_OPERATIONS

block_non_persisted_operations

Block non-persisted Operations. If the value is true, the non-persisted operations are blocked.

false

Example YAML Configuration

version: "1"

security:
    block_mutations: true
    block_subscriptions: true
    block_non_persisted_operations: true

Last updated