• Features
• Get Started
• Support
• Community
• Docs
• Blog

RabbitMQ Web STOMP Plugin

The Web STOMP plugin is a simple bridge exposing the STOMP protocol over direct or emulated HTML5 WebSockets.

The main intention of Web-Stomp is to make it possible to use RabbitMQ from Web browsers. It influenced the Web MQTT plugin which is the same idea for a different protocol, MQTT.

More context is available in the introductory blog post.

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.

Since version 3.7 support for SockJS websocket emulation was removed.

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.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. That requires Erlang/OTP 17.5 or a later version.

TLS (SSL) configuration parameters are provided in the ssl_config section:

web_stomp.ssl.port       = 12345
web_stomp.ssl.backlog    = 1024
web_stomp.ssl.certfile   = path/to/certs/client/cert.pem
web_stomp.ssl.keyfile    = path/to/certs/client/key.pem
web_stomp.ssl.cacertfile = path/to/certs/testca/cacert.pem
web_stomp.ssl.password   = changeme

Or using the classic config format:

[
  {rabbitmq_web_stomp,
      [{ssl_config, [{port,       15671},
                     {backlog,    1024},
                     {certfile,   "path/to/certs/client/cert.pem"},
                     {keyfile,    "path/to/certs/client/key.pem"},
                     {cacertfile, "path/to/certs/testca/cacert.pem"},
                     %% needed when private key has a passphrase
                     {password,   "changeme"}]}]}
].

Note that port, certfile, keyfile and password are all mandatory. See the TLS guide and Ranch documentation for details about accepted parameters.

A separate guide on TLS Troubleshooting is also available.

WebSocket Options and Content Encoding

By default, the Web STOMP plugin will expect to handle messages encoded as UTF-8. You can switch the WebSocket endpoint to binary if needed. The ws_frame option serves this purpose:

web_stomp.ws_frame = binary

Or using the classic config format:

[
  {rabbitmq_web_stomp, [{ws_frame, binary}]}
].

The Web STOMP plugin uses the Cowboy web 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. You can specify those in the Web STOMP plugin configuration, in the cowboy_opts section:

web_stomp.cowboy_opts.max_keepalive = 10

Or using the classic config format:

[
  {rabbitmq_web_stomp,
      [{cowboy_opts, [{max_keepalive, 10}]}]}
].

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}]}
].

Missing features

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