Centrifugo

Getting Started

Взять можно тут https://github.com/centrifugal/centrifugo/releases

Я взял deb пакет и установил через dpkg -i
Он предоставляет и systemd-unit, поэтому вдвойне удобно

Далее нужно сгенерить конфиг:

root@centrifugo:~# centrifugo genconfig -c /etc/centrifugo/config.json
root@centrifugo:~# cat /etc/centrifugo/config.json
{
  "token_hmac_secret_key": "b06abc67-5044-415e-afff-843be892519c",
  "admin_password": "9a722c80-6f7a-4f8f-b5a5-a343e6e4c235",
  "admin_secret": "e01a905e-220d-4d6f-84a4-d6d33ada1105",
  "api_key": "f71f267a-423b-4d10-a080-8f00bf9bc811",
  "allowed_origins": []
}

Если не указывать путь куда генерить то сгенерить туда где ты находишься

Добавляем в конфиг "admin": true и рестартим (после просто релоада админка не заработает, надо рестартить)
Становится доступна админка:
Screenshot_2021_02_02-12_49_03-2022-05-26-at-1centrifugo-admin-web.png

Вводим admin_password из конфига и можно тыкать кнопки

Для того чтобы клиент мог подключиться, нужно сгенерировать ему токен:

centrifugo gentoken -u 123722 # число это айдишник юзера (тут случайный)

А так же нужно прописать в конфиге в allowed_origins разрешенные сайты
(Когда клиент запрашивает апгрейд протокола на websocket, то передает http-заголовок Origin, этот ориджин и должен быть в конфиге)
Screenshot_2021_02_02-12_49_03-2022-05-26-at-17websocketupgrade.png

vandud@centrifugo:~$ cat /etc/centrifugo/config.json
{
  "token_hmac_secret_key": "b06abc67-5044-415e-afff-843be892519c",
  "admin_password": "9a722c80-6f7a-4f8f-b5a5-a343e6e4c235",
  "admin_secret": "e01a905e-220d-4d6f-84a4-d6d33ada1105",
  "api_key": "f71f267a-423b-4d10-a080-8f00bf9bc811",
  "allowed_origins": [
    "http://51.250.23.143"
  ],
  "admin": true
}

diagram_unidirectional_publish-791f0862f2aa9632dec9c3515bcdc6ea.png

diagram_publish_proxy-66ccb1e8b37ed8912d218b4529597bd9.png

Server Guide

Server Guide

Configure Centrifugo

Центрифугу можно конфигурировать разными способами:

Существуют internal endpoints которые не должны быть доступны через интернет
Они выделены в отдельную группу и все вместе могут быть вынесены на отдельный порт с помощью опции internal_port

Эндпоинты можно переопределять в конфиге:
Переопределим endpoint для метрик

root@centrifugo:/etc/centrifugo# tail -n 5 config.yaml
health: true
log_level: debug
prometheus: true
debug: true
prometheus_handler_prefix: /metricosy

И вот результат

(yc-zeen-pro-00:default) vandud@macbook: ~ [0] ? curl -I http://51.250.23.143:8000/metrics
HTTP/1.1 404 Not Found
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff
Date: Thu, 26 May 2022 16:37:21 GMT
Content-Length: 19

(yc-zeen-pro-00:default) vandud@macbook: ~ [0] ? curl -I http://51.250.23.143:8000/metricosy
HTTP/1.1 200 OK
Content-Type: text/plain; version=0.0.4; charset=utf-8
Date: Thu, 26 May 2022 16:37:23 GMT
Server Guide

Console Commands

Есть команда для валидации конфига

centrifugo checkconfig --config=config.json

Результат работы это exit-code 1 или 0

genconfig может генерить базовый конфиг в трех форматах (json, toml, yaml)
Для этого нужно указать расширение файла конфига

root@centrifugo:~# centrifugo genconfig -c config.json
root@centrifugo:~# centrifugo genconfig -c config.toml
root@centrifugo:~# centrifugo genconfig -c config.yaml

Результат три файла в разных форматах:

root@centrifugo:~# bat *
───────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
       │ File: config.json
───────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
   1   │ {
   2   │   "token_hmac_secret_key": "74dbbf71-d05b-43ec-8f32-4d8f94a6ed76",
   3   │   "admin_password": "152232c9-4b97-4f3d-aba6-192af509c629",
   4   │   "admin_secret": "2693d15d-cfbb-4129-be4f-30c5a9836b22",
   5   │   "api_key": "8fa3f035-72c1-4d93-8fb6-cf2054792b91",
   6   │   "allowed_origins": []
   7   │ }
