SpringCloud/spring-cloud-gateway
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Sync docs from 2.1.x to gh-pages

Browse Source
This commit is contained in:
buildmaster
2019-07-24 18:31:04 +00:00
parent ce478d3507
commit 4a7e46c8b0
4 changed files with 76 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
2.1.x/multi/multi__gatewayfilter_factories.html
View File

@@ -240,7 +240,16 @@ and have it applied to all routes.</p></div><div class="section"><div class="tit
<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="_rewriteresponseheader_gatewayfilter_factory" href="#_rewriteresponseheader_gatewayfilter_factory"></a>5.15&nbsp;RewriteResponseHeader GatewayFilter Factory</h2></div></div></div><p>The RewriteResponseHeader GatewayFilter Factory takes <code class="literal">name</code>, <code class="literal">regexp</code>, and <code class="literal">replacement</code> parameters. It uses Java regular expressions for a flexible way to rewrite the response header value.</p><p><b>application.yml.&nbsp;</b>
</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="_rewritelocationresponseheader_gatewayfilter_factory" href="#_rewritelocationresponseheader_gatewayfilter_factory"></a>5.15&nbsp;RewriteLocationResponseHeader GatewayFilter Factory</h2></div></div></div><p>The RewriteLocationResponseHeader GatewayFilter Factory modifies the value of <code class="literal">Location</code> response header, usually to get rid of backend specific details. It takes <code class="literal">stripVersionMode</code>, <code class="literal">locationHeaderName</code>, <code class="literal">hostValue</code>, and <code class="literal">protocolsRegex</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>: rewritelocationresponseheader_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"> - RewriteLocationResponseHeader</span>=AS_IN_REQUEST<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> Location<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span></pre><p>
</p><p>For example, for a request <code class="literal">POST <a class="link" href="https://api.example.com/some/object/name" target="_top">https://api.example.com/some/object/name</a></code>, <code class="literal">Location</code> response header value <code class="literal"><a class="link" href="https://object-service.prod.example.net/v2/some/object/id" target="_top">https://object-service.prod.example.net/v2/some/object/id</a></code> will be rewritten as <code class="literal"><a class="link" href="https://api.example.com/some/object/id" target="_top">https://api.example.com/some/object/id</a></code>.</p><p>Parameter <code class="literal">stripVersionMode</code> has the following possible values: <code class="literal">NEVER_STRIP</code>, <code class="literal">AS_IN_REQUEST</code> (default), <code class="literal">ALWAYS_STRIP</code>.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">NEVER_STRIP</code> - Version will not be stripped, even if the original request path contains no version</li><li class="listitem"><code class="literal">AS_IN_REQUEST</code> - Version will be stripped only if the original request path contains no version</li><li class="listitem"><code class="literal">ALWAYS_STRIP</code> - Version will be stripped, even if the original request path contains version</li></ul></div><p>Parameter <code class="literal">hostValue</code>, if provided, will be used to replace the <code class="literal">host:port</code> portion of the response <code class="literal">Location</code> header. If not provided, the value of the <code class="literal">Host</code> request header will be used.</p><p>Parameter <code class="literal">protocolsRegex</code> must be a valid regex <code class="literal">String</code>, against which the protocol name will be matched. If not matched, the filter will do nothing. Default is <code class="literal">http|https|ftp|ftps</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_rewriteresponseheader_gatewayfilter_factory" href="#_rewriteresponseheader_gatewayfilter_factory"></a>5.16&nbsp;RewriteResponseHeader GatewayFilter Factory</h2></div></div></div><p>The RewriteResponseHeader GatewayFilter Factory takes <code class="literal">name</code>, <code class="literal">regexp</code>, and <code class="literal">replacement</code> parameters. It uses Java regular expressions for a flexible way to rewrite the response header value.</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>:
@@ -249,7 +258,7 @@ and have it applied to all routes.</p></div><div class="section"><div class="tit
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://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"> - RewriteResponseHeader</span>=X-Response-Foo<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> password=[^&amp;]+<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> password=***</pre><p>
</p><p>For a header value of <code class="literal">/42?user=ford&amp;password=omg!what&amp;flag=true</code>, it will be set to <code class="literal">/42?user=ford&amp;password=***&amp;flag=true</code> after making the downstream request. Please use <code class="literal">$\</code> to mean <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.16&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
</p><p>For a header value of <code class="literal">/42?user=ford&amp;password=omg!what&amp;flag=true</code>, it will be set to <code class="literal">/42?user=ford&amp;password=***&amp;flag=true</code> after making the downstream request. Please use <code class="literal">$\</code> to mean <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.17&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="https://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>:
@@ -261,7 +270,7 @@ using something like <a class="link" href="https://projects.spring.io/spring-ses
<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="https://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.17&nbsp;SecureHeaders GatewayFilter Factory</h2></div></div></div><p>The SecureHeaders GatewayFilter Factory adds a number of headers to the response at the recommendation 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><p>To disable the default values set the property <code class="literal">spring.cloud.gateway.filter.secure-headers.disable</code> with comma separated values.</p><p><b>Example:&nbsp;</b><code class="literal">spring.cloud.gateway.filter.secure-headers.disable=frame-options,download-options</code></p></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.18&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><p>If you are integrating <a class="link" href="https://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.18&nbsp;SecureHeaders GatewayFilter Factory</h2></div></div></div><p>The SecureHeaders GatewayFilter Factory adds a number of headers to the response at the recommendation 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><p>To disable the default values set the property <code class="literal">spring.cloud.gateway.filter.secure-headers.disable</code> with comma separated values.</p><p><b>Example:&nbsp;</b><code class="literal">spring.cloud.gateway.filter.secure-headers.disable=frame-options,download-options</code></p></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.19&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>:
@@ -272,7 +281,7 @@ using something like <a class="link" href="https://projects.spring.io/spring-ses
<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="_setrequestheader_gatewayfilter_factory" href="#_setrequestheader_gatewayfilter_factory"></a>5.19&nbsp;SetRequestHeader GatewayFilter Factory</h2></div></div></div><p>The SetRequestHeader GatewayFilter Factory takes <code class="literal">name</code> and <code class="literal">value</code> parameters.</p><p><b>application.yml.&nbsp;</b>
</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="_setrequestheader_gatewayfilter_factory" href="#_setrequestheader_gatewayfilter_factory"></a>5.20&nbsp;SetRequestHeader GatewayFilter Factory</h2></div></div></div><p>The SetRequestHeader 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>:
@@ -292,7 +301,7 @@ using something like <a class="link" href="https://projects.spring.io/spring-ses
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Host</span>: {segment}.myhost.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"> - SetRequestHeader</span>=foo<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> bar-{segment<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre><p>
</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.20&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></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.21&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>:
@@ -312,7 +321,7 @@ using something like <a class="link" href="https://projects.spring.io/spring-ses
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Host</span>: {segment}.myhost.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>=foo<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> bar-{segment<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre><p>
</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.21&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></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.22&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>:
@@ -325,7 +334,7 @@ using something like <a class="link" href="https://projects.spring.io/spring-ses
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://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>=<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">401</xslthl:number></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.22&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><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.23&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>:
@@ -336,7 +345,7 @@ using something like <a class="link" href="https://projects.spring.io/spring-ses
<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>=<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">2</xslthl:number></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 class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_retry_gatewayfilter_factory" href="#_retry_gatewayfilter_factory"></a>5.23&nbsp;Retry GatewayFilter Factory</h2></div></div></div><p>The Retry GatewayFilter Factory takes <code class="literal">retries</code>, <code class="literal">statuses</code>, <code class="literal">methods</code>, and <code class="literal">series</code> as parameters.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">retries</code>: the number of retries that should be attempted</li><li class="listitem"><code class="literal">statuses</code>: the HTTP status codes that should be retried, represented using <code class="literal">org.springframework.http.HttpStatus</code></li><li class="listitem"><code class="literal">methods</code>: the HTTP methods that should be retried, represented using <code class="literal">org.springframework.http.HttpMethod</code></li><li class="listitem"><code class="literal">series</code>: the series of status codes to be retried, represented using <code class="literal">org.springframework.http.HttpStatus.Series</code></li></ul></div><p><b>application.yml.&nbsp;</b>
</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 class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_retry_gatewayfilter_factory" href="#_retry_gatewayfilter_factory"></a>5.24&nbsp;Retry GatewayFilter Factory</h2></div></div></div><p>The Retry GatewayFilter Factory takes <code class="literal">retries</code>, <code class="literal">statuses</code>, <code class="literal">methods</code>, and <code class="literal">series</code> as parameters.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">retries</code>: the number of retries that should be attempted</li><li class="listitem"><code class="literal">statuses</code>: the HTTP status codes that should be retried, represented using <code class="literal">org.springframework.http.HttpStatus</code></li><li class="listitem"><code class="literal">methods</code>: the HTTP methods that should be retried, represented using <code class="literal">org.springframework.http.HttpMethod</code></li><li class="listitem"><code class="literal">series</code>: the series of status codes to be retried, represented using <code class="literal">org.springframework.http.HttpStatus.Series</code></li></ul></div><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>:
@@ -350,7 +359,7 @@ using something like <a class="link" href="https://projects.spring.io/spring-ses
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> args</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> retries</span>: <xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">3</xslthl:number>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> statuses</span>: BAD_GATEWAY</pre><p>
</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>The retry filter does not currently support retrying with a body (e.g. for POST or PUT requests with a body).</p></td></tr></table></div><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>When using the retry filter with a <code class="literal">forward:</code> prefixed URL, the target endpoint should be written carefully so that in case of an error it does not do anything that could result in a response being sent to the client and committed. For example, if the target endpoint is an annotated controller, the target controller method should not return <code class="literal">ResponseEntity</code> with an error status code. Instead it should throw an <code class="literal">Exception</code>, or signal an error, e.g. via a <code class="literal">Mono.error(ex)</code> return value, which the retry filter can be configured to handle by retrying.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_requestsize_gatewayfilter_factory" href="#_requestsize_gatewayfilter_factory"></a>5.24&nbsp;RequestSize GatewayFilter Factory</h2></div></div></div><p>The RequestSize GatewayFilter Factory can restrict a request from reaching the downstream service , when the request size is greater than the permissible limit. The filter takes <code class="literal">RequestSize</code> as parameter which is the permissible size limit of the request defined in bytes.</p><p><b>application.yml.&nbsp;</b>
</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>The retry filter does not currently support retrying with a body (e.g. for POST or PUT requests with a body).</p></td></tr></table></div><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>When using the retry filter with a <code class="literal">forward:</code> prefixed URL, the target endpoint should be written carefully so that in case of an error it does not do anything that could result in a response being sent to the client and committed. For example, if the target endpoint is an annotated controller, the target controller method should not return <code class="literal">ResponseEntity</code> with an error status code. Instead it should throw an <code class="literal">Exception</code>, or signal an error, e.g. via a <code class="literal">Mono.error(ex)</code> return value, which the retry filter can be configured to handle by retrying.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_requestsize_gatewayfilter_factory" href="#_requestsize_gatewayfilter_factory"></a>5.25&nbsp;RequestSize GatewayFilter Factory</h2></div></div></div><p>The RequestSize GatewayFilter Factory can restrict a request from reaching the downstream service , when the request size is greater than the permissible limit. The filter takes <code class="literal">RequestSize</code> as parameter which is the permissible size limit of the request defined in bytes.</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>:
@@ -363,7 +372,7 @@ using something like <a class="link" href="https://projects.spring.io/spring-ses
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - name</span>: RequestSize
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> args</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> maxSize</span>: <xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">5000000</xslthl:number></pre><p>
</p><p>The RequestSize GatewayFilter Factory set the response status as <code class="literal">413 Payload Too Large</code> with a additional header <code class="literal">errorMessage</code> when the Request is rejected due to size. Following is an example of such an <code class="literal">errorMessage</code> .</p><p><code class="literal">errorMessage</code> : <code class="literal">Request size is larger than permissible limit. Request size is 6.0 MB where permissible limit is 5.0 MB</code></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>The default Request size will be set to 5 MB if not provided as filter argument in route definition.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_modify_request_body_gatewayfilter_factory" href="#_modify_request_body_gatewayfilter_factory"></a>5.25&nbsp;Modify Request Body GatewayFilter Factory</h2></div></div></div><p><span class="strong"><strong>This filter is considered BETA and the API may change in the future</strong></span></p><p>This filter can be used to modify the request body before it is sent downstream by the Gateway.</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>This filter can only be configured using the Java DSL</p></td></tr></table></div><pre class="programlisting"><xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@Bean</xslthl:annotation>
</p><p>The RequestSize GatewayFilter Factory set the response status as <code class="literal">413 Payload Too Large</code> with a additional header <code class="literal">errorMessage</code> when the Request is rejected due to size. Following is an example of such an <code class="literal">errorMessage</code> .</p><p><code class="literal">errorMessage</code> : <code class="literal">Request size is larger than permissible limit. Request size is 6.0 MB where permissible limit is 5.0 MB</code></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>The default Request size will be set to 5 MB if not provided as filter argument in route definition.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_modify_request_body_gatewayfilter_factory" href="#_modify_request_body_gatewayfilter_factory"></a>5.26&nbsp;Modify Request Body GatewayFilter Factory</h2></div></div></div><p><span class="strong"><strong>This filter is considered BETA and the API may change in the future</strong></span></p><p>This filter can be used to modify the request body before it is sent downstream by the Gateway.</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>This filter can only be configured using the Java DSL</p></td></tr></table></div><pre class="programlisting"><xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@Bean</xslthl:annotation>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> RouteLocator routes(RouteLocatorBuilder builder) {
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> builder.routes()
.route(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"rewrite_request_obj"</span>, r -&gt; r.host(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"*.rewriterequestobj.org"</span>)
@@ -389,7 +398,7 @@ using something like <a class="link" href="https://projects.spring.io/spring-ses
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> setMessage(String message) {
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.message = message;
}
}</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_modify_response_body_gatewayfilter_factory" href="#_modify_response_body_gatewayfilter_factory"></a>5.26&nbsp;Modify Response Body GatewayFilter Factory</h2></div></div></div><p><span class="strong"><strong>This filter is considered BETA and the API may change in the future</strong></span></p><p>This filter can be used to modify the response body before it is sent back to the Client.</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>This filter can only be configured using the Java DSL</p></td></tr></table></div><pre class="programlisting"><xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@Bean</xslthl:annotation>
}</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_modify_response_body_gatewayfilter_factory" href="#_modify_response_body_gatewayfilter_factory"></a>5.27&nbsp;Modify Response Body GatewayFilter Factory</h2></div></div></div><p><span class="strong"><strong>This filter is considered BETA and the API may change in the future</strong></span></p><p>This filter can be used to modify the response body before it is sent back to the Client.</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>This filter can only be configured using the Java DSL</p></td></tr></table></div><pre class="programlisting"><xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@Bean</xslthl:annotation>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> RouteLocator routes(RouteLocatorBuilder builder) {
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> builder.routes()
.route(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"rewrite_response_upper"</span>, r -&gt; r.host(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"*.rewriteresponseupper.org"</span>)
@@ -397,7 +406,7 @@ using something like <a class="link" href="https://projects.spring.io/spring-ses
.modifyResponseBody(String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>,
(exchange, s) -&gt; Mono.just(s.toUpperCase()))).uri(uri)
.build();
}</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_default_filters" href="#_default_filters"></a>5.27&nbsp;Default Filters</h2></div></div></div><p>If you would like to add a filter and apply it to all routes you can use <code class="literal">spring.cloud.gateway.default-filters</code>.
}</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_default_filters" href="#_default_filters"></a>5.28&nbsp;Default Filters</h2></div></div></div><p>If you would like to add a filter and apply it to all routes you can use <code class="literal">spring.cloud.gateway.default-filters</code>.
This property takes a list of filters</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>:

