RabbitMQ Web STOMP Plugin

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 rather simple. It takes the STOMP protocol, as provided by RabbitMQ STOMP plugin and exposes it using WebSockets.

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:

http://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 production systems.

To change this, 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

Or using the classic config format:

[
  {rabbitmq_web_stomp,
      [{tcp_config, [{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 (SSL)

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.certfile   = /path/to/server/certificate.pem
web_stomp.ssl.keyfile    = /path/to/server/private_key.pem
web_stomp.ssl.cacertfile = /path/to/testca/ca_certificate_bundle.pem
web_stomp.ssl.password   = changeme

In the classic config format the section is rabbitmq_web_stomp.ssl_config:

[
  {rabbitmq_web_stomp,
      [{ssl_config, [{port,       15673},
                     {backlog,    1024},
                     {certfile,   "/path/to/server/certificate.pem"},
                     {keyfile,    "/path/to/server/private_key.pem"},
                     {cacertfile, "/path/to/testca/ca_certificate_bundle.pem"},
                     %% needed when private key has a passphrase
                     {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.

A separate guide on troubleshooting TLS is also available.

Basic HTTP Authentication

The use_http_auth option extends the authentication by allowing clients to send the login and passcode in the HTTP Authorization 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 disabled by default, to enable it for clients:

web_stomp.proxy_protocol = true

Or, using the classic config format:

[
  {rabbitmq_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

Or using the classic config format:

[
  {rabbitmq_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

In the classic config format:

[
  {rabbitmq_web_stomp,
      [
        {cowboy_opts, [{max_keepalive, 200},
                       {max_headers,   100}]}
      ]
  }
].

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

web_stomp.ws_opts.max_frame_size = 50000