Перейти к основному содержимому

Подключение

Приложение NATS взаимодействует с сетью через клиент: встроенную в программу библиотеку или инструмент командной строки nats, который открывает соединение с сервером и передаёт по нему сообщения. Чтобы любой шаблон этой главы заработал, клиент должен подключиться. Эта страница посвящена самому соединению: что это, как его открыть и какие немногочисленные настройки выбрать.

Для главы нужен один работающий локальный nats-server. Стандартная сборка не требует конфигурации:

nats-server

Оставьте его работающим. Сервер слушает порт 4222, и все страницы этой главы используют его.

Одно соединение для всех операций​

Соединение — одно долгоживущее TCP-соединение клиента с сервером. Клиент открывает его один раз при запуске приложения и сохраняет открытым до завершения работы приложения.

Все операции клиента проходят по этому соединению. Каждое опубликованное сообщение и каждая подписка (постоянный запрос на получение сообщений определённой темы) мультиплексируются в одном TCP-соединении и помечаются так, чтобы обе стороны различали потоки. Клиент не открывает новое соединение на каждую тему или сообщение: все они используют одно.

Поэтому следует подключаться один раз и повторно использовать результат. Одно соединение обслуживает тысячи подписок и высокую частоту сообщений. Клиенты рассчитаны на его совместное использование всеми операциями публикации и подписки.

URL подключения​

Клиент устанавливает соединение по URL подключения — адресу сервера в формате nats://host:port. По умолчанию серверы слушают порт 4222, поэтому локальный сервер имеет адрес nats://127.0.0.1:4222. Этот адрес используется и клиентом без явно заданного URL, и CLI nats, пока вы не укажете другой через --server или сохранённый контекст.

Схема задаёт транспорт. tls:// обозначает такое же соединение с шифрованием, а ws:// и wss:// передают протокол поверх WebSocket. Этот транспорт нужен браузеру и позволяет работать в сети, допускающей только исходящие подключения к порту 443. Подробнее — в разделе Подключение через WebSocket.

Один URL задаёт один сервер. В промышленной эксплуатации клиенту обычно передают несколько URL, чтобы он мог переключаться при недоступности сервера. Список и порядок перебора рассматриваются в разделе Устойчивые клиенты → Подключение. Здесь достаточно одного локального сервера.

Обмен при установлении соединения​

После сетевого подключения клиент и сервер выполняют короткий обмен при установлении соединения (handshake) до передачи сообщений.

Первым отправляет сервер: он сразу передаёт INFO со сведениями о себе и ограничениях, включая max_payload (наибольший допустимый размер сообщения, по умолчанию 1 МБ) и поддержку заголовков сообщений. Клиент читает INFO, затем отвечает CONNECT, указывая имя, поддерживаемые возможности протокола и учётные данные. Сервер принимает параметры, и соединение готово передавать сообщения.

Первую половину обмена можно увидеть напрямую. Подключите к серверу любой инструмент для работы с TCP: сразу после подключения он выведет строку INFO:

#!/bin/bash
# The server sends first. The moment a TCP client connects to port 4222, the
# server sends an INFO line -- plain text, ending in CRLF -- describing itself
# and the limits it enforces. Any raw TCP tool shows it; here we use nc against
# the running nats-server. Ctrl-C to quit.
nc localhost 4222

# The server immediately prints a line like:
#
# INFO {"server_id":"ND2X...","version":"2.14.0","proto":1,"headers":true,"max_payload":1048576,...}
#
# headers:true means the server supports message headers, and max_payload
# (1048576 bytes, 1 MB) is the largest message it will accept. A real client
# reads this INFO, then replies with its own CONNECT line declaring its name
# and the features it wants -- the exchange your client library runs for you.

Это текстовые сообщения, каждая строка которых заканчивается возвратом каретки и переводом строки. Такой же формат используют строки PUB и SUB, передающие ваши сообщения, и описанные ниже PING/PONG. Вручную их писать не нужно: клиентская библиотека выполняет весь обмен при вызове подключения. Пошаговый разбор всех полей есть в разделе Устойчивые клиенты → Подключение.

Имя соединения​

Одно поле сообщения CONNECT стоит задать самостоятельно: имя соединения. По умолчанию клиент подключается без осмысленного имени, и мониторинг сервера показывает соединение без имени вообще (CLI nats подставляет общее NATS CLI Version …). Если задать имя, оно будет идентифицировать соединение.

CLI nats задаёт имя глобальным флагом --connection-name. Называйте соединение по сервису-владельцу. Здесь это warehouse, первый сервис Acme, который подключается и проверяет доступность сервера:

