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

TTL и лимиты

До сих пор ключи INVENTORY жили до перезаписи или удаления. Для остатка товара это разумно, но в бакете бывают и другие данные. Некоторые должны исчезать сами: цена краткой распродажи, временный токен сеанса или флаг блокировки артикула на 30 минут.

Здесь добавляются два вида ограничений. Первый — TTL отдельного ключа, удаляющий его по сроку. Второй — общие лимиты бакета: суммарный размер, размер значения, глубина истории. При истечении срока сервер оставляет маркер, чтобы складская панель узнала об исчезновении значения так же, как о любом другом изменении.

Бакет INVENTORY остаётся с предыдущих страниц: widget-blue уменьшен до 40, складская панель наблюдает. Добавим ключ с TTL.

TTL ключа удаляет отдельное значение по сроку​

TTL (time-to-live, время жизни) — срок хранения значения до удаления сервером. TTL ключа привязывает отсчёт к одному ключу. Тот живёт заданное время, затем исчезает сам: сервису не нужно помнить об удалении.

TTL ключа задаётся только при create. Вы передаёте срок вместе со значением, и отсчёт начинается с записи. Это намеренное ограничение: TTL принадлежит записываемому сейчас значению, а не тому, которое может позже заменить его через put.

Сначала нужна одна настройка. TTL ключей использует возможность бакета limit markers — маркеры лимитов, оставляющие след при истечении срока. Прежде чем ключ сможет иметь TTL, эти маркеры нужно включить. INVENTORY создан без них, поэтому один раз включите их, затем создайте временный ключ:

#!/bin/bash

# Give a single key its own lifetime with a per-key TTL.
#
# Per-key TTL rides on the bucket's Limit Markers, so the bucket must have
# them enabled first. INVENTORY was created without them, so turn them on
# once (the duration is how long the bucket keeps the expiry marker):
nats kv edit INVENTORY --marker-ttl 1h

# Now create flash-sale with a 30-minute TTL. The value expires on its own
# 30 minutes after this create; no service has to remember to clean it up.
# Note: TTL is accepted on CREATE only.
nats kv create INVENTORY flash-sale 99 --ttl 30m

# Expected: create echoes the value it stored, and the key counts down on
# its own:
#
# 99
#
# Per-key TTL requires nats-server 2.11 or newer. On an older server the
# create is rejected because the bucket cannot enable Limit Markers.

# --- Per-key TTL is create-only: to change it, delete then create ---------
#
# Neither put nor update takes a --ttl; the CLI rejects the flag. Writing
# flash-sale again with put or update appends a new value with no TTL, so
# the key stops expiring rather than keeping its clock. To give flash-sale
# a different lifetime, remove it and create it again with the new TTL:
nats kv del INVENTORY flash-sale --force
nats kv create INVENTORY flash-sale 99 --ttl 10m

# The key now expires in 10 minutes instead of 30.

Теперь flash-sale содержит 99 и удалится через 30 минут. Поскольку TTL сохранён со значением, не нужны cron, отдельный сервис очистки или обход ключей.

Для TTL ключей требуется nats-server 2.11 или новее: в этой версии появились маркеры лимитов. Старый сервер отклоняет их включение и создание ключа со сроком. В 2.11 возможность уже доступна.

Лимиты ограничивают весь бакет​

Если TTL ключа ограничивает одно значение, лимиты бакета действуют на хранилище целиком. Они не дают ему расти бесконечно и задаются при создании. Важнее всего три:

  • Максимальный размер бакета: суммарное число байтов всех ключей и сохранённых ревизий. Бакет не вырастет сверх него.
  • Максимальный размер значения: предел одного значения. Put более крупного значения отклоняется. KV предназначено для небольших значений; крупным место в хранилище объектов.
  • Глубина истории: число сохраняемых ревизий каждого ключа с предыдущей страницы. Максимум 64; это также предел числа сообщений одного ключа.

Здесь лимиты задаются отдельному временному бакету CACHE, поэтому числа не относятся к INVENTORY:

#!/bin/bash

# Create a throwaway CACHE bucket to show the three bucket-level limits.
# We use CACHE, not the pinned INVENTORY bucket, on purpose: INVENTORY's
# TTLs are per-key, not bucket-wide, and we do not want to imply the whole
# INVENTORY bucket expires.
#
# --ttl 1h bucket-wide max age: every value older than 1h is
# removed, regardless of key. This is the bucket's
# MaxAge, not a per-key TTL.
# --max-bucket-size the bucket's total size cap, in bytes.
# --max-value-size the largest a single value may be, in bytes.
nats kv add CACHE \
--history 1 \
--ttl 1h \
--max-bucket-size 16MB \
--max-value-size 64KB

