feat!: implement improved address sharing options (#2230)

This expands on the functionality previously only available to blob
tickets, of configuring the information contained in a `NodeAddr`.

## Breaking Changes

- renamed: `iroh::client::blobs::ShareTicketOptions` ->
`iroh_base::node_addr::AddrInfoOptions`
- renamed `iroh_cli`: `doc share --ticket-options` -> `doc share
--addr-options`
- Default for `AddrInfoOptions` is now `Id`, before it was
`RelayandAddresses`
- Added `addr_options` to `iroh::client::docs::Docs.share`
- Added `Id` option to `AddrInfoOptions`

Closes #2187

iroh-base/Cargo.toml

@@ -27,7 +27,7 @@ thiserror = "1"
 
 # key module
 aead = { version = "0.5.2", features = ["bytes"], optional = true }
-derive_more = { version = "1.0.0-beta.1", features = ["debug", "display"], optional = true }
+derive_more = { version = "1.0.0-beta.1", features = ["debug", "display", "from_str"], optional = true }
 ed25519-dalek = { version = "2.0.0", features = ["serde", "rand_core"], optional = true }
 once_cell = { version = "1.18.0", optional = true }
 rand = { version = "0.8", optional = true }
@@ -50,4 +50,3 @@ hash = ["bao-tree", "data-encoding", "postcard"]
 base32 = ["data-encoding"]
 redb = ["dep:redb"]
 key = ["dep:ed25519-dalek", "dep:once_cell", "dep:rand", "dep:rand_core", "dep:ssh-key", "dep:ttl_cache", "dep:aead", "dep:crypto_box", "dep:zeroize", "dep:url", "dep:derive_more"]
-

iroh-base/src/node_addr.rs

@@ -39,6 +39,11 @@ impl NodeAddr {
         self
     }
 
+    /// Apply the options to `self`.
+    pub fn apply_options(&mut self, opts: AddrInfoOptions) {
+        self.info.apply_options(opts);
+    }
+
     /// Get the direct addresses of this peer.
     pub fn direct_addresses(&self) -> impl Iterator<Item = &SocketAddr> {
         self.info.direct_addresses.iter()
@@ -83,6 +88,25 @@ impl AddrInfo {
     pub fn is_empty(&self) -> bool {
         self.relay_url.is_none() && self.direct_addresses.is_empty()
     }
+
+    /// Apply the options to `self`.
+    pub fn apply_options(&mut self, opts: AddrInfoOptions) {
+        match opts {
+            AddrInfoOptions::Id => {
+                self.direct_addresses.clear();
+                self.relay_url = None;
+            }
+            AddrInfoOptions::RelayAndAddresses => {
+                // nothing to do
+            }
+            AddrInfoOptions::Relay => {
+                self.direct_addresses.clear();
+            }
+            AddrInfoOptions::Addresses => {
+                self.relay_url = None;
+            }
+        }
+    }
 }
 
 impl NodeAddr {
@@ -102,6 +126,33 @@ impl NodeAddr {
     }
 }
 
+/// Options to configure what is included in a `NodeAddr`.
+#[derive(
+    Copy,
+    Clone,
+    PartialEq,
+    Eq,
+    Default,
+    Debug,
+    derive_more::Display,
+    derive_more::FromStr,
+    Serialize,
+    Deserialize,
+)]
+pub enum AddrInfoOptions {
+    /// Only the Node ID is added.
+    ///
+    /// This usually means that iroh-dns discovery is used to find address information.
+    #[default]
+    Id,
+    /// Include both the relay URL and the direct addresses.
+    RelayAndAddresses,
+    /// Only include the relay URL.
+    Relay,
+    /// Only include the direct addresses.
+    Addresses,
+}
+
 /// A URL identifying a relay server.
 ///
 /// This is but a wrapper around [`Url`], with a few custom tweaks:

iroh-base/src/ticket/blob.rs

@@ -5,7 +5,7 @@ use crate::{
     hash::{BlobFormat, Hash},
     ticket::{self, Ticket},
 };
