Route filters allow the modification of the incoming HTTP request or outgoing HTTP response in some manner. Route filters are scoped to a particular route. Spring Cloud Gateway includes many built-in GatewayFilter Factories.
The AddRequestHeader GatewayFilter Factory takes a name and value parameter.
application.yml. +
spring: + cloud: + gateway: + routes: + - id: add_request_header_route + uri: http://example.org + filters: + - AddRequestHeader=X-Request-Foo, Bar
+
This will add X-Request-Foo:Bar header to the downstream request’s headers for all matching requests.
The AddRequestParameter GatewayFilter Factory takes a name and value parameter.
application.yml. +
spring: + cloud: + gateway: + routes: + - id: add_request_parameter_route + uri: http://example.org + filters: + - AddRequestParameter=foo, bar
+
This will add foo=bar to the downstream request’s query string for all matching requests.
The AddResponseHeader GatewayFilter Factory takes a name and value parameter.
application.yml. +
spring: + cloud: + gateway: + routes: + - id: add_request_header_route + uri: http://example.org + filters: + - AddResponseHeader=X-Response-Foo, Bar
+
This will add X-Response-Foo:Bar header to the downstream response’s headers for all matching requests.
The Hystrix GatewayFilter Factory requires a single name parameter, which is the name of the HystrixCommand.
application.yml. +
spring: + cloud: + gateway: + routes: + - id: hystrix_route + uri: http://example.org + filters: + - Hystrix=myCommandName
+
This wraps the remaining filters in a HystrixCommand with command name myCommandName.
The Hystrix filter can also accept an optional fallbackUri parameter. Currently, only forward: schemed URIs are supported. If the fallback is called, the request will be forwarded to the controller matched by the URI.
application.yml. +
spring: + cloud: + gateway: + routes: + - id: hystrix_route + uri: lb://backing-service:8088 + predicates: + - Path=/consumingserviceendpoint + filters: + - name: Hystrix + args: + 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.
The PrefixPath GatewayFilter Factory takes a single prefix parameter.
application.yml. +
spring: + cloud: + gateway: + routes: + - id: prefixpath_route + 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.
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: + routes: + - id: preserve_host_route + uri: http://example.org + filters: + - PreserveHostHeader
+
This will prefix /mypath to the path of all matching requests. So a request to /hello, would be sent to /mypath/hello.
The RequestRateLimiter GatewayFilter Factory takes three parameters: replenishRate, burstCapacity & keyResolverName.
replenishRate is how many requests per second do you want a user to be allowed to do.
burstCapacity TODO: document burst capacity
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. +
public interface KeyResolver { + Mono<String> resolve(ServerWebExchange exchange); +}
+
The KeyResolver interface allows pluggable strategies to derive the key for limiting requests. In future milestones, there will be some KeyResolver implementations.
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.
application.yml. +
spring: + cloud: + gateway: + routes: + - id: requestratelimiter_route + uri: http://example.org + filters: + - RequestRateLimiter=10, 20, #{@userKeyResolver}
+
Config.java. +
@Bean +KeyResolver userKeyResolver() { + return exchange -> Mono.just(exchange.getRequest().getQueryParams().getFirst("user")); +}
+
This defines a request rate limit of 10 per user. The KeyResolver is a simple one that gets the user request parameter (note: this is not recommended for production).
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. +
spring: + cloud: + gateway: + routes: + - id: prefixpath_route + uri: http://example.org + filters: + - RedirectTo=302, http://acme.org
+
This will send a status 302 with a Location:http://acme.org header to perform a redirect.
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:
To change this, set the spring.cloud.gateway.filter.remove-non-proxy-headers.headers property to the list of header names to remove.
The RemoveRequestHeader GatewayFilter Factory takes a name parameter. It is the name of the header to be removed.
application.yml. +
spring: + cloud: + gateway: + routes: + - id: removerequestheader_route + uri: http://example.org + filters: + - RemoveRequestHeader=X-Request-Foo
+
This will remove the X-Request-Foo header before it is sent downstream.
The RemoveResponseHeader GatewayFilter Factory takes a name parameter. It is the name of the header to be removed.
application.yml. +
spring: + cloud: + gateway: + routes: + - id: removeresponseheader_route + uri: http://example.org + filters: + - RemoveResponseHeader=X-Response-Foo
+
This will remove the X-Response-Foo header from the response before it is returned to the gateway client.
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. +
spring: + cloud: + gateway: + routes: + - id: rewritepath_route + uri: http://example.org + predicates: + - Path=/foo/** + filters: + - RewritePath=/foo/(?<segment>.*), /$\{segment}
+
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.
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.
application.yml. +
spring: + cloud: + gateway: + routes: + - id: save_session + uri: http://example.org + predicates: + - Path=/foo/** + filters: + - SaveSession
+
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.
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):
X-Xss-Protection:1; mode=blockStrict-Transport-Security:max-age=631138519X-Frame-Options:DENYX-Content-Type-Options:nosniffReferrer-Policy:no-referrerContent-Security-Policy:default-src 'self' https:; font-src 'self' https: data:; img-src 'self' https: data:; object-src 'none'; script-src https:; style-src 'self' https: 'unsafe-inline'X-Download-Options:noopenX-Permitted-Cross-Domain-Policies:noneTo change the default values set the appropriate property in the spring.cloud.gateway.filter.secure-headers namespace:
Property to change:
xss-protection-headerstrict-transport-securityframe-optionscontent-type-optionsreferrer-policycontent-security-policydownload-optionspermitted-cross-domain-policiesThe 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. +
spring: + cloud: + gateway: + routes: + - id: setpath_route + uri: http://example.org + predicates: + - Path=/foo/{segment} + filters: + - SetPath=/{segment}
+
For a request path of /foo/bar, this will set the path to /bar before making the downstream request.
The SetResponseHeader GatewayFilter Factory takes name and value parameters.
application.yml. +
spring: + cloud: + gateway: + routes: + - id: setresponseheader_route + uri: http://example.org + filters: + - SetResponseHeader=X-Response-Foo, Bar
+
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.
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. +
spring: + cloud: + gateway: + routes: + - id: setstatusstring_route + uri: http://example.org + filters: + - SetStatus=BAD_REQUEST + - id: setstatusint_route + uri: http://example.org + filters: + - SetStatus=401
+
In either case, the HTTP status of the response will be set to 401.
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. +
spring: + cloud: + gateway: + routes: + - id: nameRoot + uri: http://nameservice + predicates: + - Path=/name/** + filters: + - StripPrefix=2
+
When a request is made through the gateway to /name/bar/foo the request made to nameservice will look like http://nameservice/foo.
The GlobalFilter interface has the same signature as GatewayFilter. These are special filters that are conditionally applied to all routes. (This interface and usage are subject to change in future milestones).
The ForwardRoutingFilter looks for a URI in the exchange attribute ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR. If the url has a forward scheme (ie forward:///localendpoint), it will use the Spring DispatcherHandler to handler the request. The unmodified original url is appended to the list in the ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR attribute.
The LoadBalancerClientFilter looks for a URI in the exchange attribute ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR. If the url has a lb scheme (ie lb://myservice), it will use the Spring Cloud LoadBalancerClient to resolve the name (myservice in the previous example) to an actual host and port and replace the URI in the same attribute. The unmodified original url is appended to the list in the ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR attribute. The filter will also look in the ServerWebExchangeUtils.GATEWAY_SCHEME_PREFIX_ATTR attribute to see if it equals lb and then the same rules apply.
The Netty Routing Filter runs if the url located in the ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR exchange attribute has a http or https scheme. It uses the Netty HttpClient to make the downstream proxy request. The response is put in the ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR exchange attribute for use in a later filter. (There is an experimental WebClientHttpRoutingFilter that performs the same function, but does not require netty)
The NettyWriteResponseFilter runs if there is a Netty HttpClientResponse in the ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR exchange attribute. It is run after all other filters have completed and writes the proxy response back to the gateway client response. (There is an experimental WebClientWriteResponseFilter that performs the same function, but does not require netty)
The RouteToRequestUrlFilter runs if there is a Route object in the ServerWebExchangeUtils.GATEWAY_ROUTE_ATTR exchange attribute. It creates a new URI, based off of the request URI, but updated with the URI attribute of the Route object. The new URI is placed in the ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR exchange attribute`.
If the URI has a scheme prefix, such as lb:ws://serviceid, the lb scheme is stripped from the URI and placed in the ServerWebExchangeUtils.GATEWAY_SCHEME_PREFIX_ATTR for use later in the filter chain.
The Websocket Routing Filter runs if the url located in the ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR exchange attribute has a ws or wss scheme. It uses the Spring Web Socket infrastructure to forward the Websocket request downstream.
Websockets may be load-balanced by prefixing the URI with lb, such as lb:ws://serviceid.
The GlobalFilter interface has the same signature as GatewayFilter. These are special filters that are conditionally applied to all routes. (This interface and usage are subject to change in future milestones).
The ForwardRoutingFilter looks for a URI in the exchange attribute ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR. If the url has a forward scheme (ie forward:///localendpoint), it will use the Spring DispatcherHandler to handler the request. The unmodified original url is appended to the list in the ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR attribute.
The LoadBalancerClientFilter looks for a URI in the exchange attribute ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR. If the url has a lb scheme (ie lb://myservice), it will use the Spring Cloud LoadBalancerClient to resolve the name (myservice in the previous example) to an actual host and port and replace the URI in the same attribute. The unmodified original url is appended to the list in the ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR attribute. The filter will also look in the ServerWebExchangeUtils.GATEWAY_SCHEME_PREFIX_ATTR attribute to see if it equals lb and then the same rules apply.
The Netty Routing Filter runs if the url located in the ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR exchange attribute has a http or https scheme. It uses the Netty HttpClient to make the downstream proxy request. The response is put in the ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR exchange attribute for use in a later filter. (There is an experimental WebClientHttpRoutingFilter that performs the same function, but does not require netty)
The NettyWriteResponseFilter runs if there is a Netty HttpClientResponse in the ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR exchange attribute. It is run after all other filters have completed and writes the proxy response back to the gateway client response. (There is an experimental WebClientWriteResponseFilter that performs the same function, but does not require netty)
The RouteToRequestUrlFilter runs if there is a Route object in the ServerWebExchangeUtils.GATEWAY_ROUTE_ATTR exchange attribute. It creates a new URI, based off of the request URI, but updated with the URI attribute of the Route object. The new URI is placed in the ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR exchange attribute`.
If the URI has a scheme prefix, such as lb:ws://serviceid, the lb scheme is stripped from the URI and placed in the ServerWebExchangeUtils.GATEWAY_SCHEME_PREFIX_ATTR for use later in the filter chain.
The Websocket Routing Filter runs if the url located in the ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR exchange attribute has a ws or wss scheme. It uses the Spring Web Socket infrastructure to forward the Websocket request downstream.
Websockets may be load-balanced by prefixing the URI with lb, such as lb:ws://serviceid.