Перейти к основному содержимому

Внутреннее устройство

Вы создали полноценный бакет INVENTORY: ключи и значения, наблюдатель, безопасное уменьшение через сравнение с заменой, автоматически истекающий ключ. Всё это использовало KV API без упоминания потока. Здесь раскрывается внутренний механизм: бакет всё время был потоком JetStream. Это помогает понять устройство KV.

Сначала проверим, что бакет — поток, и проследим один ключ до хранящего его сообщения. Затем рассмотрим операцию, чьё поведение зависит от запроса: удаление delete и очистку purge.

Бакет — это поток​

Во введении это утверждалось; теперь можно проверить. Бакет — поток JetStream с именем KV_<bucket> и темами $KV.<bucket>.>. Ключ — последний токен темы, значение — сообщение в ней. Для INVENTORY базовый поток — KV_INVENTORY, темы — $KV.INVENTORY.>, а ключ widget-blue — сообщение в $KV.INVENTORY.widget-blue.

Команды KV не показывают имя потока, но команды потоков сообщают его напрямую. Запросите у сервера поток за бакетом:

#!/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.

Выведенная конфигурация выражает все свойства 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, если нужно действительно удалить прошлые значения, например ради места или из-за чувствительных данных.

#!/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.

Обе операции заставляют 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, и лежащий под ним поток.

Что дальше​

Последняя страница подводит итоги главы, указывает, где искать полные подробности, и собирает подводные камни в список проверок перед эксплуатацией.

Переходите к странице Куда двигаться дальше.

См. также​