From 91047315416e72433dbc58d16b8a53ac1487c455 Mon Sep 17 00:00:00 2001 From: buildmaster Date: Wed, 13 Feb 2019 15:25:41 +0000 Subject: [PATCH] Sync docs from master to gh-pages --- multi/multi__developer_guide.html | 91 ++++++++++++++++++++++++++- multi/multi_spring-cloud-gateway.html | 2 +- single/spring-cloud-gateway.html | 69 ++++++++++++++++++-- spring-cloud-gateway.xml | 89 +++++++++++++++++++------- 4 files changed, 220 insertions(+), 31 deletions(-) diff --git a/multi/multi__developer_guide.html b/multi/multi__developer_guide.html index eeabed68..37f0c841 100644 --- a/multi/multi__developer_guide.html +++ b/multi/multi__developer_guide.html @@ -1,6 +1,6 @@ - 12. Developer Guide
12. Developer Guide
Prev   Next

12. Developer Guide

TODO: overview of writing custom integrations

12.1 Writing Custom Route Predicate Factories

TODO: document writing Custom Route Predicate Factories

12.2 Writing Custom GatewayFilter Factories

In order to write a GatewayFilter you will need to implement GatewayFilterFactory. There is an abstract class called AbstractGatewayFilterFactory which you can extend.

PreGatewayFilterFactory.java.  + 12. Developer Guide

12. Developer Guide
Prev   

12. Developer Guide

TODO: overview of writing custom integrations

12.1 Writing Custom Route Predicate Factories

TODO: document writing Custom Route Predicate Factories

12.2 Writing Custom GatewayFilter Factories

In order to write a GatewayFilter you will need to implement GatewayFilterFactory. There is an abstract class called AbstractGatewayFilterFactory which you can extend.

PreGatewayFilterFactory.java.  

public class PreGatewayFilterFactory extends AbstractGatewayFilterFactory<PreGatewayFilterFactory.Config> {
 
 	public PreGatewayFilterFactory() {
@@ -47,4 +47,91 @@
 	}
 
 }

-

12.3 Writing Custom Global Filters

TODO: document writing Custom Global Filters

12.4 Writing Custom Route Locators and Writers

TODO: document writing Custom Route Locators and Writers

Prev   Next
11. Actuator API Home 13. Building a Simple Gateway Using Spring MVC or Webflux
\ No newline at end of file +

12.3 Writing Custom Global Filters

In order to write a custom global filter, you will need to implement GlobalFilter interface. This will apply the filter to all requests.

Example of how to set up a Global Pre and Post filter, respectively

