Return info_updates from room-modifying endpoints

This works similarly to returning the seqno from post-modifying
endpoints, but for room metadata (fields, pinned messages, mods, etc.).

This allows a client to track when the expected change should have been
applied to the room when there might be concurrent room polling that
could race with a pre-update response.

Author: jagerman

sogs/model/room.py

@@ -1374,9 +1374,8 @@ def set_moderator(self, user: User, *, added_by: User, admin=False, visible=True
                     admin=admin,
                     visible=visible,
                 )
-                if u.id in self._perm_cache:
-                    del self._perm_cache[u.id]
 
+                self._refresh()
                 if u.id in self._perm_cache:
                     del self._perm_cache[u.id]
 
@@ -1395,19 +1394,21 @@ def remove_moderator(self, user: User, *, removed_by: User, remove_admin_only: b
         if not self.check_admin(removed_by):
             raise BadPermission()
 
-        query(
-            f"""
-            UPDATE user_permission_overrides
-            SET admin = FALSE
-                {', moderator = FALSE, visible_mod = TRUE' if not remove_admin_only else ''}
-            WHERE room = :r AND "user" = :u
-            """,
-            r=self.id,
-            u=user.id,
-        )
+        with db.transaction():
+            query(
+                f"""
+                UPDATE user_permission_overrides
+                SET admin = FALSE
+                    {', moderator = FALSE, visible_mod = TRUE' if not remove_admin_only else ''}
+                WHERE room = :r AND "user" = :u
+                """,
+                r=self.id,
+                u=user.id,
+            )
 
-        if user.id in self._perm_cache:
-            del self._perm_cache[user.id]
+            self._refresh()
+            if user.id in self._perm_cache:
+                del self._perm_cache[user.id]
 
         app.logger.info(f"{removed_by} removed {user} as mod/admin of {self}")
 
@@ -1826,7 +1827,7 @@ def pin(self, msg_id: int, admin: User):
                 a=admin.id,
                 now=time.time(),
             )
-        self._pinned = None
+            self._refresh()
 
     def unpin_all(self, admin: User):
         """
@@ -1855,8 +1856,9 @@ def unpin_all(self, admin: User):
             if unpinned_files:
                 File.reset_expiries(unpinned_files)
 
-        if count != 0:
-            self._pinned = None
+            if count != 0:
+                self._refresh()
+
         return count
 
     def unpin(self, msg_id: int, admin: User):
@@ -1884,8 +1886,9 @@ def unpin(self, msg_id: int, admin: User):
             if unpinned_files:
                 File.reset_expiries(unpinned_files)
 
-        if count != 0:
-            self._pinned = None
+            if count != 0:
+                self._refresh()
+
         return count
 
     @property

sogs/routes/messages.py

@@ -473,7 +473,10 @@ def message_pin(room, msg_id):
 
     # Return value
 
-    On success returns a 200 status code and returns an empty JSON object as response.
+    On success returns a 200 status code and returns a JSON object as response containing keys:
+
+    - `info_updates` -- the new info_updates value of the room; a client can use this to avoid
+      race conditions with room info polling that might not yet include the updated value(s).
 
     # Error status codes
 
@@ -483,7 +486,7 @@ def message_pin(room, msg_id):
       pinning (e.g. a whisper or deleted post).
     """
     room.pin(msg_id, g.user)
-    return jsonify({})
+    return jsonify({"info_updates": room.info_updates})
 
 
 @messages.post("/room/<Room:room>/unpin/<int:msg_id>")
@@ -504,14 +507,20 @@ def message_unpin(room, msg_id):
 
     # Return value
 
-    On success returns a 200 status code and returns an empty JSON object as response body.
+    On success returns a 200 status code and returns an JSON object as response body containing
+    keys:
+
+    - `unpinned` - boolean value indicating whether the message was pinned and has now been unpinned
+      (true), or was already unpinned (false).
+    - `info_updates` - the new info_updates value for the room.  This value will only change if the
+      given message was actually pinned (i.e. it does not increment when `unpinned` is false).
 
     # Error status codes
 
     - 403 Forbidden — returned if the invoking user does not have admin permission in this room.
     """
-    room.unpin(msg_id, g.user)
-    return jsonify({})
+    count = room.unpin(msg_id, g.user)
+    return jsonify({"unpinned": count > 0, "info_updates": room.info_updates})
 
 
 @messages.post("/room/<Room:room>/unpin/all")
@@ -527,15 +536,18 @@ def message_unpin_all(room):
 
     # Return value
 
-    On success returns a 200 status code with an empty JSON object as response body.  All pinned
-    messages have been removed.
+    On success returns a 200 status code with an JSON object as response body containing keys:
+
+    - `unpinned` - count of how many pinned messages were removed.
+    - `info_updates` - new `info_updates` property for the room.  This value is only incremented by
+      this operation if at least one message was found and unpinned (i.e. if `unpinned > 0`).
 
     # Error status codes
 
     - 403 Forbidden — returned if the invoking user does not have admin permission in this room.
     """
