feat: add user data to discovery

Author: Frando

Cargo.lock

@@ -41,3 +41,6 @@ unexpected_cfgs = { level = "warn", check-cfg = ["cfg(iroh_docsrs)", "cfg(iroh_l
 
 [workspace.lints.clippy]
 unused-async = "warn"
+
+[patch.crates-io]
+swarm-discovery = { git = "https://github.com/Frando/swarm-discovery.git", branch = "feat/txt" }

Cargo.toml

@@ -1,12 +1,12 @@
-use std::str::FromStr;
+use std::{net::SocketAddr, str::FromStr};
 
 use anyhow::{bail, Result};
 use clap::{Parser, ValueEnum};
 use iroh::{
     discovery::{
         dns::{N0_DNS_NODE_ORIGIN_PROD, N0_DNS_NODE_ORIGIN_STAGING},
         pkarr::{PkarrRelayClient, N0_DNS_PKARR_RELAY_PROD, N0_DNS_PKARR_RELAY_STAGING},
-        NodeData,
+        NodeData, UserData,
     },
     dns::node_info::{NodeIdExt, NodeInfo, IROH_TXT_NAME},
     NodeId, SecretKey,
@@ -40,7 +40,14 @@ struct Cli {
     #[clap(long, conflicts_with = "env")]
     pkarr_relay: Option<Url>,
     /// Home relay server to publish for this node
-    relay_url: Url,
+    #[clap(short, long)]
+    relay_url: Option<Url>,
+    /// Direct addresses to publish for this node
+    #[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,
@@ -73,12 +80,24 @@ async fn main() -> Result<()> {
     };
 
     println!("announce {node_id}:");
-    println!("    relay={}", args.relay_url);
+    if let Some(relay_url) = &args.relay_url {
+        println!("    relay={relay_url}");
+    }
+    for addr in &args.addr {
+        println!("    addr={addr}");
+    }
+    if let Some(user_data) = &args.user_data {
+        println!("    user-data={user_data}");
+    }
     println!();
     println!("publish to {pkarr_relay} ...");
 
     let pkarr = PkarrRelayClient::new(pkarr_relay);
-    let data = NodeData::default().with_relay_url(args.relay_url);
+    let data = NodeData::new(
+        args.relay_url.map(Into::into),
+        args.addr.into_iter().collect(),
+    )
+    .with_user_data(args.user_data);
     let node_info = NodeInfo::new(node_id, data);
     let signed_packet = node_info.to_pkarr_signed_packet(&secret_key, 30)?;
     pkarr.publish(&signed_packet).await?;

iroh-dns-server/examples/publish.rs

@@ -57,5 +57,8 @@ async fn main() -> anyhow::Result<()> {
     for addr in resolved.direct_addresses() {
         println!("    addr={addr}")
     }
+    if let Some(user_data) = resolved.user_data() {
+        println!("    user-data={user_data}")
+    }
     Ok(())
 }

iroh-dns-server/examples/resolve.rs

@@ -34,7 +34,7 @@
 
 use std::{
     collections::{BTreeMap, BTreeSet},
-    fmt::Display,
+    fmt::{self, Display},
     hash::Hash,
     net::SocketAddr,
     str::FromStr,
@@ -80,7 +80,9 @@ impl NodeIdExt for NodeId {
 
 /// Data about a node that may be published to and resolved from discovery services.
 ///
-/// This includes an optional [`RelayUrl`] and a set of direct addresses.
+/// This includes an optional [`RelayUrl`], a set of direct addresses, and the optional
+/// [`UserData`], a string that can be set by applications and is not parsed or used by iroh
+/// itself.
 ///
 /// This struct does not include the node's [`NodeId`], only the data *about* a certain
 /// node. See [`NodeInfo`] for a struct that contains a [`NodeId`] with associated [`NodeData`].
@@ -90,6 +92,8 @@ pub struct NodeData {
     relay_url: Option<RelayUrl>,
     /// Direct addresses where this node can be reached.
     direct_addresses: BTreeSet<SocketAddr>,
+    /// Optional user-defined [`UserData`] for this node.
+    user_data: Option<UserData>,
 }
 
 impl NodeData {
@@ -98,6 +102,7 @@ impl NodeData {
         Self {
             relay_url,
             direct_addresses,
+            user_data: None,
         }
     }
 
@@ -113,11 +118,22 @@ impl NodeData {
         self
     }
 
+    /// Sets the user data.
+    pub fn with_user_data(mut self, user_data: Option<UserData>) -> Self {
+        self.user_data = user_data;
+        self
+    }
+
     /// Returns the relay URL of the node.
     pub fn relay_url(&self) -> Option<&RelayUrl> {
         self.relay_url.as_ref()
     }
 
+    /// Returns the optional user-defined data of the node.
+    pub fn user_data(&self) -> Option<&UserData> {
+        self.user_data.as_ref()
+    }
+
     /// Returns the direct addresses of the node.
     pub fn direct_addresses(&self) -> &BTreeSet<SocketAddr> {
         &self.direct_addresses
@@ -137,17 +153,91 @@ impl NodeData {
     pub fn set_relay_url(&mut self, relay_url: Option<RelayUrl>) {
         self.relay_url = relay_url
     }
+
+    /// Sets the user data of the node data.
+    pub fn set_user_data(&mut self, user_data: Option<UserData>) {
+        self.user_data = user_data;
+    }
+
+    /// Converts into a [`NodeAddr`] and [`UserData`].
+    pub fn into_node_addr_and_user_data(self, node_id: NodeId) -> (NodeAddr, Option<UserData>) {
+        (
+            NodeAddr {
+                node_id,
+                relay_url: self.relay_url,
+                direct_addresses: self.direct_addresses,
+            },
+            self.user_data,
+        )
+    }
 }
 
 impl From<NodeAddr> for NodeData {
     fn from(node_addr: NodeAddr) -> Self {
         Self {
             relay_url: node_addr.relay_url,
             direct_addresses: node_addr.direct_addresses,
+            user_data: None,
+        }
+    }
+}
+
+// User defined data that can be published and resolved through node discovery.
+///
+/// Under the hood this is a UTF-8 String that is less than or equal to
+/// [`USER_DATA_MAX_LENGTH`] bytes.
+///
+/// Iroh does not keep track of or examine user defined data.
+#[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
+pub struct UserData(String);
+
+/// The max byte length allowed for user defined data.
+///
+/// In DNS discovery services, the user data is stored in a TXT record character string,
+/// which has a max length of 255 bytes. We need to subtract "user-data=", which leaves
+/// 245 bytes for the actual user data.
+pub const USER_DATA_MAX_LENGTH: usize = 245;
+
+/// Error returned when an input value is too long for [`UserData`].
+#[derive(Debug, thiserror::Error)]
+#[error("User-defined data exceeds max length")]
+pub struct MaxLengthExceededError;
+
+impl TryFrom<String> for UserData {
+    type Error = MaxLengthExceededError;
+    fn try_from(value: String) -> Result<Self, Self::Error> {
+        if value.len() > USER_DATA_MAX_LENGTH {
+            Err(MaxLengthExceededError)
+        } else {
+            Ok(Self(value))
+        }
+    }
+}
+
+impl FromStr for UserData {
+    type Err = MaxLengthExceededError;
+
+    fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
+        if s.len() > USER_DATA_MAX_LENGTH {
+            Err(MaxLengthExceededError)
+        } else {
+            Ok(Self(s.to_string()))
         }
     }
 }
 
+impl fmt::Display for UserData {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+impl AsRef<str> for UserData {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
 /// Information about a node that may be published to and resolved from discovery services.
 ///
 /// This struct couples a [`NodeId`] with its associated [`NodeData`].
@@ -181,9 +271,16 @@ impl From<&TxtAttrs<IrohAttr>> for NodeInfo {
             .flatten()
             .filter_map(|s| SocketAddr::from_str(s).ok())
             .collect();
+        let user_data = attrs
+            .get(&IrohAttr::UserData)
+            .into_iter()
+            .flatten()
+            .next()
+            .and_then(|s| UserData::from_str(s).ok());
         let data = NodeData {
             relay_url: relay_url.map(Into::into),
             direct_addresses,
+            user_data,
         };
         Self { node_id, data }
     }
@@ -200,6 +297,7 @@ impl From<NodeAddr> for NodeInfo {
         let data = NodeData {
             direct_addresses: value.direct_addresses,
             relay_url: value.relay_url,
+            user_data: None,
         };
         Self::new(value.node_id, data)
     }
@@ -260,6 +358,18 @@ impl NodeInfo {
     pub fn to_txt_strings(&self) -> Vec<String> {
         self.to_attrs().to_txt_strings().collect()
     }
+
+    /// Converts into a [`NodeAddr`] and optional [`UserData`].
+    pub fn into_node_addr_and_user_data(self) -> (NodeAddr, Option<UserData>) {
+        (
+            NodeAddr {
+                node_id: self.node_id,
+                relay_url: self.data.relay_url,
+                direct_addresses: self.data.direct_addresses,
+            },
+            self.data.user_data,
+        )
+    }
 }
 
 impl std::ops::Deref for NodeInfo {
@@ -300,6 +410,8 @@ pub(super) enum IrohAttr {
     Relay,
     /// Direct address.
     Addr,
+    /// User-defined data
+    UserData,
 }
 
 /// Attributes parsed from [`IROH_TXT_NAME`] TXT records.
@@ -322,6 +434,9 @@ impl From<&NodeInfo> for TxtAttrs<IrohAttr> {
         for addr in &info.data.direct_addresses {
             attrs.push((IrohAttr::Addr, addr.to_string()));
         }
+        if let Some(user_data) = &info.data.user_data {
+            attrs.push((IrohAttr::UserData, user_data.to_string()));
+        }
         Self::from_parts(info.node_id, attrs.into_iter())
     }
 }
@@ -531,7 +646,8 @@ mod tests {
         let node_data = NodeData::new(
             Some("https://example.com".parse().unwrap()),
             ["127.0.0.1:1234".parse().unwrap()].into_iter().collect(),
-        );
+        )
+        .with_user_data(Some("foobar".parse().unwrap()));
         let node_id = "vpnk377obfvzlipnsfbqba7ywkkenc4xlpmovt5tsfujoa75zqia"
             .parse()
             .unwrap();
@@ -548,7 +664,8 @@ mod tests {
         let node_data = NodeData::new(
             Some("https://example.com".parse().unwrap()),
             ["127.0.0.1:1234".parse().unwrap()].into_iter().collect(),
-        );
+        )
+        .with_user_data(Some("foobar".parse().unwrap()));
         let expected = NodeInfo::new(secret_key.public(), node_data);
         let packet = expected.to_pkarr_signed_packet(&secret_key, 30).unwrap();
         let actual = NodeInfo::from_pkarr_signed_packet(&packet).unwrap();

iroh-relay/src/dns/node_info.rs

@@ -109,7 +109,7 @@ use std::sync::Arc;
 
 use anyhow::{anyhow, ensure, Result};
 use iroh_base::{NodeAddr, NodeId};
-pub use iroh_relay::dns::node_info::{NodeData, NodeInfo};
+pub use iroh_relay::dns::node_info::{NodeData, NodeInfo, UserData};
 use n0_future::{
     stream::{Boxed as BoxStream, StreamExt},
     task::{self, AbortOnDropHandle},
@@ -203,6 +203,7 @@ impl<T: Discovery> Discovery for Arc<T> {}
 /// This struct derefs to [`NodeData`], so you can access the methods from [`NodeData`]
 /// directly from [`DiscoveryItem`].
 #[derive(Debug, Clone)]
+#[non_exhaustive]
 pub struct DiscoveryItem {
     /// The node info for the node, as discovered by the the discovery service.
     node_info: NodeInfo,
@@ -814,7 +815,7 @@ mod tests {
 mod test_dns_pkarr {
     use anyhow::Result;
     use iroh_base::{NodeAddr, SecretKey};
-    use iroh_relay::RelayMap;
+    use iroh_relay::{dns::node_info::UserData, RelayMap};
     use n0_future::time::Duration;
     use tokio_util::task::AbortOnDropHandle;
     use tracing_test::traced_test;
@@ -853,7 +854,7 @@ mod test_dns_pkarr {
             .lookup_node_by_id(&node_info.node_id, &origin)
             .await?;
 
-        assert_eq!(resolved, node_info.into());
+        assert_eq!(resolved, node_info);
 
         Ok(())
     }
@@ -872,20 +873,25 @@ mod test_dns_pkarr {
 
         let resolver = DnsResolver::with_nameserver(dns_pkarr_server.nameserver);
         let publisher = PkarrPublisher::new(secret_key, dns_pkarr_server.pkarr_url.clone());
-        let data = NodeData::new(relay_url.clone(), Default::default());
+        let user_data: UserData = "foobar".parse().unwrap();
+        let data = NodeData::new(relay_url.clone(), Default::default())
+            .with_user_data(Some(user_data.clone()));
         // does not block, update happens in background task
         publisher.update_addr_info(&data);
         // wait until our shared state received the update from pkarr publishing
         dns_pkarr_server.on_node(&node_id, PUBLISH_TIMEOUT).await?;
         let resolved = resolver.lookup_node_by_id(&node_id, &origin).await?;
+        println!("resolved {resolved:?}");
 
         let expected = NodeAddr {
             node_id,
             relay_url,
             direct_addresses: Default::default(),
         };
+        let (resolved_addr, resolved_user_data) = resolved.into_node_addr_and_user_data();
 
-        assert_eq!(resolved.node_addr(), expected);
+        assert_eq!(resolved_addr, expected);
+        assert_eq!(resolved_user_data, Some(user_data));
         Ok(())
     }