mod_websocket

WebSockets is a protocol for providing web pages with simple two-way communication with a web server. This module allows browsers to communicate with Prosody via XMPP over WebSockets. This usually induces less overhead than using BOSH.

There are many JavaScript XMPP libraries capable of utilizing WebSockets, among them:

Usage

modules_enabled = {
    -- Other modules
    "websocket"; -- Enable mod_websocket
}

To allow requests that would normally break the Same-Origin policy, the cross_domain_websocket option can be used. Set it to true to enable cross-domain requests from all websites, or specify a list:

cross_domain_websocket = { "http://jabber.org", "http://prosody.im" }

If encryption is provided by a HTTP proxy, Prosody won’t be able to see this, and consider the connection insecure (consequently forbidding some authentication mechanisms). In this case Prosody can be told to always consider WebSocket connections secure by setting in the global section.

consider_websocket_secure = true

The WebSocket endpoint will be at wss:example.com:5281/xmpp-websocket and ws:example.com:5280/xmpp-websocket by default, see HTTP path configuration if you would like to change this.

Configuration

Option	Type	Default
`c2s_close_timeout`	number	`5`
`consider_websocket_secure`	boolean	empty

Cross-domain (CORS) configuration

Starting with Prosody 0.12, mod_websocket allows cross-domain requests by default. This is the most common deployment choice, and no further configuration is necessary.

If, for some reason, you wish to modify the CORS configuration, you can do this via Prosody’s HTTP configuration starting with Prosody 0.12.1.

In Prosody 0.11 and earlier, you can instead use the cross_domain_websocket option, which can be set to a list of allowed origins, e.g. { "https://example.com" }. The http_host setting on the current VirtualHost is used as a default.