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.
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.
rabbitmq_web_stomp plugin ships with RabbitMQ.
To enable the plugin run rabbitmq-plugins:
rabbitmq-plugins enable rabbitmq_web_stomp
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, '/'); [...]
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:
We encourage you to take a look at the source code.
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.
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.
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
See RabbitMQ TLS and TLS Troubleshooting for additional information.
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}]} ].
The Web STOMP plugin supports the proxy protocol. This feature is disabled by default, to enable it for clients:
web_stomp.proxy_protocol = true
See the Networking Guide for more information about the proxy protocol.
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.
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
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 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
If you have questions about the contents of this guide or any other topic related to RabbitMQ, don't hesitate to ask them on the RabbitMQ mailing list.
If you'd like to contribute an improvement to the site, its source is available on GitHub. Simply fork the repository and submit a pull request. Thank you!