Перейти к основному содержимому
Версия: 2.11

Листовые узлы

Соединения листовых узлов расширяют кластеры NATS лёгкими соединениями, инициируемыми периферийными серверами к центральному кластеру. Протокол оптимизирован для топологии «центр — лучи» с небольшими накладными расходами. В отличие от маршрутов кластера, эти соединения асимметричны: периферийный узел инициирует и поддерживает соединение с центром.

Обзор​

Таблица перечисляет сообщения протокола листовых узлов. Имена операций не чувствительны к регистру: LS+ foo\r\n и ls+ foo\r\n эквивалентны.

СообщениеОтправительОписание
INFOВсе серверыОтправляется после подключения с расширениями листовых узлов
CONNECTЛистовой узелУстанавливает и аутентифицирует соединение
LS+Все серверыПодписывает на тему, при необходимости с группой очереди и весом
LS-Все серверыОтменяет подписку на тему, при необходимости для группы очереди
LMSGВсе серверыДоставляет сообщение с темой, необязательным ответом и группами очередей
LDSЦентральный серверТемы обнаружения циклов маршрутизации
PINGВсе серверыПроверка активности PING
PONGВсе серверыОтвет проверки активности PONG
-ERRВсе серверыОшибка протокола, которая может вызвать отключение листового узла

INFO​

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

Синтаксис​

INFO {<key>:<value>,...}

Поля, относящиеся к листовым узлам:

  • server_id: уникальный идентификатор сервера NATS
  • version: версия сервера NATS
  • proto: версия протокола (1 для текущего протокола листовых узлов)
  • go: версия Go, которой собран сервер
  • host: хост из конфигурации листового узла
  • port: порт соединений листовых узлов
  • headers: поддержка заголовков (true/false)
  • jetstream: включён ли JetStream
  • compression: режим сжатия (off, accept, s2_auto, s2_fast, s2_better, s2_uncompressed)
  • cluster: имя кластера, если сервер входит в кластер
  • domain: имя домена JetStream
  • xkey: открытый xkey сервера для шифрования
  • auth_required: обязательность аутентификации
  • tls_required: обязательность TLS
  • tls_verify: обязательность проверки сертификата TLS
  • max_payload: максимальный принимаемый размер нагрузки
  • client_id: идентификатор клиента для согласования сжатия
  • nonce: одноразовое значение для операций безопасности
  • connect_urls: альтернативные серверы подключения

Пример​

INFO {"server_id":"NCXU7YJOG5XAU","version":"2.10.0","proto":1,"go":"go1.21","host":"localhost","port":7422,"headers":true,"max_payload":1048576,"jetstream":true,"compression":"s2_auto","cluster":"hub-cluster","domain":"hub","connect_urls":["localhost:7422"]}

CONNECT​

CONNECT отправляется листовым узлом для аутентификации и задания параметров соединения. Включает конфигурацию и возможности листового узла.

Синтаксис​

CONNECT {<key>:<value>,...}

Допустимые параметры:

  • version: версия сервера листового узла
  • server_id: уникальный идентификатор листового узла
  • name: имя его сервера
  • domain: домен JetStream листового узла
  • cluster: имя кластера листового узла, если используется кластеризация
  • hub: является ли соединение центральным (true/false)
  • headers: поддерживаются ли заголовки
  • jetstream: включён ли JetStream на листовом узле
  • compression: запрашиваемый режим сжатия
  • remote_account: учётная запись привязки соединения
  • proto: версия протокола
  • nkey: открытый NKey для аутентификации
  • jwt: JWT для аутентификации
  • sig: подпись для аутентификации nkey
  • user: имя пользователя базовой аутентификации
  • pass: пароль базовой аутентификации
  • auth_token: токен аутентификации
  • tls_required: требуется ли TLS

Пример​

CONNECT {"version":"2.10.0","server_id":"NATS123","name":"edge-1","cluster":"edge","hub":false,"headers":true,"jetstream":false,"compression":"s2_auto","remote_account":"EDGE_ACCOUNT","proto":1}\r\n

LS+​

LS+ регистрирует интерес к теме в соединении листового узла, при необходимости с группой очереди и весом для распределённых очередей.

Синтаксис​

Обычная подписка

LS+ <subject>\r\n

Подписка группы очереди

LS+ <subject> <queue_group>\r\n

Подписка группы очереди с весом

LS+ <subject> <queue_group> <weight>\r\n

где:

  • subject: тема подписки с поддержкой подстановочных символов
  • queue_group: необязательное имя группы очереди
  • weight: необязательный вес распределения очереди, по умолчанию 1

Примеры​

LS+ orders.new\r\n
LS+ orders.> fulfillment\r\n
LS+ orders.> fulfillment 4\r\n

Поддержка исходного кластера​

При поддержке LNOCU (Leaf Node Origin Cluster Unsub) LS+ может включать сведения об исходном кластере для предотвращения циклов:

LS+ <subject> <queue_group> <weight> <origin_cluster>\r\n

LS-​

LS- удаляет интерес к теме в соединении листового узла, при необходимости для определённой группы очереди.

Синтаксис​

Обычная отписка

LS- <subject>\r\n

Отписка группы очереди

LS- <subject> <queue_group>\r\n

где:

  • subject: тема отменяемой подписки
  • queue_group: необязательное имя группы очереди

Примеры​

LS- orders.old\r\n
LS- orders.cancelled fulfillment\r\n

Поддержка исходного кластера​

При поддержке LNOCU LS- может включать информацию об исходном кластере:

LS- <subject> <queue_group> <origin_cluster>\r\n

LMSG​

