TTL и лимиты
До сих пор ключи INVENTORY жили до перезаписи или удаления. Для остатка товара это разумно, но в бакете бывают и другие данные. Некоторые должны исчезать сами: цена краткой распродажи, временный токен сеанса или флаг блокировки артикула на 30 минут.
Здесь добавляются два вида ограничений. Первый — TTL отдельного ключа, удаляющий его по сроку. Второй — общие лимиты бакета: суммарный размер, размер значения, глубина истории. При истечении срока сервер оставляет маркер, чтобы складская панель узнала об исчезновении значения так же, как о любом другом изменении.
Бакет INVENTORY остаётся с предыдущих страниц: widget-blue уменьшен до 40, складская панель наблюдает. Добавим ключ с TTL.
TTL ключа удаляет отдельное значение по сроку
TTL (time-to-live, время жизни) — срок хранения значения до удаления сервером. TTL ключа привязывает отсчёт к одному ключу. Тот живёт заданное время, затем исчезает сам: сервису не нужно помнить об удалении.
TTL ключа задаётся только при create. Вы передаёте срок вместе со значением, и отсчёт начинается с записи. Это намеренное ограничение: TTL принадлежит записываемому сейчас значению, а не тому, которое может позже заменить его через put.
Сначала нужна одна настройка. TTL ключей использует возможность бакета limit markers — маркеры лимитов, оставляющие след при истечении срока. Прежде чем ключ сможет иметь TTL, эти маркеры нужно включить. INVENTORY создан без них, поэтому один раз включите их, затем создайте временный ключ:
- CLI
- C
#!/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.
// Per-key TTL rides on the bucket's limit markers, so the bucket
// needs them enabled. The C client turns them on when the bucket is
// created: a LimitMarkerTTL > 0 enables per-key TTLs and is how long
// the bucket keeps an expiry marker. Requires nats-server 2.11+.
kvStore *kv = NULL;
uint64_t rev = 0;
kvConfig cfg;
kvConfig_Init(&cfg);
cfg.Bucket = "INVENTORY";
cfg.History = 10;
cfg.LimitMarkerTTL = 60LL * 60 * 1000000000LL; // 1 hour, in nanoseconds
s = js_CreateKeyValue(&kv, js, &cfg);
// Create flash-sale with a 30-minute TTL (in milliseconds). The value
// removes itself 30 minutes later; no service has to clean it up.
// A TTL is accepted on create only: neither put nor update takes one.
if (s == NATS_OK)
s = kvStore_CreateStringWithTTL(&rev, kv, "flash-sale", "99",
30 * 60 * 1000);
if (s == NATS_OK)
printf("created flash-sale at revision %" PRIu64 "\n", rev);
// A per-key TTL is create-only, and writing the key again appends a
// value with no TTL of its own. To change a TTL, delete the key and
// create it again with the new one.
if (s == NATS_OK)
s = kvStore_Delete(kv, "flash-sale");
if (s == NATS_OK)
s = kvStore_CreateStringWithTTL(&rev, kv, "flash-sale", "99",
10 * 60 * 1000);
if (s == NATS_OK)
printf("flash-sale now expires in 10 minutes\n");
Теперь flash-sale содержит 99 и удалится через 30 минут. Поскольку TTL сохранён со значением, не нужны cron, отдельный сервис очистки или обход ключей.
Для TTL ключей требуется nats-server 2.11 или новее: в этой версии появились маркеры лимитов. Старый сервер отклоняет их включение и создание ключа со сроком. В 2.11 возможность уже доступна.
Лимиты ограничивают весь бакет
Если TTL ключа ограничивает одно значение, лимиты бакета действуют на хранилище целиком. Они не дают ему расти бесконечно и задаются при создании. Важнее всего три:
- Максимальный размер бакета: суммарное число байтов всех ключей и сохранённых ревизий. Бакет не вырастет сверх него.
- Максимальный размер значения: предел одного значения. Put более крупного значения отклоняется. KV предназначено для небольших значений; крупным место в хранилище объектов.
- Глубина истории: число сохраняемых ревизий каждого ключа с предыдущей страницы. Максимум 64; это также предел числа сообщений одного ключа.
Здесь лимиты задаются отдельному временному бакету CACHE, поэтому числа не относятся к INVENTORY:
- CLI
- C
#!/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.
// Create a throwaway CACHE bucket to show the three bucket-level
// limits. TTL here is the bucket-wide max age — every value older
// than 1 hour is removed, regardless of key — not a per-key TTL.
kvStore *cache = NULL;
kvStatus *sts = NULL;
kvConfig cfg;
kvConfig_Init(&cfg);
cfg.Bucket = "CACHE";
cfg.History = 1;
cfg.TTL = 60LL * 60 * 1000000000LL; // 1 hour, in nanoseconds
cfg.MaxBytes = 16 * 1024 * 1024; // total size cap: 16 MiB
cfg.MaxValueSize = 64 * 1024; // largest single value: 64 KiB
s = js_CreateKeyValue(&cache, js, &cfg);
if (s == NATS_OK)
s = kvStore_Status(&sts, cache);
if (s == NATS_OK)
{
// A put larger than the value cap, or one that would push the
// bucket past its size cap, is rejected; existing values stay.
printf("Bucket: %s\n", kvStatus_Bucket(sts));
printf("History kept: %" PRIi64 "\n", kvStatus_History(sts));
printf("Maximum age: %" PRIi64 "s\n", kvStatus_TTL(sts) / 1000000000LL);
kvStatus_Destroy(sts);
}
kvStore_Destroy(cache);
Параметр --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, всё время лежавший под бакетом, прямое чтение и различие удаления и очистки.
Переходите к странице Внутреннее устройство.
См. также
- Справочник → Создание потока — все лимиты бакета и допустимые диапазоны.
- JetStream → TTL сообщений — механизм истечения сообщений, на котором построен TTL ключей.
- JetStream → Настройка потока —
MaxAgeи другие лимиты, соответствующие общему TTL и размеру бакета. - Хранилище объектов — место для значений, выросших за пределы KV.