samehabouelsaad/sal-modular
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
791752c3a5
sal-modular/docs/build_instructions.md

3.5 KiB
Raw Blame History

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: wasm-pack test --headless --firefox (or --chrome) inside the crate directory
  • 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.