include/git2/sys/transport.h

   1 /*
   2  * Copyright (C) the libgit2 contributors. All rights reserved.
   3  *
   4  * This file is part of libgit2, distributed under the GNU GPL v2 with
   5  * a Linking Exception. For full terms see the included COPYING file.
   6  */
   7
   8 #ifndef INCLUDE_sys_git_transport_h
   9 #define INCLUDE_sys_git_transport_h
  10
  11 #include "git2/net.h"
  12 #include "git2/types.h"
  13
  14 /**
  15  * @file git2/sys/transport.h
  16  * @brief Git custom transport registration interfaces and functions
  17  * @defgroup git_transport Git custom transport registration
  18  * @ingroup Git
  19  * @{
  20  */
  21
  22 GIT_BEGIN_DECL
  23
  24 typedef enum {
  25         GIT_TRANSPORTFLAGS_NONE = 0,
  26         /* If the connection is secured with SSL/TLS, the authenticity
  27          * of the server certificate should not be verified. */
  28         GIT_TRANSPORTFLAGS_NO_CHECK_CERT = 1
  29 } git_transport_flags_t;
  30
  31 typedef struct git_transport git_transport;
  32
  33 struct git_transport {
  34         unsigned int version;
  35         /* Set progress and error callbacks */
  36         int (*set_callbacks)(
  37                 git_transport *transport,
  38                 git_transport_message_cb progress_cb,
  39                 git_transport_message_cb error_cb,
  40                 git_transport_certificate_check_cb certificate_check_cb,
  41                 void *payload);
  42
  43         /* Connect the transport to the remote repository, using the given
  44          * direction. */
  45         int (*connect)(
  46                 git_transport *transport,
  47                 const char *url,
  48                 git_cred_acquire_cb cred_acquire_cb,
  49                 void *cred_acquire_payload,
  50                 int direction,
  51                 int flags);
  52
  53         /* This function may be called after a successful call to
  54          * connect(). The array returned is owned by the transport and
  55          * is guranteed until the next call of a transport function. */
  56         int (*ls)(
  57                 const git_remote_head ***out,
  58                 size_t *size,
  59                 git_transport *transport);
  60
  61         /* Executes the push whose context is in the git_push object. */
  62         int (*push)(git_transport *transport, git_push *push);
  63
  64         /* This function may be called after a successful call to connect(), when
  65          * the direction is FETCH. The function performs a negotiation to calculate
  66          * the wants list for the fetch. */
  67         int (*negotiate_fetch)(
  68                 git_transport *transport,
  69                 git_repository *repo,
  70                 const git_remote_head * const *refs,
  71                 size_t count);
  72
  73         /* This function may be called after a successful call to negotiate_fetch(),
  74          * when the direction is FETCH. This function retrieves the pack file for
  75          * the fetch from the remote end. */
  76         int (*download_pack)(
  77                 git_transport *transport,
  78                 git_repository *repo,
  79                 git_transfer_progress *stats,
  80                 git_transfer_progress_cb progress_cb,
  81                 void *progress_payload);
  82
  83         /* Checks to see if the transport is connected */
  84         int (*is_connected)(git_transport *transport);
  85
  86         /* Reads the flags value previously passed into connect() */
  87         int (*read_flags)(git_transport *transport, int *flags);
  88
  89         /* Cancels any outstanding transport operation */
  90         void (*cancel)(git_transport *transport);
  91
  92         /* This function is the reverse of connect() -- it terminates the
  93          * connection to the remote end. */
  94         int (*close)(git_transport *transport);
  95
  96         /* Frees/destructs the git_transport object. */
  97         void (*free)(git_transport *transport);
  98 };
  99
 100 #define GIT_TRANSPORT_VERSION 1
 101 #define GIT_TRANSPORT_INIT {GIT_TRANSPORT_VERSION}
 102
 103 /**
 104  * Initializes a `git_transport` with default values. Equivalent to
 105  * creating an instance with GIT_TRANSPORT_INIT.
 106  *
 107  * @param opts the `git_transport` struct to initialize
 108  * @param version Version of struct; pass `GIT_TRANSPORT_VERSION`
 109  * @return Zero on success; -1 on failure.
 110  */
 111 GIT_EXTERN(int) git_transport_init(
 112         git_transport *opts,
 113         unsigned int version);
 114
 115 /**
 116  * Function to use to create a transport from a URL. The transport database
 117  * is scanned to find a transport that implements the scheme of the URI (i.e.
 118  * git:// or http://) and a transport object is returned to the caller.
 119  *
 120  * @param out The newly created transport (out)
 121  * @param owner The git_remote which will own this transport
 122  * @param url The URL to connect to
 123  * @return 0 or an error code
 124  */
 125 GIT_EXTERN(int) git_transport_new(git_transport **out, git_remote *owner, const char *url);
 126
 127 /**
 128  * Create an ssh transport with custom git command paths
 129  *
 130  * This is a factory function suitable for setting as the transport
 131  * callback in a remote (or for a clone in the options).
 132  *
 133  * The payload argument must be a strarray pointer with the paths for
 134  * the `git-upload-pack` and `git-receive-pack` at index 0 and 1.
 135  *
 136  * @param out the resulting transport
 137  * @param owner the owning remote
 138  * @param payload a strarray with the paths
 139  * @return 0 or an error code
 140  */
 141 GIT_EXTERN(int) git_transport_ssh_with_paths(git_transport **out, git_remote *owner, void *payload);
 142
 143 /* Signature of a function which creates a transport */
 144 typedef int (*git_transport_cb)(git_transport **out, git_remote *owner, void *param);
 145
 146 /**
 147  * Add a custom transport definition, to be used in addition to the built-in
 148  * set of transports that come with libgit2.
 149  *
 150  * The caller is responsible for synchronizing calls to git_transport_register
 151  * and git_transport_unregister with other calls to the library that
 152  * instantiate transports.
 153  *
 154  * @param prefix The scheme (ending in "://") to match, i.e. "git://"
 155  * @param cb The callback used to create an instance of the transport
 156  * @param param A fixed parameter to pass to cb at creation time
 157  * @return 0 or an error code
 158  */
 159 GIT_EXTERN(int) git_transport_register(
 160         const char *prefix,
 161         git_transport_cb cb,
 162         void *param);
 163
 164 /**
 165  *
 166  * Unregister a custom transport definition which was previously registered
 167  * with git_transport_register.
 168  *
 169  * @param prefix From the previous call to git_transport_register
 170  * @return 0 or an error code
 171  */
 172 GIT_EXTERN(int) git_transport_unregister(
 173         const char *prefix);
 174
 175 /* Transports which come with libgit2 (match git_transport_cb). The expected
 176  * value for "param" is listed in-line below. */
 177
 178 /**
 179  * Create an instance of the dummy transport.
 180  *
 181  * @param out The newly created transport (out)
 182  * @param owner The git_remote which will own this transport
 183  * @param payload You must pass NULL for this parameter.
 184  * @return 0 or an error code
 185  */
 186 GIT_EXTERN(int) git_transport_dummy(
 187         git_transport **out,
 188         git_remote *owner,
 189         /* NULL */ void *payload);
 190
 191 /**
 192  * Create an instance of the local transport.
 193  *
 194  * @param out The newly created transport (out)
 195  * @param owner The git_remote which will own this transport
 196  * @param payload You must pass NULL for this parameter.
 197  * @return 0 or an error code
 198  */
 199 GIT_EXTERN(int) git_transport_local(
 200         git_transport **out,
 201         git_remote *owner,
 202         /* NULL */ void *payload);
 203
 204 /**
 205  * Create an instance of the smart transport.
 206  *
 207  * @param out The newly created transport (out)
 208  * @param owner The git_remote which will own this transport
 209  * @param payload A pointer to a git_smart_subtransport_definition
 210  * @return 0 or an error code
 211  */
 212 GIT_EXTERN(int) git_transport_smart(
 213         git_transport **out,
 214         git_remote *owner,
 215         /* (git_smart_subtransport_definition *) */ void *payload);
 216
 217 /*
 218  *** End of base transport interface ***
 219  *** Begin interface for subtransports for the smart transport ***
 220  */
 221
 222 /* The smart transport knows how to speak the git protocol, but it has no
 223  * knowledge of how to establish a connection between it and another endpoint,
 224  * or how to move data back and forth. For this, a subtransport interface is
 225  * declared, and the smart transport delegates this work to the subtransports.
 226  * Three subtransports are implemented: git, http, and winhttp. (The http and
 227  * winhttp transports each implement both http and https.) */
 228
 229 /* Subtransports can either be RPC = 0 (persistent connection) or RPC = 1
 230  * (request/response). The smart transport handles the differences in its own
 231  * logic. The git subtransport is RPC = 0, while http and winhttp are both
 232  * RPC = 1. */
 233
 234 /* Actions that the smart transport can ask
 235  * a subtransport to perform */
 236 typedef enum {
 237         GIT_SERVICE_UPLOADPACK_LS = 1,
 238         GIT_SERVICE_UPLOADPACK = 2,
 239         GIT_SERVICE_RECEIVEPACK_LS = 3,
 240         GIT_SERVICE_RECEIVEPACK = 4,
 241 } git_smart_service_t;
 242
 243 typedef struct git_smart_subtransport git_smart_subtransport;
 244 typedef struct git_smart_subtransport_stream git_smart_subtransport_stream;
 245
 246 /* A stream used by the smart transport to read and write data
 247  * from a subtransport */
 248 struct git_smart_subtransport_stream {
 249         /* The owning subtransport */
 250         git_smart_subtransport *subtransport;
 251
 252         int (*read)(
 253                 git_smart_subtransport_stream *stream,
 254                 char *buffer,
 255                 size_t buf_size,
 256                 size_t *bytes_read);
 257
 258         int (*write)(
 259                 git_smart_subtransport_stream *stream,
 260                 const char *buffer,
 261                 size_t len);
 262
 263         void (*free)(
 264                 git_smart_subtransport_stream *stream);
 265 };
 266
 267 /* An implementation of a subtransport which carries data for the
 268  * smart transport */
 269 struct git_smart_subtransport {
 270         int (* action)(
 271                         git_smart_subtransport_stream **out,
 272                         git_smart_subtransport *transport,
 273                         const char *url,
 274                         git_smart_service_t action);
 275
 276         /* Subtransports are guaranteed a call to close() between
 277          * calls to action(), except for the following two "natural" progressions
 278          * of actions against a constant URL.
 279          *
 280          * 1. UPLOADPACK_LS -> UPLOADPACK
 281          * 2. RECEIVEPACK_LS -> RECEIVEPACK */
 282         int (*close)(git_smart_subtransport *transport);
 283
 284         void (*free)(git_smart_subtransport *transport);
 285 };
 286
 287 /* A function which creates a new subtransport for the smart transport */
 288 typedef int (*git_smart_subtransport_cb)(
 289         git_smart_subtransport **out,
 290         git_transport* owner);
 291
 292 typedef struct git_smart_subtransport_definition {
 293         /* The function to use to create the git_smart_subtransport */
 294         git_smart_subtransport_cb callback;
 295
 296         /* True if the protocol is stateless; false otherwise. For example,
 297          * http:// is stateless, but git:// is not. */
 298         unsigned rpc;
 299 } git_smart_subtransport_definition;
 300
 301 /* Smart transport subtransports that come with libgit2 */
 302
 303 /**
 304  * Create an instance of the http subtransport. This subtransport
 305  * also supports https. On Win32, this subtransport may be implemented
 306  * using the WinHTTP library.
 307  *
 308  * @param out The newly created subtransport
 309  * @param owner The smart transport to own this subtransport
 310  * @return 0 or an error code
 311  */
 312 GIT_EXTERN(int) git_smart_subtransport_http(
 313         git_smart_subtransport **out,
 314         git_transport* owner);
 315
 316 /**
 317  * Create an instance of the git subtransport.
 318  *
 319  * @param out The newly created subtransport
 320  * @param owner The smart transport to own this subtransport
 321  * @return 0 or an error code
 322  */
 323 GIT_EXTERN(int) git_smart_subtransport_git(
 324         git_smart_subtransport **out,
 325         git_transport* owner);
 326
 327 /**
 328  * Create an instance of the ssh subtransport.
 329  *
 330  * @param out The newly created subtransport
 331  * @param owner The smart transport to own this subtransport
 332  * @return 0 or an error code
 333  */
 334 GIT_EXTERN(int) git_smart_subtransport_ssh(
 335         git_smart_subtransport **out,
 336         git_transport* owner);
 337
 338 /**
 339  * Sets a custom transport factory for the remote. The caller can use this
 340  * function to override the transport used for this remote when performing
 341  * network operations.
 342  *
 343  * @param remote the remote to configure
 344  * @param transport_cb the function to use to create a transport
 345  * @param payload opaque parameter passed to transport_cb
 346  * @return 0 or an error code
 347  */
 348 GIT_EXTERN(int) git_remote_set_transport(
 349         git_remote *remote,
 350         git_transport_cb transport_cb,
 351         void *payload);
 352
 353 /** @} */
 354 GIT_END_DECL
 355 #endif