Сообщение протокола LMSG доставляет данные через соединение листового узла. Поддерживаются темы ответа, выбор групп очередей и заголовки.

Синтаксис​

Обычное сообщение

LMSG <subject> <size>\r\n[payload]\r\n

Сообщение с темой ответа

LMSG <subject> + <reply> <size>\r\n[payload]\r\n

Сообщение с группами очередей

LMSG <subject> | <queue_group1> [queue_group2...] <size>\r\n[payload]\r\n

Сообщение с темой ответа и группами очередей

LMSG <subject> + <reply> <queue_group1> [queue_group2...] <size>\r\n[payload]\r\n

Сообщение с заголовками

LMSG <subject> [+ reply] [| queue_groups...] <header_size> <total_size>\r\n[headers]\r\n[payload]\r\n

где:

  • subject: тема доставки сообщения
  • +: признак следующей темы ответа
  • reply: необязательная тема ответа
  • |: признак следующих групп очередей
  • queue_group: целевые группы очередей
  • header_size: размер заголовков в байтах для сообщений с заголовками
  • total_size: общий размер заголовков и нагрузки
  • size: размер нагрузки в байтах для сообщений без заголовков
  • headers: заголовки NATS в стандартном формате
  • payload: полезная нагрузка сообщения

Примеры​

LMSG orders.new 11\r\nHello World\r\n
LMSG orders.new + _INBOX.123 11\r\nHello World\r\n
LMSG orders.new | fulfillment 11\r\nHello World\r\n
LMSG orders.new + _INBOX.123 fulfillment shipping 11\r\nHello World\r\n
LMSG orders.new 22 33\r\nNATS/1.0\r\nFoo: Bar\r\n\r\nHello World\r\n

LDS​

Темы обнаружения циклов (Loop Detection Subjects, LDS) — специальные темы для выявления и предотвращения циклов маршрутизации в сложных топологиях листовых узлов.

Формат​

$LDS.<unique_id>

где:

  • $LDS.: фиксированный префикс тем обнаружения циклов
  • unique_id: уникальный идентификатор, создаваемый для учётной записи

Назначение​

Получив собственную тему LDS через соединение листового узла, сервер обнаруживает цикл и принимает меры:

  1. Записывает обнаружение цикла в журнал
  2. Закрывает соединение
  3. Задерживает переподключение на 30 секунд
  4. Предотвращает бесконечное хождение сообщений по циклу

Пример​

$LDS.5XZq8bFpWH1234567890abcdef

Сжатие​

Листовые узлы поддерживают сжатие S2 для сокращения трафика, особенно полезное для WAN.

Режимы сжатия​

  • off: без сжатия
  • accept: принимать сжатые соединения, но не инициировать
  • s2_auto: автоматически выбирать сжатие по RTT
  • s2_fast: быстрое S2 с меньшей нагрузкой на процессор и меньшей степенью сжатия
  • s2_better: более эффективное S2 с большей нагрузкой на процессор
  • s2_uncompressed: кадры S2 без сжатия

Согласование​

Сжатие согласуется при обмене INFO:

  1. Обе стороны объявляют возможности сжатия в INFO
  2. Листовой узел предлагает режим в CONNECT
  3. Центральный сервер принимает или изменяет режим
  4. После успешного согласования начинается сжатие S2

Автоматический режим​

В режиме s2_auto решение зависит от RTT:

  • Сжатие включается при RTT выше порога, обычно в WAN
  • Отключается в LAN с низкой задержкой
  • Динамически подстраивается под соединение

Поддержка WebSocket​

Листовые узлы могут подключаться через WebSocket для прохождения межсетевых экранов и совместимости с браузерным транспортом.

Путь WebSocket​

ws://server:port/leafnode

Возможности​

  • Стандартный протокол листовых узлов поверх кадров WebSocket
  • Необязательное сжатие per-message-deflate
  • Маскирование кадров, отключаемое для производительности
  • Те же методы аутентификации и сообщения протокола

Пример URL подключения​

ws://hub.example.com:443/leafnode

Разрешения и безопасность​

Привязка учётной записи​

Листовой узел можно привязать к учётной записи через remote_account в CONNECT:

  • Сообщения ограничиваются этой учётной записью
  • Исключается утечка сообщений между учётными записями
  • Поддерживается изолированное размещение арендаторов на периферии

Нарушения разрешений​

При нарушении разрешений:

  • Соединение закрывается с -ERR 'Permissions Violation'
  • Переподключение задерживается на 30 секунд
  • Нарушение записывается для аудита безопасности

Способы аутентификации​

Листовые узлы поддерживают:

  • NKey с подписью
  • JWT с NKey
  • Имя пользователя и пароль
  • Токен аутентификации
  • Клиентские сертификаты TLS

PING/PONG​

PING и PONG проверяют доступность между листовым и центральным узлами. Серверы отправляют PING с настраиваемым интервалом. Отсутствие ответа PONG приводит к закрытию соединения.

Синтаксис​

PING\r\n
PONG\r\n

-ERR​

-ERR сообщает об ошибке протокола, авторизации или выполнения. Большинство ошибок закрывает соединение листового узла.

Синтаксис​

-ERR <error message>

Распространённые ошибки листовых узлов​

  • -ERR 'Permissions Violation': запрещена тема или публикация
  • -ERR 'Loop Detected': LDS обнаружил цикл маршрутизации
  • -ERR 'Authorization Violation': ошибка аутентификации или авторизации
  • -ERR 'Maximum Payload Exceeded': сообщение превышает max_payload
  • -ERR 'Invalid Subject': некорректная тема в сообщении протокола
  • -ERR 'Leafnode Not Allowed': сервер не настроен для листовых узлов