Add WASM32 core platform abstractions

This commit adds foundational WASM32 support to matrix-sdk-common by introducing platform-agnostic abstractions for async operations:

- async_lock.rs: WASM32-compatible async RwLock implementation using std::sync primitives with async interface
- stream.rs: WASM32 stream utilities using LocalBoxStream instead of BoxStream
- executor.rs: Enhanced with comprehensive WASM runtime abstraction including WasmRuntimeHandle, unified Handle/Runtime types, and improved JoinError handling
- Dependencies: Added futures-executor for WASM32 and async-compat for non-WASM32 targets

These abstractions enable matrix-rust-sdk to run on both WASM32 and native targets without conditional compilation in consuming code.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: 2 people

Cargo.lock

@@ -27,6 +27,7 @@ assert-json-diff = "2.0.2"
 assert_matches = "1.5.0"
 assert_matches2 = "0.1.2"
 async-rx = "0.1.3"
+async-compat = { git = "https://github.com/element-hq/async-compat", rev = "5a27c8b290f1f1dcfc0c4ec22c464e38528aa591" }
 async-stream = "0.3.5"
 async-trait = "0.1.85"
 as_variant = "1.3.0"

Cargo.toml

@@ -40,6 +40,7 @@ uniffi = { workspace = true, optional = true }
 
 [target.'cfg(target_arch = "wasm32")'.dependencies]
 futures-util = { workspace = true, features = ["channel"] }
+futures-executor = { workspace = true }
 wasm-bindgen-futures = { version = "0.4.33", optional = true }
 gloo-timers = { workspace = true, features = ["futures"] }
 web-sys = { workspace = true, features = ["console"] }
@@ -56,6 +57,7 @@ insta = { workspace = true }
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
 # Enable the test macro.
 tokio = { workspace = true, features = ["rt", "macros"] }
+async-compat = { workspace = true }
 
 [target.'cfg(target_arch = "wasm32")'.dev-dependencies]
 # Enable the JS feature for getrandom.

crates/matrix-sdk-common/Cargo.toml

@@ -0,0 +1,147 @@
+#[cfg(target_arch = "wasm32")]
+use std::sync::{
+    RwLock as StdRwLock, RwLockReadGuard as StdRwLockReadGuard,
+    RwLockWriteGuard as StdRwLockWriteGuard,
+};
+#[cfg(not(target_arch = "wasm32"))]
+pub use tokio::sync::{
+    RwLock as AsyncRwLock, RwLockReadGuard as AsyncRwLockReadGuard,
+    RwLockWriteGuard as AsyncRwLockWriteGuard,
+};
+
+#[cfg(target_arch = "wasm32")]
+use std::{
+    future::Future,
+    pin::Pin,
+    sync::Arc,
+    task::{Context, Poll, Waker},
+};
+
+/// A platform-independent `AsyncRwLock`.
+#[cfg(target_arch = "wasm32")]
+#[derive(Debug)]
+pub struct AsyncRwLock<T> {
+    inner: Arc<StdRwLock<T>>,
+}
+
+#[cfg(target_arch = "wasm32")]
+impl<T: Default> Default for AsyncRwLock<T> {
+    fn default() -> Self {
+        Self { inner: Arc::new(StdRwLock::new(T::default())) }
+    }
+}
+
+#[cfg(target_arch = "wasm32")]
+impl<T> AsyncRwLock<T> {
+    /// Create a new `AsyncRwLock`.
+    pub fn new(value: T) -> Self {
+        Self { inner: Arc::new(StdRwLock::new(value)) }
+    }
+
+    /// Acquire a read lock asynchronously.
+    pub async fn read(&self) -> AsyncRwLockReadGuard<'_, T> {
+        AsyncRwLockReadFuture { lock: &self.inner, waker: None }.await
+    }
+
+    /// Acquire a write lock asynchronously.
+    pub async fn write(&self) -> AsyncRwLockWriteGuard<'_, T> {
+        AsyncRwLockWriteFuture { lock: &self.inner, waker: None }.await
+    }
+}
+
+#[cfg(target_arch = "wasm32")]
+/// A future for acquiring a read lock.
+struct AsyncRwLockReadFuture<'a, T> {
+    lock: &'a StdRwLock<T>,
+    waker: Option<Waker>,
+}
+
+#[cfg(target_arch = "wasm32")]
+impl<'a, T> Future for AsyncRwLockReadFuture<'a, T> {
+    type Output = AsyncRwLockReadGuard<'a, T>;
+
+    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
+        // Store the waker so we can wake the task if needed
+        self.waker = Some(cx.waker().clone());
+
+        // Try to acquire the read lock - this is a non-blocking operation in wasm
+        match self.lock.try_read() {
+            Ok(guard) => Poll::Ready(AsyncRwLockReadGuard { guard }),
+            Err(_) => {
+                // In a true async environment we would register a waker to be notified
+                // when the lock becomes available, but in wasm we'll just yield to
+                // the executor and try again next time.
+                cx.waker().wake_by_ref();
+                Poll::Pending
+            }
+        }
+    }
+}
+
+#[cfg(target_arch = "wasm32")]
+/// A future for acquiring a write lock.
+struct AsyncRwLockWriteFuture<'a, T> {
+    lock: &'a StdRwLock<T>,
+    waker: Option<Waker>,
+}
+
+#[cfg(target_arch = "wasm32")]
+impl<'a, T> Future for AsyncRwLockWriteFuture<'a, T> {
+    type Output = AsyncRwLockWriteGuard<'a, T>;
+
+    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
+        // Store the waker so we can wake the task if needed
+        self.waker = Some(cx.waker().clone());
+
+        // Try to acquire the write lock - this is a non-blocking operation in wasm
+        match self.lock.try_write() {
+            Ok(guard) => Poll::Ready(AsyncRwLockWriteGuard { guard }),
+            Err(_) => {
+                // In a true async environment we would register a waker to be notified
+                // when the lock becomes available, but in wasm we'll just yield to
+                // the executor and try again next time.
+                cx.waker().wake_by_ref();
+                Poll::Pending
+            }
+        }
+    }
+}
+
+#[cfg(target_arch = "wasm32")]
+#[derive(Debug)]
+/// A read guard for `AsyncRwLock`.
+pub struct AsyncRwLockReadGuard<'a, T> {
+    guard: StdRwLockReadGuard<'a, T>,
+}
+
+#[cfg(target_arch = "wasm32")]
+impl<T> std::ops::Deref for AsyncRwLockReadGuard<'_, T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        &self.guard
+    }
+}
+
+#[cfg(target_arch = "wasm32")]
+#[derive(Debug)]
+/// A write guard for `AsyncRwLock`.
+pub struct AsyncRwLockWriteGuard<'a, T> {
+    guard: StdRwLockWriteGuard<'a, T>,
+}
+
+#[cfg(target_arch = "wasm32")]
+impl<T> std::ops::Deref for AsyncRwLockWriteGuard<'_, T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        &self.guard
+    }
+}
+
+#[cfg(target_arch = "wasm32")]
+impl<T> std::ops::DerefMut for AsyncRwLockWriteGuard<'_, T> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.guard
+    }
+}

