Add WASM32 core platform abstractions #5079

zzorba · 2025-05-22T22:57:44Z

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.

This is part of a larger effort by Filament to add wasm32 support to the matrix-rust-sdk and matrix-sdk-ffi bindings. We have these bindings working on our fork, and are now taking steps to cherry pick them incrementally back to main to make them more reviewable.

Public API changes documented in changelogs (optional)

Signed-off-by: Daniel Salinas

codecov · 2025-05-22T23:25:20Z

Codecov Report

Attention: Patch coverage is 0% with 49 lines in your changes missing coverage. Please review.

Project coverage is 85.75%. Comparing base (4d027ec) to head (ec94b8c).
Report is 153 commits behind head on main.

Files with missing lines	Patch %	Lines
crates/matrix-sdk-common/src/async_lock.rs	0.00%	28 Missing ⚠️
crates/matrix-sdk-common/src/executor.rs	0.00%	13 Missing ⚠️
crates/matrix-sdk-common/src/stream.rs	0.00%	8 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5079      +/-   ##
==========================================
- Coverage   85.84%   85.75%   -0.09%     
==========================================
  Files         325      327       +2     
  Lines       35906    35954      +48     
==========================================
+ Hits        30824    30834      +10     
- Misses       5082     5120      +38

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

jplatte · 2025-05-23T06:20:49Z

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

That's a lot of #[cfg(target_arch = "wasm32")]s. How about doing it like this:

#[cfg(not(target_arch = "wasm32"))] pub use tokio::sync::{ ... }; #[cfg(target_arch = "wasm32")] pub use self::async_lock_wasm::*; #[cfg(target_arch = "wasm32")] mod async_lock_wasm { // all the current cfg'd items }

Yup, this. A similar approach would be:

#[cfg(not(target_family = "wasm"))] mod sys { pub use tokio::sync::{…}; } #[cfg(target_family = "wasm"))] mod sys { pub use …; } pub use sys::*;

I would prefer this choice to be honest.

Also, please use target_family = "wasm" if possible (see target_family) rather than target_arch = "wasm32". wasm64 will come soon, and it will be a maintenance burden.

I guess this thread is irrelevant given the other one on this file ^^

Okay, I will make these corrections in these shim files. It seemed like the other was the norm but happy to adjust it.

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

jplatte · 2025-05-23T06:22:58Z

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

+    #[cfg(target_arch = "wasm32")]
+    {
+        WasmRuntimeHandle
+    }
+
+    #[cfg(not(target_arch = "wasm32"))]
+    {
+        async_compat::get_runtime_handle()
+    }


Suggested change

#[cfg(target_arch = "wasm32")]

{

WasmRuntimeHandle

}

#[cfg(not(target_arch = "wasm32"))]

{

async_compat::get_runtime_handle()

}

#[cfg(target_arch = "wasm32")]

return WasmRuntimeHandle;

#[cfg(not(target_arch = "wasm32"))]

return async_compat::get_runtime_handle();

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

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

maan2003 · 2025-05-23T07:00:19Z

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

+/// Future for the [`next`](super::StreamExt::next) method.
+#[cfg(target_arch = "wasm32")]
+#[derive(Debug)]
+#[must_use = "futures do nothing unless you `.await` or poll them"]
+pub struct Next<'a, St: ?Sized> {
+    stream: &'a mut St,
+}


why is this needed? I think futures_util::stream::StreamExt's next should just work

The issue is the call to .boxed() on the stream it returns, the StreamExt has has a Send trait requirement that prevents .boxed() from being called when used in situations like this:

