Add manager for tracking and terminating running server proxies

docs/requirements.txt

@@ -2,5 +2,6 @@ myst-parser
 sphinx-autobuild
 sphinx-book-theme
 sphinx-copybutton
+sphinxcontrib-openapi
 sphinxext-opengraph
 sphinxext-rediraffe

docs/source/api.rst

@@ -0,0 +1,8 @@
+.. _api:
+
+=============
+REST API
+=============
+
+.. openapi:: ../../jupyter_server_proxy/api.yml
+    :examples:

docs/source/conf.py

@@ -23,9 +23,10 @@
     "sphinx_copybutton",
     "sphinxext.opengraph",
     "sphinxext.rediraffe",
+    "sphinxcontrib.openapi",
 ]
 root_doc = "index"
-source_suffix = [".md"]
+source_suffix = [".md", ".rst"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 

docs/source/index.md

@@ -30,6 +30,7 @@ install
 server-process
 launchers
 arbitrary-ports-hosts
+api
 ```
 
 ## Convenience packages for popular applications

docs/source/launchers.md

@@ -27,3 +27,36 @@ buttons in JupyterLab's Launcher panel for registered server processes.
 ```
 
 Clicking on them opens the proxied application in a new browser window.
+
+Currently running proxy applications are shown in the running sessions tab
+under "Server Proxy Apps" section.
+
+```{image} _static/images/labextension-manager.gif
+
+```
+
+As shown in the GIF, users can consult the metadata of each running proxy
+application by hovering over the name of the proxy. It is also possible to
+terminate the proxy application using Shut Down button.
+
+```{note}
+When the user clicks Shut Down button to terminate a proxy application,
+a `SIGTERM` signal is sent to the application. It is the user's responsibility
+to ensure that the application exits cleanly with a `SIGTERM` signal. There
+are certain applications (like MLflow) that cannot be terminted with `SIGTERM`
+signal and in those cases, the users can setup wrapper scripts to trap the
+signal and ensure clean teardown of the application.
+```
+
+The lab extension manager will poll for running proxy applications at a
+given interval which can be configured using Jupyter Server Proxy settings.
+By default this is set to 10 seconds. Users can change
+this interval by changing `Auto-refresh rate` in `Jupyter Server Proxy`
+section in `Advanced Settings Editor` in JupyterLab UI.
+
+```{image} _static/images/labextension-settings.png
+
+```
+
+Only proxy applications that are started by `jupyter-server-proxy` are shown
+in the running Server Proxy Apps section.

jupyter_server_proxy/__init__.py

@@ -1,9 +1,10 @@
-from jupyter_server.utils import url_path_join as ujoin
+import traitlets
 
-from .api import IconHandler, ServersInfoHandler
+from .api import setup_api_handlers
 from .config import ServerProxy as ServerProxyConfig
 from .config import get_entrypoint_server_processes, make_handlers, make_server_process
 from .handlers import setup_handlers
+from .manager import ServerProxyAppManager
 
 
 # Jupyter Extension points
@@ -38,14 +39,31 @@ def _jupyter_labextension_paths():
 def _load_jupyter_server_extension(nbapp):
     # Set up handlers picked up via config
     base_url = nbapp.web_app.settings["base_url"]
+
+    # Add server_proxy_manager trait to ServerApp and Instantiate a manager
+    nbapp.add_traits(server_proxy_manager=traitlets.Instance(ServerProxyAppManager))
+    manager = nbapp.server_proxy_manager = ServerProxyAppManager()
     serverproxy_config = ServerProxyConfig(parent=nbapp)
 
+    # Add a long running background task that monitors the running proxies
+    try:
+        nbapp.io_loop.call_later(
+            serverproxy_config.monitor_interval,
+            manager.monitor,
+            serverproxy_config.monitor_interval,
+        )
+    except AttributeError:
+        nbapp.log.debug(
+            "[jupyter-server-proxy] Server proxy manager is only supportted "
+            "for Notebook >= 7",
+        )
+
     server_processes = [
         make_server_process(name, server_process_config, serverproxy_config)
         for name, server_process_config in serverproxy_config.servers.items()
     ]
     server_processes += get_entrypoint_server_processes(serverproxy_config)
-    server_handlers = make_handlers(base_url, server_processes)
+    server_handlers = make_handlers(base_url, manager, server_processes)
     nbapp.web_app.add_handlers(".*", server_handlers)
 
     # Set up default non-server handler
@@ -54,21 +72,10 @@ def _load_jupyter_server_extension(nbapp):
         serverproxy_config,
     )
 
-    icons = {}
-    for sp in server_processes:
-        if sp.launcher_entry.enabled and sp.launcher_entry.icon_path:
-            icons[sp.name] = sp.launcher_entry.icon_path
-
-    nbapp.web_app.add_handlers(
-        ".*",
-        [
-            (
-                ujoin(base_url, "server-proxy/servers-info"),
-                ServersInfoHandler,
-                {"server_processes": server_processes},
-            ),
-            (ujoin(base_url, "server-proxy/icon/(.*)"), IconHandler, {"icons": icons}),
-        ],
+    setup_api_handlers(
+        nbapp.web_app,
+        manager,
+        server_processes,
     )
 
     nbapp.log.debug(

jupyter_server_proxy/api.py

@@ -1,4 +1,4 @@
-import mimetypes
+import json
 
 from jupyter_server.base.handlers import JupyterHandler
 from jupyter_server.utils import url_path_join as ujoin
@@ -34,39 +34,94 @@ async def get(self):
         self.write({"server_processes": data})
 
 
-# FIXME: Should be a StaticFileHandler subclass
-class IconHandler(JupyterHandler):
-    """
-    Serve launcher icons
-    """
+# IconHandler has been copied from JupyterHub's IconHandler:
+# https://github.com/jupyterhub/jupyterhub/blob/4.0.0b2/jupyterhub/handlers/static.py#L22-L31
+class ServersIconHandler(web.StaticFileHandler):
+    """A singular handler for serving the icon."""
 
-    def initialize(self, icons):
-        """
-        icons is a dict of titles to paths
-        """
-        self.icons = icons
+    def get(self):
+        return super().get("")
 
+    @classmethod
+    def get_absolute_path(cls, root, path):
+        """We only serve one file, ignore relative path"""
+        import os
+
+        return os.path.abspath(root)
+
+
+class ServersAPIHandler(JupyterHandler):
+    """Handler to get metadata or terminate of a given server or all servers"""
+
+    def initialize(self, manager):
+        self.manager = manager
+
+    @web.authenticated
+    async def delete(self, name):
+        """Delete a server proxy by name"""
+        if not name:
+            raise web.HTTPError(
+                403,
+                "Please set the name of a running server proxy that "
+                "user wishes to terminate",
+            )
+
+        try:
+            val = await self.manager.terminate_server_proxy_app(name)
+            if val is None:
+                raise Exception(
+                    f"Proxy {name} not found. Are you sure the {name} "
+                    f"is managed by jupyter-server-proxy?"
+                )
+            else:
+                self.set_status(204)
+                self.finish()
+        except Exception as e:
+            raise web.HTTPError(404, str(e))
+
+    @web.authenticated
     async def get(self, name):
-        if name not in self.icons:
-            raise web.HTTPError(404)
-        path = self.icons[name]
-
-        # Guess mimetype appropriately
-        # Stolen from https://github.com/tornadoweb/tornado/blob/b399a9d19c45951e4561e6e580d7e8cf396ef9ff/tornado/web.py#L2881
-        mime_type, encoding = mimetypes.guess_type(path)
-        if encoding == "gzip":
-            content_type = "application/gzip"
-        # As of 2015-07-21 there is no bzip2 encoding defined at
-        # http://www.iana.org/assignments/media-types/media-types.xhtml
-        # So for that (and any other encoding), use octet-stream.
-        elif encoding is not None:
-            content_type = "application/octet-stream"
-        elif mime_type is not None:
-            content_type = mime_type
-        # if mime_type not detected, use application/octet-stream
+        """Get meta data of a running server proxy"""
+        if name:
+            apps = self.manager.get_server_proxy_app(name)._asdict()
+            # If no server proxy found this will be a dict with empty values
+            if not apps["name"]:
+                raise web.HTTPError(404, f"Server proxy {name} not found")
         else:
-            content_type = "application/octet-stream"
+            apps = [app._asdict() for app in self.manager.list_server_proxy_apps()]
+
+        self.set_status(200)
+        self.finish(json.dumps(apps))
+
+
+def setup_api_handlers(web_app, manager, server_processes):
+    base_url = web_app.settings["base_url"]
+
+    # Make a list of icon handlers
+    icon_handlers = []
+    for sp in server_processes:
+        if sp.launcher_entry.enabled and sp.launcher_entry.icon_path:
+            icon_handlers.append(
+                (
+                    ujoin(base_url, f"server-proxy/icon/{sp.name}"),
+                    ServersIconHandler,
+                    {"path": sp.launcher_entry.icon_path},
+                )
+            )
 
-        with open(self.icons[name]) as f:
-            self.write(f.read())
-        self.set_header("Content-Type", content_type)
+    web_app.add_handlers(
+        ".*",
+        [
+            (
+                ujoin(base_url, "server-proxy/api/servers-info"),
+                ServersInfoHandler,
+                {"server_processes": server_processes},
+            ),
+            (
+                ujoin(base_url, r"server-proxy/api/servers/(?P<name>.*)"),
+                ServersAPIHandler,
+                {"manager": manager},
+            ),
+        ]
+        + icon_handlers,
+    )