diff --git a/2.0.x/multi/multi__developer_guide.html b/2.0.x/multi/multi__developer_guide.html index f815068d..2bd8f340 100644 --- a/2.0.x/multi/multi__developer_guide.html +++ b/2.0.x/multi/multi__developer_guide.html @@ -1,3 +1,3 @@ - 9. Developer Guide

9. Developer Guide

TODO: overview of writing custom integrations

9.1 Writing Custom Route Predicate Factorys

TODO: document writing Custom Route Predicate Factorys

9.2 Writing Custom WebFilter Factorys

TODO: document writing Custom WebFilter Factorys

9.3 Writing Custom Global Filters

TODO: document writing Custom Global Filters

9.4 Writing Custom Route Locators and Writers

TODO: document writing Custom Route Locators and Writers

\ No newline at end of file + 9. Developer Guide

9. Developer Guide

TODO: overview of writing custom integrations

9.1 Writing Custom Route Predicate Factories

TODO: document writing Custom Route Predicate Factories

9.2 Writing Custom WebFilter Factories

TODO: document writing Custom WebFilter Factories

9.3 Writing Custom Global Filters

TODO: document writing Custom Global Filters

9.4 Writing Custom Route Locators and Writers

TODO: document writing Custom Route Locators and Writers

\ No newline at end of file diff --git a/2.0.x/multi/multi__global_filters.html b/2.0.x/multi/multi__global_filters.html index 631b94e2..085d9efe 100644 --- a/2.0.x/multi/multi__global_filters.html +++ b/2.0.x/multi/multi__global_filters.html @@ -1,3 +1,3 @@ - 6. Global Filters

6. Global Filters

The GlobalFilter interface has the same signature as WebFilter. These are special filters that are conditionally applied to all routes. (This interface and usage are subject to change in future milestones).

6.1 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 placed in the ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR attribute.

6.2 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.3 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.4 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`.

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

\ No newline at end of file + 6. Global Filters

6. Global Filters

The GlobalFilter interface has the same signature as WebFilter. These are special filters that are conditionally applied to all routes. (This interface and usage are subject to change in future milestones).

6.1 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 placed in the ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR attribute.

6.2 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.3 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.4 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`.

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

\ No newline at end of file diff --git a/2.0.x/multi/multi_gateway-request-predicates-factories.html b/2.0.x/multi/multi_gateway-request-predicates-factories.html index 51039d53..4c426033 100644 --- a/2.0.x/multi/multi_gateway-request-predicates-factories.html +++ b/2.0.x/multi/multi_gateway-request-predicates-factories.html @@ -1,6 +1,6 @@ - 4. Route Predicate Factories

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 Factorys. All of these predicates match on different attributes of the HTTP request. Multiple Route Predicate Factorys 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.  + 4. Route Predicate Factories

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:
   cloud:
     gateway:
@@ -80,7 +80,7 @@
         uri: http://example.org
         predicates:
         - Path=/foo/{segment}

-

This route would match if the request path was, for example: /foo/1 or /foo/bar.

This predicate extracts the URI template variables (like segment defined in the example above) as a map of names and values and places it in the ServerWebExchange.getAttributes() with a key defined in PathRoutePredicate.URL_PREDICATE_VARS_ATTR. Those values are then available for use by WebFilter Factorys

4.9 Query Route Predicate Factory

The Query Route Predicate Factory takes two parameters: a required param and an optional regexp.

application.yml.  +

This route would match if the request path was, for example: /foo/1 or /foo/bar.

This predicate extracts the URI template variables (like segment defined in the example above) as a map of names and values and places it in the ServerWebExchange.getAttributes() with a key defined in PathRoutePredicate.URL_PREDICATE_VARS_ATTR. Those values are then available for use by WebFilter Factories

4.9 Query Route Predicate Factory

The Query Route Predicate Factory takes two parameters: a required param and an optional regexp.

application.yml. 

spring:
   cloud:
     gateway:
@@ -110,4 +110,4 @@
         uri: http://example.org
         predicates:
         - RemoteAddr=192.168.1.1/24

-

This route would match if the remote address of the request was, for example, 192.168.1.10.

\ No newline at end of file +

This route would match if the remote address of the request was, for example, 192.168.1.10.

