Qore ServerSentEventHandler Module Reference 1.0.1
Loading...
Searching...
No Matches
ServerSentEventHandler::ServerSentEventHandler Class Reference

the main web socket handler class More...

#include <ServerSentEventHandler.qc.dox.h>

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 ()
 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.
 
 registerNewConnectionIntern (string cid, ServerSentEventConnection rv)
 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 (Socket sock)
 Send the default heartbeat message.
 

Protected Attributes

hash< string, ServerSentEventConnectionch
 connection hash
 
int heartbeat = DefaultHeartbeatInterval
 heartbeat interval in seconds
 
string heartbeat_msg = DefaultHeartbeatMsg
 heartbeat message
 
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:

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
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)
  • logger: a LoggerInterface object for logging
Exceptions
SERVERSENTEVENTHANDLER-OPTION-ERRORunknown 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 ( )

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
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 HTTP client connection in ServerSentEventHandler::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") 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
dthe 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
secondsthe 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
secondsthe 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
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