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

Клиентский протокол

Сервер 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всегда
hostIP-адрес запуска сервера; по умолчанию 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необязательно
ipIP-адрес сервера.stringнеобязательно
client_idИдентификатор клиента.stringнеобязательно
client_ipIP-адрес клиента.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.booltrue
pedanticВключает дополнительные строгие проверки формата, например корректности тем.booltrue
tls_requiredТребуется ли клиенту соединение SSL.booltrue
auth_tokenТокен авторизации клиента.stringесли auth_required равно true
userИмя пользователя соединения.stringесли auth_required равно true
passПароль соединения.stringесли auth_required равно true
nameИмя клиента.stringfalse
langЯзык реализации клиента.stringtrue
versionВерсия клиента.stringtrue
protocol0 или отсутствие поля означает исходный протокол. 1 — поддержку динамической топологии через асинхронные INFO со списком серверов переподключения.intfalse
echoПри false сервер 1.2.0+ не возвращает сообщения соединения его собственным подпискам. Устанавливать false следует только при поддержке функции сервером: proto в INFO не меньше 1.boolfalse
sigЕсли сервер передал nonce в INFO, клиент NATS должен вернуть здесь подписанный nonce.stringесли получен nonce
jwtJWT с разрешениями и учётной записью пользователя.stringfalse
no_respondersВключает быстрый ответ на запросы в тему без отвечающих сервисов.boolfalse
headersПоддерживает ли клиент заголовки.boolfalse
nkeyОткрытый NKey для аутентификации клиента. По нему проверяется подпись (sig) значения nonce из INFO.stringfalse

Пример​

Пример стандартной строки клиента 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Тема назначения публикации.stringtrue
reply-toТема для ответа подписчика издателю или отправителю запроса.stringfalse
#bytesРазмер нагрузки в байтах.inttrue
payloadПолезная нагрузка сообщения.stringfalse

Пример​

Публикация 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Тема назначения публикации.stringtrue
reply-toТема для ответа подписчика издателю или отправителю запроса.stringfalse
#header bytesРазмер заголовков в байтах, включая разделитель ␍␊␍␊ перед нагрузкой.inttrue
#total bytesОбщий размер заголовков и нагрузки в байтах.inttrue
headersВерсия NATS/1.0␍␊, затем пары name: value, разделённые ␍␊.stringfalse
payloadПолезная нагрузка сообщения.stringfalse

Пример​

Публикация 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Имя темы подписки.stringtrue
queue groupЕсли указана, подписчик входит в эту группу очереди.stringfalse
sidУникальный буквенно-цифровой идентификатор подписки, создаваемый клиентом.stringtrue

Пример​

Подписка на FOO с уникальным в соединении идентификатором (sid) 1:

SUB FOO 1␍␊

Подписка текущего соединения на BAR в группе распределения G1 с sid 44:

SUB BAR G1 44␍␊

UNSUB​

UNSUB отменяет подписку соединения на тему либо автоматически отписывает после заданного числа сообщений.

Синтаксис​

UNSUB <sid> [max_msgs]␍␊

где:

НазваниеОписаниеТипОбязательно
sidУникальный буквенно-цифровой идентификатор отменяемой подписки.stringtrue
max_msgsЧисло сообщений до автоматической отписки.intfalse

Пример​

Примеры для темы 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 не имеет разрешения публиковать в тему.Да