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