\ No newline at end of file diff --git a/2.0.x/multi/multi_gateway-route-filters.html b/2.0.x/multi/multi_gateway-route-filters.html index f6e08bf5..baf17877 100644 --- a/2.0.x/multi/multi_gateway-route-filters.html +++ b/2.0.x/multi/multi_gateway-route-filters.html @@ -1,6 +1,6 @@ - 5. WebFilter Factorys

5. WebFilter Factorys

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 WebFilter Factories.

5.1 AddRequestHeader WebFilter Factory

The AddRequestHeader WebFilter Factory takes a name and value parameter.

application.yml.  + 5. WebFilter Factories

5. WebFilter Factories

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 WebFilter Factories.

5.1 AddRequestHeader WebFilter Factory

The AddRequestHeader WebFilter Factory takes a name and value parameter.

application.yml. 

spring:
   cloud:
     gateway:
diff --git a/2.0.x/multi/multi_spring-cloud-gateway.html b/2.0.x/multi/multi_spring-cloud-gateway.html
index 3849ddd7..5c724857 100644
--- a/2.0.x/multi/multi_spring-cloud-gateway.html
+++ b/2.0.x/multi/multi_spring-cloud-gateway.html
@@ -1,3 +1,3 @@
 
       
-   Spring Cloud Gateway

Spring Cloud Gateway


\ No newline at end of file + Spring Cloud Gateway

Spring Cloud Gateway


\ No newline at end of file diff --git a/2.0.x/single/spring-cloud-gateway.html b/2.0.x/single/spring-cloud-gateway.html index c1ef9d7c..97011de5 100644 --- a/2.0.x/single/spring-cloud-gateway.html +++ b/2.0.x/single/spring-cloud-gateway.html @@ -1,8 +1,8 @@ - Spring Cloud Gateway

Spring Cloud Gateway


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


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.

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

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 Factorys. All of these predicates match on different attributes of the HTTP request. Multiple Route Predicate Factorys 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.  +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.

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

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:
   cloud:
     gateway:
@@ -82,7 +82,7 @@ for details on setting up your build system with the current Spring Cloud Releas
         uri: http://example.org
         predicates:
         - Path=/foo/{segment}

-

This route would match if the request path was, for example: /foo/1 or /foo/bar.

This predicate extracts the URI template variables (like segment defined in the example above) as a map of names and values and places it in the ServerWebExchange.getAttributes() with a key defined in PathRoutePredicate.URL_PREDICATE_VARS_ATTR. Those values are then available for use by WebFilter Factorys

4.9 Query Route Predicate Factory

The Query Route Predicate Factory takes two parameters: a required param and an optional regexp.

application.yml.  +

This route would match if the request path was, for example: /foo/1 or /foo/bar.

This predicate extracts the URI template variables (like segment defined in the example above) as a map of names and values and places it in the ServerWebExchange.getAttributes() with a key defined in PathRoutePredicate.URL_PREDICATE_VARS_ATTR. Those values are then available for use by WebFilter Factories

4.9 Query Route Predicate Factory

The Query Route Predicate Factory takes two parameters: a required param and an optional regexp.

application.yml. 

spring:
   cloud:
     gateway:
@@ -112,7 +112,7 @@ for details on setting up your build system with the current Spring Cloud Releas
         uri: http://example.org
         predicates:
         - RemoteAddr=192.168.1.1/24

-

This route would match if the remote address of the request was, for example, 192.168.1.10.

5. WebFilter Factorys

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 WebFilter Factories.

5.1 AddRequestHeader WebFilter Factory

The AddRequestHeader WebFilter Factory takes a name and value parameter.

application.yml.  +

This route would match if the remote address of the request was, for example, 192.168.1.10.

5. WebFilter Factories

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 WebFilter Factories.

5.1 AddRequestHeader WebFilter Factory

The AddRequestHeader WebFilter Factory takes a name and value parameter.

application.yml. 

spring:
   cloud:
     gateway:
@@ -295,7 +295,7 @@ KeyResolver userKeyResolver() {
                 .and()
             .build();
 }

-

This style also allows for more custom predicate assertions. The predicates defined by RouteDefinitionLocator beans are combined using logical and. By using the fluent Java API, you can use the and(), or() and negate() operators on the Predicate class.

8. Actuator API

TODO: document the /gateway actuator endpoint

9. Developer Guide

