Server Event Group

This site uses Just the Docs, a documentation theme for Jekyll.

@aphorica/server-event-client

Client-side utility for registering and maintaining EventSources connections.

The npm package is here:

Overview

The EventSource object is provided by the browser (or a polyfill in the case of non-support (IE/Edge)) to manage long-lived keep-alive connections with the server, and to keep them open until closed.

This utility provides an EventSource implementation that, in turn, is tuned to the server implementation provided by the @aphorica/server-event-mgr.

It also provides debugging invocations into the server to aid in development.

Installation

npm install @aphorica/server-event-client or yarn add @aphorica/server-event-client

Caveats:

  • IN PROGRESS - STILL DEVELOPING
  • (pull requests welcome, but we need to tightly coordinate any merges.)

Implementation Notes

eventsource polyfill

I’ve decided to bundle the eventsource polyfill with the client mainly because I’ve figured out how to make this implementation work (as opposed to others), especially in a CORS scenario.

If the browser doesn’t supply its own EventSource module (MS Edge, MS IE, primarily), the polyfill will provide one.

Otherwise, the package will use the browser version.

API

The EventSource object is created, retained, and destroyed entirely within the ServerEventClient instance. All interactions from the application are with the ServerEventClient instance (never with the EventSource object.)

Note also that the ServerEventClient instance is created via the ServerEventClientFactory.create() function. The reason for this is that during the creation process, several async calls must be invoked with the server, and waiting for them within a constructor is not good practice, nor are errors detected and conveyed in a constructor easily.

Creation API

ServerEventClientFactory.create(name, appurl, cb, prefix)
name - a name unique to the caller
appurl - the base url for calls to the server
cb - an object containing requisite callbacks
prefix - prepended to api calls to the server
returns - a ServerClient instance.

Creates the ServerClient instance. This instance contains the EventSource object and receives and sends requests to and from the server.

The _cb_ object can be anything that implements the set of required callbacks. Callbacks are as follows:

sseOpened(readyState, readyStateText)

readyState - the readyState value of the EventSource object. Can be one of:

  • EventSource.CONNECTING (0) ("Connecting")
  • EventSource.OPEN (1) ("Open")
  • EventSource.CLOSED(2) ("Closed")

readyStateText - text corresponding to the readyState
Called when the EventSource object establishes a connection with the server.

sseClosed()
Called when the EventSource object is closed. At this point, the object should remove itself as it is no longer valid.
sseError(readyState, readyStateText)
Called on error. (Actually haven't seen this.)
sseListenersChanged()
Received on a listeners-changed notification from the server.
sseTaskCompleted(id, taskid)
id - the unique id for this client
taskid - the taskid provided in the `submitTask` call.
Called when the specific task is completed.
sseRegistered(id)
id - the unique id for this client
Called when the server registers the id.

Operations API

submitTask(taskname)
taskname - name of the task.</em> Submits a named task to the server to execute and then send notification on completion. The taskname will be provided in the sseTaskCompleted call.
getSSEState()
Return the EventSource.readyState value.
getSSEStateText()
Return the text corresponding to the EventSource.readyState value.
disconnect()
Disconnect the EventSource object from the server. This will remove the EventSource object and invoke the sseClosed callback (which should trigger deletion of the ServerEventClient class.)

Debugging API

fetchRegistrants()
Fetch all the currently registered entries held by the server. Returned as a JSON object.
triggerCleanup()
Invokes a call to force the server to do an immediate cleanup pass.