Polishing

Closes gh-31491

Author: rstoyanchev

framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc

@@ -372,7 +372,7 @@ include::partial$web/forwarded-headers.adoc[]
 
 
 
-[[webflux-forwarded-headers-forwardedheadertransformer]]
+[[webflux-forwarded-headers-transformer]]
 === ForwardedHeaderTransformer
 
 `ForwardedHeaderTransformer` is a component that modifies the host, port, and scheme of
@@ -390,7 +390,7 @@ filters, and `ForwardedHeaderTransformer` is used instead.
 [[webflux-forwarded-headers-security]]
 === Security Considerations
 
-There are security considerations for forwarded headers, since an application cannot know
+There are security considerations for forwarded headers since an application cannot know
 if the headers were added by a proxy, as intended, or by a malicious client. This is why
 a proxy at the boundary of trust should be configured to remove untrusted forwarded traffic coming
 from the outside. You can also configure the `ForwardedHeaderTransformer` with

framework-docs/modules/ROOT/pages/web/webmvc/filters.adoc

@@ -57,7 +57,7 @@ with `removeOnly=true`, in which case it removes but does not use the headers.
 
 
 [[filters-forwarded-headers-dispatcher]]
-=== About Dispatcher Types
+=== Dispatcher Types
 
 In order to support xref:web/webmvc/mvc-ann-async.adoc[asynchronous requests] and error dispatches this
 filter should be mapped with `DispatcherType.ASYNC` and also `DispatcherType.ERROR`.

framework-docs/modules/ROOT/partials/web/forwarded-headers.adoc

@@ -1,4 +1,4 @@
-As a request goes through proxies (such as load balancers) the host, port, and
+As a request goes through proxies such as load balancers the host, port, and
 scheme may change, and that makes it a challenge to create links that point to the correct
 host, port, and scheme from a client perspective.
 
@@ -14,7 +14,6 @@ There are other non-standard headers, too, including `X-Forwarded-Host`, `X-Forw
 `X-Forwarded-Proto`, `X-Forwarded-Ssl`, and `X-Forwarded-Prefix`.
 
 
-
 [[x-forwarded-host]]
 ==== X-Forwarded-Host
 
@@ -25,7 +24,6 @@ a proxy which forwards the request to `http://localhost:8080/resource`, then a h
 `X-Forwarded-Host: example.com` can be sent to inform the server that the original host was `example.com`.
 
 
-
 [[x-forwarded-port]]
 ==== X-Forwarded-Port
 
@@ -36,7 +34,6 @@ communicate the original port to a downstream server. For example, if a request
 to inform the server that the original port was `443`.
 
 
-
 [[x-forwarded-proto]]
 ==== X-Forwarded-Proto
 
@@ -47,7 +44,6 @@ a proxy which forwards the request to `http://localhost:8080/resource`, then a h
 `X-Forwarded-Proto: https` can be sent to inform the server that the original protocol was `https`.
 
 
-
 [[x-forwarded-ssl]]
 ==== X-Forwarded-Ssl
 
@@ -58,78 +54,69 @@ original protocol (e.g. https / https) to a downstream server. For example, if a
 original protocol was `https`.
 
 
-
 [[x-forwarded-prefix]]
 ==== X-Forwarded-Prefix
 
 While not standard, https://microsoft.github.io/reverse-proxy/articles/transforms.html#defaults[`X-Forwarded-Prefix: <prefix>`]
 is a de-facto standard header that is used to communicate the original URL path prefix to a
 downstream server.
 
-The definition of the path prefix is most easily defined by an example. For example, consider
-the following proxy to server mapping of:
+Use of `X-Forwarded-Prefix` can vary by deployment scenario, and needs to be flexible to
+allow replacing, removing, or prepending the path prefix of the target server.
+
+_Scenario 1: Override path prefix_
 
 [subs="-attributes"]
 ----
 https://example.com/api/{path} -> http://localhost:8080/app1/{path}
 ----
 
