BoxLang 🚀 A New JVM Dynamic Language Learn More...
WebSocket Listener library to be used with CommandBox Websocket and BoxLang WebSocket server.
The WebSocket server in CommandBox and BoxLang MiniServer is not really a separate "server" per se, since it’s on the same port. It’s just an upgrade listener which will upgrade any WS requests.
This websocket integration will work for Lucee, Adobe, and BoxLang alike as it passes incoming messages to the app via an "internal" HTTP request to /WebSocket.cfc?method=onProcess
where the CF/BL code can handle it. The incoming request will have all cookies, headers, hostname, etc that the original websocket connection was started with, so normal CGI variables and session scopes should work fine.
You need to create a custom /WebSocket.cfc
class should extend the modules.socketbox.models.WebSocketCore
class in this library which provides the base functionality.
The BoxLang Miniserver doesn't have any configuration ATM. It uses the defaults.
CommandBox allows for the following config:
web.websocket.enable
and for an individual site under sites.mySite.websocket.enable
. true
/false
/ws
so if your site is foobar.com
then your JS code in the browser will connect to foobar.com/ws
. Configure under web.websocket.uri
for all sites and for an individual site under sites.mySite.websocket.uri
. You can use the root URI of /
but you may have issues setting up websocket proxying if you have a web server in front./WebSocket.cfc
in the web root, Configure for all sites with web.websocket.listener
and for an individual site under sites.mySite.websocket.listener
.#Usage
Methods you can override in your custom /WebSocket.cfc
are:
onConnect( required channel )
- called for every new remote connectiononClose( required channel )
- called every time a connection is closedonMessage( required message, required channel )
- called every time an incoming message is received. The message will be a string.Other methods inherited from the the WebSocketCore.cfc
you can use.
sendMessage( required message, required channel )
- Send a string message to a specific channelbroadcastMessage( required message )
- Send a string message to every connected channelgetAllConnections()
- Returns an array of all channels representing every remote connection to the server.None of these methods return any values. If you, for instance, want to reply back to a websocket message with another message, you can re-use the channel like so:
function onMessage( required message, required channel ) {
if( message EQ "Ping" ) {
sendMessage( "Pong", arguments.channel );
}
}
There are no topic or subscription semantics right now. The base library just provides the bare minimum to send and receive messages. You can build whatever you want on top of this. We’ll probably add something like STOMP on top of this in the future.
$
box install socketbox