From c99bf85eab97c10bb66726f3d5b4e1149eccd574 Mon Sep 17 00:00:00 2001 From: buildmaster Date: Wed, 11 Dec 2019 16:36:43 +0000 Subject: [PATCH] Sync docs from master to gh-pages --- reference/html/index.html | 174 ++++++++++++++++------- reference/html/spring-cloud-gateway.html | 174 ++++++++++++++++------- 2 files changed, 246 insertions(+), 102 deletions(-) diff --git a/reference/html/index.html b/reference/html/index.html index 95aad5d1..7d76c6df 100644 --- a/reference/html/index.html +++ b/reference/html/index.html @@ -177,50 +177,53 @@ $(addBlockSwitches);
  • 8. Configuration
    • -
  • 9. Route metadata configuration +
  • 9. Route metadata configuration
    • +
  • 10. Http timeouts configuration
    • -
  • 10. Reactor Netty Access Logs
    • -
  • 11. CORS Configuration
    • -
  • 12. Actuator API +
  • 11. Reactor Netty Access Logs
    • +
  • 12. CORS Configuration
    • +
  • 13. Actuator API
    • -
  • 13. Troubleshooting +
  • 14. Troubleshooting
    • -
  • 14. Developer Guide +
  • 15. Developer Guide
    • -
  • 15. Building a Simple Gateway Using Spring MVC or Webflux
    • -
  • 16. Configuration properties
    • +
  • 16. Building a Simple Gateway Using Spring MVC or Webflux
    • +
  • 17. Configuration properties
    • @@ -2492,8 +2495,77 @@ route.getMetadata(); route.getMetadata(someKey); + + +
    +

    10. Http timeouts configuration

    +
    +
    +

    Http timeouts (response and connect) can be configured for all routes and overridden for each specific route.

    +
    -

    9.1. Fluent Java Routes API

    +

    10.1. Global timeouts

    +
    +

    To configure Global http timeouts:
    +connect-timeout must be specified in milliseconds.
    +response-timeout must be specified as a java.time.Duration

    +
    +
    +
    global http timeouts example
    +
    +
    spring:
+  cloud:
+    gateway:
+      httpclient:
+        connect-timeout: 1000
+        response-timeout: 5s
    +
    +
    +
    +
    +

    10.2. Per-route timeouts

    +
    +

    To configure per-route timeouts:
    +connect-timeout must be specified in milliseconds.
    +response-timeout must be specified in milliseconds.

    +
    +
    +
    per-route http timeouts configuration via configuration
    +
    +
          - id: per_route_timeouts
+        uri: https://example.org
+        predicates:
+          - name: Path
+            args:
+              pattern: /delay/{timeout}
+        metadata:
+          response-timeout: 200
+          connect-timeout: 200
    +
    +
    +
    +
    per-route timeouts configuration using Java DSL
    +
    +
    import static org.springframework.cloud.gateway.support.RouteMetadataUtils.CONNECT_TIMEOUT_ATTR;
