Add WASM/async support via feature flag

[geofflittle]

Hello! I'm working on a project that compiles to WASM and would love to use taskchampion as a library. Currently, this isn't possible due to a dependency that doesn't support the wasm32-unknown-unknown target.

This issue proposes a non-breaking change to add first-class support for using taskchampion in a WASM and async context.

The Problem
When attempting to compile taskchampion for a WASM target, the build fails:

• UUID Generation: The uuid crate's default v4 feature relies on OS-level random number generation, which is not available in WASM.

Proposed Solution
I propose introducing a new wasm feature flag. When a user enables this feature and disables default features, the library will be fully WASM-compatible.

A consumer of the library would use it in their Cargo.toml like this:

[dependencies]
taskchampion = { version = "...", default-features = false, features = ["wasm"] }

This approach is fully backward-compatible and requires no changes for existing users.

Implementation Plan
I plan to submit a pull request with several small, logical commits to implement this. Each commit will represent a focused step in the process, making the changes easier to review.

1. Add wasm feature and configure uuid
       * Add the new wasm = ["uuid/js"] feature to Cargo.toml.
       * This configures the uuid crate to use the browser's random number generator when the wasm feature is active.
2. Introduce the AsyncServer trait
       * Add the async-trait dependency.
       * Define a new pub trait AsyncServer, mirroring the synchronous Server trait, to provide a clear interface for non-blocking server implementations.
3. Implement async synchronization
       * Implement the core async logic in a new taskdb/async_sync.rs module.
       * Add the public-facing async fn sync_async(...) methods to Replica and TaskDb.

This will make taskchampion a much more versatile library and open it up to a new ecosystem of web and serverless applications. I'm happy to discuss this proposal and am open to any feedback.

Thank you!
-Geoff

[geofflittle]

After further integration testing with my local changes, I've found that the library would be more robust and easier to use if it included a concrete AsyncSyncServer implementation directly, rather than requiring downstream async users to build their own from scratch.

This keeps the library's encryption logic properly encapsulated and provides a valuable, reusable component for the community.

My updated plan is to add the following commit:

4. Add AsyncSyncServer Implementation
   • Add reqwest as an optional dependency.
   • Create a new server-sync-async feature that enables reqwest and the new async server.
   • Create a new AsyncSyncServer struct in src/server/ that implements the AsyncServer trait, using reqwest for async HTTP requests. The implementation will mirror the logic of the existing synchronous SyncServer.

This makes the overall contribution more valuable to the project and provides a clear path for native async support alongside WASM.

[djmitche]

I'm wildly in favor of WASM compatibility -- among other things, that would mean that users can use TaskChampion in web browsers without sharing their encryption key with a web server. So, thanks for working on this!

Your original post, before editing, suggested removing the SQLite storage backend -- but that's the only functional storage backend that exists right now. Did you find a way to build that for WASM, or is there a proposted alternative? Using one of the browser storage mechanisms would be pretty interesting.

The Server trait is already an awkward fit for the cloud backends, as it calls block_on to run the async cloud SDKs:

taskchampion/src/server/cloud/gcp.rs

Lines 32 to 38 in 28e8d84

	let config: ClientConfig = if let Some(credentials) = credential_path {
	let credentials = rt.block_on(CredentialsFile::new_from_file(credentials))?;
	rt.block_on(ClientConfig::default().with_credentials(credentials))?
	} else {
	rt.block_on(ClientConfig::default().with_auth())?
	};

So, I support making that trait async, allowing removal of those block_on calls.

As for async support for the sync operation -- I think that should be the only implementation, rather than maintaining two implementations. The user-visible part of sync is very simple -- Replica::sync(..). So, we could easily add a Replica::sync_future(..) or something of the sort (I'd like to avoid sync_async due to confusion of terms). Then Replica::sync can just call block_on(self.sync_future(..)). For the moment, that should be sufficient, and as a follow-on we can remove the existing block_on(..) calls used for the cloud backends.

All of this can probably be divided up into a number of incremental PRs, all of which are an improvement to the repo.

[djmitche]

Thinking about it more, making the trait async is a breaking change. That's fine -- we'll just call it 3.0. And that means we can just make the existing sync method async, and not have to come up with a good name for it.

[djmitche]

(and we may want to think about making the Storage and StorageTxn types async at the same time, just to avoid too many breaking changes.

Would that be helpful in implementing a web-compatible storage backend?

[geofflittle]

Thanks for the feedback!

Your original post... suggested removing the SQLite storage backend... Did you find a way to build that for WASM, or is there a proposed alternative?

My initial post and then edits were confusing--I was originally working off the head of v2.0.3 and thought I'd need to make SQLite optional, since it doesn't build for WASM. Now that I'm correctly on main I see that the storage-sqlite feature flag already handles this.

My plan is to have my WASM application disable default features and use the existing InMemoryStorage backend for now. But making the Storage and StorageTxn traits async is a great foundation for future changes to add a browser-based storage backend.

Thinking about it more, making the trait async is a breaking change. That's fine -- we'll just call it 3.0... I think that should be the only implementation, rather than maintaining two implementations.

Sounds good. Making Replica::sync and the Server/Storage traits fully async as a breaking change for v3.0 makes sense.

Based on this, here is my revised plan:

Revised Plan

1. Make Storage and StorageTxn Traits async
   • Add async-trait as a dependency.
   • Convert all methods on the Storage and StorageTxn traits to async fn.
   • Update the concrete implementations (InMemoryStorage, SqliteStorage) to conform to the new async traits. For SqliteStorage, this might involve using a blocking task runner for now.
2. Make Server Trait and Replica::sync async
   • Convert all methods on the Server trait to async fn.
   • Change Replica::sync to be async fn sync.
   • Update the existing SyncServer to implement the new async Server trait, replacing its ureq client with an async client like reqwest.
   • Update the cloud server implementations to use their async SDK methods directly, removing the block_on calls.
3. Add WASM-Specific uuid Support
   • Add the wasm feature flag to Cargo.toml.
   • Configure the wasm feature to enable the js feature for the uuid crate.
4. Add the Built-in WasmSyncServer
   • Add all necessary web-sys dependencies as optional, controlled by the wasm feature flag.
   • Create a new WasmSyncServer struct that implements the async Server trait using web-sys::fetch.
   • Conditionally compile this entire new module using the wasm feature flag.

[geofflittle]

Hi @djmitche,

I've pushed the first substantial commit for this refactor to #600. This commit starts the async conversion by refactoring the storage layer.

The core changes in this first step are:

• A new AsyncStorage trait has been introduced, which defines the fully asynchronous API for storage backends.
• SqliteStorage and InMemoryStorage have been refactored to be asynchronous (using tokio-rusqlite for the former) and now implement the new AsyncStorage trait.
• To maintain compatibility with the existing synchronous code, a BlockingStorageAdapter now wraps the async storage backend. This allows the rest of the application to continue using the storage layer without any changes for now.

Before I proceed with propagating the async changes up through TaskDb and Replica, would you be able to take a look at this first commit? I want to make sure you're happy with the direction before I get too far down the road.

Thanks!

[djmitche]

I will take a look -- thanks!