-API break: allow clients to specify number of years of service to pay for, including reducer update. Will break stuff, partial patch for #6841

1 files changed, 66 insertions, 7 deletions

diff --git a/anastasis.rst b/anastasis.rst
index 5ceff112..10448a34 100644
--- a/anastasis.rst
+++ b/anastasis.rst
@@ -670,12 +670,11 @@ In the following, UUID is always defined and used according to `RFC 4122`_.
 
   **Request**:
 
-  :query pay:
-     Optional argument, any non-empty value will do,
-     suggested is ``y`` for ``yes``.
-     The client insists on making a payment for the respective
-     account, even if this is not yet required. The server
-     will respond with a ``402 Payment required``, but only
+  :query storage_duration=YEARS:
+     For how many years from now would the client like us to
+     store the recovery document? Defaults to 0 (that is, do
+     not extend / prolong existing storage contract).
+     The server will respond with a ``402 Payment required``, but only
      if the rest of the request is well-formed (account
      signature must match).  Clients that do not actually
      intend to make a new upload but that only want to pay
@@ -888,6 +887,10 @@ charge per truth operation using GNU Taler.
       // MIME type of truth, i.e. text/ascii, image/jpeg, etc.
       truth_mime: string;
 
+      // For how many years from now would the client like us to
+      // store the truth?
+      storage_duration_years: integer;
+
     }
 
 .. http:get:: /truth/$UUID[?response=$H_RESPONSE]
@@ -1902,8 +1905,14 @@ The reducer will simply transition to the ``SECRET_EDITING`` state:
 
     {
       "backup_state": "SECRET_EDITING",
+      "upload_fees" : [ "KUDOS:42" ]
+      "expiration" : { "FIXME_ms" : 1245362362 }
     }
 
+Here, ``upload_fees`` is an array of applicable upload fees for the
+given policy expiration time. This is an array because fees could
+be in different currencies.  The final cost may be lower if the
+user already paid for some of the time.
 
 If the array of ``policies`` is currently empty, the reducer will transition
 into an ``ERROR`` state instead of allowing the user to continue.
@@ -1922,10 +1931,60 @@ for example:
       "secret": {
          "value": "EDJP6WK5EG50",
          "mime" : "text/plain"
-      }
+      },
+      "name": "$NAME",
+      "expiration" : { "FIXME_ms" : 1245362362 }
     }
 
 If the application is unaware of the format, it set the ``mime`` field to ``null``.
+The ``name`` and ``expiration`` fields are optional.
+
+The reducer remains in the ``SECRET_EDITING`` state, but now the secret and
+updated expiration time are part of the state and the cost calculations will
+be updated.
+
+.. code-block:: json
+
+    {
+      "backup_state": "SECRET_EDITING",
+      "core_secret" : "$DATA",
+      "secret_name" : "$NAME",
+      "expiration" : { "FIXME_ms" : 1245362362 },
+      "upload_fees" : [ "KUDOS:42" ]
+    }
+
+
+**update_expiration:**
+
+This transition asks the reducer to change the desired expiration time
+and to update the associated cost. For example:
+
+.. code-block:: javascript
+
+    {
+      "expiration" : { "FIXME_ms" : 1245362362 }
+    }
+
+The reducer remains in the ``SECRET_EDITING`` state, but the
+expiration time and cost calculation will be updated.
+
+.. code-block:: json
+
+    {
+      "backup_state": "SECRET_EDITING",
+      "expiration" : { "FIXME_ms" : 1245362362 },
+      "upload_fees" : [ "KUDOS:43" ]
+    }
+
+
+**next** (from ``SECRET_EDITING``):
+
+Using this transition, the user confirms that the secret and expiration
+settings in the current state are acceptable. The transition does not take any
+arguments.
+
+If the secret is currently empty, the reducer will transition into an
+``ERROR`` state instead of allowing the user to continue.
 
 After adding a secret, the reducer may transition into different states
 depending on whether payment(s) are necessary.  If payments are needed, the