add jupyter_events integration

Author: dlqqq

jupyter_server_documents/__init__.py

@@ -10,6 +10,7 @@
 
 
 from .app import ServerDocsApp
+from .events import JSD_AWARENESS_EVENT_URI, JSD_ROOM_EVENT_URI
 
 
 def _jupyter_labextension_paths():

jupyter_server_documents/app.py

@@ -7,6 +7,7 @@
 from .websockets import YRoomWebsocket
 from .rooms.yroom_manager import YRoomManager
 from .outputs import OutputsManager, outputs_handlers
+from .events import JSD_AWARENESS_EVENT_SCHEMA, JSD_ROOM_EVENT_SCHEMA
 
 class ServerDocsApp(ExtensionApp):
     name = "jupyter_server_documents"
@@ -51,6 +52,10 @@ def initialize(self):
         super().initialize()
 
     def initialize_settings(self):
+        # Register event schemas
+        self.serverapp.event_logger.register_event_schema(JSD_ROOM_EVENT_SCHEMA)
+        self.serverapp.event_logger.register_event_schema(JSD_AWARENESS_EVENT_SCHEMA)
+
         # Get YRoomManager arguments from server extension context.
         # We cannot access the 'file_id_manager' key immediately because server
         # extensions initialize in alphabetical order. 'jupyter_server_documents' <
@@ -65,10 +70,11 @@ def get_fileid_manager():
         self.settings["yroom_manager"] = YRoomManager(
             get_fileid_manager=get_fileid_manager,
             contents_manager=contents_manager,
+            event_logger=self.serverapp.event_logger,
             loop=loop,
             log=log
         )
-        
+
         # Initialize OutputsManager
         self.outputs_manager = self.outputs_manager_class(config=self.config)
         self.settings["outputs_manager"] = self.outputs_manager

jupyter_server_documents/events/__init__.py

@@ -0,0 +1,14 @@
+from pathlib import Path
+from typing import Literal
+
+EVENTS_DIR = Path(__file__).parent
+
+JSD_ROOM_EVENT_URI = "https://schema.jupyter.org/jupyter_server_documents/room/v1"
+JSD_AWARENESS_EVENT_URI = "https://schema.jupyter.org/jupyter_server_documents/awareness/v1"
+
+JSD_ROOM_EVENT_SCHEMA = EVENTS_DIR / "room.yaml"
+JSD_AWARENESS_EVENT_SCHEMA = EVENTS_DIR / "awareness.yaml"
+
+type EventLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+type RoomAction = Literal["initialize", "load", "save", "overwrite", "clean"]

jupyter_server_documents/events/awareness.yaml

@@ -0,0 +1,33 @@
+"$id": https://schema.jupyter.org/jupyter_server_documents/awareness/v1
+"$schema": "http://json-schema.org/draft-07/schema"
+version: "1"
+title: Collaborative awareness events
+personal-data: true
+description: |
+  Awareness events emitted from server-side during a collaborative session.
+type: object
+required:
+  - roomid
+  - username
+  - action
+properties:
+  roomid:
+    type: string
+    description: |
+      Room ID. Usually composed by the file type, format and ID.
+  username:
+    type: string
+    description: |
+      The name of the user who joined or left room.
+  action:
+    enum:
+      - join
+      - leave
+    description: |
+      Possible values:
+      1. join
+      2. leave
+  msg:
+    type: string
+    description: |
+      Optional event message.

jupyter_server_documents/events/room.yaml

@@ -0,0 +1,60 @@
+"$id": https://schema.jupyter.org/jupyter_server_documents/room/v1
+"$schema": "http://json-schema.org/draft-07/schema"
+version: "1"
+title: Room events
+personal-data: true
+description: |
+  An event emitted by a collaboration room.
+type: object
+required:
+  - level
+  - room
+  - path
+properties:
+  level:
+    enum:
+      - INFO
+      - DEBUG
+      - WARNING
+      - ERROR
+      - CRITICAL
+    description: |
+      Message type.
+  room:
+    type: string
+    description: |
+      Room ID. This is a composite ID that takes the format `{file_type}:{file_format}:{file_id}`.
+  path:
+    type: string
+    description: |
+      Path of the file.
+  store:
+    type: string
+    description: |
+      The store used to track the document history.
+  action:
+    enum:
+      - initialize
+      - load
+      - save
+      - overwrite
+      - clean
+    description: |
+      Action performed in a room during a collaborative session.
+      Possible values:
+      1. initialize
+         Initialize a room by loading the content from the contents manager or a store.
+      2. load
+         Load the content from the contents manager.
+      3. save
+         Save the content with the contents manager.
+      4. overwrite
+         Overwrite the content in a room with content from the contents manager.
+         This can happen when multiple rooms access the same file or when a user
+         modifies the file outside Jupyter Server (e.g. using a different app).
+      5. clean
+         Clean the room once is empty (aka there is no more users connected to it).
+  msg:
+    type: string
+    description: |
+      Event message.