crates/matrix-sdk-common/src/async_lock.rs

@@ -23,15 +23,41 @@ use std::{
 };
 
 #[cfg(target_arch = "wasm32")]
-pub use futures_util::future::Aborted as JoinError;
+pub use futures_util::future::AbortHandle;
 #[cfg(target_arch = "wasm32")]
 use futures_util::{
-    future::{AbortHandle, Abortable, RemoteHandle},
+    future::{Abortable, RemoteHandle},
     FutureExt,
 };
 #[cfg(not(target_arch = "wasm32"))]
-pub use tokio::task::{spawn, JoinError, JoinHandle};
+pub use tokio::task::{spawn, AbortHandle, JoinError, JoinHandle};
 
+#[cfg(target_arch = "wasm32")]
+#[derive(Debug)]
+pub enum JoinError {
+    Cancelled,
+    Panic,
+}
+#[cfg(target_arch = "wasm32")]
+impl JoinError {
+    /// Returns true if the error was caused by the task being cancelled.
+    ///
+    /// See [the module level docs] for more information on cancellation.
+    ///
+    /// [the module level docs]: crate::task#cancellation
+    pub fn is_cancelled(&self) -> bool {
+        matches!(self, JoinError::Cancelled)
+    }
+}
+#[cfg(target_arch = "wasm32")]
+impl std::fmt::Display for JoinError {
+    fn fmt(&self, fmt: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match &self {
+            JoinError::Cancelled => write!(fmt, "task was cancelled"),
+            JoinError::Panic => write!(fmt, "task panicked"),
+        }
+    }
+}
 #[cfg(target_arch = "wasm32")]
 pub fn spawn<F, T>(future: F) -> JoinHandle<T>
 where
@@ -47,24 +73,28 @@ where
         let _ = future.await;
     });
 
-    JoinHandle { remote_handle: Some(remote_handle), abort_handle }
+    JoinHandle { remote_handle: Some(remote_handle), the_abort_handle: abort_handle }
 }
 
 #[cfg(target_arch = "wasm32")]
 #[derive(Debug)]
 pub struct JoinHandle<T> {
     remote_handle: Option<RemoteHandle<T>>,
-    abort_handle: AbortHandle,
+    the_abort_handle: AbortHandle,
 }
 
 #[cfg(target_arch = "wasm32")]
 impl<T> JoinHandle<T> {
     pub fn abort(&self) {
-        self.abort_handle.abort();
+        self.the_abort_handle.abort();
+    }
+
+    pub fn abort_handle(&self) -> AbortHandle {
+        self.the_abort_handle.clone()
     }
 
     pub fn is_finished(&self) -> bool {
-        self.abort_handle.is_aborted()
+        self.the_abort_handle.is_aborted()
     }
 }
 