-use anyhow::{ensure, Result};
+use anyhow::Result;
 use serde::{Deserialize, Serialize};
 
 use crate::node_addr::NodeAddr;
@@ -63,7 +63,6 @@ impl FromStr for BlobTicket {
 impl BlobTicket {
     /// Creates a new ticket.
     pub fn new(node: NodeAddr, hash: Hash, format: BlobFormat) -> Result<Self> {
-        ensure!(!node.info.is_empty(), "addressing info cannot be empty");
         Ok(Self { hash, format, node })
     }
 

iroh-base/src/ticket/node.rs

@@ -2,7 +2,7 @@
 
 use std::str::FromStr;
 
-use anyhow::{ensure, Result};
+use anyhow::Result;
 use serde::{Deserialize, Serialize};
 
 use crate::{
@@ -54,7 +54,6 @@ impl FromStr for NodeTicket {
 impl NodeTicket {
     /// Creates a new ticket.
     pub fn new(node: NodeAddr) -> Result<Self> {
-        ensure!(!node.info.is_empty(), "addressing info cannot be empty");
         Ok(Self { node })
     }
 

iroh-cli/src/commands/blob.rs

@@ -13,15 +13,20 @@ use indicatif::{
     HumanBytes, HumanDuration, MultiProgress, ProgressBar, ProgressDrawTarget, ProgressState,
     ProgressStyle,
 };
-use iroh::bytes::{
-    get::{db::DownloadProgress, progress::BlobProgress, Stats},
-    provider::AddProgress,
-    store::{ConsistencyCheckProgress, ExportFormat, ExportMode, ReportLevel, ValidateProgress},
-    BlobFormat, Hash, HashAndFormat, Tag,
-};
 use iroh::net::{key::PublicKey, relay::RelayUrl, NodeAddr};
 use iroh::{
-    client::{BlobStatus, Iroh, ShareTicketOptions},
+    base::node_addr::AddrInfoOptions,
+    bytes::{
+        get::{db::DownloadProgress, progress::BlobProgress, Stats},
+        provider::AddProgress,
+        store::{
+            ConsistencyCheckProgress, ExportFormat, ExportMode, ReportLevel, ValidateProgress,
+        },
+        BlobFormat, Hash, HashAndFormat, Tag,
+    },
+};
+use iroh::{
+    client::{BlobStatus, Iroh},
     rpc_protocol::{
         BlobDownloadRequest, BlobListCollectionsResponse, BlobListIncompleteResponse,
         BlobListResponse, DownloadMode, ProviderService, SetTagOption, WrapOption,
@@ -141,9 +146,11 @@ pub enum BlobCommands {
     Share {
         /// Hash of the blob to share.
         hash: Hash,
-        /// Options to configure the generated ticket.
-        #[clap(long, default_value_t = ShareTicketOptions::RelayAndAddresses)]
-        ticket_options: ShareTicketOptions,
+        /// Options to configure the address information in the generated ticket.
+        ///
+        /// Use `relay-and-addresses` in networks with no internet connectivity.
+        #[clap(long, default_value_t = AddrInfoOptions::Id)]
+        addr_options: AddrInfoOptions,
         /// If the blob is a collection, the requester will also fetch the listed blobs.
         #[clap(long, default_value_t = false)]
         recursive: bool,
@@ -350,7 +357,7 @@ impl BlobCommands {
             } => add_with_opts(iroh, path, options).await,
             Self::Share {
                 hash,
-                ticket_options,
+                addr_options,
                 recursive,
                 debug,
             } => {
@@ -360,7 +367,7 @@ impl BlobCommands {
                     BlobFormat::Raw
                 };
                 let status = iroh.blobs.status(hash).await?;
-                let ticket = iroh.blobs.share(hash, format, ticket_options).await?;
+                let ticket = iroh.blobs.share(hash, format, addr_options).await?;
 
                 let (blob_status, size) = match (status, format) {
                     (BlobStatus::Complete { size }, BlobFormat::Raw) => ("blob", size),

iroh-cli/src/commands/doc.rs

@@ -12,7 +12,7 @@ use colored::Colorize;
 use dialoguer::Confirm;
 use futures::{Stream, StreamExt, TryStreamExt};
 use indicatif::{HumanBytes, HumanDuration, MultiProgress, ProgressBar, ProgressStyle};
-use iroh::base::base32::fmt_short;
+use iroh::base::{base32::fmt_short, node_addr::AddrInfoOptions};
 use quic_rpc::ServiceConnection;
 use serde::{Deserialize, Serialize};
 use tokio::io::AsyncReadExt;
@@ -112,6 +112,11 @@ pub enum DocCommands {
         #[clap(short, long)]
         doc: Option<NamespaceId>,
         mode: ShareMode,
+        /// Options to configure the address information in the generated ticket.
+        ///
+        /// Use `relay-and-addresses` in networks with no internet connectivity.
+        #[clap(long, default_value_t = AddrInfoOptions::Id)]
+        addr_options: AddrInfoOptions,
     },
     /// Set an entry in a document.
     Set {
@@ -354,9 +359,13 @@ impl DocCommands {
                     println!("{id} {kind}")
                 }
             }
-            Self::Share { doc, mode } => {
+            Self::Share {
+                doc,
+                mode,
+                addr_options,
+            } => {
                 let doc = get_doc(iroh, env, doc).await?;
-                let ticket = doc.share(mode.into()).await?;
+                let ticket = doc.share(mode.into(), addr_options).await?;
                 println!("{}", ticket);
             }
             Self::Set {

iroh/src/client.rs

@@ -19,7 +19,7 @@ mod tags;
 pub use self::authors::Client as AuthorsClient;
 pub use self::blobs::{
     BlobAddOutcome, BlobAddProgress, BlobDownloadOutcome, BlobDownloadProgress, BlobReader,
-    BlobStatus, Client as BlobsClient, ShareTicketOptions,
+    BlobStatus, Client as BlobsClient,
 };
 pub use self::docs::{Client as DocsClient, Doc, Entry, LiveEvent};
 pub use self::node::Client as NodeClient;

iroh/src/client/blobs.rs

@@ -9,7 +9,7 @@ use std::{
 use anyhow::{anyhow, Result};
 use bytes::Bytes;
 use futures::{Future, SinkExt, Stream, StreamExt, TryStreamExt};
-use iroh_base::ticket::BlobTicket;
+use iroh_base::{node_addr::AddrInfoOptions, ticket::BlobTicket};
 use iroh_bytes::{
     export::ExportProgress,
     format::collection::Collection,
@@ -18,7 +18,6 @@ use iroh_bytes::{
     store::{ConsistencyCheckProgress, ExportFormat, ExportMode, ValidateProgress},
     BlobFormat, Hash, Tag,
 };
-use iroh_net::NodeAddr;
 use portable_atomic::{AtomicU64, Ordering};
 use quic_rpc::{client::BoxStreamSync, RpcClient, ServiceConnection};
 use tokio::io::{AsyncRead, AsyncReadExt, ReadBuf};
@@ -302,28 +301,11 @@ where
         &self,
         hash: Hash,
         blob_format: BlobFormat,
-        ticket_options: ShareTicketOptions,
+        addr_options: AddrInfoOptions,
     ) -> Result<BlobTicket> {
-        let NodeStatusResponse { addr, .. } = self.rpc.rpc(NodeStatusRequest).await??;
-        let mut node_addr = NodeAddr::new(addr.node_id);
-        match ticket_options {
-            ShareTicketOptions::RelayAndAddresses => {
-                node_addr = node_addr.with_direct_addresses(addr.direct_addresses().copied());
-                if let Some(url) = addr.relay_url() {
-                    node_addr = node_addr.with_relay_url(url.clone());
-                }
-            }
-            ShareTicketOptions::Relay => {
-                if let Some(url) = addr.relay_url() {
-                    node_addr = node_addr.with_relay_url(url.clone());
-                }
-            }
-            ShareTicketOptions::Addresses => {
-                node_addr = node_addr.with_direct_addresses(addr.direct_addresses().copied());
-            }
-        }
-
-        let ticket = BlobTicket::new(node_addr, hash, blob_format).expect("correct ticket");
+        let NodeStatusResponse { mut addr, .. } = self.rpc.rpc(NodeStatusRequest).await??;
+        addr.apply_options(addr_options);
+        let ticket = BlobTicket::new(addr, hash, blob_format).expect("correct ticket");
 
         Ok(ticket)
     }
@@ -340,20 +322,6 @@ where
     }
 }
 
-/// Options when creating a ticket
-#[derive(
-    Copy, Clone, PartialEq, Eq, Default, Debug, derive_more::Display, derive_more::FromStr,
-)]
-pub enum ShareTicketOptions {
-    /// Include both the relay URL and the direct addresses.
-    #[default]
-    RelayAndAddresses,
-    /// Only include the relay URL.
-    Relay,
-    /// Only include the direct addresses.
-    Addresses,
-}
-
 /// Status information about a blob.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum BlobStatus {

iroh/src/client/docs.rs

@@ -8,7 +8,7 @@ use std::{
 use anyhow::{anyhow, Context as _, Result};
 use bytes::Bytes;
 use futures::{Stream, StreamExt, TryStreamExt};
-use iroh_base::key::PublicKey;
+use iroh_base::{key::PublicKey, node_addr::AddrInfoOptions};
 use iroh_bytes::{export::ExportProgress, store::ExportMode, Hash};
 use iroh_net::NodeAddr;
 use iroh_sync::{
@@ -302,12 +302,17 @@ where
     }
 
     /// Share this document with peers over a ticket.
-    pub async fn share(&self, mode: ShareMode) -> anyhow::Result<DocTicket> {
+    pub async fn share(
+        &self,
+        mode: ShareMode,
+        addr_options: AddrInfoOptions,
+    ) -> anyhow::Result<DocTicket> {
         self.ensure_open()?;
         let res = self
             .rpc(DocShareRequest {
                 doc_id: self.id(),
                 mode,
+                addr_options,
             })
             .await??;
         Ok(res.0)

iroh/src/rpc_protocol.rs

@@ -11,6 +11,7 @@ use std::{collections::BTreeMap, net::SocketAddr, path::PathBuf};
 
 use bytes::Bytes;
 use derive_more::{From, TryInto};
+use iroh_base::node_addr::AddrInfoOptions;
 pub use iroh_bytes::{export::ExportProgress, get::db::DownloadProgress, BlobFormat, Hash};
 use iroh_bytes::{
     format::collection::Collection,
@@ -637,6 +638,8 @@ pub struct DocShareRequest {
     pub doc_id: NamespaceId,
     /// Whether to share read or write access to the document
     pub mode: ShareMode,
+    /// Configuration of the addresses in the ticket.
+    pub addr_options: AddrInfoOptions,
 }
 
 impl RpcMsg<ProviderService> for DocShareRequest {

iroh/src/sync_engine/rpc.rs

@@ -127,15 +127,23 @@ impl SyncEngine {
     }
 
     pub async fn doc_share(&self, req: DocShareRequest) -> RpcResult<DocShareResponse> {
-        let me = self.endpoint.my_addr().await?;
-        let capability = match req.mode {
-            ShareMode::Read => iroh_sync::Capability::Read(req.doc_id),
+        let DocShareRequest {
+            doc_id,
+            mode,
+            addr_options,
+        } = req;
+        let mut me = self.endpoint.my_addr().await?;
+        me.apply_options(addr_options);
+
+        let capability = match mode {
+            ShareMode::Read => iroh_sync::Capability::Read(doc_id),
             ShareMode::Write => {
-                let secret = self.sync.export_secret_key(req.doc_id).await?;
+                let secret = self.sync.export_secret_key(doc_id).await?;
                 iroh_sync::Capability::Write(secret)
             }
         };
-        self.start_sync(req.doc_id, vec![]).await?;
+        self.start_sync(doc_id, vec![]).await?;
+
         Ok(DocShareResponse(DocTicket {
             capability,
             nodes: vec![me],