UserGuide

This guide assumes the reader is familiar with the whereabouts of the EventSource api. If this is not currently the case, they are some good introductory materials on the Internet covering this topic. We believe that this tutorial post provides a good introduction.

In what follows, we detail features or problems that are specific to the fallback EventSource class provided by this project. Though we are trying to match as much as we can the W3C API we are limited by the javascript API that are availables in the browser we are patching.

Detecting EventSource type

If you need to control the polyfill EventSource it is important to detect when it has been loaded. To ease such task the polyfill EventSource class is marked with an attribute named isPolyfill ...

<!-- load EventSource polyfill if it is not provided by browser -->
<script type="text/javascript" src="/yourjs/eventsource.js">
</script>

<script>

    // detect what kind of EventSource we have
    var isPolyfill = EventSource.isPolyfill;

    switch (isPolyfill) {

        case undefined:

            alert("Browser supports EventSource natively");
            break;

        case "XHR":

            // IE >= 10, Android, old IPhone...
            alert("Browser loaded polyfill EventSource...");
            break;

        case "IE_8-9":

            // IE8, IE9
            alert("Browser loaded polyfill EventSource for IE8-9");
            break;

        default:

            alert("Browser loaded unexpected EventSource...");
    }

</script>

EventSource buffer size limit

The polyfill EventSource has a security mechanism to prevent its internal buffer to grow larger than a certain limit size. Such limit (default 256 kb...) can be adjusted using the bufferSizeLimit option.

// limit EventSource buffer to 384 kb
// if EventSource is polyfill

var options = {}

if (EventSource.isPolyfill !== undefined) {

    options['bufferSizeLimit'] = 393216; // 384 kb in bytes...
}

var pageEventSource = new EventSource('/path/to/event/stream', options);

pageEventSource.onmessage = function(event){...};

More information

Polyfill EventSource connects to the data streaming url using an XmlHTTPRequest object or alternatively in the case of Internet explorer (8/9) using an XDomainRequest object. One problem with those objects, is that the response datas are accumulating inside a buffer that can not be reset.

As the same response buffer may be used during large period of time (say hours...), we have put in place a mechanism that disconnect/reconnect the EventSource when the internal buffer size goes past a certain limit.

The default limit is 256 kb (256 x 1024 bytes...). This limit can be changed by assigning desired value to option bufferSizeLimit...

Reconnecting with Last-Event-Id

When in Internet Explorer 8/9, the polyfill EventSource will report Last-Event-Id using GET parameter evs_last_event_id instead of normalized HTTP request header Last-Event-Id.

More information

The EventSource specification allows the server to mark some of the event messages with a unique identifier. EventSource stores last received identifier and sends it back to the server when reconnecting. This mechanism help avoiding retransmission of important or costly to obtain messages.

As per the specification, when reconnecting, an EventSource shall report last received identifier using the HTTP header Last-Event-Id. Unfortunatly the XDomainRequest we use to support the EventSource connection when in Internet explorer, does not allow setting custom header. Hence the decision to fallback using a GET argument named evs_last_event_id in such case.

Initializing server event stream for IE8/IE9

When in Internet Explorer 8/9, the polyfill EventSource automatically add to the event stream url the GET parameter evs_preamble. If the server receives such parameter, we advise it immediatly streams back an EventSource comment of 2056 characters. If it fails to do so the EventSource will need to have received 2048 bytes of datas prior to be able to dispatch events...

More information

In Internet Explorer 8/9, the EventSource polyfill uses the XDomainRequest object to connect to the event stream url. We are overcoming a well known bug where XDomainRequest will not be able to dispatch progress events as long as it has not received 2 kb of datas.

Importing the polyfill EventSource

Normally the polyfill EventSource will be brought in global scope only if the browser does not support EventSource. They are situations in which this approach will get in the way (eg testing...).

We provide a mechanism that allow controlling under which name the polyfill EventSource shall be imported. This allow to get the polyfill EventSource alongside the native EventSource...

<!-- load polyfill EventSource under name PolyfillEvenSource -->

<script>
    // this global variable let us control the import name
    var _eventSourceImportPrefix = "Polyfill";
</script>

<script type="text/javascript" src="/yourjs/eventsource.js"></script>

<script>
    var pflSrc = new PolyfillEventSource("/path/to/your/event/stream");
    pflSrc.onmessage = function(event){...};
</script>

polyfill EventSource options

• bufferSizeLimit: maximum buffer size in bytes (default 256 kb)
• loggingEnabled: set true to enable console logging (default to false)
• loggingPrefix: default to "eventsource"
• getArgs: object containing additional GET parameters to append to stream url
• xhrHeaders: object containing supplementary HTTP headers to be passed with connection request. Those will be ignored when in IE8 and IE9

Options with name others than the one listed here will be ignored.

// Activating console logging on polyfill EventSource

var options = {}

if (EventSource.isPolyfill !== undefined) {

    options['loggingEnabled'] = true;
    options['loggingPrefix'] =  "polyfill EventSource";
}

var pageEventSource = new EventSource('/path/to/event/stream', options);

pageEventSource.onmessage = function(event){...};