This project provides an API Gateway built on top of the Spring Ecosystem, including: Spring 6, Spring Boot 3 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.
== Features
[[features]]
= Features
* Java 17
* Spring Framework 6
@ -25,99 +24,20 @@ This project provides an API Gateway built on top of the Spring Ecosystem, inclu
@@ -25,99 +24,20 @@ This project provides an API Gateway built on top of the Spring Ecosystem, inclu
* API or configuration driven
* Supports Spring Cloud `DiscoveryClient` for configuring Routes
== Building
:jdkversion: 17
=== Basic Compile and Test
[[building]]
= Building
To build the source you will need to install JDK {jdkversion}.
Spring Cloud uses Maven for most build-related activities, and you
should be able to get off the ground quite quickly by cloning the
project you are interested in and typing
----
$ ./mvnw install
----
NOTE: You can also install Maven (>=3.3.3) yourself and run the `mvn` command
in place of `./mvnw` in the examples below. If you do that you also
might need to add `-P spring` if your local Maven settings do not
contain repository declarations for spring pre-release artifacts.
NOTE: Be aware that you might need to increase the amount of memory
available to Maven by setting a `MAVEN_OPTS` environment variable with
a value like `-Xmx512m -XX:MaxPermSize=128m`. We try to cover this in
the `.mvn` configuration, so if you find you have to do it to make a
build succeed, please raise a ticket to get the settings added to
source control.
The projects that require middleware (i.e. Redis) for testing generally
require that a local instance of [Docker](https://www.docker.com/get-started) is installed and running.
=== Documentation
The spring-cloud-build module has a "docs" profile, and if you switch
that on it will try to build asciidoc sources from
`src/main/asciidoc`. As part of that process it will look for a
`README.adoc` and process it by loading all the includes, but not
parsing or rendering it, just copying it to `${main.basedir}`
(defaults to `${basedir}`, i.e. the root of the project). If there are
any changes in the README it will then show up after a Maven build as
a modified file in the correct place. Just commit it and push the change.
=== Working with the code
If you don't have an IDE preference we would recommend that you use
https://www.springsource.com/developer/sts[Spring Tools Suite] or
https://eclipse.org[Eclipse] when working with the code. We use the
https://eclipse.org/m2e/[m2eclipse] eclipse plugin for maven support. Other IDEs and tools
should also work without issue as long as they use Maven 3.3.3 or better.
==== Activate the Spring Maven profile
Spring Cloud projects require the 'spring' Maven profile to be activated to resolve
the spring milestone and snapshot repositories. Use your preferred IDE to set this
profile to be active, or you may experience build errors.
==== Importing into eclipse with m2eclipse
We recommend the https://eclipse.org/m2e/[m2eclipse] eclipse plugin when working with
eclipse. If you don't already have m2eclipse installed it is available from the "eclipse
marketplace".
NOTE: Older versions of m2e do not support Maven 3.3, so once the
projects are imported into Eclipse you will also need to tell
m2eclipse to use the right profile for the projects. If you
see many different errors related to the POMs in the projects, check
that you have an up to date installation. If you can't upgrade m2e,
add the "spring" profile to your `settings.xml`. Alternatively you can
copy the repository settings from the "spring" profile of the parent
pom into your `settings.xml`.
==== Importing into eclipse without m2eclipse
If you prefer not to use m2eclipse you can generate eclipse project metadata using the
following command:
[indent=0]
----
$ ./mvnw eclipse:eclipse
----
The generated eclipse projects can be imported by selecting `import existing projects`
from the `file` menu.
== Contributing
:spring-cloud-build-branch: master
:spring-cloud-build-branch: main
Spring Cloud is released under the non-restrictive Apache 2.0 license,
and follows a very standard Github development process, using Github
tracker for issues and merging pull requests into master. If you want
tracker for issues and merging pull requests into main. If you want
to contribute even something trivial please do not hesitate, but
follow the guidelines below.
=== Sign the Contributor License Agreement
[[sign-the-contributor-license-agreement]]
== Sign the Contributor License Agreement
Before we accept a non-trivial patch or pull request we will need you to sign the
Signing the contributor's agreement does not grant anyone commit rights to the main
@ -125,19 +45,21 @@ repository, but it does mean that we can accept your contributions, and you will
@@ -125,19 +45,21 @@ repository, but it does mean that we can accept your contributions, and you will
author credit if we do. Active contributors might be asked to join the core team, and
given the ability to merge pull requests.
=== Code of Conduct
This project adheres to the Contributor Covenant https://github.com/spring-cloud/spring-cloud-build/blob/master/docs/src/main/asciidoc/code-of-conduct.adoc[code of
[[code-of-conduct]]
== Code of Conduct
This project adheres to the Contributor Covenant https://github.com/spring-cloud/spring-cloud-build/blob/main/docs/src/main/asciidoc/code-of-conduct.adoc[code of
conduct]. By participating, you are expected to uphold this code. Please report
unacceptable behavior to spring-code-of-conduct@pivotal.io.
=== Code Conventions and Housekeeping
[[code-conventions-and-housekeeping]]
== Code Conventions and Housekeeping
None of these is essential for a pull request, but they will all help. They can also be
added after the original pull request but before a merge.
* Use the Spring Framework code format conventions. If you use Eclipse
@ -150,13 +72,14 @@ added after the original pull request but before a merge.
@@ -150,13 +72,14 @@ added after the original pull request but before a merge.
than cosmetic changes).
* Add some Javadocs and, if you change the namespace, some XSD doc elements.
* A few unit tests would help a lot as well -- someone has to do it.
* If no-one else is using your branch, please rebase it against the current master (or
* If no-one else is using your branch, please rebase it against the current main (or
other target branch in the main project).
* When writing a commit message please follow https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[these conventions],
if you are fixing an existing issue please add `Fixes gh-XXXX` at the end of the commit
message (where XXXX is the issue number).
=== Checkstyle
[[checkstyle]]
== Checkstyle
Spring Cloud Build comes with a set of checkstyle rules. You can find them in the `spring-cloud-build-tools` module. The most notable files under the module are:
@ -174,7 +97,8 @@ Spring Cloud Build comes with a set of checkstyle rules. You can find them in th
@@ -174,7 +97,8 @@ Spring Cloud Build comes with a set of checkstyle rules. You can find them in th
<2> File header setup
<3> Default suppression rules
==== Checkstyle configuration
[[checkstyle-configuration]]
=== Checkstyle configuration
Checkstyle rules are *disabled by default*. To add checkstyle to your project just define the following properties and plugins.
@ -233,16 +157,18 @@ If you need to suppress some rules (e.g. line length needs to be longer), then i
@@ -233,16 +157,18 @@ If you need to suppress some rules (e.g. line length needs to be longer), then i
It's advisable to copy the `${spring-cloud-build.rootFolder}/.editorconfig` and `${spring-cloud-build.rootFolder}/.springformat` to your project. That way, some default formatting rules will be applied. You can do so by running this script:
In order to setup Intellij you should import our coding conventions, inspection profiles and set up the checkstyle plugin.
The following files can be found in the https://github.com/spring-cloud/spring-cloud-build/tree/master/spring-cloud-build-tools[Spring Cloud Build] project.
The following files can be found in the https://github.com/spring-cloud/spring-cloud-build/tree/main/spring-cloud-build-tools[Spring Cloud Build] project.
.spring-cloud-build-tools/
----
@ -265,13 +191,13 @@ The following files can be found in the https://github.com/spring-cloud/spring-c
@@ -265,13 +191,13 @@ The following files can be found in the https://github.com/spring-cloud/spring-c
Go to `File` -> `Settings` -> `Editor` -> `Code style`. There click on the icon next to the `Scheme` section. There, click on the `Import Scheme` value and pick the `Intellij IDEA code style XML` option. Import the `spring-cloud-build-tools/src/main/resources/intellij/Intellij_Spring_Boot_Java_Conventions.xml` file.
Go to `File` -> `Settings` -> `Editor` -> `Inspections`. There click on the icon next to the `Profile` section. There, click on the `Import Profile` and import the `spring-cloud-build-tools/src/main/resources/intellij/Intellij_Project_Defaults.xml` file.
@ -279,21 +205,23 @@ Go to `File` -> `Settings` -> `Editor` -> `Inspections`. There click on the icon
@@ -279,21 +205,23 @@ Go to `File` -> `Settings` -> `Editor` -> `Inspections`. There click on the icon
To have Intellij work with Checkstyle, you have to install the `Checkstyle` plugin. It's advisable to also install the `Assertions2Assertj` to automatically convert the JUnit assertions
Go to `File` -> `Settings` -> `Other settings` -> `Checkstyle`. There click on the `+` icon in the `Configuration file` section. There, you'll have to define where the checkstyle rules should be picked from. In the image above, we've picked the rules from the cloned Spring Cloud Build repository. However, you can point to the Spring Cloud Build's GitHub repository (e.g. for the `checkstyle.xml` : `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle.xml`). We need to provide the following variables:
Go to `File` -> `Settings` -> `Other settings` -> `Checkstyle`. There click on the `+` icon in the `Configuration file` section. There, you'll have to define where the checkstyle rules should be picked from. In the image above, we've picked the rules from the cloned Spring Cloud Build repository. However, you can point to the Spring Cloud Build's GitHub repository (e.g. for the `checkstyle.xml` : `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/spring-cloud-build-tools/src/main/resources/checkstyle.xml`). We need to provide the following variables:
- `checkstyle.header.file` - please point it to the Spring Cloud Build's, `spring-cloud-build-tools/src/main/resources/checkstyle-header.txt` file either in your cloned repo or via the `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle-header.txt` URL.
- `checkstyle.suppressions.file` - default suppressions. Please point it to the Spring Cloud Build's, `spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml` file either in your cloned repo or via the `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml` URL.
- `checkstyle.header.file` - please point it to the Spring Cloud Build's, `spring-cloud-build-tools/src/main/resources/checkstyle-header.txt` file either in your cloned repo or via the `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/spring-cloud-build-tools/src/main/resources/checkstyle-header.txt` URL.
- `checkstyle.suppressions.file` - default suppressions. Please point it to the Spring Cloud Build's, `spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml` file either in your cloned repo or via the `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml` URL.
- `checkstyle.additional.suppressions.file` - this variable corresponds to suppressions in your local project. E.g. you're working on `spring-cloud-contract`. Then point to the `project-root/src/checkstyle/checkstyle-suppressions.xml` folder. Example for `spring-cloud-contract` would be: `/home/username/spring-cloud-contract/src/checkstyle/checkstyle-suppressions.xml`.
IMPORTANT: Remember to set the `Scan Scope` to `All sources` since we apply checkstyle rules for production and test sources.
=== Duplicate Finder
[[duplicate-finder]]
== Duplicate Finder
Spring Cloud Build brings along the `basepom:duplicate-finder-maven-plugin`, that enables flagging duplicate and conflicting classes and resources on the java classpath.
==== Duplicate Finder configuration
[[duplicate-finder-configuration]]
=== Duplicate Finder configuration
Duplicate finder is *enabled by default* and will run in the `verify` phase of your Maven build, but it will only take effect in your project if you add the `duplicate-finder-maven-plugin` to the `build` section of the projecst's `pom.xml`.
@ -339,3 +267,8 @@ If you need to add `ignoredClassPatterns` or `ignoredResourcePatterns` to your s
@@ -339,3 +267,8 @@ If you need to add `ignoredClassPatterns` or `ignoredResourcePatterns` to your s
----
[[contributing]]
= Contributing
Unresolved directive in <stdin> - include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing.adoc[]
This project provides an API Gateway built on top of the Spring Ecosystem, including: Spring 6, Spring Boot 3 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.
= Building a Simple Gateway by Using Spring MVC or Webflux
[[proxy-exchange-gateway]]
= Proxy Exchange Gateway with Spring MVC or Webflux
WARNING: The following describes an alternative style gateway. None of the prior documentation applies to what follows.
WARNING: The following describes an alternative style gateway. None of the Spring Cloud Gateway Server documentation applies to what follows.
Spring Cloud Gateway provides a utility object called `ProxyExchange`.
You can use it inside a regular Spring web handler as a method parameter.
@ -11,7 +11,6 @@ To use the `ProxyExchange`, include the right module in your classpath (either `
@@ -11,7 +11,6 @@ To use the `ProxyExchange`, include the right module in your classpath (either `
The following MVC example proxies a request to `/test` downstream to a remote server:
====
[source,java]
----
@RestController
@ -28,11 +27,9 @@ public class GatewaySampleApplication {
@@ -28,11 +27,9 @@ public class GatewaySampleApplication {
}
----
====
The following example does the same thing with Webflux:
====
[source,java]
----
@RestController
@ -49,12 +46,10 @@ public class GatewaySampleApplication {
@@ -49,12 +46,10 @@ public class GatewaySampleApplication {
}
----
====
Convenience methods on the `ProxyExchange` 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:
====
[source,java]
----
@GetMapping("/proxy/path/**")
@ -63,7 +58,6 @@ public ResponseEntity<?> proxyPath(ProxyExchange<byte[]> proxy) throws Exception
@@ -63,7 +58,6 @@ public ResponseEntity<?> proxyPath(ProxyExchange<byte[]> proxy) throws Exception
All the features of Spring MVC and Webflux are available to gateway handler methods.
As a result, you can inject request headers and query parameters, for instance, and you can constrain the incoming requests with declarations in the mapping annotation.
To include Spring Cloud Gateway Server MVC in your project, use the starter with a group ID of `org.springframework.cloud` and an artifact ID of `spring-cloud-starter-gateway-mvc`.
See the https://projects.spring.io/spring-cloud/[Spring Cloud Project page] for details on setting up your build system with the current Spring Cloud Release Train.
If you include the starter, but you do not want the gateway to be enabled, set `spring.cloud.gateway.enabled=false`.
IMPORTANT: Spring Cloud Gateway Server MVC is built on https://spring.io/projects/spring-boot#learn[Spring Boot] and https://docs.spring.io/spring-framework/reference/web.html[Spring Web MVC].
As a consequence, many of the asynchronous or reactive libraries may not apply when you use Spring Cloud Gateway Server MVC.
IMPORTANT: Spring Cloud Gateway Server MVC works with traditional Servlet runtimes such as Tomcat and Jetty.
@ -6,13 +6,11 @@ To be remotely accessible, the endpoint has to be https://docs.spring.io/spring-
@@ -6,13 +6,11 @@ To be remotely accessible, the endpoint has to be https://docs.spring.io/spring-
The following listing shows how to do so:
.application.properties
====
[source,properties]
----
management.endpoint.gateway.enabled=true # default value
management.endpoints.web.exposure.include=gateway
----
====
[[verbose-actuator-format]]
== Verbose Actuator Format
@ -21,7 +19,6 @@ A new, more verbose format has been added to Spring Cloud Gateway.
@@ -21,7 +19,6 @@ A new, more verbose format has been added to Spring Cloud Gateway.
It adds more detail to each route, letting you view the predicates and filters associated with each route along with any configuration that is available.
The following example configures `/actuator/gateway/routes`:
====
[source,json]
----
[
@ -38,17 +35,14 @@ The following example configures `/actuator/gateway/routes`:
@@ -38,17 +35,14 @@ The following example configures `/actuator/gateway/routes`:
}
]
----
====
This feature is enabled by default. To disable it, set the following property:
@ -65,7 +59,6 @@ This section details how to retrieve route filters, including:
@@ -65,7 +59,6 @@ This section details how to retrieve route filters, including:
To retrieve the xref:spring-cloud-gateway/global-filters.adoc[global filters] applied to all routes, make a `GET` request to `/actuator/gateway/globalfilters`. The resulting response is similar to the following:
@ -78,7 +71,6 @@ To retrieve the xref:spring-cloud-gateway/global-filters.adoc[global filters] ap
@@ -78,7 +71,6 @@ To retrieve the xref:spring-cloud-gateway/global-filters.adoc[global filters] ap
The response contains the details of the global filters that are in place.
For each global filter, there is a string representation of the filter object (for example, `org.springframework.cloud.gateway.filter.ReactiveLoadBalancerClientFilter@77856cc5`) and the corresponding xref:spring-cloud-gateway/global-filters.adoc#gateway-combined-global-filter-and-gatewayfilter-ordering[order] in the filter chain.
@ -88,7 +80,6 @@ For each global filter, there is a string representation of the filter object (f
@@ -88,7 +80,6 @@ For each global filter, there is a string representation of the filter object (f
To retrieve the xref:spring-cloud-gateway/gatewayfilter-factories.adoc[`GatewayFilter` factories] applied to routes, make a `GET` request to `/actuator/gateway/routefilters`.
The resulting response is similar to the following:
The response contains the details of the `GatewayFilter` factories applied to any particular route.
For each factory there is a string representation of the corresponding object (for example, `[SecureHeadersGatewayFilterFactory@fceab5d configClass = Object]`).
@ -112,7 +102,6 @@ To clear the routes with specific metadata values, add the Query parameter `meta
@@ -112,7 +102,6 @@ To clear the routes with specific metadata values, add the Query parameter `meta
If an error is produced during the asynchronous refresh, the refresh will not modify the existing routes.
Sending `POST` request to `/actuator/gateway/refresh?metadata=group:group-1` will only refresh the routes whose `group` metadata is `group-1`: `first_route` and `third_route`.
====
[source,json]
----
[{
@ -137,7 +126,6 @@ Sending `POST` request to `/actuator/gateway/refresh?metadata=group:group-1` wil
@@ -137,7 +126,6 @@ Sending `POST` request to `/actuator/gateway/refresh?metadata=group:group-1` wil
"metadata": { "group": "group-1" }
}]
----
====
[[retrieving-the-routes-defined-in-the-gateway]]
== Retrieving the Routes Defined in the Gateway
@ -145,7 +133,6 @@ Sending `POST` request to `/actuator/gateway/refresh?metadata=group:group-1` wil
@@ -145,7 +133,6 @@ Sending `POST` request to `/actuator/gateway/refresh?metadata=group:group-1` wil
To retrieve the routes defined in the gateway, make a `GET` request to `/actuator/gateway/routes`.
The resulting response is similar to the following:
====
----
[{
"route_id": "first_route",
@ -166,7 +153,6 @@ The resulting response is similar to the following:
@@ -166,7 +153,6 @@ The resulting response is similar to the following:
"order": 0
}]
----
====
The response contains the details of all the routes defined in the gateway.
The following table describes the structure of each element (each is a route) of the response:
@ -196,10 +182,9 @@ The following table describes the structure of each element (each is a route) of
@@ -196,10 +182,9 @@ The following table describes the structure of each element (each is a route) of
== Retrieving Information about a Particular Route
To retrieve information about a single route, make a `GET` request to `/actuator/gateway/routes/{id}` (for example, `/actuator/gateway/routes/first_route`).
To retrieve information about a single route, make a `GET` request to `/actuator/gateway/routes/\{id}` (for example, `/actuator/gateway/routes/first_route`).
The resulting response is similar to the following:
====
----
{
"id": "first_route",
@ -212,7 +197,6 @@ The resulting response is similar to the following:
@@ -212,7 +197,6 @@ The resulting response is similar to the following:
"order": 0
}
----
====
The following table describes the structure of the response:
@ -245,9 +229,9 @@ The following table describes the structure of the response:
@@ -245,9 +229,9 @@ The following table describes the structure of the response:
== Creating and Deleting a Particular Route Definition
To create a route definition, make a `POST` request to `/gateway/routes/{id_route_to_create}` with a JSON body that specifies the fields of the route (see xref:spring-cloud-gateway/actuator-api.adoc#gateway-retrieving-information-about-a-particular-route[Retrieving Information about a Particular Route]).
To create a route definition, make a `POST` request to `/gateway/routes/\{id_route_to_create}` with a JSON body that specifies the fields of the route (see xref:spring-cloud-gateway/actuator-api.adoc#gateway-retrieving-information-about-a-particular-route[Retrieving Information about a Particular Route]).
To delete a route definition, make a `DELETE` request to `/gateway/routes/{id_route_to_delete}`.
To delete a route definition, make a `DELETE` request to `/gateway/routes/\{id_route_to_delete}`.
[[creating-multiple-route-definitions]]
== Creating multiple Route Definitions
@ -281,15 +265,15 @@ The following table below summarizes the Spring Cloud Gateway actuator endpoints
@@ -281,15 +265,15 @@ The following table below summarizes the Spring Cloud Gateway actuator endpoints
|GET
| Displays the list of routes defined in the gateway.
@ -5,14 +5,12 @@ Configuration for Spring Cloud Gateway is driven by a collection of `RouteDefini
@@ -5,14 +5,12 @@ Configuration for Spring Cloud Gateway is driven by a collection of `RouteDefini
The following listing shows the definition of the `RouteDefinitionLocator` interface:
.RouteDefinitionLocator.java
====
[source,java]
----
public interface RouteDefinitionLocator {
Flux<RouteDefinition> getRouteDefinitions();
}
----
====
By default, a `PropertiesRouteDefinitionLocator` loads properties by using Spring Boot's `@ConfigurationProperties` mechanism.
@ -20,7 +18,6 @@ The earlier configuration examples all use a shortcut notation that uses positio
@@ -20,7 +18,6 @@ The earlier configuration examples all use a shortcut notation that uses positio
For some usages of the gateway, properties are adequate, but some production use cases benefit from loading configuration from an external source, such as a database. Future milestone versions will have `RouteDefinitionLocator` implementations based off of Spring Data Repositories, such as Redis, MongoDB, and Cassandra.
@ -12,7 +12,6 @@ The "`global`" CORS configuration is a map of URL patterns to {cors-configuratio
@@ -12,7 +12,6 @@ The "`global`" CORS configuration is a map of URL patterns to {cors-configuratio
In the preceding example, CORS requests are allowed from requests that originate from `docs.spring.io` for all GET requested paths.
@ -41,7 +39,6 @@ Like in the case of global configuration, the properties belong to {cors-configu
@@ -41,7 +39,6 @@ Like in the case of global configuration, the properties belong to {cors-configu
NOTE: If no `Path` predicate is present in the route '/**' will be applied.
@ -5,7 +5,6 @@ To allow for simple configuration in Java, the `RouteLocatorBuilder` bean includ
@@ -5,7 +5,6 @@ To allow for simple configuration in Java, the `RouteLocatorBuilder` bean includ
The following listing shows how it works:
.GatewaySampleApplication.java
====
[source,java]
----
// static imports from GatewayFilters and RoutePredicates
@ -35,7 +34,6 @@ public RouteLocator customRouteLocator(RouteLocatorBuilder builder, ThrottleGate
@@ -35,7 +34,6 @@ public RouteLocator customRouteLocator(RouteLocatorBuilder builder, ThrottleGate
.build();
}
----
====
This style also allows for more custom predicate assertions.
The predicates defined by `RouteDefinitionLocator` beans are combined using logical `and`.
@ -8,7 +8,6 @@ To enable the Spring Cloud CircuitBreaker filter, you need to place `spring-clou
@@ -8,7 +8,6 @@ To enable the Spring Cloud CircuitBreaker filter, you need to place `spring-clou
The following example configures a Spring Cloud CircuitBreaker `GatewayFilter`:
To configure the circuit breaker, see the configuration for the underlying circuit breaker implementation you are using.
@ -32,7 +30,6 @@ If the fallback is called, the request is forwarded to the controller matched by
@@ -32,7 +30,6 @@ If the fallback is called, the request is forwarded to the controller matched by
The following listing does the same thing in Java:
.Application.java
====
[source,java]
----
@Bean
@ -67,7 +62,6 @@ public RouteLocator routes(RouteLocatorBuilder builder) {
@@ -67,7 +62,6 @@ public RouteLocator routes(RouteLocatorBuilder builder) {
.build();
}
----
====
This example forwards to the `/inCaseofFailureUseThis` URI when the circuit breaker fallback is called.
Note that this example also demonstrates the (optional) Spring Cloud LoadBalancer load-balancing (defined by the `lb` prefix on the destination URI).
@ -78,7 +72,6 @@ This allows more complex routing options, like forwarding sections of the origin
@@ -78,7 +72,6 @@ This allows more complex routing options, like forwarding sections of the origin
In the example below the call `consumingServiceEndpoint/users/1` will be redirected to `inCaseOfFailureUseThis/users/1`.
In this example, there is no `fallback` endpoint or handler in the gateway application.
However, there is one in another application, registered under `http://localhost:9994`.
@ -143,7 +133,6 @@ status codes you want to trip the circuit breaker you can either use an integer
@@ -143,7 +133,6 @@ status codes you want to trip the circuit breaker you can either use an integer
value or the String representation of the `HttpStatus` enumeration.
The `FallbackHeaders` factory lets you add Spring Cloud CircuitBreaker execution exception details in the headers of a request forwarded to a `fallbackUri` in an external application, as in the following scenario:
In this example, after an execution exception occurs while running the circuit breaker, the request is forwarded to the `fallback` endpoint or handler in an application running on `localhost:9994`.
The headers with the exception type, message and (if available) root cause exception type and message are added to that request by the `FallbackHeaders` filter.
@ -14,7 +14,6 @@ It accepts the first parameter to override the time to expire a cache entry (exp
@@ -14,7 +14,6 @@ It accepts the first parameter to override the time to expire a cache entry (exp
The following listing shows how to add local response cache `GatewayFilter`:
NOTE: This filter also automatically calculates the `max-age` value in the HTTP `Cache-Control` header.
Only if `max-age` is present on the original response is the value rewritten with the number of seconds set in the `timeToLive` configuration parameter.
@ -7,7 +7,6 @@ It provides a convenient method to apply a transformation to JSON body content b
@@ -7,7 +7,6 @@ It provides a convenient method to apply a transformation to JSON body content b
The following example configures an `RemoveJsonAttributesResponseBody` `GatewayFilter`:
@ -5,7 +5,6 @@ The `AddRequestHeader` `GatewayFilter` factory takes a `name` and `value` parame
@@ -5,7 +5,6 @@ The `AddRequestHeader` `GatewayFilter` factory takes a `name` and `value` parame
The following example configures an `AddRequestHeader` `GatewayFilter`:
This listing adds `X-Request-red:blue` header to the downstream request's headers for all matching requests.
@ -26,7 +24,6 @@ URI variables may be used in the value and are expanded at runtime.
@@ -26,7 +24,6 @@ URI variables may be used in the value and are expanded at runtime.
The following example configures an `AddRequestHeader` `GatewayFilter` that uses a variable:
@ -5,7 +5,6 @@ The `AddRequestHeadersIfNotPresent` `GatewayFilter` factory takes a collection o
@@ -5,7 +5,6 @@ The `AddRequestHeadersIfNotPresent` `GatewayFilter` factory takes a collection o
The following example configures an `AddRequestHeadersIfNotPresent` `GatewayFilter`:
This listing adds 2 headers `X-Request-Color-1:blue` and `X-Request-Color-2:green` to the downstream request's headers for all matching requests.
This is similar to how `AddRequestHeader` works, but unlike `AddRequestHeader` it will do it only if the header is not already there.
@ -30,7 +28,6 @@ URI variables may be used in the value and are expanded at runtime.
@@ -30,7 +28,6 @@ URI variables may be used in the value and are expanded at runtime.
The following example configures an `AddRequestHeadersIfNotPresent` `GatewayFilter` that uses a variable:
@ -5,7 +5,6 @@ The `AddRequestParameter` `GatewayFilter` Factory takes a `name` and `value` par
@@ -5,7 +5,6 @@ The `AddRequestParameter` `GatewayFilter` Factory takes a `name` and `value` par
The following example configures an `AddRequestParameter` `GatewayFilter`:
This will add `red=blue` to the downstream request's query string for all matching requests.
@ -26,7 +24,6 @@ URI variables may be used in the value and are expanded at runtime.
@@ -26,7 +24,6 @@ URI variables may be used in the value and are expanded at runtime.
The following example configures an `AddRequestParameter` `GatewayFilter` that uses a variable:
@ -5,7 +5,6 @@ The `AddResponseHeader` `GatewayFilter` Factory takes a `name` and `value` param
@@ -5,7 +5,6 @@ The `AddResponseHeader` `GatewayFilter` Factory takes a `name` and `value` param
The following example configures an `AddResponseHeader` `GatewayFilter`:
This adds `X-Response-Red:Blue` header to the downstream response's headers for all matching requests.
@ -26,7 +24,6 @@ URI variables may be used in the value and are expanded at runtime.
@@ -26,7 +24,6 @@ URI variables may be used in the value and are expanded at runtime.
The following example configures an `AddResponseHeader` `GatewayFilter` that uses a variable:
@ -6,7 +6,6 @@ You can use the `CacheRequestBody` filter to cache the request body before sendi
@@ -6,7 +6,6 @@ You can use the `CacheRequestBody` filter to cache the request body before sendi
The following listing shows how to cache the request body `GatewayFilter`:
====
[source,java]
----
@Bean
@ -18,11 +17,9 @@ public RouteLocator routes(RouteLocatorBuilder builder) {
@@ -18,11 +17,9 @@ public RouteLocator routes(RouteLocatorBuilder builder) {
`CacheRequestBody` extracts the request body and converts it to a body class (such as `java.lang.String`, defined in the preceding example).
`CacheRequestBody` then places it in the attributes available from `ServerWebExchange.getAttributes()`, with a key defined in `ServerWebExchangeUtils.CACHED_REQUEST_BODY_ATTR`.
@ -5,7 +5,6 @@ The `DedupeResponseHeader` GatewayFilter factory takes a `name` parameter and an
@@ -5,7 +5,6 @@ The `DedupeResponseHeader` GatewayFilter factory takes a `name` parameter and an
The following example configures a `DedupeResponseHeader` `GatewayFilter`:
This removes duplicate values of `Access-Control-Allow-Credentials` and `Access-Control-Allow-Origin` response headers in cases when both the gateway CORS logic and the downstream logic add them.
@ -8,7 +8,6 @@ If the new named header already exists, its values are augmented with the new va
@@ -8,7 +8,6 @@ If the new named header already exists, its values are augmented with the new va
The following example configures a `MapRequestHeader`:
@ -7,7 +7,6 @@ NOTE: This filter can be configured only by using the Java DSL.
@@ -7,7 +7,6 @@ NOTE: This filter can be configured only by using the Java DSL.
The following listing shows how to modify a request body `GatewayFilter`:
====
[source,java]
----
@Bean
@ -41,6 +40,5 @@ static class Hello {
@@ -41,6 +40,5 @@ static class Hello {
NOTE: If the request has no body, the `RewriteFilter` is passed `null`. `Mono.empty()` should be returned to assign a missing body in the request.
@ -7,7 +7,6 @@ NOTE: This filter can be configured only by using the Java DSL.
@@ -7,7 +7,6 @@ NOTE: This filter can be configured only by using the Java DSL.
The following listing shows how to modify a response body `GatewayFilter`:
====
[source,java]
----
@Bean
@ -22,5 +21,4 @@ public RouteLocator routes(RouteLocatorBuilder builder) {
@@ -22,5 +21,4 @@ public RouteLocator routes(RouteLocatorBuilder builder) {
----
NOTE: If the response has no body, the `RewriteFilter` is passed `null`. `Mono.empty()` should be returned to assign a missing body in the response.
@ -6,7 +6,6 @@ The `PrefixPath` `GatewayFilter` factory takes a single `prefix` parameter.
@@ -6,7 +6,6 @@ The `PrefixPath` `GatewayFilter` factory takes a single `prefix` parameter.
The following example configures a `PrefixPath` `GatewayFilter`:
@ -7,7 +7,6 @@ This filter sets a request attribute that the routing filter inspects to determi
@@ -7,7 +7,6 @@ This filter sets a request attribute that the routing filter inspects to determi
The following example configures a `PreserveHostHeader` `GatewayFilter`:
@ -9,7 +9,6 @@ For relative redirects, you should use `uri: no://op` as the uri of your route d
@@ -9,7 +9,6 @@ For relative redirects, you should use `uri: no://op` as the uri of your route d
The following listing configures a `RedirectTo` `GatewayFilter`:
@ -7,7 +7,6 @@ The `maxSize` parameter is the maximum data size allowed by the request header (
@@ -7,7 +7,6 @@ The `maxSize` parameter is the maximum data size allowed by the request header (
The following listing configures a `RequestHeaderSize` `GatewayFilter`:
@ -11,14 +11,12 @@ In configuration, reference the bean by name using SpEL.
@@ -11,14 +11,12 @@ In configuration, reference the bean by name using SpEL.
The following listing shows the `KeyResolver` interface:
.KeyResolver.java
====
[source,java]
----
public interface KeyResolver {
Mono<String> resolve(ServerWebExchange exchange);
}
----
====
[[key-resolver-section]]
The `KeyResolver` interface lets pluggable strategies derive the key for limiting requests.
@ -34,12 +32,10 @@ You can adjust this behavior by setting the `spring.cloud.gateway.filter.request
@@ -34,12 +32,10 @@ You can adjust this behavior by setting the `spring.cloud.gateway.filter.request
The `RequestRateLimiter` is not configurable with the "shortcut" notation. The following example below is _invalid_:
@ -68,7 +64,6 @@ The following listing configures a `redis-rate-limiter`:
@@ -68,7 +64,6 @@ The following listing configures a `redis-rate-limiter`:
Rate limits below `1 request/s` are accomplished by setting `replenishRate` to the wanted number of requests, `requestedTokens` to the timespan in seconds, and `burstCapacity` to the product of `replenishRate` and `requestedTokens`.
For example, setting `replenishRate=1`, `requestedTokens=60`, and `burstCapacity=60` results in a limit of `1 request/min`.
This defines a request rate limit of 10 per user. A burst of 20 is allowed, but, in the next second, only 10 requests are available.
The `KeyResolver` is a simple one that gets the `user` request parameter
@ -110,7 +102,6 @@ In configuration, you can reference the bean by name using SpEL.
@@ -110,7 +102,6 @@ In configuration, you can reference the bean by name using SpEL.
The following listing defines a rate limiter that uses the `KeyResolver` defined in the previous listing:
@ -8,7 +8,6 @@ It is the permissible size limit of the request defined in bytes.
@@ -8,7 +8,6 @@ It is the permissible size limit of the request defined in bytes.
The following listing configures a `RequestSize` `GatewayFilter`:
The `RequestSize` `GatewayFilter` factory sets the response status as `413 Payload Too Large` with an additional header `errorMessage` when the request is rejected due to size. The following example shows such an `errorMessage`:
====
[source]
----
errorMessage : Request size is larger than permissible limit. Request size is 6.0 MB where permissible limit is 5.0 MB
----
====
NOTE: The default request size is set to five MB if not provided as a filter argument in the route definition.
@ -24,7 +24,6 @@ The following defaults are configured for `Retry` filter, if enabled:
@@ -24,7 +24,6 @@ The following defaults are configured for `Retry` filter, if enabled:
The following listing configures a Retry `GatewayFilter`:
NOTE: When using the retry filter with a `forward:` 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 `ResponseEntity` with an error status code.
@ -60,7 +58,6 @@ A simplified "shortcut" notation can be added with a single `status` and `method
@@ -60,7 +58,6 @@ A simplified "shortcut" notation can be added with a single `status` and `method
@ -6,7 +6,6 @@ It takes the `stripVersionMode`, `locationHeaderName`, `hostValue`, and `protoco
@@ -6,7 +6,6 @@ It takes the `stripVersionMode`, `locationHeaderName`, `hostValue`, and `protoco
The following listing configures a `RewriteLocationResponseHeader` `GatewayFilter`:
For example, for a request of `POST https://api.example.com/some/object/name`, the `Location` response header value of `https://object-service.prod.example.net/v2/some/object/id` is rewritten as `https://api.example.com/some/object/id`.
@ -6,7 +6,6 @@ This uses Java regular expressions for a flexible way to rewrite the request pat
@@ -6,7 +6,6 @@ This uses Java regular expressions for a flexible way to rewrite the request pat
The following listing configures a `RewritePath` `GatewayFilter`:
For a request path of `/red/blue`, this sets the path to `/blue` before making the downstream request. Note that the `$` should be replaced with `$\` because of the YAML specification.
@ -7,7 +7,6 @@ It uses Java regular expressions for a flexible way to rewrite the response head
@@ -7,7 +7,6 @@ It uses Java regular expressions for a flexible way to rewrite the response head
The following example configures a `RewriteResponseHeader` `GatewayFilter`:
For a header value of `/42?user=ford&password=omg!what&flag=true`, it is set to `/42?user=ford&password=\***&flag=true` after making the downstream request.
You must use `$\` to mean `$` because of the YAML specification.
@ -6,7 +6,6 @@ This is of particular use when using something like https://projects.spring.io/s
@@ -6,7 +6,6 @@ This is of particular use when using something like https://projects.spring.io/s
The following example configures a `SaveSession` `GatewayFilter`:
If you integrate https://projects.spring.io/spring-security/[Spring Security] with Spring Session and want to ensure security details have been forwarded to the remote process, this is critical.
This `GatewayFilter` replaces (rather than adding) all headers with the given name.
So, if the downstream server responded with `X-Request-Red:1234`, it will be replaced with `X-Request-Red:Blue`, which is what the downstream service would receive.
@ -27,7 +25,6 @@ URI variables may be used in the value and are expanded at runtime.
@@ -27,7 +25,6 @@ URI variables may be used in the value and are expanded at runtime.
The following example configures an `SetRequestHeader` `GatewayFilter` that uses a variable:
This GatewayFilter replaces (rather than adding) all headers with the given name.
So, if the downstream server responded with `X-Response-Red:1234`, it will be replaced with `X-Response-Red:Blue`, which is what the gateway client would receive.
@ -27,7 +25,6 @@ URI variables may be used in the value and will be expanded at runtime.
@@ -27,7 +25,6 @@ URI variables may be used in the value and will be expanded at runtime.
The following example configures an `SetResponseHeader` `GatewayFilter` that uses a variable:
@ -7,7 +7,6 @@ It may be the integer value `404` or the string representation of the enumeratio
@@ -7,7 +7,6 @@ It may be the integer value `404` or the string representation of the enumeratio
The following listing configures a `SetStatus` `GatewayFilter`:
In either case, the HTTP status of the response is set to 401.
@ -31,7 +29,6 @@ You can configure the `SetStatus` `GatewayFilter` to return the original HTTP st
@@ -31,7 +29,6 @@ You can configure the `SetStatus` `GatewayFilter` to return the original HTTP st
The header is added to the response if configured with the following property:
@ -6,7 +6,6 @@ The `parts` parameter indicates the number of parts in the path to strip from th
@@ -6,7 +6,6 @@ The `parts` parameter indicates the number of parts in the path to strip from th
The following listing configures a `StripPrefix` `GatewayFilter`:
@ -17,7 +17,6 @@ As Spring Cloud Gateway distinguishes between "`pre`" and "`post`" phases for fi
@@ -17,7 +17,6 @@ As Spring Cloud Gateway distinguishes between "`pre`" and "`post`" phases for fi
The following listing configures a filter chain:
.ExampleConfiguration.java
====
[source,java]
----
@Bean
@ -39,7 +38,6 @@ public class CustomGlobalFilter implements GlobalFilter, Ordered {
@@ -39,7 +38,6 @@ public class CustomGlobalFilter implements GlobalFilter, Ordered {
}
}
----
====
[[the-gateway-metrics-filter]]
== The Gateway Metrics Filter
@ -127,7 +125,6 @@ If so, the same rules apply.
@@ -127,7 +125,6 @@ If so, the same rules apply.
The following listing configures a `ReactiveLoadBalancerClientFilter`:
NOTE: By default, when a service instance cannot be found by the `ReactorLoadBalancer`, a `503` is returned.
You can configure the gateway to return a `404` by setting `spring.cloud.gateway.loadbalancer.use404=true`.
@ -173,7 +169,6 @@ NOTE: If you use https://github.com/sockjs[SockJS] as a fallback over normal HTT
@@ -173,7 +169,6 @@ NOTE: If you use https://github.com/sockjs[SockJS] as a fallback over normal HTT
The following listing configures a websocket routing filter:
@ -8,7 +8,6 @@ IMPORTANT: It must be a Java System Property, not a Spring Boot property.
@@ -8,7 +8,6 @@ IMPORTANT: It must be a Java System Property, not a Spring Boot property.
You can configure the logging system to have a separate access log file. The following example creates a Logback configuration:
@ -25,5 +24,4 @@ You can configure the logging system to have a separate access log file. The fol
@@ -25,5 +24,4 @@ You can configure the logging system to have a separate access log file. The fol
@ -14,7 +14,6 @@ This predicate matches requests that happen after the specified datetime.
@@ -14,7 +14,6 @@ This predicate matches requests that happen after the specified datetime.
The following example configures an after route predicate:
This route matches any request made after Jan 20, 2017 17:42 Mountain Time (Denver).
@ -38,7 +36,6 @@ This predicate matches requests that happen before the specified `datetime`.
@@ -38,7 +36,6 @@ This predicate matches requests that happen before the specified `datetime`.
The following example configures a before route predicate:
This route matches any request made 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.
@ -89,7 +83,6 @@ This predicate matches cookies that have the given name and whose values match t
@@ -89,7 +83,6 @@ This predicate matches cookies that have the given name and whose values match t
The following example configures a cookie route predicate factory:
This route matches requests that have a cookie named `chocolate` whose value matches the `ch.p` regular expression.
@ -113,7 +105,6 @@ This predicate matches with a header that has the given name whose value matches
@@ -113,7 +105,6 @@ This predicate matches with a header that has the given name whose value matches
The following example configures a header route predicate:
This route matches if the request has a header named `X-Request-Id` whose value matches the `\d+` regular expression (that is, it has a value of one or more digits).
@ -138,7 +128,6 @@ This predicates matches the `Host` header that matches the pattern.
@@ -138,7 +128,6 @@ This predicates matches the `Host` header that matches the pattern.
The following example configures a host route predicate:
URI template variables (such as `{sub}.myhost.org`) are supported as well.
URI template variables (such as `\{sub}.myhost.org`) are supported as well.
This route matches if the request has a `Host` header with a value of `www.somehost.org` or `beta.somehost.org` or `www.anotherhost.org`.
@ -167,7 +155,6 @@ The `Method` Route Predicate Factory takes a `methods` argument which is one or
@@ -167,7 +155,6 @@ The `Method` Route Predicate Factory takes a `methods` argument which is one or
The following example configures a method route predicate:
This route matches if the request method was a `GET` or a `POST`.
@ -190,7 +176,6 @@ The `Path` Route Predicate Factory takes two parameters: a list of Spring `PathM
@@ -190,7 +176,6 @@ The `Path` Route Predicate Factory takes two parameters: a list of Spring `PathM
The following example configures a path route predicate:
This route matches if the request path was, for example: `/red/1` or `/red/1/` or `/red/blue` or `/blue/green`.
@ -214,14 +198,12 @@ Those values are then available for use by <<gateway-route-filters,`GatewayFilte
@@ -214,14 +198,12 @@ Those values are then available for use by <<gateway-route-filters,`GatewayFilte
A utility method (called `get`) is available to make access to these variables easier.
The following example shows how to use the `get` method:
@ -230,7 +212,6 @@ The `Query` route predicate factory takes two parameters: a required `param` and
@@ -230,7 +212,6 @@ The `Query` route predicate factory takes two parameters: a required `param` and
The following example configures a query route predicate:
The preceding route matches if the request contained a `green` query parameter.
@ -269,7 +249,6 @@ The `RemoteAddr` route predicate factory takes a list (min size 1) of `sources`,
@@ -269,7 +249,6 @@ The `RemoteAddr` route predicate factory takes a list (min size 1) of `sources`,
The following example configures a RemoteAddr route predicate:
This route matches if the remote address of the request was, for example, `192.168.1.10`.
@ -305,12 +283,10 @@ If two hops of trusted infrastructure are required before Spring Cloud Gateway i
@@ -305,12 +283,10 @@ If two hops of trusted infrastructure are required before Spring Cloud Gateway i
Consider the following header value:
====
[source]
----
X-Forwarded-For: 0.0.0.1, 0.0.0.2, 0.0.0.3
----
====
The following `maxTrustedIndex` values yield the following remote addresses:
@ -323,12 +299,11 @@ The following `maxTrustedIndex` values yield the following remote addresses:
@@ -323,12 +299,11 @@ The following `maxTrustedIndex` values yield the following remote addresses:
|3 | 0.0.0.1
|[4, `Integer.MAX_VALUE`] | 0.0.0.1
|===
[[gateway-route-filters]]
[[gateway-route-filters]]
The following example shows how to achieve the same configuration with Java:
@ -13,7 +13,7 @@ By default, the gateway defines a single predicate and filter for routes created
@@ -13,7 +13,7 @@ By default, the gateway defines a single predicate and filter for routes created
The default predicate is a path predicate defined with the pattern `/serviceId/**`, where `serviceId` is
the ID of the service from the `DiscoveryClient`.
The default filter is a rewrite path filter with the regex `/serviceId/?(?<remaining>.*)` and the replacement `/${remaining}`.
The default filter is a rewrite path filter with the regex `/serviceId/?(?<remaining>.*)` and the replacement `/$\{remaining}`.
This strips the service ID from the path before the request is sent downstream.
If you want to customize the predicates or filters used by the `DiscoveryClient` routes, set `spring.cloud.gateway.discovery.locator.predicates[x]` and `spring.cloud.gateway.discovery.locator.filters[y]`.
@ -21,7 +21,6 @@ When doing so, you need to make sure to include the default predicate and filter
@@ -21,7 +21,6 @@ When doing so, you need to make sure to include the default predicate and filter
@ -5,7 +5,6 @@ The gateway can listen for requests on HTTPS by following the usual Spring serve
@@ -5,7 +5,6 @@ The gateway can listen for requests on HTTPS by following the usual Spring serve
If the Spring Cloud Gateway is not provisioned with trusted certificates, the default trust store is used (which you can override by setting the `javax.net.ssl.trustStore` system property).
@ -63,7 +57,6 @@ A number of timeouts are associated with this handshake.
@@ -63,7 +57,6 @@ A number of timeouts are associated with this handshake.
You can configure these timeouts can be configured (defaults shown) as follows:
sgibb
1 year ago