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
size(cache)cache namenumberGet number of keys in cache
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
rate_limit_gcra(cache, key, limit, period, timeout?)cache, key, limit of how many requests, spread over time period in milliseconds, optional TTL (ms)booleanGCRA rate limiting - returns true if allowed
rate_limit_gcra_rnd(cache, key, limit, period, variation, timeout?)cache, key, limit, period in ms, variation in ms for randomization (±variation), optional TTL (ms)booleanGCRA with randomized intervals - returns true if allowed

Synchronous vs Asynchronous Methods

Synchronous methods (wait for cache operation to complete):

  • increment() - Waits for the increment to be applied before returning the new value
  • rate_limit_gcra() - Waits for rate limit check to complete
  • rate_limit_gcra_rnd() - Waits for rate limit check to complete

Asynchronous methods (return immediately without waiting):

  • set(), set_values(), append(), append_values(), remove() - Queue cache update and return immediately
  • get(), get_all(), size() - Read current cache state (may not reflect recent asynchronous updates)

Important: Asynchronous write methods (set, append, remove) queue cache updates in the background. Subsequent reads within the same request may not reflect these updates. To ensure cache updates are visible immediately, use the synchronous increment() method or check the cache state in a subsequent request.

Timeout Behavior

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.

For rate_limit_gcra and rate_limit_gcra_rnd, the period and variation parameters are specified in milliseconds, and timeout defaults to 2× period if not provided. The cache is auto-created if it doesn't exist. The rate_limit_gcra_rnd variant adds random jitter of ±variation milliseconds to each request's emission interval to prevent thundering herd effects.

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:

  • 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

The increment, rate_limit_gcra, and rate_limit_gcra_rnd methods enable counter-based and GCRA rate limiting respectively. The rate_limit_gcra_rnd variant adds randomization to prevent synchronized bursts from multiple clients.

Note: For statistical counting and long-term metrics, use the count action instead. Cache increment and rate-limit methods are designed for temporary tracking with automatic expiry and script-level reads/writes.

For complete examples including configuration and pipeline integration, see Rate Limiting Algorithms.

Navigation
Home