Merge pull request #2542 from b-zee/refactor-docs-autonomi

Refactor autonomi client API

.github/workflows/merge.yml

@@ -125,11 +125,11 @@ jobs:
 
       - name: Run autonomi tests
         timeout-minutes: 25
-        run: cargo test --release --package autonomi --features full --lib
+        run: cargo test --release --package autonomi --features full,local --lib
 
       - name: Run autonomi doc tests
         timeout-minutes: 25
-        run: cargo test --release --package autonomi --features full --doc
+        run: cargo test --release --package autonomi --features full,local --doc
 
       - name: Run bootstrap tests
         timeout-minutes: 25

autonomi/Cargo.toml

@@ -13,9 +13,13 @@ repository = "https://github.com/maidsafe/autonomi"
 name = "autonomi"
 crate-type = ["cdylib", "rlib"]
 
+[[example]]
+name = "data_and_archive"
+required-features = ["full"]
+
 [[example]]
 name = "put_and_dir_upload"
-features = ["full"]
+required-features = ["full"]
 
 [features]
 default = ["vault"]

autonomi/README.md

@@ -134,3 +134,11 @@ Chunk payments address: 0x8464135c8F25Da09e49BC8782676a84730C318bC
 Deployer wallet private key: 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
 Genesis wallet balance: (tokens: 20000000000000000000000000, gas: 9998998011366954730202)
 ```
+
+# WASM
+
+For documentation on WASM, see [./README_WASM.md].
+
+# Python
+
+For documentation on the Python bindings, see [./README_PYTHON.md].

autonomi/examples/data_and_archive.rs

@@ -0,0 +1,37 @@
+use autonomi::{Bytes, Client, Metadata, PrivateArchive};
+use test_utils::evm::get_funded_wallet;
+use tracing_subscriber::{fmt, layer::SubscriberExt, util::SubscriberInitExt, EnvFilter};
+
+#[tokio::main]
+async fn main() -> eyre::Result<()> {
+    tracing_subscriber::registry()
+        .with(fmt::layer())
+        .with(EnvFilter::from_env("RUST_LOG"))
+        .init();
+
+    let client = Client::init().await?;
+    let wallet = get_funded_wallet();
+
+    // Upload 10MiB of random data and verify it by fetching it back.
+    let data = Bytes::from("Hello, World!");
+    let data_map = client.data_put(data.clone(), (&wallet).into()).await?;
+    let data_fetched = client.data_get(data_map.clone()).await?;
+    assert_eq!(data, data_fetched);
+
+    // Upload the data as part of an archive, giving it the name `test.txt`.
+    let mut archive = PrivateArchive::new();
+    archive.add_file(
+        "test.txt".into(),
+        data_map,
+        Metadata::new_with_size(data.len() as u64),
+    );
+
+    // Upload the archive to the network.
+    let archive_data_map = client.archive_put(&archive, (&wallet).into()).await?;
+    let archive_fetched = client.archive_get(archive_data_map).await?;
+    assert_eq!(archive, archive_fetched);
+
+    println!("Archive uploaded successfully");
+
+    Ok(())
+}

autonomi/examples/put_and_dir_upload.rs

@@ -1,12 +1,16 @@
-use autonomi::{Bytes, Client, Wallet};
+use autonomi::{Bytes, Client};
+use test_utils::evm::get_funded_wallet;
+use tracing_subscriber::{fmt, layer::SubscriberExt, util::SubscriberInitExt, EnvFilter};
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    // Default wallet of testnet.
-    let key = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
+    tracing_subscriber::registry()
+        .with(fmt::layer())
+        .with(EnvFilter::from_env("RUST_LOG"))
+        .init();
 
-    let client = Client::init_local().await?;
-    let wallet = Wallet::new_from_private_key(Default::default(), key)?;
+    let client = Client::init().await?;
+    let wallet = get_funded_wallet();
 
     // Put and fetch data.
     let data_addr = client

autonomi/src/client/data/mod.rs

@@ -160,6 +160,19 @@ fn hash_to_short_string(input: &str) -> String {
 
 impl Client {
     /// Fetch a blob of (private) data from the network
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use autonomi::{Client, Bytes};
+    /// # #[tokio::main]
+    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    /// # let client = Client::init().await?;
+    /// # let data_map = todo!();
+    /// let data_fetched = client.data_get(data_map).await?;
+    /// # Ok(())
+    /// # }
+    /// ```
     pub async fn data_get(&self, data_map: DataMapChunk) -> Result<Bytes, GetError> {
         info!(
             "Fetching private data from Data Map {:?}",
@@ -175,6 +188,22 @@ impl Client {
     /// The [`DataMapChunk`] is not uploaded to the network, keeping the data private.
     ///
     /// Returns the [`DataMapChunk`] containing the map to the encrypted chunks.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use autonomi::{Client, Bytes};
+    /// # #[tokio::main]
+    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    /// # let client = Client::init().await?;
+    /// # let wallet = todo!();
+    /// let data = Bytes::from("Hello, World");
+    /// let data_map = client.data_put(data, wallet).await?;
+    /// let data_fetched = client.data_get(data_map).await?;
+    /// assert_eq!(data, data_fetched);
+    /// # Ok(())
+    /// # }
+    /// ```
     pub async fn data_put(
         &self,
         data: Bytes,

autonomi/src/client/files/archive.rs

@@ -142,7 +142,7 @@ impl PrivateArchive {
     }
 
     /// Serialize to bytes.
-    pub fn into_bytes(&self) -> Result<Bytes, rmp_serde::encode::Error> {
+    pub fn to_bytes(&self) -> Result<Bytes, rmp_serde::encode::Error> {
         let root_serialized = rmp_serde::to_vec(&self)?;
         let root_serialized = Bytes::from(root_serialized);
 
@@ -163,11 +163,11 @@ impl Client {
     /// Upload a [`PrivateArchive`] to the network
     pub async fn archive_put(
         &self,
-        archive: PrivateArchive,
+        archive: &PrivateArchive,
         payment_option: PaymentOption,
     ) -> Result<PrivateArchiveAccess, PutError> {
         let bytes = archive
-            .into_bytes()
+            .to_bytes()
             .map_err(|e| PutError::Serialization(format!("Failed to serialize archive: {e:?}")))?;
         let result = self.data_put(bytes, payment_option).await;
         debug!("Uploaded private archive {archive:?} to the network and address is {result:?}");

autonomi/src/client/files/archive_public.rs

@@ -104,7 +104,7 @@ impl PublicArchive {
     }
 
     /// Serialize to bytes.
-    pub fn into_bytes(&self) -> Result<Bytes, rmp_serde::encode::Error> {
+    pub fn to_bytes(&self) -> Result<Bytes, rmp_serde::encode::Error> {
         let root_serialized = rmp_serde::to_vec(&self)?;
         let root_serialized = Bytes::from(root_serialized);
 
@@ -146,17 +146,17 @@ impl Client {
     /// # let wallet = todo!();
     /// let mut archive = PublicArchive::new();
     /// archive.add_file(PathBuf::from("file.txt"), DataAddr::random(&mut rand::thread_rng()), Metadata::new_with_size(0));
-    /// let address = client.archive_put_public(archive, &wallet).await?;
+    /// let address = client.archive_put_public(&archive, &wallet).await?;
     /// # Ok(())
     /// # }
     /// ```
     pub async fn archive_put_public(
         &self,
-        archive: PublicArchive,
+        archive: &PublicArchive,
         wallet: &EvmWallet,
     ) -> Result<ArchiveAddr, PutError> {
         let bytes = archive
-            .into_bytes()
+            .to_bytes()
             .map_err(|e| PutError::Serialization(format!("Failed to serialize archive: {e:?}")))?;
         let result = self.data_put_public(bytes, wallet.into()).await;
         debug!("Uploaded archive {archive:?} to the network and the address is {result:?}");
@@ -166,7 +166,7 @@ impl Client {
     /// Get the cost to upload an archive
     pub async fn archive_cost(&self, archive: PublicArchive) -> Result<AttoTokens, CostError> {
         let bytes = archive
-            .into_bytes()
+            .to_bytes()
             .map_err(|e| CostError::Serialization(format!("Failed to serialize archive: {e:?}")))?;
         let result = self.data_cost(bytes).await;
         debug!("Calculated the cost to upload archive {archive:?} is {result:?}");

autonomi/src/client/files/fs.rs

@@ -173,7 +173,7 @@ impl Client {
         wallet: &EvmWallet,
     ) -> Result<PrivateArchiveAccess, UploadError> {
         let archive = self.dir_upload(dir_path, wallet).await?;
-        let archive_addr = self.archive_put(archive, wallet.into()).await?;
+        let archive_addr = self.archive_put(&archive, wallet.into()).await?;
         Ok(archive_addr)
     }
 

autonomi/src/client/files/fs_public.rs

@@ -118,7 +118,7 @@ impl Client {
         wallet: &EvmWallet,
     ) -> Result<ArchiveAddr, UploadError> {
         let archive = self.dir_upload_public(dir_path, wallet).await?;
-        let archive_addr = self.archive_put_public(archive, wallet).await?;
+        let archive_addr = self.archive_put_public(&archive, wallet).await?;
         Ok(archive_addr)
     }
 

autonomi/src/client/mod.rs

@@ -36,7 +36,6 @@ mod utils;
 
 use ant_bootstrap::{BootstrapCacheConfig, BootstrapCacheStore, PeersArgs};
 pub use ant_evm::Amount;
-
 use ant_evm::EvmNetwork;
 use ant_networking::{interval, multiaddr_is_global, Network, NetworkBuilder, NetworkEvent};
 use ant_protocol::version::IDENTIFY_PROTOCOL_STR;
@@ -74,9 +73,11 @@ pub struct Client {
 }
 
 /// Configuration for [`Client::init_with_config`].
-#[derive(Debug, Clone, Default)]
+#[derive(Debug, Clone)]
 pub struct ClientConfig {
     /// Whether we're expected to connect to a local network.
+    ///
+    /// If `local` feature is enabled, [`ClientConfig::default()`] will set this to `true`.
     pub local: bool,
 
     /// List of peers to connect to.
@@ -85,7 +86,19 @@ pub struct ClientConfig {
     pub peers: Option<Vec<Multiaddr>>,
 }
 
-/// Error returned by [`Client::connect`].
+impl Default for ClientConfig {
+    fn default() -> Self {
+        Self {
+            #[cfg(feature = "local")]
+            local: true,
+            #[cfg(not(feature = "local"))]
+            local: false,
+            peers: None,
+        }
+    }
+}
+
+/// Error returned by [`Client::init`].
 #[derive(Debug, thiserror::Error)]
 pub enum ConnectError {
     /// Did not manage to populate the routing table with enough peers.