[web] separate Client from RunningClient to support early calls to add_owner

Author: ma2bd

linera-client/src/chain_listener.rs

@@ -291,7 +291,10 @@ impl<C: ClientContext + 'static> ChainListener<C> {
 
     /// Runs the chain listener.
     #[instrument(skip(self))]
-    pub async fn run(mut self) -> Result<impl Future<Output = Result<(), Error>>, Error> {
+    pub async fn run(
+        mut self,
+    ) -> Result<impl Future<Output = Result<<C::Environment as Environment>::Storage, Error>>, Error>
+    {
         let chain_ids = {
             let guard = self.context.lock().await;
             let admin_chain_id = guard.admin_chain_id();
@@ -340,7 +343,7 @@ impl<C: ClientContext + 'static> ChainListener<C> {
                 }
             }
             future::join_all(self.listening.into_values().map(|client| client.stop())).await;
-            Ok(())
+            Ok(self.storage)
         })
     }
 

web/@linera/client/src/chain/application.rs

@@ -6,11 +6,11 @@ use linera_core::client::ChainClient;
 use wasm_bindgen::prelude::*;
 use web_sys::wasm_bindgen;
 
-use crate::{Client, Environment, JsResult};
+use crate::{client::ClientContext, Environment, JsResult};
 
 #[wasm_bindgen]
 pub struct Application {
-    pub(crate) client: Client,
+    pub(crate) client_context: ClientContext,
     pub(crate) chain_client: ChainClient<Environment>,
     pub(crate) id: ApplicationId,
 }
