PR review feedback:

- rename :net_report::Config to Nnet_report::NetReportConfig
- better documentation of net report config options

Author: rklaehn

iroh/src/endpoint.rs

@@ -101,7 +101,7 @@ pub use self::{
 #[cfg(not(wasm_browser))]
 use crate::socket::transports::IpConfig;
 use crate::socket::transports::TransportConfig;
-pub use crate::{net_report::Config as NetReportConfig, portmapper::PortmapperConfig};
+pub use crate::{net_report::NetReportConfig, portmapper::PortmapperConfig};
 
 /// Builder for [`Endpoint`].
 ///
@@ -706,10 +706,13 @@ impl Builder {
         self
     }
 
-    /// Configures the net report service.
+    /// Configures the net report.
     ///
-    /// Controls which probes (HTTPS latency, captive portal detection) are run.
-    /// Defaults to all probes enabled.
+    /// The net report component is responsible for figuring out if and how the endpoint is connected to the internet.
+    /// It does this by doing various probes to the configured relay servers to get public addresses, NAT behaviour, and
+    /// relay latencies. In addition it tries to detect captive portals.
+    ///
+    /// Some non-essential features of the net report component can be disabled via this configuration.
     pub fn net_report_config(mut self, config: NetReportConfig) -> Self {
         self.net_report_config = config;
         self

iroh/src/lib.rs

@@ -276,9 +276,7 @@ pub use iroh_base::{
 pub use iroh_relay::dns;
 pub use iroh_relay::{RelayConfig, RelayMap, endpoint_info};
 pub use n0_watcher::Watcher;
-pub use net_report::{
-    Config as NetReportConfig, Report as NetReport, TIMEOUT as NET_REPORT_TIMEOUT,
-};
+pub use net_report::{NetReportConfig, Report as NetReport, TIMEOUT as NET_REPORT_TIMEOUT};
 
 #[cfg(any(test, feature = "test-utils"))]
 pub mod test_utils;

iroh/src/net_report.rs

@@ -85,26 +85,38 @@ pub use self::{
 };
 pub(crate) use self::{options::Options, reportgen::QuicConfig};
 
-/// Configuration for the net report service.
+/// Configuration for the net report component.
 ///
 /// Controls which probes and checks are performed when generating network reports.
 /// All options default to `true`.
 #[derive(Debug, Clone)]
 #[non_exhaustive]
-pub struct Config {
+pub struct NetReportConfig {
     /// Run HTTPS latency probes against relay servers.
     ///
-    /// Disable this on constrained devices where the extra TCP connections are
-    /// too expensive — QAD (UDP) probes already measure relay latency.
+    /// HTTPS latency probes perform an empty HTTPS GET request to each configured
+    /// relay server and measure latency.
+    ///
+    /// They are performed in addition to the QUIC address discovery (QAD) probes.
+    /// They are the only way to detect relay latencies and thus the preferred relay
+    /// in networks that do not allow QUIC traffic.
+    ///
+    /// Disabling them is harmless on networks that do allow QUIC traffic, but will
+    /// completely prevent finding the home relay on networks that do block QUIC.
     pub https_probes: bool,
+
     /// Check for captive portals when generating the first report.
     ///
-    /// Disable this on embedded devices or environments where captive portal
-    /// detection is not meaningful.
+    /// This is done by accessing a well-known URL that is available on each relay
+    /// server, `/generate_204`. If a GET request to this URL returns anything else
+    /// but a 204 No Content response, we assume we are behind a captive portal.
+    ///
+    /// When we have detected that we are behind a captive portal, we try to contact
+    /// the relay servers more frequently in case the captive portal status changes.
     pub captive_portal_check: bool,
 }
 
-impl Config {
+impl NetReportConfig {
     /// Creates a minimal configuration that disables all optional probes and checks.
     pub fn minimal() -> Self {
         Self {
@@ -114,7 +126,7 @@ impl Config {
     }
 }
 
-impl Default for Config {
+impl Default for NetReportConfig {
     fn default() -> Self {
         Self {
             https_probes: true,

iroh/src/net_report/options.rs

@@ -6,7 +6,7 @@ pub(crate) use imp::Options;
 mod imp {
     use std::collections::BTreeSet;
 
-    use crate::net_report::{Config, QuicConfig, probes::Probe};
+    use crate::net_report::{NetReportConfig, QuicConfig, probes::Probe};
 
     /// Options for running probes
     ///
@@ -22,15 +22,15 @@ mod imp {
         /// TLS config for HTTPS probes.
         pub(crate) tls_config: rustls::ClientConfig,
         /// User-facing configuration.
-        pub(crate) user_config: Config,
+        pub(crate) user_config: NetReportConfig,
     }
 
     impl Options {
         pub(crate) fn new(tls_config: rustls::ClientConfig) -> Self {
             Self {
                 quic_config: None,
                 tls_config,
-                user_config: Config::default(),
+                user_config: NetReportConfig::default(),
             }
         }
         /// Enable quic probes
@@ -40,7 +40,7 @@ mod imp {
         }
 
         /// Set the net report configuration.
-        pub(crate) fn net_report_config(mut self, config: Config) -> Self {
+        pub(crate) fn net_report_config(mut self, config: NetReportConfig) -> Self {
             self.user_config = config;
             self
         }
@@ -68,7 +68,7 @@ mod imp {
 mod imp {
     use std::collections::BTreeSet;
 
-    use crate::net_report::{Config, Probe};
+    use crate::net_report::{NetReportConfig, Probe};
 
     /// Options for running probes (in browsers).
     ///
@@ -77,20 +77,20 @@ mod imp {
     #[derive(Debug, Clone)]
     pub(crate) struct Options {
         /// User-facing configuration.
-        pub(crate) user_config: Config,
+        pub(crate) user_config: NetReportConfig,
     }
 
     impl Default for Options {
         fn default() -> Self {
             Self {
-                user_config: Config::default(),
+                user_config: NetReportConfig::default(),
             }
         }
     }
 
     impl Options {
         /// Set the net report configuration.
-        pub(crate) fn net_report_config(mut self, config: Config) -> Self {
+        pub(crate) fn net_report_config(mut self, config: NetReportConfig) -> Self {
             self.user_config = config;
             self
         }

iroh/src/socket.rs

@@ -150,7 +150,7 @@ pub(crate) struct Options {
     pub(crate) hooks: EndpointHooksList,
     pub(crate) transport_bias: TransportBiasMap,
     pub(crate) portmapper_config: portmapper::PortmapperConfig,
-    pub(crate) net_report_config: crate::net_report::Config,
+    pub(crate) net_report_config: crate::net_report::NetReportConfig,
 
     /// Static configuration for the endpoint.
     pub(crate) static_config: StaticConfig,