+import static org.springframework.cloud.gateway.support.RouteMetadataUtils.RESPONSE_TIMEOUT_ATTR;
+
+      @Bean
+      public RouteLocator customRouteLocator(RouteLocatorBuilder routeBuilder){
+         return routeBuilder.routes()
+               .route("test1", r -> {
+                  return r.host("*.somehost.org").and().path("/somepath")
+                        .filters(f -> f.addRequestHeader("header1", "header-value-1"))
+                        .uri("http://someuri")
+                        .metadata(RESPONSE_TIMEOUT_ATTR, 200)
+                        .metadata(CONNECT_TIMEOUT_ATTR, 200);
+               })
+               .build();
+      }
    +
    +
    +
    +
    +

    10.3. Fluent Java Routes API

    To allow for simple configuration in Java, there is a fluent API defined in the RouteLocatorBuilder bean.

    @@ -2533,7 +2605,7 @@ public RouteLocator customRouteLocator(RouteLocatorBuilder builder, ThrottleGate
    -

    9.2. DiscoveryClient Route Definition Locator

    +

    10.4. DiscoveryClient Route Definition Locator

    The Gateway can be configured to create routes based on services registered with a DiscoveryClient compatible service registry.

    @@ -2541,7 +2613,7 @@ public RouteLocator customRouteLocator(RouteLocatorBuilder builder, ThrottleGate

    To enable this, set spring.cloud.gateway.discovery.locator.enabled=true and make sure a DiscoveryClient implementation is on the classpath and enabled (such as Netflix Eureka, Consul or Zookeeper).

    -

    9.2.1. Configuring Predicates and Filters For DiscoveryClient Routes

    +

    10.4.1. Configuring Predicates and Filters For DiscoveryClient Routes

    By default the Gateway defines a single predicate and filter for routes created via a DiscoveryClient.

    @@ -2579,7 +2651,7 @@ spring.cloud.gateway.discovery.locator.filters[1].args[replacement]: "'/${remain
    -

    10. Reactor Netty Access Logs

    +

    11. Reactor Netty Access Logs

    To enable Reactor Netty access logs, set -Dreactor.netty.http.server.accessLogEnabled=true. (It must be a Java System Property, not a Spring Boot property).

    @@ -2608,7 +2680,7 @@ spring.cloud.gateway.discovery.locator.filters[1].args[replacement]: "'/${remain
    -

    11. CORS Configuration

    +

    12. CORS Configuration

    The gateway can be configured to control CORS behavior. The "global" CORS configuration is a map of URL patterns to Spring Framework CorsConfiguration.

    @@ -2636,7 +2708,7 @@ spring.cloud.gateway.discovery.locator.filters[1].args[replacement]: "'/${remain
    -

    12. Actuator API

    +

    13. Actuator API

    The /gateway actuator endpoint allows to monitor and interact with a Spring Cloud Gateway application. To be remotely accessible, the endpoint has to be enabled and exposed via HTTP or JMX in the application properties.

    @@ -2649,7 +2721,7 @@ management.endpoints.web.exposure.include=gateway
    -

    12.1. Verbose Actuator Format

    +

    13.1. Verbose Actuator Format

    A new, more verbose format has been added to Gateway. This adds more detail to each route allowing to view the predicates and filters associated to each route along with any configuration that is available.

    @@ -2687,9 +2759,9 @@ management.endpoints.web.exposure.include=gateway
    -

    12.2. Retrieving route filters

    +

    13.2. Retrieving route filters

    -

    12.2.1. Global Filters

    +

    13.2.1. Global Filters

    To retrieve the global filters applied to all routes, make a GET request to /actuator/gateway/globalfilters. The resulting response is similar to the following:

    @@ -2712,7 +2784,7 @@ management.endpoints.web.exposure.include=gateway
    -

    12.2.2. Route Filters

    +

    13.2.2. Route Filters

    To retrieve the GatewayFilter factories applied to routes, make a GET request to /actuator/gateway/routefilters. The resulting response is similar to the following:

    @@ -2731,13 +2803,13 @@ management.endpoints.web.exposure.include=gateway
    -

    12.3. Refreshing the route cache

    +

    13.3. Refreshing the route cache

    To clear the routes cache, make a POST request to /actuator/gateway/refresh. The request returns a 200 without response body.

    -

    12.4. Retrieving the routes defined in the gateway

    +

    13.4. Retrieving the routes defined in the gateway

    To retrieve the routes defined in the gateway, make a GET request to /actuator/gateway/routes. The resulting response is similar to the following:

    @@ -2804,7 +2876,7 @@ management.endpoints.web.exposure.include=gateway
    -

    12.5. Retrieving information about a particular route

    +

    13.5. Retrieving information about a particular route

    To retrieve information about a single route, make a GET request to /actuator/gateway/routes/{id} (e.g., /actuator/gateway/routes/first_route). The resulting response is similar to the following:

    @@ -2868,7 +2940,7 @@ management.endpoints.web.exposure.include=gateway
    -

    12.6. Creating and deleting a particular route

    +

    13.6. Creating and deleting a particular route

    To create a route, make a POST request to /gateway/routes/{id_route_to_create} with a JSON body that specifies the fields of the route (see the previous subsection).

    @@ -2877,7 +2949,7 @@ management.endpoints.web.exposure.include=gateway
    -

    12.7. Recap: list of all endpoints

    +

    13.7. Recap: list of all endpoints

    The table below summarises the Spring Cloud Gateway actuator endpoints. Note that each endpoint has /actuator/gateway as the base-path.

    @@ -2936,10 +3008,10 @@ management.endpoints.web.exposure.include=gateway
    -

    13. Troubleshooting

    +

    14. Troubleshooting

    -

    13.1. Log Levels

    +

    14.1. Log Levels

    Below are some useful loggers that contain valuable trouble shooting infomration at the DEBUG and TRACE levels.

    @@ -2967,7 +3039,7 @@ management.endpoints.web.exposure.include=gateway
    -

    13.2. Wiretap

    +

    14.2. Wiretap

    The Reactor Netty HttpClient and HttpServer can have wiretap enabled. When combined with setting the reactor.netty log level to DEBUG or TRACE will enable logging of @@ -2980,19 +3052,19 @@ respectively.

    -

    14. Developer Guide

    +

    15. Developer Guide

    TODO: overview of writing custom integrations

    -

    14.1. Writing Custom Route Predicate Factories

    +

    15.1. Writing Custom Route Predicate Factories

    TODO: document writing Custom Route Predicate Factories

    -

    14.2. Writing Custom GatewayFilter Factories

    +

    15.2. Writing Custom GatewayFilter Factories

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

    @@ -3053,7 +3125,7 @@ respectively.

    -

    14.3. Writing Custom Global Filters

    +

    15.3. Writing Custom Global Filters

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

    @@ -3091,7 +3163,7 @@ public GlobalFilter customGlobalPostFilter() {
    -

    14.4. Writing Custom Route Locators and Writers

    +

    15.4. Writing Custom Route Locators and Writers

    TODO: document writing Custom Route Locators and Writers

    @@ -3099,7 +3171,7 @@ public GlobalFilter customGlobalPostFilter() {
    -

    15. Building a Simple Gateway Using Spring MVC or Webflux

    +

    16. Building a Simple Gateway Using Spring MVC or Webflux

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

    @@ -3171,7 +3243,7 @@ public ResponseEntity<?> proxyPath(ProxyExchange<byte[]> proxy) thro
    -

    16. Configuration properties

    +

    17. Configuration properties

    To see the list of all Spring Cloud Gateway related configuration properties please check the Appendix page.

    diff --git a/reference/html/spring-cloud-gateway.html b/reference/html/spring-cloud-gateway.html index 95aad5d1..7d76c6df 100644 --- a/reference/html/spring-cloud-gateway.html +++ b/reference/html/spring-cloud-gateway.html @@ -177,50 +177,53 @@ $(addBlockSwitches);
  • 8. Configuration
    • -
  • 9. Route metadata configuration +
  • 9. Route metadata configuration
    • +
  • 10. Http timeouts configuration
    • -
  • 10. Reactor Netty Access Logs
    • -
  • 11. CORS Configuration
    • -
  • 12. Actuator API +
  • 11. Reactor Netty Access Logs
    • +
  • 12. CORS Configuration
    • +
  • 13. Actuator API
    • -
  • 13. Troubleshooting +
  • 14. Troubleshooting
    • -
  • 14. Developer Guide +
  • 15. Developer Guide
    • -
  • 15. Building a Simple Gateway Using Spring MVC or Webflux
    • -
  • 16. Configuration properties
    • +
  • 16. Building a Simple Gateway Using Spring MVC or Webflux
    • +
  • 17. Configuration properties
    • @@ -2492,8 +2495,77 @@ route.getMetadata(); route.getMetadata(someKey);
    + + +
    +

    10. Http timeouts configuration

    +
    +
    +

    Http timeouts (response and connect) can be configured for all routes and overridden for each specific route.

    +
    -

    9.1. Fluent Java Routes API

    +

    10.1. Global timeouts

    +
    +

    To configure Global http timeouts:
    +connect-timeout must be specified in milliseconds.
    +response-timeout must be specified as a java.time.Duration

    +
    +
    +
    global http timeouts example
    +
    +
    spring:
+  cloud:
+    gateway:
+      httpclient:
+        connect-timeout: 1000
+        response-timeout: 5s
    +
    +
    +
    +
    +

    10.2. Per-route timeouts

    +
    +

    To configure per-route timeouts:
    +connect-timeout must be specified in milliseconds.
    +response-timeout must be specified in milliseconds.

    +
    +
    +
    per-route http timeouts configuration via configuration
    +
    +
          - id: per_route_timeouts
+        uri: https://example.org
+        predicates:
+          - name: Path
+            args:
+              pattern: /delay/{timeout}
+        metadata:
+          response-timeout: 200
+          connect-timeout: 200
    +
    +
    +
    +
    per-route timeouts configuration using Java DSL
    +
    +
    import static org.springframework.cloud.gateway.support.RouteMetadataUtils.CONNECT_TIMEOUT_ATTR;
+import static org.springframework.cloud.gateway.support.RouteMetadataUtils.RESPONSE_TIMEOUT_ATTR;
+
+      @Bean
+      public RouteLocator customRouteLocator(RouteLocatorBuilder routeBuilder){
+         return routeBuilder.routes()
+               .route("test1", r -> {
+                  return r.host("*.somehost.org").and().path("/somepath")
+                        .filters(f -> f.addRequestHeader("header1", "header-value-1"))
+                        .uri("http://someuri")
+                        .metadata(RESPONSE_TIMEOUT_ATTR, 200)
+                        .metadata(CONNECT_TIMEOUT_ATTR, 200);
+               })
+               .build();
+      }
    +
    +
    +
    +
    +

    10.3. Fluent Java Routes API

    To allow for simple configuration in Java, there is a fluent API defined in the RouteLocatorBuilder bean.

    @@ -2533,7 +2605,7 @@ public RouteLocator customRouteLocator(RouteLocatorBuilder builder, ThrottleGate
    -

    9.2. DiscoveryClient Route Definition Locator

    +

    10.4. DiscoveryClient Route Definition Locator

    The Gateway can be configured to create routes based on services registered with a DiscoveryClient compatible service registry.

    @@ -2541,7 +2613,7 @@ public RouteLocator customRouteLocator(RouteLocatorBuilder builder, ThrottleGate

    To enable this, set spring.cloud.gateway.discovery.locator.enabled=true and make sure a DiscoveryClient implementation is on the classpath and enabled (such as Netflix Eureka, Consul or Zookeeper).

    -

    9.2.1. Configuring Predicates and Filters For DiscoveryClient Routes

    +

    10.4.1. Configuring Predicates and Filters For DiscoveryClient Routes

    By default the Gateway defines a single predicate and filter for routes created via a DiscoveryClient.

    @@ -2579,7 +2651,7 @@ spring.cloud.gateway.discovery.locator.filters[1].args[replacement]: "'/${remain
    -

    10. Reactor Netty Access Logs

    +

    11. Reactor Netty Access Logs

    To enable Reactor Netty access logs, set -Dreactor.netty.http.server.accessLogEnabled=true. (It must be a Java System Property, not a Spring Boot property).

    @@ -2608,7 +2680,7 @@ spring.cloud.gateway.discovery.locator.filters[1].args[replacement]: "'/${remain
    -

    11. CORS Configuration

    +

    12. CORS Configuration

    The gateway can be configured to control CORS behavior. The "global" CORS configuration is a map of URL patterns to Spring Framework CorsConfiguration.

    @@ -2636,7 +2708,7 @@ spring.cloud.gateway.discovery.locator.filters[1].args[replacement]: "'/${remain
    -

    12. Actuator API

    +

    13. Actuator API

    The /gateway actuator endpoint allows to monitor and interact with a Spring Cloud Gateway application. To be remotely accessible, the endpoint has to be enabled and exposed via HTTP or JMX in the application properties.

    @@ -2649,7 +2721,7 @@ management.endpoints.web.exposure.include=gateway
    -

    12.1. Verbose Actuator Format

    +

    13.1. Verbose Actuator Format

    A new, more verbose format has been added to Gateway. This adds more detail to each route allowing to view the predicates and filters associated to each route along with any configuration that is available.

    @@ -2687,9 +2759,9 @@ management.endpoints.web.exposure.include=gateway
    -

    12.2. Retrieving route filters

    +

    13.2. Retrieving route filters

    -

    12.2.1. Global Filters

    +

    13.2.1. Global Filters

    To retrieve the global filters applied to all routes, make a GET request to /actuator/gateway/globalfilters. The resulting response is similar to the following:

    @@ -2712,7 +2784,7 @@ management.endpoints.web.exposure.include=gateway
    -

    12.2.2. Route Filters

    +

    13.2.2. Route Filters

    To retrieve the GatewayFilter factories applied to routes, make a GET request to /actuator/gateway/routefilters. The resulting response is similar to the following:

    @@ -2731,13 +2803,13 @@ management.endpoints.web.exposure.include=gateway
    -

    12.3. Refreshing the route cache

    +

    13.3. Refreshing the route cache

    To clear the routes cache, make a POST request to /actuator/gateway/refresh. The request returns a 200 without response body.

    -

    12.4. Retrieving the routes defined in the gateway

    +

    13.4. Retrieving the routes defined in the gateway

    To retrieve the routes defined in the gateway, make a GET request to /actuator/gateway/routes. The resulting response is similar to the following:

    @@ -2804,7 +2876,7 @@ management.endpoints.web.exposure.include=gateway
    -

    12.5. Retrieving information about a particular route

    +

    13.5. Retrieving information about a particular route

    To retrieve information about a single route, make a GET request to /actuator/gateway/routes/{id} (e.g., /actuator/gateway/routes/first_route). The resulting response is similar to the following:

    @@ -2868,7 +2940,7 @@ management.endpoints.web.exposure.include=gateway
    -

    12.6. Creating and deleting a particular route

    +

    13.6. Creating and deleting a particular route

    To create a route, make a POST request to /gateway/routes/{id_route_to_create} with a JSON body that specifies the fields of the route (see the previous subsection).

    @@ -2877,7 +2949,7 @@ management.endpoints.web.exposure.include=gateway
    -

    12.7. Recap: list of all endpoints

    +

    13.7. Recap: list of all endpoints

    The table below summarises the Spring Cloud Gateway actuator endpoints. Note that each endpoint has /actuator/gateway as the base-path.

    @@ -2936,10 +3008,10 @@ management.endpoints.web.exposure.include=gateway
    -

    13. Troubleshooting

    +

    14. Troubleshooting

    -

    13.1. Log Levels

    +

    14.1. Log Levels

    Below are some useful loggers that contain valuable trouble shooting infomration at the DEBUG and TRACE levels.

    @@ -2967,7 +3039,7 @@ management.endpoints.web.exposure.include=gateway
    -

    13.2. Wiretap

    +

    14.2. Wiretap

    The Reactor Netty HttpClient and HttpServer can have wiretap enabled. When combined with setting the reactor.netty log level to DEBUG or TRACE will enable logging of @@ -2980,19 +3052,19 @@ respectively.

    -

    14. Developer Guide

    +

    15. Developer Guide

    TODO: overview of writing custom integrations

    -

    14.1. Writing Custom Route Predicate Factories

    +

    15.1. Writing Custom Route Predicate Factories

    TODO: document writing Custom Route Predicate Factories

    -

    14.2. Writing Custom GatewayFilter Factories

    +

    15.2. Writing Custom GatewayFilter Factories

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

    @@ -3053,7 +3125,7 @@ respectively.

    -

    14.3. Writing Custom Global Filters

    +

    15.3. Writing Custom Global Filters

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

    @@ -3091,7 +3163,7 @@ public GlobalFilter customGlobalPostFilter() {
    -

    14.4. Writing Custom Route Locators and Writers

    +

    15.4. Writing Custom Route Locators and Writers

    TODO: document writing Custom Route Locators and Writers

    @@ -3099,7 +3171,7 @@ public GlobalFilter customGlobalPostFilter() {
    -

    15. Building a Simple Gateway Using Spring MVC or Webflux

    +

    16. Building a Simple Gateway Using Spring MVC or Webflux

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

    @@ -3171,7 +3243,7 @@ public ResponseEntity<?> proxyPath(ProxyExchange<byte[]> proxy) thro
    -

    16. Configuration properties

    +

    17. Configuration properties

    To see the list of all Spring Cloud Gateway related configuration properties please check the Appendix page.