Key-Value хранилище

Быстрое key-value хранилище с поддержкой TTL. Идеально для кэширования, сессий и временного состояния.

Настройку хранилища см. в Store.

Загрузка

local store = require("store")

Получение хранилища

Получить ресурс хранилища по ID реестра:

local cache, err = store.get("app:cache")
if err then
    return nil, err
end

cache:set("user:123", {name = "Alice"}, 3600)
local user = cache:get("user:123")

cache:release()

Возвращает: Store, error

Сохранение значений

Сохранить значение с опциональным TTL:

local cache = store.get("app:cache")

-- Простое сохранение
cache:set("user:123:name", "Alice")

-- Сохранение с TTL (истекает через 300 секунд)
cache:set("session:abc", {user_id = 123, role = "admin"}, 300)

Возвращает: boolean, error

Получение значений

Получить значение по ключу:

local user = cache:get("user:123")
if not user then
    -- Ключ не найден или истёк
end

Возвращает: any, error

Возвращает nil если ключ не существует.

Проверка существования

Проверить наличие ключа без получения значения:

if cache:has("lock:" .. resource_id) then
    return nil, errors.new("CONFLICT", "Resource is locked")
end

Возвращает: boolean, error

Удаление ключей

Удалить ключ из хранилища:

cache:delete("session:" .. session_id)

Возвращает: boolean, error

Возвращает true если удалён, false если ключ не существовал.

Чтение метаданных записи

entry возвращает значение вместе с его version — непрозрачной строкой, используемой для оптимистичной конкурентности:

local e, err = cache:entry("user:123")
if e then
    print(e.key, e.value, e.version)
end

Возвращает: Entry, error — {key: string, value: any, version: string}

Перечисление ключей

Перечислить записи в детерминированном порядке ключей с постраничной разбивкой:

local page, err = cache:list({ prefix = "session:", limit = 100 })
for _, e in ipairs(page.items) do
    print(e.key, e.value)
end

-- следующая страница
if page.has_more then
    page = cache:list({ prefix = "session:", after = page.cursor })
end

Возвращает: Page, error — {items: Entry[], cursor: string, has_more: boolean}

Условные записи

put записывает значение и возвращает его новый Entry. Опции включают оптимистичную конкурентность:

-- создать только если ключ не существует
local e, err = cache:put("lock:job-1", owner, { only_if_absent = true })
if err and err:kind() == "ALREADY_EXISTS" then
    -- ключ держит кто-то другой
end

-- compare-and-set: записать только если версия всё ещё совпадает
local cur = cache:entry("config")
local e2, err2 = cache:put("config", new_value, { if_version = cur.version })
if err2 and err2:kind() == "CONFLICT" then
    -- конкурентный писатель изменил его; перечитать и повторить
end

only_if_absent и if_version взаимоисключающи.

Возвращает: Entry, error

Возможности хранилища

info сообщает о бэкенде и о том, что он поддерживает, чтобы код мог адаптироваться к привязанному хранилищу:

local info = cache:info()
-- info.backend      -> одно из store.backend.* (напр. "kv.raft")
-- info.consistency  -> одно из store.consistency.* (напр. "linearizable")
-- info.durable / info.list / info.versioned / info.conditional_put / info.ttl  (булевы)

Возвращает: Info, error — {id, backend, consistency, durable, list, versioned, conditional_put, ttl}

Константы

if cache:info().consistency == store.consistency.LINEARIZABLE then
    -- безопасно использовать compare-and-set
end

Методы Store

Разрешения

Операции хранилища подчиняются вычислению политики безопасности.

Ошибки

store.get() и все методы дескриптора хранилища (get, set, has, delete) возвращают структурированные ошибки (используйте err:kind()).

См. Обработка ошибок для работы с ошибками.