From e74c7ffbf1d049f007814290fddce07dc8870915 Mon Sep 17 00:00:00 2001 From: buildmaster Date: Tue, 12 Jun 2018 19:09:08 +0000 Subject: [PATCH] Sync docs from master to gh-pages --- multi/multi__gatewayfilter_factories.html | 16 +++++++++- multi/multi_spring-cloud-gateway.html | 2 +- single/spring-cloud-gateway.html | 18 +++++++++-- spring-cloud-gateway.xml | 39 +++++++++++++++++++++++ 4 files changed, 71 insertions(+), 4 deletions(-) diff --git a/multi/multi__gatewayfilter_factories.html b/multi/multi__gatewayfilter_factories.html index 01a40278..0fe5b374 100644 --- a/multi/multi__gatewayfilter_factories.html +++ b/multi/multi__gatewayfilter_factories.html @@ -184,4 +184,18 @@ using something like - 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.

Prev   Next
4. Route Predicate Factories Home 6. Global Filters
\ No newline at end of file +

When a request is made through the gateway to /name/bar/foo the request made to nameservice will look like http://nameservice/foo.

5.19 Retry GatewayFilter Factory

The Retry GatewayFilter Factory takes retries, statuses, methods, and series as parameters.

  • retries: the number of retries that should be attempted
  • statuses: the HTTP status codes that should be retried, represented using org.springframework.http.HttpStatus
  • methods: the HTTP methods that should be retried, represented using org.springframework.http.HttpMethod
  • series: the series of status codes to be retried, represented using org.springframework.http.HttpStatus.Series

application.yml.  +

spring:
+  cloud:
+    gateway:
+      routes:
+      - id: retry_test
+        uri: http://localhost:8080/flakey
+        predicates:
+        - Host=*.retry.com
+        filters:
+        - name: Retry
+          args:
+            retries: 3
+            statuses: BAD_GATEWAY

+

[Note]Note

At this time a URI using the forward protocol does not support using the retry filter.

Prev   Next
4. Route Predicate Factories Home 6. Global Filters
\ No newline at end of file diff --git a/multi/multi_spring-cloud-gateway.html b/multi/multi_spring-cloud-gateway.html index 7592199b..20265f04 100644 --- a/multi/multi_spring-cloud-gateway.html +++ b/multi/multi_spring-cloud-gateway.html @@ -1,3 +1,3 @@ - Spring Cloud Gateway
Spring Cloud Gateway
   Next

Spring Cloud Gateway

Table of Contents

1. How to Include Spring Cloud Gateway
2. Glossary
3. How It Works
4. Route Predicate Factories
4.1. After Route Predicate Factory
4.2. Before Route Predicate Factory
4.3. Between Route Predicate Factory
4.4. Cookie Route Predicate Factory
4.5. Header Route Predicate Factory
4.6. Host Route Predicate Factory
4.7. Method Route Predicate Factory
4.8. Path Route Predicate Factory
4.9. Query Route Predicate Factory
4.10. RemoteAddr Route Predicate Factory
4.10.1. Modifying the way remote addresses are resolved
5. GatewayFilter Factories
5.1. AddRequestHeader GatewayFilter Factory
5.2. AddRequestParameter GatewayFilter Factory
5.3. AddResponseHeader GatewayFilter Factory
5.4. Hystrix GatewayFilter Factory
5.5. PrefixPath GatewayFilter Factory
5.6. PreserveHostHeader GatewayFilter Factory
5.7. RequestRateLimiter GatewayFilter Factory
5.8. RedirectTo GatewayFilter Factory
5.9. RemoveNonProxyHeaders GatewayFilter Factory
5.10. RemoveRequestHeader GatewayFilter Factory
5.11. RemoveResponseHeader GatewayFilter Factory
5.12. RewritePath GatewayFilter Factory
5.13. SaveSession GatewayFilter Factory
5.14. SecureHeaders GatewayFilter Factory
5.15. SetPath GatewayFilter Factory
5.16. SetResponseHeader GatewayFilter Factory
5.17. SetStatus GatewayFilter Factory
5.18. StripPrefix GatewayFilter Factory
6. Global Filters
6.1. Combined Global Filter and GatewayFilter Ordering
6.2. Forward Routing Filter
6.3. LoadBalancerClient Filter
6.4. Netty Routing Filter
6.5. Netty Write Response Filter
6.6. RouteToRequestUrl Filter
6.7. Websocket Routing Filter
7. Configuration
7.1. Fluent Java Routes API
7.2. DiscoveryClient Route Definition Locator
8. Actuator API
9. Developer Guide
9.1. Writing Custom Route Predicate Factories
9.2. Writing Custom GatewayFilter Factories
9.3. Writing Custom Global Filters
9.4. Writing Custom Route Locators and Writers
10. Building a Simple Gateway Using Spring MVC or Webflux
   Next
   
