oxistore — The COOLJAPAN Pure-Rust storage facade

oxistore is the top-level facade crate for the OxiStore storage stack. It re-exports the core traits from oxistore-core and provides a small set of open* functions that return a Box<dyn KvStore> backed by a feature-selected engine — so callers depend on one crate and one trait, and swap storage engines by flipping a Cargo feature. Every backend is 100% Pure Rust: no C/C++/Fortran libraries are required.

The facade also gathers the optional OxiStore layers — columnar (Parquet/Arrow), blob, cache, encryption, and compression — behind feature flags, re-exporting each behind a dedicated module so the whole stack is reachable from a single dependency.

Installation

[dependencies]
# Default: redb B-tree backend
oxistore = "0.1.0"

# sled backend
oxistore = { version = "0.1.0", default-features = false, features = ["kv-sled"] }

# fjall LSM-tree backend
oxistore = { version = "0.1.0", default-features = false, features = ["kv-fjall"] }

# All KV backends + cache + blob + columnar
oxistore = { version = "0.1.0", features = ["kv-redb", "kv-sled", "kv-fjall", "cache", "blob", "columnar"] }

Quick Start

use oxistore::{open, KvStore};

fn main() -> Result<(), oxistore::StoreError> {
    // Opens the default backend (redb) at the given path.
    let store = open("/tmp/my-oxistore")?;

    store.put(b"hello", b"world")?;
    let val = store.get(b"hello")?;
    assert_eq!(val.as_deref(), Some(b"world".as_ref()));
    Ok(())
}

Selecting a backend explicitly

use oxistore::{open_with, open_in_memory, StoreKind, KvStore};

// Pick the engine at runtime.
let redb_store  = open_with(StoreKind::Redb,  "/tmp/db.redb")?;
let sled_store  = open_with(StoreKind::Sled,  "/tmp/db-sled")?;
let fjall_store = open_with(StoreKind::Fjall, "/tmp/db-fjall")?;

// Ephemeral in-memory store (per-backend semantics).
let scratch = open_in_memory(StoreKind::Redb)?;
# Ok::<(), oxistore::StoreError>(())

Feature Flags

default = ["kv-redb"]. The facade is feature-driven: each backend or layer is pulled in only when its flag is enabled, and the open* functions return StoreError::Other("<feature> not enabled") for a backend whose feature is absent.

Backend Selection

StoreKind — KV engine selector

Backend — unified backend discriminant

A wider enum for runtime introspection/logging, covering KV, columnar, blob, and cache engines: KvRedb, KvSled, KvFjall, Columnar, BlobLocal, BlobMemory, Cache. From<StoreKind> for Backend maps each KV StoreKind to its Backend variant.

API Overview

Opening a KV store

In-memory semantics per backend: Redb uses InMemoryBackend; Sled uses Config::temporary(true); Fjall creates a unique temp directory under std::env::temp_dir().

Store management

Optional layers (feature-gated functions)

CachedKvStore is a type alias for the cache-wrapped store returned by open_cached; BoxStoreAdapter is the public newtype that lets a Box<dyn KvStore> be wrapped by the cache layer.

Re-exported core API

KvStore, KvTxn, and KvSnapshot are the central traits — see oxistore-core for their full method tables. The following items are re-exported at the crate root:

Backend & layer modules

Each backend and optional layer is re-exported behind a feature-gated module:

Prelude

use oxistore::prelude::*;

Imports open, open_in_memory, open_with, Backend, StoreError, StoreKind, and the KvStore / KvTxn / KvSnapshot traits. Feature-gated additions: ArcCache / LruCache (cache); BlobMeta / LocalBlobStore / MemoryBlobStore (blob); ColumnarTable (columnar); EncryptedKv (encrypt); the typed-KV adapter types (serde-typed).

Error Handling

Every fallible function returns oxistore_core::StoreError. Notable facade-level uses: requesting a backend whose feature is not compiled in returns StoreError::Other; writing through a read-only store returns StoreError::ReadOnly; filesystem failures in destroy/detect_backend return StoreError::Io. See oxistore-core for the complete StoreError variant table.

Related Crates

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)