Lucee websockets for clustered environments extension using Redis PubSub

I have created an extension that allows you to use the Lucee websocket extension in a clustered environment using Redis PubSub. It is still a work in progress and is being released as beta for now until further testing is done but I wanted to get it out there for others to see and make improvements where they see fit.
I am just learning Java so there is probably a lot of room for improvement.

You can download the extension LEX file under the release tab in Github. To install the extension go to either the server or web Lucee administration pages and under the Extension -> Applications page towards the bottom there is a section for uploading a new extension. Just drop in the LEX file and click upload.

You will then need to head over to the Lucee web administration page for the host you are going to be using the extension for. Under the Services -> Event Gateway page you will want to create a new gateway instance using the Type “Lucee Redis Pub/Sub Gateway”. The Listener Component field is a relative path to your webroot where you will place a listener component CFC that will perform actions when a new message is published. The listener component should look something like this (it must implement the method onIncomingMessage(channel, data)):

component {

	public any function onIncomingMessage(channel, data) {


Your Lucee instance should now be subscribed to the channel you provided in the gateway instance configuration.

To test the Event Gateway go to a test file and add the following (change the first argument to the ID of the event gateway you created inside of the Lucee web admin):

sendGatewayMessage('test', {message:'Hello World!'})

The listener component that you created earlier with the onIncomingMessage method should receive the message you just sent. This is where you would broadcast it to all the subscribers on the websocket channel.

Make sure to follow the steps above for each additional Lucee instance you have in the cluster. After sending a message from one of the cluster instances the rest of the instances should receive the exact same message. I will be posting a video in the near future showing step by step how to setup and use the extension. I hope other people find this extension useful and I look forward to improving it.

Did you ever complete getting this fully implemented and building out an extension? The Git library shows three issues that implies these goals are not complete.

@John_Farrar I did get it built out as an extension, you can see it under the release section on Github. I created those issues myself as a kind of “To Do” list. I have been using the extension for a couple months now without any issues. I plan on revisiting this extension soon and improving it but I have been very busy with other projects.

Great to hear. I am focused on prep for Into The Box myself ATM. :slight_smile:

@Yamaha32088 Did you see that Lucee extensions can now be added to ForgeBox so any one in the community can easily install it without needing to deal with lex file manually? They just add as an ext provider and then it shows up.

Let me know if you want more info on that. I haven’t gotten a chance to publish a guide yet, but it’s pretty simple.

@bdw429s yes if you could provide more info that would be great. I will see if I can polish the extension up a bit and hopefully get it added to Forgebox.

In order to publish you extension (or any other package for that matter) to ForgeBox you just need three things

  1. A forgebox account (use forgebox register if you don’t have one)
  2. A box.json with the correct metadata in your package.
  3. Run the publish command from that folder.

A new package will be created if it doesn’t exist, otherwise it will be updated. A new version will also be created if it doesn’t exist matching the version in your box.json or it will be updated. Here’s our generic docs on the idea of creating and publishing packages:

So for your extension, you’ll want:

  • The slug property in your box.json to be the unique name of your ext from your manifest file. Micha usually recommends this to be a GUID, but I hate the readability of that and from what I can tell, Lucee doesn’t actually care what the string is so far as it is unique. But regardless, it needs to match what’s in your manifest or updates won’t work.
  • The version needs to be the current version of your package that you want to publish. To add a new version, you’ll just update the json and re-run the publish command. One thing to watch out for is that Lucee likes to use the x.y.z.q version format which does not quite match the npm-style x.y.z-prerelease+build format of ForgeBox. I usually stick with just three digits x.y.z so it’s compatible across the board.
  • You want the type property in your json to be lucee-extensions
  • Set your thumbnail URL in a thumbnail property in the json
  • The actual download URL of the lex file needs to be set in the location property in the json. Please note Lucee has some bugs where it doesn’t like servers that don’t set the right content type that it expects. Someone else I was helping had to rename it to a zip file on GitHub so get Lucee to accept it. I have a ticket in for Lucee for this bug.
  • Fill out any other info like name, author, etc
  • The publish command will pick up any file in your current directory and will put it on ForgeBox as the description. This is very handy so make sure you have a good readme so your package home looks good. If you want to update it, simply edit the readme file and re-run the publish command at any time.

Here is the box.json file I used when I published the Ortus Couchbase Extension.

	"name":"Ortus Couchbase Cache",
	"author":"Brad Wood",
	"description":"A Lucee caching extension allow you to connect to a Couchbase Cluster for caching, session, and client storage",

I finally just put this in the docs. I added some additional information that I didn’t include here. Please send over a pull for anything I missed.

This link in the docs is now…