Параметры конфигурации

Основой работы со STOMP.js является создание и настройка клиента, через который осуществляется подключение к брокеру сообщений. Поведение клиента полностью определяется набором параметров конфигурации, влияющих на транспорт, повторные подключения, обработку ошибок, heartbeat и форматирование кадров.

Конфигурация передаётся при создании экземпляра клиента и определяет его жизненный цикл. В современных версиях STOMP.js используется объект с полями, которые управляют как транспортным уровнем (WebSocket), так и логикой протокола STOMP.

Ключевые группы параметров:

  • параметры подключения
  • параметры протокола STOMP
  • параметры устойчивости соединения
  • параметры отладки и обработки событий

brokerURL и webSocketFactory

brokerURL

brokerURL задаёт адрес STOMP-брокера через WebSocket. Это основной способ подключения, когда WebSocket создаётся автоматически библиотекой.

Пример логики:

  • ws:// или wss:// для защищённого соединения
  • адрес напрямую указывает на endpoint брокера

Поведение:

  • если указан brokerURL, библиотека самостоятельно создаёт WebSocket
  • используется в стандартных сценариях без кастомной логики транспорта

webSocketFactory

webSocketFactory заменяет автоматическое создание WebSocket на пользовательскую реализацию.

Используется, когда:

  • требуется авторизация на уровне сокета
  • нужен SockJS вместо WebSocket
  • требуется проксирование или кастомные заголовки

Функция должна возвращать объект WebSocket-подобного интерфейса.

Ключевой момент:

  • при наличии webSocketFactory параметр brokerURL игнорируется

connectHeaders

connectHeaders определяет заголовки, отправляемые в момент STOMP-команды CONNECT.

Типичные данные:

  • login
  • passcode
  • authorization
  • кастомные метаданные клиента

Особенности:

  • отправляются один раз при установке соединения
  • могут быть динамически изменены перед реконнектом
  • часто используются для JWT-токенов

Важно учитывать:

  • заголовки не шифруются, если используется ws://
  • чувствительные данные требуют wss://

reconnectDelay

reconnectDelay управляет задержкой автоматического переподключения после разрыва соединения.

Поведение:

  • значение указывается в миллисекундах
  • 0 отключает автоматический reconnect
  • положительное значение включает стратегию повторных попыток

Типичная логика:

  • при потере соединения клиент ждёт указанное время
  • затем инициирует новое подключение

Дополнительный аспект:

  • повторные подключения не блокируют основной поток
  • состояние клиента сохраняется между попытками

heartbeatIncoming и heartbeatOutgoing

Heartbeat реализует механизм контроля «живости» соединения на уровне STOMP-протокола.

heartbeatOutgoing

Определяет интервал отправки heartbeat от клиента к серверу.

heartbeatIncoming

Ожидаемый интервал получения heartbeat от сервера.

Формат:

  • значения в миллисекундах
  • [outgoing, incoming]

Пример логики:

  • [10000, 10000] означает обмен каждые 10 секунд

Поведение:

  • при отсутствии heartbeat соединение считается мёртвым
  • автоматически инициируется reconnect (если включён)

Технический нюанс:

  • heartbeat работает поверх STOMP frame \n

debug

debug задаёт функцию логирования внутренних событий STOMP.js.

Назначение:

  • трассировка соединений
  • анализ кадров
  • диагностика ошибок протокола

Формат:

debug: (msg) => console.log(msg)

Особенности:

  • вызывается часто, включая низкоуровневые события
  • может существенно влиять на производительность
  • обычно отключается в production

reconnectDelayJitter (в расширенных реализациях)

Некоторые реализации добавляют случайную задержку к reconnect.

Назначение:

  • предотвращение «шторма переподключений»
  • распределение нагрузки на брокер

Поведение:

  • добавляется случайное значение к reconnectDelay
  • снижает синхронные попытки соединения множества клиентов

beforeConnect

beforeConnect — функция-хук, выполняемая перед каждой попыткой подключения.

