SpringCloud/spring-cloud-static
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
05e3a6afeecb344de577fd00a4eb990e7e49e593
spring-cloud-static/spring-cloud-gateway/2.0.0.RC2/single/spring-cloud-gateway.html
buildmaster 300e5f131d Sync docs from v2.0.0.RC2 to gh-pages
2018-05-25 13:15:31 +00:00

376 lines
88 KiB
HTML
Raw Blame History

<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Spring Cloud Gateway</title><link rel="stylesheet" type="text/css" href="css/manual-singlepage.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book"><div class="titlepage"><div><div><h1 class="title"><a name="d0e3"></a>Spring Cloud Gateway</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="preface"><a href="#d0e9"></a></span></dt><dt><span class="chapter"><a href="#gateway-starter">1. How to Include Spring Cloud Gateway</a></span></dt><dt><span class="chapter"><a href="#_glossary">2. Glossary</a></span></dt><dt><span class="chapter"><a href="#gateway-how-it-works">3. How It Works</a></span></dt><dt><span class="chapter"><a href="#gateway-request-predicates-factories">4. Route Predicate Factories</a></span></dt><dd><dl><dt><span class="section"><a href="#_after_route_predicate_factory">4.1. After Route Predicate Factory</a></span></dt><dt><span class="section"><a href="#_before_route_predicate_factory">4.2. Before Route Predicate Factory</a></span></dt><dt><span class="section"><a href="#_between_route_predicate_factory">4.3. Between Route Predicate Factory</a></span></dt><dt><span class="section"><a href="#_cookie_route_predicate_factory">4.4. Cookie Route Predicate Factory</a></span></dt><dt><span class="section"><a href="#_header_route_predicate_factory">4.5. Header Route Predicate Factory</a></span></dt><dt><span class="section"><a href="#_host_route_predicate_factory">4.6. Host Route Predicate Factory</a></span></dt><dt><span class="section"><a href="#_method_route_predicate_factory">4.7. Method Route Predicate Factory</a></span></dt><dt><span class="section"><a href="#_path_route_predicate_factory">4.8. Path Route Predicate Factory</a></span></dt><dt><span class="section"><a href="#_query_route_predicate_factory">4.9. Query Route Predicate Factory</a></span></dt><dt><span class="section"><a href="#_remoteaddr_route_predicate_factory">4.10. RemoteAddr Route Predicate Factory</a></span></dt><dd><dl><dt><span class="section"><a href="#_modifying_the_way_remote_addresses_are_resolved">4.10.1. Modifying the way remote addresses are resolved</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#_gatewayfilter_factories">5. GatewayFilter Factories</a></span></dt><dd><dl><dt><span class="section"><a href="#_addrequestheader_gatewayfilter_factory">5.1. AddRequestHeader GatewayFilter Factory</a></span></dt><dt><span class="section"><a href="#_addrequestparameter_gatewayfilter_factory">5.2. AddRequestParameter GatewayFilter Factory</a></span></dt><dt><span class="section"><a href="#_addresponseheader_gatewayfilter_factory">5.3. AddResponseHeader GatewayFilter Factory</a></span></dt><dt><span class="section"><a href="#_hystrix_gatewayfilter_factory">5.4. Hystrix GatewayFilter Factory</a></span></dt><dt><span class="section"><a href="#_prefixpath_gatewayfilter_factory">5.5. PrefixPath GatewayFilter Factory</a></span></dt><dt><span class="section"><a href="#_preservehostheader_gatewayfilter_factory">5.6. PreserveHostHeader GatewayFilter Factory</a></span></dt><dt><span class="section"><a href="#_requestratelimiter_gatewayfilter_factory">5.7. RequestRateLimiter GatewayFilter Factory</a></span></dt><dt><span class="section"><a href="#_redirectto_gatewayfilter_factory">5.8. RedirectTo GatewayFilter Factory</a></span></dt><dt><span class="section"><a href="#_removenonproxyheaders_gatewayfilter_factory">5.9. RemoveNonProxyHeaders GatewayFilter Factory</a></span></dt><dt><span class="section"><a href="#_removerequestheader_gatewayfilter_factory">5.10. RemoveRequestHeader GatewayFilter Factory</a></span></dt><dt><span class="section"><a href="#_removeresponseheader_gatewayfilter_factory">5.11. RemoveResponseHeader GatewayFilter Factory</a></span></dt><dt><span class="section"><a href="#_rewritepath_gatewayfilter_factory">5.12. RewritePath GatewayFilter Factory</a></span></dt><dt><span class="section"><a href="#_savesession_gatewayfilter_factory">5.13. SaveSession GatewayFilter Factory</a></span></dt><dt><span class="section"><a href="#_secureheaders_gatewayfilter_factory">5.14. SecureHeaders GatewayFilter Factory</a></span></dt><dt><span class="section"><a href="#_setpath_gatewayfilter_factory">5.15. SetPath GatewayFilter Factory</a></span></dt><dt><span class="section"><a href="#_setresponseheader_gatewayfilter_factory">5.16. SetResponseHeader GatewayFilter Factory</a></span></dt><dt><span class="section"><a href="#_setstatus_gatewayfilter_factory">5.17. SetStatus GatewayFilter Factory</a></span></dt><dt><span class="section"><a href="#_stripprefix_gatewayfilter_factory">5.18. StripPrefix GatewayFilter Factory</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_global_filters">6. Global Filters</a></span></dt><dd><dl><dt><span class="section"><a href="#_combined_global_filter_and_gatewayfilter_ordering">6.1. Combined Global Filter and GatewayFilter Ordering</a></span></dt><dt><span class="section"><a href="#_forward_routing_filter">6.2. Forward Routing Filter</a></span></dt><dt><span class="section"><a href="#_loadbalancerclient_filter">6.3. LoadBalancerClient Filter</a></span></dt><dt><span class="section"><a href="#_netty_routing_filter">6.4. Netty Routing Filter</a></span></dt><dt><span class="section"><a href="#_netty_write_response_filter">6.5. Netty Write Response Filter</a></span></dt><dt><span class="section"><a href="#_routetorequesturl_filter">6.6. RouteToRequestUrl Filter</a></span></dt><dt><span class="section"><a href="#_websocket_routing_filter">6.7. Websocket Routing Filter</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_configuration">7. Configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#_fluent_java_routes_api">7.1. Fluent Java Routes API</a></span></dt><dt><span class="section"><a href="#_discoveryclient_route_definition_locator">7.2. DiscoveryClient Route Definition Locator</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_actuator_api">8. Actuator API</a></span></dt><dt><span class="chapter"><a href="#_developer_guide">9. Developer Guide</a></span></dt><dd><dl><dt><span class="section"><a href="#_writing_custom_route_predicate_factories">9.1. Writing Custom Route Predicate Factories</a></span></dt><dt><span class="section"><a href="#_writing_custom_gatewayfilter_factories">9.2. Writing Custom GatewayFilter Factories</a></span></dt><dt><span class="section"><a href="#_writing_custom_global_filters">9.3. Writing Custom Global Filters</a></span></dt><dt><span class="section"><a href="#_writing_custom_route_locators_and_writers">9.4. Writing Custom Route Locators and Writers</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_building_a_simple_gateway_using_spring_mvc_or_webflux">10. Building a Simple Gateway Using Spring MVC or Webflux</a></span></dt></dl></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a name="d0e9" href="#d0e9"></a></h1></div></div></div><p><span class="strong"><strong>2.0.0.RC2</strong></span></p><p>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.</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="gateway-starter" href="#gateway-starter"></a>1.&nbsp;How to Include Spring Cloud Gateway</h1></div></div></div><p>To include Spring Cloud Gateway in your project use the starter with group <code class="literal">org.springframework.cloud</code>
and artifact id <code class="literal">spring-cloud-starter-gateway</code>. See the <a class="link" href="http://projects.spring.io/spring-cloud/" target="_top">Spring Cloud Project page</a>
for details on setting up your build system with the current Spring Cloud Release Train.</p><p>If you include the starter, but, for some reason, you do not want the gateway to be enabled, set <code class="literal">spring.cloud.gateway.enabled=false</code>.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>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.</p></td></tr></table></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_glossary" href="#_glossary"></a>2.&nbsp;Glossary</h1></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>Route</strong></span>: 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.</li><li class="listitem"><span class="strong"><strong>Predicate</strong></span>: This is a <a class="link" href="http://docs.oracle.com/javase/8/docs/api/java/util/function/Predicate.html" target="_top">Java 8 Function Predicate</a>. The input type is a <a class="link" href="http://docs.spring.io/spring/docs/5.0.x/javadoc-api/org/springframework/web/server/ServerWebExchange.html" target="_top">Spring Framework <code class="literal">ServerWebExchange</code></a>. This allows developers to match on anything from the HTTP request, such as headers or parameters.</li><li class="listitem"><span class="strong"><strong>Filter</strong></span>: These are instances <a class="link" href="http://docs.spring.io/spring/docs/5.0.x/javadoc-api/org/springframework/web/server/GatewayFilter.html" target="_top">Spring Framework <code class="literal">GatewayFilter</code></a> constructed in with a specific factory. Here, requests and responses can be modified before or after sending the downstream request.</li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="gateway-how-it-works" href="#gateway-how-it-works"></a>3.&nbsp;How It Works</h1></div></div></div><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-gateway/master/docs/src/main/asciidoc/images/spring_cloud_gateway_diagram.png" alt="Spring Cloud Gateway Diagram"></div></div><p>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.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>URIs defined in routes without a port will get a default port set to 80 and 443 for HTTP and HTTPS URIs respectively.</p></td></tr></table></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="gateway-request-predicates-factories" href="#gateway-request-predicates-factories"></a>4.&nbsp;Route Predicate Factories</h1></div></div></div><p>Spring Cloud Gateway matches routes as part of the Spring WebFlux <code class="literal">HandlerMapping</code> 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 <code class="literal">and</code>.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_after_route_predicate_factory" href="#_after_route_predicate_factory"></a>4.1&nbsp;After Route Predicate Factory</h2></div></div></div><p>The After Route Predicate Factory takes one parameter, a datetime. This predicate matches requests that happen after the current datetime.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: after_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> predicates</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - After</span>=<span class="hl-number">2017</span>-<span class="hl-number">01</span>-<span class="hl-number">20</span>T17:<span class="hl-number">42</span>:<span class="hl-number">47.789</span>-<span class="hl-number">07</span>:<span class="hl-number">00</span>[America/Denver<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">]</span></pre><p>
</p><p>This route matches any request after Jan 20, 2017 17:42 Mountain Time (Denver).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_before_route_predicate_factory" href="#_before_route_predicate_factory"></a>4.2&nbsp;Before Route Predicate Factory</h2></div></div></div><p>The Before Route Predicate Factory takes one parameter, a datetime. This predicate matches requests that happen before the current datetime.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: before_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> predicates</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Before</span>=<span class="hl-number">2017</span>-<span class="hl-number">01</span>-<span class="hl-number">20</span>T17:<span class="hl-number">42</span>:<span class="hl-number">47.789</span>-<span class="hl-number">07</span>:<span class="hl-number">00</span>[America/Denver<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">]</span></pre><p>
</p><p>This route matches any request before Jan 20, 2017 17:42 Mountain Time (Denver).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_between_route_predicate_factory" href="#_between_route_predicate_factory"></a>4.3&nbsp;Between Route Predicate Factory</h2></div></div></div><p>The Between Route Predicate Factory takes two parameters, datetime1 and datetime2. This predicate matches requests that happen after datetime1 and before datetime2. The datetime2 parameter must be after datetime1.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: between_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> predicates</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Between</span>=<span class="hl-number">2017</span>-<span class="hl-number">01</span>-<span class="hl-number">20</span>T17:<span class="hl-number">42</span>:<span class="hl-number">47.789</span>-<span class="hl-number">07</span>:<span class="hl-number">00</span>[America/Denver]<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> <span class="hl-number">2017</span>-<span class="hl-number">01</span>-<span class="hl-number">21</span>T17:<span class="hl-number">42</span>:<span class="hl-number">47.789</span>-<span class="hl-number">07</span>:<span class="hl-number">00</span>[America/Denver<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">]</span></pre><p>
</p><p>This route matches any request after Jan 20, 2017 17:42 Mountain Time (Denver) and before Jan 21, 2017 17:42 Mountain Time (Denver). This could be useful for maintenance windows.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_cookie_route_predicate_factory" href="#_cookie_route_predicate_factory"></a>4.4&nbsp;Cookie Route Predicate Factory</h2></div></div></div><p>The Cookie Route Predicate Factory takes two parameters, the cookie name and a regular expression. This predicate matches cookies that have the given name and the value matches the regular expression.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: cookie_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> predicates</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Cookie</span>=chocolate<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> ch.p</pre><p>
</p><p>This route matches the request has a cookie named <code class="literal">chocolate</code> who&#8217;s value matches the <code class="literal">ch.p</code> regular expression.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_header_route_predicate_factory" href="#_header_route_predicate_factory"></a>4.5&nbsp;Header Route Predicate Factory</h2></div></div></div><p>The Header Route Predicate Factory takes two parameters, the header name and a regular expression. This predicate matches with a header that has the given name and the value matches the regular expression.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: header_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> predicates</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Header</span>=X-Request-Id<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> \d+</pre><p>
</p><p>This route matches if the request has a header named <code class="literal">X-Request-Id</code> whos value matches the <code class="literal">\d+</code> regular expression (has a value of one or more digits).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_host_route_predicate_factory" href="#_host_route_predicate_factory"></a>4.6&nbsp;Host Route Predicate Factory</h2></div></div></div><p>The Host Route Predicate Factory takes one parameter: the host name pattern. The pattern is an Ant style pattern with <code class="literal">.</code> as the separator. This predicates matches the <code class="literal">Host</code> header that matches the pattern.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: host_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> predicates</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Host</span>=**.somehost.org</pre><p>
</p><p>This route would match if the request has a <code class="literal">Host</code> header has the value <code class="literal">www.somehost.org</code> or <code class="literal">beta.somehost.org</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_method_route_predicate_factory" href="#_method_route_predicate_factory"></a>4.7&nbsp;Method Route Predicate Factory</h2></div></div></div><p>The Method Route Predicate Factory takes one parameter: the HTTP method to match.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: method_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> predicates</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Method</span>=GET</pre><p>
</p><p>This route would match if the request method was a <code class="literal">GET</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_path_route_predicate_factory" href="#_path_route_predicate_factory"></a>4.8&nbsp;Path Route Predicate Factory</h2></div></div></div><p>The Path Route Predicate Factory takes one parameter: a Spring <code class="literal">PathMatcher</code> pattern.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: host_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> predicates</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Path</span>=/foo/{segment<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre><p>
</p><p>This route would match if the request path was, for example: <code class="literal">/foo/1</code> or <code class="literal">/foo/bar</code>.</p><p>This predicate extracts the URI template variables (like <code class="literal">segment</code> defined in the example above) as a map of names and values and places it in the <code class="literal">ServerWebExchange.getAttributes()</code> with a key defined in <code class="literal">PathRoutePredicate.URL_PREDICATE_VARS_ATTR</code>. Those values are then available for use by <a class="link" href="#gateway-route-filters">GatewayFilter Factories</a></p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_query_route_predicate_factory" href="#_query_route_predicate_factory"></a>4.9&nbsp;Query Route Predicate Factory</h2></div></div></div><p>The Query Route Predicate Factory takes two parameters: a required <code class="literal">param</code> and an optional <code class="literal">regexp</code>.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: query_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> predicates</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Query</span>=baz</pre><p>
</p><p>This route would match if the request contained a <code class="literal">baz</code> query parameter.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: query_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> predicates</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Query</span>=foo<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> ba.</pre><p>
</p><p>This route would match if the request contained a <code class="literal">foo</code> query parameter whose value matched the <code class="literal">ba.</code> regexp, so <code class="literal">bar</code> and <code class="literal">baz</code> would match.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_remoteaddr_route_predicate_factory" href="#_remoteaddr_route_predicate_factory"></a>4.10&nbsp;RemoteAddr Route Predicate Factory</h2></div></div></div><p>The RemoteAddr Route Predicate Factory takes a list (min size 1) of CIDR-notation (IPv4 or IPv6) strings, e.g. <code class="literal">192.168.0.1/16</code> (where <code class="literal">192.168.0.1</code> is an IP address and <code class="literal">16</code> is a subnet mask).</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: remoteaddr_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> predicates</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - RemoteAddr</span>=<span class="hl-number">192.168</span>.<span class="hl-number">1.1</span>/<span class="hl-number">24</span></pre><p>
</p><p>This route would match if the remote address of the request was, for example, <code class="literal">192.168.1.10</code>.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_modifying_the_way_remote_addresses_are_resolved" href="#_modifying_the_way_remote_addresses_are_resolved"></a>4.10.1&nbsp;Modifying the way remote addresses are resolved</h3></div></div></div><p>By default the RemoteAddr Route Predicate Factory uses the remote address from the incoming request.
This may not match the actual client IP address if Spring Cloud Gateway sits behind a proxy layer.</p><p>You can customize the way that the remote address is resolved by setting a custom <code class="literal">RemoteAddressResolver</code>.
Spring Cloud Gateway comes with one non-default remote address resolver which is based off of the <a class="link" href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For" target="_top">X-Forwarded-For header</a>, <code class="literal">XForwardedRemoteAddressResolver</code>.</p><p><code class="literal">XForwardedRemoteAddressResolver</code> has two static constructor methods which take different approaches to security:</p><p><code class="literal">XForwardedRemoteAddressResolver::trustAll</code> returns a <code class="literal">RemoteAddressResolver</code> which always takes the first IP address found in the <code class="literal">X-Forwarded-For</code> header.
This approach is vulnerable to spoofing, as a malicious client could set an initial value for the <code class="literal">X-Forwarded-For</code> which would be accepted by the resolver.</p><p><code class="literal">XForwardedRemoteAddressResolver::maxTrustedIndex</code> takes an index which correlates to the number of trusted infrastructure running in front of Spring Cloud Gateway.
If Spring Cloud Gateway is, for example only accessible via HAProxy, then a value of 1 should be used.
If two hops of trusted infrastructure are required before Spring Cloud Gateway is accessible, then a value of 2 should be used.</p><p>Given the following header value:</p><pre class="screen">X-Forwarded-For: 0.0.0.1, 0.0.0.2, 0.0.0.3</pre><p>The <code class="literal">maxTrustedIndex</code> values below will yield the following remote addresses.</p><div class="informaltable"><table style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; "><colgroup><col class="col_1"><col class="col_2"></colgroup><thead><tr><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">maxTrustedIndex</code></th><th style="border-bottom: 0.5pt solid ; " align="left" valign="top">result</th></tr></thead><tbody><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>[<code class="literal">Integer.MIN_VALUE</code>,0]</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>(invalid, <code class="literal">IllegalArgumentException</code> during initialization)</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0.0.0.3</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>2</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0.0.0.2</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>3</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0.0.0.1</p></td></tr><tr><td style="border-right: 0.5pt solid ; " align="left" valign="top"><p>[4, <code class="literal">Integer.MAX_VALUE</code>]</p></td><td style="" align="left" valign="top"><p>0.0.0.1</p></td></tr></tbody></table></div><p><a name="gateway-route-filters" href="#gateway-route-filters"></a>Using Java config:</p><p>GatewayConfig.java</p><pre class="programlisting">RemoteAddressResolver resolver = XForwardedRemoteAddressResolver
.maxTrustedIndex(<span class="hl-number">1</span>);
...
.route(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"direct-route"</span>,
r -&gt; r.remoteAddr(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"10.1.1.1"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"10.10.1.1/24"</span>)
.uri(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"https://downstream1"</span>)
.route(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"proxied-route"</span>,
r -&gt; r.remoteAddr(resolver, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"10.10.1.1"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"10.10.1.1/24"</span>)
.uri(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"https://downstream2"</span>)
)</pre></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_gatewayfilter_factories" href="#_gatewayfilter_factories"></a>5.&nbsp;GatewayFilter Factories</h1></div></div></div><p>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.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_addrequestheader_gatewayfilter_factory" href="#_addrequestheader_gatewayfilter_factory"></a>5.1&nbsp;AddRequestHeader GatewayFilter Factory</h2></div></div></div><p>The AddRequestHeader GatewayFilter Factory takes a name and value parameter.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: add_request_header_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - AddRequestHeader</span>=X-Request-Foo<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> Bar</pre><p>
</p><p>This will add <code class="literal">X-Request-Foo:Bar</code> header to the downstream request&#8217;s headers for all matching requests.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_addrequestparameter_gatewayfilter_factory" href="#_addrequestparameter_gatewayfilter_factory"></a>5.2&nbsp;AddRequestParameter GatewayFilter Factory</h2></div></div></div><p>The AddRequestParameter GatewayFilter Factory takes a name and value parameter.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: add_request_parameter_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - AddRequestParameter</span>=foo<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> bar</pre><p>
</p><p>This will add <code class="literal">foo=bar</code> to the downstream request&#8217;s query string for all matching requests.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_addresponseheader_gatewayfilter_factory" href="#_addresponseheader_gatewayfilter_factory"></a>5.3&nbsp;AddResponseHeader GatewayFilter Factory</h2></div></div></div><p>The AddResponseHeader GatewayFilter Factory takes a name and value parameter.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: add_request_header_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - AddResponseHeader</span>=X-Response-Foo<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> Bar</pre><p>
</p><p>This will add <code class="literal">X-Response-Foo:Bar</code> header to the downstream response&#8217;s headers for all matching requests.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_hystrix_gatewayfilter_factory" href="#_hystrix_gatewayfilter_factory"></a>5.4&nbsp;Hystrix GatewayFilter Factory</h2></div></div></div><p><a class="link" href="https://github.com/Netflix/Hystrix" target="_top">Hystrix</a> is a library from Netflix that implements the <a class="link" href="https://martinfowler.com/bliki/CircuitBreaker.html" target="_top">circuit breaker pattern</a>.
The Hystrix GatewayFilter allows you to introduce circuit breakers to your gateway routes, protecting your services from cascading failures and allowing you to provide fallback responses in the event of downstream failures.</p><p>To enable Hystrix GatewayFilters in your project, add a dependency on <code class="literal">spring-cloud-starter-netflix-hystrix</code> from <a class="link" href="http://cloud.spring.io/spring-cloud-netflix/" target="_top">Spring Cloud Netflix</a>.</p><p>The Hystrix GatewayFilter Factory requires a single <code class="literal">name</code> parameter, which is the name of the <code class="literal">HystrixCommand</code>.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: hystrix_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Hystrix</span>=myCommandName</pre><p>
</p><p>This wraps the remaining filters in a <code class="literal">HystrixCommand</code> with command name <code class="literal">myCommandName</code>.</p><p>The Hystrix filter can also accept an optional <code class="literal">fallbackUri</code> parameter. Currently, only <code class="literal">forward:</code> schemed URIs are supported. If the fallback is called, the request will be forwarded to the controller matched by the URI.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: hystrix_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: lb://backing-service:<span class="hl-number">8088</span>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> predicates</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Path</span>=/consumingserviceendpoint
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - name</span>: Hystrix
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> args</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> name</span>: fallbackcmd
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> fallbackUri</span>: forward:/incaseoffailureusethis
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - RewritePath</span>=/consumingserviceendpoint<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> /backingserviceendpoint</pre><p>
</p><p>This will forward to the <code class="literal">/incaseoffailureusethis</code> URI when the Hystrix fallback is called. Note that this example also demonstrates (optional) Spring Cloud Netflix Ribbon load-balancing via the <code class="literal">lb</code> prefix on the destination URI.</p><p>Hystrix settings (such as timeouts) can be configured with global defaults or on a route by route basis using application properties as explained on the <a class="link" href="https://github.com/Netflix/Hystrix/wiki/Configuration" target="_top">Hystrix wiki</a>.</p><p>To set a 5 second timeout for the example route above, the following configuration would be used:</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">hystrix.command.fallbackcmd.execution.isolation.thread.timeoutInMilliseconds</span>: <span class="hl-number">5000</span></pre><p>
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_prefixpath_gatewayfilter_factory" href="#_prefixpath_gatewayfilter_factory"></a>5.5&nbsp;PrefixPath GatewayFilter Factory</h2></div></div></div><p>The PrefixPath GatewayFilter Factory takes a single <code class="literal">prefix</code> parameter.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: prefixpath_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - PrefixPath</span>=/mypath</pre><p>
</p><p>This will prefix <code class="literal">/mypath</code> to the path of all matching requests. So a request to <code class="literal">/hello</code>, would be sent to <code class="literal">/mypath/hello</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_preservehostheader_gatewayfilter_factory" href="#_preservehostheader_gatewayfilter_factory"></a>5.6&nbsp;PreserveHostHeader GatewayFilter Factory</h2></div></div></div><p>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.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: preserve_host_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
- PreserveHostHeader</pre><p>
</p><p>This will prefix <code class="literal">/mypath</code> to the path of all matching requests. So a request to <code class="literal">/hello</code>, would be sent to <code class="literal">/mypath/hello</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_requestratelimiter_gatewayfilter_factory" href="#_requestratelimiter_gatewayfilter_factory"></a>5.7&nbsp;RequestRateLimiter GatewayFilter Factory</h2></div></div></div><p>The RequestRateLimiter GatewayFilter Factory takes three parameters: <code class="literal">replenishRate</code>, <code class="literal">burstCapacity</code> &amp; <code class="literal">keyResolverName</code>.</p><p><code class="literal">replenishRate</code> is how many requests per second do you want a user to be allowed to do.</p><p><code class="literal">burstCapacity</code> TODO: document burst capacity</p><p><code class="literal">keyResolver</code> is a bean that implements the <code class="literal">KeyResolver</code> interface. In configuration, reference the bean by name using SpEL. <code class="literal">#{@myKeyResolver}</code> is a SpEL expression referencing a bean with the name <code class="literal">myKeyResolver</code>.</p><p><b>KeyResolver.java.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> KeyResolver {
Mono&lt;String&gt; resolve(ServerWebExchange exchange);
}</pre><p>
</p><p>The <code class="literal">KeyResolver</code> interface allows pluggable strategies to derive the key for limiting requests. In future milestones, there will be some <code class="literal">KeyResolver</code> implementations.</p><p>The redis implementation is based off of work done at <a class="link" href="https://stripe.com/blog/rate-limiters" target="_top">Stripe</a>. It requires the use of the <code class="literal">spring-boot-starter-data-redis-reactive</code> Spring Boot starter.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: requestratelimiter_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - RequestRateLimiter</span>=<span class="hl-number">10</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> <span class="hl-number">20</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">#{@userKeyResolver}</span></pre><p>
</p><p><b>Config.java.&nbsp;</b>
</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Bean</span></em>
KeyResolver userKeyResolver() {
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> exchange -&gt; Mono.just(exchange.getRequest().getQueryParams().getFirst(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"user"</span>));
}</pre><p>
</p><p>This defines a request rate limit of 10 per user. The <code class="literal">KeyResolver</code> is a simple one that gets the <code class="literal">user</code> request parameter (note: this is not recommended for production).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_redirectto_gatewayfilter_factory" href="#_redirectto_gatewayfilter_factory"></a>5.8&nbsp;RedirectTo GatewayFilter Factory</h2></div></div></div><p>The RedirectTo GatewayFilter Factory takes a <code class="literal">status</code> and a <code class="literal">url</code> 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 <code class="literal">Location</code> header.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: prefixpath_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - RedirectTo</span>=<span class="hl-number">302</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> http://acme.org</pre><p>
</p><p>This will send a status 302 with a <code class="literal">Location:http://acme.org</code> header to perform a redirect.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_removenonproxyheaders_gatewayfilter_factory" href="#_removenonproxyheaders_gatewayfilter_factory"></a>5.9&nbsp;RemoveNonProxyHeaders GatewayFilter Factory</h2></div></div></div><p>The RemoveNonProxyHeaders GatewayFilter Factory removes headers from forwarded requests. The default list of headers that is removed comes from the <a class="link" href="https://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-14#section-7.1.3" target="_top">IETF</a>.</p><div class="itemizedlist"><p class="title"><b>The default removed headers are:</b></p><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Connection</li><li class="listitem">Keep-Alive</li><li class="listitem">Proxy-Authenticate</li><li class="listitem">Proxy-Authorization</li><li class="listitem">TE</li><li class="listitem">Trailer</li><li class="listitem">Transfer-Encoding</li><li class="listitem">Upgrade</li></ul></div><p>To change this, set the <code class="literal">spring.cloud.gateway.filter.remove-non-proxy-headers.headers</code> property to the list of header names to remove.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_removerequestheader_gatewayfilter_factory" href="#_removerequestheader_gatewayfilter_factory"></a>5.10&nbsp;RemoveRequestHeader GatewayFilter Factory</h2></div></div></div><p>The RemoveRequestHeader GatewayFilter Factory takes a <code class="literal">name</code> parameter. It is the name of the header to be removed.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: removerequestheader_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - RemoveRequestHeader</span>=X-Request-Foo</pre><p>
</p><p>This will remove the <code class="literal">X-Request-Foo</code> header before it is sent downstream.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_removeresponseheader_gatewayfilter_factory" href="#_removeresponseheader_gatewayfilter_factory"></a>5.11&nbsp;RemoveResponseHeader GatewayFilter Factory</h2></div></div></div><p>The RemoveResponseHeader GatewayFilter Factory takes a <code class="literal">name</code> parameter. It is the name of the header to be removed.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: removeresponseheader_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - RemoveResponseHeader</span>=X-Response-Foo</pre><p>
</p><p>This will remove the <code class="literal">X-Response-Foo</code> header from the response before it is returned to the gateway client.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_rewritepath_gatewayfilter_factory" href="#_rewritepath_gatewayfilter_factory"></a>5.12&nbsp;RewritePath GatewayFilter Factory</h2></div></div></div><p>The RewritePath GatewayFilter Factory takes a path <code class="literal">regexp</code> parameter and a <code class="literal">replacement</code> parameter. This uses Java regular expressions for a flexible way to rewrite the request path.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: rewritepath_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> predicates</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Path</span>=/foo/**
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - RewritePath</span>=/foo/(?&lt;segment&gt;.*)<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> /$\{segment<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre><p>
</p><p>For a request path of <code class="literal">/foo/bar</code>, this will set the path to <code class="literal">/bar</code> before making the downstream request. Notice the <code class="literal">$\</code> which is replaced with <code class="literal">$</code> because of the YAML spec.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_savesession_gatewayfilter_factory" href="#_savesession_gatewayfilter_factory"></a>5.13&nbsp;SaveSession GatewayFilter Factory</h2></div></div></div><p>The SaveSession GatewayFilter Factory forces a <code class="literal">WebSession::save</code> operation <span class="emphasis"><em>before</em></span> forwarding the call downstream. This is of particular use when
using something like <a class="link" href="http://projects.spring.io/spring-session/" target="_top">Spring Session</a> with a lazy data store and need to ensure the session state has been saved before making the forwarded call.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: save_session
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> predicates</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Path</span>=/foo/**
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
- SaveSession</pre><p>
</p><p>If you are integrating <a class="link" href="http://projects.spring.io/spring-security/" target="_top">Spring Security</a> with Spring Session, and want to ensure security details have been forwarded to the remote process, this is critical.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_secureheaders_gatewayfilter_factory" href="#_secureheaders_gatewayfilter_factory"></a>5.14&nbsp;SecureHeaders GatewayFilter Factory</h2></div></div></div><p>The SecureHeaders GatewayFilter Factory adds a number of headers to the response at the reccomendation from <a class="link" href="https://blog.appcanary.com/2017/http-security-headers.html" target="_top">this blog post</a>.</p><div class="itemizedlist"><p class="title"><b>The following headers are added (allong with default values):</b></p><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">X-Xss-Protection:1; mode=block</code></li><li class="listitem"><code class="literal">Strict-Transport-Security:max-age=631138519</code></li><li class="listitem"><code class="literal">X-Frame-Options:DENY</code></li><li class="listitem"><code class="literal">X-Content-Type-Options:nosniff</code></li><li class="listitem"><code class="literal">Referrer-Policy:no-referrer</code></li><li class="listitem"><code class="literal">Content-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'</code></li><li class="listitem"><code class="literal">X-Download-Options:noopen</code></li><li class="listitem"><code class="literal">X-Permitted-Cross-Domain-Policies:none</code></li></ul></div><p>To change the default values set the appropriate property in the <code class="literal">spring.cloud.gateway.filter.secure-headers</code> namespace:</p><div class="itemizedlist"><p class="title"><b>Property to change:</b></p><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">xss-protection-header</code></li><li class="listitem"><code class="literal">strict-transport-security</code></li><li class="listitem"><code class="literal">frame-options</code></li><li class="listitem"><code class="literal">content-type-options</code></li><li class="listitem"><code class="literal">referrer-policy</code></li><li class="listitem"><code class="literal">content-security-policy</code></li><li class="listitem"><code class="literal">download-options</code></li><li class="listitem"><code class="literal">permitted-cross-domain-policies</code></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_setpath_gatewayfilter_factory" href="#_setpath_gatewayfilter_factory"></a>5.15&nbsp;SetPath GatewayFilter Factory</h2></div></div></div><p>The SetPath GatewayFilter Factory takes a path <code class="literal">template</code> 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.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: setpath_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> predicates</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Path</span>=/foo/{segment<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - SetPath</span>=/{segment<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre><p>
</p><p>For a request path of <code class="literal">/foo/bar</code>, this will set the path to <code class="literal">/bar</code> before making the downstream request.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_setresponseheader_gatewayfilter_factory" href="#_setresponseheader_gatewayfilter_factory"></a>5.16&nbsp;SetResponseHeader GatewayFilter Factory</h2></div></div></div><p>The SetResponseHeader GatewayFilter Factory takes <code class="literal">name</code> and <code class="literal">value</code> parameters.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: setresponseheader_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - SetResponseHeader</span>=X-Response-Foo<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> Bar</pre><p>
</p><p>This GatewayFilter replaces all headers with the given name, rather than adding. So if the downstream server responded with a <code class="literal">X-Response-Foo:1234</code>, this would be replaced with <code class="literal">X-Response-Foo:Bar</code>, which is what the gateway client would receive.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_setstatus_gatewayfilter_factory" href="#_setstatus_gatewayfilter_factory"></a>5.17&nbsp;SetStatus GatewayFilter Factory</h2></div></div></div><p>The SetStatus GatewayFilter Factory takes a single <code class="literal">status</code> parameter. It must be a valid Spring <code class="literal">HttpStatus</code>. It may be the integer value <code class="literal">404</code> or the string representation of the enumeration <code class="literal">NOT_FOUND</code>.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: setstatusstring_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - SetStatus</span>=BAD_REQUEST
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: setstatusint_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - SetStatus</span>=<span class="hl-number">401</span></pre><p>
</p><p>In either case, the HTTP status of the response will be set to 401.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_stripprefix_gatewayfilter_factory" href="#_stripprefix_gatewayfilter_factory"></a>5.18&nbsp;StripPrefix GatewayFilter Factory</h2></div></div></div><p>The StripPrefix GatewayFilter Factory takes one paramter, <code class="literal">parts</code>. The <code class="literal">parts</code> parameter indicated the number of parts in the path to strip from the request before sending it downstream.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: nameRoot
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://nameservice
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> predicates</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Path</span>=/name/**
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - StripPrefix</span>=<span class="hl-number">2</span></pre><p>
</p><p>When a request is made through the gateway to <code class="literal">/name/bar/foo</code> the request made to <code class="literal">nameservice</code> will look like <code class="literal"><a class="link" href="http://nameservice/foo" target="_top">http://nameservice/foo</a></code>.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_global_filters" href="#_global_filters"></a>6.&nbsp;Global Filters</h1></div></div></div><p>The <code class="literal">GlobalFilter</code> interface has the same signature as <code class="literal">GatewayFilter</code>. These are special filters that are conditionally applied to all routes. (This interface and usage are subject to change in future milestones).</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_combined_global_filter_and_gatewayfilter_ordering" href="#_combined_global_filter_and_gatewayfilter_ordering"></a>6.1&nbsp;Combined Global Filter and GatewayFilter Ordering</h2></div></div></div><p>TODO: document ordering</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_forward_routing_filter" href="#_forward_routing_filter"></a>6.2&nbsp;Forward Routing Filter</h2></div></div></div><p>The <code class="literal">ForwardRoutingFilter</code> looks for a URI in the exchange attribute <code class="literal">ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR</code>. If the url has a <code class="literal">forward</code> scheme (ie <code class="literal">forward:///localendpoint</code>), it will use the Spring <code class="literal">DispatcherHandler</code> 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 <code class="literal">ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR</code> attribute.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_loadbalancerclient_filter" href="#_loadbalancerclient_filter"></a>6.3&nbsp;LoadBalancerClient Filter</h2></div></div></div><p>The <code class="literal">LoadBalancerClientFilter</code> looks for a URI in the exchange attribute <code class="literal">ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR</code>. If the url has a <code class="literal">lb</code> scheme (ie <code class="literal">lb://myservice</code>), it will use the Spring Cloud <code class="literal">LoadBalancerClient</code> to resolve the name (<code class="literal">myservice</code> 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 <code class="literal">ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR</code> attribute. The filter will also look in the <code class="literal">ServerWebExchangeUtils.GATEWAY_SCHEME_PREFIX_ATTR</code> attribute to see if it equals <code class="literal">lb</code> and then the same rules apply.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_netty_routing_filter" href="#_netty_routing_filter"></a>6.4&nbsp;Netty Routing Filter</h2></div></div></div><p>The Netty Routing Filter runs if the url located in the <code class="literal">ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR</code> exchange attribute has a <code class="literal">http</code> or <code class="literal">https</code> scheme. It uses the Netty <code class="literal">HttpClient</code> to make the downstream proxy request. The response is put in the <code class="literal">ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR</code> exchange attribute for use in a later filter. (There is an experimental <code class="literal">WebClientHttpRoutingFilter</code> that performs the same function, but does not require netty)</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_netty_write_response_filter" href="#_netty_write_response_filter"></a>6.5&nbsp;Netty Write Response Filter</h2></div></div></div><p>The <code class="literal">NettyWriteResponseFilter</code> runs if there is a Netty <code class="literal">HttpClientResponse</code> in the <code class="literal">ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR</code> 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 <code class="literal">WebClientWriteResponseFilter</code> that performs the same function, but does not require netty)</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_routetorequesturl_filter" href="#_routetorequesturl_filter"></a>6.6&nbsp;RouteToRequestUrl Filter</h2></div></div></div><p>The <code class="literal">RouteToRequestUrlFilter</code> runs if there is a <code class="literal">Route</code> object in the <code class="literal">ServerWebExchangeUtils.GATEWAY_ROUTE_ATTR</code> exchange attribute. It creates a new URI, based off of the request URI, but updated with the URI attribute of the <code class="literal">Route</code> object. The new URI is placed in the <code class="literal">ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR</code> exchange attribute`.</p><p>If the URI has a scheme prefix, such as <code class="literal">lb:ws://serviceid</code>, the <code class="literal">lb</code> scheme is stripped from the URI and placed in the <code class="literal">ServerWebExchangeUtils.GATEWAY_SCHEME_PREFIX_ATTR</code> for use later in the filter chain.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_websocket_routing_filter" href="#_websocket_routing_filter"></a>6.7&nbsp;Websocket Routing Filter</h2></div></div></div><p>The Websocket Routing Filter runs if the url located in the <code class="literal">ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR</code> exchange attribute has a <code class="literal">ws</code> or <code class="literal">wss</code> scheme. It uses the Spring Web Socket infrastructure to forward the Websocket request downstream.</p><p>Websockets may be load-balanced by prefixing the URI with <code class="literal">lb</code>, such as <code class="literal">lb:ws://serviceid</code>.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_configuration" href="#_configuration"></a>7.&nbsp;Configuration</h1></div></div></div><p>Configuration for Spring Cloud Gateway is driven by a collection of `RouteDefinitionLocator`s.</p><p><b>RouteDefinitionLocator.java.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> RouteDefinitionLocator {
Flux&lt;RouteDefinition&gt; getRouteDefinitions();
}</pre><p>
</p><p>By default, a <code class="literal">PropertiesRouteDefinitionLocator</code> loads properties using Spring Boot&#8217;s <code class="literal">@ConfigurationProperties</code> mechanism.</p><p>The configuration examples above all use a shortcut notation that uses positional arguments rather than named ones. The two examples below are equivalent:</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: setstatus_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - name</span>: SetStatus
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> args</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> status</span>: <span class="hl-number">401</span>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: setstatusshortcut_route
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://example.org
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> filters</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - SetStatus</span>=<span class="hl-number">401</span></pre><p>
</p><p>For some usages of the gateway, properties will be adequate, but some production use cases will benefit from loading configuration from an external source, such as a database. Future milestone versions will have <code class="literal">RouteDefinitionLocator</code> implementations based off of Spring Data Repositories such as: Redis, MongoDB and Cassandra.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_fluent_java_routes_api" href="#_fluent_java_routes_api"></a>7.1&nbsp;Fluent Java Routes API</h2></div></div></div><p>To allow for simple configuration in Java, there is a fluent API defined in the <code class="literal">RouteLocatorBuilder</code> bean.</p><p><b>GatewaySampleApplication.java.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// static imports from GatewayFilters and RoutePredicates</span>
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> RouteLocator customRouteLocator(RouteLocatorBuilder builder, ThrottleGatewayFilterFactory throttle) {
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> builder.routes()
.route(r -&gt; r.host(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"**.abc.org"</span>).and().path(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/image/png"</span>)
.filters(f -&gt;
f.addResponseHeader(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"X-TestHeader"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foobar"</span>))
.uri(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://httpbin.org:80"</span>)
)
.route(r -&gt; r.path(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/image/webp"</span>)
.filters(f -&gt;
f.addResponseHeader(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"X-AnotherHeader"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"baz"</span>))
.uri(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://httpbin.org:80"</span>)
)
.route(r -&gt; r.order(-<span class="hl-number">1</span>)
.host(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"**.throttle.org"</span>).and().path(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/get"</span>)
.filters(f -&gt; f.filter(throttle.apply(<span class="hl-number">1</span>,
<span class="hl-number">1</span>,
<span class="hl-number">10</span>,
TimeUnit.SECONDS)))
.uri(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://httpbin.org:80"</span>)
)
.build();
}</pre><p>
</p><p>This style also allows for more custom predicate assertions. The predicates defined by <code class="literal">RouteDefinitionLocator</code> beans are combined using logical <code class="literal">and</code>. By using the fluent Java API, you can use the <code class="literal">and()</code>, <code class="literal">or()</code> and <code class="literal">negate()</code> operators on the <code class="literal">Predicate</code> class.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_discoveryclient_route_definition_locator" href="#_discoveryclient_route_definition_locator"></a>7.2&nbsp;DiscoveryClient Route Definition Locator</h2></div></div></div><p>The Gateway can be configured to create routes based on services registered with a <code class="literal">DiscoveryClient</code> compatible service registry.</p><p>To enable this, set <code class="literal">spring.cloud.gateway.discovery.locator.enabled=true</code> and make sure a <code class="literal">DiscoveryClient</code> implementation is on the classpath and enabled (such as Netflix Eureka, Consul or Zookeeper).</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_actuator_api" href="#_actuator_api"></a>8.&nbsp;Actuator API</h1></div></div></div><p>TODO: document the <code class="literal">/gateway</code> actuator endpoint</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_developer_guide" href="#_developer_guide"></a>9.&nbsp;Developer Guide</h1></div></div></div><p>TODO: overview of writing custom integrations</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_writing_custom_route_predicate_factories" href="#_writing_custom_route_predicate_factories"></a>9.1&nbsp;Writing Custom Route Predicate Factories</h2></div></div></div><p>TODO: document writing Custom Route Predicate Factories</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_writing_custom_gatewayfilter_factories" href="#_writing_custom_gatewayfilter_factories"></a>9.2&nbsp;Writing Custom GatewayFilter Factories</h2></div></div></div><p>TODO: document writing Custom GatewayFilter Factories</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_writing_custom_global_filters" href="#_writing_custom_global_filters"></a>9.3&nbsp;Writing Custom Global Filters</h2></div></div></div><p>TODO: document writing Custom Global Filters</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_writing_custom_route_locators_and_writers" href="#_writing_custom_route_locators_and_writers"></a>9.4&nbsp;Writing Custom Route Locators and Writers</h2></div></div></div><p>TODO: document writing Custom Route Locators and Writers</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_building_a_simple_gateway_using_spring_mvc_or_webflux" href="#_building_a_simple_gateway_using_spring_mvc_or_webflux"></a>10.&nbsp;Building a Simple Gateway Using Spring MVC or Webflux</h1></div></div></div><p>Spring Cloud Gateway provides a utility object called <code class="literal">ProxyExchange</code> 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 <code class="literal">forward()</code> method. To use the <code class="literal">ProxyExchange</code> just include the right module in your classpath (either <code class="literal">spring-cloud-gateway-mvc</code> or <code class="literal">spring-cloud-gateway-webflux</code>).</p><p>MVC example (proxying a request to "/test" downstream to a remote server):</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RestController</span></em>
<em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> GatewaySampleApplication {
<em><span class="hl-annotation" style="color: gray">@Value("${remote.home}")</span></em>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> URI home;
<em><span class="hl-annotation" style="color: gray">@GetMapping("/test")</span></em>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> ResponseEntity&lt;?&gt; proxy(ProxyExchange&lt;<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">byte</span>[]&gt; proxy) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> proxy.uri(home.toString() + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/image/png"</span>).get();
}
}</pre><p>The same thing with Webflux:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RestController</span></em>
<em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> GatewaySampleApplication {
<em><span class="hl-annotation" style="color: gray">@Value("${remote.home}")</span></em>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> URI home;
<em><span class="hl-annotation" style="color: gray">@GetMapping("/test")</span></em>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Mono&lt;ResponseEntity&lt;?&gt;&gt; proxy(ProxyExchange&lt;<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">byte</span>[]&gt; proxy) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> proxy.uri(home.toString() + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/image/png"</span>).get();
}
}</pre><p>There are convenience methods on the <code class="literal">ProxyExchange</code> 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:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@GetMapping("/proxy/path/**")</span></em>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> ResponseEntity&lt;?&gt; proxyPath(ProxyExchange&lt;<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">byte</span>[]&gt; proxy) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
String path = proxy.path(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/proxy/path/"</span>);
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> proxy.uri(home.toString() + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/foos/"</span> + path).get();
}</pre><p>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 <code class="literal">@RequestMapping</code> in Spring MVC for more details of those features.</p><p>Headers can be added to the downstream response using the <code class="literal">header()</code> methods on <code class="literal">ProxyExchange</code>.</p><p>You can also manipulate response headers (and anything else you like in the response) by adding a mapper to the <code class="literal">get()</code> etc. method. The mapper is a <code class="literal">Function</code> that takes the incoming <code class="literal">ResponseEntity</code> and converts it to an outgoing one.</p><p>First class support is provided for "sensitive" headers ("cookie" and "authorization" by default) which are not passed downstream, and for "proxy" headers (<code class="literal">x-forwarded-*</code>).</p></div></div></body></html>
Reference in New Issue View Git Blame Copy Permalink