doc(docs.pages.webServer): add notes

spring-boot-project/spring-boot-docs/src/docs/antora/modules/how-to/pages/webserver.adoc

@@ -1,11 +1,10 @@
 [[howto.webserver]]
 = Embedded Web Servers
 
-Each Spring Boot web application includes an embedded web server.
-This feature leads to a number of how-to questions, including how to change the embedded server and how to configure the embedded server.
-This section answers those questions.
-
-
+* embedded web server / Spring Boot web application
+    ** typical "how-to" questions
+        *** how to change the embedded server
+        *** how to configure the embedded server
 
 [[howto.webserver.use-another]]
 == Use Another Web Server
@@ -58,7 +57,6 @@ dependencies {
 NOTE: `spring-boot-starter-reactor-netty` is required to use the `WebClient` class, so you may need to keep a dependency on Netty even when you need to include a different HTTP server.
 
 
-
 [[howto.webserver.disable]]
 == Disabling the Web Server
 
@@ -73,7 +71,6 @@ spring:
 ----
 
 
-
 [[howto.webserver.change-port]]
 == Change the HTTP Port
 
@@ -85,14 +82,12 @@ To switch off the HTTP endpoints completely but still create a `WebApplicationCo
 For more details, see xref:reference:web/servlet.adoc#web.servlet.embedded-container.customizing[Customizing Embedded Servlet Containers] in the '`Spring Boot Features`' section, or the xref:api:java/org/springframework/boot/autoconfigure/web/ServerProperties.html[`ServerProperties`] class.
 
 
-
 [[howto.webserver.use-random-port]]
 == Use a Random Unassigned HTTP Port
 
 To scan for a free port (using OS natives to prevent clashes) use `server.port=0`.
 
 
-
 [[howto.webserver.discover-port]]
 == Discover the HTTP Port at Runtime
 
@@ -112,7 +107,6 @@ Contrary to a test, application code callbacks are processed early (before the v
 ====
 
 
-
 [[howto.webserver.enable-response-compression]]
 == Enable HTTP Response Compression
 
@@ -143,7 +137,6 @@ By default, responses are compressed only if their content type is one of the fo
 You can configure this behavior by setting the configprop:server.compression.mime-types[] property.
 
 
-
 [[howto.webserver.configure-ssl]]
 == Configure SSL
 
@@ -235,7 +228,6 @@ The bundle specified with `server.ssl.bundle` will be used for the default host,
 This default bundle must be configured if any `server.ssl.server-name-bundles` are configured.
 
 
-
 [[howto.webserver.configure-http2]]
 == Configure HTTP/2
 
@@ -290,7 +282,6 @@ Developers can choose to import only the required dependencies using a classifie
 Undertow supports `h2c` and `h2` out of the box.
 
 
-
 [[howto.webserver.configure]]
 == Configure the Web Server
 
@@ -340,7 +331,6 @@ As a last resort, you can also declare your own `WebServerFactory` bean, which w
 When you do so, auto-configured customizers are still applied on your custom factory, so use that option carefully.
 
 
-
 [[howto.webserver.add-servlet-filter-listener]]
 == Add a Servlet, Filter, or Listener to an Application
 
@@ -389,7 +379,6 @@ include-code::MyFilterConfiguration[]
 By default, `@ServletComponentScan` scans from the package of the annotated class.
 
 
-
 [[howto.webserver.configure-access-logs]]
 == Configure Access Logging
 
@@ -445,34 +434,39 @@ By default, logs are redirected to `System.err`.
 For more details, see the Jetty documentation.
 
 
-
 [[howto.webserver.use-behind-a-proxy-server]]
 == Running Behind a Front-end Proxy Server
 
-If your application is running behind a proxy, a load-balancer or in the cloud, the request information (like the host, port, scheme...) might change along the way.
-Your application may be running on `10.10.10.10:8080`, but HTTP clients should only see `example.org`.
-
-https://tools.ietf.org/html/rfc7239[RFC7239 "Forwarded Headers"] defines the `Forwarded` HTTP header; proxies can use this header to provide information about the original request.
-You can configure your application to read those headers and automatically use that information when creating links and sending them to clients in HTTP 302 responses, JSON documents or HTML pages.
-There are also non-standard headers, like `X-Forwarded-Host`, `X-Forwarded-Port`, `X-Forwarded-Proto`, `X-Forwarded-Ssl`, and `X-Forwarded-Prefix`.
-
-If the proxy adds the commonly used `X-Forwarded-For` and `X-Forwarded-Proto` headers, setting `server.forward-headers-strategy` to `NATIVE` is enough to support those.
-With this option, the Web servers themselves natively support this feature; you can check their specific documentation to learn about specific behavior.
-
-If this is not enough, Spring Framework provides a {url-spring-framework-docs}/web/webmvc/filters.html#filters-forwarded-headers[ForwardedHeaderFilter] for the servlet stack and a {url-spring-framework-docs}/web/webflux/reactive-spring.html#webflux-forwarded-headers[ForwardedHeaderTransformer] for the reactive stack.
-You can use them in your application by setting configprop:server.forward-headers-strategy[] to `FRAMEWORK`.
-
-TIP: If you are using Tomcat and terminating SSL at the proxy, configprop:server.tomcat.redirect-context-root[] should be set to `false`.
-This allows the `X-Forwarded-Proto` header to be honored before any redirects are performed.
-
-NOTE: If your application runs xref:api:java/org/springframework/boot/cloud/CloudPlatform.html#enum-constant-summary[in a supported Cloud Platform], the configprop:server.forward-headers-strategy[] property defaults to `NATIVE`.
-In all other instances, it defaults to `NONE`.
-
+* 👁️if your application -- is running behind a -- proxy OR load-balancer OR | cloud -> request information (host, port, scheme...) -- might along the way --  change 👁️
+    ** _Example:_ application may be running | `10.10.10.10:8080`, BUT HTTP clients should only see `example.org`
+    ** https://tools.ietf.org/html/rfc7239[RFC7239 "Forwarded Headers"]
+        *** == `Forwarded` HTTP header
+            **** non-standard headers
+                ***** _Example:_ `X-Forwarded-Host`, `X-Forwarded-Port`, `X-Forwarded-Proto`, `X-Forwarded-Ssl`, and `X-Forwarded-Prefix`
+        *** uses
+            **** proxies -- can provide information about the -- original request
+            **** applications
+                ***** read those headers &
+                ***** automatically use them |
+                    ****** creating links
+                    ****** sending them to clients | HTTP 302 responses, JSON documents or HTML pages
+    ** if the proxy adds the commonly used `X-Forwarded-For` and `X-Forwarded-Proto` headers ->
+        *** set `server.forward-headers-strategy=NATIVE` OR
+            **** -- delegate to -- web servers
+        *** if it's NOT enough, set configprop:server.forward-headers-strategy[] =`FRAMEWORK`
+            **** {url-spring-framework-docs}/web/webmvc/filters.html#filters-forwarded-headers[ForwardedHeaderFilter] | servlet stack
+            **** {url-spring-framework-docs}/web/webflux/reactive-spring.html#webflux-forwarded-headers[ForwardedHeaderTransformer] | reactive stack
+    ** if you are using Tomcat & terminating SSL | proxy -> set configprop:server.tomcat.redirect-context-root[] = `false`
+        *** -> `X-Forwarded-Proto` header added | before performing any redirects
+    ** default values for configprop:server.forward-headers-strategy[], if your application runs
+        *** | xref:api:java/org/springframework/boot/cloud/CloudPlatform.html#enum-constant-summary[supported Cloud Platform] ->  = `NATIVE`
+        *** | other cases -> == `NONE`
 
 
 [[howto.webserver.use-behind-a-proxy-server.tomcat]]
 === Customize Tomcat's Proxy Configuration
 
+* TODO:
 If you use Tomcat, you can additionally configure the names of the headers used to carry "`forwarded`" information, as shown in the following example:
 
 [configprops,yaml]
@@ -501,7 +495,6 @@ NOTE: You can trust all proxies by setting the `internal-proxies` to empty (but
 You can take complete control of the configuration of Tomcat's `RemoteIpValve` by switching the automatic one off (to do so, set `server.forward-headers-strategy=NONE`) and adding a new valve instance using a `WebServerFactoryCustomizer` bean.
 
 
-
 [[howto.webserver.enable-multiple-connectors-in-tomcat]]
 == Enable Multiple Connectors with Tomcat