From eff97b4eb39e6174d2f085c4c4f9bf7bd7b39660 Mon Sep 17 00:00:00 2001 From: Kasey Huizinga Date: Fri, 2 Aug 2024 13:47:33 -0400 Subject: [PATCH 1/3] add documentations and examples for the `iroh::node::Client` --- Cargo.lock | 1 + iroh/Cargo.toml | 3 ++ iroh/src/client/node.rs | 81 ++++++++++++++++++++++++++++++++++++++++- 3 files changed, 84 insertions(+), 1 deletion(-) diff --git a/Cargo.lock b/Cargo.lock index af8e7a5224..32932a5825 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2525,6 +2525,7 @@ dependencies = [ "tokio-util", "tracing", "tracing-subscriber", + "url", "walkdir", ] diff --git a/iroh/Cargo.toml b/iroh/Cargo.toml index d31990e63f..e779b16488 100644 --- a/iroh/Cargo.toml +++ b/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"] diff --git a/iroh/src/client/node.rs b/iroh/src/client/node.rs index 265d3c2a00..8efbcc1c4c 100644 --- a/iroh/src/client/node.rs +++ b/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 = node.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 = node.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 { From 14cbfb122f7fa42da11dba4e95c736928ab6f050 Mon Sep 17 00:00:00 2001 From: Kasey Huizinga Date: Mon, 5 Aug 2024 08:56:19 -0400 Subject: [PATCH 2/3] fix typo --- iroh/src/client/node.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/iroh/src/client/node.rs b/iroh/src/client/node.rs index 8efbcc1c4c..09fc7f6238 100644 --- a/iroh/src/client/node.rs +++ b/iroh/src/client/node.rs @@ -76,7 +76,7 @@ use super::{flatten, RpcClient}; /// # Ok(()) /// # } /// ``` -/// You can also use the `node:Client` methods from the `Iroh` client: +/// You can also use the `node::Client` methods from the `Iroh` client: /// /// ``` /// use std::str::FromStr; From d811365e27f5025b0c6389272d88d90836a25480 Mon Sep 17 00:00:00 2001 From: Kasey Huizinga Date: Mon, 5 Aug 2024 12:24:52 -0400 Subject: [PATCH 3/3] fix doc test --- iroh/src/client/node.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/iroh/src/client/node.rs b/iroh/src/client/node.rs index 09fc7f6238..c12c5bd5bb 100644 --- a/iroh/src/client/node.rs +++ b/iroh/src/client/node.rs @@ -54,7 +54,7 @@ use super::{flatten, RpcClient}; /// // 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 = node.client().node(); +/// 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?; @@ -87,7 +87,7 @@ use super::{flatten, RpcClient}; /// // Create an iroh node: /// let iroh = iroh::node::Node::memory().spawn().await?; /// // Create a client: -/// let client = node.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?;