A more concrete sketch of how the API for obtaining mappings should look like (#450)

Author: Byron

git-repository/src/remote/connection/list_refs.rs

@@ -1,22 +1,21 @@
 use git_features::progress::Progress;
 use git_protocol::transport::client::Transport;
 
-use crate::remote::{connection::HandshakeWithRefs, fetch, Connection, Direction};
+use crate::remote::{connection::HandshakeWithRefs, Connection, Direction};
 
-mod error {
-    #[derive(Debug, thiserror::Error)]
-    pub enum Error {
-        #[error(transparent)]
-        Handshake(#[from] git_protocol::fetch::handshake::Error),
-        #[error(transparent)]
-        ListRefs(#[from] git_protocol::fetch::refs::Error),
-        #[error(transparent)]
-        Transport(#[from] git_protocol::transport::client::Error),
-        #[error(transparent)]
-        ConfigureCredentials(#[from] crate::config::credential_helpers::Error),
-    }
+/// The error returned by [`Connection::list_refs()`].
+#[derive(Debug, thiserror::Error)]
+#[allow(missing_docs)]
+pub enum Error {
+    #[error(transparent)]
+    Handshake(#[from] git_protocol::fetch::handshake::Error),
+    #[error(transparent)]
+    ListRefs(#[from] git_protocol::fetch::refs::Error),
+    #[error(transparent)]
+    Transport(#[from] git_protocol::transport::client::Error),
+    #[error(transparent)]
+    ConfigureCredentials(#[from] crate::config::credential_helpers::Error),
 }
-pub use error::Error;
 
 impl<'a, 'repo, T, P> Connection<'a, 'repo, T, P>
 where
@@ -33,13 +32,6 @@ where
         Ok(res.refs)
     }
 
-    /// A mapping showing the objects available in refs matching our ref-specs on the remote side, along with their destination
-    /// ref locally, if set and if there are no conflicts.
-    #[git_protocol::maybe_async::maybe_async]
-    pub async fn ref_mapping(self) -> Result<Vec<fetch::Mapping>, Error> {
-        todo!()
-    }
-
     #[git_protocol::maybe_async::maybe_async]
     async fn fetch_refs(&mut self) -> Result<HandshakeWithRefs, Error> {
         let mut credentials_storage;
@@ -75,15 +67,49 @@ where
         };
         Ok(HandshakeWithRefs { outcome, refs })
     }
+}
 
-    /// List all references on the remote that have been filtered through our remote's [`refspecs`][crate::Remote::refspecs()]
-    /// for _fetching_ or _pushing_ depending on `direction`.
-    ///
-    /// This comes in the form of information of all matching tips on the remote and the object they point to, along with
-    /// with the local tracking branch of these tips (if available).
-    ///
-    /// Note that this doesn't fetch the objects mentioned in the tips nor does it make any change to underlying repository.
-    pub fn list_refs_by_refspec(&mut self, _direction: Direction) -> ! {
-        todo!()
+///
+pub mod to_mapping {
+    use crate::remote::{fetch, Connection};
+    use git_features::progress::Progress;
+    use git_protocol::transport::client::Transport;
+
+    /// The error returned by [`Connection::list_refs_to_mapping()`].
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error(transparent)]
+        ListRefs(#[from] crate::remote::list_refs::Error),
+    }
+
+    impl<'a, 'repo, T, P> Connection<'a, 'repo, T, P>
+    where
+        T: Transport,
+        P: Progress,
+    {
+        /// List all references on the remote that have been filtered through our remote's [`refspecs`][crate::Remote::refspecs()]
+        /// for _fetching_.
+        ///
+        /// This comes in the form of all matching tips on the remote and the object they point to, along with
+        /// with the local tracking branch of these tips (if available).
+        ///
+        /// Note that this doesn't fetch the objects mentioned in the tips nor does it make any change to underlying repository.
+        #[git_protocol::maybe_async::maybe_async]
+        pub async fn list_refs_to_mapping(mut self) -> Result<Vec<fetch::Mapping>, Error> {
+            let mappings = self.ref_mapping().await?;
+            git_protocol::fetch::indicate_end_of_interaction(&mut self.transport)
+                .await
+                .map_err(|err| Error::ListRefs(crate::remote::list_refs::Error::Transport(err)))?;
+            Ok(mappings)
+        }
+
+        #[git_protocol::maybe_async::maybe_async]
+        async fn ref_mapping(&mut self) -> Result<Vec<fetch::Mapping>, Error> {
+            let _res = self.fetch_refs().await?;
+            let _group = git_refspec::MatchGroup::from_fetch_specs(self.remote.fetch_specs.iter().map(|s| s.to_ref()));
+            // group.match_remotes(res.refs.iter().map(|r| r.unpack()))
+            Ok(Vec::new())
+        }
     }
 }

git-repository/src/remote/connection/mod.rs

@@ -6,6 +6,7 @@ pub(crate) struct HandshakeWithRefs {
     refs: Vec<git_protocol::fetch::Ref>,
 }
 
+/// A function that performs a given credential action.
 pub type CredentialsFn<'a> = Box<dyn FnMut(git_credentials::helper::Action) -> git_credentials::protocol::Result + 'a>;
 
 /// A type to represent an ongoing connection to a remote host, typically with the connection already established.
@@ -65,4 +66,5 @@ mod access {
     }
 }
 
-mod list_refs;
+///
+pub mod list_refs;

git-repository/src/remote/mod.rs

@@ -46,7 +46,7 @@ pub mod connect;
 #[cfg(any(feature = "async-network-client", feature = "blocking-network-client"))]
 mod connection;
 #[cfg(any(feature = "async-network-client", feature = "blocking-network-client"))]
-pub use connection::Connection;
+pub use connection::{list_refs, Connection};
 
 mod access;
 pub(crate) mod url;

git-repository/tests/remote/list_refs.rs

@@ -22,10 +22,13 @@ mod blocking_io {
                     (version as u8).to_string().as_str(),
                 )?;
             }
+
             let remote = repo.find_remote("origin")?;
-            let connection = remote.connect(Fetch, progress::Discard)?;
-            let refs = connection.list_refs()?;
-            assert_eq!(refs.len(), 14, "it gets all remote refs, independently of the refspec.");
+            {
+                let connection = remote.connect(Fetch, progress::Discard)?;
+                let refs = connection.list_refs()?;
+                assert_eq!(refs.len(), 14, "it gets all remote refs, independently of the refspec.");
+            }
         }
         Ok(())
     }