-
Notifications
You must be signed in to change notification settings - Fork 63
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Re-insert some important instances of GVFS
Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
- Loading branch information
1 parent
ff040c6
commit 9f402b5
Showing
17 changed files
with
33 additions
and
269 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,237 +1 @@ | ||
| # The Scalar Protocol (v1) | ||
|
|
||
| The Scalar network protocol consists of four operations on three endpoints. In summary: | ||
| * `GET /scalar/objects/{objectId}` | ||
| * Provides a single object in loose-object format | ||
| * `POST /scalar/objects` | ||
| * Provides one or more objects in packfile or streaming loose object format | ||
| * `GET /scalar/prefetch[?lastPackTimestamp={secondsSinceEpoch}]` | ||
| * Provides one or more packfiles of non-blobs and optionally packfile indexes in a streaming format | ||
| * `POST /scalar/sizes` | ||
| * Provides the uncompressed, undeltified size of one or more objects | ||
| * `GET /scalar/config` | ||
| * Provides server-set client configuration options | ||
|
|
||
| # `GET /scalar/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](https://git-scm.com/book/en/v2/Git-Internals-Transfer-Protocols). | ||
|
|
||
| # `POST /scalar/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 `tree`s 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 `blob`s. | ||
|
|
||
| ## `Accept: application/x-scalar-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-scalar-loose-objects` | ||
| to the `POST /scalar/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 'Scalar ' | | ||
| | 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 /scalar/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-scalar-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 /scalar/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 /scalar/config` | ||
| This optional endpoint will return all server-set Scalar client configuration options. It currently | ||
| provides: | ||
|
|
||
| * A set of allowed Scalar 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 Scalar. Any caches with these names may cause undefined behavior in the Scalar 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 | ||
| }] | ||
| } | ||
| ``` | ||
| See Protocol.md in microsoft/vfsforgit. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.