Router Configuration

Router Configuration Reference

The router provides three different ways of customization:

1. Configure the router runtime: You can specify a 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 to build the file locally for development or 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.

Experimental options

Options starting with the prefix experiment_ are unstable, and do not fall under any API stability guarantees. They may be updated or removed in future versions without a deprecation notice.

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.

Multiple Config Files

The router allows you to have multiple configuration files, enabling you to override and separate configurations into more manageable chunks. When specifying configuration files, you can simply provide a comma-separated list of file names. You can read more about this here.

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.

Regular Expressions

Many configuration options support regular expressions (Go RE2 syntax). Test patterns at regex101.com using the “Golang” flavor.

Escape dots in metric names: OpenTelemetry metrics contain dots that must be escaped in regex patterns:

• Incorrect: "wg.operation.hash" (matches any character)
• Correct: "wg\\.operation\\.hash" or '^wg\.operation\.hash$' (single quotes recommended)

Common examples:

# Metric exclusion
exclude_metrics:
  - '^wg\.operation\.hash$'       # Exact match
  - '^router\.http\.request\..*'  # Prefix match

# Header matching  
headers:
  all:
    request:
      - op: "propagate"
        matching: '(?i)^x-custom-.*'  # Case-insensitive prefix

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 Variable	YAML	Required	Description	Default Value
LISTEN_ADDR	listen_addr		The server listener address.	localhost:3002
CONTROLPLANE_URL	controlplane_url		The controlplane url. Not required when a static execution config is provided.	https://cosmo-cp.wundergraph.com
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		Deprecated, use “introspection.enabled” instead. Enables the GraphQL introspection.	true
QUERY_PLANS_ENABLED	query_plans_enabled		The Router can return Query plans as part of the response, which might be useful to understand the execution.	true
LOG_LEVEL	log_level		The log level to use. Allowed levels are "debug", "info", "warn", "error", "panic", "fatal".	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 clean up all resources. 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
POLL_JITTER	poll_jitter		The maximum delay added to the poll interval to mitigate thundering herd issues in router fleets scenarios.	5s
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	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.
DEMO_MODE	demo_mode		Launch the router in demo mode. If no execution config is found, the router will start with a demo execution config and deploy a demo federated graph that can be used for testing purposes.

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

Config watcher hot reloading

The router is capable of reloading itself using an updated config without a full process restart. You can trigger a reload in one of two ways:

• Sending a SIGHUP signal to the router process.
• Configuring the watch_config section to automatically check the configuration for changes at regular intervals.

config.yaml

watch_config:
  enabled: true
  interval: "10s"

  startup_delay:
    enabled: false
    maximum: "10s"

watch_config options

Environment Variable	YAML	Required	Description	Default Value
WATCH_CONFIG_ENABLED	watch_config.enabled		Enable automatic configuration reloading at regular intervals.	false
WATCH_CONFIG_INTERVAL	watch_config.interval		The interval at which the router checks for configuration changes.	10s
WATCH_CONFIG_STARTUP_DELAY_ENABLED	watch_config.startup_delay.enabled		Enable a random delay before the first configuration check to avoid thundering herd problems in clusters.	false
WATCH_CONFIG_STARTUP_DELAY_MAXIMUM	watch_config.startup_delay.maximum		The maximum random delay before the first configuration check.	10s

Hot reloading has some limitations:

• Changes to the watch_config section are not hot-reloaded.
• Changes to flags and environment variables are not possible.
• watch_config based reloads are based on the filesystem’s modification time, edits that somehow circumvent this mechanism will not trigger a reload.

Access Logs

For a detailed example, please refer to the Access Logs section.

Environment Variable	YAML	Required	Description	Default Value
	access_logs		Enable the access logs. The access logs are used to log the incoming requests. By default, the access logs are enabled and logged to the standard output.
ACCESS_LOGS_ENABLED	access_logs.enabled		Enable the access logs. The access logs are used to log the incoming requests. By default, the access logs are enabled and logged to the standard output.	true
ACCESS_LOGS_LEVEL	access_logs.level		Minimum level required for an access log entry to be emitted. One of: debug, info, warn, error, panic, fatal.	info
ACCESS_LOGS_ADD_STACKTRACE	access_logs.add_stacktrace		When true, include stack traces in access logs for error cases. Panics always include stack traces regardless.	false
	access_logs.buffer		The buffer is used to buffer the logs before writing them to the output.
ACCESS_LOGS_BUFFER_ENABLED	access_logs.buffer.enabled		Enable the buffer.	false
ACCESS_LOGS_BUFFER_SIZE	access_logs.buffer.size		The size of the buffer. The default value is 256KB.
ACCESS_LOGS_FLUSH_INTERVAL	access_logs.buffer.flush_interval		The interval at which the buffer is flushed. The period is specified as a string with a number and a unit, e.g. 10ms, 1s, 1m, 1h. The supported units are ‘ms’, ‘s’, ‘m’, ‘h’.
	access_logs.output		The log destination. The supported destinations are stdout and file. Only one option can be enabled. The default destination is stdout.
ACCESS_LOGS_OUTPUT_STDOUT_ENABLED	access_logs.output.stdout.enabled			true
ACCESS_LOGS_OUTPUT_FILE_ENABLED	access_logs.output.file.enabled			false
ACCESS_LOGS_FILE_OUTPUT_PATH	access_logs.output.file.path		The path to the log file. The path is used to specify the path to the log file.
ACCESS_LOGS_FILE_OUTPUT_MODE	access_logs.output.file.mode		The file mode (permissions) for the log file as an octal string. Must be exactly 3 octal digits (0-7), optionally prefixed with ‘0’ (e.g., ‘640’, ‘0640’, ‘755’, ‘0755’). The default value is ‘0640’.
	access_logs.router		The configuration for access logs for the router.
ACCESS_LOGS_ROUTER_FIELDS	access_logs.router.fields		The fields to add to the access logs for router. The fields are added to the logs as key-value pairs.	[]
	access_logs.router.fields.key		The key of the field to add to the logs.
	access_logs.router.fields.default		The default value of the field. If the value is not set, value_from is used. If both value and value_from are set, value_from has precedence and in case of a missing value_from, the default value is used.
	access_logs.router.value_from		Defines a source for the field value e.g. from a request header. If both default and value_from are set, value_from has precedence.
	access_logs.router.value_from.request_header		The name of the request header from which to extract the value. The value is only extracted when a request context is available otherwise the default value is used.
	access_logs.router.value_from.context_field		The field name of the context from which to extract the value. The value is only extracted when a context is available otherwise the default value is used. One of: [ “operation_name”, “operation_type”, “operation_service_names”, “operation_hash”, “persisted_operation_sha256”, “operation_sha256”, “response_error_message”, “graphql_error_codes”, “graphql_error_service_names”, “operation_parsing_time”, “operation_validation_time”, “operation_planning_time”, “operation_normalization_time” ]
ACCESS_LOGS_ROUTER_IGNORE_QUERY_PARAMS_LIST	access_logs.router.ignore_query_params_list		A list of query parameter names to ignore/exclude from the query field in access logs. This is useful for filtering out sensitive information from query parameters, especially when GraphQL requests are made over GET.	[“variables”]
	access_logs.subgraphs		The subgraph access logs configuration
ACCESS_LOGS_SUBGRAPH_ENABLED	access_logs.subgraphs.enabled		Enable the subgraphs access logs.	false
ACCESS_LOGS_SUBGRAPH_FIELDS	access_logs.subgraphs.fields		The fields to add to the logs when printing subgraph access logs. The fields are added to the logs as key-value pairs.
	access_logs.subgraphs.fields.key		The key of the field to add to the logs.
	access_logs.subgraphs.fields.default		The default value of the field. If the value is not set, value_from is used. If both value and value_from are set, value_from has precedence and in case of a missing value_from, the default value is used.
	access_logs.subgraphs.value_from		Defines a source for the field value e.g. from a request header. If both default and value_from are set, value_from has precedence.
	access_logs.subgraphs.value_from.request_header		The name of the request header from which to extract the value. The value is only extracted when a request context is available otherwise the default value is used.
	access_logs.subgraphs.value_from.response_header		The name of the response header from which to extract the value. The value is only extracted when a request context is available otherwise the default value is used.
	access_logs.subgraphs.value_from.context_field		The field name of the context from which to extract the value. The value is only extracted when a context is available otherwise the default value is used. One of: [ “operation_name”, “operation_type”, “operation_service_names”, “operation_hash”, “persisted_operation_sha256”, “operation_sha256”, “operation_parsing_time”, “operation_validation_time”, “operation_planning_time”, “operation_normalization_time” ]

Example YAML config:

config.yaml

version: "1"

access_logs:
  enabled: true
  level: info
  add_stacktrace: true
  buffer:
    enabled: false
    size: 256KB
    flush_interval: 10s
  output:
    file:
      enabled: true
      path: "access.log"
      mode: "0640"
  router:
    ignore_query_params_list:
      - "extensions"
    fields:
      - key: "service"
        value_from:
          request_header: "x-service"
      - key: "operationName"
        value_from:
          context_field: operation_name
  subgraphs:
    fields:
      - key: "service"
        value_from:
          request_header: "x-service"
      - key: "response-service"
        value_from:
          response_header: "x-response-service"
      - key: "operationName"
        value_from:
          context_field: operation_name

Telemetry

Graph

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

