commit 879fc64fbdc2049e1bba5dd7b0c793c344348c2f
parent 3e364b9c8daab32566c945d369cba5de9f74e801
Author: Christian Grothoff <christian@grothoff.org>
Date: Wed, 31 Mar 2021 00:07:51 +0200
docs
Diffstat:
| M | anastasis.rst | | | 100 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------------- |
1 file changed, 79 insertions(+), 21 deletions(-)
diff --git a/anastasis.rst b/anastasis.rst
@@ -1869,23 +1869,44 @@ Example results are thus:
**pay:**
-FIXME: this is wrong! long polling!
-Optional arguments to try uploading just specific truths (example):
+This transition suggests to the reducer that a payment may have been made or
+is immanent, and that the reducer should check with the Anastasis service
+provider to see if the operation is now possible. The operation takes one
+optional argument, which is a ``timeout`` value that specifies how long the
+reducer may wait (in long polling) for the payment to complete:
.. code-block:: json
{
- "truth_index": [
- 1,
- 2
- ]
+ "timeout": { "d_ms" : 5000 },
}
-..note::
+The specified timeout is passed on to the Anastasis service provider(s), which
+will wait this long before giving up. If no timeout is given, the check is
+done as quickly as possible without additional delays. The reducer will continue
+to either an updated state with the remaining payment requests, to the
+``BACKUP_FINISHED`` state (if all payments have been completed and the backup
+finished), or into an ``ERROR`` state in case there was an irrecoverable error,
+indicating the specific provider and how it failed. An example for this
+final error state would be:
+
+.. code-block:: json
+
+ {
+ "backup_state": "ERROR",
+ "http_status" : 500,
+ "upload_status" : 52,
+ "provider_url" : "https://bad.example.com/",
+ }
- This is currently not supported (#6761).
+Here, the fields have the following meaning:
+ - **http_status** is the HTTP status returned by the Anastasis provider
+ - **upload_status** is the Taler error code return by the provider
+ - **provider_url** is the base URL of the failing provider
+In the above example, 52 would thus imply that the Anastasis provider failed to
+store information into its database.
Recovery transitions
@@ -1893,7 +1914,12 @@ Recovery transitions
**enter_user_attributes:**
-Arguments (example):
+This transition provides the user's personal attributes. The specific set of
+attributes required depends on the country of residence of the user. Some
+attributes may be optional, in which case they should be omitted entirely
+(that is, not simply be set to ``null`` or an empty string). The
+arguments are identical to the **enter_user_attributes__ transition from
+the backup process. Example arguments would thus be:
.. code-block:: json
@@ -1901,28 +1927,58 @@ Arguments (example):
"identity_attributes": {
"full_name": "Max Musterman",
"social_security_number": "123456789",
- "birth_year": 2000,
- "birth_month": 1,
- "birth_day": 1
+ "birthdate": "2000-01-01",
+ "birthplace": "Earth"
}
}
-Expected new state:
+However, in contrast to the backup process, the reducer will attempt to
+retrieve the latest recovery document from all known providers for the
+selected currency given the above inputs. If a recovery document was found
+by any provider, the reducer will attempt to load it and transition to
+a state where the user can choose which challenges to satisfy:
.. code-block:: json
{
- "backup_state": "CHALLENGE_SELECTING",
- "identity_attributes": {
- "full_name": "Max Musterman",
- "social_security_number": "123456789",
- "birth_year": 2000,
- "birth_month": 1,
- "birth_day": 1
- }
+ "recovery_state": "CHALLENGE_SELECTING",
+ FIXME: document rest of state here!
}
+If a recovery document was not found, either the user never performed
+a backup, entered incorrect attributes or used a provider not yet in
+the list of Anastasis providers. Hence, the user must now either
+select a different provider, or go ``back`` and update the identity
+attributes. In the case a recovery document was not found, an
+example for the new state is:
+
+.. code-block:: json
+
+ {
+ "recovery_state": "CHALLENGE_SELECTING",
+ FIXME: document rest of state here!
+ }
+**change_version:**
+
+Even if a recovery document was found, it is possible that the user
+intended to recover a different version, or recover a backup where
+the recovery document is stored at a different provider. Thus, the
+reducer allows the user to explicitly switch to a different provider
+or recovery document version using the ``change_version`` transition,
+which takes a provider URL and policy version as arguments:
+
+.. code-block:: json
+
+ {
+ "provider_url": "https://localhost:8080/",
+ "version": 2 // FIXME: correct like this?
+ }
+
+The resulting states are the same as those of the
+``enter_user_attributes`` transition, except that the recovery
+document version is not necessarily the latest available version
+at the provider.
**select_challenge:**
@@ -1931,6 +1987,8 @@ Selecting a challenge takes various formats, depending on the method.
Specifically, in the case of a security question, the answer should
already be provided.
+FIXME: give more details!
+
Arguments (example):
.. code-block:: json
