docs and cleanup

Author: Frando

Cargo.lock

@@ -25,11 +25,12 @@ data-encoding = "2.3.3"
 default-net = "0.20"
 der = { version = "0.7", features = ["alloc", "derive"] }
 derive_more = { version = "1.0.0-beta.1", features = ["debug", "display", "from", "try_into", "deref"] }
-ed25519-dalek = { version = "2.0.0", features = ["serde", "rand_core"], optional = true }
 flume = "0.11"
 futures = "0.3.25"
 governor = "0.6.0"
 hex = "0.4.3"
+hickory-proto = "0.24.0"
+hickory-resolver = "0.24.0"
 hostname = "0.3.1"
 http = "1"
 http-body-util = "0.1.0"
@@ -41,6 +42,7 @@ libc = "0.2.139"
 num_enum = "0.7"
 once_cell = "1.18.0"
 parking_lot = "0.12.1"
+pkarr = { version = "1.1.3", default-features = false, features = ["async", "relay"] }
 postcard = { version = "1", default-features = false, features = ["alloc", "use-std", "experimental-derive"] }
 quinn = "0.10"
 quinn-proto = "0.10.5"
@@ -66,12 +68,12 @@ tokio-rustls = { version = "0.24" }
 tokio-rustls-acme = { version = "0.2" }
 tokio-util = { version = "0.7", features = ["io-util", "io", "codec"] }
 tracing = "0.1"
-hickory-resolver = "0.24.0"
 url = { version = "2.4", features = ["serde"] }
 watchable = "1.1.2"
 webpki = { package = "rustls-webpki", version = "0.101.4", features = ["std"] }
 webpki-roots = "0.25"
 x509-parser = "0.15"
+z32 = "1.0.3"
 
 # derper
 clap = { version = "4", features = ["derive"], optional = true }
@@ -83,9 +85,6 @@ tracing-subscriber = { version = "0.3", features = ["env-filter"], optional = tr
 
 # metrics
 iroh-metrics = { version = "0.12.0", path = "../iroh-metrics", default-features = false }
-z32 = "1.0.3"
-hickory-proto = "0.24.0"
-pkarr = { version = "1.1.3", default-features = false, features = ["async", "relay"] }
 
 [target.'cfg(any(target_os = "linux", target_os = "android"))'.dependencies]
 netlink-packet-core = "0.7.0"

iroh-net/Cargo.toml

@@ -1,4 +1,5 @@
-//! todo
+//! This module contains functions and structs to lookup node information from DNS
+//! and to encode node information in Pkarr signed packets.
 
 use std::{collections::HashMap, fmt, str::FromStr};
 
@@ -9,23 +10,23 @@ use url::Url;
 
 use crate::{key::SecretKey, AddrInfo, NodeAddr, NodeId};
 
-///
-pub const ATTR_DERP: &str = "derp";
-///
-pub const ATTR_NODE_ID: &str = "node";
-///
-pub const ATTR_ADDR: &str = "addr";
-///
+const ATTR_DERP: &str = "derp";
+const ATTR_NODE_ID: &str = "node";
+
+/// The label for the node info TXT record
 pub const IROH_NODE_TXT_LABEL: &str = "_iroh_node";
 
+/// Lookup node info by domain name
 ///
+/// The domain name must either contain an _iroh_node TXT record or be a CNAME record that leads to
+/// an _iroh_node TXT record.
 pub async fn lookup_by_domain(domain: &str) -> Result<NodeAddr> {
     let name = Name::from_str(domain)?;
     let info = lookup_node_info(name).await?;
     Ok(info.into())
 }
 
-///
+/// Lookup node info by node id and origin domain name.
 pub async fn lookup_by_id(node_id: &NodeId, origin: &str) -> Result<NodeAddr> {
     let domain = format!("{}.{}", to_z32(node_id), origin);
     lookup_by_domain(&domain).await
@@ -45,12 +46,29 @@ fn ensure_iroh_node_txt_label(name: Name) -> Result<Name, ProtoError> {
     }
 }
 
+/// Encode a [`NodeId`] in [`z-base-32`] encoding.
+///
+/// [z-base-32]: https://philzimmermann.com/docs/human-oriented-base-32-encoding.txt
+pub fn to_z32(node_id: &NodeId) -> String {
+    z32::encode(node_id.as_bytes())
+}
+
+/// Parse a [`NodeId`] from [`z-base-32`] encoding.
 ///
+/// [z-base-32]: https://philzimmermann.com/docs/human-oriented-base-32-encoding.txt
+pub fn from_z32(s: &str) -> Result<NodeId> {
+    let bytes = z32::decode(s.as_bytes()).map_err(|_| anyhow!("invalid z32"))?;
+    let bytes: &[u8; 32] = &bytes.try_into().map_err(|_| anyhow!("not 32 bytes long"))?;
+    let node_id = NodeId::from_bytes(bytes)?;
+    Ok(node_id)
+}
+
+/// Node info contained in a DNS _iroh_node TXT record.
 #[derive(derive_more::Debug, Clone, Eq, PartialEq)]
 pub struct NodeInfo {
-    ///
+    /// The node id
     pub node_id: NodeId,
-    ///
+    /// Home Derp server for this node
     #[debug("{:?}", self.derp_url.as_ref().map(|s| s.to_string()))]
     pub derp_url: Option<Url>,
 }
@@ -74,22 +92,16 @@ impl From<NodeInfo> for AddrInfo {
 }
 
 impl NodeInfo {
-    ///
+    /// Create a new [`NodeInfo`] from its parts.
     pub fn new(node_id: NodeId, derp_url: Option<Url>) -> Self {
         Self { node_id, derp_url }
     }
-    ///
-    pub fn node_domain(&self, origin: &str) -> String {
-        format!("{}.{}", to_z32(&self.node_id), origin)
-    }
-
-    ///
-    pub fn node_info_domain(&self, origin: &str) -> String {
-        format!("{}.{}", IROH_NODE_TXT_LABEL, self.node_domain(origin))
-    }
 
+    /// Convert this node info into a DNS attribute string.
     ///
-    pub fn to_attr_string(&self) -> String {
+    /// It will look like this:
+    /// node=b32encodednodeid derp=https://myderp.example
+    pub fn into_attribute_string(&self) -> String {
         let mut attrs = vec![];
         attrs.push(fmt_attr(ATTR_NODE_ID, self.node_id));
         if let Some(derp) = &self.derp_url {
@@ -98,12 +110,12 @@ impl NodeInfo {
         attrs.join(" ")
     }
 
-    ///
+    /// Try to parse a [`NodeInfo`] from the lookup result of our DNS resolver.
     pub fn from_hickory_lookup(lookup: &hickory_resolver::lookup::Lookup) -> Result<Self> {
         Self::from_hickory_records(lookup.records())
     }
 
-    ///
+    /// Try to parse a [`NodeInfo`] from a set of DNS records.
     pub fn from_hickory_records(records: &[hickory_proto::rr::Record]) -> Result<Self> {
         use hickory_proto::rr;
         let (node_id, txt) = records
@@ -122,7 +134,9 @@ impl NodeInfo {
         Ok(node_info)
     }
 
+    /// Parse the [`NodeInfo`] from an attribute string.
     ///
+    /// See [Self::into_attribute_string] for the expected format.
     pub fn parse_from_attributes(attrs: &str) -> Result<Self> {
         let attrs = parse_attrs(attrs);
         let Some(node) = attrs.get(ATTR_NODE_ID) else {
@@ -143,7 +157,8 @@ impl NodeInfo {
         })
     }
 
-    ///
+    /// Create a [`pkarr::SignedPacket`] by constructing a DNS packet and
+    /// signing it with a [`SecretKey`].
     pub fn into_pkarr_signed_packet(
         &self,
         secret_key: &SecretKey,
@@ -155,12 +170,11 @@ impl NodeInfo {
         Ok(signed_packet)
     }
 
-    ///
-    pub fn into_pkarr_dns_packet(&self, ttl: u32) -> Result<pkarr::dns::Packet<'static>> {
+    fn into_pkarr_dns_packet(&self, ttl: u32) -> Result<pkarr::dns::Packet<'static>> {
         use pkarr::dns::{self, rdata};
         let name = dns::Name::new(IROH_NODE_TXT_LABEL)?.into_owned();
         let rdata = {
-            let value = self.to_attr_string();
+            let value = self.into_attribute_string();
             let txt = rdata::TXT::new().with_string(&value)?.into_owned();
             rdata::RData::TXT(txt)
         };
@@ -172,7 +186,7 @@ impl NodeInfo {
         Ok(packet)
     }
 
-    ///
+    /// Try to parse a [`NodeInfo`] from a [`pkarr::SignedPacket`].
     pub fn from_pkarr_signed_packet(packet: &pkarr::SignedPacket) -> Result<Self> {
         use pkarr::dns::{self, rdata::RData};
         let pubkey = packet.public_key();
@@ -194,11 +208,11 @@ impl NodeInfo {
 
         let txt_record = txt_record.to_owned();
         let txt = String::try_from(txt_record)?;
-        let an = Self::parse_from_attributes(&txt)?;
-        if an.node_id != node_id {
+        let info = Self::parse_from_attributes(&txt)?;
+        if info.node_id != node_id {
             bail!("node id mismatch between record name and TXT value");
         }
-        Ok(an)
+        Ok(info)
     }
 }
 
@@ -231,19 +245,3 @@ fn parse_attrs<'a>(s: &'a str) -> HashMap<&'a str, Vec<&'a str>> {
     map
 }
 
-/// Encode a [`NodeId`] in [`z-base-32`] encoding.
-///
-/// [z-base-32]: https://philzimmermann.com/docs/human-oriented-base-32-encoding.txt
-pub fn to_z32(node_id: &NodeId) -> String {
-    z32::encode(node_id.as_bytes())
-}
-
-/// Parse a [`NodeId`] from [`z-base-32`] encoding.
-///
-/// [z-base-32]: https://philzimmermann.com/docs/human-oriented-base-32-encoding.txt
-pub fn from_z32(s: &str) -> Result<NodeId> {
-    let bytes = z32::decode(s.as_bytes()).map_err(|_| anyhow!("invalid z32"))?;
-    let bytes: &[u8; 32] = &bytes.try_into().map_err(|_| anyhow!("not 32 bytes long"))?;
-    let node_id = NodeId::from_bytes(bytes)?;
-    Ok(node_id)
-}