document sync_providers transition

1 files 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:**