Merge pull request #1213 from tahoe-lafs/3922.minor-gbs-text-fixes

Fix some minor GBS spec issues

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

@@ -30,12 +30,12 @@ Glossary
    introducer
      a Tahoe-LAFS process at a known location configured to re-publish announcements about the location of storage servers
 
-   fURL
+   :ref:`fURLs <fURLs>`
      a self-authenticating URL-like string which can be used to locate a remote object using the Foolscap protocol
      (the storage service is an example of such an object)
 
-   NURL
-     a self-authenticating URL-like string almost exactly like a NURL but without being tied to Foolscap
+   :ref:`NURLs <NURLs>`
+     a self-authenticating URL-like string almost exactly like a fURL but without being tied to Foolscap
 
    swissnum
      a short random string which is part of a fURL/NURL and which acts as a shared secret to authorize clients to use a storage service
@@ -579,24 +579,6 @@ Responses:
   the response is ``CONFLICT``.
   At this point the only thing to do is abort the upload and start from scratch (see below).
 
-``PUT /storage/v1/immutable/:storage_index/:share_number/abort``
-!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-
-This cancels an *in-progress* upload.
-
-The request must include a ``X-Tahoe-Authorization`` header that includes the upload secret::
-
-    X-Tahoe-Authorization: upload-secret <base64-upload-secret>
-
-The response code:
-
-* When the upload is still in progress and therefore the abort has succeeded,
-  the response is ``OK``.
-  Future uploads can start from scratch with no pre-existing upload state stored on the server.
-* If the uploaded has already finished, the response is 405 (Method Not Allowed)
-  and no change is made.
-
-
 Discussion
 ``````````
 
@@ -615,6 +597,25 @@ From RFC 7231::
    PATCH method defined in [RFC5789]).
 
 
+
+``PUT /storage/v1/immutable/:storage_index/:share_number/abort``
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+This cancels an *in-progress* upload.
+
+The request must include a ``X-Tahoe-Authorization`` header that includes the upload secret::
+
+    X-Tahoe-Authorization: upload-secret <base64-upload-secret>
+
+The response code:
+
+* When the upload is still in progress and therefore the abort has succeeded,
+  the response is ``OK``.
+  Future uploads can start from scratch with no pre-existing upload state stored on the server.
+* If the uploaded has already finished, the response is 405 (Method Not Allowed)
+  and no change is made.
+
+
 ``POST /storage/v1/immutable/:storage_index/:share_number/corrupt``
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
@@ -624,7 +625,7 @@ corruption. It also includes potentially important details about the share.
 
 For example::
 
-  {"reason": u"expected hash abcd, got hash efgh"}
+  {"reason": "expected hash abcd, got hash efgh"}
 
 .. share-type, storage-index, and share-number are inferred from the URL
 
@@ -798,6 +799,7 @@ Immutable Data
      <first 16 bytes of share data>
 
      200 OK
+     { "required": [ {"begin": 16, "end": 48 } ] }
 
      PATCH /storage/v1/immutable/AAAAAAAAAAAAAAAA/7
      Authorization: Tahoe-LAFS nurl-swissnum
@@ -806,6 +808,7 @@ Immutable Data
      <second 16 bytes of share data>
 
      200 OK
+     { "required": [ {"begin": 32, "end": 48 } ] }
 
      PATCH /storage/v1/immutable/AAAAAAAAAAAAAAAA/7
      Authorization: Tahoe-LAFS nurl-swissnum
@@ -822,6 +825,7 @@ Immutable Data
      Range: bytes=0-47
 
      200 OK
+     Content-Range: bytes 0-47/48
      <complete 48 bytes of previously uploaded data>
 
 #. Renew the lease on all immutable shares in bucket ``AAAAAAAAAAAAAAAA``::
@@ -905,9 +909,12 @@ otherwise it will read a byte which won't match `b""`::
 
 #. Download the contents of share number ``3``::
 
-     GET /storage/v1/mutable/BBBBBBBBBBBBBBBB?share=3&offset=0&size=10
+     GET /storage/v1/mutable/BBBBBBBBBBBBBBBB?share=3
      Authorization: Tahoe-LAFS nurl-swissnum
+     Range: bytes=0-16
 
+     200 OK
+     Content-Range: bytes 0-15/16
      <complete 16 bytes of previously uploaded data>
 
 #. Renew the lease on previously uploaded mutable share in slot ``BBBBBBBBBBBBBBBB``::

docs/specifications/url.rst

@@ -7,6 +7,8 @@ These are not to be confused with the URI-like capabilities Tahoe-LAFS uses to r
 An attempt is also made to outline the rationale for certain choices about these URLs.
 The intended audience for this document is Tahoe-LAFS maintainers and other developers interested in interoperating with Tahoe-LAFS or these URLs.
 
+.. _furls:
+
 Background
 ----------
 
@@ -31,6 +33,8 @@ The client's use of the swissnum is what allows the server to authorize the clie
 
 .. _`swiss number`: http://wiki.erights.org/wiki/Swiss_number
 
+.. _NURLs:
+
 NURLs
 -----
 

newsfragments/3922.documentation

@@ -0,0 +1 @@
+Several minor errors in the Great Black Swamp proposed specification document have been fixed.