Чтение потока
ORDERS хранит опубликованные заказы. Пока вы видели лишь их количество через nats stream info, но не содержимое.
Прочитаем их сервисом billing Acme. Он обрабатывает каждый заказ: выставляет платёж при создании, списывает при отправке, возвращает при отмене. После первого запуска или простоя ему нужно пройти весь журнал без пропусков. Для этого создадим долговременного потребителя с номера 1. Сначала разберём три составляющие пути сообщения.
Вы могли повторять команды, поэтому сообщений может быть три или тридцать. Шаги читают всё имеющееся и не зависят от количества.
Издатель, поток и потребитель
Сообщение проходит три составляющие:
- Издатель публикует в тему, читает
PubAck, повторяет при ошибке. - Поток хранит по порядку, назначая номер в потоке — позицию сообщения.
- Потребитель — серверный курсор потока. Клиент подключается к нему для получения сообщений. Потребитель отслеживает продвижение и выдаёт следующее. Его номер доставки увеличивается при каждой выдаче, включая повторную, поэтому считает доставки, а не уникальные сообщения.
Один поток обслуживает много потребителей с независимыми позициями и скоростью. Здесь создадим одного, далее добавим других.
Потоки сохраняют сообщения
В Core NATS сообщение живёт лишь до доставки текущим подписчикам. Почему этого мало заказам, разобрано в Зачем нужен поток.
Поток сохраняет сообщения как долговременные записи с неизменными номерами. Чтение не перемещает и не удаляет запись: сообщение 1 остаётся следующим читателям. Новый потребитель через месяц может начать с того же номера 1.
Потребитель — серверный объект
Для чтения создаётся потребитель. Он расположен на сервере рядом с потоком; приложение является клиентом. Данные и позиция остаются на сервере, поэтому клиент отключается и возвращается без потери места и собственного учёта номеров.
Создайте billing:
- CLI
- JavaScript/TypeScript
- Go
- Python
- Java
- Rust
- C#/.NET
- C
#!/bin/bash
# Create a named, durable consumer on the ORDERS stream.
# A durable consumer has a name you choose. The server keeps its position on
# disk under that name, so a reader resumes where it left off after a
# disconnect or a server restart instead of starting over.
# --deliver all start at the first message in the stream (sequence 1)
# --pull the reader asks for messages when it's ready
# --ack explicit acknowledge each message; the position advances only once
# a message is acked (the default for a pull consumer)
nats consumer add ORDERS billing \
--deliver all \
--pull \
--ack explicit \
--defaults
// Create a durable consumer on the ORDERS stream. A durable keeps its position
// under a fixed name, so a reader can come back later and pick up where it left
// off. With explicit acks the server only advances that position once a reader
// acks each message. add() is idempotent: calling it again with the same config
// is a no-op.
const jsm = await jetstreamManager(nc);
await jsm.consumers.add("ORDERS", {
durable_name: "billing",
ack_policy: AckPolicy.Explicit,
deliver_policy: DeliverPolicy.All,
});
console.log("Created durable consumer: billing");
// Create a durable consumer on the ORDERS stream. The durable name lets a
// reader bind to the same consumer later and pick up where it left off.
cons, err := js.CreateOrUpdateConsumer(ctx, "ORDERS", jetstream.ConsumerConfig{
Durable: "billing",
DeliverPolicy: jetstream.DeliverAllPolicy,
AckPolicy: jetstream.AckExplicitPolicy,
})
if err != nil {
panic(err)
}
// Confirm the consumer is ready.
fmt.Printf("Created consumer: %s\n", cons.CachedInfo().Name)
# Create a durable consumer that reads the whole stream from the start.
# add_consumer is idempotent: calling it again with the same config is a no-op.
await js.add_consumer(
"ORDERS",
ConsumerConfig(
durable_name="billing",
ack_policy=AckPolicy.EXPLICIT,
deliver_policy=DeliverPolicy.ALL,
),
)
print("Created durable consumer billing on stream ORDERS")
// Create a durable consumer that delivers every stored message.
// AckPolicy.Explicit means each message must be acknowledged.
ConsumerContext cc = sc.createOrUpdateConsumer(
ConsumerConfiguration.builder()
.durable("billing")
.deliverPolicy(DeliverPolicy.All)
.ackPolicy(AckPolicy.Explicit)
.build());
System.out.println("Created durable consumer: " + cc.getConsumerName());
// Create a durable pull consumer that starts at the first stored message
// and acknowledges each message explicitly, so the server tracks progress.
let stream = js.get_stream("ORDERS").await?;
let consumer = stream
.create_consumer(pull::Config {
durable_name: Some("billing".to_string()),
deliver_policy: DeliverPolicy::All,
ack_policy: AckPolicy::Explicit,
..Default::default()
})
.await?;
println!("Created durable consumer: {}", consumer.cached_info().name);
// Create a durable consumer that delivers every stored message from the start
var consumer = await js.CreateOrUpdateConsumerAsync("ORDERS", new ConsumerConfig("billing")
{
AckPolicy = ConsumerConfigAckPolicy.Explicit,
DeliverPolicy = ConsumerConfigDeliverPolicy.All,
});
output.WriteLine($"Created durable consumer {consumer.Info.Config.Name} on stream ORDERS");
// Create a durable consumer on the ORDERS stream. The durable name
// lets a reader bind to the same consumer later and pick up where it
// left off.
jsConsumerInfo *ci = NULL;
jsConsumerConfig cc;
jsConsumerConfig_Init(&cc);
cc.Durable = "billing";
cc.DeliverPolicy = js_DeliverAll;
cc.AckPolicy = js_AckExplicit;
s = js_AddConsumer(&ci, js, "ORDERS", &cc, NULL, &jerr);
if (s == NATS_OK)
{
// Confirm the consumer is ready.
printf("Created consumer: %s\n", ci->Name);
jsConsumerInfo_Destroy(ci);
}
Три настройки определяют чтение:
- Deliver all — начать с первого сообщения, номера 1, и прочитать журнал.
- Pull — клиент запрашивает сообщения по готовности. Это стандарт для новых потребителей; существует и прежняя push-модель, но здесь используется pull.
- Ack explicit — подтверждать каждое обработанное сообщение. Позиция подтверждения продвигается по ack. Это стандарт для pull. Здесь успешный путь; далее рассмотрен цикл повторной доставки.
Посмотрите потребителя до чтения:
nats consumer info ORDERS billing
State:
Last Delivered Message: Consumer sequence: 0 Stream sequence: 0
Acknowledgment Floor: Consumer sequence: 0 Stream sequence: 0
Outstanding Acks: 0 out of maximum 1,000
Redelivered Messages: 0
Unprocessed Messages: 3
Waiting Pulls: 0 of maximum 512
Unprocessed Messages — число ещё не доставленных записей, сейчас весь поток. Оно соответствует вашим публикациям. Поля подтверждений остаются нулевыми до начала доставки и обработки.
Прочитайте сохранённые сообщения
Привязка к существующему потребителю использует его позицию, доставляет оставшееся и подтверждает по мере чтения:
- CLI
- JavaScript/TypeScript
- Go
- Python
- Java
- Rust
- C#/.NET
- C
#!/bin/bash
# Read every message the stream currently holds, in order, then stop.
# Binding 'nats sub' to the durable consumer reuses its on-disk position.
# --stream ORDERS --durable billing bind to the durable consumer
# --terminate-at-end stop once all stored messages are read
# --ack acknowledge each message it delivers
#
# This makes no assumption about how many messages are stored: it reads
# whatever is there and stops when 'pending' reaches 0.
nats sub --stream ORDERS --durable billing --terminate-at-end --ack
// Bind to the existing durable and read every stored message in order. Ask the
// consumer how many are waiting (num_pending) instead of guessing a count, then
// fetch exactly that many. Ack each message after handling it so the server
// advances the consumer past it and won't redeliver it.
const js = jetstream(nc);
const c = await js.consumers.get("ORDERS", "billing");
const info = await c.info();
const n = info.num_pending;
if (n === 0) {
console.log("nothing to read");
} else {
const msgs = await c.fetch({ max_messages: Number(n) });
for await (const m of msgs) {
console.log(
`stream seq ${m.info.streamSequence}, delivery seq ${m.info.deliverySequence}: ${m.string()}`,
);
await m.ack();
}
}
// Bind to the durable consumer created earlier.
cons, err := js.Consumer(ctx, "ORDERS", "billing")
if err != nil {
panic(err)
}
// Ask the consumer how many messages are still waiting, then read exactly
// that many. This drains everything stored without assuming a count.
info, err := cons.Info(ctx)
if err != nil {
panic(err)
}
pending := info.NumPending
if pending == 0 {
fmt.Println("nothing to read")
return
}
msgs, err := cons.Fetch(int(pending))
if err != nil {
panic(err)
}
for msg := range msgs.Messages() {
// Metadata carries the position of this message in the stream and in
// the consumer's own delivery sequence.
meta, err := msg.Metadata()
if err != nil {
panic(err)
}
fmt.Printf("stream seq=%d consumer seq=%d payload=%s\n",
meta.Sequence.Stream, meta.Sequence.Consumer, string(msg.Data()))
// Acknowledge so the server advances the consumer past this message.
if err := msg.Ack(); err != nil {
panic(err)
}
}
if msgs.Error() != nil {
panic(msgs.Error())
}
# Bind to the durable consumer created earlier and pull every stored message.
psub = await js.pull_subscribe_bind("billing", stream="ORDERS")
# Fetch in batches until a fetch times out, which means the stream is drained.
# The consumer uses explicit ack, so acknowledge each message after handling it.
while True:
try:
msgs = await psub.fetch(batch=100, timeout=1)
except nats.errors.TimeoutError:
break
for msg in msgs:
print(
f"stream seq {msg.metadata.sequence.stream}, "
f"consumer seq {msg.metadata.sequence.consumer}: "
f"{msg.data.decode()}"
)
await msg.ack()
// Ask the consumer how many messages are still waiting, then fetch
// exactly that many so the loop ends without guessing a count.
long pending = cc.getConsumerInfo().getNumPending();
if (pending == 0) {
System.out.println("Nothing to read.");
return;
}
try (FetchConsumer fc = cc.fetch(
FetchConsumeOptions.builder().maxMessages((int) pending).build())) {
Message m;
while ((m = fc.nextMessage()) != null) {
System.out.printf("stream_seq=%d consumer_seq=%d data=%s%n",
m.metaData().streamSequence(),
m.metaData().consumerSequence(),
new String(m.getData(), StandardCharsets.UTF_8));
// Acknowledge each message so the server advances the consumer.
m.ack();
}
}
// Bind to the existing durable consumer.
let stream = js.get_stream("ORDERS").await?;
let mut consumer: PullConsumer = stream.get_consumer("billing").await?;
// Ask the consumer how many messages are still waiting, then fetch exactly
// that many. This reads everything in order without assuming a count.
let pending = consumer.info().await?.num_pending;
if pending == 0 {
println!("nothing to read");
return Ok(());
}
let mut messages = consumer
.fetch()
.max_messages(usize::try_from(pending).unwrap_or(usize::MAX))
.messages()
.await?;
while let Some(msg) = messages.next().await {
let msg = msg?;
let info = msg.info()?;
println!(
"stream {} consumer {}: {}",
info.stream_sequence,
info.consumer_sequence,
std::str::from_utf8(&msg.payload)?
);
// Acknowledge so the server records this message as read.
msg.ack().await?;
}
// Bind to the existing durable consumer
var consumer = await js.GetConsumerAsync("ORDERS", "billing");
// Read exactly what the stream is holding, no count assumed up front
var pending = (long)consumer.Info.NumPending;
if (pending == 0)
{
output.WriteLine("nothing to read");
}
else
{
await foreach (var msg in consumer.FetchAsync<Order>(opts: new NatsJSFetchOpts { MaxMsgs = (int)pending }))
{
output.WriteLine($"stream {msg.Metadata?.Sequence.Stream} consumer {msg.Metadata?.Sequence.Consumer}: {msg.Data}");
read++;
// Acknowledge each message so the consumer advances past it
await msg.AckAsync();
}
}
// Ask the consumer how many messages are still waiting, then read
// exactly that many. This drains everything stored without assuming
// a count.
jsConsumerInfo *ci = NULL;
uint64_t pending = 0;
s = js_GetConsumerInfo(&ci, js, "ORDERS", "billing", NULL, &jerr);
if (s == NATS_OK)
{
pending = ci->NumPending;
jsConsumerInfo_Destroy(ci);
}
if ((s == NATS_OK) && (pending == 0))
printf("nothing to read\n");
if ((s == NATS_OK) && (pending > 0))
{
// Bind to the durable consumer created earlier and fetch the
// pending messages.
jsSubOptions so;
natsMsgList list = {NULL, 0};
jsSubOptions_Init(&so);
so.Stream = "ORDERS";
so.Consumer = "billing";
s = js_PullSubscribe(&sub, js, NULL, NULL, NULL, &so, &jerr);
if (s == NATS_OK)
s = natsSubscription_Fetch(&list, sub, (int) pending, 5000, &jerr);
if (s == NATS_OK)
{
for (int i = 0; i < list.Count; i++)
{
// Metadata carries the position of this message in the
// stream and in the consumer's own delivery sequence.
jsMsgMetaData *meta = NULL;
s = natsMsg_GetMetaData(&meta, list.Msgs[i]);
if (s != NATS_OK)
break;
printf("stream seq=%" PRIu64 " consumer seq=%" PRIu64 " payload=%s\n",
meta->Sequence.Stream, meta->Sequence.Consumer,
natsMsg_GetData(list.Msgs[i]));
jsMsgMetaData_Destroy(meta);
// Acknowledge so the server advances the consumer past
// this message.
natsMsg_Ack(list.Msgs[i], NULL);
}
natsMsgList_Destroy(&list);
}
}
Сообщения идут от старых к новым с номерами потока:
[#1] Received JetStream message: stream: ORDERS seq: 1 / pending: 2 / subject: orders.created / time: 2026-05-22 10:14:22
{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}
[#2] Received JetStream message: stream: ORDERS seq: 2 / pending: 1 / subject: orders.created / time: 2026-05-22 10:14:25
{"order_id":"ord_2zr9","customer":"globex","total_cents":7800,"ts":"2026-05-22T10:14:25Z"}
[#3] Received JetStream message: stream: ORDERS seq: 3 / pending: 0 / subject: orders.shipped / time: 2026-05-22 10:14:31
{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:31Z"}
pending уменьшается на единицу при каждой доставке; чтение прекращается при 0 независимо от размера потока. seq: 1, 2, 3 — те же номера из nats stream info. Это последовательное чтение журнала добавления.
Номер сообщения и номер доставки
Повторно запросите догнавшего потребителя:
nats consumer info ORDERS billing
State:
Last Delivered Message: Consumer sequence: 3 Stream sequence: 3
Acknowledgment Floor: Consumer sequence: 3 Stream sequence: 3
Unprocessed Messages: 0
Last Delivered Message содержит рядом два номера:
- Номер в потоке — неизменная позиция, назначенная при публикации; тот же номер в
PubAckиnats stream info. - Номер доставки потребителя — его собственный счётчик выдач, включая повторы, а не уникальных сообщений.
Оба равны 3, поскольку billing читал с начала без пропусков. При старте с середины, фильтрации или повторной доставке они расходятся. Номер потока закреплён за сообщением, счётчик потребителя — за доставкой.
В обработчике обычно не нужен отдельный nats consumer info: метаданные каждого сообщения уже содержат оба номера, остаток и число доставок. Они приходят бесплатно с сообщением; отдельный запрос годится для разовой проверки, но дорог на каждом сообщении. Пример выше читает номера прямо из доставки.
Потребитель помнит остановку
Позиция сохранена на диске. Опубликуйте ещё заказ:
nats pub --jetstream orders.created \
'{"order_id":"ord_5xk1","customer":"initech","total_cents":1500,"ts":"2026-05-22T11:02:00Z"}'
Повторите чтение той же командой: придёт только новое сообщение.
[#1] Received JetStream message: stream: ORDERS seq: 4 / pending: 0 / subject: orders.created / time: 2026-05-22 11:02:00
{"order_id":"ord_5xk1","customer":"initech","total_cents":1500,"ts":"2026-05-22T11:02:00Z"}
Отключение или перезапуск сервера не изменит позицию, привязанную к имени billing. Безымянный читатель такой долговременной позиции не имеет.
Однократное чтение без именованного потребителя
Долговременный потребитель нужен возвращающемуся читателю. Для разового просмотра nats sub --all переключается с живой Core-подписки на чтение потока. CLI создаёт временного потребителя, читает накопленное и удаляет его при выходе:
- CLI
#!/bin/bash
# Replay every message stored in the ORDERS stream, from sequence 1.
# 'nats sub' against a stream-bound subject uses an ephemeral consumer
# with no ack by default.
# --all start at the beginning of the stream
# --terminate-at-end stop once all stored messages have been read
nats sub "orders.>" --all --terminate-at-end
К временному потребителю нельзя надёжно вернуться: после бездействия он удаляется, а новое подключение начинает сначала. Для возобновляемой работы используйте долговременный вариант. Специальная форма однократного чтения в библиотеках рассмотрена в Упорядоченных потребителях.
Поток не изменился
nats stream info ORDERS показывает прежнее количество и номера плюс новый заказ. Чтение не забирает элементы из очереди: данные остаются другим читателям.
Типичные ошибки
При первом чтении реальных данных учтите несколько особенностей.
Повторный запуск догнавшего читателя ждёт. Команда выходит после чтения накопленного, но при отсутствии новых записей ждёт первого сообщения. Для разового чтения запускайте при наличии данных; для наблюдения оставляйте работать.
Чтение огромной истории с начала. Deliver all проходит весь журнал. Для миллионов заказов это время и трафик. Если история не нужна, выбирайте старт: последнее (--deliver last), час назад (--deliver 1h) или номер (--deliver 1000). Все варианты — в Создании потребителя.
Политика доставки задаёт начало, а политика воспроизведения — скорость. Стандартная instant отдаёт максимально быстро. original сохраняет промежутки исходных временных меток, воспроизводя реальную скорость. Здесь используется instant; обе описаны в справочнике.
Повторное имя с другой конфигурацией. Имя определяет долговременного потребителя. Повторное создание billing с другими настройками возвращает consumer already exists, не меняя работающего читателя. Используйте nats consumer edit или новое имя.
Что уже готово
Чтение не изменило ORDERS. Теперь есть:
- Поток
ORDERSсorders.>и опубликованными сообщениями. - Долговременный
billingс серверной позицией. - Различие номера сообщения в потоке и счётчика доставок потребителя.
Что дальше
Добавим второго потребителя с фильтром: несколько независимых представлений одного потока, каждое со своей позицией.
См. также
- Справочник → Конфигурация потребителя — политики доставки и упорядоченные потребители.
- Фильтрация — читатель только нужных тем.