diff --git a/iroh-cli/src/commands/blobs.rs b/iroh-cli/src/commands/blobs.rs index a5c07f0e82..a86869d2d1 100644 --- a/iroh-cli/src/commands/blobs.rs +++ b/iroh-cli/src/commands/blobs.rs @@ -1,9 +1,4 @@ -use std::{ - collections::{BTreeMap, HashMap}, - net::SocketAddr, - path::PathBuf, - time::Duration, -}; +//! Define blob-related commands. use anyhow::{anyhow, bail, ensure, Context, Result}; use clap::Subcommand; @@ -34,8 +29,15 @@ use iroh::{ }, net::{key::PublicKey, relay::RelayUrl, NodeAddr}, }; +use std::{ + collections::{BTreeMap, HashMap}, + net::SocketAddr, + path::PathBuf, + time::Duration, +}; use tokio::io::AsyncWriteExt; +/// Subcommands for the blob command. #[allow(clippy::large_enum_variant)] #[derive(Subcommand, Debug, Clone)] pub enum BlobCommands { @@ -160,6 +162,7 @@ pub enum BlobCommands { }, } +/// Possible outcomes of an input. #[derive(Debug, Clone, derive_more::Display)] pub enum TicketOrHash { Ticket(BlobTicket), @@ -181,6 +184,7 @@ impl std::str::FromStr for TicketOrHash { } impl BlobCommands { + /// Runs the blob command given the iroh client. pub async fn run(self, iroh: &Iroh) -> Result<()> { match self { Self::Get { @@ -437,6 +441,7 @@ pub struct BlobAddOptions { pub no_ticket: bool, } +/// Possible list subcommands. #[derive(Subcommand, Debug, Clone)] pub enum ListCommands { /// List the available blobs on the running provider. @@ -448,6 +453,7 @@ pub enum ListCommands { } impl ListCommands { + /// Runs a list subcommand. pub async fn run(self, iroh: &Iroh) -> Result<()> { match self { Self::Blobs => { @@ -494,6 +500,7 @@ impl ListCommands { } } +/// Possible delete subcommands. #[derive(Subcommand, Debug, Clone)] pub enum DeleteCommands { /// Delete the given blobs @@ -505,6 +512,7 @@ pub enum DeleteCommands { } impl DeleteCommands { + /// Runs the delete command. pub async fn run(self, iroh: &Iroh) -> Result<()> { match self { Self::Blob { hash } => { @@ -518,6 +526,7 @@ impl DeleteCommands { } } +/// Returns the corresponding [`ReportLevel`] given the verbosity level. fn get_report_level(verbose: u8) -> ReportLevel { match verbose { 0 => ReportLevel::Warn, @@ -526,6 +535,7 @@ fn get_report_level(verbose: u8) -> ReportLevel { } } +/// Applies the report level to the given text. fn apply_report_level(text: String, level: ReportLevel) -> console::StyledObject { match level { ReportLevel::Trace => style(text).dim(), @@ -535,6 +545,7 @@ fn apply_report_level(text: String, level: ReportLevel) -> console::StyledObject } } +/// Checks the consistency of the blobs on the running node, and repairs inconsistencies if instructed. pub async fn consistency_check(iroh: &Iroh, verbose: u8, repair: bool) -> Result<()> { let mut response = iroh.blobs().consistency_check(repair).await?; let verbosity = get_report_level(verbose); @@ -576,6 +587,7 @@ pub async fn consistency_check(iroh: &Iroh, verbose: u8, repair: bool) -> Result Ok(()) } +/// Checks the validity of the blobs on the running node, and repairs anything invalid if instructed. pub async fn validate(iroh: &Iroh, verbose: u8, repair: bool) -> Result<()> { let mut state = ValidateProgressState::new(); let mut response = iroh.blobs().validate(repair).await?; @@ -661,6 +673,7 @@ pub async fn validate(iroh: &Iroh, verbose: u8, repair: bool) -> Result<()> { Ok(()) } +/// Collection of all the validation progress state. struct ValidateProgressState { mp: MultiProgress, pbs: HashMap, @@ -671,6 +684,7 @@ struct ValidateProgressState { } impl ValidateProgressState { + /// Creates a new validation progress state collection. fn new() -> Self { let mp = MultiProgress::new(); let overall = mp.add(ProgressBar::new(0)); @@ -685,6 +699,7 @@ impl ValidateProgressState { } } + /// Sets the total number to the provided value and style the progress bar to starting. fn starting(&mut self, total: u64) { self.total = total; self.errors = 0; @@ -699,6 +714,7 @@ impl ValidateProgressState { ); } + /// Adds a message to the progress bar in the given `id`. fn add_entry(&mut self, id: u64, hash: Hash, path: Option, size: u64) { let pb = self.mp.insert_before(&self.overall, ProgressBar::new(size)); pb.set_style(ProgressStyle::default_bar() @@ -716,18 +732,21 @@ impl ValidateProgressState { self.pbs.insert(id, pb); } + /// Progresses the progress bar with `id` by `progress` amount. fn progress(&mut self, id: u64, progress: u64) { if let Some(pb) = self.pbs.get_mut(&id) { pb.set_position(progress); } } + /// Set an error in the progress bar. Consumes the [`ValidateProgressState`]. fn abort(self, error: String) { let error_line = self.mp.add(ProgressBar::new(0)); error_line.set_style(ProgressStyle::default_bar().template("{msg}").unwrap()); error_line.set_message(error); } + /// Finishes a progress bar with a given error message. fn done(&mut self, id: u64, error: Option) { if let Some(pb) = self.pbs.remove(&id) { let ok_char = style(Emoji("✔", "OK")).green(); @@ -796,6 +815,7 @@ pub enum TicketOption { Print, } +/// Adds a [`BlobSource`] given some [`BlobAddOptions`]. pub async fn add_with_opts( client: &iroh::client::Iroh, source: BlobSource, @@ -828,7 +848,7 @@ pub async fn add_with_opts( add(client, source, tag, ticket, wrap).await } -/// Add data to iroh, either from a path or, if path is `None`, from STDIN. +/// Adds data to iroh, either from a path or, if path is `None`, from STDIN. pub async fn add( client: &iroh::client::Iroh, source: BlobSourceIroh, @@ -877,6 +897,7 @@ pub async fn add( Ok(()) } +/// Entry with a given name, size, and hash. #[derive(Debug)] pub struct ProvideResponseEntry { pub name: String, @@ -884,6 +905,7 @@ pub struct ProvideResponseEntry { pub hash: Hash, } +/// Combines the [`AddProgress`] outputs from a [`Stream`] into a single tuple. pub async fn aggregate_add_response( mut stream: impl Stream> + Unpin, ) -> Result<(Hash, BlobFormat, Vec)> { @@ -947,6 +969,7 @@ pub async fn aggregate_add_response( Ok((hash, format, entries)) } +/// Prints out the add response. pub fn print_add_response(hash: Hash, format: BlobFormat, entries: Vec) { let mut total_size = 0; for ProvideResponseEntry { name, size, hash } in entries { @@ -961,6 +984,7 @@ pub fn print_add_response(hash: Hash, format: BlobFormat, entries: Vec Self { Self { mp: MultiProgress::new(), @@ -975,6 +1000,7 @@ impl ProvideProgressState { } } + /// Inserts a new progress bar with the given id, name, and size. fn found(&mut self, name: String, id: u64, size: u64) { let pb = self.mp.add(ProgressBar::new(size)); pb.set_style(ProgressStyle::default_bar() @@ -987,12 +1013,14 @@ impl ProvideProgressState { self.pbs.insert(id, pb); } + /// Adds some progress to the progress bar with the given id. fn progress(&mut self, id: u64, progress: u64) { if let Some(pb) = self.pbs.get_mut(&id) { pb.set_position(progress); } } + /// Sets the multiprogress bar with the given id as finished and clear it. fn done(&mut self, id: u64, _hash: Hash) { if let Some(pb) = self.pbs.remove(&id) { pb.finish_and_clear(); @@ -1000,15 +1028,18 @@ impl ProvideProgressState { } } + /// Sets the multiprogress bar as finished and clear them. fn all_done(self) { self.mp.clear().ok(); } + /// Clears the multiprogress bar. fn error(self) { self.mp.clear().ok(); } } +/// Displays the download progress for a given stream. pub async fn show_download_progress( hash: Hash, mut stream: impl Stream> + Unpin, @@ -1124,6 +1155,7 @@ impl From for OutputTarget { } } +/// Creates a [`ProgressBar`] with some defaults for the overall progress. fn make_overall_progress() -> ProgressBar { let pb = ProgressBar::hidden(); pb.enable_steady_tick(std::time::Duration::from_millis(100)); @@ -1137,6 +1169,7 @@ fn make_overall_progress() -> ProgressBar { pb } +/// Creates a [`ProgressBar`] with some defaults for the individual progress. fn make_individual_progress() -> ProgressBar { let pb = ProgressBar::hidden(); pb.enable_steady_tick(std::time::Duration::from_millis(100));