traffic_shaping

The traffic_shaping configuration object provides control over how the Hive Router manages connections and executes requests to your subgraph services.

These settings are crucial for ensuring the router operates efficiently under load and for protecting your downstream subgraphs from being overwhelmed. For a detailed guide on how to tune these settings, see the Performance Tuning & Traffic Shaping Guide.

max_connections_per_host

• Type: integer
• Default: 100

Limits the maximum number of concurrent HTTP connections the router will open to a single subgraph host. This acts as a safeguard to prevent overwhelming a subgraph with too many simultaneous requests.

Inbound Options

The following options are set under traffic_shaping.router and control behaviour of the router itself (i.e. how it handles incoming client requests).

router.dedupe

Configures inbound in-flight request deduplication. When enabled, identical concurrent incoming GraphQL query requests are coalesced into a single execution, with the result shared among all waiting clients. Subscriptions are also deduplicated: N clients subscribing to the same operation with the same variables result in exactly one upstream subgraph connection, with events fanned out to all connected clients via a broadcast channel.

This is distinct from the outbound dedupe_enabled, which deduplicates the requests the router sends to subgraphs.

For a detailed explanation and tuning guidance see the Request Deduplication section of the Performance Tuning guide.

router.dedupe.enabled

• Type: boolean
• Default: false

Enables or disables inbound in-flight request deduplication.

traffic_shaping:
  router:
    dedupe:
      enabled: true

router.dedupe.headers

• Type: string | object
• Default: "all"

Controls which request headers are factored into the deduplication fingerprint. Header names are case-insensitive and validated as standard HTTP header names.

traffic_shaping:
  router:
    dedupe:
      enabled: true
      headers: all

traffic_shaping:
  router:
    dedupe:
      enabled: true
      headers: none

traffic_shaping:
  router:
    dedupe:
      enabled: true
      headers:
        include:
          - authorization
          - cookie

router.max_long_lived_clients

• Type: integer
• Default: 128

traffic_shaping:
  router:
    max_long_lived_clients: 256

Limits the maximum number of concurrent long-lived client connections: WebSocket connections and HTTP streaming responses (SSE, Incremental Delivery, Multipart HTTP). When the limit is reached, new long-lived connection attempts are rejected with 503 Service Unavailable and a Retry-After: 5 response header. Regular HTTP requests (queries and mutations) are not affected.

This limit only activates when at least one of WebSocket or Subscriptions is enabled. Setting it to 0 disables the limit entirely.

router.tls (Client ↔ Router)

Use this configuration field to make the router serve HTTPS traffic (TLS) and optionally require client certificates (mTLS). For a conceptual overview and step-by-step setup, see TLS & mTLS.

• cert_file (required): Router server certificate file path, or a list of certificate file paths.
• key_file (required): Router server private key file path.
• client_auth.cert_file (optional): Trusted client CA certificate file path, or a list of certificate file paths.
• client_auth.required (optional, default true): Whether client certificates are required when client_auth is set.

traffic_shaping:
  router:
    tls:
      cert_file: /etc/router/tls/server.crt
      key_file: /etc/router/tls/server.key

traffic_shaping:
  router:
    tls:
      cert_file:
        - /etc/router/tls/server.crt
        - /etc/router/tls/intermediate.crt
      key_file: /etc/router/tls/server.key
      client_auth:
        cert_file: /etc/router/tls/client-ca.crt
        required: true

Outbound Options

The following options (dedupe_enabled, pool_idle_timeout, request_timeout, and tls) can be set globally for all subgraphs or overridden on a per-subgraph basis by nesting them under the subgraph's name within the traffic_shaping map.

For example, the following example shows how to set global defaults and override them for a specific subgraph named products:

traffic_shaping:
  max_connections_per_host: 150
  all:
    pool_idle_timeout: 60s
  subgraphs:
    products:
      dedupe_enabled: false
      pool_idle_timeout: 120s

dedupe_enabled

• Type: boolean
• Default: true

Enables or disables in-flight request deduplication. When true, identical, concurrent requests to a subgraph are coalesced into a single request, with the response being shared among all clients.

pool_idle_timeout

• Type: string
• Default: 50s

Controls the timeout in duration string format (e.g. 1m for 1 minute, 30s for 30 seconds) for idle keep-alive connections in the router's connection pool. Connections that are unused for this duration will be closed.

This example configuration increases the connection limit for a high-capacity subgraph and sets a longer idle timeout.

traffic_shaping:
  subgraphs:
    high_capacity_subgraph:
      pool_idle_timeout: 90s

request_timeout

• Default: 30s

Request timeout in duration string format (e.g. 30s for 30 seconds, 1m for 1 minute). This setting specifies the maximum time the router will wait for a response from a subgraph before timing out the request. By default, the router will wait up to 30 seconds for a subgraph to respond.

The value for request_timeout must be a valid duration string or a VRL expression that evaluates to a duration string.

Static

• Type: string

When a static duration string is provided, it sets a fixed timeout for all requests to subgraphs.

traffic_shaping:
  all:
    request_timeout: 30s

Dynamic

• Type: object

When an object is provided, it must contain a VRL expression that evaluates to a duration string. The expression is evaluated for each request, allowing for dynamic timeout values based on request characteristics.

• expression: (string, required) A VRL expression that computes the request timeout duration.

Within the expression, you have access to the following context:

• .request: The incoming HTTP request object, including its headers.
• .default: The default timeout value set at the global level (available for subgraph overrides).

traffic_shaping:
  all:
    request_timeout:
      expression: |
        if .request.headers."X-Priority" == "high" {
          "10s"
        } else {
          "60s"
        }
  subgraphs:
    product:
      request_timeout:
        expression: |
          if .request.headers."X-Region" == "Europe" {
            "10s"
          } else {
            .default
          }

This example sets a shorter timeout for high-priority requests based on a custom header, and configures the product subgraph to have a different timeout for requests originating from Europe.

tls (Router ↔ Subgraphs)

Use these configuration fields to configure TLS for outbound requests from the router to subgraphs. For a conceptual overview and step-by-step setup, see TLS & mTLS.

• all.tls: global default TLS config for all subgraphs.
• subgraphs.<name>.tls: per-subgraph override.

Supported fields:

• cert_file (optional): Trusted subgraph CA certificate file path, or a list of certificate file paths.
• client_auth.cert_file + client_auth.key_file (optional): Router client certificate and key for mTLS to subgraphs.
• insecure_skip_ca_verification (optional, default false): Disables server certificate verification.

When both all.tls and subgraphs.<name>.tls are set, the subgraph config overrides the matching global fields. Fields not set in the subgraph config fall back to all.tls.

traffic_shaping:
  all:
    tls:
      cert_file: /etc/router/tls/subgraph-ca.crt
  subgraphs:
    payments:
      tls:
        cert_file: /etc/router/tls/payments-ca.crt
    accounts:
      tls:
        cert_file: /etc/router/tls/accounts-ca.crt
        client_auth:
          cert_file: /etc/router/tls/router-client.crt
          key_file: /etc/router/tls/router-client.key