{"thread":{"id":"34739","subject":"[PATCH] Document the HTTP transport protocols","startedAt":"2013-08-21T13:45:13Z","lastAt":"2013-08-22T11:27:20Z","messageCount":4,"participants":["Nguyễn Thái Ngọc Duy","Junio C Hamano","Jeff King","Duy Nguyen"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"225613","messageId":"1377092713-25434-1-git-send-email-pclouds@gmail.com","threadId":"34739","inReplyTo":null,"subject":"[PATCH] Document the HTTP transport protocols","fromName":"Nguyễn Thái Ngọc Duy","fromEmail":"pclouds@gmail.com","sentAt":"2013-08-21T13:45:13Z","receivedAt":"2013-08-21T13:45:13Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"From: \"Shawn O. Pearce\" <spearce@spearce.org>\n\nSigned-off-by: Shawn O. Pearce <spearce@spearce.org>\nRevised-by: Tay Ray Chuan <rctay89@gmail.com>\nSigned-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>\n---\n This is basically the version from Tay Ray Chuan [1] with one more\n proofreading round from me. My changes besides realignments are below.\n There are TODOs remain but I think the document is valuable as it is.\n\n On the topic, C Git's (maybe) violations on this spec are:\n \n  - The client does not strip trailing slashes from $GIT_URL before\n    sending to the server, as described in section \"URL Format\".\n \n  - The client does not check that HTTP status code is either 200 or\n    304 when receiving response in discovering references phase.\n \n  - The client verifies the first 5 bytes against pattern\n    \"^[0-9a-fA-F]{4}#\" instead of \"^[0-9a-f]{4}#\" as described in\n    section \"discovering references\".\n\n [1] https://raw.github.com/rctay/git/feature/http-doc/Documentation/technical/http-protocol.txt\n\n    diff --git b/home/pclouds/t/http-protocol.txt a/Documentation/technical/http-protocol.txt\n    index 0b1c96c..8812bf6 100644\n    --- b/home/pclouds/t/http-protocol.txt\n    +++ a/Documentation/technical/http-protocol.txt\n    @@ -315,7 +315,8 @@ Servers SHOULD support all capabilities defined here.\n     \n     Clients MUST send at least one 'want' command in the request body.\n     Clients MUST NOT reference an id in a 'want' command which did not\n    -appear in the response obtained through ref discovery.\n    +appear in the response obtained through ref discovery unless the\n    +server advertises capability \"allow-tip-sha1-in-want\".\n     \n       compute_request   =  want_list\n                            have_list\n    @@ -330,31 +331,9 @@ appear in the response obtained through ref discovery.\n     \n       have_list         =  *PKT-LINE(\"have\" SP id LF)\n     \n    -  command           =  create / delete / update\n    -  create            =  zero-id SP new_id SP name\n    -  delete            =  old_id SP zero-id SP name\n    -  update            =  old_id SP new_id SP name\n    -\n     TODO: Document this further.\n     TODO: Don't use uppercase for variable names below.\n     \n    -Capability include-tag\n    -~~~~~~~~~~~~~~~~~~~~~~\n    -\n    -When packing an object that an annotated tag points at, include the\n    -tag object too.  Clients can request this if they want to fetch\n    -tags, but don't know which tags they will need until after they\n    -receive the branch data.  By enabling include-tag an extra call\n    -to upload-pack can be avoided.\n    -\n    -Capability thin-pack\n    -~~~~~~~~~~~~~~~~~~~~\n    -\n    -When packing a deltified object the base is not included if the base\n    -is reachable from an object listed in the COMMON set by the client.\n    -This reduces the bandwidth required to transfer, but it does slightly\n    -increase processing time for the client to save the pack to disk.\n    -\n     The Negotiation Algorithm\n     ~~~~~~~~~~~~~~~~~~~~~~~~~\n     The computation to select the minimal pack proceeds as follows\n    @@ -520,4 +499,5 @@ References\n     \n     link:http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n     link:http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n    -\n    +link:technical/pack-protocol.txt\n    +link:technical/protocol-capabilities.txt\n\n Documentation/technical/http-protocol.txt (new) | 503 ++++++++++++++++++++++++\n 1 file changed, 503 insertions(+)\n create mode 100644 Documentation/technical/http-protocol.txt\n\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt\nnew file mode 100644\nindex 0000000..8812bf6\n--- /dev/null\n+++ b/Documentation/technical/http-protocol.txt\n@@ -0,0 +1,503 @@\n+HTTP transfer protocols\n+=======================\n+\n+Git supports two HTTP based transfer protocols.  A \"dumb\" protocol\n+which requires only a standard HTTP server on the server end of the\n+connection, and a \"smart\" protocol which requires a Git aware CGI\n+(or server module).  This document describes both protocols.\n+\n+As a design feature smart clients can automatically upgrade \"dumb\"\n+protocol URLs to smart URLs.  This permits all users to have the\n+same published URL, and the peers automatically select the most\n+efficient transport available to them.\n+\n+\n+URL Format\n+----------\n+\n+URLs for Git repositories accessed by HTTP use the standard HTTP\n+URL syntax documented by RFC 1738, so they are of the form:\n+\n+  http://<host>:<port>/<path>?<searchpart>\n+\n+Within this documentation the placeholder $GIT_URL will stand for\n+the http:// repository URL entered by the end-user.\n+\n+Servers SHOULD handle all requests to locations matching $GIT_URL, as\n+both the \"smart\" and \"dumb\" HTTP protocols used by Git operate\n+by appending additional path components onto the end of the user\n+supplied $GIT_URL string.\n+\n+An example of a dumb client requesting for a loose object:\n+\n+  $GIT_URL:     http://example.com:8080/git/repo.git\n+  URL request:  http://example.com:8080/git/repo.git/objects/d0/49f6c27a2244e12041955e262a404c7faba355\n+\n+An example of a smart request to a catch-all gateway:\n+\n+  $GIT_URL:     http://example.com/daemon.cgi?svc=git&q=\n+  URL request:  http://example.com/daemon.cgi?svc=git&q=/info/refs&service=git-receive-pack\n+\n+An example of a request to a submodule:\n+\n+  $GIT_URL:     http://example.com/git/repo.git/path/submodule.git\n+  URL request:  http://example.com/git/repo.git/path/submodule.git/info/refs\n+\n+Clients MUST strip a trailing '/', if present, from the user supplied\n+$GIT_URL string to prevent empty path tokens ('//') from appearing\n+in any URL sent to a server.  Compatible clients MUST expand\n+'$GIT_URL/info/refs' as 'foo/info/refs' and not 'foo//info/refs'.\n+\n+\n+Authentication\n+--------------\n+\n+Standard HTTP authentication is used if authentication is required\n+to access a repository, and MAY be configured and enforced by the\n+HTTP server software.\n+\n+Because Git repositories are accessed by standard path components\n+server administrators MAY use directory based permissions within\n+their HTTP server to control repository access.\n+\n+Clients SHOULD support Basic authentication as described by RFC 2616.\n+Servers SHOULD support Basic authentication by relying upon the\n+HTTP server placed in front of the Git server software.\n+\n+Servers SHOULD NOT require HTTP cookies for the purposes of\n+authentication or access control.\n+\n+Clients and servers MAY support other common forms of HTTP based\n+authentication, such as Digest authentication.\n+\n+\n+SSL\n+---\n+\n+Clients and servers SHOULD support SSL, particularly to protect\n+passwords when relying on Basic HTTP authentication.\n+\n+\n+Session State\n+-------------\n+\n+The Git over HTTP protocol (much like HTTP itself) is stateless\n+from the perspective of the HTTP server side.  All state MUST be\n+retained and managed by the client process.  This permits simple\n+round-robin load-balancing on the server side, without needing to\n+worry about state management.\n+\n+Clients MUST NOT require state management on the server side in\n+order to function correctly.\n+\n+Servers MUST NOT require HTTP cookies in order to function correctly.\n+Clients MAY store and forward HTTP cookies during request processing\n+as described by RFC 2616 (HTTP/1.1).  Servers SHOULD ignore any\n+cookies sent by a client.\n+\n+\n+General Request Processing\n+--------------------------\n+\n+Except where noted, all standard HTTP behavior SHOULD be assumed\n+by both client and server.  This includes (but is not necessarily\n+limited to):\n+\n+If there is no repository at $GIT_URL, or the resource pointed to by a\n+location matching $GIT_URL does not exist, the server MUST NOT respond\n+with '200 OK' response.  A server SHOULD respond with\n+'404 Not Found', '410 Gone', or any other suitable HTTP status code\n+which does not imply the resource exists as requested.\n+\n+If there is a repository at $GIT_URL, but access is not currently\n+permitted, the server MUST respond with the '403 Forbidden' HTTP\n+status code.\n+\n+Servers SHOULD support both HTTP 1.0 and HTTP 1.1.\n+Servers SHOULD support chunked encoding for both request and response\n+bodies.\n+\n+Clients SHOULD support both HTTP 1.0 and HTTP 1.1.\n+Clients SHOULD support chunked encoding for both request and response\n+bodies.\n+\n+Servers MAY return ETag and/or Last-Modified headers.\n+\n+Clients MAY revalidate cached entities by including If-Modified-Since\n+and/or If-None-Match request headers.\n+\n+Servers MAY return '304 Not Modified' if the relevant headers appear\n+in the request and the entity has not changed.  Clients MUST treat\n+'304 Not Modified' identical to '200 OK' by reusing the cached entity.\n+\n+Clients MAY reuse a cached entity without revalidation if the\n+Cache-Control and/or Expires header permits caching.  Clients and\n+servers MUST follow RFC 2616 for cache controls.\n+\n+\n+Discovering References\n+----------------------\n+\n+All HTTP clients MUST begin either a fetch or a push exchange by\n+discovering the references available on the remote repository.\n+\n+Dumb Clients\n+~~~~~~~~~~~~\n+\n+HTTP clients that only support the \"dumb\" protocol MUST discover\n+references by making a request for the special info/refs file of\n+the repository.\n+\n+Dumb HTTP clients MUST make a GET request to $GIT_URL/info/refs,\n+without any search/query parameters.\n+\n+   C: GET $GIT_URL/info/refs HTTP/1.0\n+\n+   S: 200 OK\n+   S:\n+   S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31\trefs/heads/maint\n+   S: d049f6c27a2244e12041955e262a404c7faba355\trefs/heads/master\n+   S: 2cb58b79488a98d2721cea644875a8dd0026b115\trefs/tags/v1.0\n+   S: a3c2e2402b99163d1d59756e5f207ae21cccba4c\trefs/tags/v1.0^{}\n+\n+The Content-Type of the returned info/refs entity SHOULD be\n+\"text/plain; charset=utf-8\", but MAY be any content type.\n+Clients MUST NOT attempt to validate the returned Content-Type.\n+Dumb servers MUST NOT return a return type starting with\n+\"application/x-git-\".\n+\n+Cache-Control headers MAY be returned to disable caching of the\n+returned entity.\n+\n+When examining the response clients SHOULD only examine the HTTP\n+status code.  Valid responses are '200 OK', or '304 Not Modified'.\n+\n+The returned content is a UNIX formatted text file describing\n+each ref and its known value.  The file SHOULD be sorted by name\n+according to the C locale ordering.  The file SHOULD NOT include\n+the default ref named 'HEAD'.\n+\n+  info_refs   =  *( ref_record )\n+  ref_record  =  any_ref / peeled_ref\n+\n+  any_ref     =  obj-id HTAB refname LF\n+  peeled_ref  =  obj-id HTAB refname LF\n+                 obj-id HTAB refname \"^{}\" LF\n+\n+Smart Clients\n+~~~~~~~~~~~~~\n+\n+HTTP clients that support the \"smart\" protocol (or both the\n+\"smart\" and \"dumb\" protocols) MUST discover references by making\n+a parameterized request for the info/refs file of the repository.\n+\n+The request MUST contain exactly one query parameter,\n+'service=$servicename', where $servicename MUST be the service\n+name the client wishes to contact to complete the operation.\n+The request MUST NOT contain additional query parameters.\n+\n+   C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0\n+\n+   dumb server reply:\n+   S: 200 OK\n+   S:\n+   S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31\trefs/heads/maint\n+   S: d049f6c27a2244e12041955e262a404c7faba355\trefs/heads/master\n+   S: 2cb58b79488a98d2721cea644875a8dd0026b115\trefs/tags/v1.0\n+   S: a3c2e2402b99163d1d59756e5f207ae21cccba4c\trefs/tags/v1.0^{}\n+\n+   smart server reply:\n+   S: 200 OK\n+   S: Content-Type: application/x-git-upload-pack-advertisement\n+   S: Cache-Control: no-cache\n+   S:\n+   S: 001e# service=git-upload-pack\\n\n+   S: 004895dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint\\0multi_ack\\n\n+   S: 0042d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master\\n\n+   S: 003c2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0\\n\n+   S: 003fa3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}\\n\n+\n+Dumb Server Response\n+^^^^^^^^^^^^^^^^^^^^\n+Dumb servers MUST respond with the dumb server reply format.\n+\n+See the prior section under dumb clients for a more detailed\n+description of the dumb server response.\n+\n+Smart Server Response\n+^^^^^^^^^^^^^^^^^^^^^\n+If the server does not recognize the requested service name, or the\n+requested service name has been disabled by the server administrator,\n+the server MUST respond with the '403 Forbidden' HTTP status code.\n+\n+Otherwise, smart servers MUST respond with the smart server reply\n+format for the requested service name.\n+\n+Cache-Control headers SHOULD be used to disable caching of the\n+returned entity.\n+\n+The Content-Type MUST be 'application/x-$servicename-advertisement'.\n+Clients SHOULD fall back to the dumb protocol if another content\n+type is returned.  When falling back to the dumb protocol clients\n+SHOULD NOT make an additional request to $GIT_URL/info/refs, but\n+instead SHOULD use the response already in hand.  Clients MUST NOT\n+continue if they do not support the dumb protocol.\n+\n+Clients MUST validate the status code is either '200 OK' or\n+'304 Not Modified'.\n+\n+Clients MUST validate the first five bytes of the response entity\n+matches the regex \"^[0-9a-f]{4}#\".  If this test fails, clients\n+MUST NOT continue.\n+\n+Clients MUST parse the entire response as a sequence of pkt-line\n+records.\n+\n+Clients MUST verify the first pkt-line is \"# service=$servicename\".\n+Servers MUST set $servicename to be the request parameter value.\n+Servers SHOULD include an LF at the end of this line.\n+Clients MUST ignore an LF at the end of the line.\n+\n+Servers MUST terminate the response with the magic \"0000\" end\n+pkt-line marker.\n+\n+The returned response is a pkt-line stream describing each ref and\n+its known value.  The stream SHOULD be sorted by name according to\n+the C locale ordering.  The stream SHOULD include the default ref\n+named 'HEAD' as the first ref.  The stream MUST include capability\n+declarations behind a NUL on the first ref.\n+\n+  smart_reply     =  PKT-LINE(\"# service=$servicename\" LF)\n+                     ref_list\n+                     \"0000\"\n+  ref_list        =  empty_list / non_empty_list\n+\n+  empty_list      =  PKT-LINE(zero-id SP \"capabilities^{}\" NUL cap-list LF)\n+\n+  non_empty_list  =  PKT-LINE(obj-id SP name NUL cap_list LF)\n+                     *ref_record\n+\n+  cap-list        =  capability *(SP capability)\n+  capability      =  1*(LC_ALPHA / DIGIT / \"-\" / \"_\")\n+  LC_ALPHA        =  %x61-7A\n+\n+  ref_record      =  any_ref / peeled_ref\n+  any_ref         =  PKT-LINE(obj-id SP name LF)\n+  peeled_ref      =  PKT-LINE(obj-id SP name LF)\n+                     PKT-LINE(obj-id SP name \"^{}\" LF\n+\n+Smart Service git-upload-pack\n+------------------------------\n+This service reads from the repository pointed to by $GIT_URL.\n+\n+Clients MUST first perform ref discovery with\n+'$GIT_URL/info/refs?service=git-upload-pack'.\n+\n+   C: POST $GIT_URL/git-upload-pack HTTP/1.0\n+   C: Content-Type: application/x-git-upload-pack-request\n+   C:\n+   C: 0032want 0a53e9ddeaddad63ad106860237bbf53411d11a7\\n\n+   C: 0032have 441b40d833fdfa93eb2908e52742248faf0ee993\\n\n+   C: 0000\n+\n+   S: 200 OK\n+   S: Content-Type: application/x-git-upload-pack-result\n+   S: Cache-Control: no-cache\n+   S:\n+   S: ....ACK %s, continue\n+   S: ....NAK\n+\n+Clients MUST NOT reuse or revalidate a cached reponse.\n+Servers MUST include sufficient Cache-Control headers\n+to prevent caching of the response.\n+\n+Servers SHOULD support all capabilities defined here.\n+\n+Clients MUST send at least one 'want' command in the request body.\n+Clients MUST NOT reference an id in a 'want' command which did not\n+appear in the response obtained through ref discovery unless the\n+server advertises capability \"allow-tip-sha1-in-want\".\n+\n+  compute_request   =  want_list\n+                       have_list\n+                       request_end\n+  request_end       =  \"0000\" / \"done\"\n+\n+  want_list         =  PKT-LINE(want NUL cap_list LF)\n+                       *(want_pkt)\n+  want_pkt          =  PKT-LINE(want LF)\n+  want              =  \"want\" SP id\n+  cap_list          =  *(SP capability) SP\n+\n+  have_list         =  *PKT-LINE(\"have\" SP id LF)\n+\n+TODO: Document this further.\n+TODO: Don't use uppercase for variable names below.\n+\n+The Negotiation Algorithm\n+~~~~~~~~~~~~~~~~~~~~~~~~~\n+The computation to select the minimal pack proceeds as follows\n+(c = client, s = server):\n+\n+ init step:\n+ (c) Use ref discovery to obtain the advertised refs.\n+ (c) Place any object seen into set ADVERTISED.\n+\n+ (c) Build an empty set, COMMON, to hold the objects that are later\n+     determined to be on both ends.\n+ (c) Build a set, WANT, of the objects from ADVERTISED the client\n+     wants to fetch, based on what it saw during ref discovery.\n+\n+ (c) Start a queue, C_PENDING, ordered by commit time (popping newest\n+     first).  Add all client refs.  When a commit is popped from\n+     the queue its parents SHOULD be automatically inserted back.\n+     Commits MUST only enter the queue once.\n+\n+ one compute step:\n+ (c) Send one $GIT_URL/git-upload-pack request:\n+\n+   C: 0032want <WANT #1>...............................\n+   C: 0032want <WANT #2>...............................\n+   ....\n+   C: 0032have <COMMON #1>.............................\n+   C: 0032have <COMMON #2>.............................\n+   ....\n+   C: 0032have <HAVE #1>...............................\n+   C: 0032have <HAVE #2>...............................\n+   ....\n+   C: 0000\n+\n+     The stream is organized into \"commands\", with each command\n+     appearing by itself in a pkt-line.  Within a command line\n+     the text leading up to the first space is the command name,\n+     and the remainder of the line to the first LF is the value.\n+     Command lines are terminated with an LF as the last byte of\n+     the pkt-line value.\n+\n+     Commands MUST appear in the following order, if they appear\n+     at all in the request stream:\n+\n+       * want\n+       * have\n+\n+     The stream is terminated by a pkt-line flush (\"0000\").\n+\n+     A single \"want\" or \"have\" command MUST have one hex formatted\n+     SHA-1 as its value.  Multiple SHA-1s MUST be sent by sending\n+     multiple commands.\n+\n+     The HAVE list is created by popping the first 32 commits\n+     from C_PENDING.  Less can be supplied if C_PENDING empties.\n+\n+     If the client has sent 256 HAVE commits and has not yet\n+     received one of those back from S_COMMON, or the client has\n+     emptied C_PENDING it SHOULD include a \"done\" command to let\n+     the server know it won't proceed:\n+\n+   C: 0009done\n+\n+  (s) Parse the git-upload-pack request:\n+\n+      Verify all objects in WANT are directly reachable from refs.\n+\n+      The server MAY walk backwards through history or through\n+      the reflog to permit slightly stale requests.\n+\n+      If no WANT objects are received, send an error:\n+\n+TODO: Define error if no want lines are requested.\n+\n+      If any WANT object is not reachable, send an error:\n+\n+TODO: Define error if an invalid want is requested.\n+\n+     Create an empty list, S_COMMON.\n+\n+     If 'have' was sent:\n+\n+     Loop through the objects in the order supplied by the client.\n+     For each object, if the server has the object reachable from\n+     a ref, add it to S_COMMON.  If a commit is added to S_COMMON,\n+     do not add any ancestors, even if they also appear in HAVE.\n+\n+  (s) Send the git-upload-pack response:\n+\n+     If the server has found a closed set of objects to pack or the\n+     request ends with \"done\", it replies with the pack.\n+\n+TODO: Document the pack based response\n+   S: PACK...\n+\n+     The returned stream is the side-band-64k protocol supported\n+     by the git-upload-pack service, and the pack is embedded into\n+     stream 1.  Progress messages from the server side MAY appear\n+     in stream 2.\n+\n+     Here a \"closed set of objects\" is defined to have at least\n+     one path from every WANT to at least one COMMON object.\n+\n+     If the server needs more information, it replies with a\n+     status continue response:\n+\n+TODO: Document the non-pack response\n+\n+  (c) Parse the upload-pack response:\n+\n+TODO: Document parsing response\n+\n+      Do another compute step.\n+\n+\n+Smart Service git-receive-pack\n+------------------------------\n+This service reads from the repository pointed to by $GIT_URL.\n+\n+Clients MUST first perform ref discovery with\n+'$GIT_URL/info/refs?service=git-receive-pack'.\n+\n+   C: POST $GIT_URL/git-receive-pack HTTP/1.0\n+   C: Content-Type: application/x-git-receive-pack-request\n+   C:\n+   C: ....0a53e9ddeaddad63ad106860237bbf53411d11a7 441b40d833fdfa93eb2908e52742248faf0ee993 refs/heads/maint\\0 report-status\n+   C: 0000\n+   C: PACK....\n+\n+   S: 200 OK\n+   S: Content-Type: application/x-git-receive-pack-result\n+   S: Cache-Control: no-cache\n+   S:\n+   S: ....\n+\n+Clients MUST NOT reuse or revalidate a cached reponse.\n+Servers MUST include sufficient Cache-Control headers\n+to prevent caching of the response.\n+\n+Servers SHOULD support all capabilities defined here.\n+\n+Clients MUST send at least one command in the request body.\n+Within the command portion of the request body clients SHOULD send\n+the id obtained through ref discovery as old_id.\n+\n+  update_request  =  command_list\n+                     \"PACK\" <binary data>\n+\n+  command_list    =  PKT-LINE(command NUL cap_list LF)\n+                     *(command_pkt)\n+  command_pkt     =  PKT-LINE(command LF)\n+  cap_list        =  *(SP capability) SP\n+\n+  command         =  create / delete / update\n+  create          =  zero-id SP new_id SP name\n+  delete          =  old_id SP zero-id SP name\n+  update          =  old_id SP new_id SP name\n+\n+TODO: Document this further.\n+\n+\n+References\n+----------\n+\n+link:http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n+link:http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n+link:technical/pack-protocol.txt\n+link:technical/protocol-capabilities.txt\n-- \n1.8.2.83.gc99314b\n"},{"id":"225624","messageId":"xmqqsiy2uble.fsf@gitster.dls.corp.google.com","threadId":"34739","inReplyTo":"1377092713-25434-1-git-send-email-pclouds@gmail.com","subject":"Re: [PATCH] Document the HTTP transport protocols","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-08-21T18:45:33Z","receivedAt":"2013-08-21T18:45:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Nguyễn Thái Ngọc Duy <pclouds@gmail.com> writes:\n\n>  This is basically the version from Tay Ray Chuan [1] with one more\n>  proofreading round from me. My changes besides realignments are below.\n>  There are TODOs remain but I think the document is valuable as it is.\n\nThanks.\n\n>  On the topic, C Git's (maybe) violations on this spec are:\n>  \n>   - The client does not strip trailing slashes from $GIT_URL before\n>     sending to the server, as described in section \"URL Format\".\n>  \n>   - The client does not check that HTTP status code is either 200 or\n>     304 when receiving response in discovering references phase.\n>\n>   - The client verifies the first 5 bytes against pattern\n>     \"^[0-9a-fA-F]{4}#\" instead of \"^[0-9a-f]{4}#\" as described in\n>     section \"discovering references\".\n\nPerhaps add these to \"small projects ideas\"?  The last one may want\nto be phrased a bit better, though.  I needed to read it twice to\nrealize that you are saying \"the client accepts hexadecimal using\nuppercase alphabets where it should not\".\n"},{"id":"225652","messageId":"20130821220021.GA32130@sigill.intra.peff.net","threadId":"34739","inReplyTo":"1377092713-25434-1-git-send-email-pclouds@gmail.com","subject":"Re: [PATCH] Document the HTTP transport protocols","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2013-08-21T22:00:21Z","receivedAt":"2013-08-21T22:00:21Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Aug 21, 2013 at 08:45:13PM +0700, Nguyen Thai Ngoc Duy wrote:\n\n>  On the topic, C Git's (maybe) violations on this spec are:\n>  \n>   - The client does not strip trailing slashes from $GIT_URL before\n>     sending to the server, as described in section \"URL Format\".\n\nYeah. We get the basic gist right by not adding an extra \"/\" if there is\nalready a trailing slash (so you do not have http://host/path//info/refs\").\nBut we do not go out of our way to remove multiple slashes that the user\nhands out (either at the end or in the middle of the URL). I doubt that\nit matters in practice.\n\n>   - The client does not check that HTTP status code is either 200 or\n>     304 when receiving response in discovering references phase.\n\nWe rely on curl's CURLOPT_FAILONERROR to handle errors. And curl handles\nredirects internally. So yes, we could get a \"204\" or something weird,\nbut it would almost certainly not pass the other checks (proper\ncontent-type, starting with pkt-line, etc). I doubt it's a problem in\npractice.\n\nWe also handle 401 these days, which is not in the document, but\nobviously makes sense to do (ditto for 407, but I cannot remember if we\nactually handle that or not; there were patches, but I think they may\nhave been dropped).\n\n>   - The client verifies the first 5 bytes against pattern\n>     \"^[0-9a-fA-F]{4}#\" instead of \"^[0-9a-f]{4}#\" as described in\n>     section \"discovering references\".\n\nI think this could be counted as \"be liberal in what you accept\",\nalthough I do not know offhand of any implementations that use\nuppercase. But if it is not true pkt-line we would figure it out pretty\nquickly anyway.\n\n> [...]\n\nI read through the rest and did not see anything inaccurate. Thanks for\nworking on this.\n\n-Peff\n"},{"id":"225676","messageId":"CACsJy8A4c3gFeX+q4hPjki8+mLjv_xo4tNbhyyCcmaUX7tYFLA@mail.gmail.com","threadId":"34739","inReplyTo":"20130821220021.GA32130@sigill.intra.peff.net","subject":"Re: [PATCH] Document the HTTP transport protocols","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2013-08-22T11:27:20Z","receivedAt":"2013-08-22T11:27:20Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Thu, Aug 22, 2013 at 5:00 AM, Jeff King <peff@peff.net> wrote:\n> On Wed, Aug 21, 2013 at 08:45:13PM +0700, Nguyen Thai Ngoc Duy wrote:\n>\n>>  On the topic, C Git's (maybe) violations on this spec are:\n>>\n>>   - The client does not strip trailing slashes from $GIT_URL before\n>>     sending to the server, as described in section \"URL Format\".\n>\n> Yeah. We get the basic gist right by not adding an extra \"/\" if there is\n> already a trailing slash (so you do not have http://host/path//info/refs\").\n> But we do not go out of our way to remove multiple slashes that the user\n> hands out (either at the end or in the middle of the URL). I doubt that\n> it matters in practice.\n\nIt may make writing rewrite/matching patterns in http server a tiny\nbit harder, but should not be a big deal. I agree with Junio this\ncould be something a new contributor can work on to get familiar with\n(scary, imo) transport/connect code.\n\nI agree with the rest of your comments that those \"violations\" do not\nmatter much (when I raised them I did not mean \"fix Git\", just\nchecking if I missed anything) and the document is ok as-is.\n-- \nDuy\n"}]}