This document describes the "batch stat" API end-point, for checking
the size/existence of multiple blobs when the client and/or server do
not support SPDY or HTTP/2.0.  See blob-upload-protocol.txt for more
background.

Notably: the HTTP method may be GET or POST.  GET is more correct but
be aware that HTTP servers and proxies start to suck around the 2k and
4k URL lengths.  If you're stat'ing more than ~37 blobs, using POST
would be safest.

The HTTP request path is $blobRoot/camli/stat.  See
blob-upload-protocol.txt and discovery.txt for background.

In either case, the request form values: (either in the URL for GET or
application/x-www-form-urlencoded body for POST)

   camliversion    required   Version of camlistore and/or stat protocol;
                              reserved for future use.  Must be "1" for now.

   blob<n>         optional/  Must start at 1 and go up, no gaps allowed, not
                   repeated   zero-padded, etc.  Value is a blobref, e.g
                              "sha1-9b03f7aca1ac60d40b5e570c34f79a3e07c918e8"
                              There's no defined limit on how many you include here,
                              but servers may return a 400 Bad Request if you ask
                              for too many.  All servers should support <= 1000
                              though.

   maxwaitsec      optional   The client may send this, an integer max number
                              of seconds the client is willing to wait
                              for the arrival of blobs.  If the server
                              supports long-polling (an optional
                              feature), then the server will return
                              immediately if all the requested blobs
                              or available, or wait up until this
                              amount of time for the blobs to become
                              available.  The server's reply must
                              include "canLongPoll" set to true if the
                              server supports this feature.  Even if
                              the server supports long polling, the
                              server may cap 'maxwaitsec' and wait for
                              less time than requested by the client.

Examples:

GET /some-blob-root/camli/stat?camliversion=1&blob1=sha1-9b03f7aca1ac60d40b5e570c34f79a3e07c918e8 HTTP/1.1
Host: example.com

 -or-

POST /some-blob-root/camli/stat HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: example.com

camliversion=1&
blob1=sha1-9b03f7aca1ac60d40b5e570c34f79a3e07c918e8&
blob2=sha1-abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd&
blob3=sha1-deadbeefdeadbeefdeadbeefdeadbeefdeadbeef

--------------------------------------------------
Response:
--------------------------------------------------

HTTP/1.1 200 OK
Content-Length: ...
Content-Type: text/javascript

{
   "stat": [
      {"blobRef": "sha1-abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd",
       "size": 12312}
   ],
   "canLongPoll": true
}

Response keys:

   stat             required   Array of {"blobRef": BLOBREF, "size": INT_bytes}
                               for blobs that the system already has. Empty
                               list if no blobs are already present.

   canLongPoll      optional   Set to true (type boolean) if the server supports
                               long polling.  If not true, the server ignores
                               the client's "maxwaitsec" parameter.