tahoe-lafs/tahoe-lafs
tahoe-lafs
/
tahoe-lafs
2
0
Fork 0
Code Issues Pull Requests 23 Packages Projects Releases 1 Wiki Activity

More consistent header system.

This commit is contained in:
Itamar Turner-Trauring 2021-11-10 14:42:22 -05:00
parent 125c937d46
commit 8dd4aaebb6
1 changed files with 63 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
docs/proposed/http-storage-node-protocol.rst
View File

@ -363,11 +363,11 @@ one branch contains all of the share data;
another branch contains all of the lease data; another branch contains all of the lease data;
etc. etc.
Authorization is required for all endpoints. An ``Authorization`` header in requests is required for all endpoints.
The standard HTTP authorization protocol is used. The standard HTTP authorization protocol is used.
The authentication *type* used is ``Tahoe-LAFS``. The authentication *type* used is ``Tahoe-LAFS``.
The swissnum from the NURL used to locate the storage service is used as the *credentials*. The swissnum from the NURL used to locate the storage service is used as the *credentials*.
If credentials are not presented or the swissnum is not associated with a storage service then no storage processing is performed and the request receives an ``UNAUTHORIZED`` response. If credentials are not presented or the swissnum is not associated with a storage service then no storage processing is performed and the request receives an ``401 UNAUTHORIZED`` response.
General General
~~~~~~~ ~~~~~~~
@ -396,17 +396,26 @@ For example::
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Either renew or create a new lease on the bucket addressed by ``storage_index``. Either renew or create a new lease on the bucket addressed by ``storage_index``.
The details of the lease are encoded in the request body.
For a renewal, the renew secret and cancellation secret should be included as ``X-Tahoe-Authorization`` headers.
For example:: For example::
{"renew-secret": "abcd", "cancel-secret": "efgh"} X-Tahoe-Authorization: lease-renew-secret <base64 lease-renew-secret>
X-Tahoe-Authorization: lease-cancel-secret <base64 lease-cancel-secret>
If the ``renew-secret`` value matches an existing lease For a new lease, ``X-Tahoe-Set-Authorization`` headers should be used instead.
then the expiration time of that lease will be changed to 31 days after the time of this operation. For example::
If it does not match an existing lease
then a new lease will be created with this ``renew-secret`` which expires 31 days after the time of this operation.
``renew-secret`` and ``cancel-secret`` values must be 32 bytes long. X-Tahoe-Set-Authorization: lease-renew-secret <base64 lease-renew-secret>
X-Tahoe-Set-Authorization: lease-cancel-secret <base64 lease-cancel-secret>
For renewal, the expiration time of that lease will be changed to 31 days after the time of this operation.
If the renewal secret does not match, a new lease will be created, but clients should still not rely on this behavior if possible, and instead use the appropriate new lease headers.
For the creation path,
then a new lease will be created with this ``lease-renew-secret`` which expires 31 days after the time of this operation.
``lease-renew-secret`` and ``lease-cancel-secret`` values must be 32 bytes long.
The server treats them as opaque values. The server treats them as opaque values.
:ref:`Share Leases` gives details about how the Tahoe-LAFS storage client constructs these values. :ref:`Share Leases` gives details about how the Tahoe-LAFS storage client constructs these values.
@ -423,7 +432,7 @@ In these cases the server takes no action and returns ``NOT FOUND``.
Discussion Discussion
`````````` ``````````
We considered an alternative where ``renew-secret`` and ``cancel-secret`` are placed in query arguments on the request path. We considered an alternative where ``lease-renew-secret`` and ``lease-cancel-secret`` are placed in query arguments on the request path.
We chose to put these values into the request body to make the URL simpler. We chose to put these values into the request body to make the URL simpler.
Several behaviors here are blindly copied from the Foolscap-based storage server protocol. Several behaviors here are blindly copied from the Foolscap-based storage server protocol.
@ -452,13 +461,13 @@ For example::
{"share-numbers": [1, 7, ...], "allocated-size": 12345} {"share-numbers": [1, 7, ...], "allocated-size": 12345}
The request must include ``WWW-Authenticate`` HTTP headers that set the various secrets—upload, lease renewal, lease cancellation—that will be later used to authorize various operations. The request must include ``X-Tahoe-Set-Authorization`` HTTP headers that set the various secrets—upload, lease renewal, lease cancellation—that will be later used to authorize various operations.
Typically this is a header sent by the server, but in Tahoe-LAFS keys are set by the client, so may as well reuse it. Typically this is a header sent by the server, but in Tahoe-LAFS keys are set by the client, so may as well reuse it.
For example:: For example::
WWW-Authenticate: x-tahoe-renew-secret <base64-renew-secret> X-Tahoe-Set-Authorization: lease-renew-secret <base64-lease-renew-secret>
WWW-Authenticate: x-tahoe-cancel-secret <base64-cancel-secret> X-Tahoe-Set-Authorization: lease-cancel-secret <base64-lease-cancel-secret>
WWW-Authenticate: x-tahoe-upload-secret <base64-upload-secret> X-Tahoe-Set-Authorization: upload-secret <base64-upload-secret>
The response body includes encoded information about the created buckets. The response body includes encoded information about the created buckets.
For example:: For example::
@ -527,9 +536,9 @@ If any one of these requests fails then at most 128KiB of upload work needs to b
The server must recognize when all of the data has been received and mark the share as complete 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). (which it can do because it was informed of the size when the storage index was initialized).
The request must include a ``Authorization`` header that includes the upload secret:: The request must include a ``X-Tahoe-Authorization`` header that includes the upload secret::
Authorization: x-tahoe-upload-secret <base64ed-upload-secret> X-Tahoe-Authorization: upload-secret <base64ed-upload-secret>
Responses: Responses:
@ -557,9 +566,9 @@ Responses:
This cancels an *in-progress* upload. This cancels an *in-progress* upload.
The request body looks this:: The request must include a ``Authorization`` header that includes the upload secret::
{ "upload-secret": "xyzf" } X-Tahoe-Authorization: upload-secret <base64ed-upload-secret>
The response code: The response code:
@ -658,16 +667,16 @@ The first write operation on a mutable storage index creates it
(that is, (that is,
there is no separate "create this storage index" operation as there is for the immutable storage index type). there is no separate "create this storage index" operation as there is for the immutable storage index type).
The request body includes the secrets necessary to rewrite to the shares The request must include ``X-Tahoe-Authorization`` headers with write enabler and lease secrets::
along with test, read, and write vectors for the operation.
X-Tahoe-Authorization: write-enabler <base64 write enabler secret>
X-Tahoe-Authorization: lease-lease-cancel-secret <base64-lease-lease-cancel-secret>
X-Tahoe-Authorization: lease-renew-secret <base64-lease-renew-secret>
The request body includes test, read, and write vectors for the operation.
For example:: For example::
{ {
"secrets": {
"write-enabler": "abcd",
"lease-renew": "efgh",
"lease-cancel": "ijkl"
},
"test-write-vectors": { "test-write-vectors": {
0: { 0: {
"test": [{ "test": [{
@ -733,9 +742,10 @@ Immutable Data
1. Create a bucket for storage index ``AAAAAAAAAAAAAAAA`` to hold two immutable shares, discovering that share ``1`` was already uploaded:: 1. Create a bucket for storage index ``AAAAAAAAAAAAAAAA`` to hold two immutable shares, discovering that share ``1`` was already uploaded::
POST /v1/immutable/AAAAAAAAAAAAAAAA POST /v1/immutable/AAAAAAAAAAAAAAAA
WWW-Authenticate: x-tahoe-renew-secret efgh Authorization: Tahoe-LAFS nurl-swissnum
WWW-Authenticate: x-tahoe-cancel-secret jjkl X-Tahoe-Set-Authorization: lease-renew-secret efgh
WWW-Authenticate: x-tahoe-upload-secret xyzf X-Tahoe-Set-Authorization: lease-cancel-secret jjkl
X-Tahoe-Set-Authorization: upload-secret xyzf
{"share-numbers": [1, 7], "allocated-size": 48} {"share-numbers": [1, 7], "allocated-size": 48}
@ -745,22 +755,25 @@ Immutable Data
#. Upload the content for immutable share ``7``:: #. Upload the content for immutable share ``7``::
PATCH /v1/immutable/AAAAAAAAAAAAAAAA/7 PATCH /v1/immutable/AAAAAAAAAAAAAAAA/7
Authorization: Tahoe-LAFS nurl-swissnum
Content-Range: bytes 0-15/48 Content-Range: bytes 0-15/48
Authorization: x-tahoe-upload-secret xyzf X-Tahoe-Authorization: upload-secret xyzf
<first 16 bytes of share data> <first 16 bytes of share data>
200 OK 200 OK
PATCH /v1/immutable/AAAAAAAAAAAAAAAA/7 PATCH /v1/immutable/AAAAAAAAAAAAAAAA/7
Authorization: Tahoe-LAFS nurl-swissnum
Content-Range: bytes 16-31/48 Content-Range: bytes 16-31/48
Authorization: x-tahoe-upload-secret xyzf X-Tahoe-Authorization: upload-secret xyzf
<second 16 bytes of share data> <second 16 bytes of share data>
200 OK 200 OK
PATCH /v1/immutable/AAAAAAAAAAAAAAAA/7 PATCH /v1/immutable/AAAAAAAAAAAAAAAA/7
Authorization: Tahoe-LAFS nurl-swissnum
Content-Range: bytes 32-47/48 Content-Range: bytes 32-47/48
Authorization: x-tahoe-upload-secret xyzf X-Tahoe-Authorization: upload-secret xyzf
<final 16 bytes of share data> <final 16 bytes of share data>
201 CREATED 201 CREATED
@ -768,6 +781,7 @@ Immutable Data
#. Download the content of the previously uploaded immutable share ``7``:: #. Download the content of the previously uploaded immutable share ``7``::
GET /v1/immutable/AAAAAAAAAAAAAAAA?share=7 GET /v1/immutable/AAAAAAAAAAAAAAAA?share=7
Authorization: Tahoe-LAFS nurl-swissnum
Range: bytes=0-47 Range: bytes=0-47
200 OK 200 OK
@ -776,7 +790,9 @@ Immutable Data
#. Renew the lease on all immutable shares in bucket ``AAAAAAAAAAAAAAAA``:: #. Renew the lease on all immutable shares in bucket ``AAAAAAAAAAAAAAAA``::
PUT /v1/lease/AAAAAAAAAAAAAAAA PUT /v1/lease/AAAAAAAAAAAAAAAA
{"renew-secret": "efgh", "cancel-secret": "ijkl"} Authorization: Tahoe-LAFS nurl-swissnum
X-Tahoe-Authorization: lease-cancel-secret jjkl
X-Tahoe-Authorization: upload-secret xyzf
204 NO CONTENT 204 NO CONTENT
@ -789,12 +805,12 @@ if there is no existing share,
otherwise it will read a byte which won't match `b""`:: otherwise it will read a byte which won't match `b""`::
POST /v1/mutable/BBBBBBBBBBBBBBBB/read-test-write POST /v1/mutable/BBBBBBBBBBBBBBBB/read-test-write
Authorization: Tahoe-LAFS nurl-swissnum
X-Tahoe-Authorization: write-enabler abcd
X-Tahoe-Authorization: lease-cancel-secret efgh
X-Tahoe-Authorization: lease-renew-secret ijkl
{ {
"secrets": {
"write-enabler": "abcd",
"lease-renew": "efgh",
"lease-cancel": "ijkl"
},
"test-write-vectors": { "test-write-vectors": {
3: { 3: {
"test": [{ "test": [{
@ -821,12 +837,12 @@ otherwise it will read a byte which won't match `b""`::
#. Safely rewrite the contents of a known version of mutable share number ``3`` (or fail):: #. Safely rewrite the contents of a known version of mutable share number ``3`` (or fail)::
POST /v1/mutable/BBBBBBBBBBBBBBBB/read-test-write POST /v1/mutable/BBBBBBBBBBBBBBBB/read-test-write
Authorization: Tahoe-LAFS nurl-swissnum
X-Tahoe-Authorization: write-enabler abcd
X-Tahoe-Authorization: lease-cancel-secret efgh
X-Tahoe-Authorization: lease-renew-secret ijkl
{ {
"secrets": {
"write-enabler": "abcd",
"lease-renew": "efgh",
"lease-cancel": "ijkl"
},
"test-write-vectors": { "test-write-vectors": {
3: { 3: {
"test": [{ "test": [{
@ -853,12 +869,16 @@ otherwise it will read a byte which won't match `b""`::
#. Download the contents of share number ``3``:: #. Download the contents of share number ``3``::
GET /v1/mutable/BBBBBBBBBBBBBBBB?share=3&offset=0&size=10 GET /v1/mutable/BBBBBBBBBBBBBBBB?share=3&offset=0&size=10
Authorization: Tahoe-LAFS nurl-swissnum
<complete 16 bytes of previously uploaded data> <complete 16 bytes of previously uploaded data>
#. Renew the lease on previously uploaded mutable share in slot ``BBBBBBBBBBBBBBBB``:: #. Renew the lease on previously uploaded mutable share in slot ``BBBBBBBBBBBBBBBB``::
PUT /v1/lease/BBBBBBBBBBBBBBBB PUT /v1/lease/BBBBBBBBBBBBBBBB
{"renew-secret": "efgh", "cancel-secret": "ijkl"} Authorization: Tahoe-LAFS nurl-swissnum
X-Tahoe-Authorization: lease-cancel-secret efgh
X-Tahoe-Authorization: lease-renew-secret ijkl
204 NO CONTENT 204 NO CONTENT