Re: [PATCH] Documentation: document Extra Parameters

[Brandon Williams <bmwill@google.com>]

On 10/10, Jonathan Tan wrote:
> Document the server support for Extra Parameters, additional information
> that the client can send in its first message to the server during a
> Git client-server interaction.
> 
> Signed-off-by: Jonathan Tan <jonathantanmy@google.com>
> ---
> I noticed that Documentation/technical was not updated in this patch
> series. It probably should, and here is a suggestion on how to do it.
> 
> Also, I'm not sure what to call the extra sendable information. I'm open
> to suggestions for a better name than Extra Parameters.

Thanks for writing this up.

> ---
>  Documentation/technical/http-protocol.txt |  8 ++++++
>  Documentation/technical/pack-protocol.txt | 43 ++++++++++++++++++++++++++-----
>  2 files changed, 44 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt
> index 1c561bdd9..a0e45f288 100644
> --- a/Documentation/technical/http-protocol.txt
> +++ b/Documentation/technical/http-protocol.txt
> @@ -219,6 +219,10 @@ smart server reply:
>     S: 003c2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0\n
>     S: 003fa3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}\n
>  
> +The client may send Extra Parameters (see
> +Documentation/technical/pack-protocol.txt) as a colon-separated string
> +in the Git-Protocol HTTP header.
> +
>  Dumb Server Response
>  ^^^^^^^^^^^^^^^^^^^^
>  Dumb servers MUST respond with the dumb server reply format.
> @@ -269,7 +273,11 @@ the C locale ordering.  The stream SHOULD include the default ref
>  named `HEAD` as the first ref.  The stream MUST include capability
>  declarations behind a NUL on the first ref.
>  
> +The returned response contains "version 1" if "version=1" was sent as an
> +Extra Parameter.
> +
>    smart_reply     =  PKT-LINE("# service=$servicename" LF)
> +		     *1("version 1")
>  		     ref_list
>  		     "0000"
>    ref_list        =  empty_list / non_empty_list
> diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
> index ed1eae8b8..f9ebfb23e 100644
> --- a/Documentation/technical/pack-protocol.txt
> +++ b/Documentation/technical/pack-protocol.txt
> @@ -39,6 +39,19 @@ communicates with that invoked process over the SSH connection.
>  The file:// transport runs the 'upload-pack' or 'receive-pack'
>  process locally and communicates with it over a pipe.
>  
> +Extra Parameters
> +----------------
> +
> +The protocol provides a mechanism in which clients can send additional
> +information in its first message to the server. These are called "Extra
> +Parameters", and are supported by the Git, SSH, and HTTP protocols.
> +
> +Each Extra Parameter takes the form of `<key>=<value>` or `<key>`.
> +
> +Servers that receive any such Extra Parameters MUST ignore all
> +unrecognized keys. Currently, the only Extra Parameter recognized is
> +"version=1".
> +
>  Git Transport
>  -------------
>  
> @@ -46,18 +59,25 @@ The Git transport starts off by sending the command and repository
>  on the wire using the pkt-line format, followed by a NUL byte and a
>  hostname parameter, terminated by a NUL byte.
>  
> -   0032git-upload-pack /project.git\0host=myserver.com\0
> +   0033git-upload-pack /project.git\0host=myserver.com\0
> +
> +The transport may send Extra Parameters by adding an additional NUL
> +byte, and then adding one or more NUL-terminated strings:
> +
> +   003egit-upload-pack /project.git\0host=myserver.com\0\0version=1\0
>  
>  --
> -   git-proto-request = request-command SP pathname NUL [ host-parameter NUL ]
> +   git-proto-request = request-command SP pathname NUL
> +		       [ host-parameter NUL [ NUL extra-parameters ] ]

This should probably be "[ host-parameter NUL ] [ NUL extra-parameters ]"
because we don't want to require sending a host parameter in order to
send extra parameters.

>     request-command   = "git-upload-pack" / "git-receive-pack" /
>  		       "git-upload-archive"   ; case sensitive
>     pathname          = *( %x01-ff ) ; exclude NUL
>     host-parameter    = "host=" hostname [ ":" port ]
> +   extra-parameters  = 1*extra-parameter
> +   extra-parameter   = 1*( %x01-ff ) NUL
>  --
>  
> -Only host-parameter is allowed in the git-proto-request. Clients
> -MUST NOT attempt to send additional parameters. It is used for the
> +host-parameter is used for the
>  git-daemon name based virtual hosting.  See --interpolated-path
>  option to git daemon, with the %H/%CH format characters.
>  
> @@ -117,6 +137,12 @@ we execute it without the leading '/'.
>  		     v
>     ssh user@example.com "git-upload-pack '~alice/project.git'"
>  
> +Depending on the value of the `protocol.version` configuration variable,
> +Git may attempt to send Extra Parameters as a colon-separated string in
> +the GIT_PROTOCOL environment variable. This is done only if
> +the `ssh.variant` configuration variable indicates that the ssh command
> +supports passing environment variables as an argument.
> +
>  A few things to remember here:
>  
>  - The "command name" is spelled with dash (e.g. git-upload-pack), but
> @@ -137,11 +163,13 @@ Reference Discovery
>  -------------------
>  
>  When the client initially connects the server will immediately respond
> -with a listing of each reference it has (all branches and tags) along
> +with a version number (if "version=1" is sent as an Extra Parameter),
> +and a listing of each reference it has (all branches and tags) along
>  with the object name that each reference currently points to.
>  
> -   $ echo -e -n "0039git-upload-pack /schacon/gitbook.git\0host=example.com\0" |
> +   $ echo -e -n "0044git-upload-pack /schacon/gitbook.git\0host=example.com\0\0version=1\0" |
>        nc -v example.com 9418
> +   000aversion 1
>     00887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack
>  		side-band side-band-64k ofs-delta shallow no-progress include-tag
>     00441d3fcd5ced445d1abc402225c0b8a1299641f497 refs/heads/integration
> @@ -165,7 +193,8 @@ immediately after the ref itself, if presented. A conforming server
>  MUST peel the ref if it's an annotated tag.
>  
>  ----
> -  advertised-refs  =  (no-refs / list-of-refs)
> +  advertised-refs  =  *1("version 1")
> +		      (no-refs / list-of-refs)
>  		      *shallow
>  		      flush-pkt
>  
> -- 
> 2.14.2.920.gcf0c67979c-goog
> 

-- 
Brandon Williams