From 02f20ab8d7923a9d01dd642d49b2b65bee60f56f Mon Sep 17 00:00:00 2001 From: Benno Zeeman Date: Mon, 16 Dec 2024 16:19:55 +0100 Subject: [PATCH] refactor(autonomi): add docs; expose types; local Use `local` if feature is enabled --- .github/workflows/merge.yml | 4 +-- autonomi/Cargo.toml | 6 +++- autonomi/examples/data_and_archive.rs | 37 +++++++++++++++++++++ autonomi/examples/put_and_dir_upload.rs | 14 +++++--- autonomi/src/client/data/mod.rs | 29 ++++++++++++++++ autonomi/src/client/files/archive_public.rs | 2 +- autonomi/src/client/mod.rs | 17 ++++++++-- autonomi/src/lib.rs | 2 +- autonomi/tests/fs.rs | 7 +--- 9 files changed, 100 insertions(+), 18 deletions(-) create mode 100644 autonomi/examples/data_and_archive.rs diff --git a/.github/workflows/merge.yml b/.github/workflows/merge.yml index 95e456fb67..1d59de2431 100644 --- a/.github/workflows/merge.yml +++ b/.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 diff --git a/autonomi/Cargo.toml b/autonomi/Cargo.toml index d7c424d822..32692f8ca2 100644 --- a/autonomi/Cargo.toml +++ b/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"] diff --git a/autonomi/examples/data_and_archive.rs b/autonomi/examples/data_and_archive.rs new file mode 100644 index 0000000000..07fddd560f --- /dev/null +++ b/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(()) +} diff --git a/autonomi/examples/put_and_dir_upload.rs b/autonomi/examples/put_and_dir_upload.rs index 9b6d7a6a47..4af5e20b11 100644 --- a/autonomi/examples/put_and_dir_upload.rs +++ b/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> { - // 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 diff --git a/autonomi/src/client/data/mod.rs b/autonomi/src/client/data/mod.rs index e1967f0c95..f1b35083b4 100644 --- a/autonomi/src/client/data/mod.rs +++ b/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> { + /// # let client = Client::connect(&[]).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 { 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> { + /// # let client = Client::connect(&[]).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, diff --git a/autonomi/src/client/files/archive_public.rs b/autonomi/src/client/files/archive_public.rs index 0cb6cf2127..f4b487747f 100644 --- a/autonomi/src/client/files/archive_public.rs +++ b/autonomi/src/client/files/archive_public.rs @@ -146,7 +146,7 @@ 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(()) /// # } /// ``` diff --git a/autonomi/src/client/mod.rs b/autonomi/src/client/mod.rs index 88c181f02d..9f315ce765 100644 --- a/autonomi/src/client/mod.rs +++ b/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,6 +86,18 @@ pub struct ClientConfig { pub peers: Option>, } +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::connect`]. #[derive(Debug, thiserror::Error)] pub enum ConnectError { diff --git a/autonomi/src/lib.rs b/autonomi/src/lib.rs index aa95c6f648..81ff866006 100644 --- a/autonomi/src/lib.rs +++ b/autonomi/src/lib.rs @@ -76,7 +76,7 @@ pub use bytes::Bytes; pub use libp2p::Multiaddr; #[doc(inline)] -pub use client::{files::archive::PrivateArchive, Client, ClientConfig}; +pub use client::{files::archive::Metadata, files::archive::PrivateArchive, Client, ClientConfig}; #[cfg(feature = "extension-module")] mod python; diff --git a/autonomi/tests/fs.rs b/autonomi/tests/fs.rs index 941d49cb84..926baeb4fd 100644 --- a/autonomi/tests/fs.rs +++ b/autonomi/tests/fs.rs @@ -93,12 +93,7 @@ async fn file_into_vault() -> Result<()> { let archive = client.archive_get_public(addr).await?; let set_version = 0; client - .write_bytes_to_vault( - archive.into_bytes()?, - wallet.into(), - &client_sk, - set_version, - ) + .write_bytes_to_vault(archive.to_bytes()?, wallet.into(), &client_sk, set_version) .await?; // now assert over the stored account packet