Add a simple REST API for fetching a file's ID (#72)

* add a simple REST API for fetching a file's ID

* add missing dependency in tests

* Split into two endpoints after code review

* Check the error message in the unit tests

Author: Zsailer

conftest.py

@@ -1 +1,5 @@
-pytest_plugins = ["jupyter_server.pytest_plugin", "jupyter_server_fileid.pytest_plugin"]
+pytest_plugins = [
+    "jupyter_server.pytest_plugin",
+    "jupyter_server_fileid.pytest_plugin",
+    "pytest_jupyter",
+]

jupyter_server_fileid/extension.py

@@ -1,7 +1,8 @@
 from jupyter_events.logger import EventLogger
 from jupyter_server.extension.application import ExtensionApp
-from traitlets import Type
+from traitlets import Instance, Type
 
+from jupyter_server_fileid.handler import FileIDHandler, FilePathHandler
 from jupyter_server_fileid.manager import ArbitraryFileIdManager, BaseFileIdManager
 
 
@@ -10,28 +11,33 @@ class FileIdExtension(ExtensionApp):
 
     file_id_manager_class = Type(
         klass=BaseFileIdManager,
-        help="""File ID manager instance to use.
+        help="""File ID manager class to use.
 
         Defaults to ArbitraryFileIdManager.
         """,
         config=True,
         default_value=ArbitraryFileIdManager,
     )
 
+    file_id_manager = Instance(
+        klass=BaseFileIdManager, help="An instance of the File ID manager.", allow_none=True
+    )
+
+    handlers = [("/api/fileid/id", FileIDHandler), ("/api/fileid/path", FilePathHandler)]
+
     def initialize_settings(self):
         self.log.info(f"Configured File ID manager: {self.file_id_manager_class.__name__}")
-        file_id_manager = self.file_id_manager_class(
+        self.file_id_manager = self.file_id_manager_class(
             log=self.log, root_dir=self.serverapp.root_dir, config=self.config
         )
-        self.settings.update({"file_id_manager": file_id_manager})
+        self.settings.update({"file_id_manager": self.file_id_manager})
 
         # attach listener to contents manager events (requires jupyter_server~=2)
         if "event_logger" in self.settings:
             self.initialize_event_listeners()
 
     def initialize_event_listeners(self):
-        file_id_manager = self.settings["file_id_manager"]
-        handlers_by_action = file_id_manager.get_handlers_by_action()
+        handlers_by_action = self.file_id_manager.get_handlers_by_action()
 
         async def cm_listener(logger: EventLogger, schema_id: str, data: dict) -> None:
             handler = handlers_by_action[data["action"]]

jupyter_server_fileid/handler.py

@@ -0,0 +1,61 @@
+from jupyter_server.auth.decorator import authorized
+from jupyter_server.base.handlers import APIHandler
+from tornado import web
+from tornado.escape import json_encode
+
+from .manager import BaseFileIdManager
+
+
+class BaseHandler(APIHandler):
+    auth_resource = "contents"
+
+    @property
+    def file_id_manager(self) -> BaseFileIdManager:
+        return self.settings.get("file_id_manager")
+
+
+class FileIDHandler(BaseHandler):
+    """A handler that fetches a file ID from the file path."""
+
+    @web.authenticated
+    @authorized
+    def get(self):
+        try:
+            path = self.get_argument("path")
+            id = self.file_id_manager.get_id(path)
+            # If the path cannot be found, it returns None. Raise a helpful
+            # error to the client.
+            if id is None:
+                raise web.HTTPError(
+                    404,
+                    log_message=f"The ID for file, {path}, could not be found.",
+                    reason=f"The ID for file, {path}, could not be found.",
+                )
+            self.write(json_encode({"id": id, "path": path}))
+        except web.MissingArgumentError:
+            raise web.HTTPError(
+                400, log_message="'path' parameter was not provided in the request."
+            )
+
+
+class FilePathHandler(BaseHandler):
+    """A handler that fetches a file path from the file ID."""
+
+    @web.authenticated
+    @authorized
+    def get(self):
+        try:
+            id = self.get_argument("id")
+            path = self.file_id_manager.get_path(id)
+            # If the ID cannot be found, it returns None. Raise a helpful
+            # error to the client.
+            if path is None:
+                error_msg = f"The path for file, {id}, could not be found."
+                raise web.HTTPError(
+                    404,
+                    log_message=error_msg,
+                    reason=error_msg,
+                )
+            self.write(json_encode({"id": id, "path": path}))
+        except web.MissingArgumentError:
+            raise web.HTTPError(400, log_message="'id' parameter was not provided in the request.")

pyproject.toml

@@ -29,6 +29,7 @@ dependencies = [
 test = [
   "pytest",
   "pytest-cov",
+  "pytest-jupyter",
   "jupyter_server[test]>=1.15, <3"
 ]
 

tests/test_handler.py

@@ -0,0 +1,91 @@
+from unittest.mock import MagicMock
+
+import pytest
+from tornado.escape import json_decode
+from tornado.httpclient import HTTPClientError
+
+from jupyter_server_fileid.manager import BaseFileIdManager
+
+
+class MockFileIdManager(BaseFileIdManager):
+    _normalize_path = MagicMock()
+    _from_normalized_path = MagicMock()
+    index = MagicMock()
+    move = MagicMock()
+    copy = MagicMock()
+    delete = MagicMock()
+    save = MagicMock()
+    get_handlers_by_action = MagicMock()
+    get_path = MagicMock(return_value="mock_path")
+    get_id = MagicMock(return_value="mock_id")
+
+
+@pytest.fixture
+def jp_server_config():
+    yield {
+        "ServerApp": {"jpserver_extensions": {"jupyter_server_fileid": True}},
+        "FileIdExtension": {"file_id_manager_class": MockFileIdManager},
+    }
+
+
+@pytest.fixture
+def file_id_extension(jp_serverapp):
+    ext_pkg = jp_serverapp.extension_manager.extensions["jupyter_server_fileid"]
+    ext_point = ext_pkg.extension_points["jupyter_server_fileid"]
+    return ext_point.app
+
+
+async def test_file_id_handler(jp_fetch, file_id_extension):
+    response = await jp_fetch("api/fileid/id", params={"path": "test"})
+    file_id_extension.file_id_manager.get_id.assert_called_once()
+    body = json_decode(response.body)
+    assert "id" in body
+    assert body["id"] == "mock_id"
+
+
+async def test_file_path_handler(jp_fetch, file_id_extension):
+    response = await jp_fetch("api/fileid/path", params={"id": "test"})
+    file_id_extension.file_id_manager.get_path.assert_called_once()
+    body = json_decode(response.body)
+    assert "path" in body
+    assert body["path"] == "mock_path"
+
+
+async def test_missing_query_param_in_id_handler(jp_fetch):
+    with pytest.raises(HTTPClientError) as err:
+        response = await jp_fetch("api/fileid/id")
+
+    assert err.value.code == 400
+
+
+async def test_missing_query_param_in_path_handler(jp_fetch):
+    with pytest.raises(HTTPClientError) as err:
+        response = await jp_fetch("api/fileid/path")
+
+    assert err.value.code == 400
+
+
+async def test_resource_not_found_in_id_handler(jp_fetch, monkeypatch):
+    def mock_get_id_with_no_entry(self, path):
+        return None
+
+    monkeypatch.setattr(MockFileIdManager, "get_id", mock_get_id_with_no_entry)
+
+    with pytest.raises(HTTPClientError) as err:
+        await jp_fetch("api/fileid/id", params={"path": "test"})
+
+    assert err.value.code == 404
+    assert err.value.message.startswith("The ID for file")
+
+
+async def test_resource_not_found_in_path_handler(jp_fetch, monkeypatch):
+    def mock_get_path_with_no_entry(self, id):
+        return None
+
+    monkeypatch.setattr(MockFileIdManager, "get_path", mock_get_path_with_no_entry)
+
+    with pytest.raises(HTTPClientError) as err:
+        await jp_fetch("api/fileid/path", params={"id": "test"})
+
+    assert err.value.code == 404
+    assert err.value.message.startswith("The path for file")