From 64a17319f9dbdd0f20c3e605cff76e76903a182d Mon Sep 17 00:00:00 2001
From: Yann Ylavic <ylavic@apache.org>
Date: Fri, 27 Jan 2023 16:47:28 +0000
Subject: [PATCH] docs: Add deprecation note for wstunnel, move Upgrade example
 up for proxy_http.

[skip ci]


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1907035 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/mod/mod_proxy.xml          | 42 ++++++++++++++------------
 docs/manual/mod/mod_proxy_wstunnel.xml | 10 ++++--
 2 files changed, 30 insertions(+), 22 deletions(-)

diff --git a/docs/manual/mod/mod_proxy.xml b/docs/manual/mod/mod_proxy.xml
index cf0653cd95a..e73b3abbebc 100644
--- a/docs/manual/mod/mod_proxy.xml
+++ b/docs/manual/mod/mod_proxy.xml
@@ -170,6 +170,11 @@ ProxyVia On
 &lt;Proxy *&gt;
   Require host internal.example.com
 &lt;/Proxy&gt;
+    </highlight>
+    </example>
+    <example><title><a id="wsupgrade" name="wsupgrade">Websocket Upgrade (2.4.47 and later)</a></title>
+    <highlight language="config">
+ProxyPass "/some/ws/capable/path/" "http://example.com/some/ws/capable/path/" upgrade=websocket
     </highlight>
     </example>
     </section> <!-- /examples -->
@@ -1505,26 +1510,23 @@ ProxyPassReverse  "/mirror/foo/" "https://backend.example.com/"
     </highlight>
 
     <note><title><a id="protoupgrade" name="protoupgrade">Protocol Upgrade</a></title>
-        <p>Since Apache HTTP Server 2.4.47, protocol Upgrade (tunneling) can be handled
-        end-to-end by <module>mod_proxy_http</module> using the <directive>ProxyPass</directive>
-        parameter <var><a href="#upgrade">upgrade</a></var>.</p>
-        <p>End-to-end means that the HTTP Upgrade request from the client/browser is first
-        forwarded by <module>mod_proxy_http</module> to the origin server and the connection
-        will be upgraded (and tunneled by <module>mod_proxy_http</module>) only if the origin
-        server accepts/initiates the upgrade (HTTP response <code>101 Switching Protocols</code>).
-        If the origin server responds with anything else <module>mod_proxy_http</module>
-        will continue forwarding (and enforcing) the HTTP protocol as usual for this
-        connection.</p>
-        <example><title>Example</title>
-        <highlight language="config">
-ProxyPass "/some/http/or/ws/path/" "http://example.com/some/http/or/ws/path/" upgrade=websocket
-        </highlight>
-        </example>
-        <p>For Apache HTTP Server 2.4.46 and earlier (or if
-        <directive module="mod_proxy_wstunnel">ProxyWebsocketFallbackToProxyHttp</directive>
-        from 2.4.48 and later disables <module>mod_proxy_http</module> handling), see the
-        documentation of <module>mod_proxy_wstunnel</module> for how to proxy the WebSocket
-        protocol.</p>
+      <p>Since Apache HTTP Server 2.4.47, protocol Upgrade (tunneling) can be handled
+      end-to-end by <module>mod_proxy_http</module> using the <directive>ProxyPass</directive>
+      parameter <var><a href="#upgrade">upgrade</a></var>.</p>
+      <p>End-to-end means that the HTTP Upgrade request from the client/browser is first
+      forwarded by <module>mod_proxy_http</module> to the origin server and the connection
+      will be upgraded (and tunneled by <module>mod_proxy_http</module>) only if the origin
+      server accepts/initiates the upgrade (HTTP response <code>101 Switching Protocols</code>).
+      If the origin server responds with anything else <module>mod_proxy_http</module>
+      will continue forwarding (and enforcing) the HTTP protocol as usual for this
+      connection.</p>
+      <p>See <a href="#wsupgrade">Websocket Upgrade (2.4.47 and later)</a> for an example of
+      configuration using <module>mod_proxy_http</module>.</p>
+      <p>For Apache HTTP Server 2.4.46 and earlier (or if
+      <directive module="mod_proxy_wstunnel">ProxyWebsocketFallbackToProxyHttp</directive>
+      from 2.4.48 and later disables <module>mod_proxy_http</module> handling), see the
+      documentation of <module>mod_proxy_wstunnel</module> for how to proxy the WebSocket
+      protocol.</p>
     </note>
 </usage>
 </directivesynopsis>
diff --git a/docs/manual/mod/mod_proxy_wstunnel.xml b/docs/manual/mod/mod_proxy_wstunnel.xml
index e638ae03304..2f726349c3c 100644
--- a/docs/manual/mod/mod_proxy_wstunnel.xml
+++ b/docs/manual/mod/mod_proxy_wstunnel.xml
@@ -31,8 +31,8 @@
 <compatibility>Available in httpd 2.4.5 and later</compatibility>
 
 <summary>
-    <p>This module <em>requires</em> the service of <module
-    >mod_proxy</module>. It provides support for the tunnelling of web
+    <p>This module <em>requires</em> the service of <module >mod_proxy</module>.
+    It provides support for the tunnelling of web
     socket connections to a backend websockets server. The connection
     is automatically upgraded to a websocket connection:</p>
 
@@ -67,6 +67,12 @@ directive to allow the module to accept other protocol.
 NONE means you bypass the check for the header but still upgrade to WebSocket.
 ANY means that <code>Upgrade</code> will read in the request headers and use
 in the response <code>Upgrade</code></p>
+
+  <note type="warning"><title><a id="deprecation" name="deprecation">Deprecation</a></title>
+    <p>Since Apache HTTP Server 2.4.47, protocol Upgrade (tunneling) can be better handled by
+    <module>mod_proxy_http</module>.</p>
+    <p>See <a href="mod_proxy.html#protoupgrade">Protocol Upgrade</a>.</p>
+  </note>
 </summary>
 
 <seealso><module>mod_proxy</module></seealso>
-- 
2.47.2