feat: improve transfer, publish, resolve examples (#3296)

Frando · web-flow · commit 30577d3094f7 · 2025-05-12T11:44:11.000Z
## Description This improves the `transfer`, `publish` and `resolve` examples, which we often use for dogfooding new releases. #### `transfer` example: * Set `prod` or `staging` environments with a single arg, while still optionally allowing to override relay, pkarr, and DNS servers. * Add a `dev` environment that uses locally running `iroh-relay` and `iroh-dns-server` instances, for easily using the example with a locally running dev setup of all services. * Optionally enable mDNS discovery * Print connection type changes * Allow reusing a node id by setting `IROH_SECRET` environment variable * Improve help and print output * Improve code to not duplicate endpoint setup and arguments between fetch and provide side Here's the new help text and output: <details> <summary>Help text for provide</summary> ``` $ cargo run --release --example transfer --all-features -- provide --help Provide data Usage: transfer provide [OPTIONS] Options: --size <SIZE> [default: 100M] -e, --env <ENV> Set the environment for relay, pkarr, and DNS servers. If other options are set, those will override the environment defaults. [default: staging] Possible values: - prod: Use the production servers hosted by number0 - staging: Use the staging servers hosted by number0 - dev: Use localhost servers --relay-url <RELAY_URL> Set one or more relay servers to use --no-relay Disable relays completely --relay-only If set no direct connections will be established --pkarr-relay-url <PKARR_RELAY_URL> Use a custom pkarr server --no-pkarr-publish Disable publishing node info to pkarr --dns-origin-domain <DNS_ORIGIN_DOMAIN> Use a custom domain when resolving node info via DNS --dns-server <DNS_SERVER> Use a custom DNS server for resolving relay and node info domains --no-dns-resolve Do not resolve node info via DNS --mdns Enable mDNS discovery -h, --help Print help (see a summary with '-h') ``` </details> <details> <summary>Help text for fetch</summary> ``` $ cargo run -q --release --example transfer --all-features -- fetch --help Fetch data Usage: transfer fetch [OPTIONS] <TICKET> Arguments: <TICKET> Options: -e, --env <ENV> Set the environment for relay, pkarr, and DNS servers. If other options are set, those will override the environment defaults. [default: staging] Possible values: - prod: Use the production servers hosted by number0 - staging: Use the staging servers hosted by number0 - dev: Use localhost servers --relay-url <RELAY_URL> Set one or more relay servers to use --no-relay Disable relays completely --relay-only If set no direct connections will be established --pkarr-relay-url <PKARR_RELAY_URL> Use a custom pkarr server --no-pkarr-publish Disable publishing node info to pkarr --dns-origin-domain <DNS_ORIGIN_DOMAIN> Use a custom domain when resolving node info via DNS --dns-server <DNS_SERVER> Use a custom DNS server for resolving relay and node info domains --no-dns-resolve Do not resolve node info via DNS --mdns Enable mDNS discovery -h, --help Print help (see a summary with '-h') ``` </details> <details> <summary>Output on provide side</summary> ``` $ cargo -q run --release --example transfer --all-features -- provide -e staging Our node id: fdeb67bd2995cbdf1844e1170b01848af5e6b13beb4d754ec86dd38b4ecdae3a Our direct addresses: 78.xx.xx.xx:44377 (type: Stun) 192.168.xxx.xxx:44377 (type: Local) Our home relay server: https://staging-euw1-1.relay.iroh.network./ Ticket with our home relay and direct addresses: nodead66wz55[redacted] Ticket with our home relay but no direct addresses: nodead66wz55fgk4xxyyitqrocybqsfplzvrhpvu25kozbw5hc2ozwxduajlnb2hi4dthixs643umftws3thfvsxk5zrfuys44tfnrqxsltjojxwqltomv2ho33snmxc6aa Ticket with only our node id: nodead66wz55fgk4xxyyitqrocybqsfplzvrhpvu25kozbw5hc2ozwxduaaa [7b1a7ac46f] Connected [7b1a7ac46f] Received: "7b1a7ac46f is saying hello!" [7b1a7ac46f] Connection type changed to: direct(192.168.xxx.xxx:48801) [7b1a7ac46f] Transferred 100.00 MiB in 0.6929s, 144.31 MiB/s [7b1a7ac46f] Disconnected ``` </details> <details> <summary>Output on fetch side</summary> ``` $ cargo -q run --release --example transfer --all-features -- fetch -e staging nodead66wz55fgk4xxyyitqrocybqsfplzvrhpvu25kozbw5hc2ozwxduaaa Generated a new node secret. To reuse, set IROH_SECRET=a924573310dc0c0763b64ea82c307895965883d1046f4555954689dd8a937d8c Our node id: 7b1a7ac46f528bc5182ea214326fe2a348d2a6f3a3a63d505947c3f0980e8f43 Our direct addresses: 78.xxx.xxx.xxx:48801 (type: Stun) 192.168.xxx.xxx:48801 (type: Local) Our home relay server: https://staging-euw1-1.relay.iroh.network./ Connected to fdeb67bd2995cbdf1844e1170b01848af5e6b13beb4d754ec86dd38b4ecdae3a Sent: "7b1a7ac46f is saying hello!" [fdeb67bd29] Connection type changed to: direct(192.168.xxx.xxx:44555) Received 100.00 MiB in 1.0968s (91.17 MiB/s, time to first byte 0.002208444s, 3518 chunks) ``` </details> #### `publish` and `resolve` examples * Set a default relay URL in the publish example. Otherwise an empty node info would be published if not setting any further arguments, which was a major UX footgun. A new argument `no-relay-url` allows to publish without relay URL. * Cleanup constant names to match those used in the `transfer` example * Allow to set a custom origin domain in the resolve example ## Breaking Changes  ## Notes & open questions  ## Change checklist  - [x] Self-review. - [x] Documentation updates following the [style guide](https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#appendix-a-full-conventions-text), if relevant.
diff --git a/iroh-dns-server/examples/publish.rs b/iroh-dns-server/examples/publish.rs
@@ -1,6 +1,6 @@
 use std::{net::SocketAddr, str::FromStr};
 
-use anyhow::{bail, Result};
+use anyhow::{Context, Result};
 use clap::{Parser, ValueEnum};
 use iroh::{
     discovery::{
@@ -13,8 +13,9 @@ use iroh::{
 };
 use url::Url;
 
-const LOCALHOST_PKARR: &str = "http://localhost:8080/pkarr";
-const EXAMPLE_ORIGIN: &str = "irohdns.example";
+const DEV_PKARR_RELAY_URL: &str = "http://localhost:8080/pkarr";
+const DEV_DNS_ORIGIN_DOMAIN: &str = "irohdns.example";
+const EXAMPLE_RELAY_URL: &str = "https://relay.iroh.example";
 
 #[derive(ValueEnum, Clone, Debug, Default, Copy, strum::Display)]
 #[strum(serialize_all = "kebab-case")]
@@ -38,19 +39,19 @@ struct Cli {
     env: Env,
     /// Pkarr Relay URL. If set, the --env option will be ignored.
     #[clap(long, conflicts_with = "env")]
-    pkarr_relay: Option<Url>,
-    /// Home relay server to publish for this node
-    #[clap(short, long)]
+    pkarr_relay_url: Option<Url>,
+    /// Home relay server URL to publish.
+    #[clap(short, long, conflicts_with = "no_relay_url")]
     relay_url: Option<Url>,
-    /// Direct addresses to publish for this node
+    /// Do not publish a home relay server URL.
+    #[clap(long)]
+    no_relay_url: bool,
+    /// Direct addresses to publish.
     #[clap(short, long)]
     addr: Vec<SocketAddr>,
     /// User data to publish for this node
     #[clap(short, long)]
     user_data: Option<UserData>,
-    /// Create a new node secret if IROH_SECRET is unset. Only for development / debugging.
-    #[clap(short, long)]
-    create: bool,
 }
 
 #[tokio::main]
@@ -59,28 +60,34 @@ async fn main() -> Result<()> {
     let args = Cli::parse();
 
     let secret_key = match std::env::var("IROH_SECRET") {
-        Ok(s) => SecretKey::from_str(&s)?,
-        Err(_) if args.create => {
+        Ok(s) => SecretKey::from_str(&s)
+            .context("failed to parse IROH_SECRET environment variable as iroh secret key")?,
+        Err(_) => {
             let s = SecretKey::generate(rand::rngs::OsRng);
             println!("Generated a new node secret. To reuse, set");
-            println!("IROH_SECRET={s}");
+            println!("\tIROH_SECRET={s}\n");
             s
         }
-        Err(_) => {
-            bail!("Environment variable IROH_SECRET is not set. To create a new secret, use the --create option.")
-        }
     };
 
     let node_id = secret_key.public();
-    let pkarr_relay = match (args.pkarr_relay, args.env) {
-        (Some(pkarr_relay), _) => pkarr_relay,
+    let pkarr_relay_url = match (args.pkarr_relay_url, args.env) {
+        (Some(url), _) => url,
         (None, Env::Staging) => N0_DNS_PKARR_RELAY_STAGING.parse().expect("valid url"),
         (None, Env::Prod) => N0_DNS_PKARR_RELAY_PROD.parse().expect("valid url"),
-        (None, Env::Dev) => LOCALHOST_PKARR.parse().expect("valid url"),
+        (None, Env::Dev) => DEV_PKARR_RELAY_URL.parse().expect("valid url"),
     };
 
-    println!("announce {node_id}:");
-    if let Some(relay_url) = &args.relay_url {
+    let relay_url = if let Some(relay_url) = args.relay_url {
+        Some(relay_url)
+    } else if !args.no_relay_url {
+        Some(EXAMPLE_RELAY_URL.parse().expect("valid url"))
+    } else {
+        None
+    };
+
+    println!("announce node {node_id}:");
+    if let Some(relay_url) = &relay_url {
         println!("    relay={relay_url}");
     }
     for addr in &args.addr {
@@ -90,11 +97,11 @@ async fn main() -> Result<()> {
         println!("    user-data={user_data}");
     }
     println!();
-    println!("publish to {pkarr_relay} ...");
+    println!("publish to {pkarr_relay_url} ...");
 
-    let pkarr = PkarrRelayClient::new(pkarr_relay);
+    let pkarr = PkarrRelayClient::new(pkarr_relay_url);
     let node_info = NodeInfo::new(node_id)
-        .with_relay_url(args.relay_url.map(Into::into))
+        .with_relay_url(relay_url.map(Into::into))
         .with_direct_addresses(args.addr.into_iter().collect())
         .with_user_data(args.user_data);
     let signed_packet = node_info.to_pkarr_signed_packet(&secret_key, 30)?;
@@ -105,7 +112,10 @@ async fn main() -> Result<()> {
 
     match args.env {
         Env::Staging => {
-            println!("   cargo run --example resolve -- node {}", node_id);
+            println!(
+                "   cargo run --example resolve -- --env staging node {}",
+                node_id
+            );
             println!(
                 "   dig {} TXT",
                 fmt_domain(&node_id, N0_DNS_NODE_ORIGIN_STAGING)
@@ -128,7 +138,7 @@ async fn main() -> Result<()> {
             );
             println!(
                 "    dig @localhost -p 5300 {} TXT",
-                fmt_domain(&node_id, EXAMPLE_ORIGIN)
+                fmt_domain(&node_id, DEV_DNS_ORIGIN_DOMAIN)
             )
         }
     }
diff --git a/iroh-dns-server/examples/resolve.rs b/iroh-dns-server/examples/resolve.rs
@@ -1,12 +1,13 @@
+use anyhow::Context;
 use clap::{Parser, ValueEnum};
 use iroh::{
     discovery::dns::{N0_DNS_NODE_ORIGIN_PROD, N0_DNS_NODE_ORIGIN_STAGING},
     dns::DnsResolver,
     NodeId,
 };
 
-const LOCALHOST_DNS: &str = "127.0.0.1:5300";
-const EXAMPLE_ORIGIN: &str = "irohdns.example";
+const DEV_DNS_SERVER: &str = "127.0.0.1:5300";
+const DEV_DNS_ORIGIN_DOMAIN: &str = "irohdns.example";
 
 #[derive(ValueEnum, Clone, Debug, Default)]
 pub enum Env {
@@ -23,31 +24,55 @@ pub enum Env {
 struct Cli {
     #[clap(value_enum, short, long, default_value_t = Env::Staging)]
     env: Env,
+    dns_server: Option<String>,
     #[clap(subcommand)]
     command: Command,
 }
 
 #[derive(Debug, Parser)]
 enum Command {
     /// Resolve node info by node id.
-    Node { node_id: NodeId },
+    Node {
+        /// The node id to resolve.
+        node_id: NodeId,
+        /// Use a custom domain when resolving node info via DNS.
+        #[clap(long)]
+        dns_origin_domain: Option<String>,
+    },
     /// Resolve node info by domain.
     Domain { domain: String },
 }
 
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
     let args = Cli::parse();
-    let (resolver, origin) = match args.env {
-        Env::Staging => (DnsResolver::new(), N0_DNS_NODE_ORIGIN_STAGING),
-        Env::Prod => (DnsResolver::new(), N0_DNS_NODE_ORIGIN_PROD),
-        Env::Dev => (
-            DnsResolver::with_nameserver(LOCALHOST_DNS.parse()?),
-            EXAMPLE_ORIGIN,
-        ),
+    let resolver = if let Some(host) = args.dns_server {
+        let addr = tokio::net::lookup_host(host)
+            .await?
+            .next()
+            .context("failed to resolve DNS server address")?;
+        DnsResolver::with_nameserver(addr)
+    } else {
+        match args.env {
+            Env::Staging | Env::Prod => DnsResolver::new(),
+            Env::Dev => {
+                DnsResolver::with_nameserver(DEV_DNS_SERVER.parse().expect("valid address"))
+            }
+        }
     };
     let resolved = match args.command {
-        Command::Node { node_id } => resolver.lookup_node_by_id(&node_id, origin).await?,
+        Command::Node {
+            node_id,
+            dns_origin_domain,
+        } => {
+            let origin_domain = match (&dns_origin_domain, args.env) {
+                (Some(domain), _) => domain,
+                (None, Env::Prod) => N0_DNS_NODE_ORIGIN_PROD,
+                (None, Env::Staging) => N0_DNS_NODE_ORIGIN_STAGING,
+                (None, Env::Dev) => DEV_DNS_ORIGIN_DOMAIN,
+            };
+            resolver.lookup_node_by_id(&node_id, origin_domain).await?
+        }
         Command::Domain { domain } => resolver.lookup_node_by_domain_name(&domain).await?,
     };
     println!("resolved node {}", resolved.node_id);
diff --git a/iroh/examples/transfer.rs b/iroh/examples/transfer.rs
