Справочник WebSocket API

Точка подключения

ws://host/api/v2/dashboard/ws
wss://host/api/v2/dashboard/ws  (продуктивная среда)

Подключение

Параметры запроса

Параметр Тип Обязательный Описание
token string Нет* JWT-токен аутентификации

*При включённом мультитенантном режиме токен обязателен: либо как параметр запроса, либо в первом сообщении.

Аутентификация (WS3.4)

  1. Параметр запроса: ws://host/api/v2/dashboard/ws?token=<JWT>
  2. Первое сообщение: отправьте {"token": "<JWT>"} в течение 5 секунд после подключения

При неудачной аутентификации сервер отправляет:

{"event": "error", "message": "Authentication required"}

и закрывает соединение с кодом 1008.

Формат сообщений

Все сообщения — строки в формате JSON.

События сервер -> клиент

connected

Отправляется сразу после успешного подключения:

{
  "event": "connected",
  "client_id": "ws-1",
  "heartbeat_seconds": 30
}

heartbeat

Отправляется каждые N секунд (настраивается, по умолчанию 30):

{
  "event": "heartbeat",
  "timestamp": 1710700000.123,
  "clients": 3
}

project_updated

Отправляется при завершении аудита, проверки соответствия или контроля выпуска:

{
  "event": "project_updated",
  "project_name": "my-project",
  "trigger": "audit",
  "timestamp": 1710700000.123
}

pong

Ответ на клиентский ping:

{"event": "pong"}

Сообщения клиент -> сервер

Сообщение Описание
ping Поддержание соединения, сервер отвечает pong

Настройка

В config.yaml:

dashboard:
  websocket_enabled: true
  websocket_heartbeat_seconds: 30

Пример клиента на JavaScript

const protocol = location.protocol === "https:" ? "wss:" : "ws:";
const ws = new WebSocket(`${protocol}//${location.host}/api/v2/dashboard/ws`);

ws.onopen = () => console.log("Подключено");

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.event) {
    case "connected":
      console.log("ID клиента:", msg.client_id);
      break;
    case "project_updated":
      console.log("Обновлён:", msg.project_name);
      // Обновить данные панели мониторинга
      break;
    case "heartbeat":
      break;
  }
};

ws.onclose = () => {
  // Переподключение через 5 секунд
  setTimeout(() => connect(), 5000);
};

React-хук

Панель мониторинга предоставляет хук useWebSocket:

import { useWebSocket } from "@/hooks/useWebSocket";

function Dashboard() {
  const { connected, lastMessage } = useWebSocket((projectName) => {
    // Вызывается при получении события project_updated
    refetchData();
  });

  return <div>WS: {connected ? "подключено" : "отключено"}</div>;
}