Centrifugo

Назначение

Сервер real-time доставки сообщений WebSocket-клиентам. Интегрирован с NATS через брокер. Предоставляет каналы для push-уведомлений о событиях платформы: задачи, исполнители, пайплайны, AI-чат, concierge.

Архитектура взаимодействия

Клиент (браузер) → Gateway (JWT token) → Centrifugo (WebSocket, порт 8100)
Внешний Concierge UI → concierge (socket-token) → Centrifugo
                                                ↑
                                    NATS Bridge  |  Concierge HTTP API
                                                ↑
                                             NATS
                                                ↑
                                   Бэкенд-сервисы (pub events)

1. Основной клиент аутентифицируется через Gateway → получает JWT token (GET /api/v1/centrifugo/token)
2. Внешний Concierge UI берёт токен у concierge (GET /api/v1/auth/socket-token)
3. Клиент подключается к Centrifugo через WebSocket (порт 8100)
4. Бэкенд-сервисы публикуют события в NATS; NATS Bridge оборачивает их в EventEnvelope и шлёт в Centrifugo HTTP API
5. Concierge публикует в Centrifugo напрямую (каналы concierge:*), минуя NATS Bridge
6. Centrifugo доставляет события подключённым клиентам

Порты

Порт	Назначение
8100	WebSocket и HTTP API (один http_server)

Пространства каналов (Namespaces)

Namespace	Описание
user	Пользовательские события (inbox)
job	События задач (jobs)
executor	События исполнителей
pipeline	События пайплайнов
ai	Стриминг AI-чата и tool-call'ы
mcp	MCP session/tool events
tasks	Изменения Task Tracker (tasks:broadcast)
concierge	Внешний портал: concierge:user:{id}, concierge:admin

Маршрутизация каналов

• Если событие содержит user_id → персональный канал: <namespace>:user:<user_id>
• Если user_id отсутствует → broadcast: <namespace>:broadcast

Маппинг NATS → Centrifugo

NATS Subject	Namespace	Канал
job.created	job	job:user:<id> / job:broadcast
job.changed	job	job:user:<id> / job:broadcast
executor.status	executor	executor:user:<id> / executor:broadcast
runner.change	executor	executor:user:<id> / executor:broadcast
pipeline.test.>	pipeline	pipeline:user:<id> / pipeline:broadcast
tasks.>	tasks	tasks:broadcast
ai.chat.*	ai	ai:user:<id> / ai:broadcast
mcp.*	mcp	mcp:user:<id> / mcp:broadcast
inbox.created	user	user:user:<id>

События concierge в эту таблицу не входят: сервис concierge пишет в Centrifugo сам (см. concierge.md).

EventEnvelope (формат)

{
  "id": "<UUID v4>",
  "type": "<NATS subject>",
  "data": { ... },
  "timestamp": "<RFC 3339 UTC>"
}

Конфигурация

Файл: centrifugo/config.json

Переменная	Описание	По умолчанию
CENTRIFUGO_CLIENT_TOKEN_HMAC_SECRET_KEY	HMAC секрет для JWT (должен совпадать с JWT_SECRET Gateway)	—
CENTRIFUGO_HTTP_API_KEY	API ключ для HTTP API	—
CENTRIFUGO_BROKER_NATS_URL	URL NATS-брокера	nats://localhost:4222
CENTRIFUGO_PORT	Порт WebSocket и HTTP API	8100
CENTRIFUGO_TOKEN_TTL	TTL connection-токена	5m
CENTRIFUGO_NATS_PREFIX	Префикс NATS subjects	centrifugo

Обязательные переменные: MESSAGING_URL, CENTRIFUGO_API_KEY, CENTRIFUGO_TOKEN_HMAC_SECRET_KEY.