Skip to content

Phase 8.1b: Server-side WASM support (wasm32-wasip1 / WASI) #130

Closed

Description

@adityamukho

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-wasip1 CI job (see below)
  • Compile with cargo build --target wasm32-wasip1 --release
  • Fix any compilation errors — common causes:
    • std::thread usage (WASI has no threads in wasip1)
    • uuid crate v1 requires getrandom with the wasm feature; add getrandom = { version = "0.2", features = ["wasm"] } if needed
    • Any #[cfg(unix)] / #[cfg(windows)] guarded code that has no WASM fallback
    • chrono/system clock: Minigraf uses src/temporal.rs for UTC timestamps — verify clock access works under WASI or provide a fallback
  • Do not create a new storage backend; FileBackend must 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/RwLock as 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.wasm

Interactive 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.wasm

6. 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: --dir grants 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 .wasm binary 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 tempfile which 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
  • FileBackend must 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

  1. cargo build --target wasm32-wasip1 --release succeeds with no errors or warnings
  2. Smoke test passes on both Wasmtime and Wasmer in CI
  3. docs/wasi.md (or equivalent README section) documents usage
  4. CI wasm-wasi job is green on every PR going forward

Testing sign-off

The reviewer will:

  1. Run cargo build --target wasm32-wasip1 --release locally and confirm it compiles
  2. Run the smoke test under Wasmtime
  3. Confirm cargo test (native) still passes
  4. Confirm the new CI job is green

Activity

  1. ghost added
    enhancementNew feature or request
    on Apr 17, 2026
  2. ghost added
    rustPull requests that update rust code
    on Apr 17, 2026
  3. ghost closed this as completedin #152on Apr 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestrustPull requests that update rust code

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions