docs(iroh): add documentations and examples for the iroh::node::Client

iroh/Cargo.toml

@@ -59,6 +59,9 @@ indicatif = { version = "0.17", features = ["tokio"], optional = true }
 ref-cast = "1.0.23"
 console = { version = "0.15.5", optional = true }
 
+# Documentation tests
+url = { version = "2.5.0", features = ["serde"] }
+
 [features]
 default = ["metrics", "fs-store"]
 metrics = ["iroh-metrics", "iroh-blobs/metrics"]

iroh/src/client/node.rs

@@ -29,7 +29,86 @@ use crate::rpc_protocol::node::{
 
 use super::{flatten, RpcClient};
 
-/// Iroh node client.
+/// Iroh node Client.
+///
+/// Cheaply clonable and threadsafe. Use the iroh `node::Client` to access the
+/// iroh node methods from a different thread, process, or remote machine.
+/// The [`Iroh`](crate::client::Iroh) client dereferences to a `node::Client`,
+/// so you have access to this api from the [`Iroh`](crate::client::Iroh) client itself.
+///
+/// The `node::Client` api allows you to get information *about* the iroh node,
+/// its status, and connection status to other nodes. It also allows you to
+/// provide address information about *other* nodes to your node.
+///
+/// Obtain an iroh `node::Client` via [`Iroh::node()`](crate::client::Iroh::node).
+///
+/// It also provides a way to [shutdown](Client::shutdown) the entire iroh node.
+///
+/// # Examples
+/// ```
+/// use std::str::FromStr;
+/// use iroh_base::{key::NodeId, node_addr::{RelayUrl, NodeAddr}};
+/// use url::Url;
+///
+/// # async fn run() -> anyhow::Result<()> {
+/// // Create an iroh node:
+/// let iroh = iroh::node::Node::memory().spawn().await?;
+/// // Create a node client, a client that gives you access to `node` subsystem
+/// let node_client = iroh.client().node();
+/// // Get the node status, including its node id, addresses, the version of iroh
+/// // it is running, and more.
+/// let status = node_client.status().await?;
+/// println!("Node status: {status:?}");
+/// // Provide your node an address for another node
+/// let relay_url = RelayUrl::from(Url::parse("https://example.com").unwrap());
+/// let addr = NodeAddr::from_parts(
+///   // the node_id
+///   NodeId::from_str("ae58ff8833241ac82d6ff7611046ed67b5072d142c588d0063e942d9a75502b6").unwrap(),
+///   // the home relay
+///   Some(relay_url),
+///   // the direct addresses
+///   vec!["120.0.0.1:0".parse().unwrap()],
+/// );
+/// node_client.add_node_addr(addr).await?;
+/// // Shut down the node. Passing `true` will force the shutdown, passing in
+/// // `false` will allow the node to shut down gracefully.
+/// node_client.shutdown(false).await?;
+/// # Ok(())
+/// # }
+/// ```
+/// You can also use the `node::Client` methods from the `Iroh` client:
+///
+/// ```
+/// use std::str::FromStr;
+/// use iroh_base::{key::NodeId, node_addr::{RelayUrl, NodeAddr}};
+/// use url::Url;
+///
+/// # async fn run() -> anyhow::Result<()> {
+/// // Create an iroh node:
+/// let iroh = iroh::node::Node::memory().spawn().await?;
+/// // Create a client:
+/// let client = iroh.client();
+/// // Get the node status, including its node id, addresses, the version of iroh
+/// // it is running, and more.
+/// let status = client.status().await?;
+/// println!("Node status: {status:?}");
+/// // Provide your node an address for another node
+/// let relay_url = RelayUrl::from(Url::parse("https://example.com").unwrap());
+/// let addr = NodeAddr::from_parts(
+///   // the node_id
+///   NodeId::from_str("ae58ff8833241ac82d6ff7611046ed67b5072d142c588d0063e942d9a75502b6").unwrap(),
+///   // the home relay
+///   Some(relay_url),
+///   // the direct addresses
+///   vec!["120.0.0.1:0".parse().unwrap()],
+/// );
+/// client.add_node_addr(addr).await?;
+/// // Shut down the node. Passing `true` will force the shutdown, passing in
+/// // `false` will allow the node to shut down gracefully.
+/// client.shutdown(false).await?;
+/// # Ok(())
+/// # }
+/// ```
 #[derive(Debug, Clone, RefCast)]
 #[repr(transparent)]
 pub struct Client {