rest, events: Add "remoteState" to FolderCompletion, add ClusterConfi…

…gReceived (#736)

* rest, events: Add "accepted" boolean to FolderCompletion.

* Clarify that "accepted" is meaningless for disconnected remotes.

* rest, events: Switch to remoteState attribute, add new event.

Dump the "accepted" boolean in favor of the now implemented
"remoteState" enumeration.  Document the new ClusterConfigReceived
event type.

* Explicitly mention unknown and valid states.

events/clusterconfigreceived.rst

@@ -0,0 +1,19 @@
+ClusterConfigReceived
+---------------------
+
+.. versionadded:: 1.20.0
+
+The ``ClusterConfigReceived`` event is emitted after processing such a protocol
+message received from a remote device.  It is mainly used for internal purposes.
+
+.. code-block:: json
+
+    {
+        "id": 84,
+        "globalID": 84,
+        "type": "ClusterConfigReceived",
+        "time": "2022-04-27T14:14:27.043576583+09:00",
+        "data": {
+            "device": "I6KAH76-66SLLLB-5PFXSOA-UFJCDZC-YAOMLEK-CP2GB32-BV5RQST-3PSROAU"
+        }
+    }

events/foldercompletion.rst

@@ -6,13 +6,20 @@ contents for a folder changes. It contains the completion percentage for
 a given remote device and is emitted once per currently connected remote
 device.
 
+.. versionadded:: 1.20.0
+
+  Indication whether the remote device has accepted the folder (shares it with
+  us) as well, and whether it is paused.  The ``remoteState`` field is
+  ``unknown`` when the remote device is not connected.  Otherwise it can be
+  either ``paused``, ``notSharing``, or ``valid`` if the remote is sharing back.
+
 .. code-block:: json
 
     {
         "id": 84,
         "globalID": 84,
         "type": "FolderCompletion",
-        "time": "2015-04-17T14:14:27.043576583+09:00",
+        "time": "2022-04-27T14:14:27.043576583+09:00",
         "data": {
             "completion": 100,
             "device": "I6KAH76-66SLLLB-5PFXSOA-UFJCDZC-YAOMLEK-CP2GB32-BV5RQST-3PSROAU",
@@ -22,6 +29,7 @@ device.
             "needBytes": 0,
             "needDeletes": 0,
             "needItems": 0,
+            "remoteState": "valid",
             "sequence": 12
         }
     }

rest/db-completion-get.rst

@@ -44,6 +44,7 @@ Example Response
       "globalItems": 7823,
       "needItems": 412,
       "needDeletes": 0,
+      "remoteState": "valid",
       "sequence": 12
     }
 
@@ -52,3 +53,11 @@ Example Response
   The ability to aggregate multiple folders by leaving out the folder ID.
   Querying data for the local device by leaving out the device ID. Returning
   the ``globalItems`` counter in the response.
+
+.. versionadded:: 1.20.0
+
+  Indication whether the remote device has accepted the folder (shares it with
+  us) as well, and whether it is paused.  The ``remoteState`` field is
+  meaningless for aggregated responses, ``unknown`` when the remote device is
+  not connected.  Otherwise it can be either ``paused``, ``notSharing``, or
+  ``valid`` if the remote is sharing back.