Шлюзы
Шлюзовые соединения объединяют кластеры NATS в суперкластеры. Протокол расширяет протокол маршрутов маршрутизацией с учётом учётных записей и оптимизациями по интересу. В суперкластере шлюзы выступают интеллектуальными мостами, передающими сообщения между кластерами по интересу к учётным записям и темам.
Обзор
Таблица перечисляет сообщения протокола шлюзов. Имена операций не чувствительны к регистру: A+ foo\r\n и a+ foo\r\n эквивалентны.
| Сообщение | Отправитель | Описание |
|---|---|---|
INFO | Все шлюзы | После подключения передаёт расширения шлюзов |
CONNECT | Все шлюзы | Устанавливает шлюзовое соединение |
A+ | Все шлюзы | Подписывает на все темы учётной записи |
A- | Все шлюзы | Отменяет подписку на все темы учётной записи |
RS+ | Все шлюзы | Подписывает на тему учётной записи от имени заинтересованных клиентов |
RS- | Все шлюзы | Отменяет подписку или сообщает об отсутствии интереса |
RMSG | Исходный шлюз | Передаёт сообщение темы и учётной записи другому шлюзу |
HMSG | Исходный шлюз | Передаёт сообщение с заголовками для темы и учётной записи |
PING | Все шлюзы | Проверка активности PING |
PONG | Все шлюзы | Ответ проверки активности PONG |
-ERR | Все шлюзы | Ошибка протокола, которая может вызвать отключение шлюза |
INFO
INFO расширяет стандартное сообщение полями шлюза. Приняв соединение, шлюз передаёт сведения о себе, кластере и своей конфигурации.
Синтаксис
INFO {<key>:<value>,...}
Поля шлюза:
gateway: имя шлюзаgateway_urls: URL других шлюзов кластераgateway_url: URL этого шлюзаgateway_cmd: необязательный код команды координацииgateway_cmd_payload: необязательные данные командыserver_id: уникальный идентификатор сервера NATSversion: версия сервера NATSgo: версия Go, которой собран серверhost: хост из параметров шлюзаport: порт из параметров шлюзаauth_required: необходимость аутентификации при подключенииtls_required: необходимость аутентификации через TLSmax_payload: максимальный размер принимаемой нагрузкиconnect_urls: список URL серверов для подключения клиентовip: необязательный адрес шлюзового соединения,nats-gw://<hostname>:<port>
Команды шлюза
Поле gateway_cmd поддерживает коды:
1(Gossip): распространение топологии шлюзов2(All Subs Start): начало передачи всех подписок учётной записи3(All Subs Complete): окончание передачи всех подписок учётной записи
Пример
INFO {"server_id":"NCDU7ZKDF2XTYQUA","version":"2.10.0","go":"go1.21","host":"hub.nats.io","port":7222,"gateway":"hub","gateway_urls":["hub.nats.io:7222"],"gateway_url":"nats-gw://hub.nats.io:7222","auth_required":false,"tls_required":true,"max_payload":1048576}
CONNECT
CONNECT устанавливает шлюзовое соединение после обмена INFO и передаёт данные аутентификации и параметры соединения.
Синтаксис
CONNECT {<key>:<value>,...}
Допустимые параметры:
tls_required: требуется ли шлюзу соединение SSLauth_token: токен авторизацииuser: имя пользователя при заданномauth_requiredpass: пароль при заданномauth_requiredname: созданное имя шлюзаlang: язык реализации шлюза (go)version: версия шлюза
Пример
CONNECT {"tls_required":true,"name":"hub-gateway-us-east","lang":"go","version":"2.10.0"}\r\n
A+
A+ подписывает на все темы определённой учётной записи. Используется для распространения интереса на уровне учётной записи между шлюзами.
Синтаксис
A+ <account>\r\n
где:
account: имя учётной записи для подписки
Пример
A+ SYS\r\n
A-
A- отменяет подписку на все темы учётной записи. Отправляется, когда у шлюза больше нет интереса к ней.
Синтаксис
A- <account>\r\n
где:
account: имя учётной записи отменяемой подписки
Пример
A- SYS\r\n
RS+
RS+ создаёт подписку на тему учётной записи, при необходимости с именем распределённой группы очереди и весом. Это точное распространение интереса к темам.
Синтаксис
Подписка
RS+ <account> <subject>\r\n
Подписка группы очереди
RS+ <account> <subject> <queue> <weight>\r\n
где:
account: учётная запись интересаsubject: темаqueue: необязательное имя группы очередиweight: необязательный вес группы, представляющий число подписчиков
Примеры
RS+ ACC1 orders.new\r\n
RS+ ACC1 orders.> fulfillment 5\r\n
RS-
RS- отменяет подписку на тему учётной записи или сообщает об отсутствии интереса. В оптимистичном режиме предотвращает последующую доставку этой темы.
Синтаксис
Отписка
RS- <account> <subject>\r\n
Отписка группы очереди
RS- <account> <subject> <queue>\r\n
где:
account: учётная запись темыsubject: темаqueue: необязательное имя группы очереди
Примеры
RS- ACC1 orders.old\r\n
RS- ACC1 orders.processed fulfillment\r\n
RMSG
RMSG доставляет сообщение другому шлюзу для определённой учётной записи и темы.
Синтаксис
RMSG <account> <subject> [reply-to] <bytes>\r\n[payload]\r\n
где:
account: учётная запись сообщенияsubject: тема получения сообщенияreply-to: необязательная тема ответаbytes: размер нагрузки в байтахpayload: полезная нагрузка сообщения
Пример
RMSG ACC1 orders.new 11\r\nHello World\r\n
HMSG
HMSG доставляет другому шлюзу сообщение с заголовками, расширяя RMSG их поддержкой.
Синтаксис
HMSG <account> <subject> [reply-to] <header-bytes> <total-bytes>\r\n[headers]\r\n[payload]\r\n
где:
account: учётная запись сообщенияsubject: тема получения сообщенияreply-to: необязательная тема ответаheader-bytes: размер заголовков в байтахtotal-bytes: общий размер заголовков и нагрузки в байтахheaders: заголовки сообщения в формате NATSpayload: полезная нагрузка сообщения
Пример
HMSG ACC1 orders.new _INBOX.123 22 33\r\nNATS/1.0\r\nFoo: Bar\r\n\r\nHello World\r\n
Управление интересом
Шлюзы управляют интересом для уменьшения межкластерного трафика:
Оптимистичный режим
Изначально шлюзы предполагают наличие интереса и пересылают сообщения. По ответам RS- они строят список отсутствующего интереса.
Режим только по интересу
При большом числе RS-, означающем слабое пересечение интересов, шлюз переходит в режим только по интересу:
- Сообщения получают только темы с явными подписками
RS+ - Полное состояние подписок поддерживается через
A+иRS+ - Сокращается ненужный трафик между кластерами
Протокол перехода
Для перехода используются команды в INFO:
- Шлюз отправляет
gateway_cmd: 2(All Subs Start) - Шлюз отправляет все
RS+известных подписок - Шлюз отправляет
gateway_cmd: 3(All Subs Complete) - Удалённый шлюз переводит учётную запись в режим только по интересу
PING/PONG
PING и PONG проверяют доступность шлюзов. Шлюзы регулярно отправляют PING с настраиваемым интервалом. Если PONG не приходит за тайм-аут, соединение закрывается.
Синтаксис
PING\r\n
PONG\r\n
-ERR
-ERR сообщает об ошибке протокола, авторизации или выполнения. Большинство ошибок закрывает шлюзовое соединение.
Синтаксис
-ERR <error message>
Распространённые ошибки шлюзов
-ERR 'Invalid Account': неизвестная или недоступная учётная запись-ERR 'Gateway Protocol Error': некорректное сообщение протокола шлюзов-ERR 'Authorization Violation': ошибка авторизации шлюза-ERR 'Maximum Payload Exceeded': сообщение превышает max_payload