Crate wombatkv_daemon

Expand description

Shared-memory ping-pong transport for the wombatkv puffer daemon.

Two POSIX SHM disruptor rings (req + resp) carry typed rkyv-encoded messages between an inference engine (client) and a long-running daemon process holding a wombatkv_node::embed::WombatKVKvStore.

§Design choices (v1)

Right-sized frames plus client chunking. AlignedFixedFrame<DATA_BYTES> is sized for low-millisecond KV chunks, while RemoteKvStoreClient chunks larger engine payloads behind its public put_kv/get_kv API.
Tiered ops. This crate handles control + small-payload ops (PING, PUT_SMALL, GET_SMALL, EXISTS, STATS, RESTORE, CLEAR). For payloads larger than the per-frame budget are stored as chunk objects plus a tiny manifest. The daemon remains a simple key/value server.
rkyv codec. Zero-alloc encode (AlignedVec) on the producer side; on the consumer side messages are decoded into owned types for ergonomics. Switching to recv_leased for archived-view access is a one-line change once the larger-payload path lands.

§Frame budget

DATA_BYTES = 4 MiB - 16 so each ring slot fits a multi-MiB rkyv-encoded payload. With ring depth 16 that’s about 64 MiB per ring, 128 MiB for the full request+response pair. Acceptable on an RTX dev host and large enough to avoid tens of thousands of tiny chunks for real KV blobs.

Re-exports§

pub use arena::arena_path;
pub use arena::ArenaError;
pub use arena::ArenaReader;
pub use arena::ArenaWriter;
pub use arena::ARENA_HEADER_BYTES;
pub use arena::DEFAULT_ARENA_BYTES;
pub use client::ClientOptions;
pub use client::RemoteError;
pub use client::RemoteGetOutcome;
pub use client::RemoteHitTier;
pub use client::RemoteKvStoreClient;
pub use client::DEFAULT_CALL_TIMEOUT;
pub use config::DaemonConfig;
pub use lifecycle::cleanup_prefix_segments;
pub use lifecycle::ClientHeartbeat;
pub use lifecycle::HeartbeatMonitor;
pub use lifecycle::ReopenReason;

Modules§

arena: Shared mmap arena for the future zero-copy KV transfer.
client: Remote KV-store client over the SHM ring transport.
config: Centralized daemon configuration.
constants: Named magic-number constants for the daemon binary.
envelope: RFC 0018 universal wire envelope for daemon TCP + HTTP transports.
http_transport: HTTP/1.1 + rkyv transport for the WombatKV daemon.
lifecycle: Client lifecycle helpers for SHM prefix recovery.
op: Wire op codes. Encoded as u8 (struct fields) to side-step rkyv’s enum derive constraints, we want plain field traversal on the hot path, not match dispatch.
runtime_tpc: TPC (thread-per-core) runtime scaffolding for the wombatkv daemon.
status: Wire status codes (see op for design rationale).
tcp_transport: Length-prefixed rkyv-over-TCP transport for the WombatKV daemon.

Structs§

ArchivedGetKvBlocksBatchReq: An archived GetKvBlocksBatchReq
ArchivedGetKvBlocksBatchResp: An archived GetKvBlocksBatchResp
ArchivedLookupBlockPrefixReq: An archived LookupBlockPrefixReq
ArchivedLookupBlockPrefixResp: An archived LookupBlockPrefixResp
ArchivedPutKvBlocksBatchReq: An archived PutKvBlocksBatchReq
ArchivedPutKvBlocksBatchResp: An archived PutKvBlocksBatchResp
ArchivedWireRequest: An archived WireRequest
ArchivedWireResponse: An archived WireResponse
GetKvBlocksBatchReq: Request payload for op::GET_KV_BLOCKS_BATCH.
GetKvBlocksBatchReqResolver: The resolver for an archived GetKvBlocksBatchReq
GetKvBlocksBatchResp: Response payload for op::GET_KV_BLOCKS_BATCH.
GetKvBlocksBatchRespResolver: The resolver for an archived GetKvBlocksBatchResp
LookupBlockPrefixReq: Request payload for op::LOOKUP_BLOCK_PREFIX.
LookupBlockPrefixReqResolver: The resolver for an archived LookupBlockPrefixReq
LookupBlockPrefixResp: Response payload for op::LOOKUP_BLOCK_PREFIX.
LookupBlockPrefixRespResolver: The resolver for an archived LookupBlockPrefixResp
PutKvBlocksBatchReq: Request payload for op::PUT_KV_BLOCKS_BATCH.
PutKvBlocksBatchReqResolver: The resolver for an archived PutKvBlocksBatchReq
PutKvBlocksBatchResp: Response payload for op::PUT_KV_BLOCKS_BATCH.
PutKvBlocksBatchRespResolver: The resolver for an archived PutKvBlocksBatchResp
WireRequest: rkyv-archivable wire request.
WireRequestResolver: The resolver for an archived WireRequest
WireResponse: rkyv-archivable wire response.
WireResponseResolver: The resolver for an archived WireResponse

