WebSocket Options

Crossbar.io is built on an advanced and complete WebSocket implementation that exposes various options and tunables you might be interested in, especially if you take your server to production.

For options related to WebSocket compression, please see here.

To set options on a WebSocket transport, add an options dictionary to the transport configuration part. Here is an example:

{
   "type": "websocket",
   "endpoint": {
      "type": "tcp",
      "port": 8080
   },
   "url": "ws://localhost:8080",
   "options": {
      "enable_webstatus": false
   }
}

Above will run a WebSocket transport, but disable the automatic rendering of a server status page when the WebSocket server is accessed from a regular Web client that does not upgrade to WebSocket.

Available Options

The available options are:

option	description
allowed_origins	A list of allowed WebSocket origins - can use * as a wildcard character, e.g. [”https://*.tavendo.com”, “http://localhost:8080”]
external_port	The external visible port this service be reachable under (i.e. when running behind a L2/L3 forwarding device) (default: null)
enable_hybi10	Enable Hybi-10 version of WebSocket (an intermediary spec). (default: true)
enable_rfc6455	Enable RFC6455 version of WebSocket (the final spec). (default: true)
enable_webstatus	Enable the WebSocket server’s status rendering page. (default: true)
validate_utf8	Validate incoming WebSocket text messages for UTF8 conformance. (default: true)
mask_server_frames	Mask server-sent WebSocket frames. WARNING: Enabling this will break protocol compliance! (default: false)
require_masked_client_frames	Require all WebSocket frames received to be masked. (default: true)
apply_mask	Actually apply WebSocket masking (both in- and outgoing). (default: true)
max_frame_size	Maximum size in bytes of incoming WebSocket frames accepted or 0 to allow any size. (default: 0)
max_message_size	Maximum size in bytes of incoming WebSocket messages accepted or 0 to allow any size. (default: 0)
auto_fragment_size	Automatically fragment outgoing WebSocket messages into WebSocket frames of payload maximum specified size in bytes or 0 to disable. (default: 0)
fail_by_drop	On severe errors (like WebSocket protocol violations), brutally drop the TCP connection instead of performing a full WebSocket closing handshake. (default: false)
echo_close_codereason	During a WebSocket closing handshake initiated by a peer, echo the peer’s close code and reason. Otherwise reply with code 1000 and no reason. (default: false)
open_handshake_timeout	WebSocket opening handshake timeout in ms or 0 to disable. (default: 0)
close_handshake_timeout	WebSocket closing handshake timeout in ms or 0 to disable. (default: 0)
tcp_nodelay	Set the TCP No-Delay (“Nagle”) socket option (default: true)
auto_ping_interval	Send a WebSocket ping every this many ms or 0 to disable. (default: 0)
auto_ping_timeout	Drop the connection if the peer did not respond to a previously sent ping in this many ms or 0 to disable. (default: 0)
auto_ping_size	Payload size for pings sent, must be between 12 and 125 (default: 12)
auto_ping_restart_on_any_traffic	Cancel a pending ping timeout already by having received a data frame. (default: true)
compression	enable WebSocket compression - see WebSocket Compression
require_websocket_subprotocol	Require WebSocket clients to properly announce the WAMP-WebSocket subprotocols it is able to speak This can be one or more from wamp.2.json, wamp.2.msgpack, wamp.2.json.batched and wamp.2.json.batched. Crossbar.io will by default require the client to announce the subprotocols it supports and select one of the announced subprotocols. If this option is set to false, Crossbar.io will no longer require the client to announce subprotocols and assume wamp.2.json when no WebSocket subprotocol is announced. (default: true)

Production Settings

For example, here is a configuration for a production WebSocket service with conservative settings:

{
   "type": "websocket",
   "endpoint": {
      "type": "tcp",
      "port": 8080
   },
   "url": "ws://myserver.com:8080",
   "options": {
      "enable_webstatus": false,
      "max_frame_size": 1048576,
      "max_message_size": 1048576,
      "auto_fragment_size": 65536,
      "fail_by_drop": true,
      "open_handshake_timeout": 2500,
      "close_handshake_timeout": 1000,
      "auto_ping_interval": 10000,
      "auto_ping_timeout": 5000,
      "auto_ping_size": 12,
      "auto_ping_restart_on_any_traffic": true
   }
}