@Bean
+public GlobalFilter customGlobalFilter() {
+    return (exchange, chain) -> exchange.getPrincipal()
+        .map(Principal::getName)
+        .defaultIfEmpty("Default User")
+        .map(userName -> {
+          //adds header to proxied request
+          exchange.getRequest().mutate().header("CUSTOM-REQUEST-HEADER", userName).build();
+          return exchange;
+        })
+        .flatMap(chain::filter);
+}
+
+@Bean
+public GlobalFilter customGlobalPostFilter() {
+    return (exchange, chain) -> chain.filter(exchange)
+        .then(Mono.just(exchange))
+        .map(serverWebExchange -> {
+          //adds header to response
+          serverWebExchange.getResponse().getHeaders().set("CUSTOM-RESPONSE-HEADER",
+              HttpStatus.OK.equals(serverWebExchange.getResponse().getStatusCode()) ? "It worked": "It did not work");
+          return serverWebExchange;
+        })
+        .then();
+}
+---
+
+=== Writing Custom Route Locators and Writers
+
+TODO: document writing Custom Route Locators and Writers
+
+== Building a Simple Gateway Using Spring MVC or Webflux
+
+Spring Cloud Gateway provides a utility object called `ProxyExchange` which you can use inside a regular Spring web handler as a method parameter. It supports basic downstream HTTP exchanges via methods that mirror the HTTP verbs. With MVC it also supports forwarding to a local handler via the `forward()` method. To use the `ProxyExchange` just include the right module in your classpath (either `spring-cloud-gateway-mvc` or `spring-cloud-gateway-webflux`).
+
+MVC example (proxying a request to "/test" downstream to a remote server):
+
+```java
+@RestController
+@SpringBootApplication
+public class GatewaySampleApplication {
+
+	@Value("${remote.home}")
+	private URI home;
+
+	@GetMapping("/test")
+	public ResponseEntity<?> proxy(ProxyExchange<byte[]> proxy) throws Exception {
+		return proxy.uri(home.toString() + "/image/png").get();
+	}
+
+}
+```
+
+The same thing with Webflux:
+
+```java
+@RestController
+@SpringBootApplication
+public class GatewaySampleApplication {
+
+	@Value("${remote.home}")
+	private URI home;
+
+	@GetMapping("/test")
+	public Mono<ResponseEntity<?>> proxy(ProxyExchange<byte[]> proxy) throws Exception {
+		return proxy.uri(home.toString() + "/image/png").get();
+	}
+
+}
+```
+
+There are convenience methods on the `ProxyExchange` to enable the handler method to discover and enhance the URI path of the incoming request. For example you might want to extract the trailing elements of a path to pass them downstream:
+
+```java
+@GetMapping("/proxy/path/**")
+public ResponseEntity<?> proxyPath(ProxyExchange<byte[]> proxy) throws Exception {
+  String path = proxy.path("/proxy/path/");
+  return proxy.uri(home.toString() + "/foos/" + path).get();
+}
+```
+
+All the features of Spring MVC or Webflux are available to Gateway handler methods. So you can inject request headers and query parameters, for instance, and you can constrain the incoming requests with declarations in the mapping annotation. See the documentation for `@RequestMapping` in Spring MVC for more details of those features.
+
+Headers can be added to the downstream response using the `header()` methods on `ProxyExchange`.
+
+You can also manipulate response headers (and anything else you like in the response) by adding a mapper to the `get()` etc. method. The mapper is a `Function` that takes the incoming `ResponseEntity` and converts it to an outgoing one.
+
+First class support is provided for "sensitive" headers ("cookie" and "authorization" by default) which are not passed downstream, and for "proxy" headers (`x-forwarded-*`).
Prev   
11. Actuator API Home 
\ No newline at end of file diff --git a/multi/multi_spring-cloud-gateway.html b/multi/multi_spring-cloud-gateway.html index 53e499e3..bef567e1 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. FallbackHeaders GatewayFilter Factory
5.6. PrefixPath GatewayFilter Factory
5.7. PreserveHostHeader GatewayFilter Factory
5.8. RequestRateLimiter GatewayFilter Factory
5.8.1. Redis RateLimiter
5.9. RedirectTo GatewayFilter Factory
5.10. RemoveNonProxyHeaders GatewayFilter Factory
5.11. RemoveRequestHeader GatewayFilter Factory
5.12. RemoveResponseHeader GatewayFilter Factory
5.13. RewritePath GatewayFilter Factory
5.14. RewriteResponseHeader GatewayFilter Factory
5.15. SaveSession GatewayFilter Factory
5.16. SecureHeaders GatewayFilter Factory
5.17. SetPath GatewayFilter Factory
5.18. SetResponseHeader GatewayFilter Factory
5.19. SetStatus GatewayFilter Factory
5.20. StripPrefix GatewayFilter Factory
5.21. Retry GatewayFilter Factory
5.22. RequestSize GatewayFilter Factory
5.23. Modify Request Body GatewayFilter Factory
5.24. Modify Response Body 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
6.8. Gateway Metrics Filter
6.9. Marking An Exchange As Routed
7. TLS / SSL
7.1. TLS Handshake
8. Configuration
8.1. Fluent Java Routes API
8.2. DiscoveryClient Route Definition Locator
8.2.1. Configuring Predicates and Filters For DiscoveryClient Routes
9. Reactor Netty Access Logs
10. CORS Configuration
11. Actuator API
11.1. Retrieving route filters
11.1.1. Global Filters
11.1.2. Route Filters
11.2. Refreshing the route cache
11.3. Retrieving the routes defined in the gateway
11.4. Retrieving information about a particular route
11.5. Creating and deleting a particular route
11.6. Recap: list of all endpoints
12. Developer Guide
12.1. Writing Custom Route Predicate Factories
12.2. Writing Custom GatewayFilter Factories
12.3. Writing Custom Global Filters
12.4. Writing Custom Route Locators and Writers
13. 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. FallbackHeaders GatewayFilter Factory
5.6. PrefixPath GatewayFilter Factory
5.7. PreserveHostHeader GatewayFilter Factory
5.8. RequestRateLimiter GatewayFilter Factory
5.8.1. Redis RateLimiter
5.9. RedirectTo GatewayFilter Factory
5.10. RemoveNonProxyHeaders GatewayFilter Factory
5.11. RemoveRequestHeader GatewayFilter Factory
5.12. RemoveResponseHeader GatewayFilter Factory
5.13. RewritePath GatewayFilter Factory
5.14. RewriteResponseHeader GatewayFilter Factory
5.15. SaveSession GatewayFilter Factory
5.16. SecureHeaders GatewayFilter Factory
5.17. SetPath GatewayFilter Factory
5.18. SetResponseHeader GatewayFilter Factory
5.19. SetStatus GatewayFilter Factory
5.20. StripPrefix GatewayFilter Factory
5.21. Retry GatewayFilter Factory
5.22. RequestSize GatewayFilter Factory
5.23. Modify Request Body GatewayFilter Factory
5.24. Modify Response Body 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
6.8. Gateway Metrics Filter
6.9. Marking An Exchange As Routed
7. TLS / SSL
7.1. TLS Handshake
8. Configuration
8.1. Fluent Java Routes API
8.2. DiscoveryClient Route Definition Locator
8.2.1. Configuring Predicates and Filters For DiscoveryClient Routes
9. Reactor Netty Access Logs
10. CORS Configuration
11. Actuator API
11.1. Retrieving route filters
11.1.1. Global Filters
11.1.2. Route Filters
11.2. Refreshing the route cache
11.3. Retrieving the routes defined in the gateway
11.4. Retrieving information about a particular route
11.5. Creating and deleting a particular route
11.6. Recap: list of all endpoints
12. Developer Guide
12.1. Writing Custom Route Predicate Factories
12.2. Writing Custom GatewayFilter Factories
12.3. Writing Custom Global Filters
   Next
   
