kvstore API reference
A backend selector for a key/value store with per-key TTL: one Store value is one of three backends - a memcache connection, a redis connection, or the in-process kv library - and dispatches a uniform set / get / delete / touch / incrWindow surface to whichever was chosen. This is the shared backend layer under the session and ratelimit modules, so each works over any of the three without duplicating the dispatch. The verb set mirrors memcache, so a fixed-window counter (atomic incr + TTL) works identically on all three.
Store is a sum type (enum), not a tagged struct: each variant carries only its own backend handle, and the dispatch is a match the compiler checks for exhaustiveness - there is no invalid "kind says memcache but the handle is empty" state, and a new backend cannot be silently forgotten in one verb.
The memcache / redis backends are distributed (state lives on the server, shared across processes); the local backend (the kv library) keeps state in this process - either in memory (inProcessStore, reset each run) or persisted to a file (fileStore, survives across jennifer run invocations - handy for development and CLI tools with no server). Pick a distributed backend when more than one process must see the same state.
Import with import "kvstore.j" as kvstore;. See the kvstore guide for prose and examples.
Functions
kvstore.delete(store as Store, key as string)
Remove key; returns whether it existed.
Parameters
store{Store}- the backend storekey{string}- the key to remove
Returns {bool} - whether the key existed
kvstore.fileStore(path as string)
A store backed by the in-process kv library, persisted to path: its contents load on open and survive across jennifer run invocations (unlike inProcessStore, which resets each run). No server; single-process (safe for spawn within one process, but not for concurrent separate processes on one file - use a distributed backend for that). Practical for development and persistent CLI state.
Parameters
path{string}- the file to persist the store to
Returns {Store} - a file-backed local store
kvstore.get(store as Store, key as string)
Return the value at key, or "" when absent / expired.
Parameters
store{Store}- the backend storekey{string}- the key to read
Returns {string} - the value, or "" when absent / expired
kvstore.inProcessStore()
A store backed by the in-process kv library (this process only, no server). Opens a fresh kv.Store; keep the returned Store for the program's lifetime.
Returns {Store} - an in-process store
kvstore.incrWindow(store as Store, key as string, ttl as int)
Atomically increment the counter at key and return the new value, creating it (at 1, with a ttl-second expiry) on the first hit. The atomic-counter-plus-TTL primitive a fixed-window rate limiter is built from - portable across all three backends (redis INCR + EXPIRE; memcache / kv incr else add).
Parameters
store{Store}- the storekey{string}- the counter keyttl{int}- the TTL to arm on the first hit (seconds)
Returns {int} - the counter's new value
kvstore.memcacheStore(mc as memcache.Session)
A store backed by a memcache connection (distributed).
Parameters
mc{memcache.Session}- the memcache connection
Returns {Store} - a memcache-backed store
kvstore.redisStore(rc as redis.Session)
A store backed by a redis connection (distributed).
Parameters
rc{redis.Session}- the redis connection
Returns {Store} - a redis-backed store
kvstore.set(store as Store, key as string, value as string, ttl as int)
Store value at key with a ttl-second expiry (0 = no expiry), replacing any existing value.
Parameters
store{Store}- the backend storekey{string}- the key to writevalue{string}- the value to storettl{int}- the expiry in seconds (0 = no expiry)
kvstore.touch(store as Store, key as string, ttl as int)
Re-arm key's expiry to ttl seconds; returns whether it existed.
Parameters
store{Store}- the backend storekey{string}- the key to re-armttl{int}- the new expiry in seconds (0 = no expiry)
Returns {bool} - whether the key existed
Enums
kvstore.Store
A store bound to one backend (a sum type over the three). Value-semantic; the live connection / handle a variant wraps is shared across copies (a net.Conn or a kv.Store handle). Build with memcacheStore / redisStore / inProcessStore / fileStore.