Repository navigation
Description
Goal
Compile Minigraf to wasm32-wasip1 (WASI) so it runs inside server-side WASM runtimes — Wasmtime, Wasmer, Cloudflare Workers (WASI), and Fastly Compute — with full file-backed storage and no JavaScript bridge required.
Background
Phase 8.1a handles browser WASM (wasm32-unknown-unknown). This phase is the orthogonal server-side target. WASI exposes a POSIX-like filesystem API (with capability-based access control), so FileBackend should work as-is once the code compiles cleanly to wasm32-wasip1.
No new storage backend is needed. No wasm-bindgen or #[wasm_bindgen] annotations are needed. This is standard Rust compiled to a different target.
Tasks
1. Verify FileBackend under WASI
- Add a
wasm32-wasip1CI job (see below) - Compile with
cargo build --target wasm32-wasip1 --release - Fix any compilation errors — common causes:
std::threadusage (WASI has no threads in wasip1)uuidcrate v1 requiresgetrandomwith thewasmfeature; addgetrandom = { version = "0.2", features = ["wasm"] }if needed- Any
#[cfg(unix)]/#[cfg(windows)]guarded code that has no WASM fallback chrono/system clock: Minigraf usessrc/temporal.rsfor UTC timestamps — verify clock access works under WASI or provide a fallback
- Do not create a new storage backend;
FileBackendmust work via WASI's capability filesystem
2. Thread safety audit
WASI p1 does not support threads. Every Arc<Mutex<...>>, RwLock, thread_local!, and std::thread::spawn in code reachable from a wasm32-wasip1 binary must be audited:
- If the code path is only reachable in a multi-threaded native context, gate it with
#[cfg(not(target_arch = "wasm32"))] - If it is reachable from WASI, replace with single-threaded equivalents or confirm it compiles (Rust's WASI target usually supports
Mutex/RwLockas stubs — verify they don't panic at runtime)
3. getrandom / UUID generation
uuid::Uuid::new_v4() calls getrandom. Under wasm32-wasip1, getrandom 0.2 supports WASI natively — verify the dependency chain includes a compatible version. Add an explicit getrandom dependency with the right features only if the transitive version does not support WASI.
4. CI job
Add to .github/workflows/ci.yml:
wasm-wasi:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
with:
targets: wasm32-wasip1
- name: Install Wasmtime
run: |
curl -sSf https://raw.githubusercontent.com/bytecodealliance/wasmtime/main/ci/download-wasmtime-dev.sh | sh
echo "$HOME/.wasmtime/bin" >> $GITHUB_PATH
- name: Build
run: cargo build --target wasm32-wasip1 --release
- name: Smoke test (Wasmtime)
run: |
wasmtime run --dir /tmp target/wasm32-wasip1/release/minigraf.wasm -- \
"(transact [{:db/id \"eid-1\" :name \"Alice\"}])"Also test with Wasmer if feasible:
- name: Install Wasmer
run: curl https://get.wasmer.io -sSfL | sh && echo "$HOME/.wasmer/bin" >> $GITHUB_PATH
- name: Smoke test (Wasmer)
run: wasmer run --dir /tmp target/wasm32-wasip1/release/minigraf.wasm -- \
"(query [:find ?e :where [?e :name _]])"5. REPL binary
The REPL (src/repl.rs, compiled as src/main.rs) should compile and run under WASI:
cargo build --bin minigraf --target wasm32-wasip1 --release
wasmtime run --dir . target/wasm32-wasip1/release/minigraf.wasmInteractive TTY detection (is_terminal()) may behave differently under WASI — the REPL already has TTY-aware prompt suppression. Verify piped input still works:
echo '(transact [{:db/id "e1" :name "Alice"}])' | \
wasmtime run --dir . target/wasm32-wasip1/release/minigraf.wasm6. Documentation
Add docs/wasi.md (or a section in README.md) covering:
- What WASI is and why it matters (sandboxed server-side WASM, no Docker needed)
- Build command:
cargo build --target wasm32-wasip1 --release - How to run with Wasmtime:
wasmtime run --dir <data-dir> minigraf.wasm - Capability model:
--dirgrants access to a directory; without it, file operations will fail - Cloudflare Workers (WASI) and Fastly Compute: note any additional steps or limitations
- Embedding: how to embed the
.wasmbinary in a host application using the Wasmtime or Wasmer embedding API
7. Tests
- The existing test suite does not need to run under WASI (many tests use
tempfilewhich may not be available); a clean compilation + smoke test is sufficient for CI - Add at least one
#[test]that is#[cfg(target_arch = "wasm32")]gated and verifies the in-memory backend works (avoids filesystem dependency):
#[cfg(all(target_arch = "wasm32", test))]
mod wasi_tests {
use super::*;
#[test]
fn in_memory_smoke() {
let db = Minigraf::open_in_memory().expect("open");
db.execute("(transact [{:db/id \"e1\" :name \"hello\"}])").expect("transact");
let r = db.execute("(query [:find ?e :where [?e :name _]])").expect("query");
assert!(!r.is_empty());
}
}Constraints
- Must not break native (
cargo test) or browser (wasm-pack build --features browser) builds FileBackendmust work without modification — if changes are needed, make them additive and conditional- No new runtime dependencies for the native target; WASI-specific deps must be
target.'cfg(target_arch = "wasm32")'.dependencies - Binary size: no hard budget (server-side WASM is less constrained), but avoid gratuitous bloat
Deliverable
cargo build --target wasm32-wasip1 --releasesucceeds with no errors or warnings- Smoke test passes on both Wasmtime and Wasmer in CI
docs/wasi.md(or equivalent README section) documents usage- CI
wasm-wasijob is green on every PR going forward
Testing sign-off
The reviewer will:
- Run
cargo build --target wasm32-wasip1 --releaselocally and confirm it compiles - Run the smoke test under Wasmtime
- Confirm
cargo test(native) still passes - Confirm the new CI job is green
Activity