the main web socket handler class More...

Inheritance diagram for WebSocketHandler::WebSocketHandler:

[legend]

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< string >	getConnectionIds ()
	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, WebSocketConnection >	ch
	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:

WebSocketHandler::sendOne(): send a message to single connection given its connection ID
WebSocketHandler::sendAll(): send a message to all connected clients

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

auth	the authentication object to use to authenticate connections (see AbstractAuthenticator); if no AbstractAuthenticator object is passed, then by default no authentication will be required
opts	options 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-ERROR unknown 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

cx	call 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)
hdr	incoming 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"`)
b	message 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

seconds the heartbeat interval as a number of seconds

Since: WebSocketHandler 1.4.2

◆ setHeartbeatMessage()

WebSocketHandler::WebSocketHandler::setHeartbeatMessage ( string msg )

sets the heartbeat message

Parameters

msg	the 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

lid	the unique HTTP listener ID
cx	call 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)
hdr	a hash of headers in the request
sock	the Socket object for the dedicated connection to the client

Public Member Methods

Public Attributes

Private Member Methods

Private Attributes

Private:Internal Attributes

Detailed Description

Member Function Documentation

◆ constructor()

◆ flushIo()

◆ getHeartbeat()

◆ getHeartbeatMessage()

◆ handleRequest()

◆ sendAll()

◆ sendOne()

◆ setHeartbeat()

◆ setHeartbeatMessage()

◆ startImpl()