Crate kora_embedded 

kora-embedded

Embeddable library mode for the Kōra cache engine.

This crate provides Database, a high-level API for using Kōra as an in-process library rather than a standalone network server. It wraps the same multi-threaded ShardEngine that powers kora-server, but eliminates all network overhead: commands are serialised into the engine’s internal Command enum and dispatched through per-shard channels directly from the calling thread.

How it works

Each Database instance owns a ShardEngine with a configurable number of shard worker threads. Keys are hashed to a shard, and the corresponding command is sent over an mpsc channel to that shard’s worker. The calling thread blocks on a oneshot channel until the worker replies, giving synchronous semantics with lock-free, shared-nothing execution on the data path.

Embedded vs. server mode

Aspect	kora-embedded	kora-server
Transport	Direct function calls	TCP / Unix socket (RESP2)
Latency	Sub-microsecond dispatch	Network round-trip
Deployment	Linked into your binary	Separate process
Protocol	Rust types (Command / CommandResponse)	Wire-compatible RESP2

Hybrid mode

With the server Cargo feature enabled, [Database::start_listener] spawns a TCP server alongside the embedded instance, allowing external clients to connect while the host process retains direct API access.

Quick start

use kora_embedded::{Config, Database};

let db = Database::open(Config::default());
db.set("greeting", b"hello world");
assert_eq!(db.get("greeting"), Some(b"hello world".to_vec()));

Structs

Config

Configuration for opening an embedded Database.

Database

An embedded Kōra database instance.

Type Aliases

DocCollectionConfig

Configuration for creating or updating a document collection.

DocCollectionInfo

Metadata snapshot for a document collection (document count, field count, etc.).

DocDictionaryInfo

Statistics about a collection’s internal dictionary (term counts, memory usage).

DocInsertResult

Result of a Database::doc_insert call with an auto-generated document ID.

DocSetResult

Outcome of a Database::doc_set call, indicating whether the document was created or replaced.

DocStorageInfo

Statistics about a collection’s packed storage layer (byte counts, compaction state).

DocUpdateMutation

A single field-level mutation applied by Database::doc_update.