# Масштабирование потребителя

На [предыдущей странице](/learn/jetstream/pull-consumers.md) один обработчик непрерывно запрашивал shipping, отправлял заказы и подтверждал. Для нескольких заказов в час хватало.

Теперь заказы поступают быстрее обработки и накапливаются в ORDERS.

Запустите несколько процессов для того же shipping: сервер разделит сохранённые заказы между ними. Поток и потребитель прежние.

## Один потребитель, много обработчиков

Каждый использует то же имя shipping и цикл pull:

#### CLI

```
#!/bin/bash

# A worker loop for the shipping consumer.

# Run this same loop in three separate terminals to form a pool of

# three workers. All three share the one "shipping" consumer, and the

# server splits the stored messages across them.



# Each pass: pull one message, "process" it, and acknowledge it.

# --count 1 pulls a single message at a time.

# --ack acknowledges the message after it is received.

while true; do

  nats consumer next ORDERS shipping --count 1 --ack

done



# Publish work from a fourth terminal and watch it spread across the

# three running loops:

#   nats pub orders.shipped '{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'

#

# To see in-flight redelivery: stop one worker (Ctrl-C) right after it

# pulls a message but before it acks. After AckWait (30s default), the

# server redelivers that message to one of the surviving workers.
```

#### JavaScript/TypeScript

```
// Bind to the durable "shipping" consumer created earlier.

const js = jetstream(nc);

const c = await js.consumers.get("ORDERS", "shipping");



// consume() yields the orders the server hands this worker. Run this same

// program in several processes: they all share the one "shipping" consumer, and

// the server splits the stored orders across them, one order to one worker.

const messages = await c.consume();

for await (const m of messages) {

  console.log(`shipping ${m.string()}`);

  m.ack();

}
```

#### Go

```
// Bind to the durable "shipping" consumer created earlier.

cons, err := js.Consumer(ctx, "ORDERS", "shipping")

if err != nil {

	panic(err)

}



// Consume runs the handler for every order the server hands this worker.

// Start this same program in several processes: they all share the one

// "shipping" consumer, and the server splits the stored orders across them,

// one order to one worker.

consCtx, err := cons.Consume(func(msg jetstream.Msg) {

	fmt.Printf("shipping %s\n", string(msg.Data()))

	msg.Ack()

})

if err != nil {

	panic(err)

}

defer consCtx.Stop()



// Keep this worker running until interrupted (Ctrl-C).

sig := make(chan os.Signal, 1)

signal.Notify(sig, os.Interrupt)

<-sig
```

#### Python

```
# Bind to the durable "shipping" consumer created earlier. Run this same

# program in several processes: they all share the one consumer, and the

# server splits the stored orders across them, one order to one worker.

psub = await js.pull_subscribe_bind("shipping", stream="ORDERS")



# Pull one order at a time and ack it. fetch times out when nothing is

# waiting; keep looping so the worker stays ready for the next order.

while True:

    try:

        msgs = await psub.fetch(batch=1, timeout=5)

    except nats.errors.TimeoutError:

        continue



    for msg in msgs:

        print(f"shipping {msg.data.decode()}")

        await msg.ack()
```

#### Java

```
// consume() runs the handler for every order the server hands this

// worker. Run this same program in several processes: they all share

// the one "shipping" consumer, and the server splits the stored

// orders across them, one order to one worker.

try (MessageConsumer mc = cc.consume(msg -> {

    System.out.println("shipping " + new String(msg.getData(), StandardCharsets.UTF_8));

    msg.ack();

})) {

    // Keep this worker running until the process is stopped.

    Thread.sleep(Long.MAX_VALUE);

}
```

#### Rust

```
// Bind to the durable "shipping" consumer created earlier.

let stream = js.get_stream("ORDERS").await?;

let consumer: PullConsumer = stream.get_consumer("shipping").await?;



// messages() is a never-ending stream of orders the server hands this

// worker. Run this same program in several processes: they all share the

// one "shipping" consumer, and the server splits the stored orders across

// them, one order to one worker.

let mut messages = consumer.messages().await?;

while let Some(msg) = messages.next().await {

    let msg = msg?;

    println!("shipping {}", std::str::from_utf8(&msg.payload)?);

    msg.ack().await?;

}
```

#### C#/.NET

```
// Bind to the durable "shipping" consumer created earlier.

var consumer = await js.GetConsumerAsync("ORDERS", "shipping");



// ConsumeAsync yields the orders the server hands this worker. Run this

// same program in several processes: they all share the one "shipping"

// consumer, and the server splits the stored orders across them, one

// order to one worker.

await foreach (var msg in consumer.ConsumeAsync<Order>())

{

    output.WriteLine($"shipping {msg.Data}");

    await msg.AckAsync();



    // A real worker loops forever; stop once the backlog is clear so the

    // example returns.

    if (++shipped == 3)

    {

        break;

    }

}
```

#### C

```
// The handler runs for every order the server hands this worker.

static void

onOrder(natsConnection *nc, natsSubscription *sub, natsMsg *msg, void *closure)

{

    printf("shipping %.*s\n", natsMsg_GetDataLength(msg), natsMsg_GetData(msg));

    natsMsg_Ack(msg, NULL);

    natsMsg_Destroy(msg);

}

    // Bind to the durable "shipping" consumer created earlier and deliver

    // messages to the handler. Start this same program in several processes:

    // they all share the one "shipping" consumer, and the server splits the

    // stored orders across them, one order to one worker.

    jsSubOptions so;



    jsSubOptions_Init(&so);

    so.Stream    = "ORDERS";

    so.Consumer  = "shipping";

    so.ManualAck = true;



    s = js_PullSubscribeAsync(&sub, js, NULL, NULL, onOrder, NULL, NULL, &so, &jerr);



    // Keep this worker running until interrupted (Ctrl-C).

    while ((s == NATS_OK) && !done)

        nats_Sleep(100);
```

Запустите в трёх терминалах, а из четвёртого добавьте `orders.shipped` к уже имеющимся:

```
nats pub --jetstream orders.shipped '{"order_id":"ord_9x3f","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T11:01:50Z"}'

nats pub --jetstream orders.shipped '{"order_id":"ord_7p4d","customer":"globex","total_cents":7800,"ts":"2026-05-22T11:01:55Z"}'

nats pub --jetstream orders.shipped '{"order_id":"ord_5xk1","customer":"initech","total_cents":1500,"ts":"2026-05-22T11:02:00Z"}'
```

Каждый `--jetstream` получает `PubAck`. Сервер обслуживает запросы по очереди поступления и выдаёт заказ одному обработчику. При одиночных запросах нагрузка делится примерно поровну:

**Движение сообщений — Несколько обработчиков одного потребителя (анимация):** Несколько обработчиков используют одного pull-потребителя. Поток ORDERS хранит очередь заказов, а потребитель shipping проходит её одной позицией чтения. Каждый заказ получает ровно один запрашивающий обработчик, по очереди; три обработчика получают равные доли. Подтверждённые заказы остаются в потоке: обработчики делят позицию чтения, а не сообщения.

Занятый обработчик без открытого запроса пропускает очередь. Распределение зависит от спроса: быстрый чаще запрашивает и больше выполняет.

Позиция потребителя едина; число подтверждённых продвигается одним счётчиком:

```
nats consumer info ORDERS shipping
```

```
State:



  Last Delivered Message: Consumer sequence: ... Stream sequence: ...

     Acknowledgment Floor: Consumer sequence: ... Stream sequence: ...

         Outstanding Acks: 0 out of maximum 1,000
```

Номера зависят от прошлых шагов. Пара Acknowledgment Floor растёт с ack, Last Delivered не отстаёт от неё. Позиция принадлежит потребителю независимо от числа процессов.

## Работа с прежним журналом

ORDERS по-прежнему использует Limits. Разделение работы — свойство потребителя, оно работает с любым потоком без изменения хранения.

Ack двигает позицию, но не удаляет заказ. Billing, analytics и будущие читатели сохраняют доступ. Обработчики делят *позицию*, не копии сообщений.

## Отличие от группы очереди

Шаблон похож на группу очереди, но распределяет другие данные.

Core-группа очереди делит **живые** сообщения без хранения: отключённый подписчик пропускает их.

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

Второй вариант переживает уход обработчика и перезапуск.

## Падение во время обработки

Если процесс падает после получения, но до ack, заказ остаётся ожидающим. После стандартных 30 секунд AckWait он выдаётся другому. Это цикл [подтверждений](/learn/jetstream/acknowledgment.md) на уровне пула.

**Движение сообщений — Сбой при обработке и повторная доставка (анимация):** Заказ доставлен обработчику, который падает до подтверждения. Он остаётся в обработке у shipping до истечения AckWait: сервер видит не сбой, а отсутствие ack. Затем тот же заказ доставляется работающему обработчику, который отправляет его и подтверждает. Заказ обработан ровно один раз, хотя первый обработчик отказал.

Для наблюдения добавьте задержку перед ack (`sleep 5` в оболочке или паузу обработчика) и завершите процесс в ней. После AckWait заказ появится у другого и будет подтверждён. Если первый успел выполнить отправку до падения, действие повторится: ниже рассмотрена идемпотентность по `order_id`.

## Ограничение параллельной работы

Больше обработчиков — больше одновременно выполняемых заказов, но есть предел.

`MaxAckPending`, стандартно 1000, ограничивает доставленные без ack сообщения **всего потребителя**. Пять процессов получают тысячу на всех, не каждому. При достижении выдача ждёт подтверждений.

Задайте при создании или обновлении:

```
nats consumer edit ORDERS shipping --max-pending 1000
```

Слишком низкий предел оставляет процессы без работы, слишком высокий создаёт большой объём одновременных повторов при массовом отказе.

## Типичные ошибки

На практике важны AckWait и MaxAckPending.

**Повтор достаётся другому обработчику.** Побочные действия могут выполниться дважды; обеспечьте идемпотентность по `order_id`. Повтор виден по счётчику доставки.

Пул распределяет по спросу, а не вашему выбору. Для предпочтительного обработчика или резервного используйте [группы приоритетов](/learn/jetstream/priority-groups.md).

**Малый MaxAckPending оставляет большой пул простаивать.** При лимите 3 у десяти процессов одновременно заняты только три. Держите предел хотя бы на уровне числа обработчиков с запасом.

**Заказ упавшего процесса ждёт AckWait.** Сервер не отличает сбой от медленной работы. Короткий срок создаёт преждевременные повторы, длинный задерживает восстановление. Настройте по времени обработки. AckWait, MaxDeliver и backoff описаны в [Конфигурации потребителя](/reference/jetstream/api/consumer/create.md).

## Что уже готово

Теперь есть:

* Прежний shipping.
* Несколько процессов, делящих сохранённые сообщения.
* Общий предел MaxAckPending.

Масштабирование — запуск дополнительных процессов без изменения потребителя. ORDERS как журнал сохраняет обработанные заказы.

## Что дальше

Billing, analytics и shipping долговременны и возобновляемы. [Упорядоченный потребитель](/learn/jetstream/ordered-consumer.md) предназначен для обратного: одного последовательного прохода, например подсчёта всех заказов, без сохраняемой позиции.

## См. также

* [Справочник → Конфигурация потребителя](/reference/jetstream/api/consumer/create.md) — MaxAckPending, AckWait, backoff и остальные поля.
* [Основные понятия → Группы очередей](/concepts/queue-groups.md) — распределение Core NATS.
