Клиентский протокол
Сервер NATS и клиенты используют простой текстовый протокол. Транспорт по умолчанию — сокет TCP/IP; также поддерживаются WebSocket и UNIX domain socket, если сервер встроен в процесс Go.
Обзор
Таблица кратко описывает сообщения протокола NATS. Имена операций не чувствительны к регистру: SUB foo 1␍␊ и sub foo 1␍␊ эквивалентны.
| Сообщение | Отправитель | Описание |
|---|---|---|
INFO | Сервер | Отправляется клиенту после подключения TCP/IP |
CONNECT | Клиент | Передаёт серверу параметры соединения |
PUB | Клиент | Публикует сообщение в тему с необязательной темой ответа |
HPUB | Клиент | Публикует сообщение с заголовками NATS и необязательной темой ответа |
SUB | Клиент | Подписывается на тему или шаблон |
UNSUB | Клиент | Отменяет подписку, включая автоматическую |
MSG | Сервер | Доставляет полезную нагрузку подписчику |
HMSG | Сервер | Доставляет полезную нагрузку и заголовки NATS |
PING | Обе стороны | Проверка активности PING |
PONG | Обе стороны | Ответ проверки активности PONG |
+OK | Сервер | Подтверждает корректное сообщение протокола в режиме verbose |
-ERR | Сервер | Ошибка протокола, которая может вызвать отключение клиента |
Далее подробно описывается каждое сообщение.
INFO
Сначала клиент устанавливает обычное TCP-соединение. Приняв его, сервер передаёт сведения о себе, конфигурации и требованиях безопасности для успешной аутентификации и обмена сообщениями.
В обновлённом клиентском протоколе (см. CONNECT ниже) сервер может отправлять INFO в любой момент. Клиент соответствующего уровня должен обрабатывать INFO асинхронно.
Синтаксис
INFO {"option_name":option_value,...}␍␊
Допустимые параметры, закодированные как JSON:
| Название | Описание | Тип | Наличие |
|---|---|---|---|
server_id | Уникальный идентификатор сервера NATS. | string | всегда |
server_name | Имя сервера NATS. | string | всегда |
version | Версия NATS. | string | всегда |
go | Версия Go, которой собран сервер NATS. | string | всегда |
host | IP-адрес запуска сервера; по умолчанию 0.0.0.0, настраивается через -client_advertise host:port. | string | всегда |
port | Порт прослушивания сервера NATS. | int | всегда |
headers | Поддерживает ли сервер заголовки. | bool | всегда |
max_payload | Максимальный принимаемый от клиента размер нагрузки в байтах. | int | всегда |
proto | Версия протокола сервера. Сервер 1.2.0 задаёт 1, обозначая поддержку Echo. | int | всегда |
client_id | Внутренний идентификатор клиента на сервере для фильтрации мониторинга, сопоставления журналов ошибок и других задач. | uint64 | необязательно |
auth_required | При true клиент должен аутентифицироваться при подключении. | bool | необязательно |
tls_required | При true клиент должен выполнить handshake TLS/1.2. Ранее поле называлось ssl_required и было переименовано при переходе от SSL к TLS. | bool | необязательно |
tls_verify | При true клиент должен предъявить действительный сертификат при handshake TLS. | bool | необязательно |
tls_available | При true клиент может предъявить действительный сертификат при handshake TLS. | bool | необязательно |
connect_urls | Список URL серверов для подключения клиента. | [string] | необязательно |
ws_connect_urls | Список URL серверов для подключения клиента WebSocket. | [string] | необязательно |
ldm | Если сервер поддерживает уведомления Lame Duck Mode и перешёл в этот режим, ldm равно true. | bool | необязательно |
git_commit | Хеш Git, соответствующий сборке сервера NATS. | string | необязательно |
jetstream | Поддерживает ли сервер JetStream. | bool | необязательно |
ip | IP-адрес сервера. | string | необязательно |
client_id | Идентификатор клиента. | string | необязательно |
client_ip | IP-адрес клиента. | string | необязательно |
nonce | Одноразовое значение для CONNECT. | string | необязательно |
cluster | Имя кластера. | string | необязательно |
domain | Настроенный домен NATS сервера. | string | необязательно |
connect_urls
Поле connect_urls содержит список URL, отправляемый при первом подключении клиента и изменениях топологии кластера. Поле необязательно и может отсутствовать в зависимости от конфигурации сервера и уровня протокола клиента.
При расширении кластера клиенту отправляется INFO с обновлённым connect_urls. Эта удобная для облака возможность асинхронно сообщает известные серверы и позволяет подключаться к адресам, не заданным первоначально.
connect_urls содержит строки с IP-адресом и портом, например "connect_urls":["10.0.0.184:4333","192.168.129.1:4333","192.168.192.1:4333"].
Пример
Пример строки при подключении telnet к demo.nats.io:
telnet demo.nats.io 4222
Trying 107.170.221.32...
Connected to demo.nats.io.
Escape character is '^]'.
INFO {"server_id":"Zk0GQ3JBSrg3oyxCRRlE09","version":"1.2.0","proto":1,"go":"go1.10.3","host":"0.0.0.0","port":4222,"max_payload":1048576,"client_id":2392}
CONNECT
CONNECT — клиентский аналог INFO. Установив TCP/IP-соединение с сервером NATS и получив INFO, клиент может отправить CONNECT с дополнительными сведениями о соединении и безопасности.
Синтаксис
CONNECT {"option_name":option_value,...}␍␊
Допустимые параметры, закодированные как JSON:
| Название | Описание | Тип | Обязательно |
|---|---|---|---|
verbose | Включает подтверждения протокола +OK. | bool | true |
pedantic | Включает дополнительные строгие проверки формата, например корректности тем. | bool | true |
tls_required | Требуется ли клиенту соединение SSL. | bool | true |
auth_token | Токен авторизации клиента. | string | если auth_required равно true |
user | Имя пользователя соединения. | string | если auth_required равно true |
pass | Пароль соединения. | string | если auth_required равно true |
name | Имя клиента. | string | false |
lang | Язык реализации клиента. | string | true |
version | Версия клиента. | string | true |
protocol | 0 или отсутствие поля означает исходный протокол. 1 — поддержку динамической топологии через асинхронные INFO со списком серверов переподключения. | int | false |
echo | При false сервер 1.2.0+ не возвращает сообщения соединения его собственным подпискам. Устанавливать false следует только при поддержке функции сервером: proto в INFO не меньше 1. | bool | false |
sig | Если сервер передал nonce в INFO, клиент NATS должен вернуть здесь подписанный nonce. | string | если получен nonce |
jwt | JWT с разрешениями и учётной записью пользователя. | string | false |
no_responders | Включает быстрый ответ на запросы в тему без отвечающих сервисов. | bool | false |
headers | Поддерживает ли клиент заголовки. | bool | false |
nkey | Открытый NKey для аутентификации клиента. По нему проверяется подпись (sig) значения nonce из INFO. | string | false |
Пример
Пример стандартной строки клиента Go:
CONNECT {"verbose":false,"pedantic":false,"tls_required":false,"name":"","lang":"go","version":"1.2.2","protocol":1}␍␊
Большинство клиентов по умолчанию задают verbose как false: сервер не должен подтверждать каждое сообщение этого соединения ответом +OK.
PUB
PUB публикует полезную нагрузку в указанную тему, при необходимости с темой ответа. Тема ответа доставляется подходящим подписчикам вместе с нагрузкой. Сама нагрузка необязательна: для отсутствующей задайте размер 0, но второй CRLF всё равно нужен.
Синтаксис
PUB <subject> [reply-to] <#bytes>␍␊[payload]␍␊
где:
| Название | Описание | Тип | Обязательно |
|---|---|---|---|
subject | Тема назначения публикации. | string | true |
reply-to | Тема для ответа подписчика издателю или отправителю запроса. | string | false |
#bytes | Размер нагрузки в байтах. | int | true |
payload | Полезная нагрузка сообщения. | string | false |
Пример
Публикация ASCII-строки «Hello NATS!» в тему FOO:
PUB FOO 11␍␊Hello NATS!␍␊
Публикация запроса «Knock Knock» в FRONT.DOOR с темой ответа JOKE.22:
PUB FRONT.DOOR JOKE.22 11␍␊Knock Knock␍␊
Публикация пустого сообщения в NOTIFY:
PUB NOTIFY 0␍␊␍␊
HPUB
HPUB аналогичен PUB, но расширяет сообщение заголовками NATS. Нагрузка необязательна: для её отсутствия общий размер задаётся равным размеру заголовков. Завершающий CR+LF всё равно нужен.
Заголовки NATS похожи на HTTP по структуре и смыслу: пары name: value с поддержкой нескольких значений. Регистр может быть смешанным; NATS сохраняет его между издателем и получателями. См. ADR-4: Заголовки сообщений NATS.
Синтаксис
HPUB <subject> [reply-to] <#header bytes> <#total bytes>␍␊[headers]␍␊␍␊[payload]␍␊
где:
| Название | Описание | Тип | Обязательно |
|---|---|---|---|
subject | Тема назначения публикации. | string | true |
reply-to | Тема для ответа подписчика издателю или отправителю запроса. | string | false |
#header bytes | Размер заголовков в байтах, включая разделитель ␍␊␍␊ перед нагрузкой. | int | true |
#total bytes | Общий размер заголовков и нагрузки в байтах. | int | true |
headers | Версия NATS/1.0␍␊, затем пары name: value, разделённые ␍␊. | string | false |
payload | Полезная нагрузка сообщения. | string | false |
Пример
Публикация ASCII-строки "Hello NATS!" в FOO с заголовком Bar со значением Baz:
HPUB FOO 22 33␍␊NATS/1.0␍␊Bar: Baz␍␊␍␊Hello NATS!␍␊
Публикация запроса «Knock Knock» в FRONT.DOOR с темой ответа JOKE.22 и двумя заголовками:
HPUB FRONT.DOOR JOKE.22 45 56␍␊NATS/1.0␍␊BREAKFAST: donut␍␊LUNCH: burger␍␊␍␊Knock Knock␍␊
Публикация пустого сообщения в NOTIFY с заголовком Bar со значением Baz:
HPUB NOTIFY 22 22␍␊NATS/1.0␍␊Bar: Baz␍␊␍␊␍␊
Публикация в MORNING MENU с заголовком BREAKFAST, имеющим два значения, и нагрузкой «Yum!»:
HPUB MORNING.MENU 47 51␍␊NATS/1.0␍␊BREAKFAST: donut␍␊BREAKFAST: eggs␍␊␍␊Yum!␍␊
SUB
SUB создаёт подписку на тему, при необходимости присоединяясь к распределённой группе очереди.
Синтаксис
SUB <subject> [queue group] <sid>␍␊
где:
| Название | Описание | Тип | Обязательно |
|---|---|---|---|
subject | Имя темы подписки. | string | true |
queue group | Если указана, подписчик входит в эту группу очереди. | string | false |
sid | Уникальный буквенно-цифровой идентификатор подписки, создаваемый клиентом. | string | true |
Пример
Подписка на FOO с уникальным в соединении идентификатором (sid) 1:
SUB FOO 1␍␊
Подписка текущего соединения на BAR в группе распределения G1 с sid 44:
SUB BAR G1 44␍␊
UNSUB
UNSUB отменяет подписку соединения на тему либо автоматически отписывает после заданного числа сообщений.
Синтаксис
UNSUB <sid> [max_msgs]␍␊
где:
| Название | Описание | Тип | Обязательно |
|---|---|---|---|
sid | Уникальный буквенно-цифровой идентификатор отменяемой подписки. | string | true |
max_msgs | Число сообщений до автоматической отписки. | int | false |
Пример
Примеры для темы FOO с sid 1. Отмена подписки FOO:
UNSUB 1␍␊
Автоматическая отписка FOO после получения 5 сообщений:
UNSUB 1 5␍␊
MSG
Сообщение протокола MSG доставляет клиенту сообщение приложения.
Синтаксис
MSG <subject> <sid> [reply-to] <#bytes>␍␊[payload]␍␊
где:
| Название | Описание | Тип | Наличие |
|---|---|---|---|
subject | Тема получения сообщения. | string | всегда |
sid | Уникальный буквенно-цифровой идентификатор подписки. | string | всегда |
reply-to | Тема, в которой издатель ждёт ответов. | string | необязательно |
#bytes | Размер нагрузки в байтах. | int | всегда |
payload | Полезная нагрузка сообщения. | string | необязательно |
Пример
Доставка сообщения приложения из темы FOO.BAR:
MSG FOO.BAR 9 11␍␊Hello World␍␊
Доставка того же сообщения с темой ответа:
MSG FOO.BAR 9 GREETING.34 11␍␊Hello World␍␊
HMSG
HMSG аналогичен MSG, но добавляет заголовки. См. ADR-4: Заголовки сообщений NATS.
Синтаксис
HMSG <subject> <sid> [reply-to] <#header bytes> <#total bytes>␍␊[headers]␍␊␍␊[payload]␍␊
где:
| Название | Описание | Тип | Наличие |
|---|---|---|---|
subject | Тема получения сообщения. | string | всегда |
sid | Уникальный буквенно-цифровой идентификатор подписки. | string | всегда |
reply-to | Тема, в которой издатель ждёт ответов. | string | необязательно |
#header bytes | Размер заголовков в байтах, включая разделитель ␍␊␍␊ перед нагрузкой. | int | всегда |
#total bytes | Общий размер заголовков и нагрузки в байтах. | int | всегда |
headers | Версия NATS/1.0␍␊, затем пары name: value, разделённые ␍␊. | string | необязательно |
payload | Полезная нагрузка сообщения. | string | необязательно |
Пример
Доставка сообщения приложения из FOO.BAR с заголовком:
HMSG FOO.BAR 34 45␍␊NATS/1.0␍␊FoodGroup: vegetable␍␊␍␊Hello World␍␊
Доставка того же сообщения с темой ответа:
HMSG FOO.BAR 9 BAZ.69 34 45␍␊NATS/1.0␍␊FoodGroup: vegetable␍␊␍␊Hello World␍␊
PING/PONG
PING и PONG проверяют доступность между клиентом и сервером. После подключения сервер регулярно отправляет клиенту PING с настраиваемым интервалом. Если PONG не приходит за заданный срок, сервер закрывает соединение. Слишком долгое бездействие приводит к отключению.
На серверный ping можно ответить pong, подтверждая интерес к соединению. Можно также отправить ping серверу и получить pong. Интервал настраивается.
Сервер считает обычный трафик заменой ping/pong, поэтому при передаче сообщений он может не отправлять клиенту ping.
Синтаксис
PING␍␊
PONG␍␊
Пример
Пример демонстрационного сервера, отправляющего ping клиенту и в конце закрывающего соединение:
telnet demo.nats.io 4222
Trying 107.170.221.32...
Connected to demo.nats.io.
Escape character is '^]'.
INFO {"server_id":"Zk0GQ3JBSrg3oyxCRRlE09","version":"1.2.0","proto":1,"go":"go1.10.3","host":"0.0.0.0","port":4222,"max_payload":1048576,"client_id":2392}
PING
PING
-ERR 'Stale Connection'
Connection closed by foreign host.
+OK/ERR
При verbose, равном true (значение по умолчанию), сервер подтверждает каждое корректное сообщение клиента ответом +OK. Большинство клиентов NATS задаёт verbose как false в CONNECT.
-ERR используется сервером для сообщения клиенту об ошибке протокола, авторизации или другой ошибке соединения. Большинство таких ошибок закрывает соединение.
Обычно эти ошибки нужно обрабатывать асинхронно.
Синтаксис
+OK␍␊
-ERR <error message>␍␊
Ошибки
Ниже перечислены возможные ошибки. Некоторые закрывают соединение; после получения такой ошибки соединение недействительно, и клиент должен освободить связанные ресурсы. Столбец «Восстановимо» (Recoverable) показывает возможность продолжить работу.
| Ошибка | Описание | Восстановимо |
|---|---|---|
Unknown Protocol Operation | Неизвестная операция протокола. | Нет |
Attempted To Connect To Route Port | Клиент попытался подключиться к маршрутному порту вместо клиентского. | Нет |
Authorization Violation | Клиент не прошёл аутентификацию с учётными данными из CONNECT. | Нет |
Authorization Timeout | После подключения клиент слишком долго аутентифицировался; по умолчанию отведена 1 секунда. | Нет |
Invalid Client Protocol | В CONNECT указана недопустимая версия протокола. | Нет |
Maximum Control Line Exceeded | Суммарная длина темы назначения и ответа превышает max_control_line. Значение по умолчанию — 1024 байта. | Нет |
Parser Error | Не удалось разобрать сообщение протокола клиента. | Нет |
Secure Connection - TLS Required | Сервер требует TLS, но клиент его не включил. | Нет |
Stale Connection | Сервер слишком долго не получал сообщений клиента, включая PONG. | Нет |
Maximum Connections Exceeded | При создании соединения превышен серверный max_connections; по умолчанию 64 тысячи. | Нет |
Slow Consumer | Объём ожидающих отправки данных соединения достиг максимума; по умолчанию 10 МБ. | Нет |
Maximum Payload Violation | Клиент публикует нагрузку больше серверного max_payload. Лимит передаётся при подключении в первоначальном INFO. Клиент должен заранее учитывать размер отправляемых байтов, чтобы обрабатывать ошибку синхронно. | Нет |
Invalid Subject | Клиент отправил некорректную тему, например SUB foo. 90. | Да |
Permissions Violation for Subscription to <subject> | Пользователь из CONNECT не имеет разрешения подписываться на тему. | Да |
Permissions Violation for Publish to <subject> | Пользователь из CONNECT не имеет разрешения публиковать в тему. | Да |