From 602d4c5a9129e6312c1ed64d72dc4fb365f53ec4 Mon Sep 17 00:00:00 2001 From: Jean-Paul Calderone Date: Thu, 19 Aug 2021 10:26:45 -0400 Subject: [PATCH] improve the "create lease" endpoint * Simplify some language using terms from our new glossary * explicitly state the two success-case behaviors * make the error-case behavior different from the success-case behavior * link to some tickets about future work in this area --- docs/proposed/http-storage-node-protocol.rst | 24 ++++++++++++-------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/proposed/http-storage-node-protocol.rst b/docs/proposed/http-storage-node-protocol.rst index 41a0a0fea..de0918b58 100644 --- a/docs/proposed/http-storage-node-protocol.rst +++ b/docs/proposed/http-storage-node-protocol.rst @@ -369,19 +369,26 @@ For example:: ``PUT /v1/lease/:storage_index`` !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -Create a new lease that applies to all shares for the given storage index. +Create a new lease on the bucket addressed by ``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. +then the expiration time of that lease will be changed to 31 days after the time of this operation. +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. + +In these cases the response is ``NO CONTENT`` with an empty body. + +It is possible that the storage server will have no shares for the given ``storage_index`` because: + +* no such shares have ever been uploaded. +* a previous lease expired and the storage server reclaimed the storage by deleting the shares. + +In these cases the server takes no action and returns ``NOT FOUND``. -The lease expires after 31 days. Discussion `````````` @@ -391,10 +398,9 @@ 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. +* There is a cancel secret but there is no API to use it to cancel a lease (see ticket:3768). * 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. +* There are separate **add** and **renew** lease APIs (see ticket:3773). These are not necessarily ideal behaviors but they are adopted to avoid any *semantic* changes between the Foolscap- and HTTP-based protocols.