1 | # EventSource [![npm version](http://img.shields.io/npm/v/eventsource.svg?style=flat-square)](http://browsenpm.org/package/eventsource)[![Build Status](http://img.shields.io/travis/EventSource/eventsource/master.svg?style=flat-square)](https://travis-ci.org/EventSource/eventsource)[![NPM Downloads](https://img.shields.io/npm/dm/eventsource.svg?style=flat-square)](http://npm-stat.com/charts.html?package=eventsource&from=2015-09-01)[![Dependencies](https://img.shields.io/david/EventSource/eventsource.svg?style=flat-square)](https://david-dm.org/EventSource/eventsource)
|
2 |
|
3 | This library is a pure JavaScript implementation of the [EventSource](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events) client. The API aims to be W3C compatible.
|
4 |
|
5 | You can use it with Node.js or as a browser polyfill for
|
6 | [browsers that don't have native `EventSource` support](http://caniuse.com/#feat=eventsource).
|
7 |
|
8 | ## Install
|
9 |
|
10 | npm install eventsource
|
11 |
|
12 | ## Example
|
13 |
|
14 | npm install
|
15 | node ./example/sse-server.js
|
16 | node ./example/sse-client.js # Node.js client
|
17 | open http://localhost:8080 # Browser client - both native and polyfill
|
18 | curl http://localhost:8080/sse # Enjoy the simplicity of SSE
|
19 |
|
20 | ## Browser Polyfill
|
21 |
|
22 | Just add `example/eventsource-polyfill.js` file to your web page:
|
23 |
|
24 | ```html
|
25 | <script src=/eventsource-polyfill.js></script>
|
26 | ```
|
27 |
|
28 | Now you will have two global constructors:
|
29 |
|
30 | ```javascript
|
31 | window.EventSourcePolyfill
|
32 | window.EventSource // Unchanged if browser has defined it. Otherwise, same as window.EventSourcePolyfill
|
33 | ```
|
34 |
|
35 | If you're using [webpack](https://webpack.github.io/) or [browserify](http://browserify.org/)
|
36 | you can of course build your own. (The `example/eventsource-polyfill.js` is built with webpack).
|
37 |
|
38 | ## Extensions to the W3C API
|
39 |
|
40 | ### Setting HTTP request headers
|
41 |
|
42 | You can define custom HTTP headers for the initial HTTP request. This can be useful for e.g. sending cookies
|
43 | or to specify an initial `Last-Event-ID` value.
|
44 |
|
45 | HTTP headers are defined by assigning a `headers` attribute to the optional `eventSourceInitDict` argument:
|
46 |
|
47 | ```javascript
|
48 | var eventSourceInitDict = {headers: {'Cookie': 'test=test'}};
|
49 | var es = new EventSource(url, eventSourceInitDict);
|
50 | ```
|
51 |
|
52 | ### Allow unauthorized HTTPS requests
|
53 |
|
54 | By default, https requests that cannot be authorized will cause the connection to fail and an exception
|
55 | to be emitted. You can override this behaviour, along with other https options:
|
56 |
|
57 | ```javascript
|
58 | var eventSourceInitDict = {https: {rejectUnauthorized: false}};
|
59 | var es = new EventSource(url, eventSourceInitDict);
|
60 | ```
|
61 |
|
62 | Note that for Node.js < v0.10.x this option has no effect - unauthorized HTTPS requests are *always* allowed.
|
63 |
|
64 | ### HTTP status code on error events
|
65 |
|
66 | Unauthorized and redirect error status codes (for example 401, 403, 301, 307) are available in the `status` property in the error event.
|
67 |
|
68 | ```javascript
|
69 | es.onerror = function (err) {
|
70 | if (err) {
|
71 | if (err.status === 401 || err.status === 403) {
|
72 | console.log('not authorized');
|
73 | }
|
74 | }
|
75 | };
|
76 | ```
|
77 |
|
78 | ### HTTP/HTTPS proxy
|
79 |
|
80 | You can define a `proxy` option for the HTTP request to be used. This is typically useful if you are behind a corporate firewall.
|
81 |
|
82 | ```javascript
|
83 | var es = new EventSource(url, {proxy: 'http://your.proxy.com'});
|
84 | ```
|
85 |
|
86 |
|
87 | ## License
|
88 |
|
89 | MIT-licensed. See LICENSE
|
90 |
|
\ | No newline at end of file |