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

Шлюзы

Шлюзовые соединения объединяют кластеры 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: уникальный идентификатор сервера NATS
  • version: версия сервера NATS
  • go: версия Go, которой собран сервер
  • host: хост из параметров шлюза
  • port: порт из параметров шлюза
  • auth_required: необходимость аутентификации при подключении
  • tls_required: необходимость аутентификации через TLS
  • max_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: требуется ли шлюзу соединение SSL
  • auth_token: токен авторизации
  • user: имя пользователя при заданном auth_required
  • pass: пароль при заданном auth_required
  • name: созданное имя шлюза
  • 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: заголовки сообщения в формате NATS
  • payload: полезная нагрузка сообщения

Пример​

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:

  1. Шлюз отправляет gateway_cmd: 2 (All Subs Start)
  2. Шлюз отправляет все RS+ известных подписок
  3. Шлюз отправляет gateway_cmd: 3 (All Subs Complete)
  4. Удалённый шлюз переводит учётную запись в режим только по интересу

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