Extracting Matrix SDK into a Rust WASM Library

The Monolith Problem in Early Prototypes

When building an ambitious application, it is tempting to put all code into a single repository. In early iterations of Vigilant, the Rust Matrix SDK integration was tightly coupled with application-specific state handlers and UI glue code.

As the project grew, this coupling created several friction points:

• Testing the Matrix SDK integration independently from application UI state was difficult.
• Changes to the frontend interface required touching deep backend Matrix sync loops.
• Reusing the Matrix integration in another web client or tool was impossible without copy-pasting code.

I realized that Matrix client integration is fundamentally an independent concern. That realization led to extracting the Rust integration code into a standalone, reusable library: matrix-sdk-bridge.

---

Why WebAssembly for Matrix Client Logic?

The Matrix client ecosystem has robust native implementations, with matrix-sdk in Rust being one of the most active and feature-complete SDKs available.

By compiling Rust to WebAssembly target wasm32-unknown-unknown via wasm-bindgen, we get several advantages:

1. Memory Safety & Correctness: Rust's type system ensures data race safety, strict lifetime checks, and zero-cost abstractions inside the browser environment.
2. Upstream Alignment: We leverage official, audited Matrix Rust SDK crates directly rather than reimplementing protocol handling in JavaScript.
3. Clean Architectural Boundary: WebAssembly exposes a clear ABI (Application Binary Interface). JavaScript handles UI rendering while WebAssembly handles protocol state, cryptographic sessions, and timeline synchronization.

---

Designing the WASM Bridge Interface

Bridging Rust async types (Future, Stream, tokio/wasm-bindgen-futures) to JavaScript promises requires careful API design.

Here is a simplified architectural view of how data flows across the WASM boundary:

┌───────────────────────────────────────┐
│     JavaScript Application / UI       │
└───────────────────┬───────────────────┘
                    │  call async WASM methods (e.g. client.login())
                    ▼
┌───────────────────────────────────────┐
│     wasm-bindgen Export Layer         │
│  - JsValue serialization              │
│  - Future -> Promise conversion       │
└───────────────────┬───────────────────┘
                    │  Rust async calls
                    ▼
┌───────────────────────────────────────┐
│       matrix-sdk (Rust Crates)        │
│  - Room handling                      │
│  - Sync loops                         │
│  - Session state                      │
└───────────────────────────────────────┘

Key Design Principles:

1. Hide Upstream Complexity: Upstream matrix-sdk exposes dozens of types (Client, Room, Timeline, SyncResponse). The bridge packages these into high-level, serializable JS structures.
2. Explicit Event Passing: Matrix live sync updates are passed across the WASM boundary using JS callbacks or event dispatchers.
3. Graceful Error Handling: Rust Result<T, E> types are converted to structured JavaScript errors rather than panicking inside the WebAssembly module.

---

Lessons Learned

• Decoupling Accelerates Iteration: Once matrix-sdk-bridge was extracted, developing the frontend became significantly cleaner. The frontend team can mock or consume WASM methods without needing to touch Rust code.
• WASM Memory Management Matters: Passing large byte arrays or string structures continuously across the JS/WASM boundary can introduce garbage collection overhead. Using lightweight JSON or typed array structures minimizes serialization overhead.
• Treat Internal Tooling as Open Source: Even if a library starts as part of an internal project, structuring it like an open-source package forces cleaner abstractions, better documentation, and higher code quality.

In the next post, I will share the process of packaging this Rust WebAssembly bridge and publishing it to npm as @seucra/matrix-sdk-bridge.