@@ -70,7 +70,6 @@ impl Application {
 
         if !operations.is_empty() {
             let _hash = self
-                .client
                 .client_context
                 .lock()
                 .await

web/@linera/client/src/chain/mod.rs

@@ -14,14 +14,14 @@ use serde::ser::Serialize as _;
 use wasm_bindgen::prelude::*;
 use web_sys::{js_sys, wasm_bindgen};
 
-use crate::{Client, Environment, JsResult};
+use crate::{client::ClientContext, Environment, JsResult};
 
 pub mod application;
 pub use application::Application;
 
 #[wasm_bindgen]
 pub struct Chain {
-    pub(crate) client: Client,
+    pub(crate) client_context: ClientContext,
     pub(crate) chain_client: ChainClient<Environment>,
 }
 
@@ -143,7 +143,7 @@ impl Chain {
     pub async fn validator_version_info(&self) -> JsResult<JsValue> {
         self.chain_client.synchronize_from_validators().await?;
         let result = self.chain_client.local_committee().await;
-        let mut client = self.client.client_context.lock().await;
+        let mut client = self.client_context.lock().await;
         client.update_wallet(&self.chain_client).await?;
         let committee = result?;
         let node_provider = client.make_node_provider();
@@ -187,7 +187,7 @@ impl Chain {
     pub async fn application(&self, id: &str) -> JsResult<Application> {
         web_sys::console::debug_1(&format!("connecting to Linera application {id}").into());
         Ok(Application {
-            client: self.client.clone(),
+            client_context: self.client_context.clone(),
             chain_client: self.chain_client.clone(),
             id: id.parse()?,
         })

web/@linera/client/src/client.rs

@@ -1,36 +1,23 @@
 // Copyright (c) Zefchain Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-use std::{rc::Rc, sync::Arc};
+use std::{future::Future, pin::Pin, rc::Rc, sync::Arc};
 
 use futures::{
-    future::{self, FutureExt as _},
+    future::{FutureExt as _, RemoteHandle},
     lock::Mutex as AsyncMutex,
 };
 use linera_base::identifiers::{AccountOwner, ChainId};
-use linera_client::chain_listener::{ChainListener, ClientContext as _};
+use linera_client::chain_listener::{ChainListener, ChainListenerConfig, ClientContext as _};
 use tokio_util::sync::CancellationToken;
 use wasm_bindgen::prelude::*;
 use web_sys::wasm_bindgen;
 
-use crate::{chain::Chain, signer::Signer, storage, wallet::Wallet, Environment, Error, Result};
+use crate::{
+    chain::Chain, signer::Signer, storage, wallet::Wallet, Environment, Error, Result, Storage,
+};
 
-/// The full client API, exposed to the wallet implementation. Calls
-/// to this API can be trusted to have originated from the user's
-/// request.
-#[wasm_bindgen]
-#[derive(Clone)]
-pub struct Client {
-    // This use of `futures::lock::Mutex` is safe because we only
-    // expose concurrency to the browser, which must always run all
-    // futures on the global task queue.
-    // It does nothing here in this single-threaded context, but is
-    // hard-coded by `ChainListener`.
-    pub(crate) client_context: Arc<AsyncMutex<linera_client::ClientContext<Environment>>>,
-    cancellation_token: CancellationToken,
-    chain_listener_result:
-        future::Shared<future::RemoteHandle<Result<(), Rc<linera_client::Error>>>>,
-}
+pub(crate) type ClientContext = Arc<AsyncMutex<linera_client::ClientContext<Environment>>>;
 
 #[derive(Default, serde::Deserialize, tsify::Tsify)]
 #[tsify(from_wasm_abi)]
@@ -41,9 +28,24 @@ pub struct ChainOptions {
     owner: Option<AccountOwner>,
 }
 
+/// A client that has been created but whose chain listener has not yet started.
+///
+/// Use `chain()` to perform pre-start operations (e.g. `addOwner`), then call
+/// `start()` to begin background synchronization and obtain a [`RunningClient`].
+#[wasm_bindgen]
+pub struct Client {
+    pub(crate) client_context: ClientContext,
+    storage: Storage,
+    chain_listener_config: ChainListenerConfig,
+}
+
 #[wasm_bindgen]
 impl Client {
-    /// Creates a new client and connects to the network.
+    /// Creates a new client without starting the chain listener.
+    ///
+    /// After creating the client, you can perform operations like `addOwner`
+    /// via `chain()`. Call `start()` to begin background chain synchronization
+    /// and obtain a [`RunningClient`].
     ///
     /// # Errors
     /// On transport or protocol error, if persistent storage is
@@ -65,6 +67,7 @@ impl Client {
 
         let default = wallet.default;
         let genesis_config = wallet.genesis_config.clone();
+        let chain_listener_config = options.chain_listener_config.clone();
 
         let client = linera_client::ClientContext::new(
             storage.clone(),
@@ -80,59 +83,113 @@ impl Client {
         // The `Arc` here is useless, but it is required by the `ChainListener` API.
         #[expect(clippy::arc_with_non_send_sync)]
         let client = Arc::new(AsyncMutex::new(client));
-        let client_clone = client.clone();
-        let cancellation_token = tokio_util::sync::CancellationToken::new();
-        let chain_listener = ChainListener::new(
-            options.chain_listener_config,
-            client_clone,
+
+        Ok(Client {
+            client_context: client,
             storage,
+            chain_listener_config,
+        })
+    }
+
+    /// Connect to a chain on the Linera network.
+    ///
+    /// # Errors
+    ///
+    /// If the wallet could not be read or chain synchronization fails.
+    #[wasm_bindgen]
+    pub async fn chain(&self, chain: ChainId, options: Option<ChainOptions>) -> Result<Chain> {
+        make_chain(&self.client_context, chain, options).await
+    }
+
+    /// Cleanly shut down the client without starting the chain listener.
+    ///
+    /// # Errors
+    ///
+    /// If the context is being referenced by any other objects (chains,
+    /// applications…). Free these with `.free()` before disposing of this
+    /// object.
+    #[wasm_bindgen(js_name = asyncDispose)]
+    pub async fn async_dispose(self) -> Result<()> {
+        Arc::into_inner(self.client_context).ok_or(Error::new(
+            "Client disposed while being referenced elsewhere",
+        ))?;
+        Ok(())
+    }
+
+    /// Starts the chain listener for background synchronization, consuming this
+    /// `Client` and returning a [`RunningClient`].
+    ///
+    /// # Errors
+    /// If the chain listener fails to start.
+    #[wasm_bindgen]
+    pub async fn start(self) -> Result<RunningClient> {
+        let cancellation_token = CancellationToken::new();
+        let chain_listener_config = self.chain_listener_config;
+
+        let chain_listener_handle = start_listener(
+            chain_listener_config.clone(),
+            self.client_context.clone(),
+            self.storage,
             cancellation_token.clone(),
-            tokio::sync::mpsc::unbounded_channel().1,
-            true, // Enable background sync
         )
-        .run()
         .await?;
 
-        let (run_chain_listener, chain_listener_result) = async move {
-            let result = chain_listener.await.map_err(|error| {
-                tracing::error!("ChainListener error: {error:?}");
-                Rc::new(error)
-            });
-            tracing::debug!("chain listener completed");
-            result
-        }
-        .remote_handle();
-
-        wasm_bindgen_futures::spawn_local(run_chain_listener);
-
-        Ok(Self {
-            client_context: client,
+        Ok(RunningClient {
+            client_context: self.client_context,
             cancellation_token,
-            chain_listener_result: chain_listener_result.shared(),
+            chain_listener_handle: Box::pin(chain_listener_handle),
+            chain_listener_config,
         })
     }
+}
+
+/// The full client API, exposed to the wallet implementation. Calls
+/// to this API can be trusted to have originated from the user's
+/// request.
+///
+/// Obtained by calling [`Client::start()`].
+#[wasm_bindgen]
+pub struct RunningClient {
+    pub(crate) client_context: ClientContext,
+    cancellation_token: CancellationToken,
+    chain_listener_handle: Pin<Box<dyn Future<Output = Result<Storage, Rc<linera_client::Error>>>>>,
+    chain_listener_config: ChainListenerConfig,
+}
 
+#[wasm_bindgen]
+impl RunningClient {
     /// Connect to a chain on the Linera network.
     ///
     /// # Errors
     ///
     /// If the wallet could not be read or chain synchronization fails.
     #[wasm_bindgen]
     pub async fn chain(&self, chain: ChainId, options: Option<ChainOptions>) -> Result<Chain> {
-        let options = options.unwrap_or_default();
-        let mut chain_client = self
-            .client_context
-            .lock()
+        make_chain(&self.client_context, chain, options).await
+    }
+
+    /// Stops the chain listener and returns a [`Client`] that can be reconfigured
+    /// and restarted.
+    ///
+    /// # Errors
+    /// Propagates any errors that occurred during background execution of the
+    /// chain listener.
+    #[wasm_bindgen]
+    pub async fn stop(self) -> Result<Client> {
+        self.cancellation_token.cancel();
+
+        let storage = self
+            .chain_listener_handle
             .await
-            .make_chain_client(chain)
-            .await?;
-        if let Some(owner) = options.owner {
-            chain_client.set_preferred_owner(owner);
-        }
+            .map_err(|e| match Rc::into_inner(e) {
+                Some(e) => Error::from(e),
+                None => Error::new("chain listener error (details unavailable)"),
+            })?;
 
-        Ok(Chain {
-            chain_client,
-            client: self.clone(),
+        Ok(Client {
+            client_context: self.client_context,
+            storage,
+            chain_listener_config: self.chain_listener_config,
         })
     }
 
@@ -151,16 +208,67 @@ impl Client {
     pub async fn async_dispose(self) -> Result<()> {
         self.cancellation_token.cancel();
 
-        if let Err(Some(e)) = self.chain_listener_result.await.map_err(Rc::into_inner) {
-            return Err(e.into());
+        if let Err(e) = self.chain_listener_handle.await {
+            if let Some(e) = Rc::into_inner(e) {
+                return Err(e.into());
+            }
         }
 
-        let context = Arc::into_inner(self.client_context).ok_or(Error::new(
+        Arc::into_inner(self.client_context).ok_or(Error::new(
             "Client disposed while being referenced elsewhere",
         ))?;
 
-        drop(context);
-
         Ok(())
     }
 }
+
+/// Shared implementation for creating a [`Chain`] from a [`ClientContext`].
+async fn make_chain(
+    client_context: &ClientContext,
+    chain: ChainId,
+    options: Option<ChainOptions>,
+) -> Result<Chain> {
+    let options = options.unwrap_or_default();
+    let mut chain_client = client_context.lock().await.make_chain_client(chain).await?;
+    if let Some(owner) = options.owner {
+        chain_client.set_preferred_owner(owner);
+    }
+
+    Ok(Chain {
+        client_context: client_context.clone(),
+        chain_client,
+    })
+}
+
+async fn start_listener(
+    config: ChainListenerConfig,
+    context: ClientContext,
+    storage: Storage,
+    cancellation_token: CancellationToken,
+) -> Result<RemoteHandle<Result<Storage, Rc<linera_client::Error>>>> {
+    tracing::debug!("starting chain listener...");
+    let chain_listener = ChainListener::new(
+        config,
+        context,
+        storage,
+        cancellation_token,
+        tokio::sync::mpsc::unbounded_channel().1,
+        true, // Enable background sync
+    )
+    .run()
+    .await?;
+
+    let (run_chain_listener, chain_listener_handle) = async move {
+        let result = chain_listener.await.map_err(|error| {
+            tracing::error!("ChainListener error: {error:?}");
+            Rc::new(error)
+        });
+        tracing::debug!("chain listener completed");
+        result
+    }
+    .remote_handle();
+
+    wasm_bindgen_futures::spawn_local(run_chain_listener);
+
+    Ok(chain_listener_handle)
+}

web/@linera/client/src/lib.rs

@@ -24,7 +24,7 @@ use wasm_bindgen::prelude::*;
 use web_sys::wasm_bindgen;
 
 pub mod client;
-pub use client::Client;
+pub use client::{Client, RunningClient};
 pub mod chain;
 pub use chain::Chain;
 pub mod error;