Листовые узлы
Соединения листовых узлов расширяют кластеры 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: уникальный идентификатор сервера NATSversion: версия сервера NATSproto: версия протокола (1 для текущего протокола листовых узлов)go: версия Go, которой собран серверhost: хост из конфигурации листового узлаport: порт соединений листовых узловheaders: поддержка заголовков (true/false)jetstream: включён ли JetStreamcompression: режим сжатия (off,accept,s2_auto,s2_fast,s2_better,s2_uncompressed)cluster: имя кластера, если сервер входит в кластерdomain: имя домена JetStreamxkey: открытый xkey сервера для шифрованияauth_required: обязательность аутентификацииtls_required: обязательность TLStls_verify: обязательность проверки сертификата TLSmax_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: подпись для аутентификации nkeyuser: имя пользователя базовой аутентификации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 через соединение листового узла, сервер обнаруживает цикл и принимает меры:
- Записывает обнаружение цикла в журнал
- Закрывает соединение
- Задерживает переподключение на 30 секунд
- Предотвращает бесконечное хождение сообщений по циклу
Пример
$LDS.5XZq8bFpWH1234567890abcdef
Сжатие
Листовые узлы поддерживают сжатие S2 для сокращения трафика, особенно полезное для WAN.
Режимы сжатия
off: без сжатияaccept: принимать сжатые соединения, но не инициироватьs2_auto: автоматически выбирать сжатие по RTTs2_fast: быстрое S2 с меньшей нагрузкой на процессор и меньшей степенью сжатияs2_better: более эффективное S2 с большей нагрузкой на процессорs2_uncompressed: кадры S2 без сжатия
Согласование
Сжатие согласуется при обмене INFO:
- Обе стороны объявляют возможности сжатия в INFO
- Листовой узел предлагает режим в CONNECT
- Центральный сервер принимает или изменяет режим
- После успешного согласования начинается сжатие 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': сервер не настроен для листовых узлов