Introducing the SocketBox STOMP Broker (Demo), for ColdFusion (CFML) and BoxLang Developers!

You may have seen our recent announcement about SocketBox, a new WebSocket functionality built into CommandBox’s latest 6.1-rc builds and the latest snapshots of the BoxLang MiniServer. We recommend reading that post first if you haven’t heard about SocketBox yet.

We’ve been working on a fun new library to make WebSockets easier for CFML (and BoxLang) developers. WebSockets are incredibly powerful for real-time applications, but CF developers have historically lagged behind other languages in adopting this technology. With SocketBox, we’re addressing this gap by providing a solution that is easy to implement, much like Socket.io for Node.js apps.

Get Started

Overcoming Challenges in WebSocket Integration

Traditionally, CF’s deployment to a servlet makes it challenging for libraries to modify the behavior of HTTP listeners. SocketBox overcomes this limitation by offering basic WebSocket connection management and low-level messaging capabilities to build upon.

Introducing STOMP Protocol Support

As of today, we’ve taken SocketBox a step further by adding support for the STOMP (Simple Text Oriented Messaging Protocol) broker. This addition brings several powerful features on top of basic WebSocket functionality:

• Message format/serialization
• Authentication/authorization
• Topics and message routing
• Subscriptions to a topic
• Sending messages to a destination
• Automatic client reconnect
• Heartbeat messages to detect dead connections

Implementing STOMP in Your Application

To use STOMP WebSocket support, you’ll extend the modules.socketbox.models.WebSocketSTOMP class in your WebSocket.cfc. This class builds on the functionality of the WebSocketCore class and adds methods you can override for custom behavior:

Key Methods

• configure(): Configure the STOMP broker via a struct returned by this method.
• authenticate(required string login, required string passcode, string host, required channel): Custom authentication logic for accepting or denying STOMP connect requests.
• authorize(required string login, required string exchange, required string destination, required string access, required channel): Custom authorization logic for managing subscriptions and publishing to destinations.

Sending and Receiving Messages

Messages can be sent from a WebSocket connection using a Stomp.js library or directly from the server-side, like this:

new WebSocket().send('my-destination', "my message");

Client-side JavaScript or server-side CF code can receive messages. For example:

function configure() {
    return {
        "subscriptions": {
            "ping": (message) => {
                send("pong-destination", "Ping Pong!");
            },
            "generate-new-sales-data": (message) => {
                salesService.generate();
                send("sales-data-updated", "New sales data available as of #now()#");
            }
        }
    };
}

Leveraging STOMP Routing with Exchanges

STOMP introduces a robust routing system using exchanges. Messages are sent to an exchange, which determines their routing. This flexibility allows for messages to be sent to multiple destinations or none at all.

Exchange Types

1. Direct: Routes messages directly to the destination matching their header.
2. Topic: Supports wildcard subscriptions (e.g., foo.bar.baz).
3. Fanout: Sends messages to all bindings simultaneously.
4. Distribution: Routes messages to a single destination using algorithms like random or roundrobin.

Security Features

STOMP supports:

• Authentication: Validates connection requests using user credentials, session variables, or JWTs.
• Authorization: Ensures users have the proper permissions to subscribe or publish to exchanges and destinations.

Try It Yourself

We’ve published a full demo of STOMP functionality deployed on Render.com and running on the BoxLang MiniServer Docker container. This demo also works on Lucee and Adobe CF when deployed on CommandBox 6.1-rc builds with WebSockets enabled.

Get Started

Source Code

Explore the fully documented source code here: GitHub - SocketBox STOMP Demo

Conclusion

SocketBox with STOMP protocol support brings robust WebSocket capabilities to CFML and BoxLang developers, empowering them to build secure, real-time applications with ease Dive into the documentation on ForgeBox and start experimenting with these powerful new tools!