RabbitMQ Web STOMP Plugin

Overview

The Web STOMP plugin makes it possible to use STOMP over a WebSocket connection.

The goal of this plugin is to enable STOMP messaging in Web applications.

A similar plugin, Web MQTT plugin, makes it possible to use MQTT over WebSockets.

How It Works

RabbitMQ Web STOMP plugin is a minimalistic "bridge" between the STOMP protocol implementation provided by RabbitMQ STOMP plugin, and WebSocket clients.

RabbitMQ Web STOMP is fully compatible with the RabbitMQ STOMP plugin.

Enabling the Plugin

rabbitmq_web_stomp plugin ships with RabbitMQ.

To enable the plugin run rabbitmq-plugins:

rabbitmq-plugins enable rabbitmq_web_stomp

Usage

In order to use STOMP in a Web browser context, a JavaScript STOMP library is required. We've tested a stomp-websocket library by Jeff Mesnil and Jeff Lindsay. This library is included as part of RabbitMQ Web STOMP examples.

The WebSocket endpoint is available on the /ws path:

ws://127.0.0.1:15674/ws

This endpoint will only work with Websocket capable clients. Note that some configuration is necessary in order to accept binary messages.

In order to establish connection from the browser using WebSocket you may use code like:

<!-- include the client library -->
<script src="stomp.js"></script>

<script>
var ws = new WebSocket('ws://127.0.0.1:15674/ws');
var client = Stomp.over(ws);
// ...

Once you have the client object you can follow API's exposed by stomp.js library. The next step is usually to establish a STOMP connection with the broker:

// ...
var on_connect = function() {
    console.log('connected');
};
var on_error =  function() {
    console.log('error');
};
client.connect('guest', 'guest', on_connect, on_error, '/');
// ...

Web STOMP Examples

A few simple Web STOMP examples are provided as a RabbitMQ Web STOMP examples plugin. To get it running follow the installation instructions for that plugin and enable the plugin:

rabbitmq-plugins enable rabbitmq_web_stomp_examples

The examples will be available under http://127.0.0.1:15670/ url. You will see two examples:

• "echo" - shows how to use STOMP to do simple message broadcasting
• "bunny" - example of a simple collaboration canvas painting app

We encourage you to take a look at the source code.

Configuration

When no configuration is specified the Web STOMP plugin will listen on all interfaces on port 15674 and have a default user login/passcode of guest/guest. Note that this user is only allowed to connect from localhost by default. We highly recommend creating a separate user for production systems.

To change the listener port, edit your Advanced configuration file, to contain a tcp_config section with a port variable for the rabbitmq_web_stomp application.

For example, a complete configuration file which changes the listener port to 12345 would look like:

web_stomp.tcp.port = 12345

You can use the tcp_config section to specify any TCP option you need. See the RabbitMQ Networking guide and Ranch documentation for details about accepted parameters.

TLS (WSS)

The plugin supports WebSockets with TLS (WSS) connections. See TLS guide to learn more about TLS support in RabbitMQ.

TLS configuration parameters are provided in the web_stomp.ssl section:

web_stomp.ssl.port       = 15673
web_stomp.ssl.backlog    = 1024
web_stomp.ssl.cacertfile = /path/to/ca_certificate.pem
web_stomp.ssl.certfile   = /path/to/server_certificate.pem
web_stomp.ssl.keyfile    = /path/to/server_key.pem
web_stomp.ssl.password   = changeme

The TLS listener port, server certificate file, private key and CA certificate bundle are mandatory options. Password is also mandatory if the private key uses one. An extended list of TLS settings is largely identical to those for the core server. Full list of options accepted by this plugin can be found in Ranch documentation.

Enabled TLS Versions and Cipher Suites

It is possible to configure what TLS versions and cipher suites will be used by RabbitMQ. Note that not all suites will be available on all systems.

RabbitMQ TLS guide has a section on TLS versions and another one on cipher suites. Below is an example in the advanced config format that configures cipher suites and a number of other TLS options for the plugin:

web_stomp.ssl.port       = 15673
web_stomp.ssl.backlog    = 1024
web_stomp.ssl.certfile   = /path/to/server_certificate.pem
web_stomp.ssl.keyfile    = /path/to/server_key.pem
web_stomp.ssl.cacertfile = /path/to/ca_certificate_bundle.pem
web_stomp.ssl.password   = changeme

web_stomp.ssl.honor_cipher_order   = true
web_stomp.ssl.honor_ecc_order      = true
web_stomp.ssl.client_renegotiation = false
web_stomp.ssl.secure_renegotiate   = true

web_stomp.ssl.versions.1 = tlsv1.2
web_stomp.ssl.versions.2 = tlsv1.1
web_stomp.ssl.ciphers.1 = ECDHE-ECDSA-AES256-GCM-SHA384
web_stomp.ssl.ciphers.2 = ECDHE-RSA-AES256-GCM-SHA384
web_stomp.ssl.ciphers.3 = ECDHE-ECDSA-AES256-SHA384
web_stomp.ssl.ciphers.4 = ECDHE-RSA-AES256-SHA384
web_stomp.ssl.ciphers.5 = ECDH-ECDSA-AES256-GCM-SHA384
web_stomp.ssl.ciphers.6 = ECDH-RSA-AES256-GCM-SHA384
web_stomp.ssl.ciphers.7 = ECDH-ECDSA-AES256-SHA384
web_stomp.ssl.ciphers.8 = ECDH-RSA-AES256-SHA384
web_stomp.ssl.ciphers.9 = DHE-RSA-AES256-GCM-SHA384

Troubleshooting TLS (WSS)

See RabbitMQ TLS and TLS Troubleshooting for additional information.

Basic HTTP Authentication

The use_http_auth option extends the authentication by allowing clients to send the login and passcode in the HTTP authorisation header (using HTTP Basic Auth). If present, these credentials will be used. Otherwise, the default STOMP credentials are used. The credentials found in the CONNECT frame, if any, are ignored.

This is an advanced feature that is only exposed via the advanced configuration file or the classic config format:

[
  {rabbitmq_web_stomp,
      [{use_http_auth, true}]}
].

Proxy Protocol

The Web STOMP plugin supports the proxy protocol. This feature is deactivated by default, to activate it for clients:

web_stomp.proxy_protocol = true

See the Networking Guide for more information about the proxy protocol.

Advanced Options

The Web STOMP plugin uses the Cowboy HTTP and WebSocket server under the hood. Cowboy provides a number of options that can be used to customize the behavior of the server w.r.t. WebSocket connection handling.

Some settings are generic HTTP ones, others are specific to WebSockets.

Content Encoding

By default, the Web STOMP plugin will expect to handle messages encoded as UTF-8. The WebSocket endpoint exposed by this plugin can be switched to binary mode if needed using the ws_frame option:

web_stomp.ws_frame = binary

HTTP Options

Generic HTTP server settings can be specified using web_stomp.cowboy_opts.* keys, for example:

# connection inactivity timeout
web_stomp.cowboy_opts.idle_timeout = 60000
# max number of pending requests allowed on a connection
web_stomp.cowboy_opts.max_keepalive = 200
# max number of headers in a request
web_stomp.cowboy_opts.max_headers   = 100
# max number of empty lines before request body
web_stomp.cowboy_opts.max_empty_lines = 5
# max request line length allowed in requests
web_stomp.cowboy_opts.max_request_line_length

WebSocket Options

# WebSocket traffic compression is enabled by default
web_stomp.ws_opts.compress = true

# WebSocket connection inactivity timeout
web_stomp.ws_opts.idle_timeout = 60000

web_stomp.ws_opts.max_frame_size = 50000