WIP: Entrypoint configurable

.github/workflows/linkcheck.yaml

@@ -27,7 +27,7 @@ jobs:
           python-version: "3.12"
 
       - name: Install deps
-        run: pip install -r docs/requirements.txt
+        run: pip install . -r docs/requirements.txt
 
       - name: make linkcheck
         run: |

.github/workflows/test.yaml

@@ -167,6 +167,10 @@ jobs:
           jupyter lab extension list
           jupyter lab extension list 2>&1 | grep -iE 'jupyter_server_proxy.*OK.*'
 
+      - name: Install a dummy entrypoint so we can test its loaded correctly
+        run: |
+          pip install ./tests/resources/dummyentrypoint/
+
       # we have installed a pre-built wheel and configured code coverage to
       # inspect "jupyter_server_proxy", by re-locating to another directory,
       # there is no confusion about "jupyter_server_proxy" referring to our

.readthedocs.yaml

@@ -10,8 +10,10 @@ sphinx:
 build:
   os: ubuntu-22.04
   tools:
+    nodejs: "20"
     python: "3.11"
 
 python:
   install:
+    - path: .
     - requirements: docs/requirements.txt

docs/extensions/serverprocess_documenter.py

@@ -0,0 +1,58 @@
+"""
+A custom Sphinx directive to generate the Server Process options documentation:
+https://github.com/jupyterhub/jupyter-server-proxy/blob/main/docs/source/server-process.md
+"""
+
+import importlib
+from textwrap import dedent
+
+from docutils import nodes
+from sphinx.application import Sphinx
+from sphinx.util.docutils import SphinxDirective
+from sphinx.util.typing import ExtensionMetadata
+from traitlets import Undefined
+
+
+class ServerProcessDirective(SphinxDirective):
+    """A directive to say hello!"""
+
+    required_arguments = 2
+
+    def run(self) -> list[nodes.Node]:
+        module = importlib.import_module(self.arguments[0], ".")
+        cls = getattr(module, self.arguments[1])
+        config_trait_members = cls.class_traits(config=True).items()
+
+        doc = []
+
+        for name, trait in config_trait_members:
+            default_value = trait.default_value
+            if default_value is Undefined:
+                default_value = ""
+            else:
+                default_value = repr(default_value)
+            traitlets_type = trait.__class__.__name__
+
+            help = self.parse_text_to_nodes(dedent(trait.metadata.get("help", "")))
+
+            definition = nodes.definition_list_item(
+                "",
+                nodes.term(
+                    "",
+                    "",
+                    nodes.strong(text=f"{name}"),
+                    nodes.emphasis(text=f" {traitlets_type}({default_value})"),
+                ),
+                nodes.definition("", *help),
+            )
+            doc.append(nodes.definition_list("", definition))
+        return doc
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.add_directive("serverprocess", ServerProcessDirective)
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

docs/requirements.txt

@@ -1,4 +1,5 @@
 myst-parser
+sphinx>=7.4
 sphinx-autobuild
 sphinx-book-theme
 sphinx-copybutton

docs/source/conf.py

@@ -3,6 +3,8 @@
 # Configuration reference: https://www.sphinx-doc.org/en/master/usage/configuration.html
 #
 import datetime
+import sys
+from pathlib import Path
 
 # -- Project information -----------------------------------------------------
 # ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
@@ -18,11 +20,17 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 #
+
+# Custom extensions included this repo
+extensions_dir = Path(__file__).absolute().parent.parent / "extensions"
+sys.path.append(str(extensions_dir))
+
 extensions = [
     "myst_parser",
     "sphinx_copybutton",
     "sphinxext.opengraph",
     "sphinxext.rediraffe",
+    "serverprocess_documenter",
 ]
 root_doc = "index"
 source_suffix = [".md"]

docs/source/server-process.md

@@ -15,232 +15,11 @@ as separate packages.
 Server Processes are configured with a dictionary of key value
 pairs.
 
