feat: initial qlog support in iroh

Author: Frando

Cargo.lock

@@ -151,6 +151,7 @@ metrics = ["iroh-metrics/metrics", "iroh-relay/metrics", "portmapper/metrics"]
 test-utils = ["iroh-relay/test-utils", "iroh-relay/server", "dep:axum"]
 discovery-local-network = ["dep:swarm-discovery"]
 discovery-pkarr-dht = ["pkarr/dht"]
+qlog = ["quinn/qlog"]
 
 [package.metadata.docs.rs]
 all-features = true

iroh/Cargo.toml

@@ -1333,7 +1333,7 @@ mod tests {
         discovery::static_provider::StaticProvider,
         endpoint::{ConnectOptions, Connection},
         protocol::{AcceptError, ProtocolHandler, Router},
-        test_utils::{run_relay_server, run_relay_server_with},
+        test_utils::{QlogFileGroup, run_relay_server, run_relay_server_with},
     };
 
     const TEST_ALPN: &[u8] = b"n0/iroh/test";
@@ -1363,9 +1363,12 @@ mod tests {
         let server_secret_key = SecretKey::generate(&mut rng);
         let server_peer_id = server_secret_key.public();
 
+        let qlog = QlogFileGroup::from_env("endpoint_connect_close");
+
         // Wait for the endpoint to be started to make sure it's up before clients try to connect
         let ep = Endpoint::empty_builder(RelayMode::Custom(relay_map.clone()))
             .secret_key(server_secret_key)
+            .transport_config(qlog.server("server")?)
             .alpns(vec![TEST_ALPN.to_vec()])
             .insecure_skip_relay_cert_verify(true)
             .bind()
@@ -1406,6 +1409,7 @@ mod tests {
                 let ep = Endpoint::empty_builder(RelayMode::Custom(relay_map))
                     .alpns(vec![TEST_ALPN.to_vec()])
                     .insecure_skip_relay_cert_verify(true)
+                    .transport_config(qlog.client("client")?)
                     .bind()
                     .await?;
                 info!("client connecting");

iroh/src/endpoint.rs

@@ -1,7 +1,6 @@
 //! Internal utilities to support testing.
 use std::net::Ipv4Addr;
 
-pub use dns_and_pkarr_servers::DnsPkarrServer;
 use iroh_base::RelayUrl;
 use iroh_relay::{
     RelayConfig, RelayMap, RelayQuicConfig,
@@ -12,6 +11,10 @@ use iroh_relay::{
 };
 use tokio::sync::oneshot;
 
+pub use self::{dns_and_pkarr_servers::DnsPkarrServer, qlog::QlogFileGroup};
+
+mod qlog;
+
 /// A drop guard to clean up test infrastructure.
 ///
 /// After dropping the test infrastructure will asynchronously shutdown and release its

iroh/src/test_utils.rs

@@ -0,0 +1,142 @@
+//! Utils for emitting qlog files from iroh endpoint.
+
+use std::path::{Path, PathBuf};
+#[cfg(feature = "qlog")]
+use std::time::Instant;
+
+use n0_error::Result;
+use quinn::TransportConfig;
+#[cfg(feature = "qlog")]
+use quinn_proto::{QlogConfig, VantagePointType};
+
+/// Builder to create one or more related qlog configs.
+///
+/// This struct is available independently of feature flags, but if the "qlog" feature is not enabled
+/// it does not do anything.
+#[derive(Debug)]
+pub struct QlogFileGroup {
+    #[cfg(feature = "qlog")]
+    directory: PathBuf,
+    #[cfg(feature = "qlog")]
+    title: String,
+    #[cfg(feature = "qlog")]
+    start: Instant,
+}
+
+impl QlogFileGroup {
+    /// Creates a new [`QlogFileGroup] that is only enabled if feature flags and environment variables match.
+    ///
+    /// The qlog files will be written to `CARGO_MANIFEST_DIR/qlog`.
+    ///
+    /// The [`QlogFileGroup] can be used independent of feature flags, but it will only emit qlog files
+    /// if the "qlog" feature is enabled and the environment variable IROH_TEST_QLOG is set to 1.
+    pub fn from_env(title: impl ToString) -> Self {
+        let directory = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("qlog");
+        Self::new(directory, title)
+    }
+
+    /// Creates a new [`QlogFileGroup`] that writes qlog files to the specified directory.
+    ///
+    /// The [`QlogFileGroup] can be used independent of feature flags, but it will only emit qlog files
+    /// if the "qlog" feature is enabled and the environment variable IROH_TEST_QLOG is set to 1.
+    pub fn new(directory: impl AsRef<Path>, title: impl ToString) -> Self {
+        #[cfg(not(feature = "qlog"))]
+        let this = {
+            let _ = directory;
+            let _ = title;
+            Self {}
+        };
+
+        #[cfg(feature = "qlog")]
+        let this = Self {
+            title: title.to_string(),
+            directory: directory.as_ref().to_owned(),
+            start: Instant::now(),
+        };
+
+        this
+    }
+
+    /// Creates a [`TransportConfig`] that emits qlog files with a client vantage point, if enabled.
+    ///
+    /// If the "qlog" feature is enabled, and the environment varialbe IROH_TEST_QLOG is set to "1",
+    /// this returns a transport config that writes qlog configs to the configured output directory.
+    /// Otherwise, a default transport config is returned.
+    pub fn client(&self, name: impl ToString) -> Result<TransportConfig> {
+        #[cfg(not(feature = "qlog"))]
+        let config = {
+            let _ = name;
+            TransportConfig::default()
+        };
+
+        #[cfg(feature = "qlog")]
+        let config = if std::env::var("IROH_TEST_QLOG").ok().as_deref() == Some("1") {
+            self.transport_config(name.to_string(), VantagePointType::Client)?
+        } else {
+            TransportConfig::default()
+        };
+        Ok(config)
+    }
+
+    /// Creates a [`TransportConfig`] that emits qlog files with a server vantage point, if enabled.
+    ///
+    /// If the "qlog" feature is enabled, and the environment varialbe IROH_TEST_QLOG is set to "1",
+    /// this returns a transport config that writes qlog configs to the configured output directory.
+    /// Otherwise, a default transport config is returned.
+    pub fn server(&self, name: impl ToString) -> Result<TransportConfig> {
+        #[cfg(not(feature = "qlog"))]
+        let config = {
+            let _ = name;
+            TransportConfig::default()
+        };
+
+        #[cfg(feature = "qlog")]
+        let config = if std::env::var("IROH_TEST_QLOG").ok().as_deref() == Some("1") {
+            self.transport_config(name.to_string(), VantagePointType::Server)?
+        } else {
+            TransportConfig::default()
+        };
+        Ok(config)
+    }
+
+    /// Creates a qlog config with a client vantage point.
+    #[cfg(feature = "qlog")]
+    pub fn client_config(&self, name: impl ToString) -> Result<QlogConfig> {
+        self.qlog_config(name.to_string(), VantagePointType::Client)
+    }
+
+    /// Creates a qlog config with a server vantage point.
+    #[cfg(feature = "qlog")]
+    pub fn server_config(&self, name: impl ToString) -> Result<QlogConfig> {
+        self.qlog_config(name.to_string(), VantagePointType::Server)
+    }
+
+    #[cfg(feature = "qlog")]
+    fn transport_config(
+        &self,
+        name: String,
+        vantage_point: VantagePointType,
+    ) -> Result<TransportConfig> {
+        let mut transport_config = TransportConfig::default();
+        let qlog = self.qlog_config(name, vantage_point)?;
+        transport_config.qlog_stream(qlog.into_stream());
+        Ok(transport_config)
+    }
+
+    #[cfg(feature = "qlog")]
+    fn qlog_config(&self, name: String, vantage_point: VantagePointType) -> Result<QlogConfig> {
+        let full_name = format!("{}.{}", self.title, name);
+        let file_name = format!("{full_name}.qlog");
+        let file_path = self.directory.join(file_name);
+        std::fs::create_dir_all(file_path.parent().unwrap())?;
+        let file = std::fs::File::create(file_path)?;
+        let writer = std::io::BufWriter::new(file);
+
+        let mut qlog = quinn::QlogConfig::default();
+        qlog.vantage_point(vantage_point, Some(name.clone()))
+            .start_time(self.start)
+            .writer(Box::new(writer))
+            .title(Some(full_name));
+        Ok(qlog)
+    }
+}