freshlybakedca.ke
Git fork
1Packfile URIs
2=============
3
4This feature allows servers to serve part of their packfile response as URIs.
5This allows server designs that improve scalability in bandwidth and CPU usage
6(for example, by serving some data through a CDN), and (in the future) provides
7some measure of resumability to clients.
8
9This feature is available only in protocol version 2.
10
11Protocol
12--------
13
14The server advertises the `packfile-uris` capability.
15
16If the client then communicates which protocols (HTTPS, etc.) it supports with
17a `packfile-uris` argument, the server MAY send a `packfile-uris` section
18directly before the `packfile` section (right after `wanted-refs` if it is
19sent) containing URIs of any of the given protocols. The URIs point to
20packfiles that use only features that the client has declared that it supports
21(e.g. ofs-delta and thin-pack). See linkgit:gitprotocol-v2[5] for the documentation of
22this section.
23
24Clients should then download and index all the given URIs (in addition to
25downloading and indexing the packfile given in the `packfile` section of the
26response) before performing the connectivity check.
27
28Server design
29-------------
30
31The server can be trivially made compatible with the proposed protocol by
32having it advertise `packfile-uris`, tolerating the client sending
33`packfile-uris`, and never sending any `packfile-uris` section. But we should
34include some sort of non-trivial implementation in the Minimum Viable Product,
35at least so that we can test the client.
36
37This is the implementation: a feature, marked experimental, that allows the
38server to be configured by one or more `uploadpack.blobPackfileUri=
39<object-hash> <pack-hash> <uri>` entries. Whenever the list of objects to be
40sent is assembled, all such blobs are excluded, replaced with URIs. As noted
41in "Future work" below, the server can evolve in the future to support
42excluding other objects (or other implementations of servers could be made
43that support excluding other objects) without needing a protocol change, so
44clients should not expect that packfiles downloaded in this way only contain
45single blobs.
46
47Client design
48-------------
49
50The client has a config variable `fetch.uriprotocols` that determines which
51protocols the end user is willing to use. By default, this is empty.
52
53When the client downloads the given URIs, it should store them with "keep"
54files, just like it does with the packfile in the `packfile` section. These
55additional "keep" files can only be removed after the refs have been updated -
56just like the "keep" file for the packfile in the `packfile` section.
57
58The division of work (initial fetch + additional URIs) introduces convenient
59points for resumption of an interrupted clone - such resumption can be done
60after the Minimum Viable Product (see "Future work").
61
62Future work
63-----------
64
65The protocol design allows some evolution of the server and client without any
66need for protocol changes, so only a small-scoped design is included here to
67form the MVP. For example, the following can be done:
68
69 * On the server, more sophisticated means of excluding objects (e.g. by
70 specifying a commit to represent that commit and all objects that it
71 references).
72 * On the client, resumption of clone. If a clone is interrupted, information
73 could be recorded in the repository's config and a "clone-resume" command
74 can resume the clone in progress. (Resumption of subsequent fetches is more
75 difficult because that must deal with the user wanting to use the repository
76 even after the fetch was interrupted.)
77
78There are some possible features that will require a change in protocol:
79
80 * Additional HTTP headers (e.g. authentication)
81 * Byte range support
82 * Different file formats referenced by URIs (e.g. raw object)