Lua script context API - Cache sub-context

cache

Cache operations for storing and retrieving values from named in-memory caches.

Caches must be defined in the configuration using the caches clause before they can be used from scripts. Each cache is a key-value store where keys map to one or more values, with optional TTL-based expiration.

Methods

MethodParametersReturnsDescription
get(cache, key)cache name, keyvalue?Get first cached value
get_all(cache, key)cache name, keyvalues?Get all cached values
set(cache, key, value, timeout?)cache, key, value, optional TTL (ms)-Set cached value
set_values(cache, key, values, timeout?)cache, key, values array, optional TTL (ms)-Set multiple values
append(cache, key, value, timeout?)cache, key, value, optional TTL (ms)-Append to cached values
append_values(cache, key, values, timeout?)cache, key, values, optional TTL (ms)-Append multiple values
remove(cache, key)cache name, key-Remove cached values
increment(cache, key, amount, timeout?)cache, key, amount, optional TTL (ms)numberAtomically increment counter and return

The optional timeout parameter specifies the TTL (time-to-live) in milliseconds (as a plain number, not a duration string). If omitted, the cache's configured default_timeout is used. If the cache has no default_timeout, entries persist until explicitly removed or the process restarts.

Note: Unlike configuration files which support duration units (e.g., 5m, 1h), Lua script timeout parameters must be specified as raw milliseconds (e.g., 300000 for 5 minutes).

Timeout behavior (applies to all cache operations):

  • Explicit timeout provided: Always sets/resets expiration to that duration from now
  • No timeout parameter, NEW key: Sets expiration using cache's default_timeout
  • No timeout parameter, EXISTING key: Preserves the original expiration time (fixed window)

Example

local context, previous = ...

local cache = context.cache

-- Store a value with 5 minute TTL (300000 ms)
cache:set("session_cache", "user123", "session_data", 300000)

-- Retrieve value
local data = cache:get("session_cache", "user123")

-- Remove when done
cache:remove("session_cache", "user123")

return previous

Rate Limiting Example

The increment method is ideal for implementing counters and rate limiting with fixed time windows:

local context, previous = ...

local cache = context.cache
local username = context.aaa.identity

-- Atomically increment counter
-- Uses cache's configured timeout (100ms) on first call only (fixed window)
local count = cache:increment("rate_limit", username, 1)

if count > 100 then
    context.vars:set("rate_limit_exceeded", "true")
    context.log:error("Rate limit exceeded for user: " .. username)
    reject("Rate limit exceeded. Try again later.")
end

return previous

Configure the cache with the desired rate limit window:

caches {
    cache "rate_limit" {
        default_timeout 100ms;  # 100ms window = ~1000 TPS limit
    }
}

Call the script from a pipeline, typically in pre-authentication step:

pre-authentication {
    script "tps_load_limit";
    if all {
        vars.rate_limit_exceeded == any;
    } then {
        discard vars.rate_limit_exceeded;
    }
}
Navigation
Home