@joeybaker/eventsource

EventSource

This library is a pure JavaScript implementation of the EventSource client. The API aims to be W3C compatible.

You can use it with Node.js or as a browser polyfill for browsers that don't have native EventSource support.

This Fork

• Fixes several multiple reconnect issues (these are quite serious)
• Adds a timeout option to manually reconnect after a specified time
• Allows disabling the reconnection

Install

npm install @joeybaker/eventsource

Example

npm install
node ./example/sse-server.js
node ./example/sse-client.js    # Node.js client
open http://localhost:8080      # Browser client - both native and polyfill
curl http://localhost:8080/sse  # Enjoy the simplicity of SSE)

Browser Polyfill

Just add example/eventsource-polyfill.js file to your web page:

<script src=/eventsource-polyfill.js></script>

Now you will have two global constructors:

window.EventSourcePolyfill
window.EventSource // Unchanged if browser has defined it. Otherwise, same as window.EventSourcePolyfill

If you're using webpack or browserify you can of course build your own. (The example/eventsource-polyfill.js is built with webpack).

Extensions to the W3C API

Setting HTTP request headers

You can define custom HTTP headers for the initial HTTP request. This can be useful for e.g. sending cookies or to specify an initial Last-Event-ID value.

HTTP headers are defined by assigning a headers attribute to the optional eventSourceInitDict argument:

var eventSourceInitDict = {headers: {'Cookie': 'test=test'}};
var es = new EventSource(url, eventSourceInitDict);

Allow unauthorized HTTPS requests

By default, https requests that cannot be authorized will cause connection to fail and an exception to be emitted. You can override this behaviour:

var eventSourceInitDict = {rejectUnauthorized: false};
var es = new EventSource(url, eventSourceInitDict);

Note that for Node.js < v0.10.x this option has no effect - unauthorized HTTPS requests are always allowed.

HTTP status code on error events

Unauthorized and redirect error status codes (for example 401, 403, 301, 307) are available in the status property in the error event.

es.onerror = function (err) {
  if (err) {
    if (err.status === 401 || err.status === 403) {
      console.log('not authorized');
    }
  }
};

HTTP/HTTPS proxy

You can define a proxy option for the HTTP request to be used. This is typically useful if you are behind a corporate firewall.

var es = new EventSource(url, { proxy: 'http://your.proxy.com' });

Disable Reconnect

The spec says that Eventsource should reconnect when the connection errors. This is typically good behavior, but you might want to turn this off.

var es = new EventSource(url, { reconnect: false });

Timeout the Connection

To work around the disadvantages of native Eventsource, this module uses XHR long-polling to simulate an Eventsource object. This can look like an idle connection to servers which can end the connection. This module will auto-reconnect, but if you'd like to avoid server errors, you can manually re-connect after a specified time.

// reconnect after 10 seconds
var es = new EventSource(url, { time: 10000 });