Document X-Forwarded-* Headers

Previously the documentation assumed that the readers knew how to use
the X-Forwarded-* headers. This commit documents details & examples
of how to use the X-Forwarded-* headers.

See gh-31491

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

@@ -368,31 +368,34 @@ collecting to a `MultiValueMap`.
 === Forwarded Headers
 [.small]#xref:web/webmvc/filters.adoc#filters-forwarded-headers[See equivalent in the Servlet stack]#
 
-As a request goes through proxies (such as load balancers), the host, port, and
-scheme may change. That makes it a challenge, from a client perspective, to create links that point to the correct
-host, port, and scheme.
+include::partial$web/forwarded-headers.adoc[]
 
-https://tools.ietf.org/html/rfc7239[RFC 7239] defines the `Forwarded` HTTP header
-that proxies can use to provide information about the original request. There are other
-non-standard headers, too, including `X-Forwarded-Host`, `X-Forwarded-Port`,
-`X-Forwarded-Proto`, `X-Forwarded-Ssl`, and `X-Forwarded-Prefix`.
+
+
+[[webflux-forwarded-headers-forwardedheadertransformer]]
+=== ForwardedHeaderTransformer
 
 `ForwardedHeaderTransformer` is a component that modifies the host, port, and scheme of
 the request, based on forwarded headers, and then removes those headers. If you declare
 it as a bean with the name `forwardedHeaderTransformer`, it will be
 xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api-special-beans[detected] and used.
 
+NOTE: In 5.1 `ForwardedHeaderFilter` was deprecated and superseded by
+`ForwardedHeaderTransformer` so forwarded headers can be processed earlier, before the
+exchange is created. If the filter is configured anyway, it is taken out of the list of
+filters, and `ForwardedHeaderTransformer` is used instead.
+
+
+
+[[webflux-forwarded-headers-security]]
+=== Security Considerations
+
 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
 `removeOnly=true`, in which case it removes but does not use the headers.
 
-NOTE: In 5.1 `ForwardedHeaderFilter` was deprecated and superseded by
-`ForwardedHeaderTransformer` so forwarded headers can be processed earlier, before the
-exchange is created. If the filter is configured anyway, it is taken out of the list of
-filters, and `ForwardedHeaderTransformer` is used instead.
-
 
 
 [[webflux-filters]]

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

@@ -26,18 +26,16 @@ available through the `ServletRequest.getParameter{asterisk}()` family of method
 
 
 
-[[filters-forwarded-headers]]
+[[forwarded-headers]]
 == Forwarded Headers
 [.small]#xref:web/webflux/reactive-spring.adoc#webflux-forwarded-headers[See equivalent in the Reactive stack]#
 
-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.
+include::partial$web/forwarded-headers.adoc[]
 
-https://tools.ietf.org/html/rfc7239[RFC 7239] defines the `Forwarded` HTTP header
-that proxies can use to provide information about the original request. There are other
-non-standard headers, too, including `X-Forwarded-Host`, `X-Forwarded-Port`,
-`X-Forwarded-Proto`, `X-Forwarded-Ssl`, and `X-Forwarded-Prefix`.
+
+
+[[filters-forwarded-headers-non-forwardedheaderfilter]]
+=== ForwardedHeaderFilter
 
 `ForwardedHeaderFilter` is a Servlet filter that modifies the request in order to
 a) change the host, port, and scheme based on `Forwarded` headers, and b) to remove those
@@ -45,12 +43,22 @@ headers to eliminate further impact. The filter relies on wrapping the request,
 therefore it must be ordered ahead of other filters, such as `RequestContextFilter`, that
 should work with the modified and not the original request.
 
+
+
+[[filters-forwarded-headers-security]]
+=== Security Considerations
+
 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`
 headers that come from the outside. You can also configure the `ForwardedHeaderFilter`
 with `removeOnly=true`, in which case it removes but does not use the headers.
 
+
+
+[[filters-forwarded-headers-dispatcher]]
+=== About 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`.
 If using Spring Framework's `AbstractAnnotationConfigDispatcherServletInitializer`