STOMP Over WebSockets

RabbitMQ is a message broker that allows clients to connect over a range of different open and standardized protocols such as AMQP, HTTP, STOMP, MQTT, MQTT over WebSockets and STOMP over WebSockets. However, here, we are only interested in STOMP over WebSockets.

STOMP Over Websockets ?

STOMP (Simple Text Oriented Messaging Protocol) is bare-bones, text-based messaging protocol, designed to be easily implemented and understood. RabbitMQ supports the STOMP protocol, natively, via a plugin.

Now, imagine you have a browser-based application that needs to communicate with other STOMP-based systems. You can enable this communication using a messaging broker such as RabbitMQ. RabbitMQ facilitates the exchange of messages between the web application and the systems, acting as a middleman.

But here’s the catch: web browsers don’t natively support STOMP. That’s where STOMP over Websockets comes in - It’s a clever solution that allows web browsers to route STOMP traffic over a Websocket connection.

RabbitMQ supports STOMP over WebSockets via the Web-STOMP plugin. You can activate the Web-STOMP plugin using the RabbitMQ CLI with the command: rabbitmq-plugins enable rabbitmq_web_stomp or from the CloudAMQP console.

On CloudAMQP, the Web-STOMP plugin can only be enabled on dedicated plans.

Once enabled, the Web-STOMP plugin exposes a WebSocket endpoint that allows web browsers to communicate directly with your RabbitMQ server/cluster.

Usage

To use Web-STOMP, you first need to create at least one user with limited permissions and a new vhost, which you can expose publicly. The username, password, vhost, and your broker URL will be used to connect to your cluster in subsequent steps.

Next include stomp-js, the JavaScript STOMP client library, in your HTML from a CDN(for example).

<script src="//cdn.jsdelivr.net/npm/@stomp/stompjs@5.0.0/bundles/stomp.umd.min.js"></script>

Next, connect to the broker using client credentials. Then, publish and consume messages as shown in the snippet below:

import { Client } from '@stomp/stompjs';

// Load client credentials from env vars
const clientSettings = {
  brokerURL: process.env.BROKER_URL,
  connectHeaders: {
    login: process.env.BROKER_USERNAME,
    passcode: process.env.BROKER_PASSWORD,
    host: process.env.VHOST,
  },
  reconnectDelay: 5000,
  heartbeatIncoming: 4000,
  heartbeatOutgoing: 4000,
}

// Connect to broker
const client = new Client(clientSettings)

// Publish and consume messages
client.onConnect = () => {
  client.subscribe('/queue/test', message => {
    console.log(`${message.body}`)
  })
    
  client.publish({ 
    destination: '/queue/test', 
    body: 'Hello World !'
  })
}

// Error handling
client.onStompError = (frame) => {
  console.log('Broker reported error: ' + frame.headers['message'])
  console.log('Additional details: ' + frame.body)
}

client.onDisconnect = () => {
  console.log('Connection Terminated')
}

client.onWebSocketClose = (closeEevent) => {
  console.log('Websocket Terminated!!')
  console.log(`Reason: ${closeEevent.reason}`)
  console.log(`Code: ${closeEevent.code}`)
}

client.activate()

Note:

• Our servers have nginx in front of them, which performs TLS/SSL-termination. You can only connect over HTTPS; HTTP is not allowed.
• When connecting to CloudAMQP via STOMP over WebSockets, you should use a connection URL like: wss://hostname/ws/. For example: wss://blue-horse.rmq.cloudamqp.com/ws/

If you are interested in learning more about connecting browser-based applications to RabbitMQ, we encourage you to check out our 2-part series on RabbitMQ and Websockets.

For questions or any feedback, please feel free to contact support@cloudamqp.com.