rust-sdk: restructure API to builder pattern (#3000)

Author: octol

Cargo.toml

@@ -107,8 +107,11 @@ edition = "2021"
 
 [workspace.dependencies]
 async-trait = "0.1.63"
+lazy_static = "1.4.0"
 log = "0.4"
-thiserror = "1.0.38"
 serde = "1.0.152"
 serde_json = "1.0.91"
+tap = "1.0.1"
+thiserror = "1.0.38"
 tokio = "1.24.1"
+url = "2.2"

clients/client-core/src/client/base_client/mod.rs

@@ -51,11 +51,22 @@ pub mod non_wasm_helpers;
 
 pub mod helpers;
 
+#[derive(Clone)]
 pub struct ClientInput {
     pub connection_command_sender: ConnectionCommandSender,
     pub input_sender: InputMessageSender,
 }
 
+impl ClientInput {
+    pub async fn send(
+        &self,
+        message: InputMessage,
+    ) -> Result<(), tokio::sync::mpsc::error::SendError<InputMessage>> {
+        self.input_sender.send(message).await
+    }
+}
+
+#[derive(Clone)]
 pub struct ClientOutput {
     pub received_buffer_request_sender: ReceivedBufferRequestSender,
 }
@@ -303,6 +314,7 @@ where
         let shared_key = if self.key_manager.is_gateway_key_set() {
             Some(self.key_manager.gateway_shared_key())
         } else {
+            log::info!("Gateway key not set! Will proceed anyway.");
             None
         };
 

clients/client-core/src/client/replies/reply_storage/backend/browser_backend.rs

@@ -5,6 +5,8 @@ use crate::client::replies::reply_storage::backend::Empty;
 use crate::client::replies::reply_storage::{CombinedReplyStorage, ReplyStorageBackend};
 use async_trait::async_trait;
 
+use std::path::PathBuf;
+
 // well, right now we don't have the browser storage : (
 // so we keep everything in memory
 #[derive(Debug)]
@@ -27,6 +29,15 @@ impl Backend {
 impl ReplyStorageBackend for Backend {
     type StorageError = <Empty as ReplyStorageBackend>::StorageError;
 
+    async fn new(debug_config: &crate::config::DebugConfig, _db_path: Option<PathBuf>) -> Self {
+        Backend {
+            empty: Empty {
+                min_surb_threshold: debug_config.minimum_reply_surb_storage_threshold,
+                max_surb_threshold: debug_config.maximum_reply_surb_storage_threshold,
+            },
+        }
+    }
+
     async fn flush_surb_storage(
         &mut self,
         storage: &CombinedReplyStorage,

clients/client-core/src/client/replies/reply_storage/backend/fs_backend/mod.rs

@@ -1,6 +1,7 @@
 // Copyright 2022 - Nym Technologies SA <contact@nymtech.net>
 // SPDX-License-Identifier: Apache-2.0
 
+use crate::client::base_client::non_wasm_helpers;
 use crate::client::replies::reply_storage::backend::fs_backend::manager::StorageManager;
 use crate::client::replies::reply_storage::backend::fs_backend::models::{
     ReplySurbStorageMetadata, StoredReplyKey, StoredReplySurb, StoredSenderTag, StoredSurbSender,
@@ -367,6 +368,12 @@ impl Backend {
 impl ReplyStorageBackend for Backend {
     type StorageError = error::StorageError;
 
+    async fn new(debug_config: &crate::config::DebugConfig, db_path: Option<PathBuf>) -> Self {
+        non_wasm_helpers::setup_fs_reply_surb_backend(db_path, debug_config)
+            .await
+            .unwrap()
+    }
+
     fn is_active(&self) -> bool {
         self.manager.is_active()
     }

clients/client-core/src/client/replies/reply_storage/backend/mod.rs

@@ -3,7 +3,7 @@
 
 use crate::client::replies::reply_storage::CombinedReplyStorage;
 use async_trait::async_trait;
-use std::error::Error;
+use std::{error::Error, path::PathBuf};
 use thiserror::Error;
 
 #[cfg(target_arch = "wasm32")]
@@ -30,6 +30,13 @@ pub struct Empty {
 impl ReplyStorageBackend for Empty {
     type StorageError = UndefinedError;
 
+    async fn new(debug_config: &crate::config::DebugConfig, _db_path: Option<PathBuf>) -> Self {
+        Self {
+            min_surb_threshold: debug_config.minimum_reply_surb_storage_threshold,
+            max_surb_threshold: debug_config.maximum_reply_surb_storage_threshold,
+        }
+    }
+
     async fn flush_surb_storage(
         &mut self,
         _storage: &CombinedReplyStorage,
@@ -63,6 +70,8 @@ impl ReplyStorageBackend for Empty {
 pub trait ReplyStorageBackend: Sized {
     type StorageError: Error + 'static;
 
+    async fn new(debug_config: &crate::config::DebugConfig, db_path: Option<PathBuf>) -> Self;
+
     fn is_active(&self) -> bool {
         true
     }

common/client-libs/gateway-client/src/client.rs

@@ -441,6 +441,7 @@ where
         }
 
         debug_assert!(self.connection.is_available());
+        log::trace!("Registering gateway");
 
         // it's fine to instantiate it here as it's only used once (during authentication or registration)
         // and putting it into the GatewayClient struct would be a hassle

sdk/rust/nym-sdk/examples/manually_handle_keys_and_config.rs

@@ -4,41 +4,62 @@ use nym_sdk::mixnet;
 async fn main() {
     logging::setup_logging();
 
-    // We can set a few options
     let user_chosen_gateway_id = None;
     let nym_api_endpoints = vec!["https://validator.nymtech.net/api/".parse().unwrap()];
-
     let config = mixnet::Config::new(user_chosen_gateway_id, nym_api_endpoints);
 
-    let mut client = mixnet::MixnetClient::builder(Some(config), None)
-        .await
-        .unwrap();
-
     // Just some plain data to pretend we have some external storage that the application
     // implementer is using.
     let mut mock_storage = MockStorage::empty();
 
-    // In this we want to provide our own gateway config struct, and handle persisting this info to disk
-    // ourselves (e.g., as part of our own configuration file).
     let first_run = true;
-    if first_run {
-        client.register_with_gateway().await.unwrap();
+
+    let client = if first_run {
+        // Create a client without a storage backend
+        let mut client = mixnet::MixnetClientBuilder::new()
+            .config(config)
+            .build::<mixnet::EmptyReplyStorage>()
+            .await
+            .unwrap();
+
+        // In this we want to provide our own gateway config struct, and handle persisting this info to disk
+        // ourselves (e.g., as part of our own configuration file).
+        client.register_and_authenticate_gateway().await.unwrap();
         mock_storage.write(client.get_keys(), client.get_gateway_endpoint().unwrap());
+        client
     } else {
         let (keys, gateway_config) = mock_storage.read();
-        client.set_keys(keys);
-        client.set_gateway_endpoint(gateway_config);
-    }
+
+        // Create a client without a storage backend, but with explicitly set keys and gateway
+        // configuration. This creates the client in a registered state.
+        let client = mixnet::MixnetClientBuilder::new()
+            .config(config)
+            .keys(keys)
+            .gateway_config(gateway_config)
+            .build::<mixnet::EmptyReplyStorage>()
+            .await
+            .unwrap();
+        client
+    };
 
     // Connect to the mixnet, now we're listening for incoming
-    let client = client.connect_to_mixnet().await.unwrap();
+    let mut client = client.connect_to_mixnet().await.unwrap();
 
     // Be able to get our client address
-    println!("Our client address is {}", client.nym_address());
+    let our_address = client.nym_address();
+    println!("Our client nym address is: {our_address}");
 
     // Send important info up the pipe to a buddy
-    let recipient = mixnet::Recipient::try_from_base58_string("foo.bar@blah").unwrap();
-    client.send_str(recipient, "flappappa").await;
+    client.send_str(*our_address, "hello there").await;
+
+    println!("Waiting for message");
+    if let Some(received) = client.wait_for_messages().await {
+        for r in received {
+            println!("Received: {}", String::from_utf8_lossy(&r.message));
+        }
+    }
+
+    client.disconnect().await;
 }
 
 #[allow(unused)]
@@ -53,7 +74,7 @@ impl MockStorage {
     }
 
     fn write(&mut self, _keys: mixnet::KeysArc, _gateway_config: &mixnet::GatewayEndpointConfig) {
-        todo!();
+        log::info!("todo");
     }
 
     fn empty() -> Self {

sdk/rust/nym-sdk/examples/persist_keys.rs

@@ -5,7 +5,7 @@ async fn main() {
     logging::setup_logging();
 
     // Passing no config makes the client fire up an ephemeral session and figure shit out on its own
-    let mut client = mixnet::MixnetClient::connect().await.unwrap();
+    let mut client = mixnet::MixnetClient::connect_new().await.unwrap();
 
     // Be able to get our client address
     let our_address = client.nym_address();

sdk/rust/nym-sdk/examples/simple.rs

@@ -31,6 +31,8 @@ pub enum Error {
          supported, and likely and user mistake"
     )]
     ReregisteringGatewayNotSupported,
+    #[error("no gateway key set")]
+    NoGatewayKeySet,
 }
 
 pub type Result<T, E = Error> = std::result::Result<T, E>;

sdk/rust/nym-sdk/examples/simple_but_manually_connect.rs

@@ -10,7 +10,7 @@
 //! async fn main() {
 //!     // Passing no config makes the client fire up an ephemeral session and figure stuff out on
 //!     // its own
-//!     let mut client = mixnet::MixnetClient::connect().await.unwrap();
+//!     let mut client = mixnet::MixnetClient::connect_new().await.unwrap();
 //!
 //!     // Be able to get our client address
 //!     let our_address = client.nym_address();
@@ -36,8 +36,14 @@ mod connection_state;
 mod keys;
 mod paths;
 
-pub use client::{MixnetClient, MixnetClientBuilder};
-pub use client_core::config::GatewayEndpointConfig;
+pub use client::{DisconnectedMixnetClient, MixnetClient, MixnetClientBuilder, MixnetClientSender};
+pub use client_core::{
+    client::{
+        inbound_messages::InputMessage,
+        replies::reply_storage::{fs_backend::Backend as ReplyStorage, Empty as EmptyReplyStorage},
+    },
+    config::GatewayEndpointConfig,
+};
 pub use config::Config;
 pub use keys::{Keys, KeysArc};
 pub use nymsphinx::{