Cache API — Get / Set / Delete

The distributed cache is a key-value store that syncs across all nodes in the mesh. Values are stored as shared_buffer and support TTL (time-to-live) expiration.

Accessing the Cache

auto& cache = app.get_state()->of_cache();

Access the cache through state::instance. All operations are thread-safe.

---

Setting a Value

set(key, value, ttl_ms, timestamp, clock)

Stores a value in the cache with an optional TTL.

using namespace framework;

// Create a value buffer
shared_buffer value = shared_buffer::copy("hello");
shared_buffer value2 = shared_buffer::copy(std::string_view("world"));

// Or from a byte vector
auto vec = std::vector<uint8_t>{1, 2, 3, 4};
shared_buffer value3 = shared_buffer::make(std::move(vec));

// Set with TTL (60 seconds, in milliseconds)
cache.set("user:42:profile", value, 60000);

// Set with no expiration (ttl = 0)
cache.set("config:theme", value2, 0);

Parameters:

Param	Type	Description
key	std::string	The cache key. Convention: "entity:id:field".
value	shared_buffer	The value to store.
ttl_ms	uint32_t	Time-to-live in milliseconds. 0 = no expiration.
timestamp	optional<uint64_t>	Custom timestamp for conflict resolution (optional).
clock	map<uuid, uint64_t>	Vector clock for distributed consistency (optional).

Creating a shared_buffer:

Method	Description
shared_buffer::copy(data, size)	Copy raw bytes into a new buffer.
shared_buffer::copy(string)	Copy from a string or string_view.
shared_buffer::make(vector)	Move a byte vector into a buffer.
shared_buffer::make(DetachedBuffer)	Move a FlatBuffers buffer.

---

Getting a Value

get(key) → shared_buffer

Retrieves a value by key. Returns an empty shared_buffer if the key does not exist or has expired.

auto result = cache.get("user:42:profile");

if (!result.empty()) {
    auto str = result.to_string();  // convert to string
    process(result);
} else {
    // Key not found or expired
}

shared_buffer methods:

Method	Description
empty()	Returns true if the buffer is empty (key not found).
data()	Raw pointer to the buffer data.
size()	Buffer size in bytes.
to_string()	Convert to std::string.
as_asio()	Convert to boost::asio::const_buffer.

---

Deleting a Value

remove(key) → bool

Removes a key from the cache. Returns true if the key existed and was removed.

cache.remove("user:42:profile");

---

Cache Metadata

Inspect cache entries without retrieving the full value.

// Get detailed metadata for a key
auto metadata = cache.get_metadata("user:42:profile");
// metadata.key_       — the key name
// metadata.size_      — value size in bytes
// metadata.expires_at_ — expiration timestamp (epoch ms, 0 = no expiry)
// metadata.created_at_ — creation timestamp
// metadata.reads_      — read count
// metadata.read_bytes_ — total bytes read
// metadata.write_bytes_ — total bytes written

// Get expiration time
auto expiration = cache.get_expiration("user:42:profile");

// Get creation time
auto created_at = cache.get_created_at("user:42:profile");

// Get the vector clock for a key (for distributed consistency)
auto clock = cache.get_clock("user:42:profile");

// List all cache keys and their metadata
auto all = cache.get_all_metadata();

---

Cache Operations via State

The state::instance provides cache methods that automatically propagate changes across the mesh network.

auto state = app.get_state();

// These methods broadcast the change to all connected nodes
state->cache_set("key", value, 60000);
state->cache_remove("key");
state->cache_expire("key");

Use these when you need immediate cross-node consistency. The local cache.set()/cache.remove() only affect the local node's cache.