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