Add an http endpoint for making users as syncing

Add some docstrings and comments.

synapse/handlers/presence.py

@@ -392,6 +392,10 @@ class PresenceHandler(object):
         defer.returnValue(_user_syncing())
 
     def get_currently_syncing_users(self):
+        """Get the set of user ids that are currently syncing on this HS.
+        Returns:
+            set(str): A set of user_id strings.
+        """
         syncing_user_ids = {
             user_id for user_id, count in self.user_to_num_current_syncs.items()
             if count
@@ -401,15 +405,30 @@ class PresenceHandler(object):
 
     @defer.inlineCallbacks
     def update_external_syncs(self, process_id, syncing_user_ids):
-        time_now_ms = self.clock.time_msec()
+        """Update the syncing users for an external process
+
+        Args:
+            process_id(str): An identifier for the process the users are
+                syncing against. This allows synapse to process updates
+                as user start and stop syncing against a given process.
+            syncing_user_ids(set(str)): The set of user_ids that are
+                currently syncing on that server.
+        """
+
+        # Grab the previous list of user_ids that were syncing on that process
         prev_syncing_user_ids = (
             self.external_process_to_current_syncs.get(process_id, set())
         )
+        # Grab the current presence state for both the users that are syncing
+        # now and the users that were syncing before this update.
         prev_states = yield self.current_state_for_users(
             syncing_user_ids + prev_syncing_user_ids
         )
         updates = []
+        time_now_ms = self.clock.time_msec()
 
+        # For each new user that is syncing check if we need to mark them as
+        # being online.
         for new_user_id in syncing_user_ids - prev_syncing_user_ids:
             prev_state = prev_states[new_user_id]
             if prev_state.state == PresenceState.OFFLINE:
@@ -423,6 +442,9 @@ class PresenceHandler(object):
                     last_user_sync_ts=time_now_ms,
                 ))
 
+        # For each user that is still syncing or stopped syncing update the
+        # last sync time so that we will correctly apply the grace period when
+        # they stop syncing.
         for old_user_id in prev_syncing_user_ids:
             prev_state = prev_states[old_user_id]
             updates.append(prev_state.copy_and_replace(
@@ -431,10 +453,10 @@ class PresenceHandler(object):
 
         yield self._update_states(updates)
 
-        self.external_process_last_updated_ms = time_now_ms
+        # Update the last updated time for the process. We expire the entries
+        # if we don't receive an update in the given timeframe.
+        self.external_process_last_updated_ms[process_id] = self.clock.time_msec()
         self.external_process_to_current_syncs[process_id] = syncing_user_ids
-        if not syncing_user_ids:
-            del self.external_process_to_current_syncs[process_id]
 
     @defer.inlineCallbacks
     def current_state_for_user(self, user_id):

synapse/replication/presence_resource.py

@@ -0,0 +1,58 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from synapse.http.server import respond_with_json_bytes, request_handler
+from synapse.http.servlet import parse_json_object_from_request
+
+from twisted.web.resource import Resource
+from twisted.web.server import NOT_DONE_YET
+from twisted.internet import defer
+
+
+class PresenceResource(Resource):
+    """
+    HTTP endpoint for marking users as syncing.
+
+    POST /_synapse/replication/presence HTTP/1.1
+    Content-Type: application/json
+
+    {
+        "process_id": "<process_id>",
+        "syncing_users": ["<user_id>"]
+    }
+    """
+
+    def __init__(self, hs):
+        Resource.__init__(self)  # Resource is old-style, so no super()
+
+        self.version_string = hs.version_string
+        self.presence_handler = hs.get_presence_handler()
+
+    def render_POST(self, request):
+        self._async_render_POST(request)
+        return NOT_DONE_YET
+
+    @request_handler()
+    @defer.inlineCallbacks
+    def _async_render_POST(self, request):
+        content = parse_json_object_from_request(request)
+
+        process_id = content["process_id"]
+        syncing_user_ids = content["syncing_users"]
+
+        yield self.presence_handler.update_external_syncs(
+            process_id, set(syncing_user_ids)
+        )
+
+        respond_with_json_bytes(request, 200, "{}")

synapse/replication/resource.py

@@ -16,6 +16,7 @@
 from synapse.http.servlet import parse_integer, parse_string
 from synapse.http.server import request_handler, finish_request
 from synapse.replication.pusher_resource import PusherResource
+from synapse.replication.presence_resource import PresenceResource
 
 from twisted.web.resource import Resource
 from twisted.web.server import NOT_DONE_YET
@@ -115,6 +116,7 @@ class ReplicationResource(Resource):
         self.clock = hs.get_clock()
 
         self.putChild("remove_pushers", PusherResource(hs))
+        self.putChild("syncing_users", PresenceResource(hs))
 
     def render_GET(self, request):
         self._async_render_GET(request)