\ No newline at end of file diff --git a/single/spring-cloud-gateway.html b/single/spring-cloud-gateway.html index 5516fd43..dcfc64da 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. FallbackHeaders GatewayFilter Factory
5.6. PrefixPath GatewayFilter Factory
5.7. PreserveHostHeader GatewayFilter Factory
5.8. RequestRateLimiter GatewayFilter Factory
5.8.1. Redis RateLimiter
5.9. RedirectTo GatewayFilter Factory
5.10. RemoveNonProxyHeaders GatewayFilter Factory
5.11. RemoveRequestHeader GatewayFilter Factory
5.12. RemoveResponseHeader GatewayFilter Factory
5.13. RewritePath GatewayFilter Factory
5.14. RewriteResponseHeader GatewayFilter Factory
5.15. SaveSession GatewayFilter Factory
5.16. SecureHeaders GatewayFilter Factory
5.17. SetPath GatewayFilter Factory
5.18. SetResponseHeader GatewayFilter Factory
5.19. SetStatus GatewayFilter Factory
5.20. StripPrefix GatewayFilter Factory
5.21. Retry GatewayFilter Factory
5.22. RequestSize GatewayFilter Factory
5.23. Modify Request Body GatewayFilter Factory
5.24. Modify Response Body 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
6.8. Gateway Metrics Filter
6.9. Marking An Exchange As Routed
7. TLS / SSL
7.1. TLS Handshake
8. Configuration
8.1. Fluent Java Routes API
8.2. DiscoveryClient Route Definition Locator
8.2.1. Configuring Predicates and Filters For DiscoveryClient Routes
9. Reactor Netty Access Logs
10. CORS Configuration
11. Actuator API
11.1. Retrieving route filters
11.1.1. Global Filters
11.1.2. Route Filters
11.2. Refreshing the route cache
11.3. Retrieving the routes defined in the gateway
11.4. Retrieving information about a particular route
11.5. Creating and deleting a particular route
11.6. Recap: list of all endpoints
12. Developer Guide
12.1. Writing Custom Route Predicate Factories
12.2. Writing Custom GatewayFilter Factories
12.3. Writing Custom Global Filters
12.4. Writing Custom Route Locators and Writers
13. Building a Simple Gateway Using Spring MVC or Webflux