Используется для:

  • обновления токенов
  • динамической подготовки заголовков
  • асинхронных проверок состояния

Особенность:

  • может быть async
  • блокирует начало подключения до завершения выполнения

Пример поведения:

  • обновление JWT перед reconnect
  • проверка валидности сессии

onConnect

onConnect вызывается после успешного установления STOMP-соединения.

Функциональность:

  • регистрация подписок
  • инициализация состояния приложения
  • запуск обмена сообщениями

Срабатывает:

  • после handshake WebSocket
  • после успешного STOMP CONNECTED

Важно:

  • вызывается при каждом reconnect
  • не только при первом подключении

onStompError

Обработчик ошибок уровня STOMP-протокола.

Типичные случаи:

  • отказ в авторизации
  • некорректные заголовки CONNECT
  • ошибки брокера

Сигнатура содержит:

  • frame с заголовками ошибки
  • текстовое описание проблемы

Поведение:

  • соединение может быть закрыто
  • зависит от политики брокера

onWebSocketError

Обработчик ошибок транспортного уровня WebSocket.

Отличие от STOMP-ошибок:

  • не связан с протоколом STOMP
  • относится к сетевым сбоям

Примеры:

  • отказ соединения TCP
  • сбой TLS
  • разрыв канала

onDisconnect

Вызывается при штатном или аварийном разрыве соединения.

Используется для:

  • очистки состояния подписок
  • уведомления UI
  • логирования причин отключения

Особенность:

  • может вызываться до reconnect цикла

connectionTimeout

Определяет максимальное время ожидания установления соединения.

Поведение:

  • если CONNECT не завершён за указанное время, соединение прерывается
  • инициируется ошибка подключения

Применение:

  • защита от зависших соединений
  • контроль медленных сетей

forceBinaryWS (в некоторых реализациях)

Указывает использовать бинарный режим WebSocket, если доступен.

Назначение:

  • оптимизация передачи больших сообщений
  • уменьшение накладных расходов сериализации

appendMissingNULLonIncoming / outgoing

Параметры контроля завершения STOMP-фреймов.

  • outgoing: добавляет завершающий NULL символ при отправке
  • incoming: ожидает и корректирует входящие сообщения

Назначение:

  • соответствие спецификации STOMP 1.2
  • предотвращение ошибок парсинга кадров

splitLargeFrames

Управляет разбиением больших сообщений на части.

Поведение:

  • включение позволяет разделять крупные payload
  • полезно при ограничениях брокера

Риски:

  • увеличение накладных расходов
  • необходимость корректной сборки на сервере

STOMP версия и согласование протокола

Некоторые клиенты позволяют задавать версию STOMP через конфигурацию.

Влияние:

  • влияет на формат handshake
  • определяет доступные команды и заголовки
  • STOMP 1.0, 1.1, 1.2 имеют различия в heartbeat и заголовках

Поведение клиента при изменении конфигурации

Конфигурация обычно применяется:

  • до подключения
  • не изменяется «на лету» без реконнекта

Изменение параметров после activate() требует:

  • deactivate()
  • повторной инициализации клиента

Исключения:

  • динамические headers (через hooks)
  • debug можно менять в runtime

Взаимосвязь параметров

Некоторые параметры работают только совместно:

  • heartbeatIncoming/outgoing требует поддержки сервера
  • reconnectDelay зависит от состояния onDisconnect
  • beforeConnect влияет на connectHeaders
  • webSocketFactory полностью заменяет brokerURL

Конфигурация фактически формирует поведение клиента как конечного автомата:

  • подключение
  • поддержание сессии
  • восстановление
  • обработка ошибок

Типичные конфигурационные паттерны

  1. Базовое подключение:
  • brokerURL + connectHeaders + onConnect
  1. Защищённое соединение:
  • wss + токены в headers + heartbeat
  1. Устойчивый клиент:
  • reconnectDelay + beforeConnect + onDisconnect
  1. Корпоративный сценарий:
  • webSocketFactory + динамическая авторизация + строгий timeout
Оглавление