1- //! A static discovery implementation that allows adding info for nodes manually.
1+ //! A static node discovery to manually add node addressing information.
2+ //!
3+ //! Often an application might get node addressing information out-of-band in an
4+ //! application-specific way. [`NodeTicket`]'s are one common way used to achieve this.
5+ //! This "static" addressing information is often only usable for a limited time so needs to
6+ //! be able to be removed again once know it is no longer useful.
7+ //!
8+ //! This is where the [`StaticProvider`] is useful: it allows applications to add and
9+ //! retract node addressing information that is otherwise out-of-band to iroh.
10+ //!
11+ //! [`NodeTicket`]: https://docs.rs/iroh-base/latest/iroh_base/ticket/struct.NodeTicket
12+
213use std:: {
314 collections:: { btree_map:: Entry , BTreeMap , BTreeSet } ,
415 net:: SocketAddr ,
@@ -11,7 +22,48 @@ use iroh_base::{NodeAddr, NodeId, RelayUrl};
1122
1223use super :: { Discovery , DiscoveryItem } ;
1324
14- /// A static discovery implementation that allows providing info for nodes manually.
25+ /// A static node discovery to manually add node addressing information.
26+ ///
27+ /// Often an application might get node addressing information out-of-band in an
28+ /// application-specific way. [`NodeTicket`]'s are one common way used to achieve this.
29+ /// This "static" addressing information is often only usable for a limited time so needs to
30+ /// be able to be removed again once know it is no longer useful.
31+ ///
32+ /// This is where the [`StaticProvider`] is useful: it allows applications to add and
33+ /// retract node addressing information that is otherwise out-of-band to iroh.
34+ ///
35+ /// # Examples
36+ ///
37+ /// ```rust
38+ /// use iroh::{discovery::static_provider::StaticProvider, Endpoint, NodeAddr};
39+ /// use iroh_base::SecretKey;
40+ ///
41+ /// # #[tokio::main]
42+ /// # async fn main() -> anyhow::Result<()> {
43+ /// // Create the discovery service and endpoint.
44+ /// let discovery = StaticProvider::new();
45+ ///
46+ /// let _ep = Endpoint::builder()
47+ /// .add_discovery({
48+ /// let discovery = discovery.clone();
49+ /// move |_| Some(discovery)
50+ /// })
51+ /// .bind()
52+ /// .await?;
53+ ///
54+ /// /// Sometime later add a RelayUrl for a fake NodeId.
55+ /// let key = SecretKey::from_bytes(&[0u8; 32]); // Do not use fake secret keys!
56+ /// discovery.add_node_addr(NodeAddr {
57+ /// node_id: key.public(),
58+ /// relay_url: Some("https://example.com".parse()?),
59+ /// direct_addresses: Default::default(),
60+ /// });
61+ ///
62+ /// # Ok(())
63+ /// # }
64+ /// ```
65+ ///
66+ /// [`NodeTicket`]: https://docs.rs/iroh-base/latest/iroh_base/ticket/struct.NodeTicket
1567#[ derive( Debug , Default , Clone ) ]
1668#[ repr( transparent) ]
1769pub struct StaticProvider {
@@ -27,16 +79,22 @@ struct NodeInfo {
2779
2880impl StaticProvider {
2981 /// The provenance string for this discovery implementation.
82+ ///
83+ /// This is mostly used for debugging information and allows understanding the origin of
84+ /// addressing information used by an iroh [`Endpoint`].
85+ ///
86+ /// [`Endpoint`]: crate::Endpoint
3087pub const PROVENANCE : & ' static str = "static_discovery" ;
3188
32- /// Create a new static discovery instance.
89+ /// Creates a new static discovery instance.
3390pub fn new ( ) -> Self {
3491 Self :: default ( )
3592 }
3693
37- /// Creates a static discovery instance from something that can be converted into node addresses.
94+ /// Creates a static discovery instance from node addresses.
95+ ///
96+ /// # Examples
3897///
39- /// Example:
4098/// ```rust
4199/// use std::{net::SocketAddr, str::FromStr};
42100///
@@ -68,7 +126,7 @@ impl StaticProvider {
68126 res
69127 }
70128
71- /// Add node info for the given node id .
129+ /// Sets node addressing information for the given node ID .
72130///
73131/// This will completely overwrite any existing info for the node.
74132pub fn set_node_addr ( & self , info : impl Into < NodeAddr > ) -> Option < NodeAddr > {
@@ -90,9 +148,11 @@ impl StaticProvider {
90148 } )
91149 }
92150
93- /// Add node info for the given node id, combining it with any existing info .
151+ /// Augments node addressing information for the given node ID .
94152///
95- /// This will add any new direct addresses and overwrite the relay url.
153+ /// The provided addressing information is combined with the existing info in the static
154+ /// provider. Any new direct addresses are added to those already present while the
155+ /// relay URL is overwritten.
96156pub fn add_node_addr ( & self , info : impl Into < NodeAddr > ) {
97157 let info: NodeAddr = info. into ( ) ;
98158 let last_updated = SystemTime :: now ( ) ;
@@ -114,7 +174,7 @@ impl StaticProvider {
114174 }
115175 }
116176
117- /// Get node info for the given node id .
177+ /// Returns node addressing information for the given node ID .
118178pub fn get_node_addr ( & self , node_id : NodeId ) -> Option < NodeAddr > {
119179 let guard = self . nodes . read ( ) . expect ( "poisoned" ) ;
120180 let info = guard. get ( & node_id) ?;
@@ -125,7 +185,9 @@ impl StaticProvider {
125185 } )
126186 }
127187
128- /// Remove node info for the given node id.
188+ /// Removes all node addressing information for the given node ID.
189+ ///
190+ /// Any removed information is returned.
129191pub fn remove_node_addr ( & self , node_id : NodeId ) -> Option < NodeAddr > {
130192 let mut guard = self . nodes . write ( ) . expect ( "poisoned" ) ;
131193 let info = guard. remove ( & node_id) ?;
0 commit comments