Enums§

WireCodecError: Typed error for the daemon’s wire-codec helpers (encode/decode/ validate). Replaces ad-hoc Result<T, String> in the daemon’s codec surface. Named WireCodecError to avoid shadowing myelon::codec::CodecError (which we import at the top of this file for the typed-transport surface).

Constants§

ATTACH_TIMEOUT: Default attach timeout for SHM segments (matches perf-bench).
DEFAULT_RING_DEPTH: Disruptor ring depth: N in-flight slots. Total ring footprint per direction = depth × FRAME_DATA_BYTES = 1 MiB.
FRAME_DATA_BYTES: Per-frame data budget. 4 MiB minus 16-byte header.
REQ_CONSUMER_ID: Consumer id on the request ring (daemon side). Kept tiny because macOS POSIX SHM caps segment names at 31 chars; the consumer cursor segment appends this id to the ring name.
RESP_CONSUMER_ID: Consumer id on the response ring (client side).

Functions§

decode_bytes_batch: Decode an ordered payload batch without copying individual payloads.
decode_get_kv_blocks_batch_req
decode_get_kv_blocks_batch_resp
decode_key_batch: Decode an ordered key list encoded by encode_key_batch.
decode_lookup_block_prefix_req
decode_lookup_block_prefix_resp
decode_put_kv_blocks_batch_req
decode_put_kv_blocks_batch_resp
effective_attach_timeout: Resolves the effective SHM attach timeout from WMBT_KV_DAEMON_SHM_ATTACH_TIMEOUT_SECS env, falling back to ATTACH_TIMEOUT. Useful for slow Docker startup ops or CI runners where the daemon takes longer to bring up SHM segments.
encode_bytes_batch: Encode ordered payload bytes for a batched GET response.
encode_get_kv_blocks_batch_req
encode_get_kv_blocks_batch_resp
encode_key_batch: Encode an ordered key list for the daemon batched GET control path.
encode_lookup_block_prefix_req: rkyv-encode a LookupBlockPrefixReq for WireRequest.payload.
encode_lookup_block_prefix_resp: rkyv-encode a LookupBlockPrefixResp for WireResponse.payload.
encode_put_kv_blocks_batch_req
encode_put_kv_blocks_batch_resp
fits_one_frame: Returns true when a payload of len bytes fits in a single frame (after rkyv envelope overhead, uses a conservative 256-byte budget).
open_client: Open the client side of the ring pair: req-producer + resp-consumer.
open_daemon: Open the daemon side of the ring pair: req-consumer + resp-producer.
segment_names: Build the request and response SHM segment names for a daemon prefix. The format is wk<prefix>r and wk<prefix>s (no underscores) so the names stay short enough that disruptor-mp’s per-ring auxiliary segments (notably <base>_producer_seq) still fit the macOS POSIX-SHM 31-char budget.
validate_segment_name_budget: Validate that the SHM segment names derived from prefix, including the longest disruptor-mp auxiliary segment (<base>_producer_seq) - will fit the macOS POSIX-SHM 31-char budget. Returns a clear, actionable error so daemon and client both fail loud at startup instead of letting the OS surface a cryptic ENAMETOOLONG (errno 63) (or worse, a Shared segment not found after thousands of retries - see RFC 0011 P10 / the 2026-05-18 macOS DST-sweep regression).

Type Aliases§

ShmFrame: The frame type backing both rings.