Skip to main content

Connections API

Centrifugo PRO offers an extra API call, connections, which enables retrieval of all active sessions (based on user ID or expression) without the need to activate the presence feature for channels. Furthermore, developers can attach any desired JSON payload to a connection that will then be visible in the result of the connections call. It's worth noting that this additional meta-information remains hidden from the client-side, unlike the info associated with the connection.

This feature serves a valuable purpose in managing active user sessions, particularly for messenger applications. Users can review their current sessions and terminate some of them using the Centrifugo disconnect server API.

Moreover, this feature can help developers investigate issues by providing insights into the system's state.

Example

Let's look at the quick example. First, generate a JWT for user 42:

$ centrifugo genconfig

Generate token for some user to be used in the example connections:

$ centrifugo gentoken -u 42
HMAC SHA-256 JWT for user 42 with expiration TTL 168h0m0s:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MiIsImV4cCI6MTYyNzcxMzMzNX0.s3eOhujiyBjc4u21nuHkbcWJll4Um0QqGU3PF-6Mf7Y

Run Centrifugo with uni_http_stream transport enabled (it will allow us connecting from the terminal with curl):

CENTRIFUGO_UNI_HTTP_STREAM=1 centrifugo -c config.json

Create new terminal window and run:

curl -X POST http://localhost:8000/connection/uni_http_stream --data '{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MiIsImV4cCI6MTYyNzcxMzMzNX0.s3eOhujiyBjc4u21nuHkbcWJll4Um0QqGU3PF-6Mf7Y", "name": "terminal"}'

In another terminal create one more connection:

curl -X POST http://localhost:8000/connection/uni_http_stream --data '{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MiIsImV4cCI6MTYyNzcxMzMzNX0.s3eOhujiyBjc4u21nuHkbcWJll4Um0QqGU3PF-6Mf7Y", "name": "terminal"}'

Now let's call connections over HTTP API:

curl --header "Content-Type: application/json" \
--header "X-API-Key: <API_KEY>" \
--request POST \
--data '{"user": "42"}' \
http://localhost:8000/api/connections

The result:

{
"result": {
"connections": {
"db8bc772-2654-4283-851a-f29b888ace74": {
"app_name": "terminal",
"transport": "uni_http_stream",
"protocol": "json"
},
"4bc3ca70-ecc5-439d-af14-a78ae18e31c7": {
"app_name": "terminal",
"transport": "uni_http_stream",
"protocol": "json"
}
}
}
}

Here we can see that user has 2 connections from terminal app.

Each connection can be annotated with meta JSON information which is set during connection establishment (over meta claim of JWT or by returning meta in the connect proxy result).

connections

Returns information about active connections according to the request.

connections params

Parameter nameParameter typeRequiredDescription
userstringnofast filter by User ID
expressionstringnoCEL expression to filter users

connections result

Field nameField typeOptionalDescription
connectionsmap[string]ConnectionInfonoactive user connections map where key is client ID and value is ConnectionInfo

ConnectionInfo

Field nameField typeOptionalDescription
app_namestringyesclient app name (if provided by client)
app_versionstringyesclient app version (if provided by client)
transportstringnoclient connection transport
protocolstringnoclient connection protocol (json or protobuf)
userstringyesclient user ID
stateConnectionStateyesconnection state

ConnectionState object

Field nameField typeOptionalDescription
channelsmap[string]ChannelContextyesChannels client subscribed to
connection_tokenConnectionTokenInfoyesinformation about connection token
subscription_tokensmap<string, SubscriptionTokenInfo>yesinformation about channel tokens used to subscribe
metaJSON objectyesmeta information attached to a connection

ChannelContext object

Field nameField typeOptionalDescription
sourceintyesThe source of channel subscription

ConnectionTokenInfo object

Field nameField typeOptionalDescription
uidstringyesunique token ID (jti)
issued_atintyestime (Unix seconds) when token was issued

SubscriptionTokenInfo object

Field nameField typeOptionalDescription
uidstringyesunique token ID (jti)
issued_atintyestime (Unix seconds) when token was issued