1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293
use gix_protocol::transport::client::Transport;
use crate::{
bstr::BString,
remote,
remote::{
fetch::{DryRun, RefMap},
ref_map, Connection,
},
Progress,
};
mod error;
pub use error::Error;
use crate::remote::fetch::WritePackedRefs;
/// The way reflog messages should be composed whenever a ref is written with recent objects from a remote.
pub enum RefLogMessage {
/// Prefix the log with `action` and generate the typical suffix as `git` would.
Prefixed {
/// The action to use, like `fetch` or `pull`.
action: String,
},
/// Control the entire message, using `message` verbatim.
Override {
/// The complete reflog message.
message: BString,
},
}
impl RefLogMessage {
pub(crate) fn compose(&self, context: &str) -> BString {
match self {
RefLogMessage::Prefixed { action } => format!("{action}: {context}").into(),
RefLogMessage::Override { message } => message.to_owned(),
}
}
}
/// The status of the repository after the fetch operation
#[derive(Debug, Clone)]
pub enum Status {
/// Nothing changed as the remote didn't have anything new compared to our tracking branches, thus no pack was received
/// and no new object was added.
///
/// As we could determine that nothing changed without remote interaction, there was no negotiation at all.
NoPackReceived {
/// If `true`, we didn't receive a pack due to dry-run mode being enabled.
dry_run: bool,
/// Information about the pack negotiation phase if negotiation happened at all.
///
/// It's possible that negotiation didn't have to happen as no reference of interest changed on the server.
negotiate: Option<outcome::Negotiate>,
/// However, depending on the refspecs, references might have been updated nonetheless to point to objects as
/// reported by the remote.
update_refs: refs::update::Outcome,
},
/// There was at least one tip with a new object which we received.
Change {
/// Information about the pack negotiation phase.
negotiate: outcome::Negotiate,
/// Information collected while writing the pack and its index.
write_pack_bundle: gix_pack::bundle::write::Outcome,
/// Information collected while updating references.
update_refs: refs::update::Outcome,
},
}
/// The outcome of receiving a pack via [`Prepare::receive()`].
#[derive(Debug, Clone)]
pub struct Outcome {
/// The result of the initial mapping of references, the prerequisite for any fetch.
pub ref_map: RefMap,
/// The status of the operation to indicate what happened.
pub status: Status,
}
/// Additional types related to the outcome of a fetch operation.
pub mod outcome {
/// Information about the negotiation phase of a fetch.
///
/// Note that negotiation can happen even if no pack is ultimately produced.
#[derive(Default, Debug, Clone)]
pub struct Negotiate {
/// The negotiation graph indicating what kind of information 'the algorithm' collected in the end.
pub graph: gix_negotiate::IdMap,
/// Additional information for each round of negotiation.
pub rounds: Vec<negotiate::Round>,
}
///
pub mod negotiate {
/// Key information about each round in the pack-negotiation.
#[derive(Debug, Clone)]
pub struct Round {
/// The amount of `HAVE` lines sent this round.
///
/// Each `HAVE` is an object that we tell the server about which would acknowledge each one it has as well.
pub haves_sent: usize,
/// A total counter, over all previous rounds, indicating how many `HAVE`s we sent without seeing a single acknowledgement,
/// i.e. the indication of a common object.
///
/// This number maybe zero or be lower compared to the previous round if we have received at least one acknowledgement.
pub in_vain: usize,
/// The amount of haves we should send in this round.
///
/// If the value is lower than `haves_sent` (the `HAVE` lines actually sent), the negotiation algorithm has run out of options
/// which typically indicates the end of the negotiation phase.
pub haves_to_send: usize,
/// If `true`, the server reported, as response to our previous `HAVE`s, that at least one of them is in common by acknowledging it.
///
/// This may also lead to the server responding with a pack.
pub previous_response_had_at_least_one_in_common: bool,
}
}
}
/// The progress ids used in during various steps of the fetch operation.
///
/// Note that tagged progress isn't very widely available yet, but support can be improved as needed.
///
/// Use this information to selectively extract the progress of interest in case the parent application has custom visualization.
#[derive(Debug, Copy, Clone)]
pub enum ProgressId {
/// The progress name is defined by the remote and the progress messages it sets, along with their progress values and limits.
RemoteProgress,
}
impl From<ProgressId> for gix_features::progress::Id {
fn from(v: ProgressId) -> Self {
match v {
ProgressId::RemoteProgress => *b"FERP",
}
}
}
pub(crate) mod negotiate;
///
pub mod prepare {
/// The error returned by [`prepare_fetch()`][super::Connection::prepare_fetch()].
#[derive(Debug, thiserror::Error)]
#[allow(missing_docs)]
pub enum Error {
#[error("Cannot perform a meaningful fetch operation without any configured ref-specs")]
MissingRefSpecs,
#[error(transparent)]
RefMap(#[from] crate::remote::ref_map::Error),
}
impl gix_protocol::transport::IsSpuriousError for Error {
fn is_spurious(&self) -> bool {
match self {
Error::RefMap(err) => err.is_spurious(),
_ => false,
}
}
}
}
impl<'remote, 'repo, T> Connection<'remote, 'repo, T>
where
T: Transport,
{
/// Perform a handshake with the remote and obtain a ref-map with `options`, and from there one
/// Note that at this point, the `transport` should already be configured using the [`transport_mut()`][Self::transport_mut()]
/// method, as it will be consumed here.
///
/// From there additional properties of the fetch can be adjusted to override the defaults that are configured via git-config.
///
/// # Async Experimental
///
/// Note that this implementation is currently limited correctly in blocking mode only as it relies on Drop semantics to close the connection
/// should the fetch not be performed. Furthermore, there the code doing the fetch is inherently blocking and it's not offloaded to a thread,
/// making this call block the executor.
/// It's best to unblock it by placing it into its own thread or offload it should usage in an async context be truly required.
#[allow(clippy::result_large_err)]
#[gix_protocol::maybe_async::maybe_async]
pub async fn prepare_fetch(
mut self,
progress: impl Progress,
options: ref_map::Options,
) -> Result<Prepare<'remote, 'repo, T>, prepare::Error> {
if self.remote.refspecs(remote::Direction::Fetch).is_empty() {
return Err(prepare::Error::MissingRefSpecs);
}
let ref_map = self.ref_map_inner(progress, options).await?;
Ok(Prepare {
con: Some(self),
ref_map,
dry_run: DryRun::No,
reflog_message: None,
write_packed_refs: WritePackedRefs::Never,
shallow: Default::default(),
})
}
}
impl<'remote, 'repo, T> Prepare<'remote, 'repo, T>
where
T: Transport,
{
/// Return the `ref_map` (that includes the server handshake) which was part of listing refs prior to fetching a pack.
pub fn ref_map(&self) -> &RefMap {
&self.ref_map
}
}
mod config;
mod receive_pack;
///
#[path = "update_refs/mod.rs"]
pub mod refs;
/// A structure to hold the result of the handshake with the remote and configure the upcoming fetch operation.
pub struct Prepare<'remote, 'repo, T>
where
T: Transport,
{
con: Option<Connection<'remote, 'repo, T>>,
ref_map: RefMap,
dry_run: DryRun,
reflog_message: Option<RefLogMessage>,
write_packed_refs: WritePackedRefs,
shallow: remote::fetch::Shallow,
}
/// Builder
impl<'remote, 'repo, T> Prepare<'remote, 'repo, T>
where
T: Transport,
{
/// If dry run is enabled, no change to the repository will be made.
///
/// This works by not actually fetching the pack after negotiating it, nor will refs be updated.
pub fn with_dry_run(mut self, enabled: bool) -> Self {
self.dry_run = if enabled { DryRun::Yes } else { DryRun::No };
self
}
/// If enabled, don't write ref updates to loose refs, but put them exclusively to packed-refs.
///
/// This improves performance and allows case-sensitive filesystems to deal with ref names that would otherwise
/// collide.
pub fn with_write_packed_refs_only(mut self, enabled: bool) -> Self {
self.write_packed_refs = if enabled {
WritePackedRefs::Only
} else {
WritePackedRefs::Never
};
self
}
/// Set the reflog message to use when updating refs after fetching a pack.
pub fn with_reflog_message(mut self, reflog_message: RefLogMessage) -> Self {
self.reflog_message = reflog_message.into();
self
}
/// Define what to do when the current repository is a shallow clone.
///
/// *Has no effect if the current repository is not as shallow clone.*
pub fn with_shallow(mut self, shallow: remote::fetch::Shallow) -> Self {
self.shallow = shallow;
self
}
}
impl<'remote, 'repo, T> Drop for Prepare<'remote, 'repo, T>
where
T: Transport,
{
fn drop(&mut self) {
if let Some(mut con) = self.con.take() {
#[cfg(feature = "async-network-client")]
{
// TODO: this should be an async drop once the feature is available.
// Right now we block the executor by forcing this communication, but that only
// happens if the user didn't actually try to receive a pack, which consumes the
// connection in an async context.
gix_protocol::futures_lite::future::block_on(gix_protocol::indicate_end_of_interaction(
&mut con.transport,
))
.ok();
}
#[cfg(not(feature = "async-network-client"))]
{
gix_protocol::indicate_end_of_interaction(&mut con.transport).ok();
}
}
}
}