the main sse client class
More...
#include <ServerSentEventClient.qc.dox.h>
|
| clearStats () |
| Clears performance statistics.
|
|
| clearWarningQueue () |
| Removes any warning Queue object from the Socket.
|
|
hash< auto > | connect (*hash< auto > opts, *reference< hash< auto > > info) |
| Connects to the sse server.
|
|
| constructor (hash< auto > opts) |
| Creates the ServerSentEvent client object from the arguments.
|
|
| destructor () |
| disconnects the connection and stops the event thread if connected
|
|
| disconnect () |
| Disconnect with the given close code.
|
|
int | getConnectionId () |
| returns the unique connection ID
|
|
*hash< auto > | getConnectionInfo () |
| Returns information about the current connection.
|
|
*string | getPassword () |
| Returns any password set for the connection.
|
|
bool | getReconnect () |
| Returns the value of the reconnect flag.
|
|
string | getSafeUrl () |
| Returns a "safe" URL, without any password info.
|
|
hash< auto > | getSchemes () |
| returns a hash of URL scheme information for URL schemes supported by this object
|
|
string | getSerialization () |
| Returns the data serialization value ("none" , "json" )
|
|
string | getUrl () |
| returns the URL given in the constructor
|
|
hash< auto > | getUsageInfo () |
| Returns performance statistics for the socket.
|
|
*string | getUsername () |
| Returns any username set for the connection.
|
|
bool | isOpen () |
| returns True if the connection is currently open and active, False if not
|
|
bool | isReconnecting () |
| Returns True if the client is reconnecting.
|
|
| observersReady () |
| Called when all observers have been added to the object.
|
|
bool | reconnect () |
| Initiate a server reconnect immediately.
|
|
| setEventQueue () |
| Removes any Queue object so that socket events are no longer added to the Queue.
|
|
| setEventQueue (Qore::Thread::Queue queue, auto arg, *bool with_data) |
| Sets a Queue object to receive socket events.
|
|
| setWarningQueue (int warning_ms, int warning_bs, Queue queue, auto arg, timeout min_ms=1s) |
| Sets a Queue object to receive socket warnings.
|
|
| stopEvents () |
| Called to stop generating events.
|
|
|
const | DataSerializationSupport = ... |
| Data serialization support.
|
|
const | DefaultTimeout = 15s |
| Default socket I/O operation timeout: 15 seconds.
|
|
const | DefaultUserAgent = sprintf("Qore-SSE-Client/%s", ServerSentEventClient::Version) |
| default user agent string for HTTP requests
|
|
const | MaxReconnectRetries = -1 |
| Max reconnect retries; negative numbers = infinite.
|
|
const | ReconnectDelay = 2s |
| Reconnect retry delay.
|
|
const | Version = "1.0" |
| Client version.
|
|
|
| clearTid () |
| Clears the tid and stop variables and wakes up any waiting threads.
|
|
| closingConnection () |
| Called when the connection is closed.
|
|
hash< auto > | connectIntern (*hash< auto > opts, *reference< hash< auto > > info, *bool reconnect) |
| Connects to the sse server.
|
|
hash< auto > | connectUnlocked (*hash< auto > hdr0, *reference< hash< auto > > info, *bool reconnect) |
| Performs the HTTP socket connection to the ServerSentEvent server.
|
|
| constructorInit (hash< auto > opts) |
| Common constructor code.
|
|
auto | deserializeData (string buf) |
| Deserializes data received.
|
|
| disconnectIntern (*bool destroy) |
| Disconnect with the given close code.
|
|
| doReconnect () |
| Handles reconnections.
|
|
int | handleEvent (hash< SseMessageInfo > event) |
| Handles messages.
|
|
| raiseError (string fmt,...) |
| throsse an exception due to an error
|
|
| reconnectPostamble () |
| Executes after a reconnect.
|
|
| reconnectPreamble () |
| Executes before a reconnect.
|
|
| reestablishConnection (reference< hash< auto > > info) |
| Connects to the server when reconnecting.
|
|
| start () |
| Connects and starts receiving messages.
|
|
| startReconnect () |
| Starts a reconnect.
|
|
Condition | tid_cond () |
| Event thread condition variable.
|
|
| unsupportedSerialization () |
| Throws an UNSUPPORTED-SERIALIZATION error.
|
|
|
static Sequence | seq () |
| Connection sequence.
|
|
|
bool | chunked |
| Flag indicating chunked transfer encoding.
|
|
int | cid = -1 |
| Unique sse connection ID; -1 when not connected.
|
|
string | content_encoding |
| The content encoding used by the server.
|
|
bool | do_reconnect |
| Flag for a user-initiated reconnect.
|
|
TransformOutputStream | dstream |
| The decompression transform stream.
|
|
string | last_event_id |
| Request Last-Event-Id when connecting.
|
|
int | num_connects |
| Total number of connections made.
|
|
StringOutputStream | ostream |
| The decompression output stream.
|
|
bool | reconnect = False |
| Reconnect flag.
|
|
string | serialization |
| data serialization option: json or none
|
|
const | SSEEDC_BREAK = 2 |
| Event disposition code: break event loop.
|
|
const | SSEEDC_CONTINUE = 1 |
| Event disposition code: continue processing event loop.
|
|
*code | start_thread |
| callable value to start a new thread; must take a callable object as a parameter and return an integer TID
|
|
int | tid |
| TID of the event thread; only changed in the log.
|
|
int | tid_waiting |
| Event thread waiting count.
|
|
string | url |
| URL string.
|
|
*code | yield |
| callable object to yield the current thread's execution
|
|
the main sse client class
To use this class, create a ServerSentEventClient object and the call ServerSentEventClient::connect().
The ServerSentEventClient::connect() method starts a background thread to receive messages, which are then raised as observable events.
To stop listening for SSE events, call ServerSentEventClient::disconnect().
The ServerSentEventClient class includes support for running in sandboxed Program objects with the following parse options set:
◆ clearStats()
ServerSentEventClient::ServerSentEventClient::clearStats |
( |
| ) |
|
◆ clearWarningQueue()
ServerSentEventClient::ServerSentEventClient::clearWarningQueue |
( |
| ) |
|
◆ connect()
hash< auto > ServerSentEventClient::ServerSentEventClient::connect |
( |
*hash< auto > | opts, |
|
|
*reference< hash< auto > > | info ) |
Connects to the sse server.
- Example:
sub event(*data msg) {
if (!msg) {
printf("connection closed\n");
} else {
printf("%s msg: %y\n", now_us().format("YYYY-MM-DD HH:mm:SS.xx"), msg);
}
}
ServerSentEventClient sse(\event(), {
"url": "sse://example.com:8080/path",
});
sse.connect();
This method starts a background thread to receive messages, which are rasied as observable events. If the server disconnects the SSE connection, the event thread also terminates and the ServerSentEventClient object will be in a disconnected state.
To stop listening for SSE events, call ServerSentEventClient::disconnect().
If this method is called while a connection is already in progress, then the existing connection is first implicitly disconnected.
- Parameters
-
opts | a hash with the following keys:
hdr: (optional) a hash giving header values for the connection request to the SSE server
|
info | a reference to a hash which will be set to information about the call setup |
- Returns
- a hash with information about the HTTP response from the HTTP server corresponding to the return value of Qore::Socket::readHTTPHeader()
- Exceptions
-
SSE-ERROR | the option hash is missing either the 'url' key or there is type error in the option hash |
◆ constructor()
ServerSentEventClient::ServerSentEventClient::constructor |
( |
hash< auto > | opts | ) |
|
Creates the ServerSentEvent client object from the arguments.
- Example:
sub event(*data msg) {
if (!msg) {
printf("connection closed\n");
} else {
printf("%s msg: %y\n", now_us().format("YYYY-MM-DD HH:mm:SS.xx"), msg);
}
}
ServerSentEventClient sse(\event(), {
"url": "sse://example.com:8080/path",
});
- Parameters
-
opts | an option hash for the HTTPClient constructor plus the following keys:
last_event_id: Request to the server to resend messages starting after this ID
logger: an optional LoggerInterface object for internal logging
reconnect: try to reconnect when the connection is closed or lost (default False)
yield: an options closure or call reference for yielding the current thread's execution to another thread (default value: Qore::Threads::thread_yield()); required if Qore::PO_NO_PROCESS_CONTROL is set in the current execution context
|
- Exceptions
-
SSE-ERROR | unknown scheme, missing 'url' key in option hash; invalid option value |
◆ getConnectionInfo()
*hash< auto > ServerSentEventClient::ServerSentEventClient::getConnectionInfo |
( |
| ) |
|
Returns information about the current connection.
- Returns
- a hash with the following keys:
cid:
the ServerSentEvent client connection ID
num_connects:
how many times has the client connected to the server
peer:
information about the connected server socket (see Socket::getPeerInfo())
socket:
information about the connected local socket (see Socket::getSocketInfo())
◆ getPassword()
*string ServerSentEventClient::ServerSentEventClient::getPassword |
( |
| ) |
|
Returns any password set for the connection.
- Returns
- any password set for the connection
◆ getUsageInfo()
hash< auto > ServerSentEventClient::ServerSentEventClient::getUsageInfo |
( |
| ) |
|
Returns performance statistics for the socket.
- Example:
hash<auto> h = sse.getUsageInfo();
- Returns
- a hash with the following keys:
"bytes_sent"
: an integer giving the total amount of bytes sent
"bytes_recv"
: an integer giving the total amount of bytes received
"us_sent"
: an integer giving the total number of microseconds spent sending data
"us_recv"
: an integer giving the total number of microseconds spent receiving data
"arg"
: (only if warning values have been set with ServerSentEventClient::setWarningQueue()) the optional argument for warning hashes
"timeout"
: (only if warning values have been set with ServerSentEventClient::setWarningQueue()) the warning timeout in microseconds
"min_throughput"
: (only if warning values have been set with ServerSentEventClient::setWarningQueue()) the minimum warning throughput in bytes/sec
- Since
- ServerSentEventClient 1.1
- See also
- ServerSentEventClient::clearStats()
◆ getUsername()
*string ServerSentEventClient::ServerSentEventClient::getUsername |
( |
| ) |
|
Returns any username set for the connection.
- Returns
- any username set for the connection
◆ observersReady()
ServerSentEventClient::ServerSentEventClient::observersReady |
( |
| ) |
|
Called when all observers have been added to the object.
This method is meant to trigger event generation
◆ reconnect()
bool ServerSentEventClient::ServerSentEventClient::reconnect |
( |
| ) |
|
Initiate a server reconnect immediately.
- Returns
- True if the reconnect was started
◆ setEventQueue() [1/2]
ServerSentEventClient::ServerSentEventClient::setEventQueue |
( |
| ) |
|
Removes any Queue object so that socket events are no longer added to the Queue.
- Example:
- See also
- event_handling for more information
- Since
- ServerSentEventClient 1.8
◆ setEventQueue() [2/2]
ServerSentEventClient::ServerSentEventClient::setEventQueue |
( |
Qore::Thread::Queue | queue, |
|
|
auto | arg, |
|
|
*bool | with_data ) |
Sets a Queue object to receive socket events.
- Example:
sse.setEventQueue(queue);
- Parameters
-
queue | the Queue object to receive socket events; note that the Queue passed cannot have any maximum size set or a QUEUE-ERROR will be thrown |
arg | an argument that will be included in each event hash in the arg key |
with_data | if True, then the actual raw data transferred / received is also included in the events |
- Exceptions
-
QUEUE-ERROR | the Queue passed has a maximum size set |
- See also
- event_handling for more information
- Since
- ServerSentEventClient 1.8
◆ setWarningQueue()
ServerSentEventClient::ServerSentEventClient::setWarningQueue |
( |
int | warning_ms, |
|
|
int | warning_bs, |
|
|
Queue | queue, |
|
|
auto | arg, |
|
|
timeout | min_ms = 1s ) |
Sets a Queue object to receive socket warnings.
- Example:
sse.setWarningQueue(5000, 5000, queue, "socket-1");
- Parameters
-
warning_ms | the threshold in milliseconds for individual socket actions (send, receive, connect), if exceeded, a socket warning is placed on the warning queue with the following keys:
"type" : a string with the constant value "SOCKET-OPERATION-WARNING"
"operation" : a string giving the operation that caused the warning (ex: "connect" )
"us" : an integer giving the number of microseconds for the operation
"timeout" : an integer giving the warning threshold in microseconds
"arg" : if any "arg" argument is passed to the ServerSentEventClient::setWarningQueue() method, it will be included in the warning hash here
|
warning_bs | value in bytes per second; if any call has performance below this threshold, a socket warning is placed on the warning queue with the following keys:
"type" : a string with the constant value "SOCKET-THROUGHPUT-WARNING"
"dir" : either "send" or "recv" depending on the direction of the data flow
"bytes" : the amount of bytes sent
"us" : an integer giving the number of microseconds for the operation
"bytes_sec" : a float giving the transfer speed in bytes per second
"threshold" : an integer giving the warning threshold in bytes per second
"arg" : if any "arg" argument is passed to the ServerSentEventClient::setWarningQueue() method, it will be included in the warning hash here
|
queue | the Queue object to receive warning events |
arg | an optional argument to be placed in the "arg" key in each warning hash (could be used to identify the socket for example) |
min_ms | the minimum transfer time with a resolution of milliseconds for a transfer to be eligible for triggering a warning; transfers that take less than this period of time are not eligible for raising a warning |
- Exceptions
-
QUEUE-ERROR | the Queue passed has a maximum size set |
SOCKET-SETWARNINGQUEUE-ERROR | at least one of warning_ms and warning_bs must be > 0 |
- See also
- ServerSentEventClient::clearWarningQueue()
- Since
- ServerSentEventClient 1.1
◆ stopEvents()
ServerSentEventClient::ServerSentEventClient::stopEvents |
( |
| ) |
|
Called to stop generating events.
Disconnects from the server
◆ tid
int ServerSentEventClient::ServerSentEventClient::tid |
|
protected |
TID of the event thread; only changed in the log.
Threads can wait for it to be cleared using tid_waiting and tid_cond