refactor

Author: Byron

gitoxide-core/src/pack/receive.rs

@@ -88,7 +88,7 @@ where
         extra_refspecs: vec![],
     };
 
-    let fetch_refmap = handshake.fetch_or_extract_refmap(user_agent.clone(), true, context)?;
+    let fetch_refmap = handshake.prepare_lsrefs_or_extract_refmap(user_agent.clone(), true, context)?;
 
     #[cfg(feature = "async-client")]
     let refmap = fetch_refmap

gix-protocol/src/fetch/negotiate.rs

@@ -111,7 +111,7 @@ pub struct Round {
 /// * `graph`
 ///     - The commit-graph for use by the `negotiator` - we populate it with tips to initialize the graph traversal.
 /// * `ref_map`
-///     - The references known on the remote, as previously obtained with [`crate::Handshake::fetch_or_extract_refmap()`].
+///     - The references known on the remote, as previously obtained with [`crate::Handshake::prepare_lsrefs_or_extract_refmap()`].
 /// * `shallow`
 ///     - How to deal with shallow repositories. It does affect how negotiations are performed.
 /// * `mapping_is_ignored`

gix-protocol/src/fetch/refmap/init.rs

@@ -9,7 +9,7 @@ use crate::{
     handshake::Ref,
 };
 
-/// The error returned by [`crate::Handshake::fetch_or_extract_refmap()`].
+/// The error returned by [`crate::Handshake::prepare_lsrefs_or_extract_refmap()`].
 #[derive(Debug, thiserror::Error)]
 #[allow(missing_docs)]
 pub enum Error {

gix-protocol/src/fetch/types.rs

@@ -18,7 +18,7 @@ pub struct Options<'a> {
     pub reject_shallow_remote: bool,
 }
 
-/// For use in [`crate::Handshake::fetch_or_extract_refmap()`] and [`fetch`](crate::fetch()).
+/// For use in [`crate::Handshake::prepare_lsrefs_or_extract_refmap()`] and [`fetch`](crate::fetch()).
 #[cfg(feature = "handshake")]
 pub struct Context<'a, T> {
     /// The outcome of the handshake performed with the remote.
@@ -29,7 +29,7 @@ pub struct Context<'a, T> {
     ///
     /// This is always done if the underlying protocol is V2, which is implied by the absence of refs in the `handshake` outcome.
     pub transport: &'a mut T,
-    /// How to self-identify during the `ls-refs` call in [`crate::Handshake::fetch_or_extract_refmap()`] or the `fetch` call in [`fetch()`](crate::fetch()).
+    /// How to self-identify during the `ls-refs` call in [`crate::Handshake::prepare_lsrefs_or_extract_refmap()`] or the `fetch` call in [`fetch()`](crate::fetch()).
     ///
     /// This could be read from the `gitoxide.userAgent` configuration variable.
     pub user_agent: (&'static str, Option<std::borrow::Cow<'static, str>>),

gix-protocol/src/handshake/mod.rs

@@ -80,74 +80,75 @@ pub(crate) mod hero {
         use std::borrow::Cow;
 
         /// Intermediate state while potentially fetching a refmap after the handshake.
-        pub enum FetchRefMap<'a> {
-            /// We already got a refmap to use from the handshake.
-            Map(RefMap),
-            /// We need to invoke another command to get the refmap.
-            Command(crate::LsRefsCommand<'a>, crate::fetch::refmap::init::Context),
+        pub enum ObtainRefMap<'a> {
+            /// We already got a refmap to use from the V1 handshake, which always sends them.
+            Existing(RefMap),
+            /// We need to invoke another `ls-refs` command to retrieve the refmap as part of the V2 protocol.
+            LsRefsCommand(crate::LsRefsCommand<'a>, crate::fetch::refmap::init::Context),
         }
 
-        impl FetchRefMap<'_> {
-            /// Fetch the refmap, either by returning the existing one or invoking the command.
+        impl ObtainRefMap<'_> {
+            /// Fetch the refmap, either by returning the existing one or invoking the `ls-refs` command.
             #[cfg(feature = "async-client")]
             #[allow(clippy::result_large_err)]
             pub async fn fetch_async(
                 self,
                 mut progress: impl Progress,
                 transport: &mut impl async_io::Transport,
                 trace_packetlines: bool,
-            ) -> Result<crate::fetch::RefMap, crate::fetch::refmap::init::Error> {
+            ) -> Result<RefMap, crate::fetch::refmap::init::Error> {
                 let (cmd, cx) = match self {
-                    FetchRefMap::Map(map) => return Ok(map),
-                    FetchRefMap::Command(cmd, cx) => (cmd, cx),
+                    ObtainRefMap::Existing(map) => return Ok(map),
+                    ObtainRefMap::LsRefsCommand(cmd, cx) => (cmd, cx),
                 };
 
+                let _span = gix_trace::coarse!("gix_protocol::handshake::ObtainRefMap::fetch_async()");
                 let capabilities = cmd.capabilities;
                 let remote_refs = cmd.invoke_async(transport, &mut progress, trace_packetlines).await?;
                 RefMap::from_refs(remote_refs, capabilities, cx)
             }
 
-            /// Fetch the refmap, either by returning the existing one or invoking the command.
+            /// Fetch the refmap, either by returning the existing one or invoking the `ls-refs` command.
             #[cfg(feature = "blocking-client")]
             #[allow(clippy::result_large_err)]
             pub fn fetch_blocking(
                 self,
                 mut progress: impl Progress,
                 transport: &mut impl blocking_io::Transport,
                 trace_packetlines: bool,
-            ) -> Result<crate::fetch::RefMap, crate::fetch::refmap::init::Error> {
+            ) -> Result<RefMap, crate::fetch::refmap::init::Error> {
                 let (cmd, cx) = match self {
-                    FetchRefMap::Map(map) => return Ok(map),
-                    FetchRefMap::Command(cmd, cx) => (cmd, cx),
+                    ObtainRefMap::Existing(map) => return Ok(map),
+                    ObtainRefMap::LsRefsCommand(cmd, cx) => (cmd, cx),
                 };
 
+                let _span = gix_trace::coarse!("gix_protocol::handshake::ObtainRefMap::fetch_blocking()");
                 let capabilities = cmd.capabilities;
                 let remote_refs = cmd.invoke_blocking(transport, &mut progress, trace_packetlines)?;
                 RefMap::from_refs(remote_refs, capabilities, cx)
             }
         }
 
         impl Handshake {
-            /// Prepare fetching a [refmap](crate::fetch::RefMap) if not present in the handshake.
+            /// Prepare fetching a [refmap](RefMap) if not present in the handshake.
             #[allow(clippy::result_large_err)]
-            pub fn fetch_or_extract_refmap(
+            pub fn prepare_lsrefs_or_extract_refmap(
                 &mut self,
                 user_agent: (&'static str, Option<Cow<'static, str>>),
                 prefix_from_spec_as_filter_on_remote: bool,
                 refmap_context: crate::fetch::refmap::init::Context,
-            ) -> Result<FetchRefMap<'_>, crate::fetch::refmap::init::Error> {
+            ) -> Result<ObtainRefMap<'_>, crate::fetch::refmap::init::Error> {
                 if let Some(refs) = self.refs.take() {
-                    return Ok(FetchRefMap::Map(crate::fetch::RefMap::from_refs(
+                    return Ok(ObtainRefMap::Existing(RefMap::from_refs(
                         refs,
                         &self.capabilities,
                         refmap_context,
                     )?));
                 }
 
-                let _span = gix_trace::coarse!("gix_protocol::handshake::fetch_or_extract_refmap()");
                 let all_refspecs = refmap_context.aggregate_refspecs();
                 let prefix_refspecs = prefix_from_spec_as_filter_on_remote.then_some(&all_refspecs[..]);
-                Ok(FetchRefMap::Command(
+                Ok(ObtainRefMap::LsRefsCommand(
                     crate::LsRefsCommand::new(prefix_refspecs, &self.capabilities, user_agent),
                     refmap_context,
                 ))

gix-protocol/src/ls_refs.rs

@@ -48,6 +48,9 @@ pub(crate) mod function {
     };
 
     /// A command to list references from a remote Git repository.
+    ///
+    /// It acts as a utility to separate the invocation into the shared blocking portion,
+    /// and the one that performs IO either blocking or `async`.
     pub struct LsRefsCommand<'a> {
         pub(crate) capabilities: &'a Capabilities,
         features: Vec<(&'static str, Option<Cow<'static, str>>)>,
@@ -62,8 +65,6 @@ pub(crate) mod function {
             capabilities: &'a Capabilities,
             agent: (&'static str, Option<Cow<'static, str>>),
         ) -> Self {
-            let _span =
-                gix_features::trace::detail!("gix_protocol::LsRefsCommand::new()", capabilities = ?capabilities);
             let ls_refs = Command::LsRefs;
             let mut features = ls_refs.default_features(gix_transport::Protocol::V2, capabilities);
             features.push(agent);
@@ -109,6 +110,7 @@ pub(crate) mod function {
             progress: &mut impl Progress,
             trace: bool,
         ) -> Result<Vec<Ref>, Error> {
+            let _span = gix_features::trace::detail!("gix_protocol::LsRefsCommand::invoke_async()");
             Command::LsRefs.validate_argument_prefixes(
                 gix_transport::Protocol::V2,
                 self.capabilities,
@@ -144,6 +146,7 @@ pub(crate) mod function {
             progress: &mut impl Progress,
             trace: bool,
         ) -> Result<Vec<Ref>, Error> {
+            let _span = gix_features::trace::detail!("gix_protocol::LsRefsCommand::invoke_blocking()");
             Command::LsRefs.validate_argument_prefixes(
                 gix_transport::Protocol::V2,
                 self.capabilities,

gix/src/remote/connection/ref_map.rs

@@ -157,7 +157,7 @@ where
             extra_refspecs,
         };
 
-        let fetch_refmap = handshake.fetch_or_extract_refmap(
+        let fetch_refmap = handshake.prepare_lsrefs_or_extract_refmap(
             self.remote.repo.config.user_agent_tuple(),
             prefix_from_spec_as_filter_on_remote,
             context,