From d2d16a57028df7a6bc39ba0447681c09149be154 Mon Sep 17 00:00:00 2001 From: halo Date: Wed, 10 Jun 2026 08:36:44 +0900 Subject: [PATCH] docs: clarify series+statuses interaction in Retry and comma limitation in AddRequestHeader GH-1536: When both `series` and `statuses` are configured on the Retry filter, a retry occurs only when the response matches both. Documents how to retry on specific status codes without any series restriction. GH-1896: The AddRequestHeader shortcut notation parses on the first comma, so header values containing commas must use the expanded name/value form. Added a NOTE with an example for both WebFlux and WebMVC docs. Co-Authored-By: Claude Sonnet 4.6 --- .../addrequestheader-factory.adoc | 11 +++++++++++ .../gatewayfilter-factories/retry-factory.adoc | 2 +- .../filters/addrequestheader.adoc | 11 +++++++++++ 3 files changed, 23 insertions(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/gatewayfilter-factories/addrequestheader-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/gatewayfilter-factories/addrequestheader-factory.adoc index 858b04f6a..57c53d2f4 100644 --- a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/gatewayfilter-factories/addrequestheader-factory.adoc +++ b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/gatewayfilter-factories/addrequestheader-factory.adoc @@ -21,6 +21,17 @@ spring: This listing adds `X-Request-red:blue` header to the downstream request's headers for all matching requests. +NOTE: The shortcut notation (`AddRequestHeader=Name, Value`) parses the value on the first comma, so header values that contain a comma must use the expanded (`name`/`value` args) form: ++ +[source,yaml] +---- +filters: + - name: AddRequestHeader + args: + name: X-My-Header + value: "Value, with comma" +---- + `AddRequestHeader` is aware of the URI variables used to match a path or host. URI variables may be used in the value and are expanded at runtime. The following example configures an `AddRequestHeader` `GatewayFilter` that uses a variable: diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/gatewayfilter-factories/retry-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/gatewayfilter-factories/retry-factory.adoc index 6cf5b5ba7..f76d7946c 100644 --- a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/gatewayfilter-factories/retry-factory.adoc +++ b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/gatewayfilter-factories/retry-factory.adoc @@ -6,7 +6,7 @@ The `Retry` `GatewayFilter` factory supports the following parameters: * `retries`: The number of retries that should be attempted. * `statuses`: The HTTP status codes that should be retried, represented by using `org.springframework.http.HttpStatus`. * `methods`: The HTTP methods that should be retried, represented by using `org.springframework.http.HttpMethod`. -* `series`: The series of status codes to be retried, represented by using `org.springframework.http.HttpStatus.Series`. +* `series`: The series of status codes to be retried, represented by using `org.springframework.http.HttpStatus.Series`. When both `series` and `statuses` are set, a response is retried only if it matches the series AND is listed in `statuses`. To retry based on specific status codes without any series restriction, set `series` to an empty list (or `null` in YAML). * `exceptions`: A list of thrown exceptions that should be retried. * `backoff`: The configured exponential backoff for the retries. Retries are performed after a backoff interval of `firstBackoff * (factor ^ n)`, where `n` is the iteration. diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webmvc/filters/addrequestheader.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webmvc/filters/addrequestheader.adoc index 94b315d8c..5da026f00 100644 --- a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webmvc/filters/addrequestheader.adoc +++ b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webmvc/filters/addrequestheader.adoc @@ -44,6 +44,17 @@ class RouteConfiguration { This listing adds `X-Request-red:blue` header to the downstream request's headers for all matching requests. +NOTE: The shortcut notation (`AddRequestHeader=Name, Value`) parses the value on the first comma, so header values that contain a comma must use the expanded (`name`/`value` args) form: ++ +[source,yaml] +---- +filters: + - name: AddRequestHeader + args: + name: X-My-Header + value: "Value, with comma" +---- + `AddRequestHeader` is aware of the URI variables used to match a path or host. URI variables may be used in the value and are expanded at runtime. The following example configures an `AddRequestHeader` filter that uses a variable: