Re: [PATCH 1/9] protocol v2: add server-side "bundle-uri" skeleton

> +
> +PROTOCOL for bundle-uri
> +^^^^^^^^^^^^^^^^^^^^^^^
> +
> +A `bundle-uri` request takes no arguments, and as noted above does not
> +currently advertise a capability value. Both may be added in the
> +future.
> +
> +When the client issues a `command=bundle-uri` the response is a list of

> +
> +bundle-uri CLIENT AND SERVER EXPECTATIONS
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +URI CONTENTS::
> +The advertised URIs MUST be in one of two possible formats.
> ++
> +The first possible format is a bundle file that `git bundle verify`

> ++
> +The second possible format is a plaintext file that `git config --list`
> +would accept (with the `--file` option). The key-value pairs in this list
> +are in the `bundle.*` namespace (see linkgit:git-config[1]).
> +
> +bundle-uri CLIENT ERROR RECOVERY::
> +A client MUST above all gracefully degrade on errors, whether that
> +error is because of bad missing/data in the bundle URI(s), because
> +that client is too dumb to e.g. understand and fully parse out bundle
> +headers and their prerequisite relationships, or something else.
> ++
> +Server operators should feel confident in turning on "bundle-uri" and
> +not worry if e.g. their CDN goes down that clones or fetches will run
> +into hard failures. Even if the server bundle bundle(s) are
> +incomplete, or bad in some way the client should still end up with a
> +functioning repository, just as if it had chosen not to use this
> +protocol extension.
> ++
> +All subsequent discussion on client and server interaction MUST keep
> +this in mind.
> +
> +bundle-uri SERVER TO CLIENT::
> +The ordering of the returned bundle uris is not significant. Clients
> +MUST parse their headers to discover their contained OIDS and
> +prerequisites. A client MUST consider the content of the bundle(s)
> +themselves and their header as the ultimate source of truth.
> ++
> +A server MAY even return bundle(s) that don't have any direct
> +relationship to the repository being cloned (either through accident,
> +or intentional "clever" configuration), and expect a client to sort
> +out what data they'd like from the bundle(s), if any.
> +
> +bundle-uri CLIENT TO SERVER::
> +The client SHOULD provide reference tips found in the bundle header(s)
> +as 'have' lines in any subsequent `fetch` request. A client MAY also
> +ignore the bundle(s) entirely if doing so is deemed worse for some
> +reason, e.g. if the bundles can't be downloaded, it doesn't like the
> +tips it finds etc.
> +
> +WHEN ADVERTISED BUNDLE(S) REQUIRE NO FURTHER NEGOTIATION::
> +If after issuing `bundle-uri` and `ls-refs`, and getting the header(s)
> +of the bundle(s) the client finds that the ref tips it wants can be
> +retrieved entirety from advertised bundle(s), it MAY disconnect. The

> +results of such a 'clone' or 'fetch' should be indistinguishable from
> +the state attained without using bundle-uri.
> +
> +EARLY CLIENT DISCONNECTIONS AND ERROR RECOVERY::
> +A client MAY perform an early disconnect while still downloading the
> +bundle(s) (having streamed and parsed their headers). In such a case
> +the client MUST gracefully recover from any errors related to
> +finishing the download and validation of the bundle(s).
> ++
> +I.e. a client might need to re-connect and issue a 'fetch' command,
> +and possibly fall back to not making use of 'bundle-uri' at all.
> ++
> +This "MAY" behavior is specified as such (and not a "SHOULD") on the
> +assumption that a server advertising bundle uris is more likely than
> +not to be serving up a relatively large repository, and to be pointing
> +to URIs that have a good chance of being in working order. A client
> +MAY e.g. look at the payload size of the bundles as a heuristic to see
> +if an early disconnect is worth it, should falling back on a full
> +"fetch" dialog be necessary.
> +
> +WHEN ADVERTISED BUNDLE(S) REQUIRE FURTHER NEGOTIATION::
> +A client SHOULD commence a negotiation of a PACK from the server via
> +the "fetch" command using the OID tips found in advertised bundles,
> +even if's still in the process of downloading those bundle(s).
> ++
> +This allows for aggressive early disconnects from any interactive
> +server dialog. The client blindly trusts that the advertised OID tips
> +are relevant, and issues them as 'have' lines, it then requests any
> +tips it would like (usually from the "ls-refs" advertisement) via
> +'want' lines. The server will then compute a (hopefully small) PACK
> +with the expected difference between the tips from the bundle(s) and
> +the data requested.
> ++
> +The only connection the client then needs to keep active is to the
> +concurrently downloading static bundle(s), when those and the
> +incremental PACK are retrieved they should be inflated and
> +validated. Any errors at this point should be gracefully recovered
> +from, see above.
> +
> +bundle-uri PROTOCOL FEATURES
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +As noted above the `<key>=<value>` definitions are documented by the
> +`bundle.*` config namespace.

> +
> +In particular, the `bundle.version` key specifies an integer value. The
> +only accepted value at the moment is `1`, but if the client sees an
> +unexpected value here then the client MUST ignore the bundle list.
> +
> +As long as `bundle.version` is understood, all other unknown keys MAY be
> +ignored by the client. The server will guarantee compatibility with older
> +clients, though newer clients may be better able to use the extra keys to
> +minimize downloads.
> +
> +Any backwards-incompatible addition of pre-URI key-value will be
> +guarded by a new `bundle.version` value or values in 'bundle-uri'
> +capability advertisement itself, and/or by new future `bundle-uri`
> +request arguments.
> +
> +Some example key-value pairs that are not currently implemented but could
> +be implemented in the future include:
> +
> + * Add a "hash=<val>" or "size=<bytes>" advertise the expected hash or
> +   size of the bundle file.
> +
> + * Advertise that one or more bundle files are the same (to e.g. have
> +   clients round-robin or otherwise choose one of N possible files).
> +
> + * A "oid=<OID>" shortcut and "prerequisite=<OID>" shortcut. For
> +   expressing the common case of a bundle with one tip and no
> +   prerequisites, or one tip and one prerequisite.
> ++
> +This would allow for optimizing the common case of servers who'd like
> +to provide one "big bundle" containing only their "main" branch,
> +and/or incremental updates thereof.
> ++
> +A client receiving such a a response MAY assume that they can skip
> +retrieving the header from a bundle at the indicated URI, and thus
> +save themselves and the server(s) the request(s) needed to inspect the
> +headers of that bundle or bundles.