Server Settings - WebSocket
Configure WebSocket server settings
Overview
The WebSocket Settings page configures ColdFusion's WebSocket server for real-time, bidirectional communication between the server and browser clients. WebSockets enable push notifications, live chat applications, real-time dashboards, collaborative editing, and other interactive features that require instant data updates without polling.
ColdFusion's WebSocket implementation provides a high-performance, scalable solution for real-time communication with built-in support for channels, message broadcasting, authentication, and SSL/TLS encryption.
WebSocket Configuration Settings
Configure server mode, ports, timeouts, and SSL settings for WebSocket communication.
Server Status
Enable WebSocket Server
Use WebSocket Proxy Port / Built-in WebSocket Server
Port
Enable SSL
port and sslEnabled) shipped in Adobe's official Docker image.SSL Port
sslport). Check your own Administrator.Connection Settings
Socket Timeout
Max Data Size
Start Flash Policy Server
SSL/TLS Settings
KeyStore File Location
C:\OpenSSL\bin\keystore.jks (Adobe's example)Keystore Password
Using WebSockets in CFML
Server-Side WebSocket Channel
Declare channels in Application.cfc with this.wschannels. Server-side logic goes in an optional channel listener CFC that extends CFIDE.websocket.ChannelListener and overrides methods such as allowSubscribe, allowPublish, beforePublish, canSendMessage, beforeSendMessage, and afterUnsubscribe. There are no onOpen, onMessage, or onClose server-side handlers.
// Application.cfc
component {
this.name = "wsDemo";
this.wschannels = [{name: "myChannel", cfclistener: "MyChannelListener"}];
}
// MyChannelListener.cfc
component extends="CFIDE.websocket.ChannelListener" {
// Decide whether a client may subscribe to the channel
public boolean function allowSubscribe(struct subscriberInfo) {
return true; // add your authorization check here
}
// Inspect or modify a message before it is published
public any function beforePublish(any message, struct publisherInfo) {
return arguments.message;
}
}<!--- MyChannelListener.cfc (declare the channel in Application.cfc with this.wschannels) --->
<cfcomponent extends="CFIDE.websocket.ChannelListener">
<cffunction name="allowSubscribe" returntype="boolean">
<cfargument name="subscriberInfo" type="struct">
<cfreturn true>
</cffunction>
<cffunction name="beforePublish" returntype="any">
<cfargument name="message" type="any">
<cfargument name="publisherInfo" type="struct">
<cfreturn arguments.message>
</cffunction>
</cfcomponent>Client-Side JavaScript
Clients connect through the cfwebsocket tag, which generates a JavaScript object with methods such as subscribe, publish, and invoke. A raw browser WebSocket pointed at a channel URL does not speak ColdFusion's channel protocol.
<!--- Creates a JavaScript object named ws and subscribes to myChannel --->
<cfwebsocket name="ws" onMessage="handleMessage" subscribeTo="myChannel">
<script>
// Called for every message the server sends to this client
function handleMessage(msg) {
console.log("Received:", msg);
}
// Publish a message to the channel from the browser
function sendHello() {
ws.publish("myChannel", "Hello Server!");
}
</script>Publishing Messages
Send messages to connected clients:
// Publish to all subscribers of a channel
wsPublish("myChannel", {
type: "notification",
message: "Server update",
timestamp: now()
});
// To target specific clients, use subscriber selectors or
// canSendMessage() in the channel listener<!--- Publish to all subscribers of a channel --->
<cfset wsPublish("myChannel", {
type: "notification",
message: "Server update",
timestamp: now()
})>
<!--- To target specific clients, use subscriber selectors or
canSendMessage() in the channel listener --->Managing Connections
Get information about active connections:
// Get all subscribers to a channel
subscribers = wsGetSubscribers("myChannel");
// Get all active channels
channels = wsGetAllChannels();<!--- Get all subscribers to a channel --->
<cfset subscribers = wsGetSubscribers("myChannel")>
<!--- Get all active channels --->
<cfset channels = wsGetAllChannels()>WebSocket Use Cases
Real-Time Notifications
- Push notifications to users instantly
- Alert users of system events or updates
- Notify users of new messages or activities
- Display real-time status updates
Live Chat Applications
- Instant messaging between users
- Customer support chat systems
- Group chat rooms and channels
- Typing indicators and presence detection
Real-Time Dashboards
- Live data visualization and charts
- System monitoring dashboards
- Stock tickers and financial data
- Social media feeds and analytics
Collaborative Applications
- Collaborative document editing
- Shared whiteboards and drawing tools
- Multi-user project management
- Real-time form collaboration
Gaming and Interactive Apps
- Multiplayer game synchronization
- Real-time scoring and leaderboards
- Live polling and voting
- Interactive quizzes and competitions
Best Practices
Production Configuration
- Enable SSL/TLS for WebSocket connections in production
- Use secure (WSS) protocol for sensitive data transmission
- Set reasonable timeout values to free up idle connections
- Monitor WebSocket server resource usage
- Implement connection authentication and authorization
Security
- Always use WSS (secure WebSockets) in production
- Implement authentication before allowing channel subscriptions
- Validate and sanitize all incoming messages
- Use channel-level access control
- Rate limit message sending to prevent abuse
- Log suspicious connection patterns
- Implement CSRF protection for WebSocket handshake
Performance
- Keep messages small and efficient
- Use JSON for structured data transmission
- Implement message batching for high-frequency updates
- Close unused connections promptly
- Monitor memory usage per connection
- Consider horizontal scaling for high traffic
Error Handling
- Implement automatic reconnection logic in clients
- Handle connection failures gracefully
- Provide fallback mechanisms (long polling, SSE)
- Log connection errors for debugging
- Display user-friendly connection status indicators
- Queue messages during temporary disconnections
Troubleshooting
WebSocket Server Won't Start
If the WebSocket server fails to start:
- Verify WebSocket is enabled in administrator
- Check configured port is not already in use
- Ensure firewall allows connections on WebSocket port
- Verify SSL keystore configuration if SSL is enabled
- Review coldfusion-out.log for startup errors
- Check file permissions on keystore file
Clients Cannot Connect
If clients fail to establish WebSocket connections:
- Verify WebSocket URL format (ws:// or wss://)
- Check correct hostname and port are specified
- Ensure firewall/load balancer allows WebSocket traffic
- Verify proxy servers support WebSocket protocol
- Check browser console for connection errors
- Test with simple WebSocket client tool
Connections Dropping Frequently
If WebSocket connections disconnect often:
- Increase connection timeout setting
- Implement heartbeat/ping-pong messages
- Check network stability and latency
- Verify proxy/load balancer timeout settings
- Review server resource usage (CPU, memory)
- Check for application errors closing connections
Messages Not Being Received
If messages aren't reaching clients:
- Verify channel names match the names declared in this.wschannels
- Check client is subscribed to correct channel
- Confirm connection is still active
- Review message size against configured limits
- Check for JavaScript errors in client code
- Test with simpler message formats
High Memory Usage
If WebSocket server uses excessive memory:
- Reduce the maximum data size if clients send large messages
- Implement connection cleanup for idle clients
- Review application for memory leaks
- Monitor number of active channels and subscribers
- Close unused connections programmatically
SSL/TLS Connection Failures
If secure WebSocket connections fail:
- Verify SSL certificate is valid and not expired
- Check keystore path and password are correct
- Ensure certificate matches server hostname
- Verify client and JVM TLS version compatibility
- Check for certificate chain issues
- Test with self-signed certificate first
Advanced Configuration
Load Balancing WebSockets
Scaling WebSocket connections across multiple servers:
- Configure sticky sessions on load balancer
- Use ColdFusion Enterprise WebSocket clustering for cross-server messaging
- Consider proxy mode (Use Proxy) so WebSocket traffic flows through the web server connector
- Implement session affinity based on connection ID
- Monitor connection distribution across servers
- Plan for graceful server shutdowns
Monitoring and Metrics
- Track active connection count
- Monitor message throughput (sent/received per second)
- Measure average connection duration
- Log connection failures and errors
- Alert on connection limit thresholds
- Track memory and CPU usage per connection
Authentication and Authorization
- Implement token-based authentication
- Validate user credentials before channel subscription
- Use session management for connection tracking
- Implement channel-level permissions
- Support OAuth or JWT for authentication
- Log authentication attempts and failures
Performance Tuning
Message Optimization
- Use compact JSON format for messages
- Implement message compression for large payloads
- Batch multiple updates into single messages
- Use binary format for non-text data
- Implement delta updates instead of full objects