centrifuge 5.4.0 → 5.5.0

package/README.md

@@ -16,14 +16,15 @@ The features implemented by this SDK can be found in [SDK feature matrix](https:
     * [WebTransport (experimental)](#webtransport-experimental)
 * [Client API](#client-api)
     * [Client methods and events](#client-methods-and-events)
+    * [Client options](#client-options)
     * [Connection token](#connection-token)
 * [Subscription API](#subscription-api)
     * [Subscription methods and events](#subscription-methods-and-events)
     * [Subscription token](#subscription-token)
+    * [Subscription options](#subscription-options)
 * [Subscription management API](#subscription-management-api)
 * [Message batching](#message-batching)
 * [Server-side subscriptions](#server-side-subscriptions)
-* [Configuration options](#configuration-options)
 * [Protobuf support](#protobuf-support)
 * [Using with NodeJS](#using-with-nodejs)
 * [Custom WebSocket constructor](#custom-websocket-constructor)
@@ -223,6 +224,16 @@ centrifuge.on('disconnected', function(ctx) {
 });
 ```
 
+#### state event
+
+`state` event is fired when client state changes. It provides both old and new state.
+
+```javascript
+centrifuge.on('state', function(ctx) {
+    console.log('state changed from', ctx.oldState, 'to', ctx.newState);
+});
+```
+
 #### disconnect method
 
 In some cases you may need to disconnect your client from server, use `.disconnect()` method to do this:
@@ -313,6 +324,22 @@ Returns a Promise which will be resolved upon connection establishement (i.e. wh
 
 `setToken` may be useful to dynamically change the connection token. For example when you need to implement login/logout workflow. See an example in [blog post](https://centrifugal.dev/blog/2023/06/29/centrifugo-v5-released#token-behaviour-adjustments-in-sdks).
 
+#### setData method
+
+`setData` (since v5.5.0) allows setting connection data (some extra payload to deliver to the backend with connection request). This only affects the next connection attempt, not the current one. Note that if `getData` callback is configured, it will override this value during reconnects.
+
+```javascript
+centrifuge.setData({ 'name': 'Maria' });
+```
+
+#### setHeaders method
+
+`setHeaders` allows setting connection [emulated headers](https://centrifugal.dev/blog/2025/01/16/centrifugo-v6-released#headers-emulation). These headers will be sent with the next connection attempt. **Requires Centrifugo v6**.
+
+```javascript
+centrifuge.setHeaders({ 'Authorization': 'XXX' });
+```
+
 #### error event
 
 To listen asynchronous error happening internally while Centrifuge client works you can set an `error` handler:
@@ -327,6 +354,121 @@ centrifuge.on('error', function(ctx) {
 
 This can help you to log failed connection attempts, or token refresh errors, etc.
 
+### Client options
+
+Let's look at available configuration parameters when initializing `Centrifuge` object instance.
+
+#### token
+
+Set initial connection token (JWT). See [Connection Token](#connection-token) section for more details.
+
+#### getToken
+
+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). See [Connection Token](#connection-token) section for more details.
+
+#### data
+
+Set custom data to send to a server within every connect command.
+
+#### getData
+
+Set function for getting/renewing connection data. This callback is called upon reconnects to get fresh connection data. In many cases you may prefer using `setData` method of Centrifuge Client instead.
+
+```javascript
+const centrifuge = new Centrifuge('ws://localhost:8000/connection/websocket', {
+    getData: async () => {
+        // Return fresh data on each reconnect
+        return { 'timestamp': Date.now() };
+    }
+});
+```
+
+#### name
+
+Set custom client name. By default, it's set to `js`. This is useful for analytics and semantically must identify an environment from which client establishes a connection.
+
+#### version
+
+Version of your application - useful for analytics.
+
+#### headers
+
+Provide header emulation - these headers are sent with first protocol message. The backend can process those in a customized manner. In case of Centrifugo these headers are then used like real HTTP headers sent from the client. **Requires Centrifugo v6**.
+
+```javascript
+const centrifuge = new Centrifuge('ws://localhost:8000/connection/websocket', {
+    headers: {
+        'X-Custom-Header': 'value',
+        'Authorization': 'Bearer token'
+    }
+});
+```
+
+#### 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.
+
+#### minReconnectDelay
+
+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.
+
+#### maxReconnectDelay
+
+`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.
+
+#### maxServerPingDelay
+
+`maxServerPingDelay` sets the maximum delay of server pings after which connection is considered broken and client reconnects. In milliseconds. Default is `10000`.
+
+#### timeout
+
+Timeout for operations in milliseconds. Default is `5000`.
+
+#### 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.
+
+#### fetch
+
+Provide shim for fetch implementation. Useful when working in environments where fetch is not available globally.
+
+#### readableStream
+
+Provide shim for ReadableStream. Useful when working in environments where ReadableStream is not available globally.
+
+#### eventsource
+
+Provide shim for EventSource object. Useful when working in environments where EventSource is not available globally.
+
+#### emulationEndpoint
+
+Which emulation endpoint to use for bidirectional emulation transports. Default is `/emulation`.
+
+#### sockjs
+
+`sockjs` option allows to explicitly provide SockJS client object to Centrifuge client.
+
+#### sockjsOptions
+
+`sockjsOptions` allows modifying options passed to SockJS constructor. For example:
+
+```javascript
+const centrifuge = new Centrifuge(transports, {
+    sockjs: SockJS,
+    sockjsOptions: {
+        transports: ['websocket', 'xhr-streaming'],
+        timeout: 10000
+    }
+});
+```
+
+#### networkEventTarget
+
+EventTarget for network online/offline events. In browser environment Centrifuge uses global window online/offline events automatically by default. This option allows providing a custom EventTarget for handling network state changes in other environments.
+
+
 ### Connection Token
 
 Depending on authentication scheme used by a server you may also want to provide connection token:
@@ -535,6 +677,25 @@ sub.removeAllListeners();
 
 Returns a Promise which will be resolved upon subscription success (i.e. when Subscription goes to `subscribed` state).
 
+#### setData method of subscription
+
+`setData` (since v5.5.0) allows setting subscription data (some extra payload to deliver to the backend with subscription request). This only applies on the next subscription attempt. Note that if `getData` callback is configured, it will override this value during resubscriptions.
+
+#### setTagsFilter method of subscription
+
+`setTagsFilter` (since v5.5.0) allows setting tags filter for the subscription. Cannot be used together with `delta` option.
+
+See Centrifugo [Channel publication filtering](https://centrifugal.dev/docs/server/publication_filtering) docs.
+
+```javascript
+const tagsFilter = {
+    key: "ticker",
+    cmp: "eq",
+    val: ticker
+};
+sub.setTagsFilter(tagsFilter);
+```
+
 ### Subscription token
 
 You may want to provide subscription token:
@@ -586,6 +747,81 @@ sub.subscribe();
 
 > 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.
 
+### Subscription Options
+
+When creating a new subscription using `centrifuge.newSubscription(channel, options)`, you can provide various options to customize subscription behavior:
+
+#### token
+
+Allows setting initial subscription token (JWT). See [Subscription token](#subscription-token) section for more details.
+
+#### getToken
+
+Allows setting function to get/refresh subscription token. This will only be called when new token needed, not on every resubscribe. See [Subscription token](#subscription-token) section for more details.
+
+#### data
+
+Data to send to a server with subscribe command.
+
+#### getData
+
+Allows setting function to get/renew subscription data during resubscriptions. In many cases you may prefer using `setData` method of Subscription instead.
+
+```javascript
+const sub = centrifuge.newSubscription("news", {
+    getData: async (ctx) => {
+        // ctx.channel contains channel name
+        return { 'timestamp': Date.now() };
+    }
+});
+```
+
+#### since
+
+Force recovery on first subscribe from a provided `StreamPosition`. This is useful when you want to recover messages from a specific point during initial Subscription initialization.
+
+```javascript
+const sub = centrifuge.newSubscription("news", {
+    since: { offset: 100, epoch: 'xyz' }
+});
+```
+
+#### minResubscribeDelay
+
+Min delay between resubscribe attempts in milliseconds. Default is `500`.
+
+#### maxResubscribeDelay
+
+Max delay between resubscribe attempts in milliseconds. Default is `20000`.
+
+#### delta
+
+Delta format to be used for differential updates. Currently only `'fossil'` is supported. Cannot be used together with `tagsFilter`.
+
+```javascript
+const sub = centrifuge.newSubscription("news", {
+    delta: 'fossil'
+});
+```
+
+#### tagsFilter
+
+Server-side tags filter to apply for publications in channel. Cannot be used together with `delta`.
+
+See Centrifugo [Channel publication filtering](https://centrifugal.dev/docs/server/publication_filtering) docs.
+
+```javascript
+const tagsFilter = {
+    key: "ticker",
+    cmp: "eq",
+    val: ticker
+};
+
+const sub = centrifuge.newSubscription("tickers", {
+    tagsFilter: tagsFilter
+});
+```
+
 ## Subscription management API
 
 According to [client SDK spec](https://centrifugal.dev/docs/transports/client_api#subscription-management) centrifuge-js supports several methods to manage client-side subscriptions in internal registry. The following methods are available on top level of the Centrifuge SDK client instance.
@@ -680,62 +916,6 @@ Additionally, Client has several top-level methods to call with server-side subs
 * `presence(channel)`
 * `presenceStats(channel)`
 
-## Configuration options
-
-You can check out all available options with description [in source code](https://github.com/centrifugal/centrifuge-js/blob/master/src/types.ts#L82).
-
-Let's look at available configuration parameters when initializing `Centrifuge` object instance.
-
-### 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.
-
-### minReconnectDelay
-
-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.
-
-### maxReconnectDelay
-
-`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.
-
-### maxServerPingDelay
-
-`maxServerPingDelay` sets the maximum delay of server pings after which connection is considered broken and client reconnects. In milliseconds. Default is `10000`.
-
-### token
-
-Set initial connection token.
-
-### getToken
-
-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).
-
-### 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 in milliseconds.
-
-### 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.
-
 ## Protobuf support
 
 To import client which uses Protobuf protocol under the hood:

package/build/centrifuge.d.ts

@@ -71,6 +71,10 @@ export declare class Centrifuge extends Centrifuge_base {
     disconnect(): void;
     /** setToken allows setting connection token. Or resetting used token to be empty.  */
     setToken(token: string): void;
+    /** setData allows setting connection data. This only affects the next connection attempt,
+     * not the current one. Note that if getData callback is configured, it will override
+     * this value during reconnects. */
+    setData(data: any): void;
     /** setHeaders allows setting connection emulated headers. */
     setHeaders(headers: {
         [key: string]: string;

package/build/codes.d.ts

@@ -34,3 +34,6 @@ export declare enum unsubscribedCodes {
     unauthorized = 1,
     clientClosed = 2
 }
+export declare enum subscriptionFlags {
+    channelCompaction = 1
+}

package/build/index.js

@@ -556,6 +556,10 @@ exports.unsubscribedCodes = void 0;
     unsubscribedCodes[unsubscribedCodes["unauthorized"] = 1] = "unauthorized";
     unsubscribedCodes[unsubscribedCodes["clientClosed"] = 2] = "clientClosed";
 })(exports.unsubscribedCodes || (exports.unsubscribedCodes = {}));
+exports.subscriptionFlags = void 0;
+(function (subscriptionFlags) {
+    subscriptionFlags[subscriptionFlags["channelCompaction"] = 1] = "channelCompaction";
+})(exports.subscriptionFlags || (exports.subscriptionFlags = {}));
 
 /** State of client. */
 exports.State = void 0;
@@ -632,6 +636,7 @@ class Subscription extends EventEmitter$1 {
         this._recover = false;
         this._offset = null;
         this._epoch = null;
+        this._id = 0;
         this._recoverable = false;
         this._positioned = false;
         this._joinLeave = false;
@@ -645,6 +650,7 @@ class Subscription extends EventEmitter$1 {
         this._refreshTimeout = null;
         this._delta = '';
         this._delta_negotiated = false;
+        this._tagsFilter = null;
         this._prevValue = null;
         this._unsubPromise = Promise.resolve();
         this._setOptions(options);
@@ -726,6 +732,57 @@ class Subscription extends EventEmitter$1 {
             return this._centrifuge.history(this.channel, opts);
         });
     }
+    /**
+     * Sets server-side tags filter for the subscription.
+     * This only applies on the next subscription attempt, not the current one.
+     * Cannot be used together with delta option.
+     *
+     * @param tagsFilter - Filter configuration object or null to remove filter
+     * @throws {Error} If both delta and tagsFilter are configured
+     *
+     * @example
+     * ```typescript
+     * // Simple equality filter
+     * sub.setTagsFilter({
+     *   key: 'ticker',
+     *   cmp: 'eq',
+     *   val: 'BTC'
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Complex filter with logical operators
+     * sub.setTagsFilter({
+     *   op: 'and',
+     *   nodes: [
+     *     { key: 'ticker', cmp: 'eq', val: 'BTC' },
+     *     { key: 'price', cmp: 'gt', val: '50000' }
+     *   ]
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Filter with IN operator
+     * sub.setTagsFilter({
+     *   key: 'ticker',
+     *   cmp: 'in',
+     *   vals: ['BTC', 'ETH', 'SOL']
+     * });
+     * ```
+     */
+    setTagsFilter(tagsFilter) {
+        if (tagsFilter && this._delta) {
+            throw new Error('cannot use delta and tagsFilter together');
+        }
+        this._tagsFilter = tagsFilter;
+    }
+    /** setData allows setting subscription data. This only applied on the next subscription attempt,
+     * Note that if getData callback is configured, it will override this value during resubscriptions. */
+    setData(data) {
+        this._data = data;
+    }
     _methodCall() {
         if (this._isSubscribed()) {
             return Promise.resolve();
@@ -788,6 +845,9 @@ class Subscription extends EventEmitter$1 {
             return;
         }
         this._clearSubscribingState();
+        if (result.id) {
+            this._id = result.id;
+        }
         if (result.recoverable) {
             this._recover = true;
             this._offset = result.offset || 0;
@@ -983,6 +1043,7 @@ class Subscription extends EventEmitter$1 {
             req.recoverable = true;
         if (this._joinLeave)
             req.join_leave = true;
+        req.flag = exports.subscriptionFlags.channelCompaction;
         if (this._needRecover()) {
             req.recover = true;
             const offset = this._getOffset();
@@ -994,6 +1055,8 @@ class Subscription extends EventEmitter$1 {
         }
         if (this._delta)
             req.delta = this._delta;
+        if (this._tagsFilter)
+            req.tf = this._tagsFilter;
         return { subscribe: req };
     }
     _debug(...args) {
@@ -1174,6 +1237,12 @@ class Subscription extends EventEmitter$1 {
             }
             this._delta = options.delta;
         }
+        if (options.tagsFilter) {
+            this._tagsFilter = options.tagsFilter;
+        }
+        if (this._tagsFilter && this._delta) {
+            throw new Error('cannot use delta and tagsFilter together');
+        }
     }
     _getOffset() {
         const offset = this._offset;
@@ -2155,22 +2224,24 @@ class Centrifuge extends EventEmitter$1 {
      * state and rejects in case of client goes to Disconnected or Failed state.
      * Users can provide optional timeout in milliseconds. */
     ready(timeout) {
-        switch (this.state) {
-            case exports.State.Disconnected:
-                return Promise.reject({ code: exports.errorCodes.clientDisconnected, message: 'client disconnected' });
-            case exports.State.Connected:
-                return Promise.resolve();
-            default:
-                return new Promise((resolve, reject) => {
-                    const ctx = { resolve, reject };
-                    if (timeout) {
-                        ctx.timeout = setTimeout(() => {
-                            reject({ code: exports.errorCodes.timeout, message: 'timeout' });
-                        }, timeout);
-                    }
-                    this._promises[this._nextPromiseId()] = ctx;
-                });
-        }
+        return __awaiter(this, void 0, void 0, function* () {
+            switch (this.state) {
+                case exports.State.Disconnected:
+                    throw { code: exports.errorCodes.clientDisconnected, message: 'client disconnected' };
+                case exports.State.Connected:
+                    return;
+                default:
+                    return new Promise((resolve, reject) => {
+                        const ctx = { resolve, reject };
+                        if (timeout) {
+                            ctx.timeout = setTimeout(() => {
+                                reject({ code: exports.errorCodes.timeout, message: 'timeout' });
+                            }, timeout);
+                        }
+                        this._promises[this._nextPromiseId()] = ctx;
+                    });
+            }
+        });
     }
     /** connect to a server. */
     connect() {
@@ -2194,6 +2265,12 @@ class Centrifuge extends EventEmitter$1 {
     setToken(token) {
         this._token = token;
     }
+    /** setData allows setting connection data. This only affects the next connection attempt,
+     * not the current one. Note that if getData callback is configured, it will override
+     * this value during reconnects. */
+    setData(data) {
+        this._data = data;
+    }
     /** setHeaders allows setting connection emulated headers. */
     setHeaders(headers) {
         this._config.headers = headers;
@@ -3278,7 +3355,19 @@ class Centrifuge extends EventEmitter$1 {
         });
         return unsubscribePromise;
     }
-    _getSub(channel) {
+    _getSub(channel, id) {
+        if (id && id > 0) {
+            for (const ch in this._subs) {
+                if (this._subs.hasOwnProperty(ch)) {
+                    const sub = this._subs[ch];
+                    // @ts-ignore – we are accessing private property for internal use
+                    if (sub._id === id) {
+                        return sub;
+                    }
+                }
+            }
+            return null;
+        }
         const sub = this._subs[channel];
         if (!sub) {
             return null;
@@ -3491,9 +3580,9 @@ class Centrifuge extends EventEmitter$1 {
             errback({ error, next });
         }
     }
-    _handleJoin(channel, join) {
-        const sub = this._getSub(channel);
-        if (!sub) {
+    _handleJoin(channel, join, id) {
+        const sub = this._getSub(channel, id);
+        if (!sub && channel) {
             if (this._isServerSub(channel)) {
                 const ctx = { channel: channel, info: this._getJoinLeaveContext(join.info) };
                 this.emit('join', ctx);
@@ -3503,9 +3592,9 @@ class Centrifuge extends EventEmitter$1 {
         // @ts-ignore – we are hiding some symbols from public API autocompletion.
         sub._handleJoin(join);
     }
-    _handleLeave(channel, leave) {
-        const sub = this._getSub(channel);
-        if (!sub) {
+    _handleLeave(channel, leave, id) {
+        const sub = this._getSub(channel, id);
+        if (!sub && channel) {
             if (this._isServerSub(channel)) {
                 const ctx = { channel: channel, info: this._getJoinLeaveContext(leave.info) };
                 this.emit('leave', ctx);
@@ -3516,8 +3605,8 @@ class Centrifuge extends EventEmitter$1 {
         sub._handleLeave(leave);
     }
     _handleUnsubscribe(channel, unsubscribe) {
-        const sub = this._getSub(channel);
-        if (!sub) {
+        const sub = this._getSub(channel, 0);
+        if (!sub && channel) {
             if (this._isServerSub(channel)) {
                 delete this._serverSubs[channel];
                 this.emit('unsubscribed', { channel: channel });
@@ -3580,9 +3669,9 @@ class Centrifuge extends EventEmitter$1 {
         }
         return info;
     }
-    _handlePublication(channel, pub) {
-        const sub = this._getSub(channel);
-        if (!sub) {
+    _handlePublication(channel, pub, id) {
+        const sub = this._getSub(channel, id);
+        if (!sub && channel) {
             if (this._isServerSub(channel)) {
                 const ctx = this._getPublicationContext(channel, pub);
                 this.emit('publication', ctx);
@@ -3607,17 +3696,18 @@ class Centrifuge extends EventEmitter$1 {
     }
     _handlePush(data, next) {
         const channel = data.channel;
+        const id = data.id;
         if (data.pub) {
-            this._handlePublication(channel, data.pub);
+            this._handlePublication(channel, data.pub, id);
         }
         else if (data.message) {
             this._handleMessage(data.message);
         }
         else if (data.join) {
-            this._handleJoin(channel, data.join);
+            this._handleJoin(channel, data.join, id);
         }
         else if (data.leave) {
-            this._handleLeave(channel, data.leave);
+            this._handleLeave(channel, data.leave, id);
         }
         else if (data.unsubscribe) {
             this._handleUnsubscribe(channel, data.unsubscribe);