───────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
───────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
       │ File: config.toml
───────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
   1   │ token_hmac_secret_key = "0b32b520-b7c5-48ab-92b0-a9e0f26551f7"
   2   │ admin_password = "1196c810-1288-404a-8ab8-571149a59bb0"
   3   │ admin_secret = "aeeae78e-f826-40a3-9e89-b9d4d24a6d92"
   4   │ api_key = "ee59c24a-fc54-439d-b0ee-d58b7bde9c3f"
   5   │ allowed_origins = []
───────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
───────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
       │ File: config.yaml
───────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
   1   │ token_hmac_secret_key: 5e951b11-4a68-4970-bb1c-dd010eca21f3
   2   │ admin_password: 95dbf047-7cb0-4310-9c4a-ecc5c79df0c0
   3   │ admin_secret: 47f63e69-f48f-4fce-8cea-2f48921a872a
   4   │ api_key: da653ff6-f3d9-4cc2-9ef7-f8851f9d9f2f
   5   │ allowed_origins: []
───────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

gentoken/checktoken позволяют генерить и проверять токены

root@centrifugo:~# centrifugo gentoken -c /etc/centrifugo/config.yaml -t 3600 -u 2
HMAC SHA-256 JWT for user 2 with expiration TTL 1h0m0s:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyIiwiZXhwIjoxNjUzNTg3OTI4fQ.Qp1RPsIU-bQTnLr3lec0o34oJ7Hm42OOV5ctgAtXCIc

root@centrifugo:~# centrifugo checktoken -c /etc/centrifugo/config.yaml eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyIiwiZXhwIjoxNjUzNTg3OTI4fQ.Qp1RPsIU-bQTnLr3lec0o34oJ7Hm42OOV5ctgAtXCIc
{"level":"info","algorithms":"HS256, HS384, HS512","time":"2022-05-26T16:59:12Z","message":"enabled JWT verifiers"}
valid token for user 2
payload: {"sub":"2","exp":1653587928}
Server Guide

Server API

У центрифуги есть два варианта работы с API: HTTP и GRPC
Будет рассмотрен только HTTP вариант

Чтобы использовать апи нужно в нем аутентифицироваться
Для этого в заголовке нужно передать api_key из конфига

Authorization: apikey <KEY>

В теле запроса нужно передать json с двумя обязательными сущностями:

{
  "method": "info", 
  "params": {}
}

Получается такая штука:

