Struct Connection

pub struct Connection<'a, 'repo, T>
where
    T: Transport,
{ /* private fields */ }

Available on crate features async-network-client or blocking-network-client only.

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.

Implementations

impl<'a, T> Connection<'a, '_, T>

where T: Transport,

Builder

pub fn with_credentials(self, helper: impl FnMut(Action) -> Result + 'a) -> Self

Set a custom credentials callback to provide credentials if the remotes require authentication.

Otherwise, we will use the git configuration to perform the same task as the git credential helper program, which is calling other helper programs in succession while resorting to a prompt to obtain credentials from the user.

A custom function may also be used to prevent accessing resources with authentication.

Use the configured_credentials() method to obtain the implementation that would otherwise be used, which can be useful to proxy the default configuration and obtain information about the URLs to authenticate with.

pub fn with_transport_options(self, config: Box<dyn Any>) -> Self

Provide configuration to be used before the first handshake is conducted. It’s typically created by initializing it with Repository::transport_options(), which is also the default if this isn’t set explicitly. Note that all the default configuration is created from git configuration, which can also be manipulated through overrides to affect the default configuration.

Use this method to provide transport configuration with custom backend configuration that is not configurable by other means and custom to the application at hand.

impl<'a, T> Connection<'a, '_, T>

where T: Transport,

Mutation

pub fn set_credentials( &mut self, helper: impl FnMut(Action) -> Result + 'a, ) -> &mut Self

Like with_credentials(), but without consuming the connection.

pub fn set_transport_options(&mut self, config: Box<dyn Any>) -> &mut Self

Like with_transport_options(), but without consuming the connection.

impl<'repo, T> Connection<'_, 'repo, T>

where T: Transport,

Access

pub fn configured_credentials( &self, url: Url, ) -> Result<AuthenticateFn<'static>, Error>

A utility to return a function that will use this repository’s configuration to obtain credentials, similar to what git credential is doing.

It’s meant to be used by users of the with_credentials() builder to gain access to the default way of handling credentials, which they can call as fallback.

pub fn remote(&self) -> &Remote<'repo>

Return the underlying remote that instantiate this connection.

pub fn transport_mut(&mut self) -> &mut T

Provide a mutable transport to allow interacting with it according to its actual type. Note that the caller should not call configure() as we will call it automatically before performing the handshake. Instead, to bring in custom configuration, call with_transport_options().

impl<T> Connection<'_, '_, T>

where T: Transport,

pub fn ref_map( self, progress: impl Progress, options: Options, ) -> Result<(RefMap, Outcome), Error>

List all references on the remote that have been filtered through our remote’s refspecs for fetching.

This comes in the form of all matching tips on the remote and the object they point to, along 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.

Consumption

Due to management of the transport, it’s cleanest to only use it for a single interaction. Thus, it’s consumed along with the connection.

Configuration

• gitoxide.userAgent is read to obtain the application user agent for git servers and for HTTP servers as well.

impl<'remote, 'repo, T> Connection<'remote, 'repo, T>

where T: Transport,

pub fn prepare_fetch( self, progress: impl Progress, options: Options, ) -> Result<Prepare<'remote, 'repo, T>, Error>

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() 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.