Crate wombatkv 

C ABI for WombatKV’s KV store. Companion to include/wombatkv.h.

Build: cargo build -p wombatkv-cabi --release produces target/release/libwombatkv.dylib (macOS) or .so (Linux).

All extern “C” functions are wrapped in catch_unwind so a Rust panic on the puffer side never propagates into the C caller.

All pointer-handling unsafe blocks are isolated to the ffi submodule with audit comments. The rest of this crate is safe code.

Re-exports

pub use config::CabiConfig;

Modules

config

Centralized cabi (embedded + remote-client) configuration.

Structs

Handle

Public Rust handle. The cdylib hands an opaque wmbt_kv_handle_t* to C; we cast it back to &Handle on every call.

wmbt_kv_borrow

Opaque borrow handle returned by the zero-copy *_borrowed getter functions. The C caller treats it as an opaque cookie and passes it back to wmbt_kv_release_borrow when done reading the payload.

wmbt_kv_handle

Opaque handle (named wmbt_kv_handle in the C header).

Constants

ABI_MAJOR

ABI major version. Bump on backwards-incompatible C ABI changes.

ABI_MINOR

ABI minor version. Bump on backwards-compatible C ABI extensions.

Functions

wmbt_kv_abi_version

Pack ABI version as (major << 16) | minor.

wmbt_kv_blake3_64hex

Compute a 64-hex-char (32-byte) blake3 digest of the input. Output buffer MUST be at least 65 bytes (64 hex chars + NUL terminator).

wmbt_kv_crc32c

One-shot CRC32C (Castagnoli polynomial) over in_len bytes at in_ptr. Equivalent to wmbt_kv_crc32c_append(0, in_ptr, in_len).

wmbt_kv_crc32c_append

Append in_len bytes at in_ptr to a running CRC32C accumulator and return the new accumulator value. Use to chain multiple buffers into a single CRC32C without forcing the caller to materialise them contiguously. crc is the accumulator from the previous call (or 0 to start fresh).

wmbt_kv_free

Release a handle constructed by wmbt_kv_init_from_env. Safe to pass NULL.

wmbt_kv_get_kv_blocks_borrowed

Parallel GET for a batch of content-addressed blocks.

wmbt_kv_get_raw_tail_borrowed

GET a raw-tail sidecar payload with borrow semantics. Mirrors wmbt_kv_get_kv_borrowed shape.

wmbt_kv_init_from_env

Construct a handle from environment variables. Returns NULL on error; inspect wmbt_kv_last_error() for the message.

wmbt_kv_last_error

Returns the most recent thread-local error message, or NULL.

wmbt_kv_lookup_block_prefix

Walk a chain of block hashes and report how many leading hashes are present in the in-memory metadata index.

wmbt_kv_open_http

Construct an HTTP-backed handle for the given addr (“host:port”, NUL-terminated). Daemon side must be running wombatkv-daemon --http <addr>. Equivalent to setting WMBT_KV_HTTP_ADDR=<addr> in the env and calling wmbt_kv_init_from_env but lets engines pick HTTP without mutating env vars.

wmbt_kv_open_tcp

Construct a handle that talks to a remote wombatkv-daemon over TCP. addr is a NUL-terminated “host:port” string (e.g. "203.0.113.5:7878"). The daemon must be running with wombatkv-daemon --tcp <addr>.

wmbt_kv_put_kv_blocks

Parallel PUT for a batch of content-addressed blocks.

wmbt_kv_put_raw_tail

PUT a raw-tail sidecar payload keyed by chain_tip_hash_hex (64-char lower-hex blake3 digest of the LAST block in the saved chain).

wmbt_kv_release_borrow

Release a borrow obtained from any of the *_borrowed functions (wmbt_kv_get_kv_blocks_borrowed, wmbt_kv_get_raw_tail_borrowed). Safe to pass NULL.