What is the Websocket Client on the Lucee downloads page

I just noticed a new “Websocket Client” extension on the Lucee Downloads page: https://download.lucee.org/ (under the extensions). I think this is the github repo: GitHub - lucee/extension-websocket-client, but I don’t see any documentation.

Does anyone have any information about this extension?

@isapir built an extension named “Lucee WebSockets Extension”, which I am currently using, but there are some critical issues with it that make it unstable, and I don’t believe it is actively being supported at this time.

It looks like the new extension (if I have the github repo correct) is being developed by Michael Offner (can someone tag him… I don’t know his handle).

Thanks!

To clarify, my extension implements a WebSocket Server, for when you want to connect from a Client, e.g. a web browser with JavaScript code, to Lucee.

The one mentioned here is a Client, for when you want to connect from Lucee to another WebSocket Server.

I admit, that’s confusing. Why would Lucee be implementing a websocket client? I have seen the word “client” reference various server-side things, and I actually thought that you referenced the word “client” in your implementation, but I guess I’m wrong about that.

I have mentioned a Client in my extension as a possible future enhancement.

A WebSocket Client can be very useful if for example you want to connect to another server and keep the connection open for efficient communications. Instead of opening a new connection each time you keep the connection open and send and receive messages without any overhead.

I see, so this new extension would be used to connect your Lucee app to another backend server (not a Lucee server) via websockets. That’s pretty cool.

Are there any working examples of this or any other extension working? I need just a client.

The new websocket extension, latest snapshot 1.0.0.13-SNAPSHOT was just released with support for jakarta, aka Tomcat 10+

https://luceeserver.atlassian.net/browse/LDEV-5385

@webonix did a live presentation at CFCAMP 2024

https://www.cfcamp.org/resource/getting-started-with-lucee-6-websockets.html

(login required to view)

3 Likes

Looking forward to getting this working. @Zackster, the Lucee docs page you referenced is broken. Looks like it’s missing an /pre or another end tag.

ok, that should be better now, was a problem with a regex and some tech debt with our syntax highlighter

For now we override Docker and yml, let me know if any other pages have issues

https://luceeserver.atlassian.net/browse/LD-168

1 Like

So is this effectively a websocket lucee gateway client (aka incoming websocket)?

Kind of like streaming webhook?

Lucee 6.x only? And is this production ready or still in dev? Thinking maybe a http server interface for lucee on websocket server might be more stable.

@Zackster documentation is fixed, thank you.

What’s missing in the docs is any mention of accessing the user’s session scope, or the application scope. This was a difference with Lucee 5x and the old websocket extension because the scopes were passed into the websocket methods as arguments, therefore you could not lock a scope or leverage existing code that referenced these scopes.

So for example, if I need to get a value that’s stored in my application’s config, I might want to use some existing code like application.helper.getAppDSN() which would then return application.config.dsn. But this wouldn’t work because the application scope didn’t exist. As a result, I wrote a lot of duplicate code that referenced these scopes as arguments.

I’m assuming and hoping that this has all changed and those scopes do in fact exist. Can you confirm?

The documentation is being worked upon, it is a community based effort, and if you feel something is missing and can contribute to it, please do.

Otherwise, I can understand documentation at present needs some refinement and its something I plan on adding to the documentation.

There is this

Then there is this:

I’m not sure @micstriit and @webonix worked on this new version

The video I linked above goes into great detail, time to FAFO and then help improve the docs?

As for Lucee 5 support, does it show up in the admin?

The extension indicates it does, but you should be upgrading anyway :slight_smile:

@Zackster - I cannot access that video from CFCamp. Even when I’m logged in, there’s nothing on the page except for the title. Other than the Lucee documentation, which is far from complete, I cannot find any code examples or information on how use websockets in Lucee 6.

@micstriit @webonix - Can you please post some example code or at least a stub of a websocket component in the docs? There’s only a couple tiny snippets of the onOpen() method, which doesn’t provide much information. Thank you in advance!!! :slight_smile:

A couple points that are not explained… the documentation indicates that the websocket components are automatically discovered on Lucee startup in the {lucee-config}/websockets/ folder, but this is not where an application will want to put their app-specific code. The documentation doesn’t say anything about locating your websocket components in your application’s directory structure.

In addition, there is very little information about what a websocket component API looks like. Other than listing the expected methods, we don’t know the argument types, what they are, or what is the expected to be returned (if anything).

Finally, I previously had @isapir’s websocket extension installed and working in Lucee 5. The new extension shares the same UUID as the old one, which is confusing because these are two completely different websocket implementations and are not compatible at all. You cannot upgrade and expect anything to work. Perhaps they should have separate IDs so they remain independent from one another? When viewing the new websocket extension in the Lucee admin, it indicates that I can install the old version (v2.x) but trust me, nobody should do this in Lucee 6. It will not work. I had to remove old (v2.x) websocket dependencies from Tomcat and remove the config info from server.xml before I could get a clean install of the new websocket extension. Now my websockets are completely broken and I have no idea how to refactor.

1 Like

I was able to get cfcamp to make the following video public that was referenced above:

https://www.cfcamp.org/resource/getting-started-with-lucee-6-websockets.html

This video does provide a high-level overview of the new websocket extension, but there is are still many issues that were not discussed or documented. For example:

  1. Where do you physically locate your websocket components so they are within your application directory structure? From what I can tell from the documentation, websocket components need to reside in the {lucee-config}/websockets/ folder.

  2. How do you access your application and session scopes from within the websocket methods in your component? The old websocket extension passed these scopes into your endpoints, but that is less than ideal if you are trying to use existing code that accesses these scopes like session.userID or application.helper.getDSN()

  3. Is it possible to pass data to your endpoints via the path, for example: wss://myap.com/ws/user/{userid}/ or wss://myap.com/ws/thread/{threadid}/ - This was supported in the old extension. If it’s not supported, how would you accomplish the same thing?

  4. In the old websocket extension, we were required to register our endpoints with a corresponding handler. Is this no longer a required? Is there any initialization code that is required? How do you re-initialize your components as you develop them? Do we have to restart the server each time, or is there a way to cycle through code changes without forcing a server restart?

Finally, according to the video, the websocket extension’s repo is here:

…although the last commit was 8 years ago, so I’m not sure how correct this is.

1 Like

Here’s some example code from that presentation

The extension source is here

There is an outstanding bug with the latest snapshot, I’ll post here once it’s resolved.

https://luceeserver.atlassian.net/browse/LDEV-5385

Thank you @Zackster.

Sample Code - Lucee Lucee 6.1.0.193-RC` and Websockets 1.0.0.11-SNAPSHOT

This is from the sample code repo (referenced above): GitHub - webonix/Lucee-websocket-commandbox: Sample Scripts for Lucee WebSocket Extension running on CommandBox

I got this build and run, but it doesn’t work. I realize this is old code, but it seems to be loading everything as it was originally written. It’s running Lucee 6.1.0.193-RC and websocket extension version 1.0.0.11-SNAPSHOT.

This codebase doesn’t seem like it’s going to help.

When I try to open a websocket endpoint by clicking on the first button, I get an error, but the js socket.onerror() code generates an exception on event.data because event.data doesn’t exist. When viewing websocketInfo(), there are no items in the instances array.

It looks like the test.cfc and test2.cfc are being registered, although the log messages aren’t super clear on that. It doesn’t show the component name or endpoint, so I don’t really know. I don’t see any errors in the websocket.log file.

My Current Configuration - Lucee 6.2.0.321 and Websockets 3.0.0.14-RC

I’m currently using the latest Lucee 6 release and the most recent websockets extension. For context, I’m on Windows 11 and my Lucee 6 install directory is C:\lucee6\

My first step is to get a very simple websocket endpoint to connect and send a message so I can begin to figure out how this new extension works. When viewing WebsocketInfo()

image

Just to start out, I put a simple echo.cfc component in the C:\lucee6\tomcat\lucee-server\context\websockets directory. I cannot connect to the endpoint ws://mysite/ws/echo, and I cannot find any logging associated with it.

Questions:

  1. Where should the websocket log file be located? I assume it should be in C:\lucee6\tomcat\lucee-server\context\logs\
  2. How does the extension map an endpoint to my components? I can’t find any information on mapping or configuring endpoints. Do I need a url rewrite that maps ws://mysite/ws/echo to somewhere? If so, where?
  3. Do all applications share the same websocket config? How can I locate my websocket components in my application directory structure?

@Redtopia – it looks like the websocket extension is not finding the CFCs – otherwise you would see them in the instances node of the cfdump. This has been one of the issues noted in the current bug they are tracking down, but it could also be that your CFCs aren’t in the correct location. Make sure you place them in the c:\lucee6\tomcat\lucee-server\context\websockets\ directory on your PC (based on your screenshot above)

As far as your questions:

  1. The websocket log will be in the logs directory that you noted IF you tell lucee to log to that file. You either need to set it in the Lucee admin, or add a directive in the .CFconfig to log to the seprate file. By default, it throws the logs in the application.log.
  2. The ws://server/ws/ part is hard-coded. Anything after that is based on the name of the CFC you have in that websockets folder. For example, if you have a file c:\lucee6\tomcat\lucee-server\context\websockets\test1.cfc, that will translate to ws://localhost/ws/test1 . Depending on your web server, you may need to have to make sure you map that folder to Tomcat – but Tomcat should pick it up from there on its one (the websocket extension has configuration it loads into Tomcat to map that ws folder for you)
  3. Yes. The websocket components are specific to the server, not the application, so they would normally live outside your application folder. If you want to include them, you can change the websocket.json file to point to it – but it would only be one websocket extension per server.

@quetwo - Thank you for all of this. I do have my websocket echo.cfc component in that folder, but it’s obviously not picking it up, even after restarts.

Seems that the extension currently has some significant limitations, especially having to do with where your .cfc files need to be located as well as the hard coded endpoint.

What if I need to pass an identifier to the websocket, like a thread_id for a thread of messages? Normally that might look like: ws://site.com/ws/thread/{thread_id}/. Do you know if there’s a way to do this?

As buggy as the old websocket extension was, it did allow you to locate your endpoint handlers in your application directory structure, and it allowed you to specify ID placeholders in your endpoints. There were no conflicts with other apps on the server because all the components were separate (not a dealbreaker for production, but problematic for dev setups)

And finally, can you access your scopes (session and application) from inside your component methods?