The JupyterHub API

Proxies

expand icon

Proxies

Module: jupyterhub.proxy

API for JupyterHub’s proxy.

Custom proxy implementations can subclass Proxy and register in JupyterHub config:

from mymodule import MyProxy
c.JupyterHub.proxy_class = MyProxy

Route Specification:

  • A routespec is a URL prefix ([host]/path/), e.g. ‘host.tld/path/’ for host-based routing or ‘/path/’ for default routing.
  • Route paths should be normalized to always start and end with ‘/’
class jupyterhub.proxy.Proxy(**kwargs)

Base class for configurable proxies that JupyterHub can use.

A proxy implementation should subclass this and must define the following methods:

In addition to these, the following method(s) may need to be implemented:

  • start() start the proxy, if it should be launched by the Hub instead of externally managed. If the proxy is externally managed, it should set should_start to False.
  • stop() stop the proxy. Only used if start() is also used.

And the following method(s) are optional, but can be provided:

  • get_route() gets a single route. There is a default implementation that extracts data from get_all_routes(), but implementations may choose to provide a more efficient implementation of fetching a single route.
config c.Proxy.should_start = Bool(True)

Should the Hub start the proxy

If True, the Hub will start the proxy and stop it. Set to False if the proxy is managed externally, such as by systemd, docker, or another service manager.

add_all_services(service_dict)

Update the proxy table from the database.

Used when loading up a new proxy.

add_all_users(user_dict)

Update the proxy table from the database.

Used when loading up a new proxy.

add_hub_route(hub)

Add the default route for the Hub

add_route(routespec, target, data)

Add a route to the proxy.

Subclasses must define this method

Parameters:
  • routespec (str) – A URL prefix ([host]/path/) for which this route will be matched, e.g. host.name/path/
  • target (str) – A full URL that will be the target of this route.
  • data (dict) – A JSONable dict that will be associated with this route, and will be returned when retrieving information about this route.

Will raise an appropriate Exception (FIXME: find what?) if the route could not be added.

The proxy implementation should also have a way to associate the fact that a route came from JupyterHub.

add_service(service, client=None)

Add a service’s server to the proxy table.

add_user(user, client=None)

Add a user’s server to the proxy table.

check_routes(user_dict, service_dict, routes=None)

Check that all users are properly routed on the proxy.

delete_route(routespec)

Delete a route with a given routespec if it exists.

Subclasses must define this method

delete_service(service, client=None)

Remove a service’s server from the proxy table.

delete_user(user)

Remove a user’s server from the proxy table.

get_all_routes()

Fetch and return all the routes associated by JupyterHub from the proxy.

Subclasses must define this method

Should return a dictionary of routes, where the keys are routespecs and each value is a dict of the form:

{
  'routespec': the route specification ([host]/path/)
  'target': the target host URL (proto://host) for this route
  'data': the attached data dict for this route (as specified in add_route)
}
get_route(routespec)

Return the route info for a given routespec.

Parameters:routespec (str) – A URI that was used to add this route, e.g. host.tld/path/
Returns:dict with the following keys:
'routespec': The normalized route specification passed in to add_route
    ([host]/path/)
'target': The target host for this route (proto://host)
'data': The arbitrary data dict that was passed in by JupyterHub when adding this
        route.

None: if there are no routes matching the given routespec

Return type:result (dict)
config c.Proxy.should_start = Bool(True)

Should the Hub start the proxy

If True, the Hub will start the proxy and stop it. Set to False if the proxy is managed externally, such as by systemd, docker, or another service manager.

start()

Start the proxy.

Will be called during startup if should_start is True.

Subclasses must define this method if the proxy is to be started by the Hub

stop()

Stop the proxy.

Will be called during teardown if should_start is True.

Subclasses must define this method if the proxy is to be started by the Hub

validate_routespec(routespec)

Validate a routespec

  • Checks host value vs host-based routing.
  • Ensures trailing slash on path.
class jupyterhub.proxy.ConfigurableHTTPProxy(**kwargs)

Proxy implementation for the default configurable-http-proxy.

This is the default proxy implementation for running the nodejs proxy configurable-http-proxy.

If the proxy should not be run as a subprocess of the Hub, (e.g. in a separate container), set:

c.ConfigurableHTTPProxy.should_start = False
config c.ConfigurableHTTPProxy.api_url = Unicode('http://127.0.0.1:8001')

The ip (or hostname) of the proxy’s API endpoint

config c.ConfigurableHTTPProxy.auth_token = Unicode('')

The Proxy auth token

Loaded from the CONFIGPROXY_AUTH_TOKEN env variable by default.

config c.ConfigurableHTTPProxy.command = Command()

The command to start the proxy

config c.ConfigurableHTTPProxy.debug = Bool(False)

Add debug-level logging to the Proxy.

config c.ConfigurableHTTPProxy.should_start = Bool(True)

Should the Hub start the proxy

If True, the Hub will start the proxy and stop it. Set to False if the proxy is managed externally, such as by systemd, docker, or another service manager.

config c.ConfigurableHTTPProxy.api_url = Unicode('http://127.0.0.1:8001')

The ip (or hostname) of the proxy’s API endpoint

config c.ConfigurableHTTPProxy.auth_token = Unicode('')

The Proxy auth token

Loaded from the CONFIGPROXY_AUTH_TOKEN env variable by default.

config c.ConfigurableHTTPProxy.command = Command()

The command to start the proxy

config c.ConfigurableHTTPProxy.debug = Bool(False)

Add debug-level logging to the Proxy.