-The prefix is defined as the porition of the URL path before the capture group of `+{path}+`.
-For the proxy, the prefix is `/api` and for the server the prefix is `/app1`. In this case,
-the header of `X-Forwarded-Prefix: /api` can be sent to indicate the original prefix of `/api`
-which overrides the server's prefix of `/app1`.
+The prefix is the start of the path before the capture group `+{path}+`. For the proxy,
+the prefix is `/api` while for the server the prefix is `/app1`. In this case, the proxy
+can send `X-Forwarded-Prefix: /api` to have the original prefix `/api` override the
+server prefix `/app1`.
 
-The `X-Forwarded-Prefix` is flexible because it overrides the existing prefix. This means that
-the server prefix can be replaced (as demonstrated above), removed, or modified.
+_Scenario 2: Remove path prefix_
 
-The previous example demonstrated how to replace the prefix, but at times users may want to
-instruct the server to remove the prefix. For example, consider the proxy to server
-mapping of:
+At times, an application may want to have the prefix removed. For example, consider the
+following proxy to server mapping:
 
 [subs="-attributes"]
 ----
 https://app1.example.com/{path} -> http://localhost:8080/app1/{path}
 https://app2.example.com/{path} -> http://localhost:8080/app2/{path}
 ----
 
-In the `app1` example above, the proxy has an empty prefix and the server has a prefix of
-`/app1`. The header of ``X-Forwarded-Prefix: `` can be sent to indicate the original empty
-prefix which overrides the server's prefix of `/app1`. In the `app2` example above, the proxy
-has an empty prefix and the server has a prefix of `/app2`. The header of ``X-Forwarded-Prefix: ``
-can be sent to indicate the original empty prefix which overrides the server's prefix of `/app2`.
+The proxy has no prefix, while applications `app1` and `app2` have path prefixes
+`/app1` and `/app2` respectively. The proxy can send ``X-Forwarded-Prefix: `` to
+have the empty prefix override server prefixes `/app1` and `/app2`.
 
 [NOTE]
 ====
-A common usecase is that an organization pays licenses per production application server.
-This means that they prefer to deploy multiple applications to each application server to
-avoid paying the licensing fees.
-
-Another common usecase is that organizations may be using more resource intensive
-application servers. This means that they prefer to deploy multiple applications to each
-application server to avoid consuming additional resources.
-
-In both of these usecases, applications must define a non-empty context root because there is
-more than one application associated to the same application server.
-
-While their application is deployed with a non-empty context root, they do not want this
-expressed in the path of their URLs because they use a different subdomain for each application.
-Using different subdomains for each application provides benefits such as:
-
-* Added security (e.g. same origin policy)
-* Allows for scaling the applications differently (a different domain can point to different
-IP addresses)
-
-The example above illustrates how to implement such a scenario.
+A common case for this deployment scenario is where licenses are paid per
+production application server, and it is preferable to deploy multiple applications per
+server to reduce fees. Another case is I/O bound applications, and the need to deploy
+multiple applications to each application server to consume less resources.
+
+In this scenario, applications need a non-empty context root because there are multiple
+applications on the same server. However, this should not be visible in URL paths of
+the public API where applications may use different subdomains that provides benefits
+such as:
+
+* Added security, e.g. same origin policy
+* Independent scaling of applications (different domain points to different IP address)
 ====
 
-In some cases, a proxy may want to insert a prefix in front of the existing prefix. For
-example, consider the proxy to server mapping of:
+_Scenario 3: Insert path prefix_
+
+In other cases, it may be necessary to prepend a prefix. For example, consider the
+following proxy to server mapping:
 
 [subs="-attributes"]
 ----
 https://example.com/api/app1/{path} -> http://localhost:8080/app1/{path}
 ----
 
-In the example above, the proxy has a prefix of `/api/app1` and the server has a prefix of
-`/app1`. The header of `X-Forwarded-Prefix: /api/app1` can be sent to indicate the original
-prefix of `/api/app1` which overrides the server's prefix of `/app1`.
+In this case, the proxy has a prefix of `/api/app1` and the server has a prefix of
+`/app1`. The proxy can send `X-Forwarded-Prefix: /api/app1` to have the original prefix
+`/api/app1` override the server prefix `/app1`.