TODO: overview of writing custom integrations

9.1 Writing Custom Route Predicate Factorys

TODO: document writing Custom Route Predicate Factorys

9.2 Writing Custom WebFilter Factorys

TODO: document writing Custom WebFilter Factorys

9.3 Writing Custom Global Filters

TODO: document writing Custom Global Filters

9.4 Writing Custom Route Locators and Writers

TODO: document writing Custom Route Locators and Writers

10. Building a Simple Gateway Using Spring MVC

Spring Cloud Gateway provides a utility object called ProxyExchange which you can use inside a regular Spring MVC handler as a method parameter. It supports basic downstream HTTP exchanges via methods that mirror the HTTP verbs, or forwarding to a local handler via the forward() method.

Example (proxying a request to "/test" downstream to a remote server):

@RestController
+

This style also allows for more custom predicate assertions. The predicates defined by RouteDefinitionLocator beans are combined using logical and. By using the fluent Java API, you can use the and(), or() and negate() operators on the Predicate class.

8. Actuator API

TODO: document the /gateway actuator endpoint

9. Developer Guide

TODO: overview of writing custom integrations

9.1 Writing Custom Route Predicate Factories

TODO: document writing Custom Route Predicate Factories

9.2 Writing Custom WebFilter Factories

TODO: document writing Custom WebFilter Factories

9.3 Writing Custom Global Filters

TODO: document writing Custom Global Filters

9.4 Writing Custom Route Locators and Writers

TODO: document writing Custom Route Locators and Writers

10. Building a Simple Gateway Using Spring MVC

Spring Cloud Gateway provides a utility object called ProxyExchange which you can use inside a regular Spring MVC handler as a method parameter. It supports basic downstream HTTP exchanges via methods that mirror the HTTP verbs, or forwarding to a local handler via the forward() method.

Example (proxying a request to "/test" downstream to a remote server):

@RestController
 @SpringBootApplication
 public class GatewaySampleApplication {
 
diff --git a/2.0.x/spring-cloud-gateway.xml b/2.0.x/spring-cloud-gateway.xml
index 273a9530..61d5749d 100644
--- a/2.0.x/spring-cloud-gateway.xml
+++ b/2.0.x/spring-cloud-gateway.xml
@@ -4,7 +4,7 @@
 
 
 Spring Cloud Gateway
-2017-10-03
+2017-10-04
 
 
 
@@ -46,7 +46,7 @@ for details on setting up your build system with the current Spring Cloud Releas
 
 
 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 Factorys. All of these predicates match on different attributes of the HTTP request. Multiple Route Predicate Factorys can be combined and are combined via logical and.
+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.
 
After Route Predicate Factory The After Route Predicate Factory takes one parameter, a datetime. This predicate matches requests that happen after the current datetime. @@ -198,7 +198,7 @@ for details on setting up your build system with the current Spring Cloud Releas This route would match if the request path was, for example: /foo/1 or /foo/bar. -This predicate extracts the URI template variables (like segment defined in the example above) as a map of names and values and places it in the ServerWebExchange.getAttributes() with a key defined in PathRoutePredicate.URL_PREDICATE_VARS_ATTR. Those values are then available for use by WebFilter Factorys +This predicate extracts the URI template variables (like segment defined in the example above) as a map of names and values and places it in the ServerWebExchange.getAttributes() with a key defined in PathRoutePredicate.URL_PREDICATE_VARS_ATTR. Those values are then available for use by WebFilter Factories
Query Route Predicate Factory @@ -255,7 +255,7 @@ for details on setting up your build system with the current Spring Cloud Releas
-WebFilter Factorys +WebFilter Factories 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 WebFilter Factories.
AddRequestHeader WebFilter Factory @@ -717,13 +717,13 @@ public RouteLocator customRouteLocator(ThrottleWebFilterFactory throttle) { Developer Guide TODO: overview of writing custom integrations -
-Writing Custom Route Predicate Factorys -TODO: document writing Custom Route Predicate Factorys +
+Writing Custom Route Predicate Factories +TODO: document writing Custom Route Predicate Factories
-
-Writing Custom WebFilter Factorys -TODO: document writing Custom WebFilter Factorys +
+Writing Custom WebFilter Factories +TODO: document writing Custom WebFilter Factories
Writing Custom Global Filters