jupyter_server_documents/rooms/yroom.py

@@ -8,8 +8,10 @@
 from pycrdt import YMessageType, YSyncMessageType as YSyncMessageSubtype
 from jupyter_server_documents.ydocs import ydocs as jupyter_ydoc_classes
 from jupyter_ydoc.ybasedoc import YBaseDoc
+from jupyter_events import EventLogger
 from tornado.websocket import WebSocketHandler
 from .yroom_file_api import YRoomFileAPI
+from .yroom_events_api import YRoomEventsAPI
 
 if TYPE_CHECKING:
     from typing import Literal, Tuple, Any
@@ -32,7 +34,7 @@ class YRoom:
 
     file_api: YRoomFileAPI | None
     """
-    The `YRoomFileAPI` instance for this room. This is set to `None` if & only
+    The `YRoomFileAPI` instance for this room. This is set to `None` only
     if `self.room_id == "JupyterLab:globalAwareness"`.
 
     The file API provides `load_ydoc_content()` for loading the YDoc content
@@ -41,8 +43,16 @@ class YRoom:
     out-of-band changes.
     """
 
+    events_api: YRoomEventsAPI | None
+    """
+    A `YRoomEventsAPI` instance for this room that provides methods for emitting
+    events through the `jupyter_events.EventLogger` singleton. This is set to
+    `None` only if `self.room_id == "JupyterLab:globalAwareness"`.
+    """
+
     _jupyter_ydoc: YBaseDoc | None
     """JupyterYDoc"""
+
     _ydoc: pycrdt.Doc
     """Ydoc"""
     _awareness: pycrdt.Awareness
@@ -78,6 +88,7 @@ def __init__(
         loop: asyncio.AbstractEventLoop,
         fileid_manager: BaseFileIdManager,
         contents_manager: AsyncContentsManager | ContentsManager,
+        event_logger: EventLogger
     ):
         # Bind instance attributes
         self.room_id = room_id
@@ -91,14 +102,18 @@ def __init__(
         self._ydoc = pycrdt.Doc()
         self._awareness = pycrdt.Awareness(ydoc=self._ydoc)
 
-        # If this room is providing global awareness, set `file_api` and
-        # `_jupyter_ydoc` to `None` as the YDoc is unused.
+        # If this room is providing global awareness, set unused optional
+        # attributes to `None`.
         if self.room_id == "JupyterLab:globalAwareness":
             self.file_api = None
             self._jupyter_ydoc = None
+            self.events_api = None
         else:
-            # Otherwise, initialize `_jupyter_ydoc` and `file_api`.
+            # Otherwise, initialize optional attributes for document rooms
+            # Initialize JupyterYDoc
             self._jupyter_ydoc = self._init_jupyter_ydoc()
+
+            # Initialize YRoomFileAPI, start loading content
             self.file_api = YRoomFileAPI(
                 room_id=self.room_id,
                 jupyter_ydoc=self._jupyter_ydoc,
@@ -108,12 +123,18 @@ def __init__(
                 contents_manager=self._contents_manager,
                 on_outofband_change=self.reload_ydoc
             )
-
-            # Load the YDoc content after initializing
             self.file_api.load_ydoc_content()
 
             # Attach Jupyter YDoc observer to automatically save on change
             self._jupyter_ydoc.observe(self._on_jupyter_ydoc_update)
+
+            # Initialize YRoomEventsAPI
+            self.events_api = YRoomEventsAPI(
+                event_logger=event_logger,
+                fileid_manager=fileid_manager,
+                room_id=self.room_id,
+                log=self.log,
+            )
 
         # Start observers on `self.ydoc` and `self.awareness` to ensure new
         # updates are always broadcast to all clients.
@@ -131,6 +152,18 @@ def __init__(
 
         # Log notification that room is ready
         self.log.info(f"Room '{self.room_id}' initialized.")
+
+        # Emit events if defined
+        if self.events_api:
+            # Emit 'initialize' event
+            self.events_api.emit_room_event("initialize")
+
+            # Emit 'load' event once content is loaded
+            assert self.file_api
+            async def emit_load_event():
+                await self.file_api.ydoc_content_loaded.wait()
+                self.events_api.emit_room_event("load")
+            self._loop.create_task(emit_load_event())
 
 
     def _init_jupyter_ydoc(self) -> YBaseDoc:
@@ -154,7 +187,7 @@ def _init_jupyter_ydoc(self) -> YBaseDoc:
             jupyter_ydoc_classes.get(file_type, jupyter_ydoc_classes["file"])
         )
 
-        # Initialize Jupyter YDoc, add an observer to save it on change, return
+        # Initialize Jupyter YDoc and return it
         jupyter_ydoc = JupyterYDocClass(ydoc=self._ydoc, awareness=self._awareness)
         return jupyter_ydoc
 
@@ -602,6 +635,10 @@ def reload_ydoc(self) -> None:
         )
         self._jupyter_ydoc.observe(self._on_jupyter_ydoc_update)
 
+        # Emit 'overwrite' event as the YDoc content has been overwritten
+        if self.events_api:
+            self.events_api.emit_room_event("overwrite")
+
 
     async def stop(self) -> None:
         """

jupyter_server_documents/rooms/yroom_events_api.py

@@ -0,0 +1,73 @@
+from jupyter_events import EventLogger
+from ..events import JSD_ROOM_EVENT_URI, EventLevel, RoomAction
+from typing import Optional
+from jupyter_server_fileid.manager import BaseFileIdManager
+from logging import Logger
+
+
+class YRoomEventsAPI:
+    """
+    Class that provides an API to emit events to the
+    `jupyter_events.EventLogger` singleton in `jupyter_server`.
+
+    JSD room and awareness events have the same structure as
+    `jupyter_collaboration` v4 session and awareness events. The only difference
+    is that JSD emits to a different schema ID/URI. This is defined in the `$id`
+    property of the corresponding event schema.
+
+    The event schemas must be registered via
+    `event_logger.register_event_schema()` in advance. This should be done when
+    the server extension initializes.
+    """
+
+    _event_logger: EventLogger
+    _fileid_manager: BaseFileIdManager
+    room_id: str
+    log: Logger
+
+    def __init__(self, event_logger: EventLogger, fileid_manager: BaseFileIdManager, room_id: str, log: Logger):
+        self._event_logger = event_logger
+        self._fileid_manager = fileid_manager
+        self.room_id = room_id
+        self.log = log
+    
+    def emit_room_event(
+        self,
+        action: RoomAction,
+        level: Optional[EventLevel] = "INFO"
+    ):
+        """
+        Emits a room event. This method is guaranteed to log any caught
+        exceptions and never raise them to the `YRoom`.
+        """
+        try:
+            path = self._get_path()
+            event_data = {
+                "level": level,
+                "room": self.room_id,
+                "path": path,
+                "action": action
+            }
+            self._event_logger.emit(schema_id=JSD_ROOM_EVENT_URI, data=event_data)
+        except:
+            self.log.exception("Exception occurred when emitting a room event.")
+
+    def emit_awareness_event(self):
+        """
+        TODO
+        """
+        pass
+
+
+    def _get_path(self) -> str:
+        """
+        Returns the relative path to the file by querying the FileIdManager. The
+        path is relative to the `ServerApp.root_dir` configurable trait.
+        """
+        # Query for the path from the file ID in the room ID
+        file_id = self.room_id.split(":")[-1]
+        rel_path = self._fileid_manager.get_path(file_id)
+
+        # Raise exception if the path could not be found, then return
+        assert rel_path is not None
+        return rel_path

jupyter_server_documents/rooms/yroom_manager.py

@@ -8,6 +8,7 @@
     import logging
     from jupyter_server_fileid.manager import BaseFileIdManager
     from jupyter_server.services.contents.manager import AsyncContentsManager, ContentsManager
+    from jupyter_events import EventLogger
 
 class YRoomManager():
     _rooms_by_id: dict[str, YRoom]
@@ -17,12 +18,14 @@ def __init__(
         *,
         get_fileid_manager: callable[[], BaseFileIdManager],
         contents_manager: AsyncContentsManager | ContentsManager,
+        event_logger: EventLogger,
         loop: asyncio.AbstractEventLoop,
         log: logging.Logger,
     ):
         # Bind instance attributes
         self._get_fileid_manager = get_fileid_manager
         self.contents_manager = contents_manager
+        self.event_logger = event_logger
         self.loop = loop
         self.log = log
 
@@ -54,6 +57,7 @@ def get_room(self, room_id: str) -> YRoom | None:
                 loop=self.loop,
                 fileid_manager=self.fileid_manager,
                 contents_manager=self.contents_manager,
+                event_logger=self.event_logger,
             )
             self._rooms_by_id[room_id] = yroom
             return yroom