Compare-and-swap write at key in namespace: apply value (with optional
expiry) only if expect holds, else fail with
KvError::VersionConflict. The swap half of optimistic concurrency, paired
with KvEntry::version as the compare token.
Fenced compare-and-swap: the KvCas write and precondition, applied only
while the task’s fence sequence still equals fence_token (the at-most-one
effective-writer gate). A failed fence maps to KvError::LeaseLost, a failed
precondition to KvError::VersionConflict. Additive over
crate::codes::KV_OP_VERSION 1.
Request to copy the value at key to to_key (optionally into another
namespace via to_namespace) in a single backend transaction. Committed
on success, NotFound when the source is absent. The destination is
overwritten (a guarded copy composes exists + cas instead).
Request to remove key from namespace. With if_match set to a version,
the delete applies only when the live version matches (a conditional delete),
returning KvError::VersionConflict otherwise.
Request to bulk-delete entries in namespace matching the same composed
bounds as a scan (prefix/start/end/key_contains). With no bounds it
clears the whole namespace. No limit/cursor, and expiry is ignored (a
matching expired entry is removed too).
One stored entry: an arbitrary-bytes key and value plus optional expiry. The
key and value are owned Vec<u8>, so the public API never leaks the bytes
crate, and they ride the wire as CBOR byte strings, byte-exact.
Request to test presence and read metadata without the value. The cheap way
to check a precondition before transferring a large value (the formal
EXISTS primitive).
Request to set, refresh, or clear a key’s expiry in place without rewriting
its value. expires_at_micros of None clears the expiry (the formal
EXPIRE primitive).
Request to read the value at key in namespace. With if_none_match set to
a version, the read returns KvOutcome::NotModified instead of the value
when the live version matches (a conditional GET), so an up-to-date cache
skips the body transfer.
Request to acquire an advisory lease (a bounded-TTL distributed lock) on
key. On success the holder gets a lease_token to present on protected
mutations (the formal LEASE primitive). Built on compare-and-swap.
Request to apply a merge patch to a structured value without transferring the
whole object. patch is a codec-specific patch document (the content_type
names the format). With if_match set, the patch applies only at that version
(the formal PATCH primitive).
Request to list entries in namespace. With no bounds it lists the whole
namespace. prefix matches keys that start with it in byte order. start
and end bound an inclusive-start, exclusive-end key range. key_contains
keeps only keys that are valid UTF-8 and contain the substring (binary keys
are skipped). All bounds compose.
The memory scope a read-view row carries, stamped by the fold from the
record’s headers so recall reconstructs a memory item and narrows by scope.
Absent on a generic key-value entry, which carries no scope.
The precondition a KvCas write must satisfy to apply. The compare half
of compare-and-swap: lock-free optimistic concurrency for callers contending
on one key.
The canonical namespace rule, shared by the SDK client edge and every
serving tier: non-empty, at most MAX_NAMESPACE_BYTES bytes, no ASCII
control characters. The charset is otherwise open, so /-style hierarchy
stays legal. The bound is a size and sanity cap, not a safelist.