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