Внутреннее устройство
Вы создали полноценный бакет INVENTORY: ключи и значения, наблюдатель, безопасное уменьшение через сравнение с заменой, автоматически истекающий ключ. Всё это использовало KV API без упоминания потока. Здесь раскрывается внутренний механизм: бакет всё время был потоком JetStream. Это помогает понять устройство KV.
Сначала проверим, что бакет — поток, и проследим один ключ до хранящего его сообщения. Затем рассмотрим операцию, чьё поведение зависит от запроса: удаление delete и очистку purge.
Бакет — это поток
Во введении это утверждалось; теперь можно проверить. Бакет — поток JetStream с именем KV_<bucket> и темами $KV.<bucket>.>. Ключ — последний токен темы, значение — сообщение в ней. Для INVENTORY базовый поток — KV_INVENTORY, темы — $KV.INVENTORY.>, а ключ widget-blue — сообщение в $KV.INVENTORY.widget-blue.
Команды KV не показывают имя потока, но команды потоков сообщают его напрямую. Запросите у сервера поток за бакетом:
- CLI
- C
#!/bin/bash
# Inspect the bucket as the stream it really is.
#
# The INVENTORY bucket is a JetStream stream named KV_INVENTORY. The KV
# commands hide that name, but the stream commands see straight through to
# it. Ask the server for the stream that backs the bucket:
nats stream info KV_INVENTORY
# The configuration half proves every framing claim from this chapter:
#
# Subjects: $KV.INVENTORY.> # one subject per key
# Discard Policy: New # at a limit, rejects the newest write
# Direct Get: true # get reads without a consumer
# Allows Rollups: true # purge replaces a key with one marker
# Allows Msg Delete: false # deny_delete: no raw stream deletes
# Maximum Per Subject: 10 # this is the history depth (raised on
# # the history page)
#
# The key widget-blue is the last token of its subject. Confirm it by
# asking the stream for the last message on that exact subject:
nats stream subjects KV_INVENTORY
# Expected output lists $KV.INVENTORY.widget-blue (and one subject per
# other key). The value 42 you put on page 1 is the body of the last
# message on $KV.INVENTORY.widget-blue.
// The INVENTORY bucket is a JetStream stream named KV_INVENTORY. The
// KV calls hide that name, but the stream API sees straight through
// to it. Ask for the stream, including its per-subject counts.
jsStreamInfo *si = NULL;
jsErrCode jerr = 0;
jsOptions o;
jsOptions_Init(&o);
o.Stream.Info.SubjectsFilter = "$KV.INVENTORY.>";
s = js_GetStreamInfo(&si, js, "KV_INVENTORY", &o, &jerr);
if (s == NATS_OK)
{
// The config is the bucket's settings written in stream terms.
printf("Subjects: %s\n", si->Config->Subjects[0]);
printf("Maximum Per Subject: %" PRIi64 "\n", // history depth
si->Config->MaxMsgsPerSubject);
printf("Discard Policy: %s\n", // limits reject
(si->Config->Discard == js_DiscardNew) ? "New" : "Old");
printf("Direct Get: %s\n", // get without a consumer
si->Config->AllowDirect ? "true" : "false");
printf("Allows Rollups: %s\n", // purge = one marker
si->Config->AllowRollup ? "true" : "false");
printf("Allows Msg Delete: %s\n", // deny_delete on
si->Config->DenyDelete ? "false" : "true");
// One subject per key: widget-blue is the message on
// $KV.INVENTORY.widget-blue.
if (si->State.Subjects != NULL)
{
int i;
for (i = 0; i < si->State.Subjects->Count; i++)
printf(" %s: %" PRIu64 " messages\n",
si->State.Subjects->List[i].Subject,
si->State.Subjects->List[i].Msgs);
}
jsStreamInfo_Destroy(si);
}
Выведенная конфигурация выражает все свойства KV из этой главы в терминах потока:
- Subjects:
$KV.INVENTORY.>. Одна ветвь тем с ключами под ней. - Maximum Per Subject:
10. Это и есть глубина истории, увеличенная до 10 для прошлых ревизий. История бакета — хранение потоком нескольких сообщений на тему. - Discard Policy:
New. При достижении лимита бакет отклоняет новую запись, а не молча удаляет старые для освобождения места. Поэтому лимиты отклоняют: существующие сообщения сохраняются. - Direct Get:
true. Get не открывает потребителя; подробнее ниже. - Allows Rollups:
true. Purge заменяет всю тему ключа одним сообщением; подробнее ниже. - Allows Msg Delete:
false. Это соответствуетdeny_delete: поток запрещает JetStream API удаления сообщений, чтобы прямые операции не удаляли записи в обход KV API.
Это та же модель хранения, что в главе JetStream. Анимация ниже намеренно взята оттуда: слой под бакетом — именно описанный там поток.
Все параметры потока из этого вывода описаны в разделе Справочник → Создание потока. Вручную вы их не задавали: клиент отобразил на них настройки бакета.
Get читает последнее сообщение без потребителя
Чтение значения не воспроизводит поток и не открывает потребителя. Используется direct get: сервер возвращает последнее сообщение темы прямо из хранилища. Запрос идёт в $JS.API.DIRECT.GET.<stream>.<subject>, для нашего ключа — $JS.API.DIRECT.GET.KV_INVENTORY.$KV.INVENTORY.widget-blue. Сервер отвечает последним сообщением: его данные — текущее значение, порядковый номер — ревизия, время сохранения — временная метка записи.
Поэтому nats kv get INVENTORY widget-blue работает быстро и без состояния. Нет позиции для отслеживания, подтверждения сообщения или потребителя для очистки: один get — один запрос и один ответ. Так бакет ведёт себя как хранилище ключей и значений, хотя построен из журнала только с добавлением: интерфейс скрывает поток и показывает пары ключ/значение. Каждый get напрямую возвращает последнее сообщение темы.
Этот путь включает Direct Get: true в конфигурации потока. Параметр задаётся автоматически при создании бакета. Полное API прямого чтения находится в разделе Справочник → Получение сообщения потока; здесь достаточно понимать, что читается последнее сообщение темы без потребителя.
Удаление и очистка
Удаление ключа — операция, где результат зависит от запроса: на нижнем уровне отсутствие значения может означать две разные вещи.
Delete оставляет неразрушающий маркер — сообщение с заголовком KV-Operation: DEL. Ключ читается как отсутствующий, но все прежние ревизии в пределах глубины истории остаются в потоке и доступны через history. Это обычный выбор, когда ключ должен отсутствовать, а стирать прошлое не требуется. В других системах такой маркер называют tombstone; далее используем слово «маркер».
Purge уничтожает прошлые значения. Он пишет маркер с KV-Operation: PURGE и Nats-Rollup: sub. Свёртка заставляет поток удалить все более ранние сообщения темы и оставить только маркер. История сокращается до одной записи, прежние значения исчезают с диска. Используйте purge, если нужно действительно удалить прошлые значения, например ради места или из-за чувствительных данных.
- CLI
- C
#!/bin/bash
# Delete and purge both make a key read empty, but they keep different
# amounts of history. The difference matters when the prior values are
# sensitive or when the bucket is filling up.
# Delete leaves a non-destructive marker. The key reads empty, but every
# prior revision is still in the backing stream and still readable through
# history.
nats kv del INVENTORY widget-blue
# A get now reports the key is deleted, yet history still shows the
# revisions that came before:
nats kv history INVENTORY widget-blue
#
# Expected output: the kept PUT revisions PLUS a final DELETE marker
# (columns abbreviated here):
#
# Key Revision Op Value
# widget-blue 2 PUT 41
# widget-blue 5 PUT 40
# widget-blue 9 DELETE
#
# The values are still on disk, up to the bucket's history depth (raised to
# 10 on the history-and-revisions page). Delete is reversible knowledge: a
# deleted key can be put again, and its past is intact.
# Purge is destructive. It drops every prior revision for the key and
# leaves a single rollup marker behind, so history collapses to one entry.
nats kv purge INVENTORY widget-red
nats kv history INVENTORY widget-red
#
# Expected output: a single PURGE marker, the prior value gone
# (columns abbreviated here):
#
# Key Revision Op Value
# widget-red 10 PURGE
#
# Reach for purge when you must actually remove the old values (size or
# privacy); reach for delete when "this key is gone for now" is enough.
// Delete and purge both make a key read empty, but they keep
// different amounts of history.
kvEntryList list;
const char *ops[] = { "UNKNOWN", "PUT", "DELETE", "PURGE" };
int i;
// Delete leaves a non-destructive marker. The key reads empty, but
// every prior revision the bucket keeps stays readable through
// history: the kept PUTs plus a final DELETE marker.
s = kvStore_Delete(kv, "widget-blue");
if (s == NATS_OK)
s = kvStore_History(&list, kv, "widget-blue", NULL);
if (s == NATS_OK)
{
printf("widget-blue after delete:\n");
for (i = 0; i < list.Count; i++)
{
kvEntry *e = list.Entries[i];
printf(" rev %" PRIu64 " %s %s\n",
kvEntry_Revision(e), ops[kvEntry_Operation(e)],
(kvEntry_Value(e) != NULL) ? kvEntry_ValueString(e) : "");
}
kvEntryList_Destroy(&list);
}
// Purge is destructive. It drops every earlier message on the key's
// subject and keeps only a rollup marker, so history collapses to a
// single PURGE entry; the prior values are gone from disk.
if (s == NATS_OK)
s = kvStore_Purge(kv, "widget-red", NULL);
if (s == NATS_OK)
s = kvStore_History(&list, kv, "widget-red", NULL);
if (s == NATS_OK)
{
printf("widget-red after purge:\n");
for (i = 0; i < list.Count; i++)
{
kvEntry *e = list.Entries[i];
printf(" rev %" PRIu64 " %s %s\n",
kvEntry_Revision(e), ops[kvEntry_Operation(e)],
(kvEntry_Value(e) != NULL) ? kvEntry_ValueString(e) : "");
}
kvEntryList_Destroy(&list);
}
Обе операции заставляют get сообщить об отсутствии ключа. Разница лишь в последующей истории: delete сохраняет прежние ревизии, purge стирает их.
Для полноты назовём поле бакета Replicas — число серверов с копией; оно тоже видно в конфигурации потока. Репликация, выборы лидера и размещение рассматриваются в главе Кластеризация, а не здесь.
Подводные камни
Когда базовый поток стал видимым, хочется управлять им напрямую. Отсюда большинство ошибок.
Delete не удаляет историю; это делает только purge. Легко понять удаление ключа как исчезновение прежних значений, но это неверно. Все прошлые ревизии остаются доступны через историю, поскольку delete лишь добавляет маркер. Если удалить widget-blue, чтобы убрать неверный остаток, и считать его невосстановимым, значение по-прежнему доступно одной командой nats kv history. Для уничтожения прежних значений нужен purge.
Пример выше это доказывает: после delete widget-blue история по-прежнему содержит прошлые ревизии; после purge widget-red остаётся только маркер. Выбирайте операцию по тому, что требуется сохранить: прежние ревизии или занимаемое ими место.
Не управляйте базовым потоком напрямую. Бакет — управляемый поток. Не меняйте вручную конфигурацию KV_INVENTORY и не публикуйте в $KV.INVENTORY.> через обычный nats pub. KV API устанавливает заголовки корректной работы: ожидаемую ревизию для сравнения с заменой, KV-Operation и Nats-Rollup для delete и purge. Прямая публикация пишет сообщение без них: наблюдатель не отличит его от настоящего put, а задуманная очистка не произойдёт. Поток создан с deny_delete, чтобы прямые операции не удаляли записи в обход KV API, но эта настройка не запрещает обычную публикацию. Поэтому используйте nats kv put, а не nats pub; nats kv del и nats kv purge, а не удаление сообщений потока.
Ключ должен соответствовать правилам токенов темы. Теперь понятно, почему: ключ становится последней частью $KV.INVENTORY.<key>. Допускаются только буквы, цифры и -, /, _, =, ., без точки в начале или конце и без двух точек подряд. Другие варианты дают недопустимую тему. Заказ ord:8w2k содержит двоеточие и не подходит для ключа: запись отклоняется, а не сохраняется с неверным именем. Это та же проверка со страницы Первый бакет; её причина — базовый поток.
Текущее состояние
Теперь у вас есть:
- Прежний бакет
INVENTORYсо страниц от Первого бакета до TTL и лимитов и возможность изучить его как потокKV_INVENTORY, которым он всегда был. - Соответствие операций KV механизмам потока: put — сообщение, get — прямое чтение последнего сообщения темы, history — сохранённые сообщения темы, ревизия — порядковый номер, watch — потребитель.
- Чёткое различие delete (маркер с сохранением истории) и purge (маркер свёртки с удалением истории), а также правило не управлять базовым потоком напрямую.
Абстракция больше не скрывает устройство: это поток, представленный через KV API. Теперь вы видите и интерфейс KV, и лежащий под ним поток.
Что дальше
Последняя страница подводит итоги главы, указывает, где искать полные подробности, и собирает подводные камни в список проверок перед эксплуатацией.
Переходите к странице Куда двигаться дальше.
См. также
- Справочник → Получение сообщения потока — полный путь прямого чтения.
- Углублённый курс JetStream — модель потоков и потребителей, на которой построен бакет.
- Кластеризация — реплики, размещение и выборы лидера базового потока.