ServerSentEventHandler::ServerSentEventHandler Class Reference

the main web socket handler class More...

#include <ServerSentEventHandler.qc.dox.h>

Inheritance diagram for ServerSentEventHandler::ServerSentEventHandler:

Public Member Functions
	connectionRegisteredImpl (ServerSentEventConnection conn)
	Called when the connection is registered; the default implementation does nothing.
	constructor (*HttpServer::AbstractAuthenticator auth, *hash< auto > opts)
	Create the object optionally with the given AbstractAuthenticator.
	constructor (hash< auto > opts)
	Create the object optionally with the given optiond.
	deregisterConnectionImpl (ServerSentEventConnection conn)
	Called when the connection terminates; the default implementation does nothing.
ServerSentEventConnection	doNewConnection (Socket sock, hash< auto > cx, hash< auto > hdr, string cid)
	Called when a connection is established; registers the new connection internally.
string	encodeMessage (hash< SseMessageInfo > msg)
	Encode a message for sending.
bool	flushIo (ServerSentEventConnection conn, Socket sock)
	Flushes I/O in the connection queue.
*list< string >	getConnectionIds ()
	get list of socket connection ids
ServerSentEventConnection	getConnectionImpl (Socket sock, hash< auto > cx, hash< auto > hdr, string cid)
	Called when a connection is established; the default implementation creates a ServerSentEventConnection object.
int	getHeartbeat (ServerSentEventConnection conn)
	returns the connection heartbeat interval as a number of seconds
hash< HttpResponseInfo >	handleRequest (hash< auto > cx, hash< auto > hdr, *data b)
	called by the HTTP server to handle incoming HTTP requests
	logDebug (string fmt,...)
	Log to the logger.
	logError (string fmt,...)
	Log to the logger.
	logInfo (string fmt,...)
	Log to the logger.
	logWarn (string fmt,...)
	Log to the logger.
	sendAll (hash< SseMessageInfo > msg)
	sends a message to all connected clients
	sendOne (softstring id, hash< SseMessageInfo > msg)
	sends a message to the given connection ID
	setHeartbeat (date seconds)
	sets the heartbeat interval as a number of seconds
	setHeartbeat (softint seconds)
	sets the heartbeat interval as a number of seconds
bool	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.
	stopOne (softstring id)
	stop given connection ID

Static Public Member Functions
static string	serializeDefault (auto v)
	Default value serialization.
static string	serializeJson (auto v)
	JSON value serialization.

Public Attributes
const	DataSerializationSupport = ...
	Data serialization support.
const	DefaultHeartbeatInterval = 20
	default heartbeat interval in seconds
const	DefaultHeartbeatMsg = ":hb\n\n"
	default heartbeat message; this is a short comment to be used as a heartbeat message
const	DefaultSocketSendTimeout = 30s
	default socket send timeout
const	Options = ...
	known constructor options
const	SseResponseHeader = ...
	Response header to SSE requests.

Protected Member Functions
	constructorInit (*hash< auto > opts)
	Common constructor initialization.
string	getHeartbeatMessage (ServerSentEventConnection conn)
	Returns the heartbeat message to send.
	registerNewConnectionIntern (string cid, ServerSentEventConnection conn)
	Called while holding the write lock to register the new connection.
	removeConnectionLocked (string cid)
	Called when a connection is removed from the connection map.
	replayEventsSince (ServerSentEventConnection conn, auto id)
	Resend all events since the given event.
RWLock	rwl ()
	connection read-write lock
	sendHeartbeatMsg (ServerSentEventConnection conn, Socket sock)
	Send the default heartbeat message.

Protected Attributes
hash< string, ServerSentEventConnection >	ch
	connection hash
int	heartbeat = DefaultHeartbeatInterval
	heartbeat interval in seconds
string	heartbeat_msg = DefaultHeartbeatMsg
	heartbeat message returned by getHeartbeatMessage()
string	serialization
	The value of the serialization option.
code	serializer
	Value serialization code.

Private 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 ServerSentEventConnection. ServerSentEventHandler::ServerSentEventHandler::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.

Sending ServerSentEvent Message to Clients

To send a message to an HTTP client, call one of the following methods:

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

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

Member Function Documentation

constructor()

ServerSentEventHandler::ServerSentEventHandler::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) logger: a LoggerInterface object for logging

Exceptions

SERVERSENTEVENTHANDLER-OPTION-ERROR

unknown or invalid option

flushIo()

bool ServerSentEventHandler::ServerSentEventHandler::flushIo	(	ServerSentEventConnection	conn,
		Socket	sock )

Flushes I/O in the connection queue.

Returns

True if any data was flushed, False if not

getHeartbeat()

int ServerSentEventHandler::ServerSentEventHandler::getHeartbeat

(

ServerSentEventConnection

conn

)

returns the connection heartbeat interval as a number of seconds

Returns

the connection heartbeat interval as a number of seconds

handleRequest()

hash< HttpResponseInfo > ServerSentEventHandler::ServerSentEventHandler::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 HTTP client connection in ServerSentEventHandler::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") or the Content-Type headers is set to text/event-stream, 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
• "hdr": (optional) set this key to a hash of extra header information to be returned with the response

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

sendAll()

ServerSentEventHandler::ServerSentEventHandler::sendAll

(

hash< SseMessageInfo >

msg

)

sends a message to all connected clients

Parameters

d	the data to send

Messages are automatically encoded with ServerSentEventUtil::ws_encode_message() before sending

sendOne()

ServerSentEventHandler::ServerSentEventHandler::sendOne	(	softstring	id,
		hash< SseMessageInfo >	msg )

sends a message to the given connection ID

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

Messages are automatically encoded with ServerSentEventUtil::ws_encode_message() before sending

setHeartbeat() [1/2]

ServerSentEventHandler::ServerSentEventHandler::setHeartbeat

(

date

seconds

)

sets the heartbeat interval as a number of seconds

Parameters

seconds

the heartbeat interval as a number of seconds

setHeartbeat() [2/2]

ServerSentEventHandler::ServerSentEventHandler::setHeartbeat

(

softint

seconds

)

sets the heartbeat interval as a number of seconds

Parameters

seconds

the heartbeat interval as a number of seconds

startImpl()

bool ServerSentEventHandler::ServerSentEventHandler::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