Almacén clave-valor

El módulo store proporciona almacenamiento clave-valor con TTL opcionales. Puede contener datos en caché, sesiones y otro estado temporal.

Esta página es una referencia de API. Sus fragmentos presuponen un almacén configurado, los permisos indicados abajo y valores proporcionados por la aplicación, como owner o new_value. Los fragmentos posteriores a la adquisición usan un handle cache existente y activo; no son funciones independientes.

Para configurar el almacén, consulta Almacén.

Carga

local store = require("store")

Adquisición de un almacén

Adquiere un recurso de almacén por su ID de registro:

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

local _, set_err = cache:set("user:123", {name = "Alice"}, 3600)
if set_err then
    cache:release()
    return nil, set_err
end

local user, get_err = cache:get("user:123")

cache:release()
if get_err then return nil, get_err end
return user

Devuelve: Store, error

Almacenamiento de valores

Almacena un valor con un TTL opcional:

-- Simple set
local _, err = cache:set("user:123:name", "Alice")
if err then return nil, err end

-- Set with TTL (expires in 300 seconds)
local ok, ttl_err = cache:set("session:abc", {user_id = 123, role = "admin"}, 300)
if ttl_err then return nil, ttl_err end
return ok

Devuelve: boolean, error

Recuperación de valores

Recupera un valor por su clave:

local errors = require("errors")

local user, err = cache:get("user:123")
if err then
    if err:kind() == errors.NOT_FOUND then
        return nil -- key missing or expired
    end
    return nil, err
end
return user

Devuelve: any, error

Devuelve nil y un error errors.NOT_FOUND si la clave no existe o ha expirado.

Comprobación de existencia

Comprueba si una clave existe sin recuperar su valor:

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

Devuelve: boolean, error

Eliminación de claves

Elimina una clave del almacén:

local deleted, err = cache:delete("session:" .. session_id)
if err then return nil, err end
return deleted

Devuelve: boolean, error

El método devuelve true cuando elimina la clave y false cuando la clave no existe.

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 err then return nil, err end
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 })
if err then return nil, err end
for _, e in ipairs(page.items) do
    print(e.key, e.value)
end

-- next page
if page.has_more then
    local next_page, next_err = cache:list({ prefix = "session:", after = page.cursor })
    if next_err then return nil, next_err end
    page = next_page
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:

local errors = require("errors")

-- create only if the key does not exist
local e, err = cache:put("lock:job-1", owner, { only_if_absent = true })
if err and err:kind() == errors.ALREADY_EXISTS then
    -- otro la tiene
end

-- compare-and-set: write only if the version still matches
local cur, read_err = cache:entry("config")
if read_err then return nil, read_err end
local e2, err2 = cache:put("config", new_value, { if_version = cur.version })
if err2 and err2:kind() == errors.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, err = cache:info()
if err then return nil, err end
-- info.backend      -> one of store.backend.* (e.g. "kv.raft")
-- info.consistency  -> one of store.consistency.* (e.g. "linearizable")
-- info.durable / info.list / info.versioned / info.conditional_put / info.ttl  (booleans)

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

Constantes

local info, err = cache:info()
if err then return nil, err end
if info.consistency == store.consistency.LINEARIZABLE then
    -- safe to use compare-and-set
end

Métodos de Store

Permisos

La evaluación de políticas de seguridad se aplica a las operaciones del almacén.

Errores

store.get() y todos los métodos del manejador de store (get, entry, set, put, list, has, delete, info) devuelven errores estructurados (usa err:kind()), salvo que una denegación de permiso en store.get, get, set, has y delete lanza un error de Lua en su lugar.

Consulta Manejo de errores para trabajar con errores.