Подключение
Приложение 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:
- CLI
- C
#!/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.
// Raw POSIX/BSD sockets -- Unix-like systems (Linux, macOS) only.
// The server sends first. Open a raw TCP connection to port 4222 --
// no NATS library involved -- and the server immediately sends its
// INFO line: plain text, ending in CRLF, describing itself and the
// limits it enforces (headers support, max_payload, ...).
struct sockaddr_in addr;
char buf[4096];
ssize_t n;
int fd = socket(AF_INET, SOCK_STREAM, 0);
memset(&addr, 0, sizeof(addr));
addr.sin_family = AF_INET;
addr.sin_port = htons(4222);
inet_pton(AF_INET, "127.0.0.1", &addr.sin_addr);
if (connect(fd, (struct sockaddr *) &addr, sizeof(addr)) != 0)
{
perror("connect");
return 2;
}
// Read what the server sent on connect and print it. This is the
// first half of the handshake; a real client would now reply with
// its own CONNECT line, which the library does for you.
n = recv(fd, buf, sizeof(buf) - 1, 0);
if (n > 0)
{
buf[n] = '\0';
printf("%s", buf);
}
Это текстовые сообщения, каждая строка которых заканчивается возвратом каретки и переводом строки. Такой же формат используют строки PUB и SUB, передающие ваши сообщения, и описанные ниже PING/PONG. Вручную их писать не нужно: клиентская библиотека выполняет весь обмен при вызове подключения. Пошаговый разбор всех полей есть в разделе Устойчивые клиенты → Подключение.
Имя соединения
Одно поле сообщения CONNECT стоит задать самостоятельно: имя соединения. По умолчанию клиент подключается без осмысленного имени, и мониторинг сервера показывает соединение без имени вообще (CLI nats подставляет общее NATS CLI Version …). Если задать имя, оно будет идентифицировать соединение.
CLI nats задаёт имя глобальным флагом --connection-name. Называйте соединение по сервису-владельцу. Здесь это warehouse, первый сервис Acme, который подключается и проверяет доступность сервера:
- CLI
- C
#!/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.
// Name the connection "warehouse" so server monitoring identifies it,
// instead of showing a connection with no name at all.
if (s == NATS_OK)
s = natsOptions_SetName(opts, "warehouse");
// Open the connection. This runs the connect handshake: the server
// sends INFO, the client answers with CONNECT carrying the name.
if (s == NATS_OK)
s = natsConnection_Connect(&conn, opts);
// Measure the round trip: one PING sent to the server, timed until
// its PONG comes back. A printed time means the handshake succeeded
// and the server is answering.
if (s == NATS_OK)
{
int64_t rtt = 0;
s = natsConnection_GetRTT(conn, &rtt);
if (s == NATS_OK)
printf("round trip: %dus\n", (int) (rtt / 1000));
}
Имя появляется везде, где сервер перечисляет соединения: в 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 и графом интереса, определяющим получателей каждого сообщения.
См. также
- Основные понятия → Что такое NATS? — клиент, сервер и модель обмена сообщениями за пять минут.
- Устойчивые клиенты → Подключение — параметры соединения, пулы серверов, тайм-аут подключения и полный разбор handshake для промышленной эксплуатации.
- Справочник → Клиентский протокол — протокольные детали
INFO,CONNECT,PINGиPONG, рассмотренных здесь на уровне модели.