centrifuge
Advanced tools
This client can connect to Centrifuge server (and Centrifugo in particular) using pure WebSocket or SockJS polyfill transports from web browser or NodeJS environments.
The simplest way to use centrifuge-js client is download it from dist folder and include into your web page using script tag:
<script src="centrifuge.js"></script>
Or using cdn (replace X to concrete version number):
<script src="https://cdn.jsdelivr.net/gh/centrifugal/centrifuge-js@2.X.X/dist/centrifuge.min.js"></script>
Client is also available via npm:
npm install centrifuge
And then:
var Centrifuge = require("centrifuge");
Default library works with JSON only, see Protobuf support section to see how to import client with Protobuf support.
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:
var centrifuge = new Centrifuge('ws://centrifuge.example.com/connection/websocket');
centrifuge.subscribe("news", function(message) {
console.log(message);
});
centrifuge.connect();
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!
If you want to use SockJS you must also import SockJS client before centrifuge.js
<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>
Or provide it explicitly:
var Centrifuge = require("centrifuge");
var SockJS = require('sockjs-client');
var centrifuge = new Centrifuge("http://localhost:8000/connection/sockjs", {
sockjs: SockJS
})
Centrifuge object is an instance of EventEmitter.
If you are connecting to Centrifugo you must also provide connection token:
var centrifuge = new Centrifuge('ws://centrifuge.example.com/connection/websocket');
centrifuge.setToken(YOUR_TOKEN);
centrifuge.subscribe("news", function(message) {
console.log(message);
});
centrifuge.connect();
This token contains information about user of your application that tries to connect. See server authentication documentation 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.
Let's also look at optional configuration parameters available when initializing Centrifuge object instance.
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 option allows to explicitly provide SockJS client object to Centrifuge client.
For example this can be useful if you develop in ES6 with imports:
import Centrifuge from 'centrifuge'
import SockJS from 'sockjs-client'
var centrifuge = new Centrifuge('https://centrifuge.example.com/connection/sockjs', {
sockjs: SockJS
});
In case of using SockJS additional configuration parameter can be used - sockjsTransports.
It defines allowed SockJS transports and by default equals
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'
]
});
i.e. all possible SockJS transports.
So to say centrifuge-js to use only websocket and xhr-streaming transports when
using SockJS endpoint:
var centrifuge = new Centrifuge('http://centrifuge.example.com/connection/sockjs', {
sockjsTransports: ["websocket", "xhr-streaming"]
});
sockjsServer is SockJS specific option to set server name into connection urls instead
of random chars. See SockJS docs for more info.
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.
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 sets upper interval value limit when reconnecting. Or your clients will never reconnect
as exponent grows very fast:) Default is 20000 milliseconds.
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 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:
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);
});
});
}
});
disableWithCredentials is a reverse boolean option for control
withCredentials
property of XMLHttpRequest. By default false - i.e. withCredentials property is enabled.
When Centrifuge object properly initialized then it is ready to start communicating with server.
As we showed before, we must call connect() method to make an actual connection
request to Centrifugo server:
var centrifuge = new Centrifuge('ws://centrifuge.example.com/connection/websocket');
centrifuge.connect();
connect() triggers an actual connection request to server.
After connection will be established and client credentials you provided authorized
then connect event on Centrifuge object instance will be called.
You can listen to this setting event listener function on connect event:
centrifuge.on('connect', function(context) {
// now client connected to Centrifugo and authorized
});
What's in context:
{
client: "79ec54fa-8348-4671-650b-d299c193a8a3",
transport: "raw-websocket",
latency: 21
}
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.disconnect event fired on centrifuge object every time client disconnects for
some reason. This can be network disconnect or disconnect initiated by Centrifugo server.
centrifuge.on('disconnect', function(context) {
// do whatever you need in case of disconnect from server
});
What's in context?
{
reason: "connection closed",
reconnect: true
}
reason – the reason of client's disconnect (string)reconnect – flag indicating if client will reconnect or not (boolean)In some cases you may need to disconnect your client from server, use disconnect method to
do this:
centrifuge.disconnect();
After calling this client will not try to reestablish connection periodically. You must call
connect method manually again.
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:
centrifuge.publish("channel", {"input": "hello"}).then(function(res) {
console.log('successfully published');
}, function(err) {
console.log('publish error', err);
});
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.
centrifuge.send({"input": "hello"}).then(function(res) {
console.log('successfully sent');
}, function(err) {
console.log('send error', err);
});
rpc method allows to send RPC request from client to server and wait for data response.
centrifuge.rpc({"input": "hello"}).then(function(res) {
console.log('rpc result', res);
}, function(err) {
console.log('rpc error', err);
});
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).
centrifuge.namedRPC({"input": "hello"}).then(function(res) {
console.log('rpc result', res);
}, function(err) {
console.log('rpc error', err);
});
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.
centrifuge.history("channel", {since: {offset: 0, epoch: "xyz"}, limit: 10}).then(function(resp) {
console.log(resp);
}, function(err) {
console.log('history error', err);
});
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.
centrifuge.presence("channel").then(function(resp) {
console.log(resp);
}, function(err) {
console.log('presence error', err);
});
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.
centrifuge.presenceStats("channel").then(function(resp) {
console.log(resp);
}, function(err) {
console.log('presence stats error', err);
});
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).
centrifuge.setConnectData({"any": "key"});
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.
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:
var subscription = centrifuge.subscribe("news", function(message) {
// handle new message coming from channel "news"
console.log(message);
});
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 channelleave – called when someone left channelsubscribe – 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.
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:
var subscription = centrifuge.subscribe("news");
subscription.on("publish", publishHandlerFunction);
subscription.on("subscribe", subscribeHandlerFunction);
subscription.on("error", subscribeErrorHandlerFunction);
Subscription objects are instances of EventEmitter.
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.
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);
});
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)
We already know how to listen for events on subscription. Let's look at format of messages event callback functions receive as arguments.
Let's look at message format of new message received from channel:
{
"data":{"input":"hello"},
}
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):
{
"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"}
}
I.e. on("join", function(message) {...}) or on("leave", function(message) {...})
{
"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.
I.e. on("subscribe", function(context) {...})
{
"channel": "$public:chat",
"isResubscribe": true,
"recovered": false
}
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)
I.e. on("error", function(err) {...})
{
"error": "permission denied",
"channel": "$public:chat",
"isResubscribe": true
}
error - error description
isResubscribe – flag showing if this was initial subscribe (false) or resubscribe (true)
I.e on("unsubscribe", function(context) {...})
{
"channel": "$public:chat"
}
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.
var subscription = centrifuge.subscribe("news", function(message) {
// handle message
});
subscription.presence().then(function(message) {
// presence data received
}, 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:
{
"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"
}
}
}
As you can see presence data is a map where keys are client IDs and values are objects with client information.
Format of err in error callback:
{
"code": 0,
"message": "timeout"
}
code - error code (number)message – error description (string)Note, that in order presence to work corresponding options must be enabled in server channel configuration (on top level or for channel namespace)
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.
var subscription = centrifuge.subscribe("news", function(message) {
// handle message
});
subscription.presenceStats().then(function(resp) {
// presence stats data received
}, function(err) {
// presence stats call failed with error
});
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.
var subscription = centrifuge.subscribe("news", function(message) {
// handle message
});
subscription.history().then(function(response) {
// history messages received
}, function(err) {
// history call failed with error
});
Success callback response format:
{
"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:
resp = await subscription.history({'since': {'offset': 2, 'epoch': 'xcf4w'}, limit: 100});
If server can't fulfill a query for history (due to stream retention - size or expiration, or malformed offset, or stream already has another epoch) then an Unrecoverable Position Error will be returned (code 112).
To only call for current offset and epoch use:
resp = await subscription.history({limit: 0});
I.e. not providing since and using zero limit.
For now history pagination feature only works with Centrifuge library based server and not available in Centrifugo.
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.
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.
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.
var subscription = centrifuge.subscribe("news", function(message) {
// handle message
});
subscription.publish({"input": "hello world"}).then(function() {
// success ack from Centrifugo received
}, function(err) {
// publish call failed with error
});
});
err format – the same as for presence method.
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
You can call unsubscribe method to unsubscribe from subscription:
subscription.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():
subscription.unsubscribe();
subscription.removeAllListeners();
You can restore subscription after unsubscribing calling .subscribe() method:
subscription.subscribe();
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.
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:
var subscription = centrifuge.subscribe("news", function(message) {
// handle message;
});
// 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
});
// one of subscribeSuccessHandler (or subscribeErrorHandler) will be called
// only if subscription already subscribed (or subscribe request already failed).
anotherSubscription.ready(subscribeSuccessHandler, subscribeErrorHandler);
}, 5000);
When called callback and errback of ready method receive the same arguments as
callback functions for subscribe and error events of subscription.
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.
You can start collecting messages to send calling startBatching() method:
centrifuge.startBatching();
Finally if you don't want batching anymore call stopBatching() method:
centrifuge.stopBatching();
This call will flush all collected messages to network.
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.
You can subscribe on private channel as usual:
centrifuge.subscribe('$private', function(message) {
// process message
});
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.
{
"client": "<CLIENT ID>",
"channels": ["$chan1", "$chan2"]
}
Your server should validate all these subscriptions and return properly constructed response.
Response is a JSON with array channels field on top level:
{
"channels": [
{
"channel": "$chan1",
"token": "<SUBSCRIPTION JWT TOKEN>"
},
{
"channel": "$chan2",
"token": <SUBSCRIPTION JWT TOKEN>
}
]
}
I.e. you need to return individual subscription tokens for each private channel in request. See how to generate private channel tokens in Centrifugo docs.
If you don't want to give client access to channel then just do not include it into response.
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.
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": [...]}}).
centrifuge-js v2.4.0 added support for server-side subscriptions. This means several new event handlers have been added.
The main one is publish event of Centrifuge instance to handle publications coming from server-side channels:
var centrifuge = new Centrifuge(address);
centrifuge.on('publish', function(ctx) {
const channel = ctx.channel;
const payload = JSON.stringify(ctx.data);
console.log('Publication from server-side channel', channel, payload);
});
centrifuge.connect();
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.
For example:
centrifuge.on('subscribe', function(ctx) {
console.log('Subscribe to server-side channel ' + ctx.channel);
});
centrifuge.on('unsubscribe', function(ctx) {
console.log('Unsubscribe from server-side channel ' + ctx.channel);
});
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:
{
"token": "<ACTUAL JWT TOKEN>"
}
To import client with Protobuf protocol support:
<script src="https://cdn.jsdelivr.net/gh/centrifugal/centrifuge-js@2.X.X/dist/centrifuge.protobuf.min.js"></script>
Or if you are developing with npm:
import Centrifuge from 'centrifuge/dist/centrifuge.protobuf';
This client uses 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:
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):
var centrifuge = new Centrifuge('ws://centrifuge.example.com/connection/websocket', {
protocol: 'protobuf'
});
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 library):
<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
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:
npm install ws
At this point you have 2 options. Explicitly pass WebSocket object to Centrifuge.
const Centrifuge = require('centrifuge');
const WebSocket = require('ws');
var centrifuge = new Centrifuge('ws://localhost:8000/connection/websocket', {
websocket: WebSocket
})
Or define it globally:
const Centrifuge = require('centrifuge');
global.WebSocket = require('ws');
var centrifuge = new Centrifuge('ws://localhost:8000/connection/websocket')
The same if you want to use SockJS:
const Centrifuge = require('centrifuge');
const SockJS = require('sockjs-client');
var centrifuge = new Centrifuge('ws://localhost:8000/connection/sockjs', {
sockjs: SockJS
})
To work with private channels you may need to pass XMLHttpRequest object to library:
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;
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:
var Centrifuge = require("centrifuge");
const WebSocket = require('ws');
const myWs = function (options) {
return class wsClass extends WebSocket {
constructor(...args) {
super(...[...args, ...[options]])
}
}
}
It should be now possible to use pass your custom WebSocket constructor to centrifuge-js and so custom headers will be used when connecting to a server:
var centrifuge = new Centrifuge('ws://localhost:8000/connection/websocket', {
websocket: myWs({ headers: { Authorization: '<token or key>' } }),
});
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).
centrifuge.subscribe('channel', function(messageCtx) {
console.log('new message', messageCtx);
}, {'since': {'offset': 0, 'epoch': '<EPOCH>'}});
FAQs
JavaScript client SDK for bidirectional communication with Centrifugo and Centrifuge-based server from browser, NodeJS and React Native
The npm package centrifuge receives a total of 60,009 weekly downloads. As such, centrifuge popularity was classified as popular.
We found that centrifuge demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.
Security News
require(esm) backported to Node.js 20, easing the transition to ESM-only packages and reducing complexity for developers as Node 18 nears end-of-life.
Security News
PyPI now supports iOS and Android wheels, making it easier for Python developers to distribute mobile packages.