Changeset 1819e080 in trunk

Timestamp:

2021-09-02T20:21:20Z (4 years ago)

Author:

GitHub <noreply@…>

Branches:

master

Children:

51b1e56, 8d15a0d5, a5d764d, f0fe323

Parents:

056ee58 (diff), ae9ec48 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

git-author:

Jean-Paul Calderone <exarkun@…> (2021-09-02 20:21:20)

git-committer:

GitHub <noreply@…> (2021-09-02 20:21:20)

Message:

Merge pull request #1116 from LeastAuthority?/3769.gbs-immutable-upload-spec-improvements

Some GBS immutable upload spec improvements

Fixes: ticket:3769

Files:

• docs/proposed/http-storage-node-protocol.rst (modified) (1 diff)
• newsfragments/3769.documentation (added)

docs/proposed/http-storage-node-protocol.rst ¶

@@ -459 +459 @@
 The share number must belong to the storage index.
 The request body is the raw share data (i.e., ``application/octet-stream``).
-*Content-Range* requests are encouraged for large transfers.
+*Content-Range* requests are encouraged for large transfers to allow partially complete uploads to be resumed.
 For example,
-for a 1MiB share the data can be broken in to 8 128KiB chunks.
-Each chunk can be *PUT* separately with the appropriate *Content-Range* header.
+a 1MiB share can be divided in to eight separate 128KiB chunks.
+Each chunk can be uploaded in a separate request.
+Each request can include a *Content-Range* value indicating its placement within the complete share.
+If any one of these requests fails then at most 128KiB of upload work needs to be retried.
+
 The server must recognize when all of the data has been received and mark the share as complete
 (which it can do because it was informed of the size when the storage index was initialized).
 Clients should upload chunks in re-assembly order.
-Servers may reject out-of-order chunks for implementation simplicity.
-If an individual *PUT* fails then only a limited amount of effort is wasted on the necessary retry.
-
-.. think about copying https://developers.google.com/drive/api/v2/resumable-upload
+
+* When a chunk that does not complete the share is successfully uploaded the response is ``OK``.
+* When the chunk that completes the share is successfully uploaded the response is ``CREATED``.
+* If the *Content-Range* for a request covers part of the share that has already been uploaded the response is ``CONFLICT``.
+  The response body indicates the range of share data that has yet to be uploaded.
+  That is::
+
+    { "required":
+      [ { "begin": <byte position, inclusive>
+        , "end":   <byte position, exclusive>
+        }
+      ,
+      ...
+      ]
+    }
+
 
 ``POST /v1/immutable/:storage_index/:share_number/corrupt``