forked from projectmoon/tenebrous-dicebot
90 lines
3.2 KiB
Markdown
90 lines
3.2 KiB
Markdown
|
# EventSource [](http://browsenpm.org/package/eventsource)[](https://travis-ci.org/EventSource/eventsource)[](http://npm-stat.com/charts.html?package=eventsource&from=2015-09-01)[](https://david-dm.org/EventSource/eventsource)
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
You can use it with Node.js or as a browser polyfill for
|
||
|
|
[browsers that don't have native `EventSource` support](http://caniuse.com/#feat=eventsource).
|
||
|
|
|
||
|
|
## Install
|
||
|
|
|
||
|
|
npm install 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:
|
||
|
|
|
||
|
|
```html
|
||
|
|
<script src=/eventsource-polyfill.js></script>
|
||
|
|
```
|
||
|
|
|
||
|
|
Now you will have two global constructors:
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
window.EventSourcePolyfill
|
||
|
|
window.EventSource // Unchanged if browser has defined it. Otherwise, same as window.EventSourcePolyfill
|
||
|
|
```
|
||
|
|
|
||
|
|
If you're using [webpack](https://webpack.github.io/) or [browserify](http://browserify.org/)
|
||
|
|
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:
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
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 the connection to fail and an exception
|
||
|
|
to be emitted. You can override this behaviour, along with other https options:
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
var eventSourceInitDict = {https: {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.
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
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.
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
var es = new EventSource(url, {proxy: 'http://your.proxy.com'});
|
||
|
|
```
|
||
|
|
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
MIT-licensed. See LICENSE
|