Интерфейсы конфигурации

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

Основной интерфейс конфигурации строится вокруг объекта, передаваемого в конструктор клиента или назначаемого через экземпляр Client.

ClientConfig

Базовый интерфейс конфигурации клиента включает следующие поля:

  • brokerURL: string | () => string Адрес STOMP-брокера. Обычно используется формат WebSocket:

    • ws://host:port/path
    • wss://host:port/path

    Если задан webSocketFactory, поле brokerURL игнорируется.

  • webSocketFactory: () => WebSocket Фабрика WebSocket-соединения. Используется при необходимости кастомного транспорта:

    • SockJS
    • прокси-обёртки
    • тестовые моки

  • connectHeaders: ConnectHeaders Заголовки, отправляемые при установке STOMP-соединения.

  • reconnectDelay: number Задержка переподключения в миллисекундах. Значение 0 отключает автоматический reconnect.

  • heartbeatIncoming: number Интервал ожидания heartbeat от сервера. Если превышен — соединение считается потерянным.

  • heartbeatOutgoing: number Интервал отправки heartbeat на сервер.

  • debug: (msg: string) => void Функция логирования внутренних событий клиента.

  • forceBinaryWSFrames: boolean Включает использование бинарных WebSocket-фреймов вместо текстовых.

  • appendMissingNULLonIncoming: boolean Добавляет завершающий NULL-символ в входящие сообщения при необходимости совместимости.

  • splitLargeFrames: boolean Разделяет большие STOMP-фреймы на части при отправке.

ConnectHeaders

Интерфейс заголовков подключения описывает метаданные STOMP CONNECT:

  • login?: string Имя пользователя для аутентификации на брокере.

  • passcode?: string Пароль или токен доступа.

  • host?: string Виртуальный хост брокера (используется в RabbitMQ, ActiveMQ и др.).

  • heart-beat?: string Параметр согласования heartbeat в формате:

    "outgoing, incoming"

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

    • authorization
    • session-id
    • client-id

SubscribeHeaders

Интерфейс заголовков подписки используется при вызове subscribe():

  • id?: string Уникальный идентификатор подписки. Если не указан — генерируется автоматически.

  • ack?: ‘auto’ | ‘client’ | ‘client-individual’ Режим подтверждения сообщений:

    • auto — автоматическое подтверждение
    • client — ручное подтверждение батчами
    • client-individual — подтверждение каждого сообщения отдельно

  • durable?: string Имя устойчивой подписки (зависит от брокера).

  • persistent?: boolean Признак сохранения сообщений при временной недоступности клиента.

  • Дополнительные headers Поддерживаются брокер-специфичные параметры фильтрации и маршрутизации.

Message

Интерфейс входящего сообщения STOMP:

  • command: string Команда STOMP-фрейма (обычно MESSAGE).

  • headers: MessageHeaders Заголовки сообщения:

    • destination
    • message-id
    • subscription
    • content-type
    • пользовательские поля

  • body: string Тело сообщения в виде строки.

  • ack(): void Подтверждение получения сообщения (если включён ручной режим ack).

  • nack(): void Отклонение сообщения с возможностью повторной доставки.

MessageHeaders

Состав заголовков входящего сообщения зависит от брокера, но базовые поля включают:

  • destination: string — канал или очередь
  • message-id: string — идентификатор сообщения
  • subscription: string — идентификатор подписки
  • content-length?: number — размер payload
  • content-type?: string — MIME-тип
  • correlation-id?: string — связь с исходным запросом
  • ack?: string — режим подтверждения

Frame

STOMP-фрейм является низкоуровневой структурой протокола:

  • command: string Тип фрейма:

    • CONNECT
    • SEND
    • SUBSCRIBE
    • MESSAGE
    • ERROR
    • DISCONNECT

  • headers: Record<string, string> Набор строковых заголовков.

  • body: string Полезная нагрузка сообщения.

Внутренне STOMP.js преобразует WebSocket-сообщения в Frame и обратно, обеспечивая совместимость с протоколом.

AckMode и модель подтверждений

STOMP.js использует три режима подтверждений, которые формально являются частью конфигурации подписки:

  • auto Подтверждение происходит автоматически после получения.

  • client Подтверждение выполняется вручную через ack() на уровне подписки.

  • client-individual Каждый message подтверждается отдельно, обеспечивая строгий контроль доставки.

В зависимости от режима меняется поведение брокера и гарантия доставки сообщений.

Интерфейсы событий клиента

STOMP.js использует набор callback-интерфейсов для обработки состояния соединения:

  • onConnect: (frame: Frame) => void Вызывается после успешного подключения.

  • onDisconnect: (frame?: Frame) => void Срабатывает при корректном закрытии соединения.

  • onStompError: (frame: Frame) => void Обработка ошибок STOMP-протокола (например, авторизация или routing error).

  • onWebSocketError: (event: Event) => void Ошибки уровня WebSocket.

  • onWebSocketClose: (event: CloseEvent) => void Закрытие транспортного соединения.

  • beforeConnect: () => Promise | void Асинхронный хук перед установкой соединения, используется для обновления токенов или подготовки состояния.

Типизация и расширение конфигурации

TypeScript-описание STOMP.js допускает расширение интерфейсов через дополнительные поля:

  • пользовательские headers в connectHeaders
  • расширенные поля подписки
  • кастомные метаданные в frame headers

Это позволяет адаптировать клиент под различные брокеры без изменения ядра библиотеки.

Heartbeat-механизм

Heartbeat реализуется через два параметра:

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

Несовпадение настроек приводит к деградации соединения или его разрыву, поэтому конфигурация должна учитывать требования брокера.

Конфигурация reconnect-поведения

Поле reconnectDelay управляет стратегией восстановления соединения:

  • фиксированное значение — постоянная задержка
  • динамическое значение через внешнюю логику — позволяет реализовать backoff-алгоритмы

При 0 автоматическое восстановление отключается полностью, и управление жизненным циклом соединения ложится на приложение.

Особенности совместимости интерфейсов

Разные версии STOMP.js могут изменять сигнатуры callback-функций и набор допустимых headers. Основные зоны несовместимости:

  • изменение формата heart-beat
  • различие в типах ack
  • поведение webSocketFactory
  • обработка бинарных фреймов

При проектировании конфигурации учитывается минимизация зависимости от конкретной версии через абстракцию поверх ClientConfig.

Оглавление