From af539a6f5c78f9f372f445712c1eb8280ae4fa50 Mon Sep 17 00:00:00 2001 From: Jean-Paul Calderone Date: Mon, 22 Mar 2021 13:44:44 -0400 Subject: [PATCH 1/3] news fragment --- newsfragments/3037.other | 1 + 1 file changed, 1 insertion(+) create mode 100644 newsfragments/3037.other diff --git a/newsfragments/3037.other b/newsfragments/3037.other new file mode 100644 index 000000000..947dc8f60 --- /dev/null +++ b/newsfragments/3037.other @@ -0,0 +1 @@ +The "Great Black Swamp" proposed specification has been expanded to include two lease management APIs. \ No newline at end of file From 6520d3a505daf6ac6cd7c0eddc525c1f424e10db Mon Sep 17 00:00:00 2001 From: Jean-Paul Calderone Date: Mon, 22 Mar 2021 13:44:48 -0400 Subject: [PATCH 2/3] add the APIs --- docs/proposed/http-storage-node-protocol.rst | 57 ++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/docs/proposed/http-storage-node-protocol.rst b/docs/proposed/http-storage-node-protocol.rst index 1bdc774de..36c718c56 100644 --- a/docs/proposed/http-storage-node-protocol.rst +++ b/docs/proposed/http-storage-node-protocol.rst @@ -257,6 +257,62 @@ For example:: "application-version": "1.13.0" } +``PUT /v1/lease/:storage_index`` +!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +Create a new lease that applies to all shares for the given storage index. +The details of the lease are encoded in the request body. +For example:: + + {"renew-secret": "abcd", "cancel-secret": "efgh"} + +If there are no shares for the given ``storage_index`` +then do nothing and return ``NO CONTENT``. + +If the ``renew-secret`` value matches an existing lease +then that lease will be renewed instead. + +The lease expires after 31 days. + +Discussion +`````````` + +Several behaviors here are blindly copied from the Foolscap-based storage server protocol. + +* There is a cancel secret but there is no API to use it to cancel a lease. +* The lease period is hard-coded at 31 days. +* There is no way to differentiate between success and an unknown **storage index**. +* There are separate **add** and **renew** lease APIs. + +These are not necessarily ideal behaviors +but they are adopted to avoid any *semantic* changes between the Foolscap- and HTTP-based protocols. +It is expected that some or all of these behaviors may change in a future revision of the HTTP-based protocol. + +``POST /v1/lease/:storage_index`` +!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +Renew an existing lease for all shares for the given storage index. +The details of the lease are encoded in the request body. +For example:: + + {"renew-secret": "abcd"} + +If there are no shares for the given ``storage_index`` +then ``NOT FOUND`` is returned. + +If there is no lease with a matching ``renew-secret`` value on the given storage index +then ``NOT FOUND`` is returned. +In this case, +if the storage index refers to mutable data +then the response also includes a list of nodeids where the lease can be renewed. +For example:: + + {"nodeids": ["aaa...", "bbb..."]} + +Othewise, +the matching lease's expiration time is changed to be 31 days from the time of this operation +and ``NO CONTENT`` is returned. + Immutable --------- @@ -268,6 +324,7 @@ Writing Initialize an immutable storage index with some buckets. The buckets may have share data written to them once. +A lease is also created for the shares. Details of the buckets to create are encoded in the request body. For example:: From 0485eeb126f9c6a1fe43e52d7cdf50e6587c4747 Mon Sep 17 00:00:00 2001 From: Jean-Paul Calderone Date: Tue, 30 Mar 2021 10:03:03 -0400 Subject: [PATCH 3/3] Attempt to explain inclusion of lease secrets in the body --- docs/proposed/http-storage-node-protocol.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/proposed/http-storage-node-protocol.rst b/docs/proposed/http-storage-node-protocol.rst index 36c718c56..dd778473e 100644 --- a/docs/proposed/http-storage-node-protocol.rst +++ b/docs/proposed/http-storage-node-protocol.rst @@ -234,6 +234,19 @@ Because of the simple types used throughout and the equivalence described in `RFC 7049`_ these examples should be representative regardless of which of these two encodings is chosen. +HTTP Design +~~~~~~~~~~~ + +The HTTP interface described here is informed by the ideas of REST +(Representational State Transfer). +For ``GET`` requests query parameters are preferred over values encoded in the request body. +For other requests query parameters are encoded into the message body. + +Many branches of the resource tree are conceived as homogenous containers: +one branch contains all of the share data; +another branch contains all of the lease data; +etc. + General ~~~~~~~ @@ -277,6 +290,9 @@ The lease expires after 31 days. Discussion `````````` +We considered an alternative where ``renew-secret`` and ``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. + Several behaviors here are blindly copied from the Foolscap-based storage server protocol. * There is a cancel secret but there is no API to use it to cancel a lease.