Unidirectional WebSocket
While WebSocket is bidirectional transport in its nature Centrifugo provides its unidirectional version too to give developers more choice in transports when using the unidirectional approach.
How to enable
{
"uni_websocket": {
"enabled": true
}
}
Default endpoint
Default unidirectional WebSocket connection endpoint in Centrifugo is:
/connection/uni_websocket
Send connect request
Once connection established you must pass ConnectRequest as first WebSocket message to server.
Supported data formats
JSON
Ping
Centrifugo uses empty commands ({}
in JSON case) as pings for unidirectional WS. You can ignore such messages or use them to detect broken connections (nothing received from a server for a long time).
uni_websocket
uni_websocket.enabled
Boolean, default: false
.
Enables unidirectional WebSocket endpoint.
{
"uni_websocket": {
"enabled": true
}
}
uni_websocket.message_size_limit
Default: 65536 (64KB)
Maximum allowed size of a first connect message received from WebSocket connection in bytes.
uni_websocket.join_push_messages
Boolean. Default: false
. New in Centrifugo v6.0.3
Once the option enabled, Centrifugo can join different messages going through unidirectional WebSocket into a single websocket frame. The messages are joined using the same approach as Centrifugo uses for bidirectional protocol. This means that for JSON case messages are joined with new line.
In other words, you can benefit from message batching and less system calls (which is positive for server CPU usage). But your client side must be prepared to decode the WebSocket message into separate Push
messages: For JSON case split by \n
:
const messages = data.trim().split('\n').map(r => JSON.parse(r));
Note, trim
is important since message may end on \n
too: {}\n{}\n
.
Example
Let's connect to a unidirectional WebSocket endpoint using wscat tool – it allows connecting to WebSocket servers interactively from a terminal.
First, run Centrifugo with uni_websocket
enabled. Also let's enable automatic personal channel subscriptions for users. Configuration example:
{
"client": {
"token": {
"hmac_secret_key": "secret"
},
"subscribe_to_user_personal_channel": {
"enabled": true
}
},
"uni_websocket": {
"enabled": true
}
}
Run Centrifugo:
./centrifugo -c config.json
In another terminal:
❯ ./centrifugo gentoken -c config.json -u test_user
HMAC SHA-256 JWT for user test_user with expiration TTL 168h0m0s:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ0ZXN0X3VzZXIiLCJleHAiOjE2MzAxMzAxNzB9.u7anX-VYXywX1p1lv9UC9CAu04vpA6LgG5gsw5lz1Iw
Install wscat and run:
wscat -c "ws://localhost:8000/connection/uni_websocket"
This will establish a connection with a server and you then can send connect command to a server:
❯ wscat -c "ws://localhost:8000/connection/uni_websocket"
Connected (press CTRL+C to quit)
> {"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ0ZXN0X3VzZXIiLCJleHAiOjE2NTY1MDMwNDV9.3UYL-UCUBp27TybeBK7Z0OenwdsKwCMRe46fuEjJnzI", "subs": {"abc": {}}}
< {"connect":{"client":"bfd28799-b958-4791-b9e9-b011eaef68c1","version":"0.0.0","subs":{"#test_user":{}},"expires":true,"ttl":604407,"ping":25,"session":"57b1287b-44ec-45c8-93fc-696c5294af25"}}
The connection will receive server pings (empty commands {}
) periodically. You can try to publish something to #test_user
or abc
channels (using Centrifugo server API or using admin UI) – and the message should come to the connection we just established.