This will add X-Response-Foo:Bar header to the downstream response’s headers for all matching requests.
5.4 Hystrix GatewayFilter Factory
Hystrix is a library from Netflix that implements the circuit breaker pattern.
The Hystrix GatewayFilter allows you to introduce circuit breakers to your gateway routes, protecting your services from cascading failures and allowing you to provide fallback responses in the event of downstream failures.
To enable Hystrix GatewayFilters in your project, add a dependency on spring-cloud-starter-netflix-hystrix from Spring Cloud Netflix.
The Hystrix GatewayFilter Factory requires a single name parameter, which is the name of the HystrixCommand.
application.yml.
spring:
cloud:
@@ -52,9 +52,59 @@ The Hystrix GatewayFilter allows you to introduce circuit breakers to your gatew
name: fallbackcmd
fallbackUri: forward:/incaseoffailureusethis
- RewritePath=/consumingserviceendpoint, /backingserviceendpoint
-
This will forward to the /incaseoffailureusethis URI when the Hystrix fallback is called. Note that this example also demonstrates (optional) Spring Cloud Netflix Ribbon load-balancing via the lb prefix on the destination URI.
Hystrix settings (such as timeouts) can be configured with global defaults or on a route by route basis using application properties as explained on the Hystrix wiki.
To set a 5 second timeout for the example route above, the following configuration would be used:
application.yml.
+
This will forward to the /incaseoffailureusethis URI when the Hystrix fallback is called. Note that this example also demonstrates (optional) Spring Cloud Netflix Ribbon load-balancing via the lb prefix on the destination URI.
The primary scenario is to use the fallbackUri to an internal controller or handler within the gateway app.
+However, it is also possible to reroute the request to a controller or handler in an external application, like so:
In this example, there is no fallback endpoint or handler in the gateway application, however, there is one in another
+app, registered under http://localhost:9994.
In case of the request being forwarded to fallback, the Hystrix Gateway filter also provides the Throwable that has
+caused it. It’s added to the ServerWebExchange as the
+ServerWebExchangeUtils.HYSTRIX_EXECUTION_EXCEPTION_ATTR attribute that can be used when
+handling the fallback within the gateway app.
For the external controller/ handler scenario, headers can be added with exception details. You can find more information
+on it in the FallbackHeaders GatewayFilter Factory section.
Hystrix settings (such as timeouts) can be configured with global defaults or on a route by route basis using application properties as explained on the Hystrix wiki.
To set a 5 second timeout for the example route above, the following configuration would be used:
The PrefixPath GatewayFilter Factory takes a single prefix parameter.
application.yml.
+
5.5 FallbackHeaders GatewayFilter Factory
The FallbackHeaders factory allows you to add Hystrix execution exception details in headers of a request forwarded to
+a fallbackUri in an external application, like in the following scenario:
In this example, after an execution exception occurs while running the HystrixCommand, the request will be forwarde to
+the fallback endpoint or handler in an app running on localhost:9994. The headers with the exception type, message
+and -if available- root cause exception type and message will be added to that request by the FallbackHeaders filter.
The names of the headers can be overwritten in the config by setting the values of the arguments listed below, along with
+their default values:
The PrefixPath GatewayFilter Factory takes a single prefix parameter.
application.yml.
spring:
cloud:
gateway:
@@ -63,7 +113,7 @@ The Hystrix GatewayFilter allows you to introduce circuit breakers to your gatew
uri: http://example.org
filters:
- PrefixPath=/mypath
-
This will prefix /mypath to the path of all matching requests. So a request to /hello, would be sent to /mypath/hello.
5.6 PreserveHostHeader GatewayFilter Factory
The PreserveHostHeader GatewayFilter Factory has not parameters. This filter, sets a request attribute that the routing filter will inspect to determine if the original host header should be sent, rather than the host header determined by the http client.
application.yml.
+
This will prefix /mypath to the path of all matching requests. So a request to /hello, would be sent to /mypath/hello.
5.7 PreserveHostHeader GatewayFilter Factory
The PreserveHostHeader GatewayFilter Factory has not parameters. This filter, sets a request attribute that the routing filter will inspect to determine if the original host header should be sent, rather than the host header determined by the http client.
application.yml.
spring:
cloud:
gateway:
@@ -72,14 +122,14 @@ The Hystrix GatewayFilter allows you to introduce circuit breakers to your gatew
uri: http://example.org
filters:
- PreserveHostHeader
-
5.7 RequestRateLimiter GatewayFilter Factory
The RequestRateLimiter GatewayFilter Factory is uses a RateLimiter implementation to determine if the current request is allowed to proceed. If it is not, a status of HTTP 429 - Too Many Requests (by default) is returned.
This filter takes an optional keyResolver parameter and parameters specific to the rate limiter (see below).
keyResolver is a bean that implements the KeyResolver interface. In configuration, reference the bean by name using SpEL. #{@myKeyResolver} is a SpEL expression referencing a bean with the name myKeyResolver.
KeyResolver.java.
+
5.8 RequestRateLimiter GatewayFilter Factory
The RequestRateLimiter GatewayFilter Factory is uses a RateLimiter implementation to determine if the current request is allowed to proceed. If it is not, a status of HTTP 429 - Too Many Requests (by default) is returned.
This filter takes an optional keyResolver parameter and parameters specific to the rate limiter (see below).
keyResolver is a bean that implements the KeyResolver interface. In configuration, reference the bean by name using SpEL. #{@myKeyResolver} is a SpEL expression referencing a bean with the name myKeyResolver.
The KeyResolver interface allows pluggable strategies to derive the key for limiting requests. In future milestones, there will be some KeyResolver implementations.
The default implementation of KeyResolver is the PrincipalNameKeyResolver which retrieves the Principal from the ServerWebExchange and calls Principal.getName().
Note
The RequestRateLimiter is not configurable via the "shortcut" notation. The example below is invalid
The redis-rate-limiter.replenishRate is how many requests per second do you want a user to be allowed to do, without any dropped requests. This is the rate that the token bucket is filled.
The redis-rate-limiter.burstCapacity is the maximum number of requests a user is allowed to do in a single second. This is the number of tokens the token bucket can hold. Setting this value to zero will block all requests.
A steady rate is accomplished by setting the same value in replenishRate and burstCapacity. Temporary bursts can be allowed by setting burstCapacity higher than replenishRate. In this case, the rate limiter needs to be allowed some time between bursts (according to replenishRate), as 2 consecutive bursts will result in dropped requests (HTTP 429 - Too Many Requests).
application.yml.
+
5.8.1 Redis RateLimiter
The redis implementation is based off of work done at Stripe. It requires the use of the spring-boot-starter-data-redis-reactive Spring Boot starter.
The redis-rate-limiter.replenishRate is how many requests per second do you want a user to be allowed to do, without any dropped requests. This is the rate that the token bucket is filled.
The redis-rate-limiter.burstCapacity is the maximum number of requests a user is allowed to do in a single second. This is the number of tokens the token bucket can hold. Setting this value to zero will block all requests.
A steady rate is accomplished by setting the same value in replenishRate and burstCapacity. Temporary bursts can be allowed by setting burstCapacity higher than replenishRate. In this case, the rate limiter needs to be allowed some time between bursts (according to replenishRate), as 2 consecutive bursts will result in dropped requests (HTTP 429 - Too Many Requests).
The RedirectTo GatewayFilter Factory takes a status and a url parameter. The status should be a 300 series redirect http code, such as 301. The url should be a valid url. This will be the value of the Location header.
application.yml.
+
5.9 RedirectTo GatewayFilter Factory
The RedirectTo GatewayFilter Factory takes a status and a url parameter. The status should be a 300 series redirect http code, such as 301. The url should be a valid url. This will be the value of the Location header.
This will send a status 302 with a Location:http://acme.org header to perform a redirect.
5.9 RemoveNonProxyHeaders GatewayFilter Factory
The RemoveNonProxyHeaders GatewayFilter Factory removes headers from forwarded requests. The default list of headers that is removed comes from the IETF.
The default removed headers are:
Connection
Keep-Alive
Proxy-Authenticate
Proxy-Authorization
TE
Trailer
Transfer-Encoding
Upgrade
To change this, set the spring.cloud.gateway.filter.remove-non-proxy-headers.headers property to the list of header names to remove.
5.10 RemoveRequestHeader GatewayFilter Factory
The RemoveRequestHeader GatewayFilter Factory takes a name parameter. It is the name of the header to be removed.
application.yml.
+
This will send a status 302 with a Location:http://acme.org header to perform a redirect.
5.10 RemoveNonProxyHeaders GatewayFilter Factory
The RemoveNonProxyHeaders GatewayFilter Factory removes headers from forwarded requests. The default list of headers that is removed comes from the IETF.
The default removed headers are:
Connection
Keep-Alive
Proxy-Authenticate
Proxy-Authorization
TE
Trailer
Transfer-Encoding
Upgrade
To change this, set the spring.cloud.gateway.filter.remove-non-proxy-headers.headers property to the list of header names to remove.
5.11 RemoveRequestHeader GatewayFilter Factory
The RemoveRequestHeader GatewayFilter Factory takes a name parameter. It is the name of the header to be removed.
This will remove the X-Response-Foo header from the response before it is returned to the gateway client.
5.12 RewritePath GatewayFilter Factory
The RewritePath GatewayFilter Factory takes a path regexp parameter and a replacement parameter. This uses Java regular expressions for a flexible way to rewrite the request path.
application.yml.
+
This will remove the X-Response-Foo header from the response before it is returned to the gateway client.
5.13 RewritePath GatewayFilter Factory
The RewritePath GatewayFilter Factory takes a path regexp parameter and a replacement parameter. This uses Java regular expressions for a flexible way to rewrite the request path.
For a request path of /foo/bar, this will set the path to /bar before making the downstream request. Notice the $\ which is replaced with $ because of the YAML spec.
5.13 SaveSession GatewayFilter Factory
The SaveSession GatewayFilter Factory forces a WebSession::save operation before forwarding the call downstream. This is of particular use when
+
For a request path of /foo/bar, this will set the path to /bar before making the downstream request. Notice the $\ which is replaced with $ because of the YAML spec.
5.14 SaveSession GatewayFilter Factory
The SaveSession GatewayFilter Factory forces a WebSession::save operation before forwarding the call downstream. This is of particular use when
using something like Spring Session with a lazy data store and need to ensure the session state has been saved before making the forwarded call.
If you are integrating Spring Security with Spring Session, and want to ensure security details have been forwarded to the remote process, this is critical.
5.14 SecureHeaders GatewayFilter Factory
The SecureHeaders GatewayFilter Factory adds a number of headers to the response at the reccomendation from this blog post.
The following headers are added (allong with default values):
To change the default values set the appropriate property in the spring.cloud.gateway.filter.secure-headers namespace:
Property to change:
xss-protection-header
strict-transport-security
frame-options
content-type-options
referrer-policy
content-security-policy
download-options
permitted-cross-domain-policies
5.15 SetPath GatewayFilter Factory
The SetPath GatewayFilter Factory takes a path template parameter. It offers a simple way to manipulate the request path by allowing templated segments of the path. This uses the uri templates from Spring Framework. Multiple matching segments are allowed.
application.yml.
+
If you are integrating Spring Security with Spring Session, and want to ensure security details have been forwarded to the remote process, this is critical.
5.15 SecureHeaders GatewayFilter Factory
The SecureHeaders GatewayFilter Factory adds a number of headers to the response at the reccomendation from this blog post.
The following headers are added (allong with default values):
To change the default values set the appropriate property in the spring.cloud.gateway.filter.secure-headers namespace:
Property to change:
xss-protection-header
strict-transport-security
frame-options
content-type-options
referrer-policy
content-security-policy
download-options
permitted-cross-domain-policies
5.16 SetPath GatewayFilter Factory
The SetPath GatewayFilter Factory takes a path template parameter. It offers a simple way to manipulate the request path by allowing templated segments of the path. This uses the uri templates from Spring Framework. Multiple matching segments are allowed.
This GatewayFilter replaces all headers with the given name, rather than adding. So if the downstream server responded with a X-Response-Foo:1234, this would be replaced with X-Response-Foo:Bar, which is what the gateway client would receive.
5.17 SetStatus GatewayFilter Factory
The SetStatus GatewayFilter Factory takes a single status parameter. It must be a valid Spring HttpStatus. It may be the integer value 404 or the string representation of the enumeration NOT_FOUND.
application.yml.
+
This GatewayFilter replaces all headers with the given name, rather than adding. So if the downstream server responded with a X-Response-Foo:1234, this would be replaced with X-Response-Foo:Bar, which is what the gateway client would receive.
5.18 SetStatus GatewayFilter Factory
The SetStatus GatewayFilter Factory takes a single status parameter. It must be a valid Spring HttpStatus. It may be the integer value 404 or the string representation of the enumeration NOT_FOUND.
In either case, the HTTP status of the response will be set to 401.
5.18 StripPrefix GatewayFilter Factory
The StripPrefix GatewayFilter Factory takes one paramter, parts. The parts parameter indicated the number of parts in the path to strip from the request before sending it downstream.
application.yml.
+
In either case, the HTTP status of the response will be set to 401.
5.19 StripPrefix GatewayFilter Factory
The StripPrefix GatewayFilter Factory takes one paramter, parts. The parts parameter indicated the number of parts in the path to strip from the request before sending it downstream.
When using the retry filter with a forward: prefixed URL, the target endpoint should be written carefully so that in case of an error it does not do anything that could result in a response being sent to the client and committed. For example, if the target endpoint is an annotated controller, the target controller method should not return ResponseEntity with an error status code. Instead it should throw an Exception, or signal an error, e.g. via a Mono.error(ex) return value, which the retry filter can be configured to handle by retrying.
5.20 RequestSize GatewayFilter Factory
The RequestSize GatewayFilter Factory can restrict a request from reaching the downstream service , when the request size is greater than the permissible limit. The filter takes RequestSize as parameter which is the permissible size limit of the request defined in bytes.
application.yml.
+
Note
When using the retry filter with a forward: prefixed URL, the target endpoint should be written carefully so that in case of an error it does not do anything that could result in a response being sent to the client and committed. For example, if the target endpoint is an annotated controller, the target controller method should not return ResponseEntity with an error status code. Instead it should throw an Exception, or signal an error, e.g. via a Mono.error(ex) return value, which the retry filter can be configured to handle by retrying.
5.21 RequestSize GatewayFilter Factory
The RequestSize GatewayFilter Factory can restrict a request from reaching the downstream service , when the request size is greater than the permissible limit. The filter takes RequestSize as parameter which is the permissible size limit of the request defined in bytes.
![[Note]](images/note.png)