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