REST: file storage
The endpoint /storage stores a file on the network, reads it back and deletes it. The data is spread over
gridnodes with erasure coding, see Network storage and Erasure coding. The
endpoint is part of the REST interface and needs the bearer token like every other endpoint.
The fingerprint. An upload answers with a fingerprint, 32 secret bytes behind one format byte in base58 with
a checksum. It is the only key to the file. It is sent in the header X-Fingerprint and never in the URL, so it
does not end up in a log of requests. A fingerprint that is not well formed is answered with 400 and
Malformed fingerprint.
Limits. A file may be up to 64 GiB. The body is streamed, so a file does not have to fit in memory. The storage spork must be set and enough gridnodes must be active, see Grid sporks.
After 0.0.8. File storage is on the
masterbranch and not part of a release yet. Release 0.0.9 answers every call with 503 andThis release does not include the storage partunless the node runs with the hidden--previewswitch, which turns on the parts the release leaves off.
POST /storage
The body is the file, application/octet-stream, with a Content-Length.
| Answer | Meaning |
|---|---|
| 201 | The file is stored. The body is {"fingerprint": "<fingerprint>"} |
| 411 | The request has no Content-Length; a body is read only when it announces a length |
| 413 | The announced length is above 64 GiB |
| 503 | The storage spork is not set, or fewer gridnodes are active than a file needs |
| 500 | The store failed |
GET /storage
The header X-Fingerprint names the file. The body is the file, streamed, and X-File-Size holds its size, so a
client can tell that a stripe was lost late and the stream ended early.
| Answer | Meaning |
|---|---|
| 200 | The file |
| 400 | The fingerprint is not well formed |
| 404 | No file has that fingerprint |
| 410 | Too much of the file is lost to restore it |
| 503 | The storage spork is not set, or too few gridnodes are active |
| 500 | The read failed |
DELETE /storage
The header X-Fingerprint names the file.
| Answer | Meaning |
|---|---|
| 204 | The file is deleted |
| 400 | The fingerprint is not well formed |
| 404 | No file has that fingerprint |
| 503 | The storage spork is not set, or too few gridnodes are active |
| 500 | The delete failed |
In the source
application/src/main/java/org/unigrid/hedgehog/server/rest/StorageResource.java: the three calls and their answers.application/src/main/java/org/unigrid/hedgehog/model/storage/Fingerprint.java: the fingerprint.application/src/main/java/org/unigrid/hedgehog/service/storage/StorageService.java: the storing and reading that the calls hand over to.