move all possible code from gix to gix-protocol.

For now, just move the code down and immediately re-integrate in `gix`
to be able to use its tests to validate it.

Author: Byron

Cargo.lock

@@ -55,6 +55,7 @@ gix-hash = { version = "^0.15.1", path = "../gix-hash" }
 gix-date = { version = "^0.9.2", path = "../gix-date" }
 gix-credentials = { version = "^0.25.1", path = "../gix-credentials" }
 gix-utils = { version = "^0.1.13", path = "../gix-utils" }
+gix-refspec = { version = "^0.27.0", path = "../gix-refspec" }
 
 thiserror = "2.0.0"
 serde = { version = "1.0.114", optional = true, default-features = false, features = [

gix-protocol/Cargo.toml

@@ -9,3 +9,42 @@ pub use response::Response;
 
 mod handshake;
 pub use handshake::upload_pack as handshake;
+
+mod refmap;
+
+/// A type to represent an ongoing connection to a remote host, typically with the connection already established.
+///
+/// It can be used to perform a variety of operations with the remote without worrying about protocol details,
+/// much like a remote procedure call.
+pub struct Connection<'a, T> {
+    // TODO: figure out how to abstract `Remote`.
+    pub(crate) authenticate: Option<crate::AuthenticateFn<'a>>,
+    pub(crate) transport_options: Option<Box<dyn std::any::Any>>,
+    pub(crate) transport: T,
+    pub(crate) trace: bool,
+}
+
+/// Information about the relationship between our refspecs, and remote references with their local counterparts.
+#[derive(Default, Debug, Clone)]
+#[cfg(any(feature = "blocking-client", feature = "async-client"))]
+pub struct RefMap {
+    /// A mapping between a remote reference and a local tracking branch.
+    pub mappings: Vec<refmap::Mapping>,
+    /// Refspecs which have been added implicitly due to settings of the `remote`, possibly pre-initialized from
+    /// [`extra_refspecs` in RefMap options][crate::remote::ref_map::Options::extra_refspecs].
+    ///
+    /// They are never persisted nor are they typically presented to the user.
+    pub extra_refspecs: Vec<gix_refspec::RefSpec>,
+    /// Information about the fixes applied to the `mapping` due to validation and sanitization.
+    pub fixes: Vec<gix_refspec::match_group::validate::Fix>,
+    /// All refs advertised by the remote.
+    pub remote_refs: Vec<crate::handshake::Ref>,
+    /// Additional information provided by the server as part of the handshake.
+    ///
+    /// Note that the `refs` field is always `None` as the refs are placed in `remote_refs`.
+    pub handshake: crate::handshake::Outcome,
+    /// The kind of hash used for all data sent by the server, if understood by this client implementation.
+    ///
+    /// It was extracted from the `handshake` as advertised by the server.
+    pub object_hash: gix_hash::Kind,
+}

gix-protocol/src/fetch/mod.rs

@@ -0,0 +1,106 @@
+/// Either an object id that the remote has or the matched remote ref itself.
+#[derive(Debug, Clone)]
+#[cfg(any(feature = "blocking-client", feature = "async-client"))]
+pub enum Source {
+    /// An object id, as the matched ref-spec was an object id itself.
+    ObjectId(gix_hash::ObjectId),
+    /// The remote reference that matched the ref-specs name.
+    Ref(crate::handshake::Ref),
+}
+
+#[cfg(any(feature = "blocking-client", feature = "async-client"))]
+impl Source {
+    /// Return either the direct object id we refer to or the direct target that a reference refers to.
+    /// The latter may be a direct or a symbolic reference.
+    /// If unborn, `None` is returned.
+    pub fn as_id(&self) -> Option<&gix_hash::oid> {
+        match self {
+            Source::ObjectId(id) => Some(id),
+            Source::Ref(r) => r.unpack().1,
+        }
+    }
+
+    /// Return the target that this symbolic ref is pointing to, or `None` if it is no symbolic ref.
+    pub fn as_target(&self) -> Option<&bstr::BStr> {
+        match self {
+            Source::ObjectId(_) => None,
+            Source::Ref(r) => match r {
+                crate::handshake::Ref::Peeled { .. } | crate::handshake::Ref::Direct { .. } => None,
+                crate::handshake::Ref::Symbolic { target, .. } | crate::handshake::Ref::Unborn { target, .. } => {
+                    Some(target.as_ref())
+                }
+            },
+        }
+    }
+
+    /// Returns the peeled id of this instance, that is the object that can't be de-referenced anymore.
+    pub fn peeled_id(&self) -> Option<&gix_hash::oid> {
+        match self {
+            Source::ObjectId(id) => Some(id),
+            Source::Ref(r) => {
+                let (_name, target, peeled) = r.unpack();
+                peeled.or(target)
+            }
+        }
+    }
+
+    /// Return ourselves as the full name of the reference we represent, or `None` if this source isn't a reference but an object.
+    pub fn as_name(&self) -> Option<&bstr::BStr> {
+        match self {
+            Source::ObjectId(_) => None,
+            Source::Ref(r) => match r {
+                crate::handshake::Ref::Unborn { full_ref_name, .. }
+                | crate::handshake::Ref::Symbolic { full_ref_name, .. }
+                | crate::handshake::Ref::Direct { full_ref_name, .. }
+                | crate::handshake::Ref::Peeled { full_ref_name, .. } => Some(full_ref_name.as_ref()),
+            },
+        }
+    }
+}
+
+/// An index into various lists of refspecs that have been used in a [Mapping] of remote references to local ones.
+#[cfg(any(feature = "blocking-client", feature = "async-client"))]
+#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Ord, PartialOrd)]
+pub enum SpecIndex {
+    /// An index into the _refspecs of the remote_ that triggered a fetch operation.
+    /// These refspecs are explicit and visible to the user.
+    ExplicitInRemote(usize),
+    /// An index into the list of [extra refspecs][crate::remote::fetch::RefMap::extra_refspecs] that are implicit
+    /// to a particular fetch operation.
+    Implicit(usize),
+}
+
+#[cfg(any(feature = "blocking-client", feature = "async-client"))]
+impl SpecIndex {
+    /// Depending on our index variant, get the index either from `refspecs` or from `extra_refspecs` for `Implicit` variants.
+    pub fn get<'a>(
+        self,
+        refspecs: &'a [gix_refspec::RefSpec],
+        extra_refspecs: &'a [gix_refspec::RefSpec],
+    ) -> Option<&'a gix_refspec::RefSpec> {
+        match self {
+            SpecIndex::ExplicitInRemote(idx) => refspecs.get(idx),
+            SpecIndex::Implicit(idx) => extra_refspecs.get(idx),
+        }
+    }
+
+    /// If this is an `Implicit` variant, return its index.
+    pub fn implicit_index(self) -> Option<usize> {
+        match self {
+            SpecIndex::Implicit(idx) => Some(idx),
+            SpecIndex::ExplicitInRemote(_) => None,
+        }
+    }
+}
+
+/// A mapping between a single remote reference and its advertised objects to a local destination which may or may not exist.
+#[derive(Debug, Clone)]
+#[cfg(any(feature = "blocking-client", feature = "async-client"))]
+pub struct Mapping {
+    /// The reference on the remote side, along with information about the objects they point to as advertised by the server.
+    pub remote: Source,
+    /// The local tracking reference to update after fetching the object visible via `remote`.
+    pub local: Option<bstr::BString>,
+    /// The index into the fetch ref-specs used to produce the mapping, allowing it to be recovered.
+    pub spec_index: SpecIndex,
+}

gix-protocol/src/fetch/refmap.rs

@@ -10,6 +10,11 @@
 #![cfg_attr(all(doc, feature = "document-features"), feature(doc_cfg, doc_auto_cfg))]
 #![deny(missing_docs, rust_2018_idioms, unsafe_code)]
 
+/// A function that performs a given credential action, trying to obtain credentials for an operation that needs it.
+///
+/// Useful for both `fetch` and `push`.
+pub type AuthenticateFn<'a> = Box<dyn FnMut(gix_credentials::helper::Action) -> gix_credentials::protocol::Result + 'a>;
+
 /// A selector for V2 commands to invoke on the server for purpose of pre-invocation validation.
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
 pub enum Command {