Rework interface of unix_socket option

Author: takluyver

docs/source/server-process.rst

@@ -103,15 +103,16 @@ pairs.
 ``unix_socket``
 ^^^^^^^^^^^^^^^
 
-    If *True*, the server will listen on a Unix socket at a filesystem path, instead
-    of a TCP port. The ``{port}`` argument (see :ref:`server-process-cmd`) will be a
-    filesystem path for this socket instead of a port number. The server should
-    create a Unix socket bound to this path and listen for HTTP requests on it.
-
-    The Unix socket will only be available to the user the server belongs to,
-    whereas TCP sockets are available to any users on the same host.
-
-    If this is used, the ``port`` configuration key is ignored.
+    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 ``{port}`` argument in the command template
+    (see :ref:`server-process-cmd`) will be a filesystem path for this socket
+    instead of a port number. 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.
 
     Defaults to *False*.
 

jupyter_server_proxy/config.py

@@ -6,7 +6,9 @@
 from traitlets.config import Configurable
 from tornado import httpclient
 from warnings import warn
-from .handlers import SuperviseAndProxyHandler, AddSlashHandler, RewritableResponse
+from .handlers import (
+    NamedLocalProxyHandler, SuperviseAndProxyHandler, AddSlashHandler,
+)
 import pkg_resources
 from collections import namedtuple
 from .utils import call_with_asked_args
@@ -17,63 +19,56 @@
 except ImportError:
     from .utils import Callable
 
-def _make_serverproxy_handler(name, command, environment, timeout, absolute_url, port, unix_socket, mappath, request_headers_override, rewrite_response):
+
+LauncherEntry = namedtuple('LauncherEntry', ['enabled', 'icon_path', 'title', 'path_info'])
+ServerProcess = namedtuple('ServerProcess', [
+    'name', 'command', 'environment', 'timeout', 'absolute_url', 'port', 'unix_socket',
+    'mappath', 'launcher_entry', 'new_browser_tab', 'request_headers_override', 'rewrite_response',
+])
+
+
+def _make_namedproxy_handler(sp: ServerProcess):
+    class _Proxy(NamedLocalProxyHandler):
+        def __init__(self, *args, **kwargs):
+            super().__init__(*args, **kwargs)
+            self.name = sp.name
+            self.proxy_base = sp.name
+            self.absolute_url = sp.absolute_url
+            self.port = sp.port
+            self.unix_socket = sp.unix_socket
+            self.mappath = sp.mappath
+            self.rewrite_response = sp.rewrite_response
+
+        def get_request_headers_override(self):
+            return self._realize_rendered_template(sp.request_headers_override)
+
+    return _Proxy
+
+def _make_supervisedproxy_handler(sp: ServerProcess):
     """
     Create a SuperviseAndProxyHandler subclass with given parameters
     """
     # FIXME: Set 'name' properly
     class _Proxy(SuperviseAndProxyHandler):
         def __init__(self, *args, **kwargs):
             super().__init__(*args, **kwargs)
-            self.name = name
-            self.command = command
-            self.proxy_base = name
-            self.absolute_url = absolute_url
-            self.requested_port = port
-            self.unix_socket = unix_socket
-            self.mappath = mappath
-            self.rewrite_response = rewrite_response
-
-        @property
-        def process_args(self):
-            return {
-                'port': self.port,
-                'base_url': self.base_url,
-            }
-
-        def _render_template(self, value):
-            args = self.process_args
-            if type(value) is str:
-                return value.format(**args)
-            elif type(value) is list:
-                return [self._render_template(v) for v in value]
-            elif type(value) is dict:
-                return {
-                    self._render_template(k): self._render_template(v)
-                    for k, v in value.items()
-                }
-            else:
-                raise ValueError('Value of unrecognized type {}'.format(type(value)))
-
-        def _realize_rendered_template(self, attribute):
-            '''Call any callables, then render any templated values.'''
-            if callable(attribute):
-                attribute = self._render_template(
-                    call_with_asked_args(attribute, self.process_args)
-                )
-            return self._render_template(attribute)
-
-        def get_cmd(self):
-            return self._realize_rendered_template(self.command)
+            self.name = sp.name
+            self.command = sp.command
+            self.proxy_base = sp.name
+            self.absolute_url = sp.absolute_url
+            self.requested_port = sp.port
+            self.requested_unix_socket = sp.unix_socket
+            self.mappath = sp.mappath
+            self.rewrite_response = sp.rewrite_response
 
         def get_env(self):
-            return self._realize_rendered_template(environment)
+            return self._realize_rendered_template(sp.environment)
 
         def get_request_headers_override(self):
-            return self._realize_rendered_template(request_headers_override)
+            return self._realize_rendered_template(sp.request_headers_override)
 
         def get_timeout(self):
-            return timeout
+            return sp.timeout
 
     return _Proxy
 
@@ -94,31 +89,25 @@ def make_handlers(base_url, server_processes):
     """
     handlers = []
     for sp in server_processes:
-        handler = _make_serverproxy_handler(
-            sp.name,
-            sp.command,
-            sp.environment,
-            sp.timeout,
-            sp.absolute_url,
-            sp.port,
-            sp.unix_socket,
-            sp.mappath,
-            sp.request_headers_override,
-            sp.rewrite_response,
-        )
+        if sp.command:
+            handler = _make_supervisedproxy_handler(sp)
+            kwargs = dict(state={})
+        else:
+            if not (sp.port or isinstance(sp.unix_socket, str)):
+                warn(f"Server proxy {sp.name} does not have a command, port "
+                     f"number or unix_socket path. At least one of these is "
+                     f"required.")
+                continue
+            handler = _make_namedproxy_handler(sp)
+            kwargs = {}
         handlers.append((
-            ujoin(base_url, sp.name, r'(.*)'), handler, dict(state={}),
+            ujoin(base_url, sp.name, r'(.*)'), handler, kwargs,
         ))
         handlers.append((
             ujoin(base_url, sp.name), AddSlashHandler
         ))
     return handlers
 
-LauncherEntry = namedtuple('LauncherEntry', ['enabled', 'icon_path', 'title', 'path_info'])
-ServerProcess = namedtuple('ServerProcess', [
-    'name', 'command', 'environment', 'timeout', 'absolute_url', 'port', 'unix_socket',
-    'mappath', 'launcher_entry', 'new_browser_tab', 'request_headers_override', 'rewrite_response',
-])
 
 def make_server_process(name, server_process_config, serverproxy_config):
     le = server_process_config.get('launcher_entry', {})