restart inactive rooms instead of deleting

Author: dlqqq

jupyter_server_documents/rooms/yroom.py

@@ -76,12 +76,17 @@ class YRoom:
     _ydoc_subscription: pycrdt.Subscription
     """Subscription to YDoc changes."""
 
-    _stopped: bool = False
+    _stopped: bool
     """
     Whether the YRoom is stopped. Set to `True` when `stop()` is called and set
     to `False` when `restart()` is called.
     """
 
+    _updated: bool
+    """
+    See `self.updated` for more info.
+    """
+
     _fileid_manager: BaseFileIdManager
     _contents_manager: AsyncContentsManager | ContentsManager
 
@@ -103,6 +108,7 @@ def __init__(
         self._fileid_manager = fileid_manager
         self._contents_manager = contents_manager
         self._stopped = False
+        self._updated = False
 
         # Initialize YjsClientGroup, YDoc, and Awareness
         self._client_group = YjsClientGroup(room_id=room_id, log=self.log, loop=self._loop)
@@ -511,8 +517,9 @@ def _on_jupyter_ydoc_update(self, updated_key: str, event: Any) -> None:
             map_event = cast(pycrdt.MapEvent, event)
             if should_ignore_state_update(map_event):
                 return
-
-        # Otherwise, save the file
+        
+        # Otherwise, a change was made. Set `updated=True` and save the file
+        self._updated = True
         self.file_api.schedule_save()
 
 
@@ -663,6 +670,8 @@ def stop(self, close_code: int = 1001, immediately: bool = False):
         - Clears the YDoc, Awareness, and JupyterYDoc, freeing their memory to
         the server. This deletes the YDoc history.
         """
+        self.log.info(f"Stopping YRoom '{self.room_id}'.")
+
         # Disconnect all clients with the given close code
         self.clients.stop(close_code=close_code)
 
@@ -734,6 +743,17 @@ def stopped(self) -> bool:
         """
         return self._stopped
 
+    @property
+    def updated(self) -> bool:
+        """
+        Returns whether the room has been updated since the last restart, or
+        since initialization if the room was not restarted.
+
+        This initializes to `False` and is set to `True` whenever a meaningful
+        update that needs to be saved occurs. This is reset to `False` when
+        `restart()` is called.
+        """
+        return self._updated
 
     def restart(self, close_code: int = 1001, immediately: bool = False):
         """
@@ -745,10 +765,13 @@ def restart(self, close_code: int = 1001, immediately: bool = False):
         immediately)` with the given arguments. Otherwise, `close_code` and
         `immediately` are ignored.
         """
-        # Stop if not stopped already, then reset `stopped` state
+        # Stop if not stopped already
         if not self._stopped:
             self.stop(close_code=close_code, immediately=immediately)
+        
+        # Reset internal state
         self._stopped = False
+        self._updated = False
 
         # Restart client group
         self.clients.restart()
@@ -759,6 +782,8 @@ def restart(self, close_code: int = 1001, immediately: bool = False):
 
         # Restart `_process_message_queue()` task
         self._loop.create_task(self._process_message_queue())
+
+        self.log.info(f"Restarted YRoom '{self.room_id}'.")
 
 
 def should_ignore_state_update(event: pycrdt.MapEvent) -> bool:

jupyter_server_documents/rooms/yroom_file_api.py

@@ -396,7 +396,6 @@ def stop(self) -> None:
         To save the YDoc after stopping, call `await
         file_api.save_immediately()` after calling this method.
         """
-        self.log.info(f"Stopping FileAPI for room '{self.room_id}'.")
         if self._watch_file_task:
             self._watch_file_task.cancel()
         self._stopped = True

jupyter_server_documents/rooms/yroom_manager.py

@@ -12,15 +12,17 @@
 
 class YRoomManager():
     """
-    A singleton that manages all `YRoom` instances in the server extension. This
-    automatically stops `YRoom` instances if they have had no connected clients
-    or active kernel for >10 seconds.
+    A singleton that manages all `YRoom` instances in the server extension.
+
+    This manager automatically restarts updated `YRoom` instances if they have
+    had no connected clients or active kernel for >10 seconds. This deletes the
+    YDoc history to free its memory to the server.
     """
 
     _rooms_by_id: dict[str, YRoom]
     """
     Dictionary of active `YRoom` instances, keyed by room ID. Rooms are never
-    deleted from this dictionary, even if stopped due to inactivity.
+    deleted from this dictionary.
 
     TODO: Delete a room if its file was deleted in/out-of-band or moved
     out-of-band. See #116.
@@ -30,8 +32,7 @@ class YRoomManager():
     """
     Set of room IDs that were marked inactive on the last iteration of
     `_watch_rooms()`. If a room is inactive and its ID is present in this set,
-    then the room the room should be stopped as it has been inactive for >10
-    seconds.
+    then the room should be restarted as it has been inactive for >10 seconds.
     """
 
     _get_fileid_manager: callable[[], BaseFileIdManager]
@@ -79,8 +80,7 @@ def get_room(self, room_id: str) -> YRoom | None:
         not exist, this method will initialize one and return it. Otherwise,
         this method returns the instance from its cache.
         """
-        # First, ensure this room stays open for >10 seconds by removing it from
-        # the inactive set of rooms if it is present.
+        # First, ensure the room is not considered inactive.
         self._inactive_rooms.discard(room_id)
 
         # If room exists, return the room
@@ -144,14 +144,16 @@ def delete_room(self, room_id: str) -> None:
     async def _watch_rooms(self) -> None:
         """
         Background task that checks all `YRoom` instances every 10 seconds,
-        stopping any rooms that have been inactive for >10 seconds.
+        restarting any updated rooms that have been inactive for >10 seconds.
+        This frees the memory occupied by the room's YDoc history, discarding it
+        in the process.
 
-        - For rooms providing notebooks: This task stops the room if it has no
-        connected clients and its kernel execution status is either 'idle' or
-        'dead'.
+        - For rooms providing notebooks: This task restarts the room if it has
+        been updated, has no connected clients, and its kernel execution status
+        is either 'idle' or 'dead'.
 
-        - For all other rooms: This task stops the room if it has no connected
-        clients.
+        - For all other rooms: This task restarts the room if it has been
+        updated and has no connected clients.
         """
         while True:
             # Check every 10 seconds
@@ -161,7 +163,7 @@ async def _watch_rooms(self) -> None:
             room_ids = set(self._rooms_by_id.keys())
             room_ids.discard("JupyterLab:globalAwareness")
 
-            # Iterate through all rooms. If any rooms are empty, stop the room.
+            # Check all rooms and restart it if inactive for >10 seconds.
             for room_id in room_ids:
                 self._check_room(room_id)
 
@@ -170,12 +172,15 @@ def _check_room(self, room_id: str) -> None:
         """
         Checks a room for inactivity.
 
+        - Rooms that have not been updated are not restarted, as there is no
+        YDoc history to free.
+
         - If a room is inactive and not in `_inactive_rooms`, this method adds
         the room to `_inactive_rooms`. 
 
         - If a room is inactive and is listed in `_inactive_rooms`, this method
-        stops the room, as it has been inactive for 2 consecutive iterations of
-        `_watch_rooms()`.
+        restarts the room, as it has been inactive for 2 consecutive iterations
+        of `_watch_rooms()`.
         """
         # Do nothing if the room has any connected clients.
         room = self._rooms_by_id[room_id]
@@ -192,15 +197,22 @@ def _check_room(self, room_id: str) -> None:
         if execution_state not in { "idle", "dead", None }:
             self._inactive_rooms.discard(room_id)
             return
+        
+        # Do nothing if the room has not been updated. This prevents empty rooms
+        # from being restarted every 10 seconds.
+        if not room.updated:
+            self._inactive_rooms.discard(room_id)
+            return
 
-        # The room is inactive if this line is reached.
-        # Stop the room if was marked as inactive in the last iteration,
+        # The room is updated (with history) & inactive if this line is reached.
+        # Restart the room if was marked as inactive in the last iteration,
         # otherwise mark it as inactive.
         if room_id in self._inactive_rooms:
             self.log.info(
-                f"YRoom '{room_id}' has been inactive for >10 seconds. "
+                f"Room '{room_id}' has been inactive for >10 seconds. "
+                "Restarting the room to free memory occupied by its history."
             )
-            room.stop()
+            room.restart()
             self._inactive_rooms.discard(room_id)
         else:
             self._inactive_rooms.add(room_id)