WebSocketServlet

The WebSocket protocol provides full-duplex communication over a single TCP connection (see RFC 6455). The WebSocket handshake is interpreted by HTTP servers as an upgrade request. The WebSocketServlet is responsible for supporting connections over a WebSocket.

The WebSocketServlet can be used for normal HTTP traffic and for traffic with the WebSocket protocol. The WebSocketServlet behaves like a normal HttpConnectorServlet before a protocol upgrade header, or after the WebSocket connection is closed.

Classname:
ch::nevis::isiweb4::servlet::connector::websocket::WebSocketServlet

Library:
libWebSocketServlet.so.1

Configuration

All the configuration attributes of the Http(s)ConnectorServlet (see the chapters: "HttpConnectorServlet" and "HttpsConnectorServlet") can also be configured for theWebSocketServlet, except for theKeepAliveattribute. This attribute has to be set to true (which is the configured default). Otherwise, an exception will be thrown on startup and the WebSocketServlet will not be active. The only required attribute is the InetAddress attribute. All other attributes are optional or have a default value.

Additionally, the WebSocketServlet contains the following attributes:

UpdateSessionInterval

• Type: integer
• Usage Constrains: optional
• Default: 30

If an HTTP session is closed, all TCP connections opened by WebSocketServlets are also closed, due to security reasons. If there is ongoing traffic on the WebSocketServlet, the servlet will prevent the timeout of the session by updating the timestamp of the session every 30 seconds. The UpdateSessionInterval attribute allows you to override this value.

A value of "0" will disable this session-keepalive mechanism. In this case, a terminated session will not cause the closing of the WebSocket connections. This is a special case and not recommended for security reasons.

info

• If the UpdateSessionInterval is high and the inactive session timeout is low, then sessions might time out even if the WebSocket connection is active.
• If the UpdateSessionInterval is too low and you use a MariaDB-based session store, you might generate too much change in the database, leading to too much data in the binary logs. This can happen if there are too many active WebSocket connections.

IdleTimeout

• Type: integer (seconds)
• Usage Constrains: optional
• Default: min: 1

If there is no ongoing traffic during the configured IdleTimeout on the WebSocket streams, then the WebSocket connection is closed.

note

Using filters with buffering capabilities before the WebSocketServlet can result in undefined behavior. Whether this behavior occurs, depends on the configuration of the filters.

• You can use the following filters in a chain with a WebSocketServlet at its end, if you set the RequestFlagNEEDS_SWITCHING_PROTOCOLS:

  • LuaFilter - For this filter, set the flag NEEDS_SWITCHING_PROTOCOLS.
  • ModsecurityFilter - This filter has enabled the NEEDS_SWITCHING_PROTOCOLS flags per default. The ModSecurity filter does not protect binary data flow generated by WebSocket clients and servers
  • UrlEncryptionFilter - This filter has enabled the NEEDS_SWITCHING_PROTOCOLS flags per default
  • RewriteFilter - The rules are not applied to the data stream of the websocket data.
  • ICAPFilter - The websocket data stream is not passed to the icap-server.

  For more information on RequestFlags, see chapter RequestFlags

  The above filter list is not complete. Other filters may be concerned, depending on their configuration.

Sample configuration

The following example shows a simple WebSocketServlet configuration:

<servlet>
    <servlet-name>WebSocketServlet</servlet-name>
    <servlet-class>ch::nevis::isiweb4::servlet::connector::websocket::WebSocketServlet</servlet-class>
  
    <init-param>
      <param-name>InetAddress</param-name>
      <param-value>@HOST_NAME@:@HOST_PORT@</param-value>
    </init-param>

    <init-param>
      <param-name>AllowedMethods</param-name>
      <param-value>HEAD,POST,GET</param-value>
    </init-param>
  
    <init-param>
      <param-name>CookieManager</param-name>
      <param-value>store:^.*$</param-value>
    </init-param>
  
    <init-param>
      <param-name>UseSSL</param-name>
      <param-value>false</param-value>
    </init-param>

    <init-param>
        <param-name>ResourceManager.RetryTimeout</param-name>
        <param-value>0</param-value>
    </init-param>

    <init-param>
        <param-name>ResourceManager.DisablePing</param-name>
        <param-value>true</param-value>
    </init-param>
</servlet>

<!-- ********** servlet mapping ************** -->
  
<servlet-mapping>
    <servlet-name>WebSocketServlet</servlet-name>
    <url-pattern>/path/to/servlet/*</url-pattern>
</servlet-mapping>