@@ -83,17 +113,119 @@ impl<T: 'static> Future for JoinHandle<T> {
     type Output = Result<T, JoinError>;
 
     fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
-        if self.abort_handle.is_aborted() {
+        if self.the_abort_handle.is_aborted() {
             // The future has been aborted. It is not possible to poll it again.
-            Poll::Ready(Err(JoinError))
+            Poll::Ready(Err(JoinError::Cancelled))
         } else if let Some(handle) = self.remote_handle.as_mut() {
             Pin::new(handle).poll(cx).map(Ok)
         } else {
-            Poll::Ready(Err(JoinError))
+            Poll::Ready(Err(JoinError::Panic))
         }
     }
 }
 
+#[cfg(target_arch = "wasm32")]
+use futures_executor;
+
+/// A handle to a runtime for executing async tasks and futures.
+///
+/// This is a unified type that represents either:
+/// - A `tokio::runtime::Handle` on non-WASM platforms
+/// - A `WasmRuntimeHandle` on WASM platforms
+///
+/// This abstraction allows code to run on both WASM and non-WASM platforms
+/// without conditional compilation.
+#[cfg(not(target_arch = "wasm32"))]
+pub type Handle = tokio::runtime::Handle;
+#[cfg(not(target_arch = "wasm32"))]
+pub type Runtime = tokio::runtime::Runtime;
+
+#[cfg(target_arch = "wasm32")]
+pub type Handle = WasmRuntimeHandle;
+#[cfg(target_arch = "wasm32")]
+pub type Runtime = WasmRuntimeHandle;
+
+#[cfg(target_arch = "wasm32")]
+#[derive(Debug)]
+/// A dummy guard that does nothing when dropped.
+/// This is used for the WASM implementation to match tokio::runtime::EnterGuard.
+pub struct WasmRuntimeGuard;
+
+#[cfg(target_arch = "wasm32")]
+impl Drop for WasmRuntimeGuard {
+    fn drop(&mut self) {
+        // No-op, as there's no special context to exit in WASM
+    }
+}
+
+#[cfg(target_arch = "wasm32")]
+#[derive(Default, Debug)]
+/// A runtime handle implementation for WebAssembly targets.
+///
+/// This implements a minimal subset of the tokio::runtime::Handle API
+/// that is needed for the matrix-rust-sdk to function on WASM.
+pub struct WasmRuntimeHandle;
+
+#[cfg(target_arch = "wasm32")]
+impl WasmRuntimeHandle {
+    /// Spawns a future in the wasm32 bindgen runtime.
+    #[track_caller]
+    pub fn spawn<F>(&self, future: F) -> JoinHandle<F::Output>
+    where
+        F: Future + 'static,
+        F::Output: 'static,
+    {
+        spawn(future)
+    }
+
+    /// Runs the provided function on an executor dedicated to blocking
+    /// operations.
+    #[track_caller]
+    pub fn spawn_blocking<F, R>(&self, func: F) -> JoinHandle<R>
+    where
+        F: FnOnce() -> R + 'static,
+        R: 'static,
+    {
+        spawn(async move { func() })
+    }
+
+    /// Runs a future to completion on the current thread.
+    pub fn block_on<F, T>(&self, future: F) -> T
+    where
+        F: Future<Output = T>,
+    {
+        futures_executor::block_on(future)
+    }
+
+    /// Enters the runtime context.
+    ///
+    /// For WebAssembly, this is a no-op that returns a dummy guard.
+    pub fn enter(&self) -> WasmRuntimeGuard {
+        WasmRuntimeGuard
+    }
+}
+
+/// Get a runtime handle appropriate for the current target platform.
+///
+/// This function returns a unified `Handle` type that works across both
+/// WASM and non-WASM platforms, allowing code to be written that is
+/// agnostic to the platform-specific runtime implementation.
+///
+/// Returns:
+/// - A `tokio::runtime::Handle` on non-WASM platforms
+/// - A `WasmRuntimeHandle` on WASM platforms
+pub fn get_runtime_handle() -> Handle {
+    #[cfg(target_arch = "wasm32")]
+    {
+        WasmRuntimeHandle
+    }
+
+    #[cfg(not(target_arch = "wasm32"))]
+    {
+        async_compat::get_runtime_handle()
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use assert_matches::assert_matches;