Scatter-gather
Сервис наличия товаров отвечал на запрос одним ответом — обычный случай, когда на один вопрос нужен один ответ.
У некоторых вопросов несколько ответов. Например: «Сколько стоит доставить заказ?» Acme работает с тремя перевозчиками, и каждый предлагает свою цену. Сервис заказов хочет получить все три предложения и выбрать самое дешёвое.
Это scatter-gather: отправить один запрос всем отвечающим сервисам и собрать ответы. На этой странице мы построим такой обмен через shipping.quote с тремя поставщиками тарифов.
Почему один запрос даёт несколько ответов
Вспомните запрос-ответ: клиент подписывается на уникальную тему _INBOX и публикует запрос с этим inbox как темой ответа. Механизм не ограничивает число отвечающих. Если три поставщика подписаны на shipping.quote, все получают запрос через обычную публикацию и подписку и все могут ответить в inbox. Ранее единственный ответ был результатом одного отвечающего сервиса и клиента, остановившегося после первого ответа.
Это работает, только если сервисы не состоят в общей группе очереди: группа передаёт запрос одному участнику, обеспечивая балансировку, а не scatter-gather. Каждый сервис должен иметь независимую подписку. CLI-пример ниже явно задаёт такое поведение, поскольку по умолчанию CLI делает обратное.
Создание трёх поставщиков тарифов
Поставщик подписывается на shipping.quote, читает заказ и отвечает ценой. Запустите три экземпляра с разными ценами.
- CLI
- JavaScript/TypeScript
- Go
- Python
- Java
- Rust
- C#/.NET
- C
#!/bin/bash
# Three shipping-quote providers, each answering on shipping.quote.
#
# IMPORTANT: `nats reply` subscribes inside a queue group by default
# (NATS-RPLY-22). Three providers left on that default would share ONE
# queue group, so only one would ever answer. To scatter the request to
# all three, give each provider its OWN queue group name with --queue.
# A queue group of one member behaves like a plain subscriber.
#
# Run each line in its own terminal.
# Terminal 1 — carrier A quotes 1500 cents.
nats reply shipping.quote --queue carrier-a '{"carrier":"carrier-a","quote_cents":1500}'
# Terminal 2 — carrier B quotes 1200 cents.
nats reply shipping.quote --queue carrier-b '{"carrier":"carrier-b","quote_cents":1200}'
# Terminal 3 — carrier C quotes 1800 cents.
nats reply shipping.quote --queue carrier-c '{"carrier":"carrier-c","quote_cents":1800}'
// A shipping-quote provider. Subscribe plainly to shipping.quote (NOT in a
// queue group, so every provider sees each request) and reply with a price.
// Run several copies, each quoting a different number.
const sub = nc.subscribe("shipping.quote");
for await (const msg of sub) {
msg.respond('{"carrier":"carrier-a","quote_cents":1500}');
}
// A shipping-quote provider. Subscribe plainly to shipping.quote (NOT a
// queue group, so every provider sees each request) and reply with a price.
// Run several copies, each quoting a different number.
nc.Subscribe("shipping.quote", func(m *nats.Msg) {
m.Respond([]byte(`{"carrier":"carrier-a","quote_cents":1500}`))
})
# A shipping-quote provider. Subscribe plainly to shipping.quote (NOT in a
# queue group, so every provider sees each request) and reply with a price.
# Run several copies, each quoting a different number.
async with await client.subscribe("shipping.quote") as subscription:
async for message in subscription:
if message.reply:
await client.publish(message.reply, b'{"carrier":"carrier-a","quote_cents":1500}')
// A shipping-quote provider. Subscribe plainly to shipping.quote (NOT in a
// queue group, so every provider sees each request) and reply with a price.
// Run several copies, each quoting a different number.
nc.createDispatcher(msg -> {
if (msg.getReplyTo() != null) {
nc.publish(msg.getReplyTo(),
"{\"carrier\":\"carrier-a\",\"quote_cents\":1500}".getBytes(StandardCharsets.UTF_8));
}
}).subscribe("shipping.quote");
// A shipping-quote provider. Subscribe plainly to shipping.quote (NOT in a
// queue group, so every provider sees each request) and reply with a price.
// Run several copies, each quoting a different number.
let mut sub = client.subscribe("shipping.quote").await?;
while let Some(msg) = sub.next().await {
if let Some(reply) = msg.reply {
client
.publish(
reply,
r#"{"carrier":"carrier-a","quote_cents":1500}"#.into(),
)
.await?;
}
}
// A shipping-quote provider. Subscribe plainly to shipping.quote (NOT in a
// queue group, so every provider sees each request) and reply with a price.
// Run several copies, each quoting a different number.
await foreach (var msg in client.SubscribeAsync<Order>("shipping.quote"))
{
await msg.ReplyAsync(new ShippingQuote(Carrier: "carrier-a", QuoteCents: 1500));
}
// A shipping-quote provider. Subscribe plainly to shipping.quote (NOT a
// queue group, so every provider sees each request) and reply with a
// price. Run several copies, each quoting a different number.
static void
onQuote(natsConnection *nc, natsSubscription *sub, natsMsg *msg, void *closure)
{
if (natsMsg_GetReply(msg) != NULL)
natsConnection_PublishString(nc, natsMsg_GetReply(msg),
"{\"carrier\":\"carrier-a\",\"quote_cents\":1500}");
natsMsg_Destroy(msg);
}
if (s == NATS_OK)
s = natsConnection_Subscribe(&sub, conn, "shipping.quote",
onQuote, NULL);
У nats reply есть особенность: по умолчанию CLI подписывается в группе очереди NATS-RPLY-22. Три экземпляра nats reply с настройками по умолчанию образуют одну группу, и отвечает лишь один из них. Это балансировка с предыдущей страницы, а здесь нужно другое.
Чтобы поставщики отвечали независимо, задайте каждому своё имя группы через --queue. Группа из одного участника ведёт себя как обычный подписчик: получает каждый подходящий запрос. CLI-пример выше запускает поставщиков с разными именами (carrier-a, carrier-b, carrier-c), поэтому все трое видят каждый запрос.
В библиотеках такой особенности нет. Без явного запроса группы создаётся обычная подписка, поэтому три обычных подписчика shipping.quote уже получают каждый запрос.
Сбор по числу ответов
Теперь сбор. Клиент отправляет один запрос в shipping.quote и собирает ответы всех поставщиков.
- CLI
- JavaScript/TypeScript
- Go
- Python
- Java
- Rust
- C#/.NET
- C
#!/bin/bash
# Send one request to shipping.quote and gather replies from every provider.
# Gather by count: stop after 3 replies have arrived.
nats request shipping.quote \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}' \
--replies 3 --timeout 2s
# Gather by deadline instead: --replies 0 collects every reply that arrives
# during the full --timeout window, then returns. It is a fixed, predictable
# budget; --reply-timeout has no effect in this mode. Use this when you do
# not know how many providers are running.
nats request shipping.quote \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}' \
--replies 0 --timeout 2s
// Scatter one request to every shipping-quote provider and gather the replies.
// Subscribe to a private inbox, publish the request with that inbox as the
// reply subject, then collect quotes until they stop arriving and pick the
// cheapest.
const order =
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}';
const inbox = createInbox();
const sub = nc.subscribe(inbox);
nc.publish("shipping.quote", order, { reply: inbox });
const quotes: string[] = [];
const gather = (async () => {
for await (const msg of sub) {
quotes.push(msg.string());
}
})();
// Stop once no further reply is expected.
setTimeout(() => sub.unsubscribe(), 300);
await gather;
console.log(`gathered ${quotes.length} quotes: ${JSON.stringify(quotes)}`);
// Scatter one request to every shipping-quote provider and gather the
// replies. Subscribe to a private inbox, publish the request with that
// inbox as the reply subject, then collect quotes until they stop arriving
// and pick the cheapest.
order := `{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}`
inbox := nats.NewInbox()
sub, _ := nc.SubscribeSync(inbox)
nc.PublishRequest("shipping.quote", inbox, []byte(order))
var quotes []string
for {
msg, err := sub.NextMsg(300 * time.Millisecond)
if err != nil {
break
}
quotes = append(quotes, string(msg.Data))
}
fmt.Printf("gathered %d quotes: %v\n", len(quotes), quotes)
# Scatter one request to every shipping-quote provider and gather the
# replies. Subscribe to a private inbox, publish the request with that inbox
# as the reply subject, then collect quotes until they stop arriving and
# pick the cheapest.
order = '{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
inbox = f"_INBOX.{uuid.uuid4().hex}"
async with await client.subscribe(inbox) as subscription:
await client.publish("shipping.quote", order.encode(), reply=inbox)
quotes = []
while True:
try:
message = await subscription.next(timeout=0.3)
quotes.append(message.data.decode())
except TimeoutError:
break
print(f"gathered {len(quotes)} quotes: {quotes}")
// Scatter one request to every shipping-quote provider and gather the
// replies. Subscribe to a private inbox, publish the request with that
// inbox as the reply subject, then collect quotes until they stop arriving
// and pick the cheapest.
byte[] order = ("{\"order_id\":\"ord_8w2k\",\"customer\":\"acme-co\","
+ "\"total_cents\":4200,\"ts\":\"2026-05-22T10:14:22Z\"}").getBytes(StandardCharsets.UTF_8);
String inbox = nc.createInbox();
Subscription sub = nc.subscribe(inbox);
nc.publish("shipping.quote", inbox, order);
List<String> quotes = new ArrayList<>();
Message m = sub.nextMessage(Duration.ofMillis(300));
while (m != null) {
quotes.add(new String(m.getData(), StandardCharsets.UTF_8));
m = sub.nextMessage(Duration.ofMillis(300));
}
System.out.println("gathered " + quotes.size() + " quotes");
// Scatter one request to every shipping-quote provider and gather the
// replies. Subscribe to a private inbox, publish the request with that inbox
// as the reply subject, then collect quotes until they stop arriving and
// pick the cheapest.
let order = r#"{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}"#;
let inbox = client.new_inbox();
let mut sub = client.subscribe(inbox.clone()).await?;
client
.publish_with_reply("shipping.quote", inbox, order.into())
.await?;
client.flush().await?;
let mut quotes = Vec::new();
while let Ok(Some(msg)) = tokio::time::timeout(Duration::from_millis(300), sub.next()).await {
quotes.push(String::from_utf8_lossy(&msg.payload).to_string());
}
println!("gathered {} quotes: {:?}", quotes.len(), quotes);
// Scatter one request to every shipping-quote provider and gather the
// replies. Subscribe to a private inbox, publish the request with that inbox
// as the reply subject, then collect quotes until they stop arriving and
// pick the cheapest.
var order = new Order(OrderId: "ord_8w2k", Customer: "acme-co", TotalCents: 4200, Timestamp: DateTimeOffset.Parse("2026-05-22T10:14:22Z", CultureInfo.InvariantCulture));
var inbox = client.Connection.NewInbox();
await using var sub = await client.Connection.SubscribeCoreAsync<ShippingQuote>(inbox);
await client.PublishAsync<Order>("shipping.quote", order, replyTo: inbox);
var quotes = new List<ShippingQuote>();
using var cts = new CancellationTokenSource(TimeSpan.FromMilliseconds(300));
try
{
await foreach (var msg in sub.Msgs.ReadAllAsync(cts.Token))
{
quotes.Add(msg.Data!);
}
}
catch (OperationCanceledException)
{
}
output.WriteLine($"gathered {quotes.Count} quotes");
// Scatter one request to every shipping-quote provider and gather the
// replies. Subscribe to a private inbox, publish the request with that
// inbox as the reply subject, then collect quotes until they stop
// arriving and pick the cheapest.
const char *order = "{\"order_id\":\"ord_8w2k\",\"customer\":\"acme-co\","
"\"total_cents\":4200,\"ts\":\"2026-05-22T10:14:22Z\"}";
int quotes = 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, "shipping.quote",
(const char *) inbox, order);
while (s == NATS_OK)
{
natsMsg *quote = NULL;
// Stop once no further quote arrives within the gap deadline.
s = natsSubscription_NextMsg("e, sub, 300);
if (s != NATS_OK)
break;
printf("quote: %.*s\n",
natsMsg_GetDataLength(quote), natsMsg_GetData(quote));
quotes++;
natsMsg_Destroy(quote);
}
printf("gathered %d quotes\n", quotes);
CLI использует --replies 3: читать inbox до трёх ответов либо до прекращения их поступления — что случится раньше. При трёх работающих поставщиках вывод содержит три предложения, по одному от перевозчика. Клиент сравнивает цены и сохраняет минимальную.
Библиотека делает то же; объём ручного кода зависит от клиента. Обычный request() возвращает только первый ответ и сам по себе не возвращает список: клиент не знает, сколько сервисов ответят. Некоторые клиенты имеют готовые средства сбора: в nats.js это requestMany, в orbit.go — RequestMany (оба следуют ADR-47 «Request Many» с остановкой по числу, паузе или завершающему сигналу), в .NET — RequestManyAsync. Если помощника нет, напишите цикл: подпишитесь на новый inbox, опубликуйте запрос с этим inbox как темой ответа, читайте подписку и добавляйте ответы в список до нужного числа или срока, затем отпишитесь.
Сбор по сроку
Подсчёт предполагает известное число поставщиков. Часто оно неизвестно: перевозчики подключаются и отключаются, один может быть недоступен. Ручной сбор без срока чтения навсегда застрянет в ожидании третьего ответа, если ответят только двое.
Надёжнее собирать по сроку: принимать все ответы в пределах заданного времени и затем использовать полученный набор.
В CLI --replies 0 включает сбор по сроку: --timeout становится общим окном сбора. Команда читает ответы всё окно и возвращает результат после его закрытия. Поэтому --replies 0 --timeout 2s собирает всё пришедшее за две секунды. Время фиксировано и предсказуемо. --reply-timeout здесь не действует: он ограничивает паузу между ответами только при сборе по числу.
nats request shipping.quote \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}' \
--replies 0 --timeout 2s
При трёх работающих поставщиках ответы приходят за миллисекунды, но команда всё равно ждёт полные две секунды. При одном недоступном вы получите два ответа после того же окна. Если подписанных поставщиков нет вообще, команда сразу возвращает no responders; однако подписанный, но медленный сервис требует полного ожидания --timeout. В любом случае ожидание ограничено.
Срок меняет правило: ждать не всех, а только успевших ответить. При непостоянном составе сервисов это единственное безопасное предположение.
Третий способ завершить сбор — завершающий сигнал (sentinel). С --wait-for-empty команда собирает ответы до сообщения с пустой полезной нагрузкой, которым сервис обозначает конец набора. Здесь учитывается поток ответов, а не одно общее окно. Если сигнал не придёт, --reply-timeout ограничит паузу между ответами, и ожидание всё равно закончится.
Гарантии доставки
Как и всё остальное, scatter-gather использует доставку не более одного раза: потерянный ответ отсутствует в наборе, повторной доставки нет, порядок прихода не несёт смысла. Рассматривайте результат как набор пришедших ответов, а не рейтинг. Для тарифов это подходит: повторить вопрос недорого. Если каждый ответ должен переживать сбой, нужен JetStream, а не базовый сбор.
Подводные камни
Получение только первого ответа. Обычный nats request останавливается после одного ответа: --replies по умолчанию равен 1. Среди трёх поставщиков вы получите первого ответившего, а остальные предложения будут отброшены без уведомления. Обычный библиотечный request() делает то же. Для сбора используйте CLI --replies 0, помощник клиента (nats.js requestMany, orbit.go RequestMany) или собственную подписку на inbox с циклом чтения.
- CLI
- C
#!/bin/bash
# The "first reply only" trap, and the fix.
#
# `nats request` defaults to --replies 1: it reads ONE reply and stops.
# With three providers up, you get whichever carrier answered first and
# the other two quotes are silently discarded. That is a single request,
# not a scatter-gather.
# WRONG for scatter-gather — takes only the first quote that lands.
nats request shipping.quote \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
# RIGHT — gather every quote, then pick the cheapest. --replies 0 collects
# every reply that arrives during the full --timeout window, then returns —
# a fixed, predictable budget. If a carrier is down, its quote is simply
# absent from the set; --reply-timeout has no effect in this mode.
nats request shipping.quote \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}' \
--replies 0 --timeout 2s
// The "first reply only" trap: a plain request reads ONE reply and
// stops. With three providers up, you get whichever carrier answered
// first and the other two quotes are silently discarded.
const char *order = "{\"order_id\":\"ord_8w2k\",\"customer\":\"acme-co\","
"\"total_cents\":4200,\"ts\":\"2026-05-22T10:14:22Z\"}";
natsMsg *first = NULL;
if (s == NATS_OK)
s = natsConnection_RequestString(&first, conn, "shipping.quote",
order, 2000);
if (s == NATS_OK)
{
printf("first quote only: %.*s\n",
natsMsg_GetDataLength(first), natsMsg_GetData(first));
natsMsg_Destroy(first);
}
// The fix: gather every quote yourself. Subscribe to a private inbox,
// publish the request with that inbox as the reply subject, and read
// replies until they stop arriving.
int quotes = 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, "shipping.quote",
(const char *) inbox, order);
while (s == NATS_OK)
{
natsMsg *quote = NULL;
s = natsSubscription_NextMsg("e, sub, 300);
if (s != NATS_OK)
break;
printf("quote: %.*s\n",
natsMsg_GetDataLength(quote), natsMsg_GetData(quote));
quotes++;
natsMsg_Destroy(quote);
}
printf("gathered %d quotes\n", quotes);
Ожидание ответов без срока. Ручной сбор без ограничения чтения зависает при недоступном поставщике. Задайте срок (--replies 0 --timeout 2s), чтобы отсутствующий перевозчик просто не вошёл в набор предложений.
Восприятие результата как рейтинга. Порядок прихода не означает приоритет, а неполный набор не обязательно является ошибкой. Оценивайте содержание каждого ответа: здесь минимальный quote_cents.
Что уже сделано
Теперь Acme ORDERS использует четыре схемы взаимодействия через один локальный nats-server:
notificationsиanalyticsполучают собственные копии всех сообщенийorders.created(публикация и подписка).- Региональная аналитика охватывает
orders.us.createdиorders.eu.createdчерезorders.*.created, а аудит читает иерархию черезorders.>. - Сервис
inventoryотвечает на отдельные запросыorders.inventory.check(запрос-ответ). - Группа
packersраспределяет работу наorders.created: один упаковщик на заказ. - Три поставщика отвечают на один запрос
shipping.quote, а клиент собирает ответы в пределах срока и выбирает самый дешёвый.
Это основа Core NATS: темы, интерес, inbox ответов и группы очередей. Всё работает без хранения, с доставкой не более одного раза; после доставки ничего не запоминается.
Что дальше
Следующая страница добавляет к теме и полезной нагрузке сообщения третью часть: заголовки с метаданными «ключ — значение». Вы добавите идентификатор запроса и трассировки в поток заказов и прочитаете статус, которым сервер сообщает об отсутствии отвечающих сервисов. Перейдите к Заголовкам сообщений.
См. также
- Основные понятия → Запрос-ответ — пятиминутный обзор базового шаблона.
- Изучение → Сервисы — переход от нескольких отвечающих процессов к управляемому сервису с агрегацией результатов.
- Справочник — сигнатуры средств сбора для клиентских библиотек.