centrifuge 2.8.3 → 3.0.0-beta.0

package/README.md

@@ -1,37 +1,38 @@
-# Centrifuge client for NodeJS and browser
+# Centrifuge and Centrifugo bidirectional SDK for NodeJS, React-Native and browser
 
-This client can connect to [Centrifuge](https://github.com/centrifugal/centrifuge) server (and [Centrifugo](https://github.com/centrifugal/centrifugo) in particular) using pure WebSocket or [SockJS](https://github.com/sockjs/sockjs-client) polyfill transports from web browser or NodeJS environments.
+This SDK provides a client to connect to [Centrifugo](https://github.com/centrifugal/centrifugo) or any [Centrifuge-based](https://github.com/centrifugal/centrifuge) server using pure WebSocket or one of the fallback transports from web browser, ReactNative, or NodeJS environments.
 
-* [Install and quick start](#install-and-quick-start)
-* [Connection Token](#connection-token)
-* [Configuration parameters](#configuration-parameters)
+The client behaves according to a common [Centrifigo SDK spec](https://centrifugal.dev/docs/transports/client_api). It's recommended to read that before starting to work with this SDK as the spec covers common SDK behavior - describes client and subscription state transitions, main options and methods. Then proceed with this readme for more specifics about `centrifuge-js`.
+
+* [Install](#install)
+* [Quick start](#quick-start)
+* [WebSocket transport](#websocket-transport)
+* [Using fallbacks](#using-fallbacks)
+    * [SockJS](#using-fallbacks)
+    * [Bidirectional emulation](#bidirectional-emulation)
 * [Client API](#client-api)
-* [Private channels subscription](#private-channels-subscription)
+    * [Client methods and events](#client-methods-and-events)
+    * [Connection token](#connection-token)
+* [Subscription API](#subscription-api)
+    * [Subscription methods and events](#client-methods-and-events)
+    * [Subscription token](#connection-token)
+* [Message batching](#message-batching)
 * [Server-side subscriptions](#server-side-subscriptions)
-* [Connection expiration](#connection-expiration)
+* [Configuration parameters](#configuration-parameters)
 * [Protobuf support](#protobuf-support)
 * [Browser support](#browser-support)
 * [Using with NodeJS](#using-with-nodejs)
-* [Custom XMLHttpRequest](#custom-xmlhttprequest)
 * [Custom WebSocket constructor](#custom-websocket-constructor)
-* [Subscribe since known position](#subscribe-since-known-position)
-* [Feature Matrix](#feature-matrix)
 
-## Install and quick start
+## Install
 
-The simplest way to use `centrifuge-js` client is download it from `dist` folder and include into your web page using `script` tag:
+Using cdn (replace `X` to a concrete version number):
 
 ```html
-<script src="centrifuge.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/centrifugal/centrifuge-js@3.X.X/dist/centrifuge.min.js"></script>
 ```
 
-Or using cdn (replace `X` to concrete version number):
-
-```html
-<script src="https://cdn.jsdelivr.net/gh/centrifugal/centrifuge-js@2.X.X/dist/centrifuge.min.js"></script>
-```
-
-Client is also available via `npm`:
+Also available via `npm`:
 
 ```bash
 npm install centrifuge
@@ -40,274 +41,170 @@ npm install centrifuge
 And then:
 
 ```javascript
-var Centrifuge = require("centrifuge");
+import { Centrifuge } from 'centrifuge';
 ```
 
-Default library works with JSON only, see `Protobuf support` section to see how to import client with Protobuf support.
+By default, library works with JSON only, see [Protobuf support](#protobuf-support) section to see how to import client with Protobuf support.
+
+## Quick start
 
-As soon as you installed and imported `centrifuge-js` you can create new `Centrifuge` object instance, subscribe on channel and call `.connect()` method to make actual connection to server:
+The basic usage example may look like this:
 
 ```javascript
-var centrifuge = new Centrifuge('ws://centrifuge.example.com/connection/websocket');
+// Use WebSocket transport endpoint.
+const centrifuge = new Centrifuge('ws://centrifuge.example.com/connection/websocket');
 
-centrifuge.subscribe("news", function(message) {
-    console.log(message);
-});
+// Allocate Subscription to a channel.
+const sub = centrifuge.newSubscription('news');
 
-centrifuge.connect();
-```
+// React on `news` channel real-time publications.
+sub.on('publication', function(ctx) {
+    console.log(ctx.data);
+});
 
-In example above we initialize `Centrifuge` object instance, subscribe on channel `news`, print all new messages received from channel `news` into console and actually make connection to server. And that's all for basic real-time messaging on client side!
+// Trigger subscribe process.
+sub.subscribe();
 
-If you want to use SockJS you must also import SockJS client before centrifuge.js
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/sockjs-client@1.3/dist/sockjs.min.js" type="text/javascript"></script>
-<script src="centrifuge.js" type="text/javascript"></script>
+// Trigger actual connection establishement.
+centrifuge.connect();
 ```
 
-Or provide it explicitly:
+Note, that we explicitly call `.connect()` method to initiate connection establishement with a server and `.subscribe()` method to move Subscription to `subsribing` state (which should transform into `subscribed` state soon after connection with a server is established). The order of `.connect()` and `.subscribe` calls does not actually matter here.
 
-```javascript
-var Centrifuge = require("centrifuge");
-var SockJS = require('sockjs-client');
+**`Centrifuge` object and `Subscription` object are both instances of [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter).** Below we will describe events that can be exposed in detail.
 
-var centrifuge = new Centrifuge("http://localhost:8000/connection/sockjs", {
-  sockjs: SockJS
-})
-```
+## Websocket transport
 
-**`Centrifuge` object is an instance of [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter).**
+WebSocket is the main protocol used by `centrifuge-js` to communicate with a server. In browser environment it's available globally, but if you want to connect from NodeJS env – then you need to provide WebSocket constructor to `centrifuge-js` explicitly. [See below](#using-with-nodejs) more information about this.
 
-## Connection Token
+## Using fallbacks
 
-If you are connecting to Centrifugo **you must also provide connection token**:
+In the quick start example above we used WebSocket endpoint to configure Centrifuge. WebSocket is the main transport – it's bidirectional out of the box.
 
-```javascript
-var centrifuge = new Centrifuge('ws://centrifuge.example.com/connection/websocket');
+In some cases though, WebSocket connection may not be established (for example, due to corporate firewalls and proxies). For such situations `centrifuge-js` offers several WebSocket fallback options. 
 
-centrifuge.setToken(YOUR_TOKEN);
+### Using SockJS
 
-centrifuge.subscribe("news", function(message) {
-    console.log(message);
-});
+If you want to use SockJS you must also import SockJS client before centrifuge.js
 
-centrifuge.connect();
+```html
+<script src="https://cdn.jsdelivr.net/npm/sockjs-client@1.3/dist/sockjs.min.js" type="text/javascript"></script>
+<script src="centrifuge.js" type="text/javascript"></script>
 ```
 
-This token contains information about user of your application that tries to connect. See [server authentication documentation](https://centrifugal.github.io/centrifugo/server/authentication/) for details on how to generate it on your backend side.
-
-**Connection JWT comes to Javascript code from application backend - i.e. must be generated on backend**.
-
-## Configuration parameters
-
-Let's also look at optional configuration parameters available when initializing `Centrifuge` object instance.
-
-#### websocket
-
-`websocket` option allows to explicitly provide custom WebSocket client to use. By default centrifuge-js will try to use global WebSocket object, so if you are in web browser – it will just use native WebSocket implementation. See notes about using `centrifuge-js` with NodeJS below.
-
-#### sockjs
-
-`sockjs` option allows to explicitly provide SockJS client object to Centrifuge client.
-
-For example this can be useful if you develop in ES6 with imports:
+Or provide it explicitly as a dependency:
 
 ```javascript
-import Centrifuge from 'centrifuge'
+import { Centrifuge } from 'centrifuge'
 import SockJS from 'sockjs-client'
 
-var centrifuge = new Centrifuge('https://centrifuge.example.com/connection/sockjs', {
+const centrifuge = new Centrifuge("http://localhost:8000/connection/sockjs", {
   sockjs: SockJS
-});
+})
 ```
 
-#### sockjsTransports
-
-In case of using SockJS additional configuration parameter can be used - `sockjsTransports`.
+Note, that in SockJS case endpoint starts with `http://`, not with `ws://` as we used above when connecting to a pure WebSocket endpoint.
 
-It defines allowed SockJS transports and by default equals
+### Bidirectional emulation
 
-```javascript
-var centrifuge = new Centrifuge(
-  'http://centrifuge.example.com/connection/sockjs', 
-  {
-    sockjsTransports: [
-        'websocket', 
-        'xdr-streaming',
-        'xhr-streaming',
-        'eventsource',
-        'iframe-eventsource',
-        'iframe-htmlfile',
-        'xdr-polling',
-        'xhr-polling',
-        'iframe-xhr-polling',
-        'jsonp-polling'
-    ]
-});
-```
+SockJS is robust and stable product, but it's an extra dependency, it's pretty old, comes with some overhead and sticky sessions requirement for a distributed backend case. In most scenarios these days clients are fine to use WebSocket protocol for messaging. There are rare connection issues though which are caused by corporate firewall and proxy software. To deal with users behind such proxies Centrifuge SDK offers its own bidirectional emulation layer. This layer uses two HTTP-based transports:
 
-i.e. all possible SockJS transports.
+* HTTP-streaming based on ReadableStream API
+* SSE (EventSource).
 
-So to say `centrifuge-js` to use only `websocket` and `xhr-streaming` transports when
-using SockJS endpoint:
+Bidirectional emulation must be first enabled on a server-side. For example, see Centrifugo docs to find out how. Then in Javascript you can slightly change client initialization and point it to a list of endpoints and transports you want to use:
 
 ```javascript
-var centrifuge = new Centrifuge('http://centrifuge.example.com/connection/sockjs', {
-    sockjsTransports: ["websocket", "xhr-streaming"]
-});
-```
-
-#### sockjsServer
-
-`sockjsServer` is SockJS specific option to set server name into connection urls instead
-of random chars. See SockJS docs for more info.
-
-#### debug
-
-`debug` is a boolean option which is `false` by default. When enabled lots of various debug
-messages will be logged into javascript console. Mostly useful for development or
-troubleshooting.
-
-#### minRetry
-
-When client disconnected from server it will automatically try to reconnect using exponential
-backoff algorithm to get interval between reconnect attempts which value grows exponentially.
-`minRetry` option sets minimal interval value in milliseconds. Default is `1000` milliseconds.
-
-#### maxRetry
-
-`maxRetry` sets upper interval value limit when reconnecting. Or your clients will never reconnect
-as exponent grows very fast:) Default is `20000` milliseconds.
-
-#### subscribeEndpoint
-
-`subscribeEndpoint` is url to use when sending auth request for authorizing subscription on private channel. By default `/centrifuge/subscribe`. See also useful related options:
-
-* `subscribeHeaders` - map of headers to send with subscribe request (default `{}`)
-* `subscribeParams` - map of params to include in subscribe endpoint url (default `{}`)
-
-#### refreshEndpoint
-
-`refreshEndpoint` is url to use when refreshing client connection parameters when connection check mechanism enabled in Centrifugo configuration. See also related options:
-
-* `refreshHeaders` - map of headers to send with refresh request (default `{}`)
-* `refreshParams` - map of params to include in refresh url (default `{}`)
-* `refreshData` - send extra data in body (as JSON payload) when sending AJAX POST refresh request.
-* `refreshAttempts` - limit amount of refresh requests before giving up (by default `null` - unlimited)
-* `onRefreshFailed` - callback function called when `refreshAttempts` came to the end. By default `null` - i.e. nothing called.
-* `onRefresh` - optional callback to fully control refresh behaviour. This function will ve called as soon as connection token needs to be refreshed. After this it's up to application to get new token in a way it needs. As soon as application got token it must call callback passed as argument with proper data - see example below. *In this case `centrifuge-js` will not send automatic AJAX requests to your application*.
-
-Here is an example of using custom `onRefresh` function:
-
-```javascript
-centrifuge = new Centrifuge("http://localhost:8000/connection/websocket", {
-    debug: true,
-    onRefresh: function(ctx, cb) {
-        let promise = fetch("http://localhost:3000/centrifuge/refresh", {
-            method: "POST"
-        }).then(function(resp) {
-            resp.json().then(function(data) {
-                // Data must be like {"status": 200, "data": {"token": "JWT"}} - see 
-                // type definitions in dist folder. Note that setting status to 200 is
-                // required at moment. Any other status will result in refresh process
-                // failure so client will eventually be disconnected by server.
-                cb(data);
-            });
-        });
+const transports = [
+    {
+        transport: 'websocket',
+        endpoint: 'ws://example.com/connection/websocket'
+    },
+    {
+        transport: 'http_stream',
+        endpoint: 'http://example.com/connection/http_stream'
+    },
+    {
+        transport: 'sse',
+        endpoint: 'http://example.com/connection/sse'
     }
-});
+];
+const centrifuge = new Centrifuge(transports);
+centrifuge.connect()
 ```
 
-#### disableWithCredentials
+In this case, client will try transports in order, one by one, during the initial handshake. Until success. Then will only use a successful transport during reconnects.
+
+Supported transports are:
 
-`disableWithCredentials` is a reverse boolean option for control
-[withCredentials](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials)
-property of XMLHttpRequest. By default `false` - i.e. `withCredentials` property is enabled.
+* `websocket`
+* `http_stream`
+* `sse`
+* `sockjs` (yes, SockJS can also be used as a fallback in the bidirectional emulation layer, but sticky session must be used on the backend in distributed case).
 
 ## Client API
 
-When `Centrifuge` object properly initialized then it is ready to start communicating with server.
+Let's look at top-level API of `Centrifuge` client.
+
+### Client methods and events
 
 #### connect method
 
-As we showed before, we must call `connect()` method to make an actual connection
+As we already showed above, we must call `connect()` method to make an actual connection
 request to Centrifugo server:
 
 ```javascript
-var centrifuge = new Centrifuge('ws://centrifuge.example.com/connection/websocket');
-
+const centrifuge = new Centrifuge('ws://centrifuge.example.com/connection/websocket');
 centrifuge.connect();
 ```
 
 `connect()` triggers an actual connection request to server.
 
-#### connect event
+#### connected event
 
-After connection will be established and client credentials you provided authorized
-then `connect` event on `Centrifuge` object instance will be called.
+As soon as connection is established and client successfully authenticated – `connected` event on `Centrifuge` object instance will be called.
 
-You can listen to this setting event listener function on `connect` event:
+It's possible to listen to this event by setting event listener function on `connected` event:
 
 ```javascript
-centrifuge.on('connect', function(context) {
-    // now client connected to Centrifugo and authorized
+centrifuge.on('connected', function(ctx) {
+    // now client connected to Centrifugo and authenticated.
 });
 ```
 
-What's in `context`:
+#### connecting event
+
+`connecting` event fired when Centrifuge object goes to connecting state. This may be called during initial connect, or after being `connected` due to temporary connection loss.
 
 ```javascript
-{
-    client: "79ec54fa-8348-4671-650b-d299c193a8a3",
-    transport: "raw-websocket",
-    latency: 21
-}
+centrifuge.on('connecting', function(ctx) {
+    // do whatever you need in case of connecting to a server
+});
 ```
 
-* `client` – client ID Centrifugo gave to this connection (string)
-* `transport` – name of transport used to establish connection with server (string)
-* `latency` – latency in milliseconds (int). This measures time passed between sending
-    `connect` client protocol command and receiving connect response.
+#### disconnected event
 
-#### disconnect event
-
-`disconnect` event fired on centrifuge object every time client disconnects for
-some reason. This can be network disconnect or disconnect initiated by Centrifugo server.
+`disconnected` event fired on Centrifuge object every time client disconnects for some reason. This can be terminal disconnect due to advice from a server or disconnect initiated by client-side.
 
 ```javascript
-centrifuge.on('disconnect', function(context) {
+centrifuge.on('disconnected', function(ctx) {
     // do whatever you need in case of disconnect from server
 });
 ```
 
-What's in `context`?
-
-```javascript
-{
-    reason: "connection closed",
-    reconnect: true
-}
-```
-
-* `reason` – the reason of client's disconnect (string)
-* `reconnect` – flag indicating if client will reconnect or not (boolean)
-
 #### disconnect method
 
-In some cases you may need to disconnect your client from server, use `disconnect` method to
-do this:
+In some cases you may need to disconnect your client from server, use `.disconnect()` method to do this:
 
 ```javascript
 centrifuge.disconnect();
 ```
 
-After calling this client will not try to reestablish connection periodically. You must call
-`connect` method manually again.
+After calling this client will not try to reestablish connection periodically. You must call `.connect()` method manually again.
 
 #### publish method
 
-Sometimes you need to publish into channel with `publish` option set to `true` without actually being subscribed to it. In this case you can use `publish` method:
+Sometimes you need to publish into channel without actually being subscribed to it. In this case you can use `publish` method:
 
 ```javascript
 centrifuge.publish("channel", {"input": "hello"}).then(function(res) {
@@ -319,7 +216,7 @@ centrifuge.publish("channel", {"input": "hello"}).then(function(res) {
 
 #### send method
 
-This is only valid for Centrifuge library and does not work for Centrifugo server. `send` method allows to send asynchronous message from client to server.
+This is only valid for Centrifuge library and does not work for Centrifugo server at the moment. `send` method allows sending asynchronous message from a client to a server.
 
 ```javascript
 centrifuge.send({"input": "hello"}).then(function(res) {
@@ -331,22 +228,10 @@ centrifuge.send({"input": "hello"}).then(function(res) {
 
 #### rpc method
 
-`rpc` method allows to send RPC request from client to server and wait for data response.
+`rpc` method allows to send rpc request from client to server and wait for data response.
 
 ```javascript
-centrifuge.rpc({"input": "hello"}).then(function(res) {
-    console.log('rpc result', res);
-}, function(err) {
-    console.log('rpc error', err);
-});
-```
-
-#### namedRPC method
-
-`namedRPC` method allows to send rpc request from client to server and wait for data response. Unlike `rpc` it additionally allows to provide method name string (which can be handy to have on RPC request top level).
-
-```javascript
-centrifuge.namedRPC({"input": "hello"}).then(function(res) {
+centrifuge.rpc("my.method.name", {"input": "hello"}).then(function(res) {
     console.log('rpc result', res);
 }, function(err) {
     console.log('rpc error', err);
@@ -355,8 +240,6 @@ centrifuge.namedRPC({"input": "hello"}).then(function(res) {
 
 #### history method
 
-Available since v2.7.0
-
 Allows to get history from a server. This is a top-level analogue of `Subscription.history` method. But accepts a channel as first argument.
 
 ```javascript
@@ -369,8 +252,6 @@ centrifuge.history("channel", {since: {offset: 0, epoch: "xyz"}, limit: 10}).the
 
 #### presence method
 
-Available since v2.7.0
-
 Allows to get presence info from a server. This is a top-level analogue of `Subscription.presence` method. But accepts a channel as first argument.
 
 ```javascript
@@ -383,8 +264,6 @@ centrifuge.presence("channel").then(function(resp) {
 
 #### presenceStats method
 
-Available since v2.7.0
-
 Allows to get presence stats from a server. This is a top-level analogue of `Subscription.presenceStats` method. But accepts a channel as first argument.
 
 ```javascript
@@ -395,243 +274,139 @@ centrifuge.presenceStats("channel").then(function(resp) {
 });
 ```
 
-### setConnectData method
-
-Allows setting custom data sent to a server in first message. This data will be available on a server side in OnConnecting callback (if using Centrifugo library) or proxied to application backend (in using Centrifugo with connect proxy enabled).
+#### ready method
 
-```
-centrifuge.setConnectData({"any": "key"});
-```
+Returns a Promise which will be resolved upon connection establishement (i.e. when Client goes to `connected` state).
 
-## Subscriptions
+#### error event
 
-Of course being just connected is useless. What we usually want from Centrifugo is to
-receive new messages published into channels. So our next step is `subscribe` on channel
-from which we want to receive real-time messages.
-
-### subscribe method
-
-To subscribe on channel we must use `subscribe` method of `Centrifuge` object instance.
-
-The simplest usage that allow to subscribe on channel and listen to new messages is:
+To listen asynchronous error happening internally while Centrifuge client works you can set an `error` handler:
 
 ```javascript
-var subscription = centrifuge.subscribe("news", function(message) {
-    // handle new message coming from channel "news"
-    console.log(message);
-});
-```
+const centrifuge = new Centrifuge('ws://centrifuge.example.com/connection/websocket');
 
-And that's all! For lots of cases it's enough! But let's look at possible events that
-can happen with subscription:
-
-* `publish` – called when new publication message received (callback function in our previous example is `publish` event callback btw)
-* `join` – called when someone joined channel
-* `leave` – called when someone left channel
-* `subscribe` – called when subscription on channel successful and acknowledged by Centrifugo
-    server. It can be called several times during lifetime as browser client automatically resubscribes on channels after successful reconnect (caused by temporary network disconnect for example or Centrifugo server restart)
-* `error` – called when subscription on channel failed with error. It can be called several times
-    during lifetime as browser client automatically resubscribes on channels after successful reconnect 
-    (caused by temporary network disconnect for example or Centrifugo server restart)
-* `unsubscribe` – called every time subscription that was successfully subscribed
-    unsubscribes from channel (can be caused by network disconnect or by calling
-    `unsubscribe` method of subscription object)
-
-Don't be frightened by amount of events available. In most cases you only need some of them
-until you need full control to what happens with your subscriptions. We will look at format
-of messages for this event callbacks later below.
-
-There are 2 ways setting callback functions for events above.
-
-First is providing object containing event callbacks as second argument to `subscribe` method.
-
-```javascript
-var callbacks = {
-    "publish": function(message) {
-        // See below description of message format
-        console.log(message);
-    },
-    "join": function(message) {
-        // See below description of join message format
-        console.log(message);
-    },
-    "leave": function(message) {
-        // See below description of leave message format
-        console.log(message);
-    },
-    "subscribe": function(context) {
-        // See below description of subscribe callback context format
-        console.log(context);
-    },
-    "error": function(errContext) {
-        // See below description of subscribe error callback context format
-        console.log(err);
-    },
-    "unsubscribe": function(context) {
-        // See below description of unsubscribe event callback context format
-        console.log(context);
-    }
-}
-
-var subscription = centrifuge.subscribe("news", callbacks);
-```
-
-Another way is setting callbacks using `on` method of subscription. Subscription object
-is event emitter so you can simply do the following:
-
-```javascript
-var subscription = centrifuge.subscribe("news");
-
-subscription.on("publish", publishHandlerFunction);
-subscription.on("subscribe", subscribeHandlerFunction);
-subscription.on("error", subscribeErrorHandlerFunction);
+centrifuge.on('error', function(ctx) {
+    console.log(ctx);
+});
 ```
 
-**`Subscription` objects are instances of [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter).**
+This can help you to log failed connection attempts, or token refresh errors, etc.
 
-### join and leave events of subscription
+### Connection Token
 
-As you know you can enable `join_leave` option for channel in Centrifugo configuration.
-This gives you an opportunity to listen to `join` and `leave` events in those channels.
-Just set event handlers on `join` and `leave` events of subscription.
+Depending on authentication scheme used by a server you may also want to provide connection token:
 
 ```javascript
-var subscription = centrifuge.subscribe("news", function(message) {
-    // handle message
-}).on("join", function(message) {
-    console.log("Client joined channel", message);
-}).on("leave", function(message) {
-    console.log("Client left channel", message);
+const centrifuge = new Centrifuge('ws://centrifuge.example.com/connection/websocket', {
+    token: '<CONNECTION_TOKEN>'
 });
 ```
 
-*Note, that in order join/leave events to work corresponding options must be enabled in server channel configuration (on top level or for channel namespace)*
-
-### subscription event context formats
+In case of Centrifugo on a server side this may be a JSON Web Token - see [authentication documentation](https://centrifugal.github.io/centrifugo/server/authentication/) for details on how to generate it on your backend side.
 
-We already know how to listen for events on subscription. Let's look at format of
-messages event callback functions receive as arguments.
+**Connection token must come to the frontend from application backend - i.e. must be generated on the backend side**. The way to deliver token to the application frontend is up to the developer. Usually you can pass it in template rendering context or issue a separate call to request a connection token from the backend.
 
-#### format of message event context
+If the token sets connection expiration then the client SDK will keep the token refreshed. It does this by calling a special callback function. This callback must return a new token. If a new token with updated connection expiration is returned from callback then it's sent to Centrifugo. If your callback returns an empty string – this means the user has no permission to connect to Centrifugo and the Client will move to a disconnected state. In case of error returned by your callback SDK will retry the operation after some jittered time.
 
-Let's look at message format of new message received from channel:
+An example of possible `getToken` function implementation:
 
 ```javascript
-{
-    "data":{"input":"hello"},
+function getToken(url, ctx) {
+    return new Promise((resolve, reject) => {
+        fetch(url, {
+            method: 'POST',
+            headers: new Headers({ 'Content-Type': 'application/json' }),
+            body: JSON.stringify(ctx)
+        })
+        .then(res => {
+            if (!res.ok) {
+                throw new Error(`Unexpected status code ${res.status}`);
+            }
+            return res.json();
+        })
+        .then(data => {
+            resolve(data.token);
+        })
+        .catch(err => {
+            reject(err);
+        });
+    });
 }
-```
-
-I.e. `data` field contains actual data that was published.
-
-Message can optionally contain additional client `info` in case when this message was published by javascript client directly using `publish` method (see details below):
 
-```javascript
-{
-    "info":{
-        "user":"2694",
-        "client":"7080fd2a-bd69-4f1f-6648-5f3ceba4b643",
-        "conn_info":{"name":"Alexandr"},
-        "chan_info":{"extra":"extra JSON data when authorizing private channel"}
-    },
-    "data":{"input":"hello"}
-}
+const client = new Centrifuge(
+    'ws://localhost:8000/connection/websocket',
+    {
+        token: 'JWT-GENERATED-ON-BACKEND-SIDE',
+        getToken: function (ctx) {
+            return getToken('/centrifuge/connection_token', ctx);
+        }
+    }
+);
 ```
 
-#### format of join/leave event message
+:::tip
 
-I.e. `on("join", function(message) {...})` or `on("leave", function(message) {...})`
+If initial token is not provided, but `getToken` is specified – then SDK assumes that developer wants to use token authentication. In this case SDK attempts to get a connection token before establishing an initial connection.
 
-```javascript
-{
-    "info":{
-        "user":"2694",
-        "client":"2724adea-6e9b-460b-4430-a9f999e94c36",
-        "conn_info":{"first_name":"Alexandr"},
-        "chan_info":{"extra":"extra JSON data when authorizing"}
-    }
-}
-```
+:::
 
-`conn_info` and `chan_info` exist in message only if not empty.
+## Subscription API
 
-#### format of subscribe event context
+What we usually want from Centrifugo is to receive new messages published into channels. To do this we must create `Subscription` object.
 
-I.e. `on("subscribe", function(context) {...})`
+### Subscription methods and events
 
-```javascript
-{
-    "channel": "$public:chat",
-    "isResubscribe": true,
-    "recovered": false
-}
-```
+#### Subscribe to a channel
 
-`isResubscribe` – boolean flag showing if this was initial subscribe (`false`) or resubscribe (`true`)
-`recovered` – boolean flag that indicated whether missed messages were recovered on reconnect or not (recovery works according to Centrifugo channel configuration)
+The simplest usage that allow to subscribe on channel and listen to new messages is:
 
-#### format of subscription error event context
+```javascript
+const sub = centrifuge.newSubscription('example');
 
-I.e. `on("error", function(err) {...})`
+sub.on('publication', function(ctx) {
+    // handle new Publication data coming from channel "news".
+    console.log(ctx.data);
+});
 
-```javascript
-{
-    "error": "permission denied",
-    "channel": "$public:chat",
-    "isResubscribe": true
-}
+sub.subscribe();
 ```
 
-`error` - error description
-`isResubscribe` – flag showing if this was initial subscribe (`false`) or resubscribe (`true`)
+#### Subscription events
+
+Some events which can be listened on Subscription object are:
 
-#### format of unsubscribe event context
+* `publication` – called when new publication received from a Subscription channel
+* `join` – called when someone joined channel
+* `leave` – called when someone left channel
+* `subscribing` - called when Subscription goes to `subscribing` state (initial subscribe and re-subscribes)
+* `subscribed` – called when Subscription goes to `subscribed` state
+* `unsubscribed` – called when Subscription goes to `unsubscribed` state
+* `error` – called when subscription on channel failed with error. It can be called several times
+    during lifetime as browser client automatically resubscribes on channels after successful reconnect 
+    (caused by temporary network disconnect for example or Centrifugo server restart)
 
-I.e `on("unsubscribe", function(context) {...})`
+Don't be frightened by amount of events available. In most cases you only need some of them until you need full control to what happens with your subscriptions.
 
-```javascript
-{
-    "channel": "$public:chat"
-}
-```
+**`Subscription` objects are instances of [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter).**
 
-### presence method of subscription
+#### presence method of Subscription
 
 `presence` allows to get information about clients which are subscribed on channel at
 this moment. Note that this information is only available if `presence` option enabled
 in Centrifugo configuration for all channels or for channel namespace.
 
 ```javascript
-var subscription = centrifuge.subscribe("news", function(message) {
-    // handle message
-});
+const sub = centrifuge.newSubscription("news");
+sub.subscribe()
 
-subscription.presence().then(function(message) {
-    // presence data received
+sub.presence().then(function(ctx) {
+    console.log(ctx.clients);
 }, function(err) {
     // presence call failed with error
 });
 ```
 
-`presence` is internally a promise that will be resolved with data or error only
-when subscription actually subscribed.
-
-Format of success callback `message`:
-
-```javascript
-{
-    "presence":{
-        "2724adea-6e9b-460b-4430-a9f999e94c36": {
-            "user":"2694",
-            "client":"2724adea-6e9b-460b-4430-a9f999e94c36"
-        },
-        "d274505c-ce63-4e24-77cf-971fd8a59f00":{
-            "user":"2694",
-            "client":"d274505c-ce63-4e24-77cf-971fd8a59f00"
-        }
-    }
-}
-```
+`presence` is internally a promise that will be waiting for subscription subscribe success if required.
 
 As you can see presence data is a map where keys are client IDs and values are objects
 with client information.
@@ -640,8 +415,8 @@ Format of `err` in error callback:
 
 ```javascript
 {
-    "code": 0,
-    "message": "timeout"
+    "code": 108,
+    "message": "not available"
 }
 ```
 
@@ -650,68 +425,37 @@ Format of `err` in error callback:
 
 *Note, that in order presence to work corresponding options must be enabled in server channel configuration (on top level or for channel namespace)*
 
-### presenceStats method of subscription
+#### presenceStats method of subscription
 
 `presenceStats` allows to get two counters from a server: number of total clients currently subscribed and number of unique users currently subscribed. Note that this information is only available if `presence` option enabled in server configuration for a channel.
 
 ```javascript
-var subscription = centrifuge.subscribe("news", function(message) {
-    // handle message
-});
-
-subscription.presenceStats().then(function(resp) {
-    // presence stats data received
+sub.presenceStats().then(function(ctx) {
+    console.log(ctx.numClients);
 }, function(err) {
     // presence stats call failed with error
 });
 ```
 
-### history method of subscription
+#### history method of subscription
 
-`history` method allows to get last messages published into channel. Note that history
-for channel must be configured in Centrifugo to be available for `history` calls from
-client.
+`history` method allows to get last messages published into channel. Note that history for channel must be configured in Centrifugo to be available for `history` calls from client.
 
 ```javascript
-var subscription = centrifuge.subscribe("news", function(message) {
-    // handle message
-});
-
-subscription.history().then(function(response) {
-    // history messages received
+sub.history({limit: 100}).then(function(ctx) {
+    console.log(ctx.publications);
 }, function(err) {
     // history call failed with error
 });
 ```
 
-Success callback `response` format:
-
-```javascript
-{
-    "publications": [
-        {
-            "data": {"input": "hello2"},
-            "offset": 1
-        },
-        {
-            "data": {"input": "hello1"},
-            "offset": 2
-        }
-    ],
-    "offset": 2,
-    "epoch": "xcf4w"
-}
-```
-
-Where `publications` is an array of messages published into channel, `offset` is a current stream top offset (added in v2.7.0), `epoch` is a current stream epoch (added in v2.7.0).
-
-Note that also additional fields can be included in publication objects - `client`, `info` if those fields were set in original publications.
-
-`err` format – the same as for `presence` method.
-
 *Note, that in order history to work corresponding options must be enabled in server channel configuration (on top level or for channel namespace)*
 
-Starting from v2.7.0 it's possible to iterate over history stream:
+Some history options available:
+
+* `limit` (number)
+* `since` (StreamPosition)
+* `reverse` (boolean)
 
 ```javascript
 resp = await subscription.history({'since': {'offset': 2, 'epoch': 'xcf4w'}, limit: 100});
@@ -727,22 +471,16 @@ resp = await subscription.history({limit: 0});
 
 I.e. not providing `since` and using zero `limit`.
 
-**For now history pagination feature only works with [Centrifuge](https://github.com/centrifugal/centrifuge) library based server and not available in Centrifugo**.
-
-### publish method of subscription
+#### publish method of subscription
 
-`publish` method of subscription object allows to publish data into channel directly from client. The main idea of Centrifugo is server side only push. Usually your application backend receives new event (for example new comment created, someone clicked like button etc) and then backend posts that event into Centrifugo over API. But in some cases you may need to allow clients to publish data into channels themselves. This can be used for demo projects, when prototyping ideas for example, for personal usage. And this allow to make something with real-time features without any application backend at all. Just Javascript code and Centrifugo.
+`publish` method of Subscription object allows publishing data into channel directly from a client.
 
-**So to emphasize: using client publish is not an idiomatic Centrifugo usage. It's not for production applications but in some cases (demos, personal usage, Centrifugo as backend microservice) can be justified and convenient. In most real-life apps you need to send new data to your application backend first (using the convenient way, for example AJAX request in web app) and then publish data to Centrifugo over Centrifugo API.**
+**Using client-side publish is not an idiomatic Centrifugo usage in many cases. Centrifugo is standalone server and when publishing from a client you won't get the message on the backend side (except using publish proxy feature of Centrifugo). In most real-life apps you need to send new data to your application backend first (using the convenient way, for example AJAX request in web app) and then publish data to Centrifugo over Centrifugo API.**
 
-To do this you can use `publish` method. Note that just like presence and history publish must be allowed in Centrifugo configuration for all channels or for channel namespace. When using `publish` data will go through Centrifugo to all clients in channel. Your application backend won't receive this message.
+*Just like presence and history publish must be allowed in Centrifugo configuration for all channels or for channel namespace.*
 
 ```javascript
-var subscription = centrifuge.subscribe("news", function(message) {
-    // handle message
-});
-
-subscription.publish({"input": "hello world"}).then(function() {
+sub.publish({"input": "hello world"}).then(function() {
         // success ack from Centrifugo received
     }, function(err) {
         // publish call failed with error
@@ -750,78 +488,91 @@ subscription.publish({"input": "hello world"}).then(function() {
 });
 ```
 
-`err` format – the same as for `presence` method.
+*Note, that in order publish to work in Centrifugo corresponding option must be enabled in server channel configuration or client should have capability to publish*.
 
-*Note, that in order publish to work corresponding option must be enabled in server channel configuration (on top level or for channel namespace), by default client can not publish into channel*
+#### unsubscribe method of subscription
 
-### unsubscribe method of subscription
-
-You can call `unsubscribe` method to unsubscribe from subscription:
+You can call `unsubscribe` method to unsubscribe from a channel:
 
 ```javascript
-subscription.unsubscribe();
+sub.unsubscribe();
 ```
 
-**Important thing to know** is that unsubscribing from subscription does not remove event hanlers you already set to that subscription object. This allows to simply subscribe to channel again later calling `.subscribe()` method of subscription (see below). But there are cases when your code structured in a way that you need to remove event handlers after unsubscribe **to prevent them be executed twice** in the future. To do this remove event listeners explicitly after calling `unsubscribe()`:
+**Important thing to know** is that unsubscribing from subscription does not remove event handlers you already set to that Subscription object. This allows to simply subscribe to channel again later calling `.subscribe()` method of subscription (see below). But there are cases when your code structured in a way that you need to remove event handlers after unsubscribe **to prevent them be executed twice** in the future. To do this remove event listeners explicitly after calling `unsubscribe()`:
 
 ```javascript
-subscription.unsubscribe();
-subscription.removeAllListeners();
+sub.unsubscribe();
+sub.removeAllListeners();
 ```
 
-### subscribe method of subscription
+#### ready method of subscription
+
+Returns a Promise which will be resolved upon subscription success (i.e. when Subscription goes to `subscribed` state).
+
+### Subscription token
 
-You can restore subscription after unsubscribing calling `.subscribe()` method:
+You may want to provide subscription token:
 
 ```javascript
-subscription.subscribe();
+const sub = centrifuge.newSubscription("news", {
+    token: '<SUBSCRIPTION_TOKEN>'
+});
 ```
 
-### ready method of subscription
+In case of Centrifugo on a server side this may be a JSON Web Token - see [channel token auth documentation](https://centrifugal.github.io/centrifugo/server/channel_token_auth) for details on how to generate it on your backend side.
 
-A small drawback of setting event handlers on subscription using `on` method is that event
-handlers can be set after `subscribe` event of underlying subscription already fired. This
-is not a problem in general but can be actual if you use one subscription (i.e. subscription
-to the same channel) from different parts of your javascript application - so be careful.
+**Subscription token must come to the frontend from application backend - i.e. must be generated on the backend side**. The way to deliver token to the application frontend is up to the developer. Usually you can pass it in template rendering context or issue a separate call to request a connection token from the backend.
 
-For this case one extra helper method `.ready(callback, errback)` exists. This method calls
-`callback` if subscription already subscribed and calls `errback` if subscription already
-failed to subscribe with some error (because you subscribed on this channel before). So
-when you want to call subscribe on channel already subscribed before you may find `ready()`
-method useful:
+If token sets subscription expiration client SDK will keep token refreshed. It does this by calling special callback function. This callback must return a new token. If new token with updated subscription expiration returned from a calbback then it's sent to Centrifugo. If your callback returns an empty string – this means user has no permission to subscribe to a channel anymore and subscription will be unsubscribed. In case of error returned by your callback SDK will retry operation after some jittered time. 
 
-```javascript
-var subscription = centrifuge.subscribe("news", function(message) {
-    // handle message;
-});
+An example:
 
-// artificially model subscription to the same channel that happen after
-// first subscription successfully subscribed - subscribe on the same
-// channel after 5 seconds.
-setTimeout(function() {
-    var anotherSubscription = centrifuge.subscribe("news", function(message) {
-        // another listener of channel "news"
-    }).on("subscribe", function() {
-        // won't be called on first subscribe because subscription already subscribed!
-        // but will be called every time automatic resubscribe after network disconnect
-        // happens
+```javascript
+function getToken(url, ctx) {
+    return new Promise((resolve, reject) => {
+        fetch(url, {
+            method: 'POST',
+            headers: new Headers({ 'Content-Type': 'application/json' }),
+            body: JSON.stringify(ctx)
+        })
+        .then(res => {
+            if (!res.ok) {
+                throw new Error(`Unexpected status code ${res.status}`);
+            }
+            return res.json();
+        })
+        .then(data => {
+            resolve(data.token);
+        })
+        .catch(err => {
+            reject(err);
+        });
     });
-    // one of subscribeSuccessHandler (or subscribeErrorHandler) will be called
-    // only if subscription already subscribed (or subscribe request already failed).
-    anotherSubscription.ready(subscribeSuccessHandler, subscribeErrorHandler);
-}, 5000);
+}
+
+const client = new Centrifuge('ws://localhost:8000/connection/websocket', {});
+
+const sub = centrifuge.newSubscription(channel, {
+    token: 'JWT-GENERATED-ON-BACKEND-SIDE',
+    getToken: function (ctx) {
+        // ctx has channel in the Subscription token case.
+        return getToken('/centrifuge/subscription_token', ctx);
+    },
+});
+sub.subscribe();
 ```
 
-When called `callback` and `errback` of `ready` method receive the same arguments as
-callback functions for `subscribe` and `error` events of subscription.
+:::tip
+
+If initial token is not provided, but `getToken` is specified – then SDK assumes that developer wants to use token authorization for a channel subscription. In this case SDK attempts to get a subscription token before initial subscribe.
 
-### Message batching
+:::
 
-There is also message batching support. It allows to send several messages to server
-in one request - this can be especially useful when connection established via one of
-SockJS polling transports.
+## Message batching
 
-You can start collecting messages to send calling `startBatching()` method:
+There is also a command batching support. It allows to send several commands to a server in one request - may be especially useful when connection established via one of HTTP-based transports.
+
+You can start collecting commands by calling `startBatching()` method:
 
 ```javascript
 centrifuge.startBatching();
@@ -833,98 +584,111 @@ Finally if you don't want batching anymore call `stopBatching()` method:
 centrifuge.stopBatching();
 ```
 
-This call will flush all collected messages to network.
+This call will flush all collected commands to a network.
 
-## Private channels subscription
+## Server-side subscriptions
 
-If channel name starts with `$` then subscription on this channel will be checked via AJAX POST request from Javascript client to your web application backend.
+TODO.
 
-You can subscribe on private channel as usual:
+## Configuration parameters
 
-```javascript
-centrifuge.subscribe('$private', function(message) {
-    // process message
-});
-```
+Let's look at available configuration parameters when initializing `Centrifuge` object instance.
 
-But in this case Javascript client will first check subscription via your backend sending AJAX POST request to `/centrifuge/subscribe` endpoint (by default, can be changed via configuration option `subscribeEndpoint`). As said this is a POST request with JSON body. Request will contain `client` field on top level of JSON which is your connection client ID and array `channels` field - one or multiple private channels client wants to subscribe to.
+### debug
 
-```javascript
-{
-  "client": "<CLIENT ID>",
-  "channels": ["$chan1", "$chan2"]
-}
-```
+`debug` is a boolean option which is `false` by default. When enabled lots of various debug
+messages will be logged into javascript console. Mostly useful for development or
+troubleshooting.
 
-Your server should validate all these subscriptions and return properly constructed response.
+### minReconnectDelay
 
-Response is a JSON with array `channels` field on top level:
+When client disconnected from a server it will automatically try to reconnect using a backoff algorithm with jitter. `minReconnectDelay` option sets minimal interval value in milliseconds before first reconnect attempt. Default is `500` milliseconds.
 
-```javascript
-{
-  "channels": [
-    {
-      "channel": "$chan1",
-      "token": "<SUBSCRIPTION JWT TOKEN>"
-    },
-    {
-      "channel": "$chan2",
-      "token": <SUBSCRIPTION JWT TOKEN>
-    }
-  ]
-}
-```
+### maxReconnectDelay
 
-I.e. you need to return individual subscription tokens for each private channel in request. See [how to generate private channel tokens](https://centrifugal.github.io/centrifugo/server/private_channels/) in Centrifugo docs.
+`maxReconnectDelay` sets an upper reconnect delay value. Default is `20000` milliseconds - i.e. clients won't have delays between reconnect attempts which are larger than 20 seconds.
 
-If you don't want to give client access to channel then just do not include it into response.
+### maxServerPingDelay
 
-There are also two public API methods which can help to subscribe to many private channels sending only one POST request to your web application backend: `startSubscribeBatching` and `stopSubscribeBatching`. When you `startSubscribeBatching` javascript client will collect private subscriptions until `stopSubscribeBatching()` called – and then send them all at once.
+`maxServerPingDelay` sets the maximum delay of server pings after which connection is considered broken and client reconnects.
 
-As we just described when client subscribes on private channel by default AJAX request will be sent to `subscribeEndpoint` automatically if channel starts with `$`. In this case developer only needs to return proper response from server. But there is a way to override default behaviour and take full control on authorizing private channels. To do this it's possible to provide custom `onPrivateSubscribe` function in configuration options. This function will be called with all data required to authorize private channels client subscribes to and should call callback (will be provided by centrifuge-js as second argument) with authorization data when done. See our type declarations in `dist` folder to find out data format (**for `onPrivateSubscribe` it is slightly different** - like `{"status": 200, "data": {"channels": [...]}}`).
+### protocol
 
-## Server-side subscriptions
+By default, client works using `json` protocol. If you want to use binary transfer with Protobuf-based protocol this option must be set to `protobuf`. See more details about Protobuf communication in a special chapter.
 
-`centrifuge-js` v2.4.0 added support for server-side subscriptions. This means several new event handlers have been added.
+### token
 
-The main one is `publish` event of Centrifuge instance to handle publications coming from server-side channels:
+Set initial connection token.
 
-```javascript
-var centrifuge = new Centrifuge(address);
+### getToken
 
-centrifuge.on('publish', function(ctx) {
-    const channel = ctx.channel;
-    const payload = JSON.stringify(ctx.data);
-    console.log('Publication from server-side channel', channel, payload);
-});
+Set function for getting connection token. This may be used for initial token loading and token refresh mechanism (when initial token is going to expire).
 
-centrifuge.connect();
-```
+### data
+
+Set custom data to send to a server withing every connect command.
+
+### name
+
+Set custom client name. By default, it's set to `js`. This is useful for analitycs and semantically must identify an environment from which client establishes a connection.
+
+### version
+
+Version of your application - useful for analitycs.
+
+### timeout
+
+Timeout for operations.
 
-Also there are event handlers for `join`, `leave`, `subscribe` and `unsubscribe` events. Actually they work the same way as analogues from Subscription instance but binded to Centrifuge instance instead.
+### websocket
 
-For example:
+`websocket` option allows to explicitly provide custom WebSocket client to use. By default centrifuge-js will try to use global WebSocket object, so if you are in web browser – it will just use native WebSocket implementation. See notes about using `centrifuge-js` with NodeJS below.
+
+### sockjs
+
+`sockjs` option allows to explicitly provide SockJS client object to Centrifuge client.
+
+For example this can be useful if you develop in ES6 with imports:
 
 ```javascript
-centrifuge.on('subscribe', function(ctx) {
-    console.log('Subscribe to server-side channel ' + ctx.channel);
-});
+import Centrifuge from 'centrifuge'
+import SockJS from 'sockjs-client'
 
-centrifuge.on('unsubscribe', function(ctx) {
-    console.log('Unsubscribe from server-side channel ' + ctx.channel);
+const centrifuge = new Centrifuge('https://centrifuge.example.com/connection/sockjs', {
+  sockjs: SockJS
 });
 ```
 
-## Connection expiration
+### sockjsTransports
 
-When connection expiration mechanism is on on server client will automatically ask your backend for updated connection credentials sending AJAX HTTP POST request to `/centrifuge/refresh` endpoint (by default, can be changed using `refreshEndpoint` option). Client will send that request when connection ttl is close to the end. In response backend should return response with JSON like this:
+In case of using SockJS additional configuration parameter can be used - `sockjsTransports`.
+
+It defines allowed SockJS transports.
 
 ```javascript
-{
-  "token": "<ACTUAL JWT TOKEN>"
-}
+const centrifuge = new Centrifuge(
+  'http://centrifuge.example.com/connection/sockjs', 
+  {
+    sockjsTransports: [
+        'websocket', 
+        'xdr-streaming',
+        'xhr-streaming',
+        'eventsource',
+        'iframe-eventsource',
+        'iframe-htmlfile',
+        'xdr-polling',
+        'xhr-polling',
+        'iframe-xhr-polling',
+        'jsonp-polling'
+    ]
+});
 ```
 
+### sockjsServer
+
+`sockjsServer` is SockJS specific option to set server name into connection urls instead
+of random chars. See SockJS docs for more info.
+
 ## Protobuf support
 
 To import client with Protobuf protocol support:
@@ -936,42 +700,28 @@ To import client with Protobuf protocol support:
 Or if you are developing with npm:
 
 ```javascript
-import Centrifuge from 'centrifuge/dist/centrifuge.protobuf';
+import Centrifuge from 'centrifuge/build/protobuf';
 ```
 
 This client uses [protobuf.js](https://github.com/dcodeIO/ProtoBuf.js/) under the hood.
 
-Centrifuge client with Protobuf support also works with JSON. To enable binary websocket add `format` query param with `protobuf` value to Websocket endpoint URL:
-
-```javascript
-var centrifuge = new Centrifuge('ws://centrifuge.example.com/connection/websocket?format=protobuf');
-```
-
-When using Centrifugo v3 or Centrifuge >= v0.18.0 on server side prefer using client options instead of setting format in URL (available in `centrifuge-js` >= v2.8.0):
+Centrifuge client with Protobuf support also works with JSON. To enable binary websocket add `protocol: "protobuf"` option to Centrifuge configuration options:
 
 ```javascript
-var centrifuge = new Centrifuge('ws://centrifuge.example.com/connection/websocket', {
+const centrifuge = new Centrifuge('ws://centrifuge.example.com/connection/websocket", {
     protocol: 'protobuf'
 });
 ```
 
 ## Browser support
 
-This client intended to work in all modern browsers with Websocket support: https://caniuse.com/#search=websocket.
-
-**To support IE 11** you must additionally polyfill `Promise` as this library uses `Promise`.
-
-You can easily polyfill `Promise` via CDN (example here uses [es6-promise](https://github.com/stefanpenner/es6-promise) library):
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/es6-promise@4/dist/es6-promise.auto.min.js"></script>
-```
-
-Or you can explicitly polyfill `Promise` in your code, see [auto-polyfill of es6-promise](https://github.com/stefanpenner/es6-promise#auto-polyfill)
+TODO.
 
 ## Using with NodeJS
 
-NodeJS does not have native WebSocket library in std lib. To use `centrifuge-js` on Node you need to provide WebSocket object. You need to install WebSocket dependency:
+NodeJS does not have native WebSocket library in std lib. To use `centrifuge-js` on Node you need to explicitly provide WebSocket constructor to the library.
+
+First, install WebSocket dependency:
 
 ```
 npm install ws
@@ -1008,24 +758,7 @@ var centrifuge = new Centrifuge('ws://localhost:8000/connection/sockjs', {
 })
 ```
 
-### Custom XMLHttpRequest
-
-To work with private channels you may need to pass `XMLHttpRequest` object to library:
-
-```javascript
-const Centrifuge = require('centrifuge');
-const WebSocket = require('ws');
-const XMLHttpRequest = require("xmlhttprequest").XMLHttpRequest;
-
-var centrifuge = new Centrifuge('ws://localhost:8000/connection/websocket', {
-    websocket: WebSocket,
-    xmlhttprequest: XMLHttpRequest
-})
-```
-
-Or define XMLHttpRequest globally over `global.XMLHttpRequest = require("xmlhttprequest").XMLHttpRequest;`
-
-### Custom WebSocket constructor
+## Custom WebSocket constructor
 
 If you are building a client for a non-browser environment and want to pass custom headers then you can use the following approach to wrap a WebSocket constructor and let custom options to be used on connection initialization:
 
@@ -1049,53 +782,3 @@ var centrifuge = new Centrifuge('ws://localhost:8000/connection/websocket', {
     websocket: myWs({ headers: { Authorization: '<token or key>' } }),
 });
 ```
-
-### Subscribe since known position
-
-Available in `centrifuge-js` >= v2.8.0.
-
-Subscribe API supports setting known StreamPosition object to use server recovery feature on the connection start (otherwise recovery only used upon client reconnections due to temporary connection problems).
-
-```javascript
-centrifuge.subscribe('channel', function(messageCtx) {
-    console.log('new message', messageCtx);
-}, {'since': {'offset': 0, 'epoch': '<EPOCH>'}});
-```
-
-## Feature matrix
-
-- [x] connect to server using JSON protocol format
-- [x] connect to server using Protobuf protocol format
-- [x] connect with token (JWT)
-- [ ] connect with custom header (not supported by browser API, though [possible for a non-browser target env](https://github.com/centrifugal/centrifuge-js#custom-websocket-constructor))
-- [x] automatic reconnect in case of errors, network problems etc
-- [x] an exponential backoff for reconnect
-- [x] connect and disconnect events
-- [x] handle disconnect reason
-- [x] subscribe on a channel and handle asynchronous Publications
-- [x] handle Join and Leave messages
-- [x] handle Unsubscribe notifications
-- [x] reconnect on subscribe timeout
-- [x] publish method of Subscription
-- [x] unsubscribe method of Subscription
-- [x] presence method of Subscription
-- [x] presence stats method of Subscription
-- [x] history method of Subscription
-- [x] top-level publish method
-- [x] top-level presence method
-- [x] top-level presence stats method
-- [x] top-level history method
-- [ ] top-level unsubscribe method
-- [x] send asynchronous messages to server
-- [x] handle asynchronous messages from server
-- [x] send RPC commands
-- [x] subscribe to private channels with token (JWT)
-- [x] connection token (JWT) refresh
-- [x] private channel subscription token (JWT) refresh
-- [x] handle connection expired error
-- [x] handle subscription expired error
-- [x] ping/pong to find broken connection
-- [x] message recovery mechanism for client-side subscriptions
-- [x] server-side subscriptions
-- [x] message recovery mechanism for server-side subscriptions
-- [x] history stream pagination