Client persistent KVP

Endpoint- and resource-isolated local key/value persistence: CRUD, search, atomic operations, quotas, and why it must never hold secrets.

2 min read363 wordsMarkdown

CyberM.kvp stores small client-local values persistently. Its namespace is always:

connection address -> resource name -> key

Connecting to 188.40.140.88:11777 and localhost:11777 therefore creates two independent stores, even if both addresses reach the same machine. Resources cannot name or inspect another resource's namespace.

local ok, reason = CyberM.kvp.set("character:lastSlot", 2)
assert(ok, reason)

local slot = CyberM.kvp.get("character:lastSlot", 1)
local present = CyberM.kvp.has("character:lastSlot")
local newCount = CyberM.kvp.increment("stats:connections", 1)

API

Method Result Description
set(key, value) true or false, reason Store a string, integer, finite number, or boolean.
get(key[, default]) value/default, or nil, reason Read the original Lua type. Missing keys are not errors.
has(key) boolean, optionally reason Check whether the key exists.
delete(key) boolean, optionally reason Delete a key and report whether it existed.
keys([prefix[, limit]]) string array or nil, reason Sorted prefix search; default limit is 256.
find([prefix[, limit]]) entry array or nil, reason Return { key, value, type } records.
clear([prefix]) removed count or nil, reason Delete this resource's matching keys only.
increment(key[, delta]) number or nil, reason Atomically create/increment a numeric value.
setIfAbsent(key, value) boolean, optionally reason Redis-style SETNX.
compareAndSet(key, expected, replacement) boolean, optionally reason Atomic CAS. nil means missing for expected and deletion for replacement.
stats() table or nil, reason Entry/byte usage, quotas, address, and resource namespace.

FiveM-familiar aliases are also available: SetResourceKvp, GetResourceKvp, and DeleteResourceKvp. New code should prefer CyberM.kvp because it exposes typed results and the atomic/search operations.

Limits and persistence guarantees

  • Keys: 1-256 bytes, with no control characters.
  • String values: at most 64 KiB each.
  • Resource store: at most 4,096 entries and 1 MiB of key/value payload.
  • Files are committed through a same-directory temporary file and an atomic replace.
  • A versioned binary header and CRC32 reject truncated or corrupted files instead of silently replacing them.
  • Validation/preflight Lua states cannot write KVP data.

Data is stored below red4ext/plugins/CyberM/storage/kvp. The connection address is reversibly hex-encoded before becoming a directory name, preventing path traversal without changing its namespace semantics.

This is local persistence, not secret storage. The player owns the machine and can inspect or remove the files. Never store passwords, server tokens, private keys, or authoritative economy state in client KVP. Use the server database for anything that must resist client modification.

For agents and LLMs: this page as Markdown · llms.txt · llms-full.txt