From d4c1bc829f8dc0879dec59abd87ef82a2f336e75 Mon Sep 17 00:00:00 2001 From: Kasey Date: Fri, 14 Oct 2022 11:35:19 -0400 Subject: [PATCH 1/2] docs: add full help text for `lookup`, `connect`, `get`, `p2p`, and `iroh` commands --- iroh/src/p2p.rs | 43 +++++++++++++++++++++++++++++++-- iroh/src/run.rs | 64 +++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 103 insertions(+), 4 deletions(-) diff --git a/iroh/src/p2p.rs b/iroh/src/p2p.rs index a6bddff037..2c24b12ebd 100644 --- a/iroh/src/p2p.rs +++ b/iroh/src/p2p.rs @@ -5,7 +5,11 @@ use clap::{Args, Subcommand}; use iroh_api::{Multiaddr, P2pApi, PeerId, PeerIdOrAddr}; #[derive(Args, Debug, Clone)] -#[clap(about = "Manage peer-2-peer networking.")] +#[clap(about = "Peer-2-peer commands")] +#[clap( + after_help = "p2p commands all relate to peer-2-peer connectivity. See subcommands for +additional details." +)] pub struct P2p { #[clap(subcommand)] command: P2pCommands, @@ -13,8 +17,40 @@ pub struct P2p { #[derive(Subcommand, Debug, Clone)] pub enum P2pCommands { + #[clap(about = "Connect to a peer")] + #[clap(after_help = " +Attempts to open a new direct connection to a peer address. By default p2p +continulously maintains an open set of peer connections based on requests & +internal hueristics. Connect is useful in situations where it makes sense to +manually force libp2p to dial a known peer. A common example includes when you +know the multiaddr or peer ID of a peer that you would like to exchange data +with. + +The address format is in multiaddr format. For example: + + > iroh p2p connect /ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ + +for more info on multiaddrs see https://iroh.computer/docs/concepts#multiaddr + +If a peer ID is provided, connect first perform a distribtued hash table (DHT) +lookup to learn the address of the given peer ID before dialing.")] + Connect { + /// Multiaddr or peer ID of a peer to connect to + addr: PeerIdOrAddrArg, + }, #[clap(about = "Retrieve info about a node")] - Lookup { addr: PeerIdOrAddrArg }, + #[clap( + after_help = "Takes as input a peer ID or address and prints the output of the libp2p-identify +protocol. When provided with a peer ID, the address is looked up on the +Network's Distributed Hash Table (DHT) before connecting to the node. When +provided with a multiaddress, the connection is dialed directly. + +Providing no argument will return your local node information." + )] + Lookup { + /// multiaddress or peer ID + addr: PeerIdOrAddrArg, + }, } #[derive(Debug, Clone)] @@ -35,6 +71,9 @@ impl FromStr for PeerIdOrAddrArg { pub async fn run_command(p2p: &impl P2pApi, cmd: &P2p) -> Result<()> { match &cmd.command { + P2pCommands::Connect { .. } => { + todo!("`iroh p2p connect` is not yet implemented") + } P2pCommands::Lookup { addr } => { let lookup = p2p.lookup(&addr.0).await?; println!("peer id: {}", lookup.peer_id); diff --git a/iroh/src/run.rs b/iroh/src/run.rs index 438397a0f5..3de3a5d09b 100644 --- a/iroh/src/run.rs +++ b/iroh/src/run.rs @@ -10,7 +10,19 @@ use iroh_api::{Api, ApiExt, IpfsPath, Iroh}; use iroh_metrics::config::Config as MetricsConfig; #[derive(Parser, Debug, Clone)] -#[clap(version, about, long_about = None, propagate_version = true)] +#[clap(version, long_about = None, propagate_version = true)] +#[clap(about = "A next generation IPFS implementation: https://iroh.computer")] +#[clap( + after_help = "Iroh is a next-generation implementation the Interplanetary File System (IPFS). +IPFS is a networking protocol for exchanging content-addressed blocks of +immutable data. 'content-addressed' means referring to data by the hash of it's +content, which makes the reference both unique and verifiable. These two +properties make it possible to get data from any node in the network that speaks +the IPFS protocol, including IPFS content being served by other implementations +of the protocol. + +For more info see https://iroh.computer/docs" +)] pub struct Cli { #[clap(long)] cfg: Option, @@ -33,9 +45,43 @@ impl Cli { enum Commands { // status checks the health of the different processes #[clap(about = "Check the health of the different iroh processes.")] + #[clap( + after_help = "status reports the current operational setup of iroh. Use status as a go-to +command for understanding where iroh commands are being processed. different +ops configurations utilize different network and service implementations +under the hood, which can lead to varying performance characteristics. + +Status reports connectivity, which is either offline or online: + + offline: iroh is not connected to any background process, all commands + are one-off, any network connections are closed when a command + completes. Some network duties may be delegated to remote hosts. + + online: iroh has found a long-running process to issue commands to. Any + comand issued will be deletegated to the long-running process as a + remote procedure call + +If iroh is online, status also reports the service configuration of the +long running process, including the health of the configured subsystem(s). +Possible configurations fall into two buckets: + + one: Iroh is running with all services bundled into one single process, + this setup is common in desktop enviornments. + + cloud: Iroh is running with services split into separate processes, which + are speaking to each other via remote procedure calls. + +Use the --watch flag to continually poll for changes. + +Status reports no metrics about the running system aside from current service +health. Instead all metrics are emitted through uniform tracing collection & +reporting, which is intended to be consumed by tools like prometheus and +grafana. For more info on metrics collection, see +https://iroh.computer/docs/metrics" + )] Status { #[clap(short, long)] - /// when true, updates the status table whenever a change in a process's status occurs + /// Poll process for changes watch: bool, }, P2p(P2p), @@ -51,6 +97,20 @@ enum Commands { no_wrap: bool, }, #[clap(about = "Fetch IPFS content and write it to disk")] + #[clap( + after_help = "Download file or directory specified by from IPFS into [path]. If +path already exists and is a file then it's overwritten with the new downloaded +file. If path already exists and is a directory, the command fails with an +error. If path already exists, is a file and the downloaded data is a directory, +that's an error. + +By default, the output will be written to the working directory. If no file or +directory name can be derived from the , the output will be written +to the given path's CID. + +If is already present in the iroh store, no network call will +be made." + )] Get { /// CID or CID/with/path/qualifier to get ipfs_path: IpfsPath, From 6aba07b476147710a73f89579769136ba0b90f42 Mon Sep 17 00:00:00 2001 From: b5 Date: Fri, 14 Oct 2022 20:24:31 -0400 Subject: [PATCH 2/2] move long descriptions into constants --- iroh/src/doc.rs | 83 +++++++++++++++++++++++++++++++++++++++++++++++++ iroh/src/lib.rs | 1 + iroh/src/p2p.rs | 30 +++--------------- iroh/src/run.rs | 63 +++---------------------------------- 4 files changed, 92 insertions(+), 85 deletions(-) create mode 100644 iroh/src/doc.rs diff --git a/iroh/src/doc.rs b/iroh/src/doc.rs new file mode 100644 index 0000000000..bc74577923 --- /dev/null +++ b/iroh/src/doc.rs @@ -0,0 +1,83 @@ +pub const IROH_LONG_DESCRIPTION: &str = " +Iroh is a next-generation implementation the Interplanetary File System (IPFS). +IPFS is a networking protocol for exchanging content-addressed blocks of +immutable data. 'content-addressed' means referring to data by the hash of it's +content, which makes the reference both unique and verifiable. These two +properties make it possible to get data from any node in the network that speaks +the IPFS protocol, including IPFS content being served by other implementations +of the protocol. + +For more info see https://iroh.computer/docs"; + +pub const STATUS_LONG_DESCRIPTION: &str = " +status reports the current operational setup of iroh. Use status as a go-to +command for understanding where iroh commands are being processed. different +ops configurations utilize different network and service implementations +under the hood, which can lead to varying performance characteristics. + +Status reports connectivity, which is either offline or online: + + offline: iroh is not connected to any background process, all commands + are one-off, any network connections are closed when a command + completes. Some network duties may be delegated to remote hosts. + + online: iroh has found a long-running process to issue commands to. Any + comand issued will be deletegated to the long-running process as a + remote procedure call + +If iroh is online, status also reports the service configuration of the +long running process, including the health of the configured subsystem(s). +Possible configurations fall into two buckets: + + one: Iroh is running with all services bundled into one single process, + this setup is common in desktop enviornments. + + cloud: Iroh is running with services split into separate processes, which + are speaking to each other via remote procedure calls. + +Use the --watch flag to continually poll for changes. + +Status reports no metrics about the running system aside from current service +health. Instead all metrics are emitted through uniform tracing collection & +reporting, which is intended to be consumed by tools like prometheus and +grafana. For more info on metrics collection, see +https://iroh.computer/docs/metrics"; + +pub const GET_LONG_DESCRIPTION: &str = " +Download file or directory specified by from IPFS into [path]. If +path already exists and is a file then it's overwritten with the new downloaded +file. If path already exists and is a directory, the command fails with an +error. If path already exists, is a file and the downloaded data is a directory, +that's an error. + +By default, the output will be written to the working directory. If no file or +directory name can be derived from the , the output will be written +to the given path's CID. + +If is already present in the iroh store, no network call will +be made."; + +pub const P2P_CONNECT_LONG_DESCRIPTION: &str = " +Attempts to open a new direct connection to a peer address. By default p2p +continulously maintains an open set of peer connections based on requests & +internal hueristics. Connect is useful in situations where it makes sense to +manually force libp2p to dial a known peer. A common example includes when you +know the multiaddr or peer ID of a peer that you would like to exchange data +with. + +The address format is in multiaddr format. For example: + + > iroh p2p connect /ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ + +for more info on multiaddrs see https://iroh.computer/docs/concepts#multiaddr + +If a peer ID is provided, connect first perform a distribtued hash table (DHT) +lookup to learn the address of the given peer ID before dialing."; + +pub const P2P_LOOKUP_LONG_DESCRIPTION: &str = " +Takes as input a peer ID or address and prints the output of the libp2p-identify +protocol. When provided with a peer ID, the address is looked up on the +Network's Distributed Hash Table (DHT) before connecting to the node. When +provided with a multiaddress, the connection is dialed directly. + +Providing no argument will return your local node information."; diff --git a/iroh/src/lib.rs b/iroh/src/lib.rs index 8a2ce9d7c9..5a1c1bab2a 100644 --- a/iroh/src/lib.rs +++ b/iroh/src/lib.rs @@ -1,3 +1,4 @@ +pub mod doc; #[cfg(feature = "testing")] mod fixture; pub mod metrics; diff --git a/iroh/src/p2p.rs b/iroh/src/p2p.rs index 2c24b12ebd..a6a32b3050 100644 --- a/iroh/src/p2p.rs +++ b/iroh/src/p2p.rs @@ -1,8 +1,8 @@ -use std::str::FromStr; - +use crate::doc; use anyhow::{Error, Result}; use clap::{Args, Subcommand}; use iroh_api::{Multiaddr, P2pApi, PeerId, PeerIdOrAddr}; +use std::str::FromStr; #[derive(Args, Debug, Clone)] #[clap(about = "Peer-2-peer commands")] @@ -18,35 +18,13 @@ pub struct P2p { #[derive(Subcommand, Debug, Clone)] pub enum P2pCommands { #[clap(about = "Connect to a peer")] - #[clap(after_help = " -Attempts to open a new direct connection to a peer address. By default p2p -continulously maintains an open set of peer connections based on requests & -internal hueristics. Connect is useful in situations where it makes sense to -manually force libp2p to dial a known peer. A common example includes when you -know the multiaddr or peer ID of a peer that you would like to exchange data -with. - -The address format is in multiaddr format. For example: - - > iroh p2p connect /ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ - -for more info on multiaddrs see https://iroh.computer/docs/concepts#multiaddr - -If a peer ID is provided, connect first perform a distribtued hash table (DHT) -lookup to learn the address of the given peer ID before dialing.")] + #[clap(after_help = doc::P2P_CONNECT_LONG_DESCRIPTION)] Connect { /// Multiaddr or peer ID of a peer to connect to addr: PeerIdOrAddrArg, }, #[clap(about = "Retrieve info about a node")] - #[clap( - after_help = "Takes as input a peer ID or address and prints the output of the libp2p-identify -protocol. When provided with a peer ID, the address is looked up on the -Network's Distributed Hash Table (DHT) before connecting to the node. When -provided with a multiaddress, the connection is dialed directly. - -Providing no argument will return your local node information." - )] + #[clap(after_help = doc::P2P_LOOKUP_LONG_DESCRIPTION)] Lookup { /// multiaddress or peer ID addr: PeerIdOrAddrArg, diff --git a/iroh/src/run.rs b/iroh/src/run.rs index 3de3a5d09b..ecb2616d0f 100644 --- a/iroh/src/run.rs +++ b/iroh/src/run.rs @@ -1,6 +1,7 @@ use std::collections::HashMap; use std::path::PathBuf; +use crate::doc; #[cfg(feature = "testing")] use crate::fixture::get_fixture_api; use crate::p2p::{run_command as run_p2p_command, P2p}; @@ -12,17 +13,7 @@ use iroh_metrics::config::Config as MetricsConfig; #[derive(Parser, Debug, Clone)] #[clap(version, long_about = None, propagate_version = true)] #[clap(about = "A next generation IPFS implementation: https://iroh.computer")] -#[clap( - after_help = "Iroh is a next-generation implementation the Interplanetary File System (IPFS). -IPFS is a networking protocol for exchanging content-addressed blocks of -immutable data. 'content-addressed' means referring to data by the hash of it's -content, which makes the reference both unique and verifiable. These two -properties make it possible to get data from any node in the network that speaks -the IPFS protocol, including IPFS content being served by other implementations -of the protocol. - -For more info see https://iroh.computer/docs" -)] +#[clap(after_help = doc::IROH_LONG_DESCRIPTION)] pub struct Cli { #[clap(long)] cfg: Option, @@ -45,40 +36,7 @@ impl Cli { enum Commands { // status checks the health of the different processes #[clap(about = "Check the health of the different iroh processes.")] - #[clap( - after_help = "status reports the current operational setup of iroh. Use status as a go-to -command for understanding where iroh commands are being processed. different -ops configurations utilize different network and service implementations -under the hood, which can lead to varying performance characteristics. - -Status reports connectivity, which is either offline or online: - - offline: iroh is not connected to any background process, all commands - are one-off, any network connections are closed when a command - completes. Some network duties may be delegated to remote hosts. - - online: iroh has found a long-running process to issue commands to. Any - comand issued will be deletegated to the long-running process as a - remote procedure call - -If iroh is online, status also reports the service configuration of the -long running process, including the health of the configured subsystem(s). -Possible configurations fall into two buckets: - - one: Iroh is running with all services bundled into one single process, - this setup is common in desktop enviornments. - - cloud: Iroh is running with services split into separate processes, which - are speaking to each other via remote procedure calls. - -Use the --watch flag to continually poll for changes. - -Status reports no metrics about the running system aside from current service -health. Instead all metrics are emitted through uniform tracing collection & -reporting, which is intended to be consumed by tools like prometheus and -grafana. For more info on metrics collection, see -https://iroh.computer/docs/metrics" - )] + #[clap(after_help = doc::STATUS_LONG_DESCRIPTION)] Status { #[clap(short, long)] /// Poll process for changes @@ -97,20 +55,7 @@ https://iroh.computer/docs/metrics" no_wrap: bool, }, #[clap(about = "Fetch IPFS content and write it to disk")] - #[clap( - after_help = "Download file or directory specified by from IPFS into [path]. If -path already exists and is a file then it's overwritten with the new downloaded -file. If path already exists and is a directory, the command fails with an -error. If path already exists, is a file and the downloaded data is a directory, -that's an error. - -By default, the output will be written to the working directory. If no file or -directory name can be derived from the , the output will be written -to the given path's CID. - -If is already present in the iroh store, no network call will -be made." - )] + #[clap(after_help = doc::GET_LONG_DESCRIPTION )] Get { /// CID or CID/with/path/qualifier to get ipfs_path: IpfsPath,