# Обнаружение

Ваш сервис `OrderInventory` отвечает на `orders.inventory.check`, а `ShippingQuote` — на `shipping.quote`. Для вызова приходилось заранее знать эти субъекты. Здесь это требование снимается.

Каждый создаваемый фреймворком сервис автоматически отвечает ещё на один набор субъектов: **команды обнаружения**. Через них клиент может спросить работающую систему, какие сервисы существуют, на что каждый отвечает и как он работает, без жёстко заданных субъектов и отдельного реестра.

Для этого не нужно добавлять код. Как только `AddService` вернулся на странице `your-first-service`, фреймворк подписался на эти субъекты за вас. Здесь показано, как ими пользоваться.

## Три команды обнаружения

Обнаружение — **получение сведений о существующих сервисах и обслуживаемых ими запросах** через фиксированный набор субъектов с префиксом `$SRV`. Каждый сервис отвечает на три команды:

* **PING** проверяет наличие сервиса. Ответ содержит имя сервиса, идентификатор экземпляра и версию. Используется для поиска сервисов и измерения времени кругового обхода.
* **INFO** сообщает, на что отвечает сервис. Ответ добавляет описание и список конечных точек с субъектами и группами очередей.
* **STATS** сообщает, как работает сервис. Ответ добавляет счётчики по конечным точкам. Их прочитаем на следующей странице; пока достаточно знать о команде.

Команды и их субъекты записываются прописными буквами. Сам сервис не публикует в `$SRV`: он подписывается там и отвечает на ваши запросы с помощью знакомого механизма запросов и ответов.

## Три уровня адресации

Каждая команда работает на трёх уровнях, сужая область от всех сервисов до одного экземпляра:

| Субъект                         | Кто отвечает                             |
| ------------------------------- | ---------------------------------------- |
| `$SRV.INFO`                     | Все сервисы аккаунта                     |
| `$SRV.INFO.OrderInventory`      | Все экземпляры с именем `OrderInventory` |
| `$SRV.INFO.OrderInventory.<id>` | Один экземпляр с этим идентификатором    |

Те же уровни работают для `PING` и `STATS`. Первый позволяет перечислить содержимое незнакомой системы. Второй ограничивает запрос одним именем сервиса. Третий обращается к одному **экземпляру** — работающей копии сервиса с **идентификатором**, сгенерированным фреймворком.

Попросите `OrderInventory` описать себя на уровне имени и прочитайте список конечных точек из ответа:

#### CLI

```
#!/bin/bash

# Ask the OrderInventory service to describe itself. INFO is a discovery

# verb every service answers automatically on the $SRV subject tree. The

# name level ($SRV.INFO.OrderInventory) reaches every running instance of

# OrderInventory, and each one replies with its name, id, version, and the

# list of endpoints it serves.

#

# Discovery is broadcast: a plain request would return only the first

# reply, so the CLI waits a short window and collects every responder.

# That is why the timeout matters here.

nats request '$SRV.INFO.OrderInventory' '' --replies=0 --timeout=1s



# The reply for each instance is JSON like:

#

#   {

#     "type": "io.nats.micro.v1.info_response",

#     "name": "OrderInventory",

#     "id": "JJTBR2MN3JSAYBI5ST7E32",

#     "version": "1.0.0",

#     "endpoints": [

#       { "name": "check",

#         "subject": "orders.inventory.check",

#         "queue_group": "q" }

#     ]

#   }

#

# Read the endpoints array to learn what the service answers and on which

# subject -- no documentation lookup required.

#

# The same information, formatted, comes from the CLI ops shortcut:

nats service info OrderInventory
```

#### C

```
// Ask every running instance of OrderInventory to describe itself.

// INFO is a discovery verb the framework answers automatically; the

// name level ($SRV.INFO.OrderInventory) reaches every instance, and

// each one replies with its name, id, version, and endpoint list.

//

// Discovery is broadcast: a plain request would return only the first

// reply. Subscribe to a private inbox, send the request there, and

// collect replies until none arrives within the deadline.

int instances = 0;



if (s == NATS_OK)

    s = natsInbox_Create(&inbox);

if (s == NATS_OK)

    s = natsConnection_SubscribeSync(&sub, conn, (const char *) inbox);

if (s == NATS_OK)

    s = natsConnection_PublishRequestString(conn, "$SRV.INFO.OrderInventory",

                                            (const char *) inbox, "");



while (s == NATS_OK)

{

    natsMsg *info = NULL;



    // Stop once no further instance replies within the deadline.

    s = natsSubscription_NextMsg(&info, sub, 1000);

    if (s != NATS_OK)

        break;



    // Each reply is an info_response JSON document; its "endpoints"

    // array lists each endpoint's subject and queue group.

    printf("info: %.*s\n",

           natsMsg_GetDataLength(info), natsMsg_GetData(info));

    instances++;

    natsMsg_Destroy(info);

}

printf("collected %d instance(s)\n", instances);
```

Ответ сообщает, что конечная точка `check` слушает `orders.inventory.check` в группе очереди `"q"`. Раньше вы настроили это вручную, а теперь любой клиент может получить сведения от работающего сервиса, не полагаясь на документацию.

Сетевой формат `$SRV.PING`/`INFO`/`STATS` и схемы ответов JSON описаны в [справочнике](/reference/services/.md). Здесь нам нужно только поведение.

## Обнаружение использует широковещательные запросы без балансировки

Одна деталь работает иначе, чем можно ожидать. Созданные конечные точки отвечают в **группе очереди**, поэтому каждый запрос получает ровно один экземпляр. Команды обнаружения **не используют** такую группу. Запрос `$SRV.INFO.OrderInventory` достигает *каждого* экземпляра `OrderInventory`, и каждый отвечает.

Это намеренное поведение. Цель обнаружения — получить ответ от всех экземпляров, например от всех трёх, а не от первого ответившего. Поэтому клиент не ждёт один ответ: он задаёт короткое время ожидания и собирает все пришедшие за него ответы.

**Движение сообщений — Обнаружение сервисов (анимация):** Обнаружение сервисов: сначала широковещательный, затем адресный запрос. Первый расходится ко всем трём экземплярам OrderInventory, каждый возвращает INFO. Второй содержит идентификатор id2 и достигает только его; лишь он возвращает STATS. Те же темы сервиса обеспечивают оба вида запросов.

* клиент → сервер
* сервер → клиент

Анимация показывает, как один запрос `$SRV.INFO.OrderInventory` расходится ко всем трём экземплярам и возвращаются три ответа INFO. Последний адресный запрос `$SRV.STATS.OrderInventory.id2` достигает только `id2`: третий уровень адресации направляет запрос одному экземпляру.

## Обращение к одному экземпляру

Если идентификатор уже известен из ответа PING или INFO, можно обратиться только к этому экземпляру. Так можно изучать или сравнивать отдельную копию сервиса среди множества работающих.

Третий уровень достигает ровно одного экземпляра, поэтому ожидается один ответ и цикл сбора с ограничением по времени не нужен:

#### CLI

```
#!/bin/bash

# The third discovery level adds the service id, addressing exactly one

# instance instead of all of them. Use it when several instances of

# OrderInventory are running and you want to inspect one in particular.

#

# Pick an id from an earlier INFO or PING reply, then target it. Replace

# the id below with one your own service printed.

INSTANCE_ID="JJTBR2MN3JSAYBI5ST7E32"



# $SRV.STATS.OrderInventory.<id> reaches only the instance with that id,

# so a single reply is expected -- no deadline loop needed for one

# instance.

nats request "\$SRV.STATS.OrderInventory.$INSTANCE_ID" '' --timeout=1s



# PING at the instance level is the lightweight check: it confirms that

# one specific instance is alive and reports its name, id, and version.

nats request "\$SRV.PING.OrderInventory.$INSTANCE_ID" '' --timeout=1s
```

#### C

```
// The third discovery level adds the service id, addressing exactly

// one instance instead of all of them. Pick an id from an earlier

// INFO or PING reply; replace the one below with your own.

const char *instanceID = "JJTBR2MN3JSAYBI5ST7E32";

natsMsg    *reply      = NULL;

char       subject[256];



// $SRV.STATS.OrderInventory.<id> reaches only the instance with that

// id, so a single reply is expected -- no deadline loop needed.

snprintf(subject, sizeof(subject),

         "$SRV.STATS.OrderInventory.%s", instanceID);

if (s == NATS_OK)

    s = natsConnection_RequestString(&reply, conn, subject, "", 1000);

if (s == NATS_OK)

{

    printf("stats: %.*s\n",

           natsMsg_GetDataLength(reply), natsMsg_GetData(reply));

    natsMsg_Destroy(reply);

    reply = NULL;

}



// PING at the instance level is the lightweight check: it confirms

// that one specific instance is alive and reports its name, id, and

// version.

snprintf(subject, sizeof(subject),

         "$SRV.PING.OrderInventory.%s", instanceID);

if (s == NATS_OK)

    s = natsConnection_RequestString(&reply, conn, subject, "", 1000);

if (s == NATS_OK)

{

    printf("ping: %.*s\n",

           natsMsg_GetDataLength(reply), natsMsg_GetData(reply));

    natsMsg_Destroy(reply);

}
```

## Сбор ответов через CLI

Для интерактивной работы CLI `nats` выполняет цикл сбора широковещательных ответов за вас. `nats service list` перечисляет все найденные сервисы и экземпляры; `nats service info` выводит конечные точки сервиса; `nats service ping` измеряет время кругового обхода до каждого отвечающего экземпляра:

```
nats service list

nats service info OrderInventory

nats service ping
```

Внутри выполняются те же запросы `$SRV`, а ответы собираются до истечения времени ожидания. При разработке это самый быстрый способ увидеть запущенные сервисы; ваши собственные инструменты используют программные команды, показанные выше.

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

При первых запросах обнаружения распространены две ошибки. Обе связаны с широковещательным поведением.

**Обнаружение широковещательное: один ответ не даёт всей картины.** Обычный запрос возвращает первый ответ и завершает ожидание. Для `$SRV.INFO.OrderInventory` это показывает один экземпляр и незаметно скрывает остальные: пять работающих экземпляров выглядят как один. Не обрабатывайте обнаружение как обычный вызов запроса и ответа. Ждите до заданного срока и собирайте все ответы, как CLI:

#### CLI

```
#!/bin/bash

# Ask the OrderInventory service to describe itself. INFO is a discovery

# verb every service answers automatically on the $SRV subject tree. The

# name level ($SRV.INFO.OrderInventory) reaches every running instance of

# OrderInventory, and each one replies with its name, id, version, and the

# list of endpoints it serves.

#

# Discovery is broadcast: a plain request would return only the first

# reply, so the CLI waits a short window and collects every responder.

# That is why the timeout matters here.

nats request '$SRV.INFO.OrderInventory' '' --replies=0 --timeout=1s



# The reply for each instance is JSON like:

#

#   {

#     "type": "io.nats.micro.v1.info_response",

#     "name": "OrderInventory",

#     "id": "JJTBR2MN3JSAYBI5ST7E32",

#     "version": "1.0.0",

#     "endpoints": [

#       { "name": "check",

#         "subject": "orders.inventory.check",

#         "queue_group": "q" }

#     ]

#   }

#

# Read the endpoints array to learn what the service answers and on which

# subject -- no documentation lookup required.

#

# The same information, formatted, comes from the CLI ops shortcut:

nats service info OrderInventory
```

#### C

```
// Ask every running instance of OrderInventory to describe itself.

// INFO is a discovery verb the framework answers automatically; the

// name level ($SRV.INFO.OrderInventory) reaches every instance, and

// each one replies with its name, id, version, and endpoint list.

//

// Discovery is broadcast: a plain request would return only the first

// reply. Subscribe to a private inbox, send the request there, and

// collect replies until none arrives within the deadline.

int instances = 0;



if (s == NATS_OK)

    s = natsInbox_Create(&inbox);

if (s == NATS_OK)

    s = natsConnection_SubscribeSync(&sub, conn, (const char *) inbox);

if (s == NATS_OK)

    s = natsConnection_PublishRequestString(conn, "$SRV.INFO.OrderInventory",

                                            (const char *) inbox, "");



while (s == NATS_OK)

{

    natsMsg *info = NULL;



    // Stop once no further instance replies within the deadline.

    s = natsSubscription_NextMsg(&info, sub, 1000);

    if (s != NATS_OK)

        break;



    // Each reply is an info_response JSON document; its "endpoints"

    // array lists each endpoint's subject and queue group.

    printf("info: %.*s\n",

           natsMsg_GetDataLength(info), natsMsg_GetData(info));

    instances++;

    natsMsg_Destroy(info);

}

printf("collected %d instance(s)\n", instances);
```

Верно и обратное: если нужен определённый экземпляр, используйте уровень `$SRV.STATS.OrderInventory.<id>` вместо фильтрации широковещательных ответов. Он обращается к экземпляру напрямую и возвращает один ответ.

**`$SRV` — зарезервированный префикс субъектов: не публикуйте туда собственные сообщения.** Всё дерево `$SRV` принадлежит фреймворку: сервисы подписываются там для ответов PING, INFO и STATS. Ваши публикации под `$SRV` мешают этому механизму и искажают результаты обнаружения. Используйте собственные префиксы (`orders.*`, `shipping.*`) и оставьте `$SRV` фреймворку. Кто может видеть `$SRV` через границы аккаунтов — отдельный вопрос из главы [Безопасность](/learn/security/.md).

## Текущее состояние

Теперь систему можно обнаруживать, а не запоминать. Команды PING, INFO и STATS под `$SRV` позволяют перечислить все сервисы аккаунта, узнать конечные точки сервиса и обратиться к одному экземпляру по идентификатору. Вы также знаете ограничение: обнаружение широковещательное, поэтому нужно собирать ответы до заданного срока, а не брать первый.

`OrderInventory` и `ShippingQuote` продолжают работать. Сами они не изменились; вы лишь научились спрашивать их о себе.

## Что дальше

INFO сообщает, *на что* отвечает сервис. STATS показывает, *как он работает*: число запросов, число ошибок и время обработки каждой конечной точки. На следующей странице прочитаем эти счётчики и посмотрим, как обработчик регистрирует ошибку.

Переходите к странице [Наблюдаемость](/learn/services/observability.md).

## См. также

* [Запросы и ответы](/learn/core-nats/request-reply.md) — механизм доставки каждого ответа `$SRV`.
* [Наблюдаемость](/learn/services/observability.md) — сведения STATS и их чтение.
* [Справочник](/reference/services/.md) — сетевой формат `$SRV` и схемы ответов.
