Sameh Abouelsaad
cea2d7e655
- Remove hardcoded dependencies in kvstore Cargo.toml; use features instead. This allows for more flexible compilation for different targets (native vs. WASM). - Improve logging in vault crate using the `log` crate. This makes debugging easier and provides more informative output during execution. Native tests use `env_logger`, WASM tests use `console_log`. - Update README to reflect new logging best practices. - Add cfg attributes to native and wasm modules to improve clarity. - Update traits.rs to specify Send + Sync behavior expectations.
86 lines
3.5 KiB
Markdown
86 lines
3.5 KiB
Markdown
# Plan: Ensuring Native and WASM Builds Work for the Vault/KVStore System
|
|
|
|
## Purpose
|
|
This document outlines the steps and requirements to guarantee that both native (desktop/server) and WASM (browser) builds of the `vault` and `kvstore` crates work seamlessly, securely, and efficiently.
|
|
|
|
---
|
|
|
|
## 1. Architecture Principles
|
|
- **Async/Await Everywhere:** All APIs must be async and runtime-agnostic (no Tokio requirement in library code).
|
|
- **KVStore Trait:** Use an async trait for storage, with platform-specific implementations (sled for native, IndexedDB/idb for WASM).
|
|
- **Conditional Compilation:** Use `#[cfg(target_arch = "wasm32")]` and `#[cfg(not(target_arch = "wasm32"))]` to select code and dependencies.
|
|
- **No Blocking in WASM:** All I/O and crypto operations must be async and non-blocking in browser builds.
|
|
- **WASM-Compatible Crypto:** Only use crypto crates that compile to WASM (e.g., `aes-gcm`, `chacha20poly1305`, `k256`, `rand_core`).
|
|
- **Separation of Concerns:** All encryption and password logic resides in `vault`, not `kvstore`.
|
|
- **Stateless and Session APIs:** Provide both stateless (context-passing) and session-based APIs in `vault`.
|
|
|
|
---
|
|
|
|
## 2. Cargo.toml and Dependency Management
|
|
- **Native:**
|
|
- `[target.'cfg(not(target_arch = "wasm32"))'.dependencies]`
|
|
- `tokio` (with only supported features)
|
|
- `sled`
|
|
- **WASM:**
|
|
- `[target.'cfg(target_arch = "wasm32")'.dependencies]`
|
|
- `idb`
|
|
- `wasm-bindgen`, `wasm-bindgen-futures`
|
|
- **Crypto:**
|
|
- Only include crates that are WASM-compatible for both targets.
|
|
- **No unconditional `tokio`** in `vault` or `kvstore`.
|
|
|
|
---
|
|
|
|
## 3. Code Organization
|
|
- **KVStore Trait:**
|
|
- Define as async trait (using `async_trait`).
|
|
- Implement for sled (native) and idb (WASM), using `#[cfg]`.
|
|
- **Vault:**
|
|
- All persistence must go through the KVStore trait.
|
|
- All cryptography must be WASM-compatible.
|
|
- No direct file or blocking I/O in WASM.
|
|
- **Runtime:**
|
|
- Only use `tokio` in binaries or native-specific code.
|
|
- In WASM, use `wasm-bindgen-futures::spawn_local` for async tasks.
|
|
|
|
---
|
|
|
|
## 4. Platform-Specific Guidelines
|
|
- **Native (Desktop/Server):**
|
|
- Use `sled` for storage.
|
|
- Use `tokio::task::spawn_blocking` for blocking I/O if needed.
|
|
- All async code should work with any runtime.
|
|
- **WASM (Browser):**
|
|
- Use `idb` crate for IndexedDB storage.
|
|
- All code must be non-blocking and compatible with the browser event loop.
|
|
- Use `wasm-bindgen` and `wasm-bindgen-futures` for JS interop and async.
|
|
- Expose APIs with `#[wasm_bindgen]` for JS usage.
|
|
|
|
---
|
|
|
|
## 5. Testing
|
|
- **Native:** `cargo test`
|
|
- **WASM:** `cargo test --target wasm32-unknown-unknown --release` (or use `wasm-pack test`)
|
|
- **Separate tests** for native and WASM backends in `tests/`.
|
|
|
|
---
|
|
|
|
## 6. Checklist for Compliance
|
|
- [ ] No unconditional `tokio` usage in library code
|
|
- [ ] All dependencies are WASM-compatible (where needed)
|
|
- [ ] All storage goes through async KVStore trait
|
|
- [ ] No blocking I/O or native-only APIs in WASM
|
|
- [ ] All cryptography is WASM-compatible
|
|
- [ ] Both stateless and session APIs are available in `vault`
|
|
- [ ] All APIs are async and runtime-agnostic
|
|
- [ ] Native and WASM tests both pass
|
|
|
|
---
|
|
|
|
## 7. References
|
|
- See `docs/Architecture.md`, `docs/kvstore-vault-architecture.md`, and `docs/vault_impl_plan.md` for architectural background and rationale.
|
|
|
|
---
|
|
|
|
By following this plan, the codebase will be robust, portable, and secure on both native and browser platforms, and will adhere to all project architectural guidelines.
|