From bf2798f5775e139058759be56b478fc0aff264bf Mon Sep 17 00:00:00 2001 From: Arda TANRIKULU Date: Mon, 3 Nov 2025 15:24:30 +0300 Subject: [PATCH 1/5] docs(router): new `pool_idle_timeout` --- .../src/content/router/configuration/traffic_shaping.mdx | 8 ++++---- .../docs/src/content/router/guides/performance-tuning.mdx | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx b/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx index 03c4115c40d..c2e930a83a2 100644 --- a/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx +++ b/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx @@ -30,10 +30,10 @@ Limits the maximum number of concurrent HTTP connections the router will open to host. This acts as a safeguard to prevent overwhelming a subgraph with too many simultaneous requests. -### `pool_idle_timeout_seconds` +### `pool_idle_timeout` -- **Type:** `integer` -- **Default:** `50` +- **Type:** `string` +- **Default:** `50s` Controls the timeout (in seconds) for idle keep-alive connections in the router's connection pool. Connections that are unused for this duration will be closed. @@ -47,5 +47,5 @@ longer idle timeout. traffic_shaping: dedupe_enabled: true max_connections_per_host: 250 - pool_idle_timeout_seconds: 90 + pool_idle_timeout: 90s ``` diff --git a/packages/web/docs/src/content/router/guides/performance-tuning.mdx b/packages/web/docs/src/content/router/guides/performance-tuning.mdx index 9852fc95e03..67b342c34b5 100644 --- a/packages/web/docs/src/content/router/guides/performance-tuning.mdx +++ b/packages/web/docs/src/content/router/guides/performance-tuning.mdx @@ -54,10 +54,10 @@ Start with the default and adjust based on your observations: ## Managing Idle Connections -The `pool_idle_timeout_seconds` setting controls how long unused connections stay open in the -router's connection pool before being closed. +The `pool_idle_timeout` setting controls how long unused connections stay open in the router's +connection pool before being closed. -- **Default Value:** `50` seconds +- **Default Value:** `50s` ### The Connection Reuse Trade-off From 03782743fa12a41c57813f782e3430edce590d7a Mon Sep 17 00:00:00 2001 From: Arda TANRIKULU Date: Mon, 3 Nov 2025 15:38:05 +0300 Subject: [PATCH 2/5] Clarify duration string --- .../src/content/router/configuration/traffic_shaping.mdx | 5 +++-- .../docs/src/content/router/guides/performance-tuning.mdx | 3 +++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx b/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx index c2e930a83a2..f2e3e1c0660 100644 --- a/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx +++ b/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx @@ -35,8 +35,9 @@ requests. - **Type:** `string` - **Default:** `50s` -Controls the timeout (in seconds) for idle keep-alive connections in the router's connection pool. -Connections that are unused for this duration will be closed. +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. ## Example diff --git a/packages/web/docs/src/content/router/guides/performance-tuning.mdx b/packages/web/docs/src/content/router/guides/performance-tuning.mdx index 67b342c34b5..1b93ced73b3 100644 --- a/packages/web/docs/src/content/router/guides/performance-tuning.mdx +++ b/packages/web/docs/src/content/router/guides/performance-tuning.mdx @@ -59,6 +59,9 @@ connection pool before being closed. - **Default Value:** `50s` +It takes a duration string (like `30s` for 30 seconds, or `1m` for 1 minute). This setting affects +how aggressively the router reuses existing connections versus closing them to free up resources. + ### The Connection Reuse Trade-off **Too short = latency overhead:** From 2f8038bea9b7f06bfe7f23ba35c60bd97f1fefd0 Mon Sep 17 00:00:00 2001 From: Arda TANRIKULU Date: Tue, 4 Nov 2025 15:13:36 +0300 Subject: [PATCH 3/5] docs(router): subgraph timeout configuration --- .../router/configuration/traffic_shaping.mdx | 90 ++++++++++++++++--- 1 file changed, 80 insertions(+), 10 deletions(-) diff --git a/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx b/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx index f2e3e1c0660..7aee9dc7efc 100644 --- a/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx +++ b/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx @@ -13,14 +13,6 @@ these settings, see the [Performance Tuning & Traffic Shaping Guide](../guides/p ## Options -### `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. - ### `max_connections_per_host` - **Type:** `integer` @@ -30,7 +22,34 @@ Limits the maximum number of concurrent HTTP connections the router will open to host. This acts as a safeguard to prevent overwhelming a subgraph with too many simultaneous requests. -### `pool_idle_timeout` +### Subgraph Specific Options + +The following options 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`: + +```yaml +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` @@ -39,7 +58,7 @@ Controls the timeout in duration string format (e.g. `1m` for 1 minute, `30s` fo idle keep-alive connections in the router's connection pool. Connections that are unused for this duration will be closed. -## Example +##### Example This example configuration increases the connection limit for a high-capacity subgraph and sets a longer idle timeout. @@ -50,3 +69,54 @@ traffic_shaping: max_connections_per_host: 250 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. + +##### Value Options + +The value for `request_timeout` must be a valid duration string or a VRL expression that evaluates +to a duration string. + +###### Static Duration String + +- **Type:** `string` + +When a static duration string is provided, it sets a fixed timeout for all requests to subgraphs. + +```yamlyaml +traffic_shaping: + request_timeout: 30s +``` + +###### Dynamic with `expression` + +- **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. + +```yaml +traffic_shaping: + request_timeout: + expression: | + if .request.headers["X-Priority"] == "high" { + "10s" + } else { + "60s" + } +``` + +This example sets a shorter timeout for high-priority requests based on a custom header. From df6bdcc3b728860a2a28bc4a82cf572fc96f3661 Mon Sep 17 00:00:00 2001 From: Arda TANRIKULU Date: Tue, 4 Nov 2025 15:46:11 +0300 Subject: [PATCH 4/5] lets go --- .../router/configuration/traffic_shaping.mdx | 29 ++++++++++--------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx b/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx index 7aee9dc7efc..a1332044956 100644 --- a/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx +++ b/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx @@ -24,8 +24,9 @@ requests. ### Subgraph Specific Options -The following options 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. +The following options (`dedupe_enabled`, `pool_idle_timeout`, and `request_timeout`) 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`: @@ -65,9 +66,9 @@ longer idle timeout. ```yaml filename="router.config.yaml" traffic_shaping: - dedupe_enabled: true - max_connections_per_host: 250 - pool_idle_timeout: 90s + subgraphs: + high_capacity_subgraph: + pool_idle_timeout: 90s ``` #### `request_timeout` @@ -91,7 +92,8 @@ When a static duration string is provided, it sets a fixed timeout for all reque ```yamlyaml traffic_shaping: - request_timeout: 30s + all: + request_timeout: 30s ``` ###### Dynamic with `expression` @@ -110,13 +112,14 @@ Within the `expression`, you have access to the following context: ```yaml traffic_shaping: - request_timeout: - expression: | - if .request.headers["X-Priority"] == "high" { - "10s" - } else { - "60s" - } + all: + request_timeout: + expression: | + if .request.headers["X-Priority"] == "high" { + "10s" + } else { + "60s" + } ``` This example sets a shorter timeout for high-priority requests based on a custom header. From d99f76fb2365cad443a92f527293c7c575e1f38e Mon Sep 17 00:00:00 2001 From: Kamil Kisiela Date: Fri, 28 Nov 2025 10:51:48 +0100 Subject: [PATCH 5/5] Refactor traffic shaping docs --- .../router/configuration/traffic_shaping.mdx | 37 +++++++++++-------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx b/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx index a1332044956..a0dc6358a00 100644 --- a/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx +++ b/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx @@ -11,9 +11,7 @@ These settings are crucial for ensuring the router operates efficiently under lo protecting your downstream subgraphs from being overwhelmed. For a detailed guide on how to tune these settings, see the [Performance Tuning & Traffic Shaping Guide](../guides/performance-tuning). -## Options - -### `max_connections_per_host` +## `max_connections_per_host` - **Type:** `integer` - **Default:** `100` @@ -22,7 +20,7 @@ Limits the maximum number of concurrent HTTP connections the router will open to host. This acts as a safeguard to prevent overwhelming a subgraph with too many simultaneous requests. -### Subgraph Specific Options +## Subgraph Specific Options The following options (`dedupe_enabled`, `pool_idle_timeout`, and `request_timeout`) can be set globally for all subgraphs or overridden on a per-subgraph basis by nesting them under the @@ -42,7 +40,7 @@ traffic_shaping: pool_idle_timeout: 120s ``` -#### `dedupe_enabled` +### `dedupe_enabled` - **Type:** `boolean` - **Default:** `true` @@ -50,7 +48,7 @@ traffic_shaping: 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` +### `pool_idle_timeout` - **Type:** `string` - **Default:** `50s` @@ -59,8 +57,6 @@ Controls the timeout in duration string format (e.g. `1m` for 1 minute, `30s` fo idle keep-alive connections in the router's connection pool. Connections that are unused for this duration will be closed. -##### Example - This example configuration increases the connection limit for a high-capacity subgraph and sets a longer idle timeout. @@ -71,7 +67,7 @@ traffic_shaping: pool_idle_timeout: 90s ``` -#### `request_timeout` +### `request_timeout` - **Default:** `30s` @@ -79,24 +75,22 @@ Request timeout in duration string format (e.g. `30s` for 30 seconds, `1m` for 1 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. -##### Value Options - The value for `request_timeout` must be a valid duration string or a VRL expression that evaluates to a duration string. -###### Static Duration String +#### Static - **Type:** `string` When a static duration string is provided, it sets a fixed timeout for all requests to subgraphs. -```yamlyaml +```yaml traffic_shaping: all: request_timeout: 30s ``` -###### Dynamic with `expression` +#### Dynamic - **Type:** `object` @@ -109,17 +103,28 @@ request characteristics. 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). ```yaml traffic_shaping: all: request_timeout: expression: | - if .request.headers["X-Priority"] == "high" { + 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. +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.