2.1.1.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. FallbackHeaders GatewayFilter Factory
5.6. PrefixPath GatewayFilter Factory
5.7. PreserveHostHeader GatewayFilter Factory
5.8. RequestRateLimiter GatewayFilter Factory
5.8.1. Redis RateLimiter
5.9. RedirectTo GatewayFilter Factory
5.10. RemoveNonProxyHeaders GatewayFilter Factory
5.11. RemoveRequestHeader GatewayFilter Factory
5.12. RemoveResponseHeader GatewayFilter Factory
5.13. RewritePath GatewayFilter Factory
5.14. RewriteResponseHeader GatewayFilter Factory
5.15. SaveSession GatewayFilter Factory
5.16. SecureHeaders GatewayFilter Factory
5.17. SetPath GatewayFilter Factory
5.18. SetResponseHeader GatewayFilter Factory
5.19. SetStatus GatewayFilter Factory
5.20. StripPrefix GatewayFilter Factory
5.21. Retry GatewayFilter Factory
5.22. RequestSize GatewayFilter Factory
5.23. Modify Request Body GatewayFilter Factory
5.24. Modify Response Body 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
6.8. Gateway Metrics Filter
6.9. Marking An Exchange As Routed
7. TLS / SSL
7.1. TLS Handshake
8. Configuration
8.1. Fluent Java Routes API
8.2. DiscoveryClient Route Definition Locator
8.2.1. Configuring Predicates and Filters For DiscoveryClient Routes
9. Reactor Netty Access Logs
10. CORS Configuration
11. Actuator API
11.1. Retrieving route filters
11.1.1. Global Filters
11.1.2. Route Filters
11.2. Refreshing the route cache
11.3. Retrieving the routes defined in the gateway
11.4. Retrieving information about a particular route
11.5. Creating and deleting a particular route
11.6. Recap: list of all endpoints
12. Developer Guide
12.1. Writing Custom Route Predicate Factories
12.2. Writing Custom GatewayFilter Factories
12.3. Writing Custom Global Filters

2.1.1.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:
@@ -713,7 +713,45 @@ spring.cloud.gateway.discovery.locator.filters[1].args[replacement]: "'/${remain
 	}
 
 }

-

12.3 Writing Custom Global Filters

TODO: document writing Custom Global Filters

12.4 Writing Custom Route Locators and Writers

TODO: document writing Custom Route Locators and Writers

13. Building a Simple Gateway Using Spring MVC or Webflux

Spring Cloud Gateway provides a utility object called ProxyExchange which you can use inside a regular Spring web handler as a method parameter. It supports basic downstream HTTP exchanges via methods that mirror the HTTP verbs. With MVC it also supports forwarding to a local handler via the forward() method. To use the ProxyExchange just include the right module in your classpath (either spring-cloud-gateway-mvc or spring-cloud-gateway-webflux).

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

@RestController
+

12.3 Writing Custom Global Filters

In order to write a custom global filter, you will need to implement GlobalFilter interface. This will apply the filter to all requests.

Example of how to set up a Global Pre and Post filter, respectively