#!/bin/bash
# Open a named connection to the server and measure the round trip. `nats rtt`
# dials the default URL (nats://127.0.0.1:4222), sends a PING, times the PONG
# that comes back, and by default averages five such round trips.
# --connection-name labels this connection "warehouse" so it is identifiable
# in server monitoring instead of the generic default name the CLI uses when
# you leave it unset.
nats rtt --connection-name warehouse

# You will see the average round trip per server address, something like:
#
# nats://127.0.0.1:4222:
#
# nats://127.0.0.1:4222: 187µs
#
# A printed time means the connect handshake succeeded and the server answered
# the PING. The same --connection-name flag works on every nats command (sub,
# pub, request), so name each long-lived client after the service that owns it.

Имя появляется везде, где сервер перечисляет соединения: в nats server report connections и точке мониторинга. В списке клиентов оно позволяет определить приложение без догадок по адресу и номеру. Для полного ответа команды отчёта нужны учётные данные системной учётной записи. Точка мониторинга (nats-server -m 8222) — вариант без учётных данных.

Получение собственных сообщений​

Ещё одна настройка подключения — echo. По умолчанию соединение получает собственные сообщения: если клиент публикует в тему и одновременно подписан на неё, сервер отправляет ему копию так же, как остальным подписчикам.

Обычно это незаметно: клиент подписывается на темы, в которые публикуют другие. Настройка важна, когда один клиент и публикует обновления в тему, и слушает её: он получает собственную публикацию. Отключение echo при подключении (опция NoEcho в клиентах) указывает серверу пропускать исходное соединение при доставке, чтобы клиент не получал свои сообщения. Как и имя, настройка действует весь срок жизни соединения и выбирается при его открытии.

Проверка соединения с помощью PING/PONG​

Открытое соединение может простаивать между сообщениями. Чтобы заметить отключение, сбой или потерю сетевой связи на другой стороне, не дожидаясь ошибки очередной отправки, обе стороны обмениваются heartbeat.

Механизм называется PING/PONG. Каждая сторона периодически отправляет PING и ждёт PONG. Если слишком много PING остаётся без ответа, сторона считает партнёра недоступным и закрывает соединение. Клиент и сервер делают это независимо, поэтому отказ может обнаружить любая сторона. Значения по умолчанию одинаковы: PING раз в две минуты, соединение считается потерянным после двух PING без ответа.

Выполненная выше команда nats rtt запускает этот обмен по требованию. Каждый измеренный цикл — это PING серверу и ответный PONG. По умолчанию усредняются пять таких измерений.

Heartbeat лишь обнаруживает разрыв. Восстановление через переподключение и буферизацию публикаций во время отключения описано далее в разделе Жизненный цикл соединения, а производственные настройки — в Устойчивые клиенты → Переподключение.

Подводные камни​

Новое соединение на каждое сообщение. Соединение предназначено для однократного открытия и совместного использования. Если подключаться, публиковать одно сообщение и отключаться, весь handshake повторяется каждый раз, а соединение, рассчитанное на тысячи сообщений, выбрасывается. Открывайте одно соединение при запуске сервиса и используйте его для всех публикаций и подписок.

Клиент, публикующий и подписанный на одну тему, получает собственные сообщения. При включённом echo (по умолчанию) публикации клиента возвращаются его подходящим подпискам. Если это не нужно, открывайте соединение с отключённым echo (NoEcho), чтобы исходное соединение пропускалось.

Завершение до отправки буферизованных публикаций. Публикация помещает сообщение в буфер записи клиента и сразу возвращает управление. Короткоживущая программа может завершиться до передачи буфера серверу. Перед выходом выполняйте flush. Подробности — в разделе о подводных камнях публикации и подписки: этот буфер используется и для одного сообщения, и для многих.

Что уже сделано​

Теперь в примере Acme есть работающий сервер и клиент, способный к нему подключиться:

  • Один локальный nats-server работает на nats://127.0.0.1:4222.
  • Вы понимаете соединение как одно долгоживущее TCP-соединение для всех публикаций и подписок.
  • Оно открывается по URL; до передачи сообщений сервер отправляет INFO, а клиент — CONNECT.
  • Соединение warehouse имеет имя, заданное через --connection-name, по которому сервер может его определить.
  • Echo по умолчанию возвращает клиенту его сообщения, а heartbeat PING/PONG помогает обеим сторонам заметить недоступного партнёра.

Что дальше​

Соединение открыто. Теперь используйте его: опубликуйте сообщение в тему, чтобы другие клиенты получили копию. Раздел Публикация и подписка знакомит с базовой операцией Core NATS и графом интереса, определяющим получателей каждого сообщения.

См. также​