# Expected output is the bucket's status. The CLI parses MB and KB as binary
# units (1 MB = 1 MiB, 1 KB = 1 KiB), so 16MB shows as 16 MiB and 64KB as
# 64 KiB (labels abbreviated here):
#
# Information for Key-Value Store Bucket CACHE created <time>
#
# Configuration:
#
# Bucket Name: CACHE
# History Kept: 1
# Maximum Age: 1h0m0s
# Maximum Bucket Size: 16 MiB
# Maximum Value Size: 64 KiB
# ...
#
# A KV bucket uses discard-new: a put that would push it past
# --max-bucket-size, or a value larger than --max-value-size, is rejected
# with an error and the existing values are kept. Size the bucket for the
# working set you need to hold, not the average, so a burst doesn't bounce
# writes.

Параметр --ttl бакета выше задаёт другой срок, чем TTL ключа. TTL бакета удаляет каждое значение по достижении возраста, TTL ключа — одно. Общий вариант — лимит потока MaxAge, единый срок для всех значений, описанный вместе с другими лимитами потока. Вариант ключа построен на TTL сообщений JetStream; именно его применение в KV рассматривает эта глава.

Все параметры конфигурации бакета приведены в разделе Справочник → Создание потока: бакет создаётся как поток, а лимиты отображаются на его поля. Здесь достаточно трёх перечисленных.

Истечение срока оставляет маркер наблюдателям​

Когда TTL ключа истекает, сервер не просто молча отбрасывает значение, а оставляет маркер: небольшое сообщение о том, что ключ удалён и почему. В других системах такой маркер называют tombstone. В KV используем слово «маркер»; при истечении TTL он содержит причину MaxAge: значение устарело.

Маркер нужен складской панели. Наблюдатель получает его как очистку ключа: CLI выводит PURGE, как при ручной очистке. Без маркера наблюдатель, увидевший появление flash-sale, никогда не узнал бы об исчезновении, и его состояние устарело бы. Маркер поддерживает актуальность наблюдателей при автоматическом удалении.

Анимация показывает последовательность: inventory создаёт flash-sale с TTL 30 минут, время проходит, сервер ставит маркер с причиной MaxAge, а складская панель получает его как очистку. Значение исчезло без изменения со стороны сервисов, но наблюдатель всё равно уведомлён через маркер.

Подводные камни​

При первом добавлении TTL или лимитов распространены две ошибки: от них ожидают поведения, которого нет.

TTL ключа задаётся только при create. Put и update не принимают --ttl: CLI сразу отклоняет флаг. Повторная запись также не продлевает TTL: put или update добавляет новое текущее значение без собственного срока, и ключ просто перестаёт истекать. Обе операции ведут себя одинаково. Для другого TTL удалите ключ и создайте заново с новым сроком. Меняйте TTL удалением и созданием, а не put или update.

Это показано в примере create выше: после создания со сроком flash-sale удаляется и создаётся снова с более коротким TTL. Это единственный способ изменить срок.

Лимиты отклоняют запись, а не освобождают место для слишком большого значения. Put значения больше максимального размера сразу отклоняется, как и запись, которая превысила бы общий размер бакета. Сервер возвращает ошибку и сохраняет существующие значения. Inventory видит ошибку при put, а не позднее при get, поэтому CACHE, рассчитанный на среднюю нагрузку, начинает отказывать при первом всплеске до предела. Рассчитывайте бакет на реально нужный рабочий набор, а не среднее значение, чтобы напряжённая минута не отклоняла необходимые записи. Предел значения задавайте выше наибольшего допустимого значения.

Текущее состояние​

Теперь у вас есть:

  • Бакет INVENTORY с включёнными маркерами лимитов и ключ flash-sale, автоматически истекающий по собственному TTL.
  • Понимание трёх общих лимитов: размер бакета, размер значения и глубина истории.
  • Модель маркера истечения: сервер оставляет причину MaxAge, а складская панель получает маркер как очистку ключа.

Бакет теперь полностью настроен: хранит ключи и значения, сохраняет историю, поддерживает безопасные одновременные записи и автоматическое удаление по TTL.

Что дальше​

Следующая страница раскрывает поток KV_INVENTORY, всё время лежавший под бакетом, прямое чтение и различие удаления и очистки.

Переходите к странице Внутреннее устройство.

См. также​