? curl -s -X POST --header "Authorization: apikey f71f267a-423b-4d10-a080-8f00bf9bc811" \
--data '{"method": "info", "params": {}}' http://51.250.23.143:8000/api | jq | head -n 20
{
  "result": {
    "nodes": [
      {
        "uid": "b1499040-5927-4ffc-af9c-f6111b71ec53",
        "name": "centrifugo_8000",
        "version": "3.2.0",
        "num_clients": 2,
        "num_users": 1,
        "num_channels": 1,
        "uptime": 10793,
        "metrics": {
          "interval": 60,
          "items": {
            "centrifugo.api.command_duration_seconds.count.method.info.protocol.http": 10,
            "centrifugo.api.command_duration_seconds.quantile.50.method.info.protocol.http": 5.174e-06,
            "centrifugo.api.command_duration_seconds.quantile.99.method.info.protocol.http": 1.6736e-05,
            "centrifugo.api.command_duration_seconds.quantile.999.method.info.protocol.http": 1.6736e-05,
            "centrifugo.api.command_duration_seconds.sum.method.info.protocol.http": 6.281499999999905e-05,
            "centrifugo.client.command_duration_seconds.count.method.connect": 0,
            ...

Методы

Server Guide

Client Authentication

Клиенты могут аутентифицироваться по JWT

diagram_jwt_authentication-6a769cc8f218228df5954d240b2057cc.png

Центрифуга использует следующие ключи из JWT:

Server Guide

Channels

Channel name rules

Канал это маршрут для публикаций
Клиенты подписываются на канал и получают сообщения опубликованные в него

Каналы эфемерны, их не надо создавать или удалять явно, они существуют пока существуют подписчики (подписчик подписался - канал создался, подписчиков не осталось - канал удалился)
Соответственно чтобы было куда публиковать сообщения, нужно чтобы были подписчики

Неймспейсы позволяют определять кастомные опции для групп каналов

Имя канала может содержать только ASCII символы и быть не длиннее 255 символов
Несколько символов зарезервированы:

Channel options

Используя опции можно изменять поведение каналов глобально или per namespace

Опции можно прописывать в корне конфига (тогда они будут глобальными), а можно описать для каждого неймспейса отдельно

{
    "token_hmac_secret_key": "very-long-secret-key",
    "api_key": "secret-api-key",
    "anonymous": true,
    "publish": true,
    "presence": true,
    "join_leave": true,
    "history_size": 10,
    "history_ttl": "30s",
    "namespaces": [
        {
          "name": "public",
          "publish": true,
          "anonymous": true,
          "history_size": 10,
          "history_ttl": "300s",
          "recover": true
        },
        {
          "name": "gossips",
          "presence": true,
          "join_leave": true
        }
    ]
}
Server Guide

Engines, scalability

Engine отвечает за паблишинг между нодами, хранение presence и истории
По умолчанию используется движок Memory. Доступны еще Redis, KeyDB и Tarantool
Memory engine позволяет использовать только одну ноду, Редис позволяет запустить несколько нод на разных машинах с подключением через pub/sub, все ноды будут знать друг про друга, будут хранить историю и presence в редисе, а не в памяти, и данные будут доступны на каждой ноде и не будут теряться при рестартах

Движок задается опцией engine в конфиге, возможные значения: memory, redis и tarantool (по умолчанию memory)

Memory Engine

Все данные хранятся в памяти процесса. Это работает быстро но это невозможно масштабировать
Для memory enginge в конфиге доступна опция history_meta_ttl, ее можно задать чтобы не было утечек памяти

Redis Engine

Redis engine позволяет масштабировать центрифугу (потому что данные хранятся во внешнем хранилище)
Для redis engine в конфиге доступно несколько опций:

Центрифуга имеет встроенную поддержку шардинга редисов (но шардятся только данные, общего pub/sub у них не будет)
Пример конфига:

{
    ...
    "engine": "redis",
    "redis_address": [
        "192.168.1.34:6379",
        "192.168.1.35:6379",
    ]
}
Server Guide

Proxy

Можно проксировать некоторые запросы от клиентов к бэкенду сквозь центрифугу
Подробно тут https://centrifugal.dev/docs/server/proxy

Server Guide

History and recovery

Центрифуга может хранить историю публикаций

История конфигурируется на уровне неймспейса
Чтобы она была включена, нужно чтобы опции history_size и history_ttl имели значения больше нуля

Каждая публикация в истории имеет поле offset - это инкрементное uint64 поле
Каждый стрим (redis stream) идентифицируется по полю epoch

Центрифуга предоставляет механизм восстановления данных из истории, это полезно когда клиент находился какое-то небольшое время в автономном режиме (например мигнула сеть), вместо того чтобы клиент шел к бэкенду и получал последние данные от него, он получает их от центрифуги
Таким образом если мигнула сеть на продакшене или мигнул балансер, то все наши клиенты не ломанутся одновременно к бэкенду, а получат данные от центрифуги

Чтобы включить этот механизм нужно в конфиге проставить опцию recover в true (глобально или для неймспейса)

Server Guide

Admin web UI

У центрифуги есть встроенный web ui, он позволяет просматривать инфу и статистику по нодам и выполнять команды (паблишить, подписывать итд)
В конфиге есть соответствующие опции:

{
    "admin": true,
    "admin_password": "<PASSWORD>",
    "admin_secret": "<SECRET>"
}

Можно использовать кастомную вебню
Например отредактировать стандартную https://github.com/centrifugal/web и заставить центрифугу использовать ее
Для этого в конфиге нужно в опции admin_web_path указать путь до новой вебни

Можно указать опцию admin_insecure со значением true и тогда админка не будет просить пароль (но так делать не надо)

Server Guide

Configure TLS

Лучше переложить задачу терминирования tls на прокси или балансировщик, но при необходимости центрифуга может делать это и самостоятельно
Для этого нужно указать в конфиге пути до серта и ключа

{
  ...
  "tls": true,
  "tls_key": "server.key",
  "tls_cert": "server.crt"
}

Еще можно заставить центрифугу выпускать серты самостоятельно (через LE)

{
  ...
  "tls_autocert": true,
  "tls_autocert_host_whitelist": "www.example.com",
  "tls_autocert_cache_dir": "/tmp/certs",
  "tls_autocert_email": "user@example.com",
  "tls_autocert_http": true,
  "tls_autocert_http_addr": ":80"
}