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