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 is a fork of the original EventSource project by Aslak Hellesøy, with additions to support the requirements of the LaunchDarkly SDKs. Note that as described in the changelog, the API is not backward-compatible with the original package, although it can be used with minimal changes.

Install

npm install launchdarkly-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);

Normally, EventSource will always add the headers Cache-Control: no-cache (since an SSE stream should always contain live content, not cached content), and Accept: text/event-stream. This could cause problems if you are making a cross-origin request, since CORS has restrictions on what headers can be sent. To turn off the default headers, so that it will only send the headers you specify, set the skipDefaultHeaders option to true:

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

Setting HTTP request method/body

By default, EventSource makes a GET request. You can specify a different HTTP verb and/or a request body:

var eventSourceInitDict = {method: 'POST', body: 'n=100'};
var es = new EventSource(url, eventSourceInitDict);

Special HTTPS configuration

In Node.js, you can customize the behavior of HTTPS requests by specifying, for instance, additional trusted CA certificates. You may use any of the special TLS options supported by Node's tls.connect() and tls.createSecureContext() (depending on what version of Node you are using) by putting them in an object in the https property of your configuration:

var eventSourceInitDict = {
  https: {
    rejectUnauthorized: false  // causes requests to succeed even if the certificate cannot be validated
  }
}
var es = new EventSource(url, eventSourceInitDict);

This only works in Node.js, not in a browser.

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'});

Detecting supported features

In cases where the EventSource implementation is determined at runtime (for instance, if you are in a browser that may or may not have native support for EventSource, and you are only loading this polyfill if there is no native support), you may want to know ahead of time whether certain nonstandard features are available or not.

The special property EventSource.supportedOptions is an object containing a true value for each property name that is allowed in the constructor parameters. If EventSource.supportedOptions.somePropertyName is true, then you are using a version of this polyfill that supports the somePropertyName option. If EventSource.supportedOptions.somePropertyName is false or undefined, or if EventSource.supportedOptions does not exist, then you are using either an older version of the polyfill, or some completely different EventSource implementation.

For instance, if you want to use the POST method-- which built-in EventSource implementations in browsers cannot do-- but you do not know for sure whether the current EventSource is this polyfill or a built-in browser version, you should check first whether that option is supported; otherwise, if it's the browser version, it will simply ignore the method option and do a GET request instead which probably won't work. So your logic might look like this:

if (EventSource.supportedOptions && EventSource.supportedOptions.method) {
  var es = new EventSource(url, {method: 'POST'})
} else {
  // do whatever you want to do if you can't do a POST request
}

License

MIT-licensed. See LICENSE