Merge in APR[-util] macros from branches/trunk-buildconf-noapr

[apache] / docs / manual / mod / mod_proxy_wstunnel.xml

diff --git a/docs/manual/mod/mod_proxy_wstunnel.xml b/docs/manual/mod/mod_proxy_wstunnel.xml
index 203bf04fa23874fa3d845af792dfde84a211d53b..41afed05487cb174f99322eb95f2ec7686506cbb 100644 (file)
--- a/docs/manual/mod/mod_proxy_wstunnel.xml
+++ b/docs/manual/mod/mod_proxy_wstunnel.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
-<!-- $LastChangedRevision: 1174747 $ -->
+<!-- $LastChangedRevision$ -->
 
 <!--
  Licensed to the Apache Software Foundation (ASF) under one or more
@@ -28,28 +28,90 @@
 <status>Extension</status>
 <sourcefile>mod_proxy_wstunnel.c</sourcefile>
 <identifier>proxy_wstunnel_module</identifier>
-<compatibility>Available for unix in version 2.4.5 and later</compatibility>
+<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
     socket connections to a backend websockets server. The connection
-    is automagically upgraded to a websocket connection:</p>
+    is automatically upgraded to a websocket connection:</p>
 
-    <highlight language="config">
+    <example><title>HTTP Response</title>
+        <highlight language="config">
 Upgrade: WebSocket
 Connection: Upgrade
-    </highlight>
-
+        </highlight>
+    </example>
 
-    <example><title>Proxying requests to websockets server</title>
+<p>Proxying requests to a websockets server like <code>echo.websocket.org</code> can be done using the
+<directive type="ProxyPass" module="mod_proxy">ProxyPass</directive> directive:</p>
     <highlight language="config">
-ProxyPass /ws2/  ws://echo.websocket.org/
-ProxyPass /wss2/ wss://echo.websocket.org/
+ProxyPass "/ws2/"  "ws://echo.websocket.org/"
+ProxyPass "/wss2/" "wss://echo.websocket.org/"
     </highlight>
-    </example>
 
+<p>Load balancing for multiple backends can be achieved using <module>mod_proxy_balancer</module>.</p>
+
+<p>In fact the module can be used to upgrade to other protocols, you can set the <code>upgrade</code>
+parameter in the <directive type="ProxyPass" module="mod_proxy">ProxyPass</directive>
+directive to allow the module to accept other protocol.
+NONE means you bypass the check for the header but still upgrade to WebSocket.</p>
 </summary>
 
 <seealso><module>mod_proxy</module></seealso>
+
+<directivesynopsis>
+<name>ProxyWebsocketAsync</name>
+<description>Instructs this module to try to create an asynchronous tunnel</description>
+<syntax>ProxyWebsocketAsync ON|OFF</syntax>
+<contextlist><context>server config</context>
+<context>virtual host</context>
+</contextlist>
+
+<usage>
+    <p>This directive instructs the server to try to create an asynchronous tunnel.
+    If the current MPM does not support the necessary features, a synchronous
+    tunnel is used.</p>
+    <note><title>Note</title><p>Async support is experimental and subject
+    to change.</p></note>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>ProxyWebsocketIdleTimeout</name>
+<description>Sets the maximum amount of time to wait for data on the websockets tunnel</description>
+<syntax>ProxyWebsocketIdleTimeout <var>num</var>[ms]</syntax>
+<default>ProxyWebsocketIdleTimeout 0</default>
+<contextlist><context>server config</context>
+<context>virtual host</context>
+</contextlist>
+
+<usage>
+    <p>This directive imposes a maximum amount of time for the tunnel to be
+    left open while idle. The timeout is considered in seconds by default, but
+    it is possible to increase the time resolution to milliseconds
+    adding the <em>ms</em> suffix.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>ProxyWebsocketAsyncDelay</name>
+<description>Sets the amount of time the tunnel waits synchronously for data</description>
+<syntax>ProxyWebsocketAsyncDelay <var>num</var>[ms]</syntax>
+<default>ProxyWebsocketAsyncDelay 0</default>
+<contextlist><context>server config</context>
+<context>virtual host</context>
+</contextlist>
+
+<usage>
+    <p>If <directive>ProxyWebsocketAsync</directive> is enabled, this directive
+    controls how long the server synchronously waits for more data. The timeout
+    is considered in seconds by default, but it is possible to increase
+    the time resolution to milliseconds adding the <em>ms</em> suffix.</p>
+
+    <note><title>Note</title><p>Async support is experimental and subject
+    to change. </p></note>
+
+</usage>
+</directivesynopsis>
 </modulesynopsis>