@Bean
+public GlobalFilter customGlobalFilter() {
+    return (exchange, chain) -> exchange.getPrincipal()
+        .map(Principal::getName)
+        .defaultIfEmpty("Default User")
+        .map(userName -> {
+          //adds header to proxied request
+          exchange.getRequest().mutate().header("CUSTOM-REQUEST-HEADER", userName).build();
+          return exchange;
+        })
+        .flatMap(chain::filter);
+}
+
+@Bean
+public GlobalFilter customGlobalPostFilter() {
+    return (exchange, chain) -> chain.filter(exchange)
+        .then(Mono.just(exchange))
+        .map(serverWebExchange -> {
+          //adds header to response
+          serverWebExchange.getResponse().getHeaders().set("CUSTOM-RESPONSE-HEADER",
+              HttpStatus.OK.equals(serverWebExchange.getResponse().getStatusCode()) ? "It worked": "It did not work");
+          return serverWebExchange;
+        })
+        .then();
+}
+---
+
+=== Writing Custom Route Locators and Writers
+
+TODO: document writing Custom Route Locators and Writers
+
+== Building a Simple Gateway Using Spring MVC or Webflux
+
+Spring Cloud Gateway provides a utility object called `ProxyExchange` which you can use inside a regular Spring web handler as a method parameter. It supports basic downstream HTTP exchanges via methods that mirror the HTTP verbs. With MVC it also supports forwarding to a local handler via the `forward()` method. To use the `ProxyExchange` just include the right module in your classpath (either `spring-cloud-gateway-mvc` or `spring-cloud-gateway-webflux`).
+
+MVC example (proxying a request to "/test" downstream to a remote server):
+
+```java
+@RestController
 @SpringBootApplication
 public class GatewaySampleApplication {
 
@@ -725,7 +763,13 @@ spring.cloud.gateway.discovery.locator.filters[1].args[replacement]: "'/${remain
 		return proxy.uri(home.toString() + "/image/png").get();
 	}
 
-}

The same thing with Webflux:

@RestController
+}
+```
+
+The same thing with Webflux:
+
+```java
+@RestController
 @SpringBootApplication
 public class GatewaySampleApplication {
 
@@ -737,8 +781,23 @@ spring.cloud.gateway.discovery.locator.filters[1].args[replacement]: "'/${remain
 		return proxy.uri(home.toString() + "/image/png").get();
 	}
 
-}

There are convenience methods on the ProxyExchange to enable the handler method to discover and enhance the URI path of the incoming request. For example you might want to extract the trailing elements of a path to pass them downstream:

@GetMapping("/proxy/path/**")
+}
+```
+
+There are convenience methods on the `ProxyExchange` to enable the handler method to discover and enhance the URI path of the incoming request. For example you might want to extract the trailing elements of a path to pass them downstream:
+
+```java
+@GetMapping("/proxy/path/**")
 public ResponseEntity<?> proxyPath(ProxyExchange<byte[]> proxy) throws Exception {
   String path = proxy.path("/proxy/path/");
   return proxy.uri(home.toString() + "/foos/" + path).get();
-}

All the features of Spring MVC or Webflux are available to Gateway handler methods. So you can inject request headers and query parameters, for instance, and you can constrain the incoming requests with declarations in the mapping annotation. See the documentation for @RequestMapping in Spring MVC for more details of those features.

Headers can be added to the downstream response using the header() methods on ProxyExchange.

You can also manipulate response headers (and anything else you like in the response) by adding a mapper to the get() etc. method. The mapper is a Function that takes the incoming ResponseEntity and converts it to an outgoing one.

First class support is provided for "sensitive" headers ("cookie" and "authorization" by default) which are not passed downstream, and for "proxy" headers (x-forwarded-*).

\ No newline at end of file +} +``` + +All the features of Spring MVC or Webflux are available to Gateway handler methods. So you can inject request headers and query parameters, for instance, and you can constrain the incoming requests with declarations in the mapping annotation. See the documentation for `@RequestMapping` in Spring MVC for more details of those features. + +Headers can be added to the downstream response using the `header()` methods on `ProxyExchange`. + +You can also manipulate response headers (and anything else you like in the response) by adding a mapper to the `get()` etc. method. The mapper is a `Function` that takes the incoming `ResponseEntity` and converts it to an outgoing one. + +First class support is provided for "sensitive" headers ("cookie" and "authorization" by default) which are not passed downstream, and for "proxy" headers (`x-forwarded-*`).
\ No newline at end of file diff --git a/spring-cloud-gateway.xml b/spring-cloud-gateway.xml index 63096576..fc25cdac 100644 --- a/spring-cloud-gateway.xml +++ b/spring-cloud-gateway.xml @@ -1672,18 +1672,47 @@ management.endpoints.web.exposure.include=gateway
Writing Custom Global Filters -TODO: document writing Custom Global Filters -
-
-Writing Custom Route Locators and Writers -TODO: document writing Custom Route Locators and Writers -
- - -Building a Simple Gateway Using Spring MVC or Webflux -Spring Cloud Gateway provides a utility object called ProxyExchange which you can use inside a regular Spring web handler as a method parameter. It supports basic downstream HTTP exchanges via methods that mirror the HTTP verbs. With MVC it also supports forwarding to a local handler via the forward() method. To use the ProxyExchange just include the right module in your classpath (either spring-cloud-gateway-mvc or spring-cloud-gateway-webflux). -MVC example (proxying a request to "/test" downstream to a remote server): -@RestController +In order to write a custom global filter, you will need to implement GlobalFilter interface. This will apply the filter to all requests. +Example of how to set up a Global Pre and Post filter, respectively +@Bean +public GlobalFilter customGlobalFilter() { + return (exchange, chain) -> exchange.getPrincipal() + .map(Principal::getName) + .defaultIfEmpty("Default User") + .map(userName -> { + //adds header to proxied request + exchange.getRequest().mutate().header("CUSTOM-REQUEST-HEADER", userName).build(); + return exchange; + }) + .flatMap(chain::filter); +} + +@Bean +public GlobalFilter customGlobalPostFilter() { + return (exchange, chain) -> chain.filter(exchange) + .then(Mono.just(exchange)) + .map(serverWebExchange -> { + //adds header to response + serverWebExchange.getResponse().getHeaders().set("CUSTOM-RESPONSE-HEADER", + HttpStatus.OK.equals(serverWebExchange.getResponse().getStatusCode()) ? "It worked": "It did not work"); + return serverWebExchange; + }) + .then(); +} +--- + +=== Writing Custom Route Locators and Writers + +TODO: document writing Custom Route Locators and Writers + +== Building a Simple Gateway Using Spring MVC or Webflux + +Spring Cloud Gateway provides a utility object called `ProxyExchange` which you can use inside a regular Spring web handler as a method parameter. It supports basic downstream HTTP exchanges via methods that mirror the HTTP verbs. With MVC it also supports forwarding to a local handler via the `forward()` method. To use the `ProxyExchange` just include the right module in your classpath (either `spring-cloud-gateway-mvc` or `spring-cloud-gateway-webflux`). + +MVC example (proxying a request to "/test" downstream to a remote server): + +```java +@RestController @SpringBootApplication public class GatewaySampleApplication { @@ -1695,9 +1724,13 @@ public class GatewaySampleApplication { return proxy.uri(home.toString() + "/image/png").get(); } -} -The same thing with Webflux: -@RestController +} +``` + +The same thing with Webflux: + +```java +@RestController @SpringBootApplication public class GatewaySampleApplication { @@ -1709,16 +1742,26 @@ public class GatewaySampleApplication { return proxy.uri(home.toString() + "/image/png").get(); } -} -There are convenience methods on the ProxyExchange to enable the handler method to discover and enhance the URI path of the incoming request. For example you might want to extract the trailing elements of a path to pass them downstream: -@GetMapping("/proxy/path/**") +} +``` + +There are convenience methods on the `ProxyExchange` to enable the handler method to discover and enhance the URI path of the incoming request. For example you might want to extract the trailing elements of a path to pass them downstream: + +```java +@GetMapping("/proxy/path/**") public ResponseEntity<?> proxyPath(ProxyExchange<byte[]> proxy) throws Exception { String path = proxy.path("/proxy/path/"); return proxy.uri(home.toString() + "/foos/" + path).get(); -} -All the features of Spring MVC or Webflux are available to Gateway handler methods. So you can inject request headers and query parameters, for instance, and you can constrain the incoming requests with declarations in the mapping annotation. See the documentation for @RequestMapping in Spring MVC for more details of those features. -Headers can be added to the downstream response using the header() methods on ProxyExchange. -You can also manipulate response headers (and anything else you like in the response) by adding a mapper to the get() etc. method. The mapper is a Function that takes the incoming ResponseEntity and converts it to an outgoing one. -First class support is provided for "sensitive" headers ("cookie" and "authorization" by default) which are not passed downstream, and for "proxy" headers (x-forwarded-*). +} +``` + +All the features of Spring MVC or Webflux are available to Gateway handler methods. So you can inject request headers and query parameters, for instance, and you can constrain the incoming requests with declarations in the mapping annotation. See the documentation for `@RequestMapping` in Spring MVC for more details of those features. + +Headers can be added to the downstream response using the `header()` methods on `ProxyExchange`. + +You can also manipulate response headers (and anything else you like in the response) by adding a mapper to the `get()` etc. method. The mapper is a `Function` that takes the incoming `ResponseEntity` and converts it to an outgoing one. + +First class support is provided for "sensitive" headers ("cookie" and "authorization" by default) which are not passed downstream, and for "proxy" headers (`x-forwarded-*`). + \ No newline at end of file