2
2.1.x/multi/multi_spring-cloud-gateway.html
View File

File diff suppressed because one or more lines are too long

35
2.1.x/single/spring-cloud-gateway.html
View File

File diff suppressed because one or more lines are too long

32
2.1.x/spring-cloud-gateway.xml
View File

@@ -808,6 +808,38 @@ and have it applied to all routes.</simpara>
</formalpara>
<simpara>For a request path of <literal>/foo/bar</literal>, this will set the path to <literal>/bar</literal> before making the downstream request. Notice the <literal>$\</literal> which is replaced with <literal>$</literal> because of the YAML spec.</simpara>
</section>
<section xml:id="_rewritelocationresponseheader_gatewayfilter_factory">
<title>RewriteLocationResponseHeader GatewayFilter Factory</title>
<simpara>The RewriteLocationResponseHeader GatewayFilter Factory modifies the value of <literal>Location</literal> response header, usually to get rid of backend specific details. It takes <literal>stripVersionMode</literal>, <literal>locationHeaderName</literal>, <literal>hostValue</literal>, and <literal>protocolsRegex</literal> parameters.</simpara>
<formalpara>
<title>application.yml</title>
<para>
<programlisting language="yaml" linenumbering="unnumbered">spring:
cloud:
gateway:
routes:
- id: rewritelocationresponseheader_route
uri: http://example.org
filters:
- RewriteLocationResponseHeader=AS_IN_REQUEST, Location, ,</programlisting>
</para>
</formalpara>
<simpara>For example, for a request <literal>POST <link xl:href="https://api.example.com/some/object/name">https://api.example.com/some/object/name</link></literal>, <literal>Location</literal> response header value <literal><link xl:href="https://object-service.prod.example.net/v2/some/object/id">https://object-service.prod.example.net/v2/some/object/id</link></literal> will be rewritten as <literal><link xl:href="https://api.example.com/some/object/id">https://api.example.com/some/object/id</link></literal>.</simpara>
<simpara>Parameter <literal>stripVersionMode</literal> has the following possible values: <literal>NEVER_STRIP</literal>, <literal>AS_IN_REQUEST</literal> (default), <literal>ALWAYS_STRIP</literal>.</simpara>
<itemizedlist>
<listitem>
<simpara><literal>NEVER_STRIP</literal> - Version will not be stripped, even if the original request path contains no version</simpara>
</listitem>
<listitem>
<simpara><literal>AS_IN_REQUEST</literal> - Version will be stripped only if the original request path contains no version</simpara>
</listitem>
<listitem>
<simpara><literal>ALWAYS_STRIP</literal> - Version will be stripped, even if the original request path contains version</simpara>
</listitem>
</itemizedlist>
<simpara>Parameter <literal>hostValue</literal>, if provided, will be used to replace the <literal>host:port</literal> portion of the response <literal>Location</literal> header. If not provided, the value of the <literal>Host</literal> request header will be used.</simpara>
<simpara>Parameter <literal>protocolsRegex</literal> must be a valid regex <literal>String</literal>, against which the protocol name will be matched. If not matched, the filter will do nothing. Default is <literal>http|https|ftp|ftps</literal>.</simpara>
</section>
<section xml:id="_rewriteresponseheader_gatewayfilter_factory">
<title>RewriteResponseHeader GatewayFilter Factory</title>
<simpara>The RewriteResponseHeader GatewayFilter Factory takes <literal>name</literal>, <literal>regexp</literal>, and <literal>replacement</literal> parameters. It uses Java regular expressions for a flexible way to rewrite the response header value.</simpara>