Connections API
Centrifugo PRO provides an additional API call connections
. It allows getting all active sessions of the user (by user ID) without turning on presence feature for channels at all. It's also possible to attach any JSON payload to a connection which will be then visible in the result of connections
call. The important thing is that this additional meta information won't be exposed to a client-side (unlike connection info
for example).
This feature can be useful to manage active user sessions – for example in a messenger application. Users can look at a list of own current sessions and close some of them (possible with Centrifugo disconnect server API).
Also, it can help developers to understand the system state during issue investigations.
Let's look at example. Generate a JWT for user 42:
centrifugo genconfig
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 to connect from console):
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 "Authorization: apikey <API_KEY>" \
--request POST \
--data '{"method": "connections", "params": {"user": "42"}}' \
http://localhost:8000/api
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 connect proxy result).
User connections params
Parameter name | Parameter type | Required | Description |
---|---|---|---|
user | string | no | fast filter by User ID |
expression | string | no | CEL expression to filter users |
User connections result
Field name | Field type | Optional | Description |
---|---|---|---|
connections | map of string to UserConnectionInfo | no | active user connections map where key is client ID and value is UserConnectionInfo |
UserConnectionInfo
Field name | Field type | Optional | Description |
---|---|---|---|
app_name | string | yes | client app name (if provided by client) |
app_version | string | yes | client app version (if provided by client) |
transport | string | no | client connection transport |
protocol | string | no | client connection protocol (json or protobuf) |
state | ConnectionState | yes | connection state |
ConnectionState object
Field name | Field type | Optional | Description |
---|---|---|---|
channels | array of strings | yes | Channels client subscribed to |
connection_token | ConnectionTokenInfo | yes | information about connection token |
subscription_tokens | map<string, SubscriptionTokenInfo> | yes | information about channel tokens used to subscribe |
meta | JSON object | yes | meta information attached to a connection |
ConnectionTokenInfo object
Field name | Field type | Optional | Description |
---|---|---|---|
uid | string | yes | unique token ID (jti) |
issued_at | int | yes | time (Unix seconds) when token was issued |
SubscriptionTokenInfo object
Field name | Field type | Optional | Description |
---|---|---|---|
uid | string | yes | unique token ID (jti) |
issued_at | int | yes | time (Unix seconds) when token was issued |