From 61b5c8873834d458e58bdbab7ee0fb7fb385211b Mon Sep 17 00:00:00 2001
From: Jean-Paul Calderone <exarkun@twistedmatrix.com>
Date: Thu, 2 Sep 2021 13:16:20 -0400
Subject: [PATCH] reveal to clients what data is still required

This lets a client recover from an upload that completes but for which the
response is lost (eg because network error or client restart)
---
 docs/proposed/http-storage-node-protocol.rst | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/docs/proposed/http-storage-node-protocol.rst b/docs/proposed/http-storage-node-protocol.rst
index 5012d4143..d7a41e827 100644
--- a/docs/proposed/http-storage-node-protocol.rst
+++ b/docs/proposed/http-storage-node-protocol.rst
@@ -469,10 +469,21 @@ The server must recognize when all of the data has been received and mark the sh
 (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.
 
+* 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>
+        }
+      ,
+      ...
+      ]
+    }
 
-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``.
 
 ``POST /v1/immutable/:storage_index/:share_number/corrupt``
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!