Module cache 

OrbitCache — fleet-shared binary K,V cache over the Orbit ring.

This is the raw primitive layer: keys and values are bytes, the shared truth is the fleet ring, and higher layers decide how bytes become application structs or FFI payloads.

V0 shape

Each mutation is one ring frame:

[ op:u8 ][ key_len:u16 LE ][ value_len:u16 LE ][ expires_at_ms:u64 LE ]
[ key bytes ][ value bytes ]

Reads walk the ring backwards and stop at the newest frame for the scoped key. A delete frame shadows older puts. A reset frame shadows older puts/deletes for the cache prefix. An expired put is a miss and also shadows older puts, matching normal cache TTL semantics.

Why no typed values here

orbit-rs is framework-agnostic. It does not know application object models, external cache APIs, FFI values, or serde choices. It only preserves bytes and coarse cache semantics. Typed decode/L1 lives in adapter crates above orbit-rs.

Deferred substrate

V0 stores the value inline in the ring frame, so payloads are small and bounded by the SHM ring payload size. The eventual larger-value shape is ring-as-mutation-log plus an indexed SHM arena. The public byte-oriented API is intended to survive that swap.

Structs

OrbitCache

Fleet-shared binary cache. Cheap to clone.

OrbitCacheEntry

Decoded cache entry returned by OrbitCache::get_entry.

Enums

OrbitCacheRead

Honest read result: either the newest matching frame is a value, or the key is currently absent. epoch is the ring counter of the newest matching frame when one exists, useful for local L1 invalidation.

Constants

CACHE_PAYLOAD_MAX

Cache frame payload limit for V0. On Unix this matches the SHM ring’s fixed slot payload size; non-Unix keeps the same contract so tests and callers do not accidentally rely on unbounded in-memory frames.