-(server-process:cmd)=
+```{eval-rst}
 
-### `command`
-
-One of:
-
-- A list of strings that is the command used to start the
-  process. The following template strings will be replaced:
-
-  - `{port}` the port that the process should listen on. This will be 0 if it
-    should use a Unix socket instead.
-  - `{unix_socket}` the path at which the process should listen on a Unix
-    socket. This will be an empty string if it should use a TCP port.
-  - `{base_url}` the base URL of the notebook. For example, if the application
-    needs to know its full path it can be constructed from
-    `{base_url}/proxy/{port}`
-
-- A callable that takes any {ref}`callable arguments <server-process:callable-arguments>`,
-  and returns a list of strings that are used & treated same as above.
-
-If the command is not specified or is an empty list, the server process is
-assumed to be started ahead of time and already available to be proxied to.
-
-### `timeout`
-
-Timeout in seconds for the process to become ready, default `5`.
-
-A process is considered 'ready' when it can return a valid HTTP response on the
-port it is supposed to start at.
-
-### `environment`
-
-One of:
-
-- A dictionary of strings that are passed in as the environment to
-  the started process, in addition to the environment of the notebook
-  process itself. The strings `{port}`, `{unix_socket}` and
-  `{base_url}` will be replaced as for **command**.
-- A callable that takes any {ref}`callable arguments <server-process:callable-arguments>`,
-  and returns a dictionary of strings that are used & treated same as above.
-
-### `absolute_url`
-
-_True_ if the URL as seen by the proxied application should be the full URL
-sent by the user. _False_ if the URL as seen by the proxied application should
-see the URL after the parts specific to jupyter-server-proxy have been stripped.
-
-For example, with the following config:
-
-```python
-c.ServerProxy.servers = {
-    "test-server": {
-        "command": ["python3", "-m", "http.server", "{port}"],
-        "absolute_url": False
-    }
-}
+.. serverprocess:: jupyter_server_proxy.config ServerProcess
 ```
 
-When a user requests `/test-server/some-url`, the proxied server will see it
-as a request for `/some-url` - the `/test-server` part is stripped out.
-
-If `absolute_url` is set to `True` instead, the proxied server will see it
-as a request for `/test-server/some-url` instead - without any stripping.
-
-This is very useful with applications that require a `base_url` to be set.
-
-Defaults to _False_.
-
-### `port`
-
-Set the port that the service will listen on. The default is to
-automatically select an unused port.
-
-(server-process:unix-socket)=
-
-### `unix_socket`
-
-This option uses a Unix socket on a filesystem path, instead of a TCP
-port. It can be passed as a string specifying the socket path, or _True_ for
-Jupyter Server Proxy to create a temporary directory to hold the socket,
-ensuring that only the user running Jupyter can connect to it.
-
-If this is used, the `{unix_socket}` argument in the command template
-(see {ref}`server-process:cmd`) will be a filesystem path. The server should
-create a Unix socket bound to this path and listen for HTTP requests on it.
-The `port` configuration key will be ignored.
-
-```{note}
-Proxying websockets over a Unix socket requires Tornado >= 6.3.
-```
-
-### `mappath`
-
-Map request paths to proxied paths.
-Either a dictionary of request paths to proxied paths,
-or a callable that takes parameter `path` and returns the proxied path.
-
-### `launcher_entry`
-
-A dictionary with options on if / how an entry in the classic Jupyter Notebook
-'New' dropdown or the JupyterLab launcher should be added. It can contain
-the following keys:
-
-1. **enabled**
-   Set to True (default) to make an entry in the launchers. Set to False to have no
-   explicit entry.
-2. **icon_path**
-   Full path to an svg icon that could be used with a launcher. Currently only used by the
-   JupyterLab launcher, when category is "Notebook" (default) or "Console".
-3. **title**
-   Title to be used for the launcher entry. Defaults to the name of the server if missing.
-4. **path_info**
-   The trailing path that is appended to the user's server URL to access the proxied server.
-   By default it is the name of the server followed by a trailing slash.
-5. **category**
-   The category for the launcher item. Currently only used by the JupyterLab launcher.
-   By default it is "Notebook".
-
-### `new_browser_tab`
-
-_JupyterLab only_ - _True_ (default) if the proxied server URL should be opened in a new browser tab.
-_False_ if the proxied server URL should be opened in a new JupyterLab tab.
-
-If _False_, the proxied server needs to allow its pages to be rendered in an iframe. This
-is generally done by configuring the web server `X-Frame-Options` to `SAMEORIGIN`.
-For more information, refer to
-[MDN Web docs on X-Frame-Options](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Frame-Options).
-
-Note that applications might use a different terminology to refer to frame options.
-For example, RStudio uses the term _frame origin_ and require the flag
-`--www-frame-origin=same` to allow rendering of its pages in an iframe.
-
-### `request_headers_override`
-
-One of:
-
-- A dictionary of strings that are passed in as HTTP headers to the proxy
-  request. The strings `{port}`, `{unix_socket}` and `{base_url}` will be
-  replaced as for **command**.
-- A callable that takes any {ref}`callable arguments <server-process:callable-arguments>`,
-  and returns a dictionary of strings that are used & treated same as above.
-
-### `update_last_activity`
-
-Whether to report activity from the proxy to Jupyter Server. If _True_, Jupyter Server
-will be notified of new activity. This is primarily used by JupyterHub for idle detection and culling.
-
-Useful if you want to have a seperate way of determining activity through a
-proxied application.
-
-Defaults to _True_.
-
-(server-process:callable-arguments)=
-
-### `raw_socket_proxy`
-
-_True_ to proxy only websocket connections into raw stream connections.
-_False_ (default) if the proxied server speaks full HTTP.
-
-If _True_, the proxied server is treated a raw TCP (or unix socket) server that
-does not use HTTP.
-In this mode, only websockets are handled, and messages are sent to the backend
-server as raw stream data. This is similar to running a
-[websockify](https://github.com/novnc/websockify) wrapper.
-All other HTTP requests return 405.
-
-### Callable arguments
-
-Certain config options accept callables, as documented above. This should return
-the same type of object that the option normally expects.
-When you use a callable this way, it can ask for any arguments it needs
-by simply declaring it - only arguments the callable asks for will be passed to it.
-
-For example, with the following config:
-
-```python
-def _cmd_callback():
-    return ["some-command"]
-
-server_config = {
-    "command": _cmd_callback
-}
-```
-
-No arguments will be passed to `_cmd_callback`, since it doesn't ask for any. However,
-with:
-
-```python
-def _cmd_callback(port):
-    return ["some-command", "--port=" + str(port)]
-
-server_config = {
-    "command": _cmd_callback
-}
-```
-
-The `port` argument will be passed to the callable. This is a simple form of dependency
-injection that helps us add more parameters in the future without breaking backwards
-compatibility.
-
-#### Available arguments
-
-Unless otherwise documented for specific options, the arguments available for
-callables are:
-
-1. **port**
-   The TCP port on which the server should listen, or is listening.
-   This is 0 if a Unix socket is used instead of TCP.
-2. **unix_socket**
-   The path of a Unix socket on which the server should listen, or is listening.
-   This is an empty string if a TCP socket is used.
-3. **base_url**
-   The base URL of the notebook
-
-If any of the returned strings, lists or dictionaries contain strings
-of form `{<argument-name>}`, they will be replaced with the value
-of the argument. For example, if your function is:
-
-```python
-def _openrefine_cmd():
-    return ["openrefine", "-p", "{port}"]
-```
-
-The `{port}` will be replaced with the appropriate port before
-the command is started
-
 ## Specifying config via traitlets
 
 [Traitlets](https://traitlets.readthedocs.io/) are the configuration

jupyter_server_proxy/__init__.py

@@ -2,6 +2,7 @@
 
 from ._version import __version__  # noqa
 from .api import IconHandler, ServersInfoHandler
+from .config import ServerProcess, ServerProcessEntryPoint
 from .config import ServerProxy as ServerProxyConfig
 from .config import get_entrypoint_server_processes, make_handlers, make_server_process
 from .handlers import setup_handlers
@@ -45,7 +46,9 @@ def _load_jupyter_server_extension(nbapp):
         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_processes += get_entrypoint_server_processes(
+        serverproxy_config, parent=nbapp
+    )
     server_handlers = make_handlers(base_url, server_processes)
     nbapp.web_app.add_handlers(".*", server_handlers)
 
@@ -81,3 +84,5 @@ def _load_jupyter_server_extension(nbapp):
 # For backward compatibility
 load_jupyter_server_extension = _load_jupyter_server_extension
 _jupyter_server_extension_paths = _jupyter_server_extension_points
+
+__all__ = ["ServerProcess", "ServerProcessEntryPoint"]