Подключение
Первый шаг устойчивости — открыть соединение. Одного URL хватало ноутбуку; при эксплуатации именно достижение сервера и аутентификация часто отказывают первыми.
Зададим параметры, имя и несколько серверов и рассмотрим протокол connect. Дальнейшие механизмы будут опираться на эту связь.
Параметры соединения
Они задаются при connect на срок соединения. Сначала важны три.
Имя order-svc позволяет найти приложение в nats server report connections и журналах вместо анонимного клиента.
Пул серверов — допустимые URL. Несколько дают переключение уже при первом подключении, если один недоступен.
Начнём именованным соединением к одному серверу:
- CLI
- C
#!/bin/bash
# Open order-svc's connection to a single server and give it a name.
#
# The --connection-name flag labels the connection so it is identifiable
# in `nats server report connections`. Without it, the CLI connects under
# its default name (`NATS CLI Version <version>`), so you cannot tell
# order-svc apart from any other CLI run.
#
# This publishes the canonical order event once the connection is up.
nats pub orders.created \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}' \
--server nats://n1:4222 \
--connection-name order-svc
// Name the connection so `nats server report connections` and the
// server logs show order-svc instead of an anonymous client.
if (s == NATS_OK)
s = natsOptions_SetName(opts, "order-svc");
if (s == NATS_OK)
s = natsConnection_Connect(&conn, opts);
// Publish the canonical order event once the connection is up.
if (s == NATS_OK)
s = natsConnection_PublishString(conn, "orders.created",
"{\"order_id\":\"ord_8w2k\",\"customer\":\"acme-co\","
"\"total_cents\":4200,\"ts\":\"2026-05-22T10:14:22Z\"}");
Во всех примерах прежнее событие:
{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}
Случайный порядок пула
По умолчанию URL перемешиваются: разные клиенты начинают с разных n1/n2/n3, распределяя нагрузку.
Для намеренного порядка есть NoRandomize, Python dont_randomize, Rust retain_servers_order. Обычно оставляйте случайность против массового наплыва на первый узел.
Подключение к трём адресам:
- CLI
- C
#!/bin/bash
# Open order-svc against a server pool instead of a single server.
#
# Pass every server URL the client may connect to, comma-separated. The
# client picks one at random by default; if the first dial fails it tries
# the next. That is failover at connect time, before a single message is
# sent.
#
# --connection-name labels the connection. The CLI does not expose the
# connect-timeout knob; in a client library, set the timeout that bounds
# how long each dial may block.
nats pub orders.created \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}' \
--server "nats://n1:4222,nats://n2:4222,nats://n3:4222" \
--connection-name order-svc
// The server pool: every URL order-svc may dial. The client
// randomizes this list before dialing, so a restart of every
// instance spreads across the servers instead of piling onto the
// first URL. natsOptions_SetNoRandomize(opts, true) would keep a
// deliberate preferred order.
const char *servers[] = {"nats://n1:4222", "nats://n2:4222",
"nats://n3:4222"};
if (s == NATS_OK)
s = natsOptions_SetServers(opts, servers, 3);
if (s == NATS_OK)
s = natsOptions_SetName(opts, "order-svc");
// Bound each dial: an unreachable server costs at most 2 seconds
// before the client moves on to the next URL in the pool.
if (s == NATS_OK)
s = natsOptions_SetTimeout(opts, 2000);
if (s == NATS_OK)
s = natsConnection_Connect(&conn, opts);
if (s == NATS_OK)
s = natsConnection_PublishString(conn, "orders.created",
"{\"order_id\":\"ord_8w2k\",\"customer\":\"acme-co\","
"\"total_cents\":4200,\"ts\":\"2026-05-22T10:14:22Z\"}");
Устройство кластера — Ваш первый кластер. Здесь это просто доступный пул.
Обнаруженные серверы
INFO при установлении связи содержит connect_urls соседей, а изменения списка сообщаются весь срок связи. Это gossip; клиент добавляет адреса в пул как обнаруженные.
Они так же перемешиваются и используются при восстановлении. Настроенные остаются навсегда, обнаруженные могут удалиться после исчезновения объявления. Даже один n1 после INFO даёт n1/n2/n3.
Объединение включено везде. Отключение: Go IgnoreDiscoveredServers, Java ignoreDiscoveredServers(), Rust ignore_discovered_servers, JavaScript ignoreClusterUpdates. Python и C# не отключают. Причина отказа от обнаружения — недостижимые из клиентской сети объявленные адреса.
Сигналы обнаружения: Go DiscoveredServersCB, Python discovered_server_cb, Java DISCOVERED_SERVERS, JavaScript update с добавленными/удалёнными. Rust/C# сигнала нет. Подробнее — События.
CLI с --trace выводит >>> Discovered new servers, known servers are now ...:
- CLI
- C
#!/bin/bash
# Watch the pool grow beyond what you configured.
#
# Connect to n1 only. The first INFO from n1 already lists the other
# cluster members in connect_urls, so the client's pool holds all three
# servers even though --server names one. That first merge is silent.
#
# --trace makes the CLI log later pool growth: when a server the client
# has not seen before joins the cluster mid-connection, it prints
#
# >>> Discovered new servers, known servers are now ...
#
# followed by the full pool. The client libraries expose the same
# signal as a callback or event.
nats sub "orders.>" \
--server nats://n1:4222 \
--connection-name order-svc \
--trace
static void
printPool(natsConnection *nc)
{
char **servers = NULL;
int count = 0;
int i;
if (natsConnection_GetServers(nc, &servers, &count) != NATS_OK)
return;
for (i = 0; i < count; i++)
{
printf(" %s\n", servers[i]);
free(servers[i]);
}
free(servers);
}
// Fires when gossip adds a server the client has not seen before.
static void
onDiscoveredServers(natsConnection *nc, void *closure)
{
printf("discovered new servers, known servers are now:\n");
printPool(nc);
}
if (s == NATS_OK)
s = natsOptions_SetName(opts, "order-svc");
// Register the discovered-servers callback before connecting.
if (s == NATS_OK)
s = natsOptions_SetDiscoveredServersCB(opts, onDiscoveredServers, NULL);
if (s == NATS_OK)
s = natsConnection_Connect(&conn, opts);
// The first INFO already merged the rest of the cluster into the
// pool, silently: one configured URL, three known servers.
if (s == NATS_OK)
{
printf("configured one server, pool after connect:\n");
printPool(conn);
}
При no_advertise сервер не отправляет connect_urls: останется заданный пул. См. Топологии.
Тайм-аут подключения
DNS, TCP и ответ сервера могут зависнуть из-за адреса, межсетевого экрана или перегрузки. Ожидание должно быть ограничено.
Connect timeout ограничивает одну попытку до следующего URL. Обычно две секунды, в Rust пять, JavaScript двадцать. Проверьте библиотеку и задайте по сети осознанно.
Пул даёт альтернативы, тайм-аут — время отказа от одной. Недоступный узел стоит один интервал, затем следующий.
Точные клиентские API — в справке библиотеки, серверные параметры — в справочнике.
Протокол установления связи
Параметры выбирают сервер, handshake превращает TCP в рабочую NATS-связь.
Четыре шага:
- TCP к выбранному серверу с ограниченным временем.
- INFO сервера: server_id, max_payload, auth_required, tls_required и другое.
- CONNECT клиента: имя, данные входа, возможности; затем PING.
- PONG означает CONNECTED. При отказе -ERR, например Authorization Violation, и закрытие сокета. Verbose также даёт +OK на CONNECT, но обычно выключен.
Схема двух исходов — принятие и отказ:
Особенно важны поля:
Auth_required заранее объявляет необходимость данных входа. Без них -ERR до CONNECTED; передача — TLS и аутентификация.
Max_payload, стандартно мегабайт, проверяется клиентом до отправки. Слишком большой orders.created отклоняется локально.
Типичные ошибки
Неудача возможна до первой публикации: сервер может принять TCP, но вернуть -ERR maximum connections exceeded. Повтор connect тоже требует задержки.
Один URL — точка отказа первого входа. Настройте несколько URL или IP за именем.
Опора только на discovery ненадёжна. Оно зависит от объявления и достижимости адресов. Задайте все обязательные серверы, найденные считайте дополнением.
Долгий dial тормозит запуск. Явный короткий срок плюс пул ограничивает цену зависшего узла.
Большое сообщение — ошибка publish, не connect. Не лечите переподключением. Большой объект храните отдельно с передачей ссылки.
Обрабатывайте неудачный вход у границы приложения:
- CLI
- C
#!/bin/bash
# Connecting can fail before any message moves. This script handles the case
# the page's pitfalls build up to: no server in the pool is reachable, so the
# connect itself fails.
#
# With the CLI, a failed connect prints the error and exits non-zero, so
# you can branch on it. The client libraries surface the same failures as
# an error you catch at connect time.
# A pool whose first URL is unreachable: the client tries the next one.
# If every dial fails, the command exits non-zero and prints the reason.
if nats pub orders.created \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}' \
--server "nats://n1:4222,nats://n2:4222,nats://n3:4222" \
--connection-name order-svc; then
echo "connected and published"
else
echo "could not connect to any server in the pool" >&2
exit 1
fi
// A pool whose first pick may be unreachable: the client tries the
// next URL. Connect fails only when every dial failed.
const char *servers[] = {"nats://n1:4222", "nats://n2:4222",
"nats://n3:4222"};
if (s == NATS_OK)
s = natsOptions_SetServers(opts, servers, 3);
if (s == NATS_OK)
s = natsOptions_SetName(opts, "order-svc");
// Handle the failure at the boundary. NATS_NO_SERVER means no
// server in the pool answered; anything else is a rejected connect,
// an -ERR from a server the client did reach.
if (s == NATS_OK)
s = natsConnection_Connect(&conn, opts);
if (s == NATS_NO_SERVER)
{
fprintf(stderr, "could not connect to any server in the pool\n");
natsOptions_Destroy(opts);
exit(1);
}
if (s == NATS_OK)
s = natsConnection_PublishString(conn, "orders.created",
"{\"order_id\":\"ord_8w2k\",\"customer\":\"acme-co\","
"\"total_cents\":4200,\"ts\":\"2026-05-22T10:14:22Z\"}");
if (s == NATS_OK)
printf("connected and published\n");
Что уже готово
Order-svc имеет:
- Имя.
- Перемешиваемый n1/n2/n3.
- Дополнение из connect_urls.
- Ограничение времени каждой попытки.
Вы знаете TCP → INFO → CONNECT → PONG и значения auth_required/max_payload.
Что дальше
Переподключение переживает потерю уже открытого канала с задержками и буфером.
Перейдите к Переподключению.
См. также
- Ваш первый кластер — серверная сторона пула.
- TLS и аутентификация — данные входа.