Environment Variable	YAML	Required	Description	Default Value
GRAPH_API_TOKEN	token		The token permits the router to communicate with the controlplane and export telemetry. Created with . (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>"

Introspection

Overall configuration for managing introspection queries on this Router.

Environment Variable	YAML	Required	Description	Default Value
INTROSPECTION_ENABLED	enabled		Enable or disable introspection queries	true
INTROSPECTION_SECRET	secret		Optional, dedicated secret used for instrospection authentication. Only used when authentication.ignore_introspection is set to true.

Example YAML config:

config.yaml

version: "1"

introspection:
  enabled: true
  secret: "dedicated_secret_for_introspection"

MCP (Model Context Protocol)

The Model Context Protocol (MCP) server allows AI models to discover and interact with your GraphQL API in a secure way.

Environment Variable	YAML	Required	Description	Default Value
MCP_ENABLED	mcp.enabled		Enable or disable the MCP server	false
MCP_SERVER_LISTEN_ADDR	mcp.server.listen_addr		The address and port where the MCP server will listen for requests	localhost:5025
MCP_ROUTER_URL	mcp.router_url		Custom URL to use for the router GraphQL endpoint in MCP. Use this when your router is behind a proxy; used in MCP responses to provide the real router URL.	-
MCP_STORAGE_PROVIDER_ID	mcp.storage.provider_id		The ID of a storage provider to use for loading GraphQL operations. Only file_system providers are supported.	-
MCP_SESSION_STATELESS	mcp.session.stateless		Whether the MCP server should operate in stateless mode. When true, no server-side session state is maintained between requests.	true
MCP_GRAPH_NAME	mcp.graph_name		The name of the graph to be used by the MCP server	mygraph
MCP_EXCLUDE_MUTATIONS	mcp.exclude_mutations		Whether to exclude mutation operations from being exposed	false
MCP_ENABLE_ARBITRARY_OPERATIONS	mcp.enable_arbitrary_operations		Whether to allow arbitrary GraphQL operations to be executed. Security risk: Should only be enabled in secure, internal environments.	false
MCP_EXPOSE_SCHEMA	mcp.expose_schema		Whether to expose the full GraphQL schema. Security risk: Should only be enabled in secure, internal environments.	false

Example YAML config:

config.yaml

version: "1"

mcp:
  enabled: true
  server:
    listen_addr: "localhost:5025"
  router_url: "https://your-public-router-url.example.com/graphql" # Optional: Used in MCP responses when your router is behind a proxy.
  storage:
    provider_id: "mcp" # References a file_system provider defined below
  session:
    stateless: true # Optional: When true, no server-side session state is kept
  graph_name: "my-graph"
  exclude_mutations: true
  enable_arbitrary_operations: false
  expose_schema: false

# Configure storage providers
storage_providers:
  file_system:
    - id: "mcp"
      path: "operations" # Relative to the router binary

For more details on how to use the MCP server, see the MCP Integration documentation.

TLS

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

Server TLS

Environment Variable	YAML	Required	Description	Default 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 Variable	YAML	Required	Description	Default 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 Variable	YAML	Required	Description	Default 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 Variable	YAML	Required	Description	Default Value
CLUSTER_NAME	name		The logical name of the router cluster. The name is used for analytic purpose.

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 Variable	YAML	Required	Description	Default Value
TELEMETRY_SERVICE_NAME	service_name		The name of the service.	cosmo-router
	resource_attributes		The resource attributes to add to OTEL metrics and traces. The resource attributes identify the entity producing the traces and metrics.
	resource_attributes.key		The key of the attribute.
	resource_attributes.value		The value of the attribute.
	attributes		The attributes to add to OTEL metrics and traces. Because Prometheus metrics rely on the OpenTelemetry metrics, the attributes are also added to the Prometheus metrics.	[]
	attributes.key		The key of the attribute.
	attributes.default		The value of the attribute.
	attributes.value_from		Defines a source for the attribute value e.g. from a request header. If both default and value_from are set, value_from has precedence.
	attributes.value_from.request_header		The name of the request header from which to extract the value. The value is only extracted when a request context is available otherwise the default value is used. Don’t forget to add the header to your CORS settings.

Example YAML config:

config.yaml

version: "1"

# Only needed when setting attributes based on a request header
cors:
  allow_headers:
    - "x-service"

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  # Common options
  service_name: "cosmo-router"
  resource_attributes:
    - key: env
      value: "prod"
  attributes:
    - key: service
      default: "static"
      value_from:
        request_header: "x-service"

Tracing

Environment Variable	YAML	Required	Description	Default Value
TRACING_ENABLED	enabled			true
TRACING_SAMPLING_RATE	sampling_rate		The sampling rate for the traces. The value must be between 0 and 1. If the value is 0, no traces will be sampled. If the value is 1, all traces will be sampled. For managed plans, the trace sampling rate will not exceed the rate imposed by the organization limit of the plan.	1
TRACING_PARENT_BASED_SAMPLER	parent_based_sampler		Enable the parent-based sampler. The parent-based sampler is used to sample the traces based on the parent trace.	true
TRACING_BATCH_TIMEOUT	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
TRACING_OPERATION_CONTENT_ATTRIBUTES	operation_content_attributes		Enable the addition of GraphQL operation body content as trace attributes. When enabled, original operation content will be added to the trace span for parse and normalized operation content will be added to the trace span for normalize. The default value is false.	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
    operation_content_attributes: false
    with_new_root: false

Exporters

Environment Variable	YAML	Required	Description	Default Value
	diabled		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 Variable	YAML	Required	Description	Default Value
	trace_context			true
	jaeger
	b3
	baggage
	datadog		Enable Datadog trace propagation	false

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
      # https://docs.datadoghq.com/tracing/trace_collection/trace_context_propagation/?tab=java#datadog-format
      datadog: false

Attributes

YAML	Required	Description	Default Value
attributes		The attributes to add for Tracing.	[]
attributes.key		The key of the field.
attributes.value_from		Defines a source for the field value.
attributes.value_from.expression		The expression for the trace attribute.

Example YAML config:

config.yaml

version: "1"

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  # OpenTelemetry Tracing
  tracing:
    attributes:
      - key: "x-new-attribute"
        value_from:
          expression: "request.url.method"

Metrics

Environment Variable	YAML	Required	Description	Default Value
METRICS_EXPERIMENT_CARDINALITY_LIMIT	experiment_cardinality_limit		Sets a hard limit on the number of Metric Points that can be collected during a collection cycle.	2000

The experiment_cardinality_limit option is experimental because it relies on experimental functionality in the OpenTelemetry SDK for Go. This feature helps prevent excessive memory usage by limiting the number of unique metric combinations (cardinality) that can be collected in a single collection cycle.

See the specification for more information: https://opentelemetry.io/docs/specs/otel/metrics/sdk/#cardinality-limits

This option may change or be removed in future versions as the OpenTelemetry SDK stabilizes this functionality.

OTLP

Environment Variable	YAML	Required	Description	Default Value
METRICS_OTLP_ENABLED	enabled		Enables OTEL metrics instrumentation	true
METRICS_OTLP_ROUTER_RUNTIME	router_runtime		Enable the collection of metrics for the router runtime.	true
METRICS_OTLP_GRAPHQL_CACHE	graphql_cache		Enable the collection of metrics for the GraphQL operation router caches.	false
METRICS_OTLP_EXCLUDE_METRICS	exclude_metrics		The metrics to exclude from the OTEL metrics. Accepts a list of Go regular expressions. Use https://regex101.com/ to test your regular expressions.	[]
METRICS_OTLP_EXCLUDE_METRIC_LABELS	exclude_metric_labels		The metric labels to exclude from the OTEL metrics. Accepts a list of Go regular expressions. Use https://regex101.com/ to test your regular expressions.	[]
METRICS_OTLP_CONNECTION_STATS	connection_stats		Enable connection metrics.	false
METRICS_OTLP_CIRCUIT_BREAKER	circuit_breaker		Ensure that circuit breaker metrics are enabled for OTEL.	false
METRICS_OTLP_STREAM	streams		Enable Cosmo Streams metrics.	false

Attributes

YAML	Required	Description	Default Value
attributes		The attributes to add to OTLP Metrics and Prometheus.	[]
attributes.key		The key of the field.
attributes.default		The default value of the field. If the value is not set, value_from is used. If both value and value_from are set, value_from has precedence and in case of a missing value_from, the default value is used.
attributes.value_from		Defines a source for the field value e.g. from a request header or request context. If both default and value_from are set, value_from has precedence.
attributes.value_from.request_header		The name of the request header from which to extract the value. The value is only extracted when a request context is available otherwise the default value is used.
attributes.value_from.context_field		The field name of the context from which to extract the value. The value is only extracted when a context is available otherwise the default value is used.	One of:[“operation_service_names”, “graphql_error_codes”, “graphql_error_service_names”, “operation_sha256”]

Example YAML config:

config.yaml

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  metrics:
    experiment_cardinality_limit: 2000
    otlp:
      enabled: true
      router_runtime: true
      graphql_cache: true
      exclude_metrics: []
      exclude_metric_labels: []
      streams: true
    attributes:
      - key: "x-new-attribute"
        default: "foo"
        value_from:
          request_header: "X-Request-ID"

      - key: "error_codes"
        value_from:
          context_field: graphql_error_codes

Prometheus

Environment Variable	YAML	Required	Description	Default 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 address to listen on for the prometheus metrics endpoint.	”127.0.0.1:8088”
PROMETHEUS_GRAPHQL_CACHE	graphql_cache		Enable the collection of metrics for the GraphQL operation router caches.	false
PROMETHEUS_CONNECTION_STATS	connection_stats		Enable connection metrics.	false
PROMETHEUS_EXCLUDE_METRICS	exclude_metrics
PROMETHEUS_EXCLUDE_METRIC_LABELS	exclude_metric_labels
PROMETHEUS_EXCLUDE_SCOPE_INFO	exclude_scope_info		Exclude scope info from Prometheus metrics.	false
PROMETHEUS_CIRCUIT_BREAKER	circuit_breaker		Enable the circuit breaker metrics for prometheus metric collection.	false
PROMETHEUS_OTLP_STREAM	streams		Enable Cosmo Streams metrics.	false

Example YAML config:

config.yaml

version: "1"

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

Exporter

YAML	Required	Description	Default Value
disabled
exporter		one of: http,grpc
endpoint
path		The path to which the metrics are exported. This is ignored when using ‘grpc’ as exporter and can be omitted.
headers
temporality		Temporality defines the window that an aggregation is calculated over. one of: delta, cumulative

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
          temporality: delta # or cumulative
          # 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 Variable	YAML	Required	Description	Default Value
GRAPHQL_METRICS_ENABLED	enabled			true
GRAPHQL_METRICS_COLLECTOR_ENDPOINT	collector_endpoint		Default endpoint	https://cosmo-metrics.wundergraph.com

Example YAML config:

config.yaml

version: "1"

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

CORS

Environment Variable	YAML	Required	Description	Default Value
CORS_ENABLED	enabled		Set this to enable/disable the CORS middleware. It is enabled by default. When disabled, the rest of the properties for CORS have no effect.	true
CORS_ALLOW_ORIGINS	allow_origins		This is a list of origins which are allowed. You can provide origins with wildcards	*
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: 5m

Cache Control Policy

Configure your cache control policy. More information on this feature can be found here: #cache-control-policy

Environment Variable	YAML	Required	Description	Default Value
CACHE_CONTROL_POLICY_ENABLED	enabled		Set this to enable/disable the strict cache control policy. It is false by default	false
CACHE_CONTROL_POLICY_VALUE	value		The default value for the cache control policy. It will be applied to all requests, unless a subgraph has a more strict one

Example YAML Config:

config.yaml

version: "1"

cache_control_policy:
  enabled: true
  value: "max-age=180, public"
  subgraphs:
    - name: "products"
      value: "max-age=60, public"
    - name: "pricing"
      value: "no-cache"

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

Router Plugins

The configuration for the router plugins. To learn more about the plugins, see the plugins documentation.

Environment Variable	YAML	Required	Description	Default Value
PLUGINS_ENABLED	enabled		Enable the router plugins. If the value is true, the router plugins are enabled.	false
PLUGINS_PATH	path		The path to the plugins directory. The plugins directory is used to load the plugins.	plugins

Example YAML config:

config.yaml

version: "1"

plugins:
  enabled: true
  path: "plugins"

Headers

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

Cookie Whitelist

When Cookieis a propagated header, you may want to filter the keys that are forwarded to the subgraph from the client, you can do this via the cookie_whitelistoption, which is a list of string cookie keys that will not be discarded. An empty value means allow all. If you’d like to block all cookies, disable the header propagation entirely.

The cookie whitelist can also affect custom modules that read request cookies, even if propagation is disabled for the Cookie header. This is because the whitelisting happens very early in the request lifecycle, before it reaches subgraphs or custom modules.

Example YAML config:

version: "1"

# Header manipulation
# See "https://cosmo-docs.wundergraph.com/router/proxy-capabilities" for more info
headers:
  cookie_whitelist:
   - "authorization"
   - "my-cookie-key"
  all:
    request:
      - op: "propagate"
        named: Cookie

Global Header Rules

Apply to requests/responses to/from “all” Subgraphs. These will be applied globally in the graph

Environment Variable	YAML	Required	Description	Default Value
	request		List of Request Header Rules
	response		List of Response Header Rules

Example YAML config:

config.yaml

version: "1"

# Header manipulation
# See "https://cosmo-docs.wundergraph.com/router/proxy-capabilities" for more info
headers:
  all: # Header rules for all origin requests.
    request:
      - op: "propagate"
        named: X-Test-Header
      - op: "propagate"
        matching: (?i)^x-deprecated-.*
      - op: "set"
        name: "X-API-Key"
        value: "my-secret-value"
    response:
      - op: "propagate"
        algorithm: "append"
        named: "X-Custom-Header"

Header Rule Example Using Template Expression:

This example sets the X-User-ID header based on the sub claim from the JWT token, if the user is authenticated. Learn more about template expressions.

config.yaml

version: "1"

headers:
  all:
    request:
      - op: "set"
        name: "X-User-ID"
        # Sets the header only if the user is authenticated
        expression: "request.auth.isAuthenticated ? request.auth.claims.sub : ''"

Request Header Rule

Apply to requests to specific Subgraphs.

Environment Variable	YAML	Required	Description	Default Value
	op		oneof=propagate, set
	matching		matching is the regex to match the header name against
	named		named is the exact header name to match
	rename		renames the header’s key to the provided value
	default		default is the default value to set if the header is not present
	name		If op is set, name is the name of the desired header to set
	value		If op is set, value is the value of the desired header to set
	expression		If op is set, expression is the expression to evaluate to get the value of the desired header to set

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
        - op: "set"
          name: "X-API-Key"
          value: "my-secret-value"

Response Header Rule

These rules can be applied to all responses, as well as just to specific subgraphs, and used to manipulate and propagate response headers from subgraphs to the client. By configuring the rule, users can define how headers should be handled when multiple subgraphs provide conflicting values for a specific header.

Environment Variable	YAML	Required	Description	Default Value
	op		oneof=propagate, set
	algorithm		oneof=first_write, last_write, append
	matching		matching is the regex to match the header name against. This
	named		named is the exact header name to match
	default		default is the default value to set if the header is not present
	rename		renames the header’s key to the provided value

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
      response:
        - op: "propagate"
          algorithm: "append"
          named: "X-Test-Header"
        - op: "propagate"
          algorithm: "last_write"
          named: "X-Test2-Header"
        - op: "set"
          name: "X-User-Key"
          value: "my-user-value"

Storage Providers

Storage providers allow you to configure different backends for persisted operations, router execution config and MCP operations.

Example YAML config:

config.yaml

version: "1"

storage_providers:
  s3:
    - id: "s3-provider"
      endpoint: "s3.amazonaws.com"
      access_key: "${AWS_ACCESS_KEY_ID}"
      secret_key: "${AWS_SECRET_ACCESS_KEY}"
      bucket: "my-bucket"
      region: "us-east-1"
      secure: true
  redis:
    - id: "redis-provider"
      urls:
        - "redis://localhost:6379"
      cluster_enabled: false
  file_system:
    - id: "fs-provider"
      path: "/path/to/files"
  cdn:
    - id: "cdn-provider"
      url: "https://cosmo-cdn.wundergraph.com"

Storage Provider Types

File System Storage Provider

This provider allows you to load files from the local file system. This is particularly useful for the MCP server to load GraphQL operations.

Environment Variable	YAML	Required	Description	Default Value
STORAGE_PROVIDER_FS_ID	id		The ID of the provider to reference in other configurations
STORAGE_PROVIDER_FS_PATH	path		The path on the file system where files should be loaded from

The file system storage provider is currently only supported by the MCP feature. It cannot be used for persisted operations or execution configurations.

Redis Storage Provider

Used for distributed caching like automatic persisted queries.

Environment Variable	YAML	Required	Description	Default Value
STORAGE_PROVIDER_REDIS_ID	id		The ID of the provider to reference in other configurations
STORAGE_PROVIDER_REDIS_URLS	urls		List of Redis URLs to connect to. If cluster_enabled is true, these are the seeds to discover the cluster
STORAGE_PROVIDER_REDIS_CLUSTER_ENABLED	cluster_enabled		Whether to use the Redis Cluster client	false

S3 Storage Provider

For storing operations and configs in S3-compatible storage.

Environment Variable	YAML	Required	Description	Default Value
	id		The ID of the provider to reference in other configurations
	endpoint		The endpoint of the S3 service
	access_key		The access key for the S3 service
	secret_key		The secret key for the S3 service
	bucket		The bucket where objects will be stored
	region		The region of the S3 bucket
	secure		Whether to use HTTPS for S3 connections	true

CDN Provider

For connecting to the Cosmo CDN.

Environment Variable	YAML	Required	Description	Default Value
	id		The ID of the provider to reference in other configurations
	url		The URL of the CDN	https://cosmo-cdn.wundergraph.com

Persisted Operations

The configuration for the persisted operations allows you to maintain a fixed set of GraphQL operations that can be queried against the router without exposing your entire graph to the public. This approach enhances security and performance.

Example YAML config:

config.yaml

version: "1"

persisted_operations:
  disabled: false
  log_unknown: false
  safelist:
    enabled: false
  cache:
    size: 100MB
  storage:
    provider_id: s3
    object_prefix: wundergraph

Persisted Operations Configuration Options

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

Environment Variable	YAML	Required	Description	Default Value
	persisted_operations		The configuration for the persisted operations.
PERSISTED_OPERATIONS_DISABLED	persisted_operations.disabled		Disable persisted operations.	false
	persisted_operations.cache		LRU cache for persisted operations.
PERSISTED_OPERATIONS_CACHE_SIZE	persisted_operations.cache.size		The size of the cache in SI unit.	”100MB”
	persisted_operations.storage		The storage provider for persisted operation. Only one provider can be active. When no provider is specified, the router will fallback to the Cosmo CDN provider to download the persisted operations.
PERSISTED_OPERATIONS_STORAGE_PROVIDER_ID	persisted_operations.storage.provider_id		The ID of the storage provider. The ID must match the ID of the storage provider in the storage_providers section.
PERSISTED_OPERATIONS_STORAGE_OBJECT_PREFIX	persisted_operations.storage.object_prefix		The prefix of the object in the storage provider location. The prefix is put in front of the operation SHA256 hash. $prefix/SHA256.json
PERSISTED_OPERATIONS_LOG_UNKNOWN	persisted_operations.log_unknown		Log operations (sent with the operation body) which haven’t yet been persisted. If the value is true, all operations not yet persisted are logged to the router logs.	false
PERSISTED_OPERATIONS_SAFELIST_ENABLED	persisted_operations.safelist.enabled		Only allows persisted operations (sent with operation body). If the value is true, all operations not explicitly added to the safelist are blocked.	false

Automatic Persisted Queries

The configuration for automatic persisted queries allows you to enable automated caching of select GraphQL operations that can be queried against the router, using both POST and GET requests. This approach enhances performance.

It defaults to using a local cache (with the size defined in cache.size), but users can optionally use a Redis storage

Example YAML config:

config.yaml

version: "1"

automatic_persisted_queries:
  enabled: true
  cache:
    size: 10MB # This is only relevant for an in-memory cache that we maintain
    ttl: 900 # in seconds, set both for a local and a remote KV
  storage:
    provider_id: "my_redis"
    object_prefix: cosmo_apq

Configuration Options

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

Environment Variable	YAML	Required	Description	Default Value
	automatic_persisted_queries		The configuration for the persisted operations.
	automatic_persisted_queries.enabled		Whether or not automatic persisted queries is enabled	true
	automatic_persisted_queries.cache		LRU cache for persisted operations.
	automatic_persisted_queries.cache.size		The size of the cache in SI unit.	”100MB”
	automatic_persisted_queries.cache.ttl		The TTL of the cache, in seconds. Set to 0 to set no TTL
	automatic_persisted_queries.storage		The external storage provider (redis) for automatic persisted operation. Only one provider can be active. When no provider is specified, the router will fallback to using a local in-memory cache (configured in the automatic_persisted_queries.cache options)
	automatic_persisted_queries.storage.provider_id		The ID of the Redis storage provider. The ID must match the ID of the storage provider in the storage_providers.redis section.
	automatic_persisted_queries.storage.object_prefix		The prefix of the object in the storage provider location. The prefix is put in front of the operation SHA256 hash. $prefix/SHA256

Execution Config

The configuration for the execution setup contains instructions for the router to plan and execute your GraphQL operations. You can specify the storage provider from which the configuration should be fetched.

Example YAML config:

config.yaml

version: "1"

execution_config:
  storage:
    provider_id: s3
    object_path: /prod

or

config.yaml

version: "1"

execution_config:
  file:
    path: "./__schemas/config.json"
    watch: true
    watch_interval: "1s"

Execution config options

Environment Variable	YAML	Required	Description	Default Value
	execution_config		The configuration for the execution config.
	file		The configuration for the execution config file. The config file is used to load the execution config from the local file system. The file has precedence over the storage provider.
EXECUTION_CONFIG_FILE_PATH	file.path		The path to the execution config file. The path is used to load the execution config from the local file system.
EXECUTION_CONFIG_FILE_WATCH	file.watch		Enable the watch mode. The watch mode is used to watch the execution config file for changes. If the file changes, the router will reload the execution config without downtime.	true
EXECUTION_CONFIG_FILE_WATCH_INTERVAL	file.watch_interval		The interval at which the file is checked for changes.	1s
	execution_config.storage		The storage provider for the execution config. Only one provider can be active. When no provider is specified, the router will fallback to the Cosmo CDN provider to download the execution config.
EXECUTION_CONFIG_STORAGE_PROVIDER_ID	execution_config.storage.provider_id		The ID of the storage provider. The ID must match the ID of the storage provider in the storage_providers section.
EXECUTION_CONFIG_STORAGE_OBJECT_PATH	execution_config.storage.object_path		The path to the execution config in the storage provider. The path is used to download the execution config from the S3 bucket.
EXECUTION_CONFIG_FALLBACK_STORAGE_ENABLED	execution_config.fallback_storage.enabled		Enable a fallback storage to fetch the execution config in case the above primary source fails.	false
EXECUTION_CONFIG_FALLBACK_STORAGE_PROVIDER_ID	execution_config.fallback_storage.provider_id		The ID of the storage provider. The ID must match the ID of the storage provider in the storage_providers section.
EXECUTION_CONFIG_FALLBACK_STORAGE_OBJECT_PATH	execution_config.fallback_storage.object_path		The path to the execution config in the storage provider. The path is used to download the execution config from the S3 bucket.

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
    max_header_bytes: 1MiB
    decompression_enabled: true
    response_compression_min_size: 4KiB
  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: 90s
    keep_alive_probe_interval: 30s
    max_idle_conns: 1024
    max_conns_per_host: 100
    max_idle_conns_per_host: 20
    # 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
      condition: "IsRetryableStatusCode() || IsConnectionError() || IsTimeout()"
    # Circuit Breaker
    circuit_breaker:
      enabled: true
      request_threshold: 20
      error_threshold_percentage: 50
      sleep_window: 30s
      half_open_attempts: 5
      required_successful: 3
      rolling_duration: 60s
      num_buckets: 10
      execution_timeout: 60s
      max_concurrent_requests: -1

  subgraphs: # allows you to create subgraph specific traffic shaping rules
    products: # Will only affect this subgraph, and override the options in "all" for that subgraph
      request_timeout: 60s
      dial_timeout: 30s
      keep_alive_idle_timeout: 0s
      keep_alive_probe_interval:
      tls_handshake_timeout: 10s
      response_header_timeout: 0s
      expect_continue_timeout: 0s
      max_idle_conns: 1024
      max_conns_per_host: 100
      max_idle_conns_per_host: 20
      # You can configure circuit breakers per subgraph, which includes the above configurations
      circuit_breaker:
        enabled: false

Subgraph Request Rules

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

Environment Variable	YAML	Required	Description	Default Value
	retry		#traffic-shaping-jitter-retry
	circuit_breaker		#circuit-breaker
	request_timeout			60s
	dial_timeout			30s
	response_header_timeout			0s
	expect_continue_timeout			0s
	tls_handshake_timeout			10s
	keep_alive_idle_timeout			90s
	keep_alive_probe_interval			30s
	max_idle_conns			1024
	max_conns_per_host			100
	max_idle_conns_per_host			20

Subgraph specific request rules

In addition to the general traffic shaping rules, we also allow users to set subgraph specific timeout options, overriding the default traffic rules defined in all(if present)

Environment Variable	YAML	Required	Description	Default Value
	request_timeout			60s
	dial_timeout			30s
	response_header_timeout			0s
	expect_continue_timeout			0s
	keep_alive_idle_timeout			90s
	keep_alive_probe_interval			30s
	max_idle_conns			1024
	max_conns_per_host			100
	max_idle_conns_per_host			20

Circuit Breaker

Configure circuit breaker either for all subgraphs, or per subgraph. More information on circuit breakers can be found here.

Environment Variable	YAML	Required	Description	Default Value
	enabled		Enable the circuit breaker for the target (all subgraphs or a specific subgraph).	false
	error_threshold_percentage		This represents the percentage of failed requests within the rolling window that will trigger the circuit to open. For example, with a 50% threshold and 100 total requests in the window, the circuit will open when 50 or more requests fail.	50
	request_threshold		Defines the minimum number of requests that must be received before the circuit breaker will evaluate error rates for potential state transitions.	20
	sleep_window		This setting determines how long the circuit will block all requests after transitioning to the open state. The sleep window serves a critical purpose: it gives the failing service time to recover without being overwhelmed by continued request attempts.	5s
	half_open_attempts		Number of test requests allowed in the half-open state.	1
	required_successful		How many successful requests are needed to close the circuit from the half-open state. This setting works in conjunction with half_open_attempts to determine the recovery behavior.	1
	rolling_duration		The time window for collecting error and request statistics. Only data from within this window influences circuit breaker decisions, ensuring that the circuit responds to current conditions rather than being influenced by historical problems that may have been resolved.	10s
	num_buckets		Number of buckets for statistics in the rolling window (higher = finer granularity).	10
	execution_timeout		The maximum time allocated before marking a request as failed due to timeout. This timeout is specifically for circuit breaker error tracking and operates independently of any actual request timeouts.	60s
	max_concurrent_requests		This controls the maximum number of concurrent requests that the circuit breaker will process simultaneously. When set to the default value of -1, there is no limit on concurrent requests.	-1

Jitter Retry

Environment Variable	YAML	Required	Description	Default Value
RETRY_ENABLED	enabled			true
RETRY_ALGORITHM	algorithm		backoff_jitter	backoff_jitter
RETRY_EXPRESSION	expression		The retry expression used to decide if a failed subgraph request should be retried.	`IsRetryableStatusCode()		IsConnectionError()		IsTimeout()`
RETRY_MAX_ATTEMPTS	max_attempts
RETRY_MAX_DURATION	max_duration
RETRY_INTERVAL	interval

Client Request Request Rules

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

Environment Variable	YAML	Required	Description	Default Value
	max_request_body_size			5mb
MAX_HEADER_BYTES	max_header_bytes		Minimum Router version: 0.156.0 The maximum size of the request headers. Setting this to 0 uses the default value from the http standard lib, which is 1MiB.	1mib
	decompression_enabled		When enabled, the router will check incoming requests for a ‘Content-Encoding’ header and decompress the body accordingly Note: Currently only “gzip” is supported	true
	response_compression_min_size		The minimum size of the response body in bytes to enable response compression. The size is specified as a string with a number and a unit, e.g. 10KB, 1MB, 1GB	4KiB
5mb

WebSocket

Configure WebSocket handlers, protocols, and more.

WebSocket Configuration

Environment Variable	YAML	Required	Description	Default Value
WEBSOCKETS_ENABLED	enabled			true
	absinthe_protocol		Absinthe Protocol Configuration
	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
	forward_upgrade_query_params		Forward all query parameters from the Upgrade Request in the extensions field when subscribing on a Subgraph
	forward_initial_payload		Forward the initial payload from a client subscription in the extensions field when subscribing on a Subgraph	true
	client_info_from_initial_payload		WebSocket Client Info Configuration

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 Variable	YAML	Required	Description	Default Value
WEBSOCKETS_ABSINTHE_ENABLED	enabled			true
WEBSOCKETS_ABSINTHE_HANDLER_PATH	handler_path		The path to mount the Absinthe handler on	/absinthe/socket

WebSocket Authentication

It’s possible that Authentication for a WebSocket connection is not possible at the HTTP layer. In such a case, you can enable Authentication “from_initial_payload”. This will extract a value from the “initial_payload” field in the first WebSocket message which is responsible for negotiating the protocol between client and server.

In addition, it’s possible to export the extracted value into a Request Header, which allows the Router to propagate it using Header Propagation Rules in subsequent Subgraph Requests.

WebSocket Client Info Configuration

Configure how to extract client info from the initial WebSocket payload. This allows you to set client name and version information from the initial connection payload, which can then be forwarded to request headers if needed.

Environment Variable	YAML	Required	Description	Default Value
WEBSOCKETS_CLIENT_INFO_FROM_INITIAL_PAYLOAD_ENABLED	enabled		Enable extracting client info from initial payload	true
WEBSOCKETS_CLIENT_INFO_FROM_INITIAL_PAYLOAD_NAME_FIELD	name_field		The field name in the initial payload to extract the client name from
WEBSOCKETS_CLIENT_INFO_FROM_INITIAL_PAYLOAD_VERSION_FIELD	version_field		The field name in the initial payload to extract the client version from
WEBSOCKETS_CLIENT_INFO_FROM_INITIAL_PAYLOAD_FORWARD_TO_REQUEST_HEADERS_ENABLED	forward_to_request_headers.enabled		Enable forwarding extracted client info to request headers	true
WEBSOCKETS_CLIENT_INFO_FROM_INITIAL_PAYLOAD_NAME_TARGET_HEADER	forward_to_request_headers.name_target_header		The header name to forward the client name to
WEBSOCKETS_CLIENT_INFO_FROM_INITIAL_PAYLOAD_VERSION_TARGET_HEADER	forward_to_request_headers.version_target_header		The header name to forward the client version to

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:
    enabled: true
    allow_list: # an empty list allows all headers
      - "Authorization" # forward only the Authorization Header
  forward_upgrade_query_params:
    enabled: true
    allow_list:
      - "Authorization"
  client_info_from_initial_payload:
    # enable extracting client info from initial payload
    enabled: true
    # the field name in the initial payload to extract the client name from
    name_field: "graphql-client-name"
    # the field name in the initial payload to extract the client version from
    version_field: "graphql-client-version"
    # enable forwarding extracted client info to request headers
    forward_to_request_headers:
      # enable forwarding extracted client info to request headers
      enabled: true
      # the header name to forward the client name to
      name_target_header: "GraphQL-Client-Name"
      # the header name to forward the client version to
      version_target_header: "GraphQL-Client-Version"
  authentication:
    # enable authentication from the initial payload
    from_initial_payload:
      enabled: false
      # which key to use one the initial payload to "extract" the Authorization value
      key: "authorization"
      export_token:
        export_token: false
        # to enable Subgraph authentication, we can export the value into a Header
        header_key: "Authorization"

Authentication

Configure different authentication providers.

New Authentication Config (Router Version ≥ 0.169.0)

JWKS

The following configuration has two flavours

JWKS URL endpoint

This is useful when you want to connect to a JWKS endpoint

YAML	Required	Description	Default Value
url		The URL of the JWKs. The JWKs are used to verify the JWT (JSON Web Token). The URL is specified as a string with the format ‘scheme://host:port’.
refresh_interval		The interval at which the JWKs are refreshed. The period is specified as a string with a number and a unit, e.g. 10ms, 1s, 1m, 1h. The supported units are ‘ms’, ‘s’, ‘m’, ‘h’.	1m
allowed_use		The allowed value of the use parameter for the JWKs. If not specified, only keys with use set to ‘sig’ will be used. If your server provides no use, you can add an empty value to allow those keys.	[“sig”]
algorithms		The allowed algorithms for the keys that are retrieved from the JWKs. An empty list means that all algorithms are allowed. The following algorithms are supported “RS256”, “RS384”, “RS512”, “ES256”, “ES384”, “ES512”, “PS256”, “PS384”, “PS512”, “EdDSA”	[] (all allowed)
refresh_unknown_kid.enabled		Enable automatic JWKS refresh when encountering a valid token with an unknown KID (Key ID). When enabled, the router will fetch updated keys to find the matching KID.	false
refresh_unknown_kid.max_wait		Maximum time a refresh is allowed to wait. If the computed wait would exceed this value, the request fails immediately with 401 Unauthorized instead of waiting.	2m
refresh_unknown_kid.interval		Time between replenishing burst tokens. With burst=1, each subsequent request within the interval must wait for (interval × attempt number).	30s
refresh_unknown_kid.burst		Maximum number of refreshes allowed without waiting. Prevents overloading the JWKS endpoint; beyond this, requests wait until the interval elapses or fail due to max_wait.	2

Secret

This is useful when you have a symmetric key that you cannot expose through a JWKS endpoint, you can use the secret based configuration

YAML	Required	Description	Default Value
secret		The secret value, which will be used to construct the “k” parameter of the JWKS
header_key_id		The key id, this is required as the router use JWK Sets and is used to construct the “kid” attribute which helps identify the correct JWK
symmetric_algorithm		Specify which symmetric algorithm is used for signing, supported algorithms are “HS256”, “HS384”, “HS512”

Audience Validation

In addition to the above JWKS configuration flavours, you can define a list of audiences of which one is required (if specified) with either options.

YAML	Required	Description	Default Value
audiences		The allowed list of audiences, of which at least one audience is required in the token	[]

JWT

YAML	Required	Description	Default Value
header_name		The name of the header. The header is used to extract the token from the request. The default value is ‘Authorization’.	Authorization
header_value_prefix		The prefix of the header value. The prefix is used to extract the token from the header value. The default value is ‘Bearer’.	Bearer

Header Sources

YAML	Required	Description	Default Value
type		The type of the source. The only currently supported type is ‘header’.	header
name		The name of the header. The header is used to extract the token from the request. The default value is ‘Authorization’.	Authorization
value_prefixes		The prefixes of the header value. The prefixes are used to extract the token from the header value. The default value is ‘Bearer’.	Bearer

Example YAML config V2:

authentication:
  jwt:
    jwks:
      - url: "https://example.com/.well-known/jwks.json"
        refresh_interval: 1m
        # Leaving algorithms empty will allow all supported algorithms from the config docs
        refresh_unknown_kid:
          enabled: true
          max_wait: 2m
          interval: 30s
          burst: 2
      - url: "https://example2.com/.well-known/jwks.json"
        refresh_interval: 2m
        # optional list of allowed algorithms per JWKS
        algorithms: ["RS256", "EdDSA", "HS512"]
        refresh_unknown_kid:
          enabled: false # These are defaults
          max_wait: 2m 
          interval: 30s
          burst: 2
    header_name: Authorization # This is the default value
    header_value_prefix: Bearer # This is the default value
    header_sources:
      - type: header
        name: X-Auth-Token
        value_prefixes: [Token, MyToken]
      - type: header
        name: X-Authorization

Bypass Introspection Authentication

This is useful when you want to bypass authentication for introspection queries, for example let certain tools introspect the schema without requiring authentication token.

This feature is meant to be used in secure, internal environments. It is not recommended for use in a production environment. By default, introspection queries are not excluded from authentication. Also consider setting introspection.secret for a static secret dedicated to introspection queries.

Environment Variable	YAML	Required	Description	Default Value
	ignore_introspection		Bypass introspection authentication	false

Old Authentication Config (Router Version < 0.XXX.X)

Provider

Environment Variable	YAML	Required	Description	Default Value
	name		Name of the provider	My Auth Provider
	jwks		JWKS Provider

JWK Provider

Environment Variable	YAML	Required	Description	Default 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 Variable	YAML	Required	Description	Default 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 Variable	YAML	Required	Description	Default Value
CDN_URL	url		The URL of the CDN where the Router will fetch its Config. Not required when a static execution config is provided.	https://cosmo-cdn.wundergraph.com
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 Cosmo Streams / EDFS.

We support NATS, Kafka and Redis as event bus provider.

config.yaml

version: "1"

events:
  providers:
    nats:
      - id: default
        url: "nats://localhost:4222"
        authentication:
          token: "token" # or
          user_info:
            username: "username"
            password: "password"
    kafka:
      - id: my-kafka
        tls:
          enabled: true
        authentication:
          sasl_plain:
            password: "password"
            username: "username"
        brokers:
          - "localhost:9092"
    redis:
      - id: my-redis
        urls:
          - "localhost:9092"

Provider

Environment Variable	YAML	Required	Description	Default Value
	providers		one of: nats, kafka, redis

NATS Provider

Environment Variable	YAML	Required	Description	Default Value
	id		The ID of the provider. This have to match with the ID specified in the subgraph schema.
	url		NATS Connection string
	authentication		Authentication configuration for the NATS provider.
	authentication.token		Token based authentication.
	authentication.user_info		User-Info based authentication.
	authentication.user_info.username		Username.
	authentication.user_info.password		Password.

Kafka Provider

Environment Variable	YAML	Required	Description	Default Value
	id		The ID of the provider. This have to match with the ID specified in the subgraph schema.	[]
	brokers		A list of broker URLs.
	authentication		Authentication settings
	authentication.sasl_plain		SASL/Plain Authentication method
	authentication.sasl_plain.username		SASL/Plain Username
	authentication.sasl_plain.password		SASL/Plain Password
	authentication.sasl_scram		SASL/SCRAM Authentication method
	authentication.sasl_scram.username		SASL/SCRAM Username
	authentication.sasl_scram.password		SASL/SCRAM Password
	authentication.sasl_scram.mechanism		SASL/SCRAM Mechanism, could be SCRAM-SHA-256 of SCRAM-SHA-512
	tls		TLS configuration for the Kafka provider. If enabled, it uses SystemCertPool for RootCAs by default.
	tls.enabled		Enable the TLS.

Redis Provider

Environment Variable	YAML	Required	Description	Default Value
	id		The ID of the provider. This have to match with the ID specified in the subgraph schema.	[]
	urls		A list of redis instances URLS, e.g: redis://localhost:6379/2

Cosmo Streams handlers

Configuration for Cosmo Streams handlers. Learn more about Custom Modules for Cosmo Streams.

Environment Variable	YAML	Required	Description	Default Value
	handlers.on_receive_events.handler_timeout		The maximum time to wait for all OnReceiveEvents handlers to complete per event-batch.	5s
	handlers.on_receive_events.max_concurrent_handlers		The maximum number of concurrent OnReceiveEvents handlers per trigger.	100

Router Engine Configuration

Configure the GraphQL Execution Engine of the Router.

Environment Variable	YAML	Required	Description	Default 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		Deprecated, use “enable_cache_response_headers” instead. 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.	32
ENGINE_ENABLE_NET_POLL	enable_net_poll		Enables the more efficient poll implementation for all WebSocket implementations (client, server) of the router. This is only available on Linux and MacOS. On Windows or when the host system is limited, the default synchronous implementation is used.	true
ENGINE_WEBSOCKET_CLIENT_POLL_TIMEOUT	websocket_client_poll_timeout		The timeout for the poll loop of the WebSocket client implementation. The period is specified as a string with a number and a unit	1s
ENGINE_WEBSOCKET_CLIENT_CONN_BUFFER_SIZE	websocket_client_conn_buffer_size		The buffer size for the poll buffer of the WebSocket client implementation. The buffer size determines how many connections can be handled in one loop.	128
ENGINE_WEBSOCKET_CLIENT_READ_TIMEOUT	websocket_client_read_timeout		The timeout for the websocket read of the WebSocket client implementation.	5s
ENGINE_WEBSOCKET_CLIENT_WRITE_TIMEOUT	websocket_client_write_timeout		The timeout for the websocket write of the WebSocket client implementation.	10s
ENGINE_WEBSOCKET_CLIENT_PING_INTERVAL	websocket_client_ping_interval		The Websocket client ping interval to the subgraph. Defines how often the router will ping the subgraph to signal that the connection is still alive. Timeout needs to be coordinated with the subgraph. The timeout is specified as a string with a number and a unit, e.g. 10ms, 1s, 1m, 1h. The supported units are ‘ms’, ‘s’, ‘m’, ‘h’.	15s
ENGINE_WEBSOCKET_CLIENT_PING_TIMEOUT	websocket_client_ping_timeout		The Websocket client ping timeout to the subgraph. Defines how long the router will wait for a ping response from the subgraph. The timeout is specified as a string with a number and a unit, e.g. 10ms, 1s, 1m, 1h. The supported units are ‘ms’, ‘s’, ‘m’, ‘h’.	30s
ENGINE_WEBSOCKET_CLIENT_FRAME_TIMEOUT	websocket_client_frame_timeout		The Websocket client frame timeout to the subgraph. Defines how long the router will wait for a frame response from the subgraph. The timeout is specified as a string with a number and a unit, e.g. 10ms, 1s, 1m, 1h. The supported units are ‘ms’, ‘s’, ‘m’, ‘h’.	100ms
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.	1024
ENGINE_MINIFY_SUBGRAPH_OPERATIONS	minify_subgraph_operations		Minify the subgraph operations. If the value is true, GraphQL Operations get minified after planning. This reduces the amount of GraphQL AST nodes the Subgraph has to parse, which ultimately saves CPU time and memory, resulting in faster response times.	false
ENGINE_ENABLE_PERSISTED_OPERATIONS_CACHE	enable_persisted_operations_cache		Enable the persisted operations cache. The persisted operations cache is used to cache normalized persisted operations to improve performance.	true
ENGINE_ENABLE_NORMALIZATION_CACHE	enable_normalization_cache		Enable the normalization cache. The normalization cache is used to cache normalized operations to improve performance.	true
ENGINE_NORMALIZATION_CACHE_SIZE	normalization_cache_size		The size of the normalization cache.	1024
ENGINE_PARSEKIT_POOL_SIZE	parsekit_pool_size		The size of the ParseKit pool. The ParseKit pool provides re-usable Resources for parsing, normalizing, validating and planning GraphQL Operations. Setting the pool size to a value much higher than the number of CPU Threads available will not improve performance, but only increase memory usage.	8
ENGINE_RESOLVER_MAX_RECYCLABLE_PARSER_SIZE	resolver_max_recyclable_parser_size		Limits the size of the Parser that can be recycled back into the Pool. If set to 0, no limit is applied. This helps keep the Heap size more maintainable if you regularly perform large queries.	32768
ENGINE_ENABLE_VALIDATION_CACHE	enable_validation_cache		Enable the validation cache. The validation cache is used to cache results of validating GraphQL Operations.	true
ENGINE_VALIDATION_CACHE_SIZE	validation_cache_size		The size of the validation cache.	1024
ENGINE_DISABLE_EXPOSING_VARIABLES_CONTENT_ON_VALIDATION_ERROR	disable_exposing_variables_content_on_validation_error		Disables exposing the variables content in the error response. This is useful to avoid leaking sensitive information in the error response.	false
ENGINE_ENABLE_SUBGRAPH_FETCH_OPERATION_NAME	enable_subgraph_fetch_operation_name		Enable appending the operation name to subgraph fetches. This will ensure that the operation name will be included in the corresponding subgraph requests using the following format: $OperationName__$SubgraphName__$FetchID.	false
ENGINE_ENABLE_REQUIRE_FETCH_REASONS	enable_require_fetch_reasons		Enable the openfed__requireFetchReasons directive, and forces the adding of the “fetch_reasons” extension to upstream subgraph requests. This extension explains why each field was requested.	false
ENGINE_VALIDATE_REQUIRED_EXTERNAL_FIELDS	validate_required_external_fields		Validate nullable external “@requires” dependencies. When a subgraph entity fetch returns a null value with an error for a field set specified in the “@requires” directive, any following fetch that depends on it should not receive such an entity.	false
ENGINE_SUBSCRIPTION_FETCH_TIMEOUT	subscription_fetch_timeout		The maximum time a subscription fetch can take before it is considered timed out.	30s

Example YAML config:

config.yaml

version: "1"

engine:
  enable_single_flight: true
  enable_request_tracing: true
  max_concurrent_resolvers: 32
  enable_websocket_epoll_kqueue: true
  epoll_kqueue_poll_timeout: "1s"
  epoll_kqueue_conn_buffer_size: 128
  websocket_client_read_timeout: "1s"
  websocket_client_write_timeout: "5s"
  websocket_client_ping_interval: "15s"
  websocket_client_ping_timeout: "30s"
  websocket_client_frame_timeout: "100ms"
  execution_plan_cache_size: 10000
  minify_subgraph_operations: true
  enable_persisted_operations_cache: true
  enable_normalization_cache: true
  normalization_cache_size: 1024
  parsekit_pool_size: 8
  enable_validation_cache: true
  validation_cache_size: 1024
  disable_exposing_variables_content_on_validation_error: false
  enable_subgraph_fetch_operation_name: true
  subscription_fetch_timeout: 30s

Debug Configuration

Environment Variable	YAML	Required	Description	Default Value
ENGINE_DEBUG_PRINT_OPERATION_TRANSFORMATIONS	print_operation_transformations		Print the operation transformations.	false
ENGINE_DEBUG_PRINT_OPERATION_ENABLE_AST_REFS	print_operation_enable_ast_refs		Print the operation enable AST refs.	false
ENGINE_DEBUG_PRINT_PLANNING_PATHS	print_planning_paths		Print the planning paths.	false
ENGINE_DEBUG_PRINT_QUERY_PLANS	print_query_plans		Print the query plans.	false
ENGINE_DEBUG_PRINT_NODE_SUGGESTIONS	print_node_suggestions		Print the node suggestions.	false
ENGINE_DEBUG_CONFIGURATION_VISITOR	configuration_visitor		Print the configuration visitor.	false
ENGINE_DEBUG_PLANNING_VISITOR	planning_visitor		Print the planning visitor.	false
ENGINE_DEBUG_DATASOURCE_VISITOR	datasource_visitor		Print the datasource visitor.	false
ENGINE_DEBUG_REPORT_WEBSOCKET_CONNECTIONS	report_websocket_connections		Print the websocket connections.	false
ENGINE_DEBUG_REPORT_MEMORY_USAGE	report_memory_usage		Print the memory usage.	false
ENGINE_DEBUG_ENABLE_RESOLVER_DEBUGGING	enable_resolver_debugging		Enable verbose debug logging for the Resolver.	false
ENGINE_DEBUG_ENABLE_CACHE_RESPONSE_HEADERS	enable_cache_response_headers		Enable hit/miss response headers for the normalization caches (“X-WG-Normalization-Cache”, “X-WG-Variables-Normalization-Cache”, “X-WG-Variables-Remapping-Cache”), the persisted operations cache (“X-WG-Persisted-Operation-Cache”), and the execution plan cache (“X-WG-Execution-Plan-Cache”).	false
ENGINE_DEBUG_ENABLE_PERSISTED_OPERATIONS_CACHE_RESPONSE_HEADER	enable_persisted_operations_cache_response_header		Deprecated, use “enable_cache_response_headers” instead. Enable the persisted operations cache response header. The persisted operations cache response header is used to cache the persisted operations in the client.	false
ENGINE_DEBUG_ENABLE_NORMALIZATION_CACHE_RESPONSE_HEADER	enable_normalization_cache_response_header		Deprecated, use “enable_cache_response_headers” instead. Enable the normalization cache response header. The normalization cache response header is used to cache the normalized operations in the client.	false
ENGINE_DEBUG_ALWAYS_INCLUDE_QUERY_PLAN	always_include_query_plan		Always include the query plan in the response.	false
ENGINE_DEBUG_ALWAYS_SKIP_LOADER	always_skip_loader		Always skip the loader. This will return no data but only render response extensions, e.g. to expose the query plan.	false

Example YAML config:

config.yaml

version: "1"

engine:
  debug:
    print_operation_transformations: false
    print_operation_enable_ast_refs: false
    print_planning_paths: false
    print_query_plans: false
    print_node_suggestions: false
    configuration_visitor: false
    planning_visitor: false
    datasource_visitor: false
    report_websocket_connections: false
    report_memory_usage: false
    enable_resolver_debugging: false
    enable_persisted_operations_cache_response_header: false
    enable_normalization_cache_response_header: false
    always_include_query_plan: false
    always_skip_loader: 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.

Key Suffix Expression

As you can see in the config table below, you can define an expression to generate the a rate limiting key suffix. The evaluation of the expression must return a string, which will be appended to the key prefix.

Using a key suffix expression, you’re able to dynamically choose a rate limiting key, e.g. based on the user authentication, a header, or a combination. Here’s an example expression that uses the sub claim if available, and a Header as the fallback.

request.auth.claims.sub ?? request.header.Get('X-Forwarded-For')

For mor information on how to use the expression language, please refer to the Template Expressions section.

General Rate Limiting Configuration

Environment Variable	YAML	Required	Description	Default Value
RATE_LIMIT_ENABLED	enabled		Enable / Disable rate limiting globally	false
RATE_LIMIT_STRATEGY	strategy		The rate limit strategy to use	simple
	simple_strategy		[
Rate Limiting Simple Strategy](/router/configuration#rate-limiting-simple-strategy)	simple
	storage		Rate Limiting Redis Storage
RATE_LIMIT_KEY_SUFFIX_EXPRESSION	key_suffix_expression		The expression to define a key suffix for the rate limit, e.g. by using request headers, claims, or a combination of both with a fallback strategy. The expression is specified as a string and needs to evaluate to a string. Please see https://expr-lang.org/ for more information.
	error_extension_code
Rate Limit Error Extension Code

Rate Limiting Redis Storage

Environment Variable	YAML	Required	Description	Default Value
RATE_LIMIT_REDIS_URLS	urls		List of the connection URL(s).	[redis://localhost:6379]
RATE_LIMIT_REDIS_CLUSTER_ENABLED	cluster_enabled		If the Redis instance is a Redis cluster	false
RATE_LIMIT_REDIS_KEY_PREFIX	key_prefix		This prefix is used to namespace the ratelimit keys	cosmo_rate_limit

Rate Limiting Simple Strategy

Environment Variable	YAML	Required	Description	Default 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
RATE_LIMIT_SIMPLE_HIDE_STATS_FROM_RESPONSE_EXTENSION	hide_stats_from_response_extension		Hide the rate limit stats from the response extension. If the value is true, the rate limit stats are not included in the response extension.	false

Rate Limit Error Extension Code

Environment Variable	YAML	Required	Description	Default Value
RATE_LIMIT_ERROR_EXTENSION_CODE_ENABLED	enabled		If enabled, a code will be added to the extensions.code field of error objects related to rate limiting. This allows clients to easily identify if an error happened due to rate limiting.	true
RATE_LIMIT_ERROR_EXTENSION_CODE	code		The code to add to the extensions.code field of error objects related to rate limiting.	RATE_LIMIT_EXCEEDED

Rate Limiting Example YAML configuration

config.yaml

rate_limit:
    enabled: true
    strategy: "simple"
    simple_strategy:
        rate: 10
        burst: 10
        period: 1s
        reject_exceeding_requests: false
        reject_status_code: 200
        hide_stats_from_response_extension: false
    storage:
        cluster_enabled: false
        urls:
         - "redis://localhost:6379"
        key_prefix: "cosmo_rate_limit"
    debug: false
    key_suffix_expression: ""
    error_extension_code:
        enabled: true
        code: "RATE_LIMIT_EXCEEDED"

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 Variable	YAML	Required	Description	Default 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, the location field of Subgraph errors will be omitted.	true
SUBGRAPH_ERROR_PROPAGATION_OMIT_EXTENSIONS	omit_extensions		Omit the extensions field of Subgraph errors. If the value is true, the extensions field of Subgraph errors will be omitted.	false
SUBGRAPH_ERROR_PROPAGATION_STATUS_CODES	propagate_status_codes		Propagate Subgraph status codes. If the value is true, Subgraph Response status codes will be propagated to the client in the errors.extensions.code field.	false
SUBGRAPH_ERROR_PROPAGATION_ALLOWED_FIELDS	allowed_fields		In passthrough mode, by default only message and path is propagated. You can specify additional fields here.
SUBGRAPH_ERROR_PROPAGATION_DEFAULT_EXTENSION_CODE	default_extension_code		The default extension code. The default extension code is used to specify the default code for the Subgraph errors when the code is not present.	DOWNSTREAM_SERVICE_ERROR
SUBGRAPH_ERROR_PROPAGATION_ATTACH_SERVICE_NAME	attach_service_name		Attach the service name to each Subgraph error. If the value is true, the service name will be attached to the Subgraph errors.	true
SUBGRAPH_ERROR_PROPAGATION_ALLOWED_EXTENSION_FIELDS	allowed_extension_fields		The allowed extension fields. The allowed extension fields are used to specify which fields of the Subgraph errors are allowed to be propagated to the client.	[“code”]
SUBGRAPH_ERROR_PROPAGATION_ALLOW_ALL_EXTENSION_FIELDS	allow_all_extension_fields		Allow all extension fields from Subgraph errors to be propagated to the client. If the value is true (default: false), all extension fields from Subgraph errors will be propagated, overriding the allowed_extension_fields configuration.	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 # If true, overrides allowed_extension_fields and allow_all_extension_fields
  default_extension_code: DOWNSTREAM_SERVICE_ERROR
  attach_service_name: true
  allow_all_extension_fields: false # If true, overrides allowed_extension_fields
  allowed_extension_fields:
    - "code"

See Subgraph Error Propagation for more detailed information.

Security

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

Environment Variable	YAML	Required	Description	Default Value
SECURITY_BLOCK_MUTATIONS	block_mutations		Block mutation Operations.
SECURITY_BLOCK_MUTATIONS_ENABLED	block_mutations.enabled		If the value is true, the mutations are blocked.	false
SECURITY_BLOCK_MUTATIONS_CONDITION	block_mutations.condition		The expression to evaluate if the operation should be blocked.
SECURITY_BLOCK_SUBSCRIPTIONS	block_subscriptions		Block subscription Operations.
	block_subscriptions.enabled		If the value is true, the subscriptions are blocked.	false
	block_subscriptions.condition		The expression to evaluate if the operation should be blocked.
SECURITY_BLOCK_NON_PERSISTED_OPERATIONS	block_non_persisted_operations		Block non-persisted Operations.
SECURITY_BLOCK_NON_PERSISTED_OPERATIONS_ENABLED	block_non_persisted_operations.enabled		If the value is true, the non-persisted operations are blocked.	false
SECURITY_BLOCK_NON_PERSISTED_OPERATIONS_CONDITION	block_non_persisted_operations.condition		The expression to evaluate if the operation should be blocked.
SECURITY_BLOCK_PERSISTED_OPERATIONS	block_persisted_operations		Block persisted Operations.
SECURITY_BLOCK_PERSISTED_OPERATIONS_ENABLED	block_persisted_operations.enabled		If the value is true, the persisted operations are blocked.	false
SECURITY_BLOCK_PERSISTED_OPERATIONS_CONDITION	block_persisted_operations.condition		The expression to evaluate if the operation should be blocked.
	complexity_calculation_cache		Complexity Cache configuration
	complexity_limits		Complexity limits configuration
	parser_limits.approximate_depth_limit		The approximate cumulative depth limit of a query, including fragments. Set to 0 to disable.	200
	parser_limits.total_fields_limit		The total number of fields the parser will allow. Set to 0 to disable.	3500
SECURITY_OPERATION_NAME_LENGTH_LIMIT	operation_name_length_limit		The maximum allowed length for the operation name. Set to 0 to disable.	512

Example YAML Configuration

version: "1"

security:
  block_mutations:
    enabled: false
    condition: "request.header.Get('x-block-mutation') == 'yes'"
  block_subscriptions:
    enabled: false
  block_non_persisted_operations:
    enabled: false
  block_persisted_operations:
    enabled: false
  complexity_calculation_cache: # This is for a local in-memory cache, to persist the calculation results
    enabled: true
    size: 1024
  complexity_limits:
    depth: # the equivalent of `security.depth_limit` prevoiusly
      enabled: true
      limit: 7
      ignore_persisted_operations: true
    total_fields:
      enabled: true
      limit: 128
      ignore_persisted_operations: true
    root_fields:
      enabled: true
      limit: 3
      ignore_persisted_operations: true
    root_field_aliases:
      enabled: false
      limit: 3
      ignore_persisted_operations: true
  parser_limits:
    approximate_depth_limit: 300
    total_fields_limit: 700
  operation_name_length_limit: 1024

Query Depth is now deprecated. We recommend using the security.complexity_calculation_cache and security.complexity_limits configurations instead, which provide that functionality.

Complexity Calculation Cache

The configuration for the in-memory complexity cache, to help speed up the calculation process in the event of a recurring query

Environment Variable	YAML	Required	Description	Default Value
SECURITY_COMPLEXITY_CACHE_ENABLED	enabled		Enable the complexity cache	false
SECURITY_COMPLEXITY_CACHE_SIZE	size		The size of the complexity cache	1024

Complexity Limits

The configuration for adding a complexity limits for queries. We currently expose 4 limits:

• Query Depth - How many nested levels you can have in a query. This limit prevents infinite querying, and also limits the size of the data returned.
• Total Fields in Query
• Root Fields in Query
• Root Field Aliases in Query

For all of the limits, if the limit is 0, or enabled isn’t true, the limit isn’t applied. All of them have the same configuration fields:

Environment Variable	YAML	Required	Description	Default Value
	enabled		Enable the specific limit. If the value is true (default: false), and a valid limit value is set, the limit will be applied	false
	limit		The limit amount for query. If the limit is 0, this limit isn’t applied	0
	ignore_persisted_operations		Disable the limit for persisted operations. Since persisted operations are stored intentionally, users may want to disable the limit to consciously allow nested persisted operations	false

File Upload

The configuration for file upload. Configure whether it should be enabled along with file size and number of files.

Environment Variable	YAML	Required	Description	Default Value
FILE_UPLOAD_ENABLED	enabled		Whether the feature is enabled or not	true
FILE_UPLOAD_MAX_FILE_SIZE	max_file_size		The maximum size of a file that can be uploaded. The size is specified as a string with a number and a unit, e.g. 10KB, 1MB, 1GB. The supported units are ‘KB’, ‘MB’, ‘GB’.	50MB
FILE_UPLOAD_MAX_FILES	max_files		The maximum number of files that can be uploaded per request.	2

Example YAML Configuration

version: "1"

file_upload:
  enabled: true
  max_file_size: 1GB
  max_files: 2

Client Header

The configuration for custom names for client name and client version headers.

Environment Variable	YAML	Required	Description	Default Value
	name		The custom name of the client name header.
	version		The custom name of the client version header.

Example YAML Configuration

version: "1"

client_header:
  name: "Client-Name"
  version: "Client-Version"

By default, we support Graphql-Client-Name , Graphql-Client-Version, Apollo-Graphql-Client-Name, Apollo-Graphql-Client-Version.

The custom names are given more precedence.

Apollo Compatibility Flags

This configuration is used to enable full compatibility with Apollo Federation, Apollo Gateway and Apollo Router, you can enable certain compatibility flags, allowing you to use Cosmo Router as a drop-in replacement for Apollo.

Apollo Compatibility Value Completion

Invalid __typename values will be returned in extensions.valueCompletion instead of errors.

Apollo Compatibility Truncate Floats

Truncate floats like 1.0 to 1, 2.0 to 2, etc.. Values like 1.1 or 2.2 will not be truncated.

Apollo Compatibility Suppress Fetch Errors

Suppresses fetch errors. When enabled, only the ‘data’ object is returned, suppressing errors. If disabled, fetch errors are included in the ‘errors’ array.

Apollo Compatibility Replace Undefined Op Field Errors (Deprecated)

This flag is deprecated. Use use_graphql_validation_failed_status instead.

Produces the same error message as Apollo when an invalid operation field is included in an operation selection set. Extension code: “GRAPHQL_VALIDATION_FAILED” Status code: 400

Apollo Compatibility Use GraphQL Validation Failed Status

Produces the same error message and status as Apollo when GraphQL validation fails. Extension code: “GRAPHQL_VALIDATION_FAILED” Status code: 400

Apollo Compatibility Replace Invalid Var Errors

Produces the same error message as Apollo when an invalid variable is supplied. Extension code: “BAD_USER_INPUT”

Apollo Compatibility Replace Validation Error Status

Produces the same error status as Apollo when validation fails. Error status: 400 Bad Request Minimum router version: 0.175.0

Environment Variable	YAML	Required	Description	Default Value
APOLLO_COMPATIBILITY_ENABLE_ALL	apollo_compatibility_flags: enable_all: <bool>		Enables all the options of Apollo Compatibility.	false
APOLLO_COMPATIBILITY_VALUE_COMPLETION_ENABLED	value_completion: enabled: <bool>		Enables value completion.	false
APOLLO_COMPATIBILITY_TRUNCATE_FLOATS_ENABLED	truncate_floats: enabled: <bool>		Enables truncate floats.	false
APOLLO_COMPATIBILITY_SUPPRESS_FETCH_ERRORS_ENABLED	suppress_fetch_errors: enabled: <bool>		Enables suppress fetch errors.	false
APOLLO_COMPATIBILITY_REPLACE_UNDEFINED_OP_FIELD_ERRORS_ENABLED	replace_undefined_op_field_errors: enabled: <bool>		Deprecated. Replaces undefined operation field errors. Use use_graphql_validation_failed_status instead.	false
APOLLO_COMPATIBILITY_REPLACE_INVALID_VAR_ERRORS_ENABLED	replace_invalid_var_errors: enabled: <bool>		Replaces invalid variable errors.	false
APOLLO_COMPATIBILITY_REPLACE_VALIDATION_ERROR_STATUS_ENABLED	replace_validation_error_status: enabled: <bool>		Replaces validation error status with 400.	false
APOLLO_COMPATIBILITY_SUBSCRIPTION_MULTIPART_PRINT_BOUNDARY_ENABLED	subscription_multipart_print_boundary: enabled: <bool>		Prints the multipart boundary right after the message in multipart subscriptions. Without this flag, the Apollo client wouldn’t parse a message until the next one is pushed.	false
APOLLO_COMPATIBILITY_USE_GRAPHQL_VALIDATION_FAILED_STATUS_ENABLED	use_graphql_validation_failed_status: enabled: <bool>		Uses GraphQL validation failed status code and error format.	false

Example YAML Configuration

version: "1"

apollo_compatibility_flags:
  enable_all: false
  value_completion:
    enabled: true
  truncate_floats:
    enabled: false
  suppress_fetch_errors:
    enabled: true
  replace_undefined_op_field_errors:
    enabled: true # Deprecated, use use_graphql_validation_failed_status instead
  replace_invalid_var_errors:
    enabled: true
  replace_validation_error_status:
    enabled: false
  subscription_multipart_print_boundary:
    enabled: false
  use_graphql_validation_failed_status:
    enabled: true

Apollo Router Compatibility Flags

Apollo Router Compatibility Flags can be enabled alongside Apollo Compatibility Flags, but some will override their counterpart’s functionality. This means you can safely use enable_all: true alongside these flags.

Apollo Router Compatibility Replace Invalid Var Errors

Produces the same error messages as Apollo Router when an invalid variable is supplied.

Extension code: “VALIDATION_INVALID_TYPE_VARIABLE”

Environment Variable	YAML	Required	Description	Default Value
APOLLO_ROUTER_COMPATIBILITY_REPLACE_INVALID_VAR_ERRORS_ENABLED	replace_invalid_var_errors		Replaces invalid variable errors.	false

Example YAML Configuration

version: "1"

apollo_router_compatibility_flags:
  replace_invalid_var_errors:
    enabled: true

Cache warmer

Environment Variable	YAML	Required	Description	Default Value
CACHE_WARMUP_ENABLED	enabled		Enable the cache warmer.	false
CACHE_WARMUP_ITEMS_PER_SECOND	items_per_second		The number of cache warmup items to process per second. Higher numbers decrease the time to warm up the cache but increase the load on the system.	50
CACHE_WARMUP_TIMEOUT	timeout		The timeout for warming up the cache. This can be used to limit the amount of time cache warming will block deploying a new config. The period is specified as a string with a number and a unit, e.g. 10ms, 1s, 1m, 1h. The supported units are ‘ms’, ‘s’, ‘m’, ‘h’.	30s
CACHE_WARMUP_WORKERS	workers		The number of workers for the cache warmup to run in parallel. Higher numbers decrease the time to warm up the cache but increase the load on the system.	8
	source		The source of the cache warmup items. Only one can be specified. If empty, the cache warmup source is the Cosmo CDN and it requires a graph to be set.
CACHE_WARMUP_IN_MEMORY_FALLBACK	in_memory_fallback		Enable in-memory switchover that persists the plan cache across router restarts. When enabled, the router will use queries from the previous instance’s plan cache to warm up the new cache on restart. Can be used as a fallback or as the primary source for cache warming.	true

Example YAML config:

config.yaml

version: "1"

cache_warmup:
  enabled: true
  workers: 8
  items_per_second: 50
  timeout: 30s
  in_memory_fallback: true

Source

The source of the cache warmup items. Only one can be specified. If empty, the cache warmup source is the Cosmo CDN and it requires a graph to be set.

Environment Variable	YAML	Required	Description	Default Value
	filesystem.path		The path to the directory containing the cache warmup items.
	cdn.enabled		Whether the CDN is the source for warming the cache.	true

Example YAML config:

config.yaml

version: "1"

cache_warmup:
  enabled: true
  workers: 8
  items_per_second: 50
  timeout: 30s
  in_memory_fallback: true
  source:
    cdn:
      enabled: true
    filesystem:
      path: "./cache-warmer/operations"