[taler-anastasis] branch master updated: document sync_providers transition

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository anastasis.

The following commit(s) were added to refs/heads/master by this push:
     new f698795  document sync_providers transition
f698795 is described below

commit f6987954390132a274ddb613593c181bc593e006
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Fri Jan 21 21:47:54 2022 +0100

    document sync_providers transition
---
 doc/sphinx/reducer.rst | 32 +++++++++++++++++++++-----------
 1 file changed, 21 insertions(+), 11 deletions(-)

diff --git a/doc/sphinx/reducer.rst b/doc/sphinx/reducer.rst
index 5a92d9d..47bb98b 100644
--- a/doc/sphinx/reducer.rst
+++ b/doc/sphinx/reducer.rst
@@ -1443,23 +1443,33 @@ However, in general it should be sufficient to display 
the slightly
 more generic Taler error code that is returned with the new state.
 
 
-**FIXME: add new transition: sync_providers**
+**sync_providers**
 
 The downloaded policy may include secrets from providers for which
 we do not (yet) have the cost structure or even the salt. So here
-a client/UI should have _again_ the opportunity to explicitly request
-providers to be downloaded to fill in missing cost(s) and salts.
+an application can use the ``sync_providers`` request to download
+``/config`` from providers that are in the challenge list but not
+yet known with their salt and other attributes in the provider list.
 
-As providers may fail to respond, this action may need to be called
-repeatedly ("sync" button in the UI?).  Once all providers are in
-'sync', that button should be hidden/obscured.  Alternatively, we
-may want to enable long-polling on this one => no button!
+The transition fails if all providers relevant for the selected
+policy are already downloaded. Applications may either internally
+check the state for this, or call ``sync_providers`` until it fails
+with this error:
+
+.. code-block:: json
 
-Furthermore, we likely need an additional *error* case in case a
-challenge is selected for which the provider details are unknown
-(invalid input!), and the UI should somehow disable buttons for
-challenges for which the provider details are unknown.
+  {
+    "detail": "already in sync",
+    "code": 8400,
+    "hint": "The given action is invalid for the current state of the reducer."
+  }
 
+As providers may fail to respond, this action may need to be called
+repeatedly. The action will block until progress is made on any provider.
+As some providers may never respond, the application should disable
+challenge buttons for challenges where providers are down.  However,
+users should be able to solve challenges where the provider is up while
+the reducer is polling for ``/config`` in the background.
 
 
 **select_challenge:**

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.