[GH-ISSUE #1809] [RFC]: Detailed Step-by-Step Plan to Integrate Mooncake Store into Dynamo KVCM with Native Rust API #519

New issue

Closed

opened 2026-10-29 21:15:48 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 21:15:48 +00:00

Owner

Originally created by @stmatengss on GitHub (Apr 2, 2026).
Original GitHub issue: https://github.com/kvcache-ai/Mooncake/issues/1809

Originally assigned to: @stmatengss, @Copilot on GitHub.

Changes proposed

Motivation

Integrate Mooncake store with Dynamo KVCM by providing an official Rust API for Mooncake. This enables direct, safe, and efficient usage of the Mooncake store from the Rust-based Dynamo system, without FFI workarounds. This RFC provides a step-by-step and code-level plan to achieve robust, maintainable integration.

Step-by-Step & Code-Level Plan

1. Scope Alignment & Requirements

Identify key Dynamo KVCM requirements (API signatures, async support, error types, lifetime management, etc.).
Survey current Mooncake C++ APIs for coverage and extensibility. Document feature gaps.

2. Designing the Rust API

Define the minimal Rust interface required by Dynamo KVCM (trait KvBackend):

#[async_trait::async_trait]
pub trait KvBackend {
    async fn put(&self, key: &[u8], value: &[u8], opts: PutOptions) -> Result<(), KvError>;
    async fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>, KvError>;
    async fn batch_get(&self, keys: &[&[u8]]) -> Result<Vec<Option<Vec<u8>>>, KvError>;
    async fn delete(&self, key: &[u8]) -> Result<(), KvError>;
}

Define PutOptions, KvError, and other necessary Rust-side types to match Mooncake semantics.

3. Expose CXX/Rust Bridge in Mooncake

In Mooncake (C++):

Use cxx crate to declare and implement Rust FFI bridges directly in the C++ codebase.

Example header (mooncake_store_ffi.rs):

#[cxx::bridge]
mod ffi {
  unsafe extern "C++" {
    include!("mooncake/store.h");

    type Store;

    fn new_store(path: &str) -> Result<Box<Store>>;
    fn put(self: &Store, key: &[u8], value: &[u8], opts: &PutOptions) -> Result<()>;
    fn get(self: &Store, key: &[u8]) -> Result<Option<Vec<u8>>>;
    fn delete(self: &Store, key: &[u8]) -> Result<()>;
    // add more methods as needed
  }
}

Implement corresponding C++ methods, ensuring exception handling matches Rust Result semantics.

4. Native Rust Wrapper (mooncake-rs crate)

Create crate under bindings/rust/ in Mooncake repo (mooncake-rs).

Wrap CXX-exposed types with idiomatic, async Rust API:

pub struct MooncakeStore {
    inner: Box<ffi::Store>,
}
// Implement KvBackend for MooncakeStore

Provide lifetime and ownership guarantees (Arc, Mutex if needed for safety across threads).
Document usage and error handling for users.

5. Wire into Dynamo

Implement KvBackend for MooncakeStore in Dynamo:

impl KvBackend for MooncakeStore { /* Forward calls to ffi-generated methods */ }

Add feature flag to Dynamo to toggle between Mooncake and other backends.
Provide test suite for integration.

6. End-to-End Testing & Docs

Demonstrate from Rust main() sample (can build/run under examples/):

#[tokio::main]
async fn main() {
    let store = MooncakeStore::new("/mnt/kvdata").unwrap();
    store.put(b"foo", b"bar", Default::default()).await.unwrap();
    let v = store.get(b"foo").await.unwrap();
    println!("Value for foo: {:?}", v);
}

Document build instructions (Rust toolchain + C++ dependencies) and troubleshooting FAQ.

Contributor Tasks

Design and discuss Rust API and CXX bridge in Mooncake.
Implement and test CXX bridge and Rust wrapper (mooncake-rs).
Integrate into Dynamo KVCM; contribute test coverage and migration docs.

References

Thanks for contributing 🎉!

Before submitting a new issue...

Make sure you already searched for relevant issues and read the documentation

Originally created by @stmatengss on GitHub (Apr 2, 2026). Original GitHub issue: https://github.com/kvcache-ai/Mooncake/issues/1809 Originally assigned to: @stmatengss, @Copilot on GitHub. ### Changes proposed ## Motivation Integrate Mooncake store with Dynamo KVCM by providing an official Rust API for Mooncake. This enables direct, safe, and efficient usage of the Mooncake store from the Rust-based Dynamo system, without FFI workarounds. This RFC provides a step-by-step and code-level plan to achieve robust, maintainable integration. ## Step-by-Step & Code-Level Plan ### 1. Scope Alignment & Requirements - Identify key Dynamo KVCM requirements (API signatures, async support, error types, lifetime management, etc.). - Survey current Mooncake C++ APIs for coverage and extensibility. Document feature gaps. ### 2. Designing the Rust API - Define the minimal Rust interface required by Dynamo KVCM (trait `KvBackend`): ```rust #[async_trait::async_trait] pub trait KvBackend { async fn put(&self, key: &[u8], value: &[u8], opts: PutOptions) -> Result<(), KvError>; async fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>, KvError>; async fn batch_get(&self, keys: &[&[u8]]) -> Result<Vec<Option<Vec<u8>>>, KvError>; async fn delete(&self, key: &[u8]) -> Result<(), KvError>; } ``` - Define `PutOptions`, `KvError`, and other necessary Rust-side types to match Mooncake semantics. ### 3. Expose CXX/Rust Bridge in Mooncake - In Mooncake (C++): - Use [cxx](https://cxx.rs/) crate to declare and implement Rust FFI bridges directly in the C++ codebase. - Example header (mooncake_store_ffi.rs): ```rust #[cxx::bridge] mod ffi { unsafe extern "C++" { include!("mooncake/store.h"); type Store; fn new_store(path: &str) -> Result<Box<Store>>; fn put(self: &Store, key: &[u8], value: &[u8], opts: &PutOptions) -> Result<()>; fn get(self: &Store, key: &[u8]) -> Result<Option<Vec<u8>>>; fn delete(self: &Store, key: &[u8]) -> Result<()>; // add more methods as needed } } ``` - Implement corresponding C++ methods, ensuring exception handling matches Rust Result semantics. ### 4. Native Rust Wrapper (mooncake-rs crate) - Create crate under `bindings/rust/` in Mooncake repo (`mooncake-rs`). - Wrap CXX-exposed types with idiomatic, async Rust API: ```rust pub struct MooncakeStore { inner: Box<ffi::Store>, } // Implement KvBackend for MooncakeStore ``` - Provide lifetime and ownership guarantees (Arc, Mutex if needed for safety across threads). - Document usage and error handling for users. ### 5. Wire into Dynamo - Implement `KvBackend` for `MooncakeStore` in Dynamo: ```rust impl KvBackend for MooncakeStore { /* Forward calls to ffi-generated methods */ } ``` - Add feature flag to Dynamo to toggle between Mooncake and other backends. - Provide test suite for integration. ### 6. End-to-End Testing & Docs - Demonstrate from Rust main() sample (can build/run under examples/): ```rust #[tokio::main] async fn main() { let store = MooncakeStore::new("/mnt/kvdata").unwrap(); store.put(b"foo", b"bar", Default::default()).await.unwrap(); let v = store.get(b"foo").await.unwrap(); println!("Value for foo: {:?}", v); } ``` - Document build instructions (Rust toolchain + C++ dependencies) and troubleshooting FAQ. ## Contributor Tasks - Design and discuss Rust API and CXX bridge in Mooncake. - Implement and test CXX bridge and Rust wrapper (`mooncake-rs`). - Integrate into Dynamo KVCM; contribute test coverage and migration docs. ## References - [Mooncake Documentation](https://kvcache-ai.github.io/Mooncake/) - [cxx crate docs](https://cxx.rs/) - [Dynamo Docs](link-to-dynamo-docs) --- Thanks for contributing 🎉! ### Before submitting a new issue... - [ ] Make sure you already searched for relevant issues and read the [documentation](https://kvcache-ai.github.io/Mooncake/)

bsakaguchi closed this issue

2026-10-29 21:15:48 +00:00