Almacen Clave-Valor

Almacenamiento clave-valor rapido con soporte de TTL. Ideal para cache, sesiones y estado temporal.

Para configuración del almacen, consulte Almacen.

Carga

local store = require("store")

Adquirir un Almacen

Obtener un recurso de almacen por ID de 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()

Devuelve: Store, error

Almacenar Valores

Almacenar un valor con TTL opcional:

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

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

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

Devuelve: boolean, error

Recuperar Valores

Obtener un valor por clave:

local user = cache:get("user:123")
if not user then
    -- Clave no encontrada o expirada
end

Devuelve: any, error

Devuelve nil si la clave no existe.

Verificar Existencia

Verificar si una clave existe sin recuperar:

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

Devuelve: boolean, error

Eliminar Claves

Eliminar una clave del almacen:

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

Devuelve: boolean, error

Devuelve true si se elimino, false si la clave no existia.

Lectura de Metadatos de Entrada

entry devuelve el valor junto con su version — una cadena opaca usada para concurrencia optimista:

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

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

Listado de Claves

Lista entradas en orden determinista de claves, con paginación:

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

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

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

Escrituras Condicionales

put escribe un valor y devuelve su nueva Entry. Las opciones habilitan concurrencia optimista:

-- crear solo si la clave no existe
local e, err = cache:put("lock:job-1", owner, { only_if_absent = true })
if err and err:kind() == "ALREADY_EXISTS" then
    -- otro la tiene
end

-- compare-and-set: escribir solo si la versión aún coincide
local cur = cache:entry("config")
local e2, err2 = cache:put("config", new_value, { if_version = cur.version })
if err2 and err2:kind() == "CONFLICT" then
    -- un escritor concurrente la cambió; volver a leer y reintentar
end

only_if_absent e if_version son mutuamente exclusivos.

Devuelve: Entry, error

Capacidades del Store

info reporta el backend y lo que soporta, de modo que el código puede adaptarse al almacén que esté vinculado:

local info = cache:info()
-- info.backend      -> uno de store.backend.* (p. ej. "kv.raft")
-- info.consistency  -> uno de store.consistency.* (p. ej. "linearizable")
-- info.durable / info.list / info.versioned / info.conditional_put / info.ttl  (booleanos)

Devuelve: 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

Metodos de Store

Permisos

Las operaciones de almacen estan sujetas a evaluacion de politica de seguridad.

Errores

store.get() y todos los métodos del manejador de store (get, set, has, delete) devuelven errores estructurados (usa err:kind()).

Consulte Manejo de Errores para trabajar con errores.