Skip to main content

Unidirectional WebSocket

Default unidirectional WebSocket connection endpoint in Centrifugo is:

/connection/uni_websocket

While WebSocket is bidirectional transport in its nature Centrifugo provides its unidirectional version too to give developers more choice in transports when using unidirectional approach.

Connect command

It's possible to send connect command as first WebSocket message (as JSON).

Field nameField typeRequiredDescription
tokenstringnoConnection JWT, not required when using the connect proxy feature.
dataany JSONnoCustom JSON connection data
namestringnoApplication name
versionstringnoApplication version
subsmap of channel to SubscribeRequestnoPass an information about desired subscriptions to a server

SubscribeRequest

Field nameField typeRequiredDescription
recoverbooleannoWhether a client wants to recover from a certain position
offsetintegernoKnown stream position offset when recover is used
epochstringnoKnown stream position epoch when recover is used

Supported data formats

JSON

Pings

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).

Options

uni_websocket

Boolean, default: false.

Enables unidirectional WebSocket endpoint.

config.json
{
...
"uni_websocket": true
}

uni_websocket_message_size_limit

Default: 65536 (64KB)

Maximum allowed size of a first connect message received from WebSocket connection in bytes.

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:

config.json
{
"token_hmac_secret_key": "secret",
"uni_websocket":true,
"user_subscribe_to_personal": 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.