Add compatibility with Jupyter Collaboration v4 (#106)

* standardize labextension plugin IDs

* disable jupyter_collaboration extensions thru metadata

* fix missing plugin error, now works w/ JCollab4

* add new JCollab 4 + JSD dev env, remove old ones

* add jupyter_events integration

* fix wrong room_id doc comment

* add JCollab Python API

* use same event schema IDs as jupyter_collaboration

* fix JAI compatibility issue

* remove custom type only supported in Py >3.12

Author: dlqqq

devenv-jcollab-backend.yml

@@ -0,0 +1,11 @@
+name: serverdocs-jcollab
+channels:
+  - conda-forge
+dependencies:
+  - python
+  - nodejs=22
+  - uv
+  - jupyterlab
+  - pip:
+      - jupyterlab>=4.4.0,<5.0.0
+      - jupyter_collaboration~=4.0

devenv-jcollab-frontend.yml

@@ -1,7 +1,8 @@
 {
   "ServerApp": {
     "jpserver_extensions": {
-      "jupyter_server_documents": true
+      "jupyter_server_documents": true,
+      "jupyter_server_ydoc": false
     }
   }
 }

devenv-jcollab.yml

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

jupyter-config/server-config/jupyter_server_documents.json

@@ -7,6 +7,8 @@
 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
+from .jcollab_api import JCollabAPI
 
 class ServerDocsApp(ExtensionApp):
     name = "jupyter_server_documents"
@@ -51,6 +53,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,13 +71,22 @@ 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
+
+        # Serve Jupyter Collaboration API on
+        # `self.settings["jupyter_server_ydoc"]` for compatibility with
+        # extensions depending on Jupyter Collaboration
+        self.settings["jupyter_server_ydoc"] = JCollabAPI(
+            get_fileid_manager=get_fileid_manager,
+            yroom_manager=self.settings["yroom_manager"]
+        )
 
     def _link_jupyter_server_extension(self, server_app):
         """Setup custom config needed by this extension."""

jupyter_server_documents/__init__.py

@@ -0,0 +1,10 @@
+from pathlib import Path
+
+EVENTS_DIR = Path(__file__).parent
+
+# Use the same schema ID as `jupyter_collaboration` for compatibility
+JSD_ROOM_EVENT_URI = "https://schema.jupyter.org/jupyter_collaboration/session/v1"
+JSD_AWARENESS_EVENT_URI = "https://schema.jupyter.org/jupyter_collaboration/awareness/v1"
+
+JSD_ROOM_EVENT_SCHEMA = EVENTS_DIR / "room.yaml"
+JSD_AWARENESS_EVENT_SCHEMA = EVENTS_DIR / "awareness.yaml"

jupyter_server_documents/app.py

@@ -0,0 +1,33 @@
+"$id": https://schema.jupyter.org/jupyter_collaboration/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/__init__.py

@@ -0,0 +1,60 @@
+"$id": https://schema.jupyter.org/jupyter_collaboration/session/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_format}:{file_type}:{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/events/awareness.yaml

@@ -0,0 +1 @@
+from .jcollab_api import JCollabAPI