refactor!: turn handshake::Outcome into Handshake type.

This includes a utility to get a refmap out of a handshake, plastering
over differences between V1 and V2 of the protocol.

Author: Byron

gix-protocol/src/fetch/handshake.rs

@@ -6,10 +6,7 @@ use maybe_async::maybe_async;
 use crate::transport::client::async_io::Transport;
 #[cfg(feature = "blocking-client")]
 use crate::transport::client::blocking_io::Transport;
-use crate::{
-    credentials,
-    handshake::{Error, Outcome},
-};
+use crate::{credentials, handshake::Error, Handshake};
 
 /// Perform a handshake with the server on the other side of `transport`, with `authenticate` being used if authentication
 /// turns out to be required. `extra_parameters` are the parameters `(name, optional value)` to add to the handshake,
@@ -22,7 +19,7 @@ pub async fn upload_pack<AuthFn, T>(
     authenticate: AuthFn,
     extra_parameters: Vec<(String, Option<String>)>,
     progress: &mut impl Progress,
-) -> Result<Outcome, Error>
+) -> Result<Handshake, Error>
 where
     AuthFn: FnMut(credentials::helper::Action) -> credentials::protocol::Result,
     T: Transport,

gix-protocol/src/fetch/response/mod.rs

@@ -185,7 +185,7 @@ impl Response {
     }
 
     /// Append the given `updates` which may have been obtained from a
-    /// (handshake::Outcome)[crate::handshake::Outcome::v1_shallow_updates].
+    /// (handshake::Outcome)[crate::handshake::Handshake::v1_shallow_updates].
     ///
     /// In V2, these are received as part of the pack, but V1 sends them early, so we
     /// offer to re-integrate them here.

gix-protocol/src/fetch/types.rs

@@ -24,7 +24,7 @@ pub struct Context<'a, T> {
     /// The outcome of the handshake performed with the remote.
     ///
     /// Note that it's mutable as depending on the protocol, it may contain refs that have been sent unconditionally.
-    pub handshake: &'a mut crate::handshake::Outcome,
+    pub handshake: &'a mut crate::Handshake,
     /// The transport to use when making an `ls-refs` or `fetch` call.
     ///
     /// This is always done if the underlying protocol is V2, which is implied by the absence of refs in the `handshake` outcome.

gix-protocol/src/handshake/function.rs

@@ -2,11 +2,12 @@ use gix_features::{progress, progress::Progress};
 use gix_transport::{client, Service};
 use maybe_async::maybe_async;
 
-use super::{Error, Outcome};
+use super::Error;
 #[cfg(feature = "async-client")]
 use crate::transport::client::async_io::{SetServiceResponse, Transport};
 #[cfg(feature = "blocking-client")]
 use crate::transport::client::blocking_io::{SetServiceResponse, Transport};
+use crate::Handshake;
 use crate::{credentials, handshake::refs};
 
 /// Perform a handshake with the server on the other side of `transport`, with `authenticate` being used if authentication
@@ -21,7 +22,7 @@ pub async fn handshake<AuthFn, T>(
     mut authenticate: AuthFn,
     extra_parameters: Vec<(String, Option<String>)>,
     progress: &mut impl Progress,
-) -> Result<Outcome, Error>
+) -> Result<Handshake, Error>
 where
     AuthFn: FnMut(credentials::helper::Action) -> credentials::protocol::Result,
     T: Transport,
@@ -103,7 +104,7 @@ where
         .map(|(refs, shallow)| (Some(refs), Some(shallow)))
         .unwrap_or_default();
 
-    Ok(Outcome {
+    Ok(Handshake {
         server_protocol_version,
         refs,
         v1_shallow_updates,

gix-protocol/src/handshake/mod.rs

@@ -50,20 +50,24 @@ pub enum Ref {
     },
 }
 
-/// The result of the [`handshake()`][super::handshake()] function.
-#[derive(Default, Debug, Clone)]
-#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg(feature = "handshake")]
-pub struct Outcome {
-    /// The protocol version the server responded with. It might have downgraded the desired version.
-    pub server_protocol_version: gix_transport::Protocol,
-    /// The references reported as part of the `Protocol::V1` handshake, or `None` otherwise as V2 requires a separate request.
-    pub refs: Option<Vec<Ref>>,
-    /// Shallow updates as part of the `Protocol::V1`, to shallow a particular object.
-    /// Note that unshallowing isn't supported here.
-    pub v1_shallow_updates: Option<Vec<crate::fetch::response::ShallowUpdate>>,
-    /// The server capabilities.
-    pub capabilities: gix_transport::client::Capabilities,
+pub(crate) mod hero {
+    use crate::handshake::Ref;
+
+    /// The result of the [`handshake()`](crate::handshake()) function.
+    #[derive(Default, Debug, Clone)]
+    #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+    pub struct Handshake {
+        /// The protocol version the server responded with. It might have downgraded the desired version.
+        pub server_protocol_version: gix_transport::Protocol,
+        /// The references reported as part of the `Protocol::V1` handshake, or `None` otherwise as V2 requires a separate request.
+        pub refs: Option<Vec<Ref>>,
+        /// Shallow updates as part of the `Protocol::V1`, to shallow a particular object.
+        /// Note that unshallowing isn't supported here.
+        pub v1_shallow_updates: Option<Vec<crate::fetch::response::ShallowUpdate>>,
+        /// The server capabilities.
+        pub capabilities: gix_transport::client::Capabilities,
+    }
 }
 
 #[cfg(feature = "handshake")]

gix-protocol/src/lib.rs

@@ -61,6 +61,8 @@ pub mod handshake;
 #[cfg(any(feature = "blocking-client", feature = "async-client"))]
 #[cfg(feature = "handshake")]
 pub use handshake::function::handshake;
+#[cfg(feature = "handshake")]
+pub use handshake::hero::Handshake;
 
 ///
 pub mod ls_refs;

gix-protocol/tests/protocol/fetch/_impl.rs

@@ -74,7 +74,7 @@ mod fetch_fn {
         P: NestedProgress + 'static,
         P::SubProgress: 'static,
     {
-        let gix_protocol::handshake::Outcome {
+        let gix_protocol::Handshake {
             server_protocol_version: protocol_version,
             refs,
             v1_shallow_updates: _ignored_shallow_updates_as_it_is_deprecated,