Подключите открытый дашборд к событиям обновления проекта после подготовки отчёта аудита. Сервер отправляет project_updated с именем проекта и источником события. Клиент перечитывает нужные REST-ресурсы и обновляет экран. Справочник объясняет разработчику интерфейса аутентификацию, поля событий и восстановление соединения.
Подготовка
Настройте сервер и войдите в приложение, чтобы получить JWT текущей сессии.
Включите dashboard.websocket_enabled: по умолчанию этот канал отключён.
Дашборд должен иметь доступ к API и функцию обновления данных проекта через
REST API.
Адрес подключения
wss://codegraph.example/api/v1/traceability/ws
Используйте ws только в доверенной локальной HTTP-среде. Страница, открытая по HTTPS, должна подключаться через wss.
Аутентификация
Передайте токен первым сообщением. Если в URL есть непустой параметр token, сервер отклоняет HTTP handshake со статусом 403 до открытия WebSocket. Обработчик использует причину отказа Query token transport is not allowed.
Сервер принимает WebSocket и в течение 5 секунд ждёт первое сообщение клиента. Передайте объект с JWT:
{"token": "<JWT>"}
Сервер также принимает строку с токеном, но документированный контракт — JSON-объект. При ошибке аутентификации сервер отправляет событие error и закрывает соединение кодом 1008. Если первое сообщение не пришло за 5 секунд, соединение закрывается по тайм-ауту аутентификации.
Если превышен лимит подключений, сервер закрывает соединение кодом 1008
с причиной WebSocket rate limit exceeded, без события connected.
Работа без токена разрешена только при явно включённом локальном режиме и адресах обратной петли клиента и запрошенного хоста.
События
Каждое сообщение дашборда — JSON-объект. Поле event определяет событие, остальные поля содержат его данные.
| event | Когда отправляется | Значимые поля |
|---|---|---|
| connected | Аутентификация и проверка квоты прошли | client_id, heartbeat_seconds |
| heartbeat | До истечения heartbeat-интервала клиент ничего не отправил | timestamp, clients |
| project_updated | Завершён отчёт аудита или другой источник вызвал функцию рассылки | project_name, trigger, timestamp |
| pong | Клиент отправил текст ping | нет |
| error | После открытия соединения не прошла аутентификация или превышен лимит сообщений | message |
Сервер рассылает событие project_updated всем подключённым клиентам. Событие содержит имя проекта, источник и время. По этим данным выберите ресурсы REST API для обновления.
По project_name выберите ресурсы дашборда для обновления. Поле trigger называет источник, который запросил обновление, а timestamp содержит время создания события в секундах Unix.
Пример для браузера
Добавьте функцию в код аутентифицированного дашборда. Передайте действующий JWT и функцию
refreshDashboardResources(projectName), которая перечитывает нужные REST-ресурсы проекта.
Адрес берётся из location.host: пример предполагает общий хост страницы и API.
function connectDashboardSocket(accessToken, refreshDashboardResources) {
const scheme = location.protocol === "https:" ? "wss:" : "ws:";
const socket = new WebSocket(
scheme + "//" + location.host + "/api/v1/traceability/ws"
);
socket.addEventListener("open", () => {
socket.send(JSON.stringify({ token: accessToken }));
});
socket.addEventListener("message", async (event) => {
const message = JSON.parse(event.data);
if (message.event === "project_updated") {
await refreshDashboardResources(message.project_name);
}
});
return socket;
}
Вызовите connectDashboardSocket с токеном текущей сессии и существующей функцией обновления ресурсов. Функция возвращает экземпляр WebSocket. После успешной аутентификации сервер отправляет connected с идентификатором клиента и интервалом heartbeat. Каждое событие project_updated вызывает вашу функцию обновления с именем проекта. Когда дашборд закрывается, вызовите socket.close().
Храните токен в памяти сессии; исключите его из URL и логов.
Heartbeat и переподключение
После настроенного интервала без входящих сообщений сервер отправляет heartbeat. Клиент может передать обычный текст ping и получить событие pong.
Переподключайтесь с ограниченным экспоненциальным увеличением задержки и случайным разбросом. Если сессия истекла, до повторного подключения получите свежий токен. Не повторяйте соединение непрерывно после кода 1008: сначала устраните проблему аутентификации, конфигурации или лимитов запросов.
После восстановления соединения перечитайте ресурсы дашборда через REST: события, возникшие во время разрыва, не воспроизводятся.
Конфигурация
dashboard:
websocket_enabled: true
websocket_heartbeat_seconds: 30
Эффективный heartbeat ограничен runtime-тайм-аутом WebSocket ping. Изменение конфигурации требует штатного процесса развёртывания и перезапуска для установки.
Для чата, прогресса задач и пользовательских уведомлений используйте WebSocket API приложения.