# 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

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

#### C

```
// 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 предназначено для небольших значений; крупным место в [хранилище объектов](/learn/object-store/.md).
* **Глубина истории**: число сохраняемых ревизий каждого ключа с предыдущей страницы. Максимум 64; это также предел числа сообщений одного ключа.

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

#### CLI

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

#### C

```
// 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`, единый срок для всех значений, описанный вместе с другими [лимитами потока](/learn/jetstream/shaping-the-stream.md). Вариант ключа построен на [TTL сообщений](/learn/jetstream/message-ttl.md) JetStream; именно его применение в KV рассматривает эта глава.

Все параметры конфигурации бакета приведены в разделе [Справочник → Создание потока](/reference/jetstream/api/stream/create.md): бакет создаётся как поток, а лимиты отображаются на его поля. Здесь достаточно трёх перечисленных.

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

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

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

**Движение сообщений — Истечение TTL ключа KV (анимация):** TTL отдельного ключа истекает самостоятельно, а наблюдатель узнаёт об этом. Inventory записывает flash-sale=99 в KV\_INVENTORY со сроком 30 минут. После этого времени значение устаревает, сервер ставит маркер с причиной MaxAge. Наблюдающий warehouse-dashboard получает его как очистку и узнаёт об исчезновении, хотя ни один сервис не удалял ключ.

* inventory → inventory
* clock → inventory
* inventory → warehouse-dashboard

Анимация показывает последовательность: 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`, всё время лежавший под бакетом, прямое чтение и различие удаления и очистки.

Переходите к странице [Внутреннее устройство](/learn/key-value/under-the-hood.md).

## См. также

* [Справочник → Создание потока](/reference/jetstream/api/stream/create.md) — все лимиты бакета и допустимые диапазоны.
* [JetStream → TTL сообщений](/learn/jetstream/message-ttl.md) — механизм истечения сообщений, на котором построен TTL ключей.
* [JetStream → Настройка потока](/learn/jetstream/shaping-the-stream.md) — `MaxAge` и другие лимиты, соответствующие общему TTL и размеру бакета.
* [Хранилище объектов](/learn/object-store/.md) — место для значений, выросших за пределы KV.
