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, ServerSentEventConnection > | ch
| 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:
  - 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 | ( |  | ) |

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