Re: [PATCH] Document smart http

From: Jeff King <peff@peff.net>
Date: Aug 20, 2013, 14:16 UTC
Message-ID: <20130820141630.GB32370@sigill.intra.peff.net>
In-Reply-To: <1376975288-17079-1-git-send-email-pclouds@gmail.com>

On Tue, Aug 20, 2013 at 12:08:08PM +0700, Nguyen Thai Ngoc Duy wrote:

> This may provide some clues for those who want to modify smart http
> code as smart http is pretty much undocumented. Smart http "document"
> so far is a few commit messages and the source code.

There was also this:

  http://article.gmane.org/gmane.comp.version-control.git/129734

which seems to have never gotten updated enough to be applied along with the code. But with some updates to make sure it matches the current behavior, it is probably a more comprehensive description.

But if you don't feel like spending more time on this on top of what you've already done, I think the patch I'm responding to is better than what we have now (i.e., nothing).

Show 34 quoted lines

> +Reference Discovery
> +-------------------
> +
> +The server end always sends the list of references in both push and
> +fetch cases. This ref list is retrieved by the client's sending HTTP
> +GET request to a smart http url ending with
> +"/info/refs?service=<service>" where <service> could be either
> +git-upload-pack or git-receive-pack for fetching or pushing
> +respectively. The output is in pkt-line format.
> +
> +----
> +  advertised-refs  =  service
> +		      flush-pkt
> +		      (no-refs / list-of-refs)
> +		      flush-pkt
> +
> +  service          =  PKT-LINE("# service=" service-name)
> +  service-name     =  ("git-upload-pack" / "git-receive-pack")
> +
> +  no-refs          =  PKT-LINE(zero-id SP "capabilities^{}"
> +		      NUL capability-list LF)
> +
> +  list-of-refs     =  first-ref *other-ref
> +  first-ref        =  PKT-LINE(obj-id SP refname
> +		      NUL capability-list LF)
> +
> +  other-ref        =  PKT-LINE(other-tip / other-peeled)
> +  other-tip        =  obj-id SP refname LF
> +  other-peeled     =  obj-id SP refname "^{}" LF
> +
> +  capability-list  =  capability *(SP capability)
> +  capability       =  1*(LC_ALPHA / DIGIT / "-" / "_")
> +  LC_ALPHA         =  %x61-7A
> +----

Most of this is a repeat of what is in the earlier sections. I don't think the protocol is changing much and these are not likely to get out of date with each other, but I wonder if it is easier on the reader to simply describe the output in terms of what is added on top of the regular ref advertisement (i.e., the service line). Something like:

  stateless-advertised-refs =  service
                               advertised-refs

  service                   =  PKT-LINE("# service=" service-name)
  service-name              =  ("git-upload-pack" / "git-receive-pack")

where advertised-refs is defined in the earlier BNF. You may also want to note:

  Servers may respond to a smart request with a regular `advertised-refs`
  response rather than a `stateless-advertised-refs` response. In this
  case, the client MUST assume that the server does not understand smart
  HTTP and either abort or proceed with the non-smart protocol.

-Peff