Key-Value Store

Armazenamento key-value rapido com suporte a TTL. Ideal para cache, sessoes e estado temporario.

Para configuração de store, veja Store.

Carregamento

local store = require("store")

Adquirindo um Store

Obter um recurso store por ID do registro:

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()

Retorna: Store, error

Armazenando Valores

Armazenar um valor com TTL opcional:

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

-- Set simples
cache:set("user:123:name", "Alice")

-- Set com TTL (expira em 300 segundos)
cache:set("session:abc", {user_id = 123, role = "admin"}, 300)

Retorna: boolean, error

Recuperando Valores

Obter um valor por chave:

local user = cache:get("user:123")
if not user then
    -- Chave não encontrada ou expirada
end

Retorna: any, error

Retorna nil se chave não existe.

Verificando Existencia

Verificar se uma chave existe sem recuperar:

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

Retorna: boolean, error

Deletando Chaves

Remover uma chave do store:

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

Retorna: boolean, error

Retorna true se deletado, false se chave não existia.

Lendo Metadados da Entrada

entry retorna o valor junto com sua version — uma string opaca usada para concorrência otimista:

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

Retorna: Entry, error — {key: string, value: any, version: string}

Listando Chaves

Listar entradas em ordem determinística de chave, com paginação:

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

-- próxima página
if page.has_more then
    page = cache:list({ prefix = "session:", after = page.cursor })
end

Retorna: Page, error — {items: Entry[], cursor: string, has_more: boolean}

Escritas Condicionais

put escreve um valor e retorna sua nova Entry. As opções habilitam concorrência otimista:

-- cria apenas se a chave não existir
local e, err = cache:put("lock:job-1", owner, { only_if_absent = true })
if err and err:kind() == "ALREADY_EXISTS" then
    -- outra pessoa a detém
end

-- compare-and-set: escreve apenas se a versão ainda corresponder
local cur = cache:entry("config")
local e2, err2 = cache:put("config", new_value, { if_version = cur.version })
if err2 and err2:kind() == "CONFLICT" then
    -- um escritor concorrente a alterou; releia e tente novamente
end

only_if_absent e if_version são mutuamente exclusivos.

Retorna: Entry, error

Capacidades do Store

info informa o backend e o que ele suporta, para que o código possa se adaptar a qualquer store vinculado:

local info = cache:info()
-- info.backend      -> um de store.backend.* (ex.: "kv.raft")
-- info.consistency  -> um de store.consistency.* (ex.: "linearizable")
-- info.durable / info.list / info.versioned / info.conditional_put / info.ttl  (booleans)

Retorna: Info, error — {id, backend, consistency, durable, list, versioned, conditional_put, ttl}

Constantes

if cache:info().consistency == store.consistency.LINEARIZABLE then
    -- seguro usar compare-and-set
end

Métodos do Store

Permissões

Operações de store estao sujeitas a avaliação de política de segurança.

Erros

store.get() e todos os métodos do handle do store (get, set, has, delete) retornam erros estruturados (use err:kind()).

Veja Error Handling para trabalhar com erros.