Упорядоченные потребители
billing сохраняет позицию для перезапуска, shipping долговременен и разделяется пулом. Они рассчитаны на длительную работу.
Но финансам может понадобиться один проход ORDERS с начала для сверки итогов. Такой читатель не делит работу, не требует ack и не нужен после завершения.
Упорядоченный потребитель предназначен для быстрого последовательного чтения с автоматической очисткой.
Клиентский код
Запросите его у библиотеки и перебирайте сообщения. Имя, ack и ручное удаление не нужны. Библиотека выдаёт непрерывный поток в порядке журнала от выбранной позиции до конца.
- JavaScript/TypeScript
- Go
- Python
- Java
- Rust
- C#/.NET
- C
// Ask for an ordered consumer over the stream: consumers.get() with no consumer
// name returns one. There's no ack to send — the library runs the consumer for
// you and recreates it if it ever misses a message, so you read every order in
// stream order.
const js = jetstream(nc);
const c = await js.consumers.get("ORDERS");
// Read the whole log once, in order, stopping when caught up (pending 0).
const messages = await c.consume();
for await (const m of messages) {
console.log(`order ${m.string()}`);
if (m.info.pending === 0) {
break;
}
}
// Ask for an ordered consumer over the stream. There's no name to manage and
// no ack to send: the library runs the consumer for you and recreates it if
// it ever misses a message, so you read every order in stream order. An
// empty config starts from the first order.
cons, err := js.OrderedConsumer(ctx, "ORDERS", jetstream.OrderedConsumerConfig{})
if err != nil {
panic(err)
}
iter, err := cons.Messages()
if err != nil {
panic(err)
}
defer iter.Stop()
// Read the whole log once, in order, stopping when caught up (NumPending 0).
for {
msg, err := iter.Next()
if err != nil {
break
}
meta, err := msg.Metadata()
if err != nil {
panic(err)
}
fmt.Printf("order %s\n", string(msg.Data()))
if meta.NumPending == 0 {
break
}
}
# Ask for an ordered consumer with ordered_consumer=True. There's no ack to
# send: nats.py runs the consumer for you and recreates it if it ever misses
# a message, so you read every order in stream order. deliver_policy=ALL
# starts from the first order.
psub = await js.subscribe(
"orders.>",
stream="ORDERS",
ordered_consumer=True,
deliver_policy=DeliverPolicy.ALL,
)
# Read the whole log once, in order, stopping when caught up (num_pending 0).
while True:
msg = await psub.next_msg(timeout=5)
print(f"order {msg.data.decode()}")
if msg.metadata.num_pending == 0:
break
// Ask for an ordered consumer over the stream. There's no ack to
// send: the library runs the consumer for you and recreates it if it
// ever misses a message, so you read every order in stream order.
// DeliverPolicy.All starts from the first order.
OrderedConsumerContext occ = sc.createOrderedConsumer(
new OrderedConsumerConfiguration().deliverPolicy(DeliverPolicy.All));
// Read the whole log once, in order, stopping when caught up.
Message m;
while ((m = occ.next(Duration.ofSeconds(5))) != null) {
System.out.println("order " + new String(m.getData(), StandardCharsets.UTF_8));
if (m.metaData().pendingCount() == 0) {
break;
}
}
// Ask for an ordered consumer over the stream. There's no name to manage and
// no ack to send: the library runs the consumer for you and recreates it if
// it ever misses a message, so you read every order in stream order.
let stream = js.get_stream("ORDERS").await?;
let consumer = stream
.create_consumer(consumer::pull::OrderedConfig {
deliver_policy: consumer::DeliverPolicy::All,
..Default::default()
})
.await?;
// Read the whole log once, in order, stopping when caught up (pending 0).
let mut messages = consumer.messages().await?;
while let Some(msg) = messages.next().await {
let msg = msg?;
println!("order {}", std::str::from_utf8(&msg.payload)?);
if msg.info()?.pending == 0 {
break;
}
}
// Ask for an ordered consumer over the stream. There's no ack to send:
// the library runs the consumer for you and recreates it if it ever
// misses a message, so you read every order in stream order.
var consumer = await js.CreateOrderedConsumerAsync("ORDERS");
// Read the whole log once, in order, stopping when caught up.
await foreach (var msg in consumer.ConsumeAsync<Order>())
{
output.WriteLine($"order {msg.Data}");
read++;
if (msg.Metadata?.NumPending == 0)
{
break;
}
}
// Ask for an ordered consumer over the stream. There's no name to
// manage and no ack to send: the library runs the consumer for you and
// recreates it if it ever misses a message, so you read every order in
// stream order, starting from the first one.
jsSubOptions so;
jsSubOptions_Init(&so);
so.Stream = "ORDERS";
so.Ordered = true;
s = js_SubscribeSync(&sub, js, "orders.>", NULL, &so, &jerr);
// Read the whole log once, in order, stopping when caught up
// (NumPending 0).
while (s == NATS_OK)
{
natsMsg *msg = NULL;
jsMsgMetaData *meta = NULL;
uint64_t pending = 0;
s = natsSubscription_NextMsg(&msg, sub, 5000);
if (s != NATS_OK)
break;
s = natsMsg_GetMetaData(&meta, msg);
if (s == NATS_OK)
{
pending = meta->NumPending;
printf("order %.*s\n",
natsMsg_GetDataLength(msg), natsMsg_GetData(msg));
jsMsgMetaData_Destroy(meta);
}
natsMsg_Destroy(msg);
if ((s == NATS_OK) && (pending == 0))
break;
}
// An empty stream simply times out waiting for the first message.
if (s == NATS_TIMEOUT)
s = NATS_OK;
Это клиентская конструкция, поэтому отдельной формы CLI нет.
Работа библиотеки
Внутри создаётся обычный потребитель с коротким порогом бездействия, после которого сервер его удаляет. Библиотека отслеживает номера и передаёт последовательные сообщения приложению.
При пропуске или исчезновении сигналов активности — удалении, переподключении, перезапуске узла — старый потребитель заменяется новым с начала ожидаемого номера. Имена меняются (prefix_1, prefix_2), а приложение видит непрерывное чтение; восстановление прозрачно.
Это позволяет обойтись без ack: обычный no-ack-потребитель пропустил бы потерю, а упорядоченный замечает разрыв и пересоздаётся с недостающей позиции, пока сообщение остаётся в потоке.
Внутренняя конфигурация
На сервере это не отдельный тип, а обычный потребитель с настройками для однократного чтения:
- Без ack (
AckPolicy=none): последовательное чтение без учёта обработки и повторов. - Хранение в памяти: быстрее, долговременная позиция не нужна.
- Одна реплика состояния: дёшево для повторяемого прохода.
- Короткий порог бездействия — пять минут: автоматическое удаление.
- Выбранное начало: весь журнал, номер или время. После восстановления стартует с ожидаемого номера.
Те же поля доступны любому потребителю; здесь они настроены ради скорости и временного использования. См. Конфигурацию потребителя.
Ограничения
Компромиссы:
- Нет подтверждения отдельных сообщений: нельзя отметить один заказ обработанным, другой нет. Для надёжной работы нужен именованный потребитель с явным ack, как shipping.
- Нет разделения между процессами: каждый создаёт свой экземпляр.
- Нет параллельной доставки: один поток исполнения, последовательные сообщения.
Взамен — упорядоченный проход без пропусков, учёта ack и оставленных ресурсов.
Применение
Наблюдение Key-Value и чтение Object Store основаны на таких потребителях. Используйте для прохода потока без координации читателей и подтверждений.
Типичные ошибки
Использование для работы с обязательной обработкой. Без ack нельзя записать, что заказ 5 отправлен, а 6 нет. Используйте именованного потребителя с явными подтверждениями и повторной доставкой.
Ожидание общей позиции процессов. Они прочитают весь поток независимо. Для разделения нужен пул одного именованного потребителя.
Ожидание долговременной позиции. Память, одна реплика и короткое бездействие намеренно делают курсор временным. После падения приложение начинает заново.
Что дальше
Вернёмся к нескольким читателям shipping. Группы приоритетов направляют работу предпочтительному клиенту или включают резерв при отставании.
См. также
- ADR-17: Ordered Consumer — реализуемое библиотеками поведение.
- Конфигурация потребителя — внутренние поля.
- Key-Value, Object Store — применение.