# Подключение

Приложение 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](/learn/websocket/.md).

Один URL задаёт один сервер. В промышленной эксплуатации клиенту обычно передают несколько URL, чтобы он мог переключаться при недоступности сервера. Список и порядок перебора рассматриваются в разделе [Устойчивые клиенты → Подключение](/learn/resilient-clients/connecting.md). Здесь достаточно одного локального сервера.

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

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

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

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

#### CLI

```
#!/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.
```

#### C

```
// 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`. Вручную их писать не нужно: клиентская библиотека выполняет весь обмен при вызове подключения. Пошаговый разбор всех полей есть в разделе [Устойчивые клиенты → Подключение](/learn/resilient-clients/connecting.md).

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

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

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

#### CLI

```
#!/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.
```

#### C

```
// 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` и [точке мониторинга](/learn/monitoring/monitoring-endpoints.md). В списке клиентов оно позволяет определить приложение без догадок по адресу и номеру. Для полного ответа команды отчёта нужны учётные данные системной учётной записи. Точка мониторинга (`nats-server -m 8222`) — вариант без учётных данных.

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

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

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

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

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

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

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

Heartbeat лишь обнаруживает разрыв. Восстановление через переподключение и буферизацию публикаций во время отключения описано далее в разделе [Жизненный цикл соединения](/learn/core-nats/connection-lifecycle.md), а производственные настройки — в [Устойчивые клиенты → Переподключение](/learn/resilient-clients/reconnection.md).

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

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

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

**Завершение до отправки буферизованных публикаций.** Публикация помещает сообщение в буфер записи клиента и сразу возвращает управление. Короткоживущая программа может завершиться до передачи буфера серверу. Перед выходом выполняйте flush. Подробности — в [разделе о подводных камнях публикации и подписки](/learn/core-nats/publish-subscribe.md#pitfalls): этот буфер используется и для одного сообщения, и для многих.

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

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

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

## Что дальше

Соединение открыто. Теперь используйте его: опубликуйте сообщение в тему, чтобы другие клиенты получили копию. Раздел [Публикация и подписка](/learn/core-nats/publish-subscribe.md) знакомит с базовой операцией Core NATS и графом интереса, определяющим получателей каждого сообщения.

## См. также

* [Основные понятия → Что такое NATS?](/concepts/what-is-nats.md) — клиент, сервер и модель обмена сообщениями за пять минут.
* [Устойчивые клиенты → Подключение](/learn/resilient-clients/connecting.md) — параметры соединения, пулы серверов, тайм-аут подключения и полный разбор handshake для промышленной эксплуатации.
* [Справочник → Клиентский протокол](/reference/protocols/client.md) — протокольные детали `INFO`, `CONNECT`, `PING` и `PONG`, рассмотренных здесь на уровне модели.
