ContextQMD
Back to Vfsforgit

The GVFS Protocol (v1)

Protocol.md

latest9.4 KB
Original Source

The GVFS Protocol (v1)

The GVFS network protocol consists of four operations on three endpoints. In summary:

  • GET /gvfs/objects/{objectId}
    • Provides a single object in loose-object format
  • POST /gvfs/objects
    • Provides one or more objects in packfile or streaming loose object format
  • GET /gvfs/prefetch[?lastPackTimestamp={secondsSinceEpoch}]
    • Provides one or more packfiles of non-blobs and optionally packfile indexes in a streaming format
  • POST /gvfs/sizes
    • Provides the uncompressed, undeltified size of one or more objects
  • GET /gvfs/config
    • Provides server-set client configuration options

GET /gvfs/objects/{objectId}

Will return a single object in compressed loose object format, which can be directly written to .git/xx/yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy if desired. The request/response looks similar to the "Dumb Protocol" as described here.

POST /gvfs/objects

Will return multiple objects, possibly more than the client requested based on request parameters.

The request consists of a JSON body with the following format:

{
    "objectIds" : [ {JSON array of SHA-1 object IDs, as strings} ],
    "commitDepth" : {positive integer}
}

For example,

{
    "objectIds" : [
        "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
    ],
    "commitDepth" : 1
}

Accept: application/x-git-packfile (the default)

If

  • An Accept header of application/x-git-packfile is specified, or
  • No Accept header is specified

then a git packfile, indexable via index-pack, will be returned to the client.

If objectIds includes a commit, then all trees recursively referenced by that commit are also returned. If any other object type is requested (tree, blob, or tag), then only that object will be returned.

commitDepth - if the requested object is a commit, all parents up to n levels deep will be returned, along with all their trees as previously described. Does not include any blobs.

Accept: application/x-gvfs-loose-objects

NOTE: This format is currently only supposed by the cache server, not by VSTS.

To enable scenarios where multiple objects are required, but less overhead would be incurred by using pre-existing loose objects (e.g. on a caching proxy), an alternative, packfile-like response format that contains loose objects is also supported.

To receive objects in this format, the client MUST supply an Accept header of application/x-gvfs-loose-objects to the POST /gvfs/objects endpoint. Otherwise, the response format will be application/x-git-packfile.

This format will NOT perform any commit to tree expansion, and will return an error if a commitDepth greater than 1 is supplied. Said another way, this Accept/return type has no concept of "implicitly-requested" objects.

Version 1

  • Integers are signed and little-endian, unless otherwise specified
  • Byte offset 0 is the first byte in the file
  • Index offset 0 is the first byte in the first element of an array
  • num_objects represents the variable number of objects in the file/response
Count            Size (bytes)    Chunk Description

HEADER
                +-------------------------------------------------------------------------------+
1               |          5 | UTF-8 encoded 'GVFS '                                            |
                |          1 | Unsigned byte version number. Currently, 1.                      |
                +-------------------------------------------------------------------------------+

OBJECT CONTENT
                +-------------------------------------------------------------------------------+
num_objects     |         20 | SHA-1 ID of the object.                                          |
                |          8 | Signed-long length of the object.                                |
                |   variable | Compressed, raw loose object content.                            |
                +-------------------------------------------------------------------------------+

TRAILER
                +-------------------------------------------------------------------------------+
1               |         20 | Zero bytes                                                       |
                +-------------------------------------------------------------------------------+

GET /gvfs/prefetch[?lastPackTimestamp={secondsSinceEpoch}]

To enable the reuse of already-existing packfiles and indexes, a custom format for transmitting these files is supported. The prefetch endpoint will return one or more packfiles of non-blob objects.

If the optional lastPackTimestamp query parameter is supplied, only packs created by the server after the specific Unix epoch time (approximately, ±10 minutes or so) will be returned. Generally, these packs will contain only objects introduced to the repository after that UTC-based timestamp, but will not contain all objects introduced after that timestamp.

A media-type of application/x-gvfs-timestamped-packfiles-indexes will be returned from this endpoint.

Response format

  • Integers are signed and little-endian, unless otherwise specified
  • Byte offset 0 is the first byte in the file
  • Index offset 0 is the first byte in the first element of an array
  • num_packs represents the variable number of packs in the file/response

Version 1

Count            Size (bytes)    Chunk Description

HEADER
                +-------------------------------------------------------------------------------+
1               |          5 | UTF-8 encoded 'GPRE '                                            |
                |          1 | Unsigned byte version number. Currently, 1.                      |
                +-------------------------------------------------------------------------------+

CONTENT

                +-------------------------------------------------------------------------------+
1               |          2 | Unsigned short number of packs. `num_packs`.                     |
                +-------------------------------------------------------------------------------+

                +-------------------------------------------------------------------------------+
num_packs       |          8 | Signed-long pack timestamp in seconds since UTC epoch.           |
                |          8 | Signed-long length of the pack.                                  |
                |          8 | Signed-long length of the pack index. -1 indicates no index.     |
                |   variable | Pack contents.                                                   |
                |   variable | Pack index contents.                                             |
                +-------------------------------------------------------------------------------+

Packs MUST be sent in increasing timestamp order. In the case of a failed connection, this allows the client to keep the packs it received successfully and "resume" by sending the highest completed timestamp.

POST /gvfs/sizes

Will return the uncompressed, undeltified length of the requested objects in JSON format.

The request consists of a JSON body with the following format:

[ {JSON array of SHA-1 object IDs, as strings} ]

For example, a request of:

[
    "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
]

will result in a a response like:

[
    {
        "Id" : "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "Size" : 123
    },
    {
        "Id" : "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
        "Size" : 456
    }
]

GET /gvfs/config

This optional endpoint will return all server-set GVFS client configuration options. It currently provides:

  • A set of allowed GVFS client version ranges, in order to block older clients from running in certain scenarios. For example, a data corruption bug may be found and encouraging clients to avoid that version is desirable.
  • A list of available cache servers, each describing their url and default-ness with a friendly name that users can use to inform which cache server to use. Note that the names "None" and "User Defined" are reserved by GVFS. Any caches with these names may cause undefined behavior in the GVFS client.

An example response is provided below. Note that the null "Max" value is only allowed for the last (or greatest) range, since it logically excludes greater version numbers from having an effect.

{
	"AllowedGvfsClientVersions": [{
		"Max": {
			"Major": 0,
			"Minor": 4,
			"Build": 0,
			"Revision": 0
		},
		"Min": {
			"Major": 0,
			"Minor": 2,
			"Build": 0,
			"Revision": 0
		}
	}, {
		"Max": {
			"Major": 0,
			"Minor": 5,
			"Build": 0,
			"Revision": 0
		},
		"Min": {
			"Major": 0,
			"Minor": 4,
			"Build": 17009,
			"Revision": 1
		}
	}, {
		"Max": null,
		"Min": {
			"Major": 0,
			"Minor": 5,
			"Build": 16326,
			"Revision": 1
		}
	}],
	"CacheServers": [{
		"Url": "https://redmond-cache-machine/repo-id",
		"Name": "Redmond",
		"GlobalDefault": true
	}, {
		"Url": "https://dublin-cache-machine/repo-id",
		"Name": "Dublin",
		"GlobalDefault": false
	}]
}