mirror of https://github.com/perkeep/perkeep.git
85 lines
3.5 KiB
Markdown
85 lines
3.5 KiB
Markdown
|
# Blob Stat Protocol
|
||
|
|
|
||
|
|
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](blob-upload.md) 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](blob-upload.md) and [discovery](discovery.md) 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.
|
||
|
|
|