let (initial, mut subscriber): (RoomPaginationStatus, BoxStream<'_, RoomPaginationStatus>) = match self.inner.live_back_pagination_status().await { Some((status, stream)) => (status, stream.boxed()), None => { let (status, stream) = self.inner.focused_pagination_status().await.context( "can't subscribe to the back-pagination status on a focused timeline", )?; (status, stream.boxed()) } };

Here is the definition of .boxed() from the futures_util::stream::StreamExt

/// Wrap the stream in a Box, pinning it. /// /// This method is only available when the `std` or `alloc` feature of this /// library is activated, and it is activated by default. #[cfg(feature = "alloc")] fn boxed<'a>(self) -> BoxStream<'a, Self::Item> where Self: Sized + Send + 'a, { assert_stream::<Self::Item, _>(Box::pin(self)) }

maan2003 · 2025-05-23T07:01:41Z

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

would strongly recommend https://docs.rs/n0-future/latest/n0_future/ instead of making our own abstractions

Thank you for this suggestion, I will update this in the split out PR to use this library for the shim instead.

Hywan

Thanks for your contribution!

I've a couple of remarks though.

I think it's better to split your single patch into one patch per features: one patch for async_lock, one patch for stream etc. It would help the reviewer,
I don't understand why async_lock is necessary at all since tokio::sync is Wasm-compatible (see tokio Wasm support),
I suggest to use the #[cfg(target…)] mod sys + pub use sys::* pattern more broadly to reduce most of the #[cfg(target…)] you have; it will also greatly clarify the code!
I suggest to use target_family = "wasm" to target Wasm instead of target_arch = "wasm32",
I don't understand the need for WasmRuntime because tokio::runtime is Wasm-compatible (see the same link for tokio::sync),
I don't understand why you re-implement Next, it is by-design Wasm-compatible. I understand the need to “alias” LocalBoxStream to BoxStream though.

In general, please justify the reason of being of those types in their respective documentation please.

Hywan · 2025-05-23T07:43:30Z

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

Yup, this. A similar approach would be:

#[cfg(not(target_family = "wasm"))] mod sys { pub use tokio::sync::{…}; } #[cfg(target_family = "wasm"))] mod sys { pub use …; } pub use sys::*;

I would prefer this choice to be honest.

Also, please use target_family = "wasm" if possible (see target_family) rather than target_arch = "wasm32". wasm64 will come soon, and it will be a maintenance burden.

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

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

Hywan · 2025-05-23T07:48:05Z

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

+#[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.


Please put the #[…] after the comment.

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

Hywan · 2025-05-23T07:49:15Z

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

The copyright is missing, along with a comment explaining why this is needed, what it does etc.

Cargo.toml

Hywan · 2025-05-23T07:56:44Z

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

+#[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;


Could become:

#[cfg(not(target_family = "wasm"))] mod sys { pub use tokio::runtime::{Handle, Runtime}; } #[cfg(target_family = "wasm")] mod sys { pub struct Handle; pub struct Runtime; } pub use sys::*;

maan2003 · 2025-05-23T08:07:30Z

I don't understand the need for WasmRuntime because tokio::runtime is Wasm-compatible (see the same link for tokio::sync),

actually no, tokio rt on wasm doesn't integrate with the browser (for fetch() etc), many wasm compatible crates require the wasm-bindgen-futures runtime

Instead of scattered conditional compilation directives throughout the code, this commit consolidates platform-specific code into sys modules with the pattern: mod sys { // native implementations } mod sys { // wasm implementations } pub use sys::*; Eliminate the definition of the unnecessary async_lock

zzorba · 2025-05-23T14:13:29Z

I will split up patch into two commits (one for Stream, one for Executor, as async_lock is indeed not necessary)
Have adjusted code to use mod sys exports.
Moved to target_family = "wasm"
Tokio rt does not work with wasm, I believe an alternative runtime is necessary as a result.
The issue is the .boxed() call on StreamExt, which has a Send trait. I will try to find a way to add this as an extension for Wasm in a way that doesn't require redefining Stream.

zzorba · 2025-05-23T16:25:28Z

Okay, I have split up this PR:

Stream extension: #5085
Executor/JoinHandle extensions: #5088
Runtime: #5089 (dependent on 5088, will mark as ready once 5088 is merged)

zzorba · 2025-05-25T14:52:19Z

I believe this PR can be closed in favor of the smaller ones, leaving it open just in case there is any back-and-forth on existing comments.

Hywan · 2025-05-26T10:16:56Z

Thank you for your work <3!

zzorba requested a review from a team as a code owner May 22, 2025 22:57

zzorba requested review from Hywan and removed request for a team May 22, 2025 22:57

zzorba force-pushed the wasm32-core-abstractions branch 2 times, most recently from 0823d50 to ec94b8c Compare May 22, 2025 23:10

zzorba mentioned this pull request May 23, 2025

Move to Uniffi 0.29, adjust async callback macros #5080

Draft

1 task

jplatte reviewed May 23, 2025

View reviewed changes

maan2003 reviewed May 23, 2025

View reviewed changes

crates/matrix-sdk-common/src/async_lock.rs Outdated Show resolved Hide resolved

maan2003 reviewed May 23, 2025

View reviewed changes

Hywan requested changes May 23, 2025

View reviewed changes

zzorba force-pushed the wasm32-core-abstractions branch from bde0663 to de2fcc0 Compare May 23, 2025 13:52

zzorba mentioned this pull request May 23, 2025

feat(wasm): StreamExt that supports wasm platforms #5085

Open

1 task

zzorba closed this May 27, 2025

Add WASM32 core platform abstractions #5079

Add WASM32 core platform abstractions #5079

Uh oh!

Conversation

zzorba commented May 22, 2025

Uh oh!

codecov bot commented May 22, 2025

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Hywan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maan2003 commented May 23, 2025

Uh oh!

zzorba commented May 23, 2025

Uh oh!

zzorba commented May 23, 2025

Uh oh!

zzorba commented May 25, 2025

Uh oh!

Hywan commented May 26, 2025

Uh oh!

Uh oh!