\ No newline at end of file + Spring Cloud Gateway
Spring Cloud Gateway
   Next

Spring Cloud Gateway

Table of Contents

1. How to Include Spring Cloud Gateway
2. Glossary
3. How It Works
4. Route Predicate Factories
4.1. After Route Predicate Factory
4.2. Before Route Predicate Factory
4.3. Between Route Predicate Factory
4.4. Cookie Route Predicate Factory
4.5. Header Route Predicate Factory
4.6. Host Route Predicate Factory
4.7. Method Route Predicate Factory
4.8. Path Route Predicate Factory
4.9. Query Route Predicate Factory
4.10. RemoteAddr Route Predicate Factory
4.10.1. Modifying the way remote addresses are resolved
5. GatewayFilter Factories
5.1. AddRequestHeader GatewayFilter Factory
5.2. AddRequestParameter GatewayFilter Factory
5.3. AddResponseHeader GatewayFilter Factory
5.4. Hystrix GatewayFilter Factory
5.5. PrefixPath GatewayFilter Factory
5.6. PreserveHostHeader GatewayFilter Factory
5.7. RequestRateLimiter GatewayFilter Factory
5.8. RedirectTo GatewayFilter Factory
5.9. RemoveNonProxyHeaders GatewayFilter Factory
5.10. RemoveRequestHeader GatewayFilter Factory
5.11. RemoveResponseHeader GatewayFilter Factory
5.12. RewritePath GatewayFilter Factory
5.13. SaveSession GatewayFilter Factory
5.14. SecureHeaders GatewayFilter Factory
5.15. SetPath GatewayFilter Factory
5.16. SetResponseHeader GatewayFilter Factory
5.17. SetStatus GatewayFilter Factory
5.18. StripPrefix GatewayFilter Factory
5.19. Retry GatewayFilter Factory
6. Global Filters
6.1. Combined Global Filter and GatewayFilter Ordering
6.2. Forward Routing Filter
6.3. LoadBalancerClient Filter
6.4. Netty Routing Filter
6.5. Netty Write Response Filter
6.6. RouteToRequestUrl Filter
6.7. Websocket Routing Filter
7. Configuration
7.1. Fluent Java Routes API
7.2. DiscoveryClient Route Definition Locator
8. Actuator API
9. Developer Guide
9.1. Writing Custom Route Predicate Factories
9.2. Writing Custom GatewayFilter Factories
9.3. Writing Custom Global Filters
9.4. Writing Custom Route Locators and Writers
10. Building a Simple Gateway Using Spring MVC or Webflux
   Next
   
\ No newline at end of file diff --git a/single/spring-cloud-gateway.html b/single/spring-cloud-gateway.html index d97efc1d..d6b0ad17 100644 --- a/single/spring-cloud-gateway.html +++ b/single/spring-cloud-gateway.html @@ -1,6 +1,6 @@ - Spring Cloud Gateway

Spring Cloud Gateway

Table of Contents

1. How to Include Spring Cloud Gateway
2. Glossary
3. How It Works
4. Route Predicate Factories
4.1. After Route Predicate Factory
4.2. Before Route Predicate Factory
4.3. Between Route Predicate Factory
4.4. Cookie Route Predicate Factory
4.5. Header Route Predicate Factory
4.6. Host Route Predicate Factory
4.7. Method Route Predicate Factory
4.8. Path Route Predicate Factory
4.9. Query Route Predicate Factory
4.10. RemoteAddr Route Predicate Factory
4.10.1. Modifying the way remote addresses are resolved
5. GatewayFilter Factories
5.1. AddRequestHeader GatewayFilter Factory
5.2. AddRequestParameter GatewayFilter Factory
5.3. AddResponseHeader GatewayFilter Factory
5.4. Hystrix GatewayFilter Factory
5.5. PrefixPath GatewayFilter Factory
5.6. PreserveHostHeader GatewayFilter Factory
5.7. RequestRateLimiter GatewayFilter Factory
5.8. RedirectTo GatewayFilter Factory
5.9. RemoveNonProxyHeaders GatewayFilter Factory
5.10. RemoveRequestHeader GatewayFilter Factory
5.11. RemoveResponseHeader GatewayFilter Factory
5.12. RewritePath GatewayFilter Factory
5.13. SaveSession GatewayFilter Factory
5.14. SecureHeaders GatewayFilter Factory
5.15. SetPath GatewayFilter Factory
5.16. SetResponseHeader GatewayFilter Factory
5.17. SetStatus GatewayFilter Factory
5.18. StripPrefix GatewayFilter Factory
6. Global Filters
6.1. Combined Global Filter and GatewayFilter Ordering
6.2. Forward Routing Filter
6.3. LoadBalancerClient Filter
6.4. Netty Routing Filter
6.5. Netty Write Response Filter
6.6. RouteToRequestUrl Filter
6.7. Websocket Routing Filter
7. Configuration
7.1. Fluent Java Routes API
7.2. DiscoveryClient Route Definition Locator
8. Actuator API
9. Developer Guide
9.1. Writing Custom Route Predicate Factories
9.2. Writing Custom GatewayFilter Factories
9.3. Writing Custom Global Filters
9.4. Writing Custom Route Locators and Writers
10. Building a Simple Gateway Using Spring MVC or Webflux

2.0.0.BUILD-SNAPSHOT

This project provides an API Gateway built on top of the Spring Ecosystem, including: Spring 5, Spring Boot 2 and Project Reactor. Spring Cloud Gateway aims to provide a simple, yet effective way to route to APIs and provide cross cutting concerns to them such as: security, monitoring/metrics, and resiliency.

1. How to Include Spring Cloud Gateway

To include Spring Cloud Gateway in your project use the starter with group org.springframework.cloud + Spring Cloud Gateway

Spring Cloud Gateway

Table of Contents

1. How to Include Spring Cloud Gateway
2. Glossary
3. How It Works
4. Route Predicate Factories
4.1. After Route Predicate Factory
4.2. Before Route Predicate Factory
4.3. Between Route Predicate Factory
4.4. Cookie Route Predicate Factory
4.5. Header Route Predicate Factory
4.6. Host Route Predicate Factory
4.7. Method Route Predicate Factory
4.8. Path Route Predicate Factory
4.9. Query Route Predicate Factory
4.10. RemoteAddr Route Predicate Factory
4.10.1. Modifying the way remote addresses are resolved
5. GatewayFilter Factories
5.1. AddRequestHeader GatewayFilter Factory
5.2. AddRequestParameter GatewayFilter Factory
5.3. AddResponseHeader GatewayFilter Factory
5.4. Hystrix GatewayFilter Factory
5.5. PrefixPath GatewayFilter Factory
5.6. PreserveHostHeader GatewayFilter Factory
5.7. RequestRateLimiter GatewayFilter Factory
5.8. RedirectTo GatewayFilter Factory
5.9. RemoveNonProxyHeaders GatewayFilter Factory
5.10. RemoveRequestHeader GatewayFilter Factory
5.11. RemoveResponseHeader GatewayFilter Factory
5.12. RewritePath GatewayFilter Factory
5.13. SaveSession GatewayFilter Factory
5.14. SecureHeaders GatewayFilter Factory
5.15. SetPath GatewayFilter Factory
5.16. SetResponseHeader GatewayFilter Factory
5.17. SetStatus GatewayFilter Factory
5.18. StripPrefix GatewayFilter Factory
5.19. Retry GatewayFilter Factory
6. Global Filters
6.1. Combined Global Filter and GatewayFilter Ordering
6.2. Forward Routing Filter
6.3. LoadBalancerClient Filter
6.4. Netty Routing Filter
6.5. Netty Write Response Filter
6.6. RouteToRequestUrl Filter
6.7. Websocket Routing Filter
7. Configuration
7.1. Fluent Java Routes API
7.2. DiscoveryClient Route Definition Locator
8. Actuator API
9. Developer Guide
9.1. Writing Custom Route Predicate Factories
9.2. Writing Custom GatewayFilter Factories
9.3. Writing Custom Global Filters
9.4. Writing Custom Route Locators and Writers
10. Building a Simple Gateway Using Spring MVC or Webflux

2.0.0.BUILD-SNAPSHOT

This project provides an API Gateway built on top of the Spring Ecosystem, including: Spring 5, Spring Boot 2 and Project Reactor. Spring Cloud Gateway aims to provide a simple, yet effective way to route to APIs and provide cross cutting concerns to them such as: security, monitoring/metrics, and resiliency.

1. How to Include Spring Cloud Gateway

To include Spring Cloud Gateway in your project use the starter with group org.springframework.cloud and artifact id spring-cloud-starter-gateway. See the Spring Cloud Project page for details on setting up your build system with the current Spring Cloud Release Train.

If you include the starter, but, for some reason, you do not want the gateway to be enabled, set spring.cloud.gateway.enabled=false.

[Important]Important

Spring Cloud Gateway requires the Netty runtime provided by Spring Boot and Spring Webflux. It does not work in a traditional Servlet Container or built as a WAR.

2. Glossary

  • Route: Route the basic building block of the gateway. It is defined by an ID, a destination URI, a collection of predicates and a collection of filters. A route is matched if aggregate predicate is true.
  • Predicate: This is a Java 8 Function Predicate. The input type is a Spring Framework ServerWebExchange. This allows developers to match on anything from the HTTP request, such as headers or parameters.
  • Filter: These are instances Spring Framework GatewayFilter constructed in with a specific factory. Here, requests and responses can be modified before or after sending the downstream request.

3. How It Works

Spring Cloud Gateway Diagram

Clients make requests to Spring Cloud Gateway. If the Gateway Handler Mapping determines that a request matches a Route, it is sent to the Gateway Web Handler. This handler runs sends the request through a filter chain that is specific to the request. The reason the filters are divided by the dotted line, is that filters may execute logic before the proxy request is sent or after. All "pre" filter logic is executed, then the proxy request is made. After the proxy request is made, the "post" filter logic is executed.

[Note]Note

URIs defined in routes without a port will get a default port set to 80 and 443 for HTTP and HTTPS URIs respectively.

4. Route Predicate Factories

Spring Cloud Gateway matches routes as part of the Spring WebFlux HandlerMapping infrastructure. Spring Cloud Gateway includes many built-in Route Predicate Factories. All of these predicates match on different attributes of the HTTP request. Multiple Route Predicate Factories can be combined and are combined via logical and.

4.1 After Route Predicate Factory

The After Route Predicate Factory takes one parameter, a datetime. This predicate matches requests that happen after the current datetime.

application.yml.  

spring:
@@ -301,7 +301,21 @@ using something like         - 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.

6. Global Filters

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).

6.1 Combined Global Filter and GatewayFilter Ordering

TODO: document ordering

6.2 Forward Routing Filter

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 path part of the request URL will be overridden with the path in the forward URL. The unmodified original url is appended to the list in the ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR attribute.

6.3 LoadBalancerClient Filter

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.

6.4 Netty Routing Filter

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)

6.5 Netty Write Response Filter

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)

6.6 RouteToRequestUrl Filter

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.

6.7 Websocket Routing Filter

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.

7. Configuration

Configuration for Spring Cloud Gateway is driven by a collection of `RouteDefinitionLocator`s.

RouteDefinitionLocator.java.  +

When a request is made through the gateway to /name/bar/foo the request made to nameservice will look like http://nameservice/foo.

5.19 Retry GatewayFilter Factory

The Retry GatewayFilter Factory takes retries, statuses, methods, and series as parameters.

  • retries: the number of retries that should be attempted
  • statuses: the HTTP status codes that should be retried, represented using org.springframework.http.HttpStatus
  • methods: the HTTP methods that should be retried, represented using org.springframework.http.HttpMethod
  • series: the series of status codes to be retried, represented using org.springframework.http.HttpStatus.Series

application.yml.  +

spring:
+  cloud:
+    gateway:
+      routes:
+      - id: retry_test
+        uri: http://localhost:8080/flakey
+        predicates:
+        - Host=*.retry.com
+        filters:
+        - name: Retry
+          args:
+            retries: 3
+            statuses: BAD_GATEWAY

+

[Note]Note

At this time a URI using the forward protocol does not support using the retry filter.

6. Global Filters

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).

6.1 Combined Global Filter and GatewayFilter Ordering

TODO: document ordering

6.2 Forward Routing Filter

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 path part of the request URL will be overridden with the path in the forward URL. The unmodified original url is appended to the list in the ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR attribute.

6.3 LoadBalancerClient Filter

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.

6.4 Netty Routing Filter

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)

6.5 Netty Write Response Filter

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)

6.6 RouteToRequestUrl Filter

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.

6.7 Websocket Routing Filter

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.

7. Configuration

Configuration for Spring Cloud Gateway is driven by a collection of `RouteDefinitionLocator`s.

RouteDefinitionLocator.java.  

public interface RouteDefinitionLocator {
 	Flux<RouteDefinition> getRouteDefinitions();
 }

diff --git a/spring-cloud-gateway.xml b/spring-cloud-gateway.xml index 939ef1aa..b085e30a 100644 --- a/spring-cloud-gateway.xml +++ b/spring-cloud-gateway.xml @@ -762,6 +762,45 @@ using something like S When a request is made through the gateway to /name/bar/foo the request made to nameservice will look like http://nameservice/foo. +

+Retry GatewayFilter Factory +The Retry GatewayFilter Factory takes retries, statuses, methods, and series as parameters. + + +retries: the number of retries that should be attempted + + +statuses: the HTTP status codes that should be retried, represented using org.springframework.http.HttpStatus + + +methods: the HTTP methods that should be retried, represented using org.springframework.http.HttpMethod + + +series: the series of status codes to be retried, represented using org.springframework.http.HttpStatus.Series + + + +application.yml + +spring: + cloud: + gateway: + routes: + - id: retry_test + uri: http://localhost:8080/flakey + predicates: + - Host=*.retry.com + filters: + - name: Retry + args: + retries: 3 + statuses: BAD_GATEWAY + + + +At this time a URI using the forward protocol does not support using the retry filter. + +
Global Filters