-    room.unpin_all(g.user)
-    return jsonify({})
+    count = room.unpin_all(g.user)
+    return jsonify({"unpinned": count, "info_updates": room.info_updates})
 
 
 @messages.put("/room/<Room:room>/reaction/<int:msg_id>/<path:reaction>")

sogs/routes/rooms.py

@@ -203,7 +203,10 @@ def update_room(room):
 
     # Return value
 
-    On success this endpoint returns a 200 status code and an empty json object (`{}`) as the body.
+    On success this endpoint returns a 200 status code and a json object containing keys:
+
+    - `info_updates` -- the new info_updates value of the room; a client can use this to avoid
+      race conditions with room info polling that might not yet include the updated value(s).
 
     # Error status codes
 
@@ -276,7 +279,7 @@ def update_room(room):
             app.logger.warning("Room update: must include at least one field to update")
             abort(http.BAD_REQUEST)
 
-    return jsonify({})
+    return jsonify({"info_updates": room.info_updates})
 
 
 def addExtraPermInfo(perms):

sogs/routes/users.py

@@ -94,15 +94,15 @@ def set_mod(sid):
     - `rooms` — List of one or more room tokens to which the moderator status should be applied. The
       invoking user must be an admin of all of the given rooms.
 
-        This may be set to the single-element list ["*"] to add or remove the moderator from all
+        This may be set to the single-element list `["*"]` to add or remove the moderator from all
         rooms in which the current user has admin permissions (the call will succeed if the calling
-        user is an admin in at least one channel).
+        user is an admin in at least one room).
 
         Exclusive of `global`.
 
     - `global` — boolean value: if true then apply the change at the server-wide global level: the
-      user will be added/removed as a global moderator.  The invoking user must be a global admin in
-      order to control global mods/admins.
+      user will be added/removed as a global moderator/admin.  The invoking user must be a global
+      admin in order to control global mods/admins.
 
         Exclusive of `rooms`.
 
@@ -156,7 +156,16 @@ def set_mod(sid):
 
     # Return value
 
-    On success returns a 200 status code with an empty JSON object as body.
+    On success returns a 200 status code with JSON object as body containing keys:
+
+    - "info_updates": this is an object where each key is a room token, and each value is that
+      room's new `info_updates` value.  For a request making changes to room-level mods (i.e. using
+      the `rooms` parameter) this will be the new `info_updates` value for each of the given rooms.
+      For global moderator changes this will contain the new info_updates value of *all* rooms on
+      the server (because all rooms are updated when a global mod is added/removed).
+
+      These values can be useful to track whether possibly-concurrent room polling requests are
+      expected to have the moderator changes applied yet.
 
     # Error status codes
 
@@ -205,6 +214,8 @@ def set_mod(sid):
         if visible is None:
             visible = True
 
+        info_updates = {}
+
         with db.transaction():
             for room in rooms:
                 if (admin, mod) in ((True, None), (None, True)):
@@ -220,6 +231,8 @@ def set_mod(sid):
                     app.logger.error("Internal error: unhandled mod/admin room case")
                     raise RuntimeError("Internal error: unhandled mod/admin room case")
 
+                info_updates[room.token] = room.info_updates
+
     else:  # global mod
         if visible is None:
             visible = False
@@ -234,8 +247,9 @@ def set_mod(sid):
             with db.transaction():
                 user.remove_moderator(removed_by=g.user, remove_admin_only=True)
                 user.set_moderator(added_by=g.user, admin=bool(admin), visible=visible)
+        info_updates = {room.token: room.info_updates for room in mroom.get_rooms()}
 
-    return jsonify({})
+    return jsonify({"info_updates": info_updates})
 
 
 @users.post("/user/<AnySessionID:sid>/ban")

tests/test_room_routes.py

@@ -466,7 +466,8 @@ def test_polling(client, room, user, user2, mod, admin, global_mod, global_admin
     assert img.expiry == from_now.hours(1)
     r = sogs_put(client, f'/room/{room.token}', {'image': img.id}, admin)
     assert r.status_code == 200
-    assert r.json == dict()
+    assert r.json == {"info_updates": info_up + 1}
+
     img = File(id=img.id)
     assert img.expiry is None