# Группы приоритетов

[Пул](/learn/jetstream/worker-pool.md) делил работу по запросам обработчиков shipping.

Иногда нужен один активный клиент до отказа или удалённый резерв, включаемый при отставании ближних. Равномерное разделение этого не обеспечивает.

**Группы приоритетов** задают такое поведение pull-потребителя. Они описаны в [ADR-42](https://github.com/nats-io/nats-architecture-and-design/blob/main/adr/ADR-42.md). Рассмотрим все три политики.

## Устройство группы

Это имя группы на потребителе и политика выдачи для неё.

При создании задаются:

* **`PriorityGroups`** — список имён. Сейчас используется только первое, хотя несколько принимаются.
* **`PriorityPolicy`** — `overflow`, `pinned_client` или `prioritized`.

Overflow и pinned\_client требуют ack, поэтому примеры задают `--ack explicit`: сервер учитывает ожидающие и неподтверждённые сообщения либо активность запросов клиента. Prioritized только сортирует запросы и не требует ack.

Каждый pull должен указать совпадающую группу, иначе `Bad Request - Priority Group missing`.

Итак, имя и политика задаются потребителю, запрос присоединяется по имени. Далее — три варианта.

## Политика overflow

Ближний `us-east` дешёв, удалённый `us-west` медленнее и дороже. Резерв должен работать лишь при отставании основного.

При **overflow** ближние запрашивают без порога, дальние — с `min_pending`. Сервер обслуживает их только при достаточном числе ожидающих; ниже порога запрос не получает ничего.

**Движение сообщений — Политика приоритета Overflow (анимация):** Политика Overflow: ближний обработчик us-east выполняет pull без порога и всегда разбирает ORDERS; дальний us-west задаёт min\_pending и получает работу только выше порога. Всплеск увеличивает очередь, us-west берёт излишек, а после снижения ниже порога снова ждёт.

Создайте потребителя ORDERS из файла:

```
nats consumer add ORDERS dispatch --config overflow-consumer.json
```

`overflow-consumer.json` задаёт политику и одну группу:

```
{

  "durable_name": "dispatch",

  "ack_policy": "explicit",

  "priority_policy": "overflow",

  "priority_groups": ["regions"]

}
```

Сокращённая форма `nats consumer add ORDERS dispatch --overflow-groups regions --ack explicit --pull` до natscli v0.4.x включает политику без группы и вызывает `10159`. До исправления используйте `--config`. Флаги остальных политик ниже работают обычно.

Проверьте:

```
nats consumer info ORDERS dispatch
```

В конфигурации два поля:

```
Configuration:



              Pull Mode: true

             Ack Policy: Explicit

        Priority Policy: Overflow

        Priority Groups: regions
```

Порог задаётся запросу, не потребителю. `min_pending` считает ожидающие сообщения, `min_ack_pending` — неподтверждённые. Для выдачи достаточно достижения любого.

У `nats consumer next` этих флагов нет; запрос через библиотеку:

#### CLI

```
#!/bin/bash



# Overflow policy: a standby region pulls only when the consumer has

# backed up past a min_pending threshold.



# Create an overflow pull consumer on ORDERS. --overflow-groups sets the

# policy to overflow and names the single group "regions". Overflow

# requires explicit acks.

nats consumer add ORDERS dispatch \

  --overflow-groups regions \

  --pull \

  --ack explicit \

  --defaults



# Inspect it — the configuration now shows Priority Policy: overflow and

# Priority Groups: [regions].

nats consumer info ORDERS dispatch



# The min_pending threshold lives on the pull request, which natscli's

# `nats consumer next` does not expose a flag for. A near-region worker

# pulls plainly and always gets messages:

nats consumer next ORDERS dispatch --count 5
```

#### C

```
// Bind to the existing overflow consumer. Every pull on a

// priority-group consumer must name its group.

jsSubOptions so;



jsSubOptions_Init(&so);

so.Stream = "ORDERS";

so.Consumer = "dispatch";



s = js_PullSubscribe(&sub, js, NULL, "dispatch", NULL, &so, &jerr);



// A near-region worker pulls with no threshold, so it always gets

// messages.

if (s == NATS_OK)

{

    jsFetchRequest  req;

    natsMsgList     list = {NULL, 0};



    jsFetchRequest_Init(&req);

    req.Batch = 5;

    req.Expires = 2 * 1000000000LL; // 2 seconds, in nanoseconds

    req.Group = "regions";



    s = natsSubscription_FetchRequest(&list, sub, &req);

    if (s == NATS_OK)

    {

        printf("near region got %d messages\n", list.Count);

        for (i = 0; i < list.Count; i++)

            natsMsg_Ack(list.Msgs[i], NULL);

        natsMsgList_Destroy(&list);

    }

    else if (s == NATS_TIMEOUT)

        s = NATS_OK; // nothing waiting right now

}



// A far-region worker adds MinPending: the server answers its pull

// only when the consumer has backed up past that many waiting

// messages. Below the threshold it gets nothing, the same as if the

// stream were empty.

if (s == NATS_OK)

{

    jsFetchRequest  req;

    natsMsgList     list = {NULL, 0};



    jsFetchRequest_Init(&req);

    req.Batch = 5;

    req.Expires = 2 * 1000000000LL;

    req.Group = "regions";

    req.MinPending = 100;



    s = natsSubscription_FetchRequest(&list, sub, &req);

    if (s == NATS_OK)

    {

        printf("far region got %d overflow messages\n", list.Count);

        for (i = 0; i < list.Count; i++)

            natsMsg_Ack(list.Msgs[i], NULL);

        natsMsgList_Destroy(&list);

    }

    else if (s == NATS_TIMEOUT)

    {

        // Backlog below 100: the far region stays idle.

        printf("far region got nothing\n");

        s = NATS_OK;

    }

}
```

Ближний обработчик разбирает очередь, дальний включается после порога и снова простаивает, когда основной догоняет.

## Политика pinned\_client

**Pinned\_client** держит одного активного клиента и резерв вместо распределения под нагрузкой.

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

Сервер **закрепляет** один ожидающий запрос. Остальные ждут; если закреплённый перестал запрашивать дольше тайм-аута, выбирается резервный.

**Движение сообщений — Политика закрепления клиента (анимация):** Политика Pinned\_client: сервер закрепляет одного обработчика и отправляет ему все сообщения, остальные ждут. Когда он замолкает дольше PinnedTTL, сервер закрепляет резервного и отмечает сообщения новым Nats-Pin-Id. Следующий pull старого обработчика с прежним id получает 423: тот сбрасывает id и возвращается в резерв.

Создайте:

```
nats consumer add ORDERS sequencer --pinned-groups ordered --pinned-ttl 90s --ack explicit --pull --defaults
```

`--pinned-groups ordered` задаёт политику и имя, `--pinned-ttl 90s` — допустимый перерыв между запросами.

Тайм-аут закрепления должен с запасом превышать `expires`, получение пакета и обработку. Стандарт — две минуты; `expires` меньше минуты оставляет время циклу.

Клиент получает и удерживает закрепление так:

#### CLI

```
#!/bin/bash



# Pinned_client policy: one active client gets all the work, with a

# standby ready to take over.



# Create a pinned consumer. --pinned-groups sets the policy to

# pinned_client and names the group "ordered". --pinned-ttl is how long

# the server waits for a pull from the pinned client before pinning a

# standby instead. Pinned consumers require explicit acks.

nats consumer add ORDERS sequencer \

  --pinned-groups ordered \

  --pinned-ttl 90s \

  --pull \

  --ack explicit \

  --defaults



# Inspect it — the configuration shows Priority Policy: pinned_client,

# Priority Groups: [ordered], and Pinned TTL: 1m30s. The State block

# shows which client (if any) currently holds the pin.

nats consumer info ORDERS sequencer



# The Nats-Pin-Id handshake happens on the pull request, which natscli's

# `nats consumer next` does not drive. Pull a message to see delivery:

nats consumer next ORDERS sequencer --count 1



# Force the server to pick a new pinned client:

nats consumer unpin ORDERS sequencer ordered
```

#### C

```
// Pull from the pinned consumer with the async helper. The library

// runs the pin handshake for you: it stores the Nats-Pin-Id header

// from the first delivered message, sends it back on every later pull,

// and clears it to rejoin the standby pool if the server unpins this

// client.

jsOptions       jsOpts;

jsSubOptions    so;



jsOptions_Init(&jsOpts);

jsOpts.PullSubscribeAsync.Group = "ordered"; // the consumer's priority group

jsOpts.PullSubscribeAsync.Timeout = 30000;   // stop after 30 seconds



jsSubOptions_Init(&so);

so.Stream = "ORDERS";

so.Consumer = "sequencer";

so.ManualAck = true; // pinned_client requires explicit acks



s = js_PullSubscribeAsync(&sub, js, NULL, "sequencer",

                          onMsg, NULL, &jsOpts, &so, &jerr);



// If the server pins this client, every message flows here; if a

// standby client runs the same code, its pulls wait until the pin

// moves to it.

while ((s == NATS_OK) && natsSubscription_IsValid(sub))

    nats_Sleep(100);
```

Первое сообщение содержит `Nats-Pin-Id`. Клиент возвращает его в следующих запросах; сервер обслуживает совпадающий ID, удерживая остальных.

После истечения срока новый клиент получает закрепление. Старый ID вызывает `423`: очистите его и запросите без него, возвращаясь в резерв. Протокол и уведомления — в [API потребителей](/reference/jetstream/api/consumer/info.md).

Администратор может принудительно снять закрепление через `nats consumer unpin`:

```
nats consumer unpin ORDERS sequencer ordered -f
```

Команда принимает поток, потребителя и группу; `-f` пропускает подтверждение. Выводит снятого клиента:

```
Unpinned client <client-id> from Priority Group ORDERS > sequencer > ordered
```

Без изменений посмотрите `State` команды `nats consumer info ORDERS sequencer`:

```
State:



          Priority Groups: ordered: pinned <client-id> at 2026-06-02 12:14:22
```

Без активного — `No client`. Все закреплённые потребители находятся через `nats consumer find ORDERS --pinned`.

:::note Поддержка клиентов различается Сохранение `Nats-Pin-Id`, его возврат и обработка `423` реализованы в Go, Java, JavaScript/TypeScript и .NET. Rust и Python позволяют задать конфигурацию, но ещё не выполняют клиентский цикл закрепления. Проверьте документацию своей библиотеки. :::

## Политика prioritized

Иногда резерв должен включаться сразу при отсутствии запросов основного, без ожидания накопленного порога.

Например, `us-east` имеет приоритет при свободных ресурсах, затем `us-west`, затем `eu-west`.

**Prioritized** обслуживает `priority` от `0` до `9`, сначала меньшие числа, внутри одного — по кругу. `us-east` с 0 получает при наличии запроса, затем `us-west` с 1, затем `eu-west` с 2.

**Движение сообщений — Политика Prioritized (анимация):** Политика Prioritized: три региона выполняют pull с приоритетами 0, 1 и 2. Сервер без задержки обслуживает наименьший из активных запросов. us-east (0) получает всё, пока запрашивает; при его молчании работа переходит us-west (1), затем eu-west (2). После возвращения us-east работа сразу возвращается к 0.

Создайте:

```
nats consumer add ORDERS dispatch --prioritized-groups regions --pull --defaults
```

`--prioritized-groups regions` задаёт политику и группу. Индивидуальные счётчики не нужны, поэтому явные ack не обязательны.

Имя `dispatch` намеренно повторяет overflow: выберите один вариант региональной диспетчеризации. Политику можно сменить живому потребителю полным `--config`, отдельного флага у `nats consumer edit` нет.

Приоритет — поле запроса; CLI next его не задаёт, поэтому используйте библиотеку:

#### CLI

```
#!/bin/bash



# Prioritized policy: each pull carries a 0-9 priority and the server serves

# the lowest number first, so nearer workers get first refusal and farther

# ones pick up the instant the nearer ones go quiet.



# Create a prioritized pull consumer on ORDERS. --prioritized-groups sets the

# policy to prioritized and names the single group "regions". Prioritized

# sorts pulls by number and tracks no per-client counts, so unlike overflow

# and pinned_client it needs no explicit acks.

nats consumer add ORDERS dispatch \

  --prioritized-groups regions \

  --pull \

  --defaults



# Inspect it — the configuration shows Priority Policy: prioritized and

# Priority Groups: [regions].

nats consumer info ORDERS dispatch



# The priority rides on the pull request, which natscli's `nats consumer next`

# does not expose a flag for. A worker pulls plainly (priority 0) and is

# served ahead of any higher-numbered pull:

nats consumer next ORDERS dispatch --count 5
```

#### C

```
// Bind to the existing prioritized consumer. Every pull names the

// group and carries a priority from 0 to 9; the server serves the

// lowest number present first.

jsSubOptions so;



jsSubOptions_Init(&so);

so.Stream = "ORDERS";

so.Consumer = "dispatch";



s = js_PullSubscribe(&sub, js, NULL, "dispatch", NULL, &so, &jerr);



// us-east pulls at priority 0, so it's served ahead of any

// higher-numbered pull.

if (s == NATS_OK)

{

    jsFetchRequest  req;

    natsMsgList     list = {NULL, 0};



    jsFetchRequest_Init(&req);

    req.Batch = 5;

    req.Expires = 2 * 1000000000LL; // 2 seconds, in nanoseconds

    req.Group = "regions";

    req.Priority = 0;



    s = natsSubscription_FetchRequest(&list, sub, &req);

    if (s == NATS_OK)

    {

        printf("us-east got %d messages\n", list.Count);

        for (i = 0; i < list.Count; i++)

            natsMsg_Ack(list.Msgs[i], NULL);

        natsMsgList_Destroy(&list);

    }

    else if (s == NATS_TIMEOUT)

        s = NATS_OK; // nothing waiting right now

}



// us-west pulls the same way at priority 1: it's served the moment no

// priority-0 pull is waiting, with no threshold and no delay.

if (s == NATS_OK)

{

    jsFetchRequest  req;

    natsMsgList     list = {NULL, 0};



    jsFetchRequest_Init(&req);

    req.Batch = 5;

    req.Expires = 2 * 1000000000LL;

    req.Group = "regions";

    req.Priority = 1;



    s = natsSubscription_FetchRequest(&list, sub, &req);

    if (s == NATS_OK)

    {

        printf("us-west got %d messages\n", list.Count);

        for (i = 0; i < list.Count; i++)

            natsMsg_Ack(list.Msgs[i], NULL);

        natsMsgList_Destroy(&list);

    }

    else if (s == NATS_TIMEOUT)

        s = NATS_OK;

}
```

Overflow избегает частых переключений ценой ожидания порога. Prioritized переключает немедленно, но работа может чаще переходить между регионами.

Все поля, `423`, `PriorityGroupState` и уведомления описаны в [API потребителей](/reference/jetstream/api/consumer/info.md) и [ADR-42](https://github.com/nats-io/nats-architecture-and-design/blob/main/adr/ADR-42.md).

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

Несколько деталей легко упустить.

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

#### CLI

```
#!/bin/bash



# A consumer acts on exactly one priority group. The --overflow-groups

# and --pinned-groups flags accept a comma list, so it is easy to pass

# two by accident.



# NOT THIS: two group names. The server accepts the create without error,

# but it uses only the first group (regions) and silently ignores the

# rest. Multiple groups per consumer is reserved for a future release.

nats consumer add ORDERS dispatch \

  --overflow-groups regions,backup \

  --pull \

  --ack explicit \

  --defaults



# DO THIS: name a single group. To split work by region or tier, run

# separate consumers, each with its own group, on the same stream.

nats consumer add ORDERS dispatch \

  --overflow-groups regions \

  --pull \

  --ack explicit \

  --defaults
```

#### C

```
// A consumer acts on exactly one priority group, but PriorityGroups is

// a list, so it's easy to pass two by accident.

jsConsumerConfig    cc;

const char          *twoGroups[] = {"regions", "backup"};

const char          *oneGroup[]  = {"regions"};



// NOT THIS: two group names. The server accepts the create without

// error, but it uses only the first group (regions) and silently

// ignores the rest. Multiple groups per consumer is reserved for a

// future release.

jsConsumerConfig_Init(&cc);

cc.Durable = "dispatch";

cc.AckPolicy = js_AckExplicit;

cc.PriorityPolicy = "overflow";

cc.PriorityGroups = twoGroups;

cc.PriorityGroupsLen = 2;



s = js_AddConsumer(&ci, js, "ORDERS", &cc, NULL, &jerr);

if (s == NATS_OK)

{

    jsConsumerInfo_Destroy(ci);

    ci = NULL;

    // The policy and groups are fixed at creation, so delete the

    // consumer before recreating it correctly.

    s = js_DeleteConsumer(js, "ORDERS", "dispatch", NULL, &jerr);

}



// DO THIS: name a single group. To split work by region or tier, run

// separate consumers, each with its own group, on the same stream.

if (s == NATS_OK)

{

    cc.PriorityGroups = oneGroup;

    cc.PriorityGroupsLen = 1;

    s = js_AddConsumer(&ci, js, "ORDERS", &cc, NULL, &jerr);

}

if (s == NATS_OK)

    printf("dispatch uses group %s\n", ci->Config->PriorityGroups[0]);
```

**Закрепление не гарантирует исключительное владение.** Сервер может переключить клиента, пока старый ещё выполняет работу. Устаревший ID даст `423`; очистите его и вернитесь в резерв. От дублей защищают явный ack и идемпотентные действия, а не одно закрепление.

**Молчащий клиент удерживает закрепление до срока.** Пока он занят медленной работой, остальные ждут `--pinned-ttl`. Держите `expires` существенно ниже него для своевременного продления. Обслуживание запросов узлами — в [Кластеризации](/learn/clustering/.md).

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

Одна группа плюс политика: overflow включает резерв при нагрузке, pinned\_client даёт активного и резервного, prioritized немедленно обслуживает меньший номер приоритета.

## Что дальше

Далее остановим выдачу потребителю на заданное время с сохранением позиции.

## См. также

* [API потребителей](/reference/jetstream/api/consumer/info.md) — поля, состояние, `423`, уведомления.
* [ADR-42](https://github.com/nats-io/nats-architecture-and-design/blob/main/adr/ADR-42.md) — проектирование.
* [Пул обработчиков](/learn/jetstream/worker-pool.md) — обычное равномерное разделение.
