Группы приоритетов
Пул делил работу по запросам обработчиков shipping.
Иногда нужен один активный клиент до отказа или удалённый резерв, включаемый при отставании ближних. Равномерное разделение этого не обеспечивает.
Группы приоритетов задают такое поведение pull-потребителя. Они описаны в ADR-42. Рассмотрим все три политики.
Устройство группы
Это имя группы на потребителе и политика выдачи для неё.
При создании задаются:
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. Сервер обслуживает их только при достаточном числе ожидающих; ниже порога запрос не получает ничего.
Создайте потребителя 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
- C
#!/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
// 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 держит одного активного клиента и резерв вместо распределения под нагрузкой.
Это нужно конвейеру со строгим порядком: два запущены ради отказоустойчивости, но работать должен один.
Сервер закрепляет один ожидающий запрос. Остальные ждут; если закреплённый перестал запрашивать дольше тайм-аута, выбирается резервный.
Создайте:
nats consumer add ORDERS sequencer --pinned-groups ordered --pinned-ttl 90s --ack explicit --pull --defaults
--pinned-groups ordered задаёт политику и имя, --pinned-ttl 90s — допустимый перерыв между запросами.
Тайм-аут закрепления должен с запасом превышать expires, получение пакета и обработку. Стандарт — две минуты; expires меньше минуты оставляет время циклу.
Клиент получает и удерживает закрепление так:
- CLI
- C
#!/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
// 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 потребителей.
Администратор может принудительно снять закрепление через 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.
Создайте:
nats consumer add ORDERS dispatch --prioritized-groups regions --pull --defaults
--prioritized-groups regions задаёт политику и группу. Индивидуальные счётчики не нужны, поэтому явные ack не обязательны.
Имя dispatch намеренно повторяет overflow: выберите один вариант региональной диспетчеризации. Политику можно сменить живому потребителю полным --config, отдельного флага у nats consumer edit нет.
Приоритет — поле запроса; CLI next его не задаёт, поэтому используйте библиотеку:
- CLI
- C
#!/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
// 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 потребителей и ADR-42.
Типичные ошибки
Несколько деталей легко упустить.
Одна группа на потребителя. Флаги принимают список, но сервер использует только первое имя. Поддержка нескольких планируется. Пока разделяйте регионы или уровни отдельными потребителями со своими группами.
- CLI
- C
#!/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
// 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 существенно ниже него для своевременного продления. Обслуживание запросов узлами — в Кластеризации.
Что уже готово
Одна группа плюс политика: overflow включает резерв при нагрузке, pinned_client даёт активного и резервного, prioritized немедленно обслуживает меньший номер приоритета.
Что дальше
Далее остановим выдачу потребителю на заданное время с сохранением позиции.
См. также
- API потребителей — поля, состояние,
423, уведомления. - ADR-42 — проектирование.
- Пул обработчиков — обычное равномерное разделение.