.. _websockets:

**********
WebSockets
**********

App Suite Proxy provides a way to handle WebSockets to support bidirectional real-time communication between client and server.
Therefor the Proxy runtime can establish a tunnel between a client and a backend server. The client needs to simply send a valid WebSocket handshake 
request and if backend server accepts the handshake the tunnel will be opened.

.. _configuration:

Configuration
=============
The settings to setup WebSockets needs to be done in ``application.properties`` and ``routing.yml``  

**application.properties:**

:proxy.websockets.enabled: **Manadatory for WebSockets:** Enable WebSockets

                         Default: ``false``

                         Reloadable: ``false``
                         
                         EnvVar: ``PROXY_WEBSOCKETS_ENABLED``

:proxy.websockets.port.offset: **Optional:** If WebSockets are enabled the given value can be used to start proxy with a dedicated port on which WebSockets are supported. The concrete port depends on the settings for ``zuul.server.port.main`` and ``proxy.tls.port``. E.g. if ``proxy.tls.port`` is ``8443`` and ``proxy.websockets.port.offset`` is ``10`` the WebSocket port will be ``8453`` . This allows a dedicated management where request on port ``8453`` allow HTTPS as well as WebSockets but request on ``8443`` only allow plain HTTPS.          

                         Default: ``0``

                         Reloadable: ``false``
                         
                         EnvVar: ``PROXY_WEBSOCKETS_PORT_OFFSET``

:proxy.websockets.port.offset: **Optional:** If WebSockets are enabled the given value can be used to override the settings in routing and backend configuration and set the timeout for all WebSocket connections. If set to 0 proxy will never close a connection no matter how long there was no read or write operation on opened connection. If set to -1 this property is disabled and the configuration in routing / backend will be used.         

                         Default: ``-1``

                         Reloadable: ``true``
                         
                         EnvVar: ``PROXY_WEBSOCKETS_GLOBAL_TIMEOUT``

**routing.yml:**

WebSockets needs a specific action type. This enables the proxy to deal with incoming handshake requests. See section WebSocket tunnel in :ref:`Routing Action<routing_actions>`.