Wrap eventsource package as a node
npm install @parasaurolophus/node-red-eventsourceWrap the eventsource package for
use with Node-RED
Used by a personal home automation flow:
Tested with Node-RED 3.1 on Node.js 20.x. May not be compatible with earlier
versions.
See:
-
-
-
An EventSource node listens for event messages sent asynchronously by a
server, forwarding them as they arrive to other nodes downstream in a flow.
``mermaid
graph LR
server[Server]
subgraph Node-RED
eventsource[EventSource]
flow[Flow]
end
server -- Server-Sent Events --> eventsource
eventsource -- onopen\nServer-Sent Events\nonerror --> flow
`
The SSE (Server-Sent Event) and life-cycle state messages are as described by
If a URL is set in the node settings dialog, the node will attempt to connect
automatically each time the flow is (re-)started. Such a node will still respond
to messages sent to its input port as described in the next section. The URL may
be specified as a static string or with embedded references to environment
variables.
The node settings also includes a property named initDict whose value isEventSource
passed as the second parameter to the wrapped constructor. It can
be specified using JSON or JSONata.
_Note: Any parameters passed in an incoming message will override the
corresponding properties specified via the node's settings dialog._
If msg.payload is an object with a url property and, optionally, aninitDict property then this node uses new EventSource(msg.payload.url,
msg.payload.initDict) to wrap a newly created eventsource instance. TheinitDict defaults to an empty object ({}) if it is not supplied inmsg.payload. A common use of initDict is to pass authentication tokens toEventSource services that require them.
Otherwise, if msg.payload is not an object or does not have a url propertyeventsource.close()
then this node calls the method of the wrapped instance,
if it exists. If a subsequent message is received, any current connection will
be closed before attempting to establish a new connection.
1. Asynchronous stream of server-sent event objects
2. Asynchronous stream of EventSource.onopen life-cycleEventSource.onerror
messages
3. Asynchronous stream of life-cycle
messages
Each server-sent event object emitted from the first output will have
msg.payload.type and msg.payload.data fields and msg.topic set to"message". The content and format of the type and data properties are
determined by the server:
`json`
{
"topic": "message",
"payload": {
"type": "<...some string...>",
"data": "<...message body...>"
}
}
The default value for the type field defined by the"message"
WHATWG
specification is but can be set to (almost) any string for a givendata
event sent by a given server. The value of the field may be anything that
can be encoded in a HTTP response message but is often the HTML, JSON or XML
encoded representation of some "entity."
The second output will emit the objects sent to the EventSource.onopenmsg.topic
handler. Each such object will have set to "open" andmsg.payload will be the value passed to the handler.
The third output will emit the objects sent to the EventSource.onerrormsg.topic
handler. Each such object will have set to "error" andmsg.payload will be the value passed to the handler. SeeEventSource.onopen
for information on the payload content. As with events, themsg.payload
exact here is usually of limited usefulness due to issues with the
design and implementation of both the _WHATWG_ specification and the underlying
_EventSource_ library package wrapped by this node. What is of interest, again,
is that receipt of any event of this type indicates that the connection is
experiencing (hopefully transient) issues and the underlying library package is
still attempting to automatically (re-)connect.
This is a deliberately minimalist implementation of the protocol and JavaScript
interface underlying the standard _EventSource_ feature available in modern web
browsers. An aspect of the "minimalist" philoosophy is that an instance of
EventSource wrapped by this node will automatically subscribe to and forwardEventSource.onmessage
to the node's output all messages sent by the server, using an handler. (In particular, it makes no attempt to exposeEventTarget.addEventListener(type, handler, ...)
the more fine grained EventSource
interface.) To start receiving events, send a message with URL and configuration
parameters in its payload as described above. The node will open a
connection and begin emitting event messages asynchronously as they are sent by
the server.
The status.text of the EventSource node can be used to track the state of
the connection:
| status.text | Description |-1
| ------------- | ----------------------------------------------------------------------------------------------- |
| | The eventsource client object has not yet been created since the flow was last (re-)started |0
| | The eventsource.readyState value indicating the client is attempting to connect to the server |1
| | The eventsource.readyState value indicating the client is currently connected to the server |2
| | The eventsource.readyState value indicating the connection has failed |
The EventSource node's status will oscillate between 0 and 1 as the wrappedeventsource instance attempts to stay connected. If the status reaches 2,msg
there will be no more attempts to reconnect automatically. You will need to send
another to the EventSource node's input in order to resume receivingonopen
server-sent events. The and onerror` life-cycle messages described
above are emitted along the way.