Qore WebSocketHandler Module Reference  1.5.3
WebSocketHandler::WebSocketHandler Class Reference

the main web socket handler class More...

Inheritance diagram for WebSocketHandler::WebSocketHandler:

Public Member Methods

 constructor (*HttpServer::AbstractAuthenticator auth, *hash< auto > opts)
 create the object optionally with the given AbstractAuthenticator More...
 
 deregisterConnectionImpl (WebSocketConnection wsc)
 called when the connection terminates; the default implementation does nothing
 
WebSocketConnection doNewConnection (hash< auto > cx, hash< auto > hdr, string cid)
 called when a connection is established; registers the new connection internally
 
bool flushIo (WebSocketConnection wsc, Socket sock)
 Flushes I/O in the connection queue. More...
 
*list< stringgetConnectionIds ()
 get list of socket connection ids
 
WebSocketConnection getConnectionImpl (hash< auto > cx, hash< auto > hdr, string cid)
 called when a connection is established; the default implementation creates a WebSocketConnection object
 
int getHeartbeat ()
 returns the connection heartbeat interval as a number of seconds More...
 
string getHeartbeatMessage ()
 returns the heartbeat message as a string More...
 
hash< auto > handleRequest (hash< auto > cx, hash< auto > hdr, *data b)
 called by the HTTP server to handle incoming HTTP requests More...
 
 logDebug (string fmt)
 default implementation is empty
 
 logError (string fmt)
 default implementation is empty
 
 logInfo (string fmt)
 default implementation is empty
 
 sendAll (data d)
 sends a message to all connected clients More...
 
 sendOne (softstring id, data d)
 sends a message to the given connection ID More...
 
 setHeartbeat (softint seconds)
 sets the heartbeat interval as a number of seconds More...
 
 setHeartbeatMessage (string msg)
 sets the heartbeat message More...
 
 startImpl (softstring lid, hash< auto > cx, hash< auto > hdr, Qore::Socket sock)
 called from the HTTP server after the handleRequest() method indicates that a dedicated connection should be established More...
 
 stopOne (softstring id)
 stop given connection ID
 

Public Attributes

const DefaultHeartbeatInterval = 20s
 default heartbeat interval
 
const DefaultHeartbeatMsg = "heartbeat"
 default heartbeat message
 
const DefaultSocketSendTimeout = 30s
 default socket send timeout
 
const Options = ...
 known constructor options
 

Private Member Methods

RWLock rwl ()
 connection read-write lock
 

Private Attributes

hash< string, WebSocketConnectionch
 connection hash
 
softint heartbeat = DefaultHeartbeatInterval
 heartbeat interval in seconds
 
string heartbeat_msg = DefaultHeartbeatMsg
 heartbeat message
 

Private:Internal Attributes

string tlk = get_random_string(50)
 Thread-local key for I/O check.
 

Detailed Description

the main web socket handler class

connections are represented by object descended from WebSocketConnection. WebSocketHandler::WebSocketHandler::getConnectionImpl() returns a suitable object for each connection, this method can be overridden in subclasses to return a custom object for each connection if required.

Receiving WebSocket Messages from Clients
When the WebSocketHandler class receives a message from the client, the WebSocketHandler class calls the WebSocketConnection::gotMessage() on the object that represents that connection.
Sending WebSocket Message to Clients
To send a message to a websocket client, call one of the following methods:

Websocket connections are identified by their HTTP connection ID as passed in WebSocketHandler::handleRequest() in the "cx.id" argument when the connection is first established.

Member Function Documentation

◆ constructor()

WebSocketHandler::WebSocketHandler::constructor ( *HttpServer::AbstractAuthenticator  auth,
*hash< auto >  opts 
)

create the object optionally with the given AbstractAuthenticator

Parameters
auththe authentication object to use to authenticate connections (see AbstractAuthenticator); if no AbstractAuthenticator object is passed, then by default no authentication will be required
optsoptions for the object with the following optional keys:
  • heartbeat: a positive integer value giving seconds for the heartbeat interval for the server connection (default: 20 seconds)
  • heartbeat_msg: a string giving the payload to send in heartbeat messages (default: "heartbeat"); may be an empty string meaning no message
Exceptions
WEBSOCKETHANDLER-OPTION-ERRORunknown or invalid option

◆ flushIo()

bool WebSocketHandler::WebSocketHandler::flushIo ( WebSocketConnection  wsc,
Socket  sock 
)

Flushes I/O in the connection queue.

Returns
True if any data was flushed, False if not

◆ getHeartbeat()

int WebSocketHandler::WebSocketHandler::getHeartbeat ( )

returns the connection heartbeat interval as a number of seconds

Returns
the connection heartbeat interval as a number of seconds
Since
WebSocketHandler 1.4.2

◆ getHeartbeatMessage()

string WebSocketHandler::WebSocketHandler::getHeartbeatMessage ( )

returns the heartbeat message as a string

Returns
the heartbeat message as a string; an empty string means no message
Since
WebSocketHandler 1.4.2

◆ handleRequest()

hash<auto> WebSocketHandler::WebSocketHandler::handleRequest ( hash< auto >  cx,
hash< auto >  hdr,
*data  b 
)

called by the HTTP server to handle incoming HTTP requests

To accept a dedicated connection; make sure the return value hash's "code" key is 101 (i.e. "Switching Protocols") and the "close" key is not False

Parameters
cxcall context hash; this hash will have the following keys:
  • socket: the bind address used to bind the listener ("socket-info" provides more detailed information)
  • socket-info: a hash of socket information for the listening socket (as returned by Qore::Socket::getSocketInfo())
  • peer-info: a hash of socket information for the remote socket (as returned by Qore::Socket::getPeerInfo())
  • url: a hash of broken-down URL information (as returned from parseURL())
  • id: the unique HTTP connection ID; this ID is also used to identify the websocket client connection in WebSocketHandler::sendOne()
  • listener-id: the HTTP server listener ID (see HttpServer::HttpServer::getListenerInfo() )
  • user: the current RBAC username (if any)
hdrincoming header hash; all keys will be converted to lower-case, additionally the following keys will be present:
  • method: the HTTP method received (ie "GET", "POST", etc)
  • path: the HTTP path given in the request, after processing by decode_url() (Qore function)
  • http_version: the HTTP version number in the request (either "1.0" or "1.1")
bmessage body, if any
Returns
a hash representing the response to the client as follows; to accept a dedicated connection; make sure the "code" is 101 (ie "Switching Protocols") and the "close" key is not False:
  • "code": the HTTP return code (see HttpServer::HttpCodes) (101 "Switching Protocols" to accept the dedicated connection, in which case the start() method will be called)
  • "body": the message body to return in the response
  • "close": (optional) set this key to True if the connection should be unconditionally closed when the handler returns
  • "hdr": (optional) set this key to a hash of extra header information to be returned with the response

Websocket connections are identified by their HTTP connection ID as passed in "cx.id"

◆ sendAll()

WebSocketHandler::WebSocketHandler::sendAll ( data  d)

sends a message to all connected clients

Messages are automatically encoded with WebSocketUtil::ws_encode_message() before sending.

◆ sendOne()

WebSocketHandler::WebSocketHandler::sendOne ( softstring  id,
data  d 
)

sends a message to the given connection ID

Websocket connections are identified by their HTTP connection ID as passed in WebSocketHandler::handleRequest() in the "cx.id" argument when the connection is first established.

Messages are automatically encoded with WebSocketUtil::ws_encode_message() before sending.

◆ setHeartbeat()

WebSocketHandler::WebSocketHandler::setHeartbeat ( softint  seconds)

sets the heartbeat interval as a number of seconds

Parameters
secondsthe heartbeat interval as a number of seconds
Since
WebSocketHandler 1.4.2

◆ setHeartbeatMessage()

WebSocketHandler::WebSocketHandler::setHeartbeatMessage ( string  msg)

sets the heartbeat message

Parameters
msgthe string payload to send with heartbeat messages; an empty string means no message
Since
WebSocketHandler 1.4.2

◆ startImpl()

WebSocketHandler::WebSocketHandler::startImpl ( softstring  lid,
hash< auto >  cx,
hash< auto >  hdr,
Qore::Socket  sock 
)

called from the HTTP server after the handleRequest() method indicates that a dedicated connection should be established

This method should not return until the connection is closed or the stop() method is called

Parameters
lidthe unique HTTP listener ID
cxcall context hash; this hash will have the following keys:
  • socket: the bind address used to bind the listener ("socket-info" provides more detailed information)
  • socket-info: a hash of socket information for the listening socket (as returned by Qore::Socket::getSocketInfo())
  • peer-info: a hash of socket information for the remote socket (as returned by Qore::Socket::getPeerInfo())
  • url: a hash of broken-down URL information (as returned from parseURL())
  • id: the unique HTTP connection ID
  • listener-id: the HTTP server listener ID (see HttpServer::HttpServer::getListenerInfo())
  • user: the current RBAC username (if any)
hdra hash of headers in the request
sockthe Socket object for the dedicated connection to the client