From a10879f493410531c87885a3b1b4247bcac38eeb Mon Sep 17 00:00:00 2001 From: Chidinma Udo <97461848+Mackenzie-OO7@users.noreply.github.com> Date: Wed, 12 Oct 2022 16:20:18 +0100 Subject: [PATCH] Modifications to URLs docs --- docs/source/reference/urls.md | 86 +++++++++++++++++------------------ 1 file changed, 42 insertions(+), 44 deletions(-) diff --git a/docs/source/reference/urls.md b/docs/source/reference/urls.md index d71feaf2..8e4ec0f3 100644 --- a/docs/source/reference/urls.md +++ b/docs/source/reference/urls.md @@ -2,13 +2,13 @@ This document describes how JupyterHub routes requests. -This does not include the [REST API](./rest.md) urls. +This does not include the [REST API](./rest.md) URLs. In general, all URLs can be prefixed with `c.JupyterHub.base_url` to run the whole JupyterHub application on a prefix. -All authenticated handlers redirect to `/hub/login` to login users -prior to being redirected back to the originating page. +All authenticated handlers redirect to `/hub/login` to log-in users +before being redirected back to the originating page. The returned request should preserve all query parameters. ## `/` @@ -25,12 +25,12 @@ This is an authenticated URL. This handler redirects users to the default URL of the application, which defaults to the user's default server. -That is, it redirects to `/hub/spawn` if the user's server is not running, -or the server itself (`/user/:name`) if the server is running. +That is, the handler redirects to `/hub/spawn` if the user's server is not running, +or to the server itself (`/user/:name`) if the server is running. -This default url behavior can be customized in two ways: +This default URL behavior can be customized in two ways: -To redirect users to the JupyterHub home page (`/hub/home`) +First, to redirect users to the JupyterHub home page (`/hub/home`) instead of spawning their server, set `redirect_to_server` to False: @@ -40,7 +40,7 @@ c.JupyterHub.redirect_to_server = False This might be useful if you have a Hub where you expect users to be managing multiple server configurations -and automatic spawning is not desirable. +but automatic spawning is not desirable. Second, you can customise the landing page to any page you like, such as a custom service you have deployed e.g. with course information: @@ -57,7 +57,7 @@ By default, the Hub home page has just one or two buttons for starting and stopping the user's server. If named servers are enabled, there will be some additional -tools for management of named servers. +tools for management of the named servers. _Version added: 1.0_ named server UI is new in 1.0. @@ -65,34 +65,34 @@ _Version added: 1.0_ named server UI is new in 1.0. This is the JupyterHub login page. If you have a form-based username+password login, -such as the default PAMAuthenticator, +such as the default [PAMAuthenticator](https://en.wikipedia.org/wiki/Pluggable_authentication_module), this page will render the login form. ![A login form](../images/login-form.png) If login is handled by an external service, e.g. with OAuth, this page will have a button, -declaring "Login with ..." which users can click -to login with the chosen service. +declaring "Log in with ..." which users can click +to log in with the chosen service. ![A login redirect button](../images/login-button.png) -If you want to skip the user-interaction to initiate logging in -via the button, you can set +If you want to skip the user interaction and initiate login +via the button, you can set: ```python c.Authenticator.auto_login = True ``` -This can be useful when the user is "already logged in" via some mechanism, -but a handshake via redirects is necessary to complete the authentication with JupyterHub. +This can be useful when the user is "already logged in" via some mechanism. +However, a handshake via `redirects` is necessary to complete the authentication with JupyterHub. ## `/hub/logout` -Visiting `/hub/logout` clears cookies from the current browser. +Visiting `/hub/logout` clears [cookies](https://en.wikipedia.org/wiki/HTTP_cookie) from the current browser. Note that **logging out does not stop a user's server(s)** by default. -If you would like to shutdown user servers on logout, +If you would like to shut down user servers on logout, you can enable this behavior with: ```python @@ -105,8 +105,8 @@ does not mean the user is no longer actively using their server from another mac ## `/user/:username[/:servername]` If a user's server is running, this URL is handled by the user's given server, -not the Hub. -The username is the first part and, if using named servers, +not by the Hub. +The username is the first part, and if using named servers, the server name is the second part. If the user's server is _not_ running, this will be redirected to `/hub/user/:username/...` @@ -120,11 +120,11 @@ if the specified server were running). Handling this URL is the most complicated condition in JupyterHub, because there can be many states: -1. server is not active +1. the server is not active a. user matches b. user doesn't match -2. server is ready -3. server is pending, but not ready +2. the server is ready +3. the server is pending, but not ready If the server is pending spawn, the browser will be redirected to `/hub/spawn-pending/:username/:servername` @@ -140,39 +140,37 @@ Some checks are performed and a delay is added before redirecting back to `/user If something is really wrong, this can result in a redirect loop. Visiting this page will never result in triggering the spawn of servers -without additional user action (i.e. clicking the link on the page) +without additional user action (i.e. clicking the link on the page). ![Visiting a URL for a server that's not running](../images/not-running.png) _Version changed: 1.0_ -Prior to 1.0, this URL itself was responsible for spawning servers, -and served the progress page if it was pending, -redirected to running servers, and -This was useful because it made sure that requested servers were restarted after they stopped, -but could also be harmful because unused servers would continuously be restarted if e.g. -an idle JupyterLab frontend were open pointed at it, -which constantly makes polling requests. +Prior to 1.0, this URL itself was responsible for spawning servers. +If the progress page was pending, the URL redirected it to running servers. +This was useful because it made sure that the requested servers were restarted after they stopped. +However, it could also be harmful because unused servers would continuously be restarted if e.g. +an idle JupyterLab frontend that constantly makes polling requests was openly pointed at it. ### Special handling of API requests Requests to `/user/:username[/:servername]/api/...` are assumed to be from applications connected to stopped servers. -These are failed with 503 and an informative JSON error message -indicating how to spawn the server. -This is meant to help applications such as JupyterLab +These requests fail with a `503` status code and an informative JSON error message +that indicates how to spawn the server. +This is meant to help applications such as JupyterLab, that are connected to a server that has stopped. _Version changed: 1.0_ -JupyterHub 0.9 failed these API requests with status 404, -but 1.0 uses 503. +JupyterHub version 0.9 failed these API requests with status `404`, +but version 1.0 uses 503. ## `/user-redirect/...` -This URL is for sharing a URL that will redirect a user +The `/user-redirect/...` URL is for sharing a URL that will redirect a user to a path on their own default server. -This is useful when users have the same file at the same URL on their servers, +This is useful when different users have the same file at the same URL on their servers, and you want a single link to give to any user that will open that file on their server. e.g. a link to `/user-redirect/notebooks/Index.ipynb` @@ -194,7 +192,7 @@ that is intended to make it possible. ### `/hub/spawn[/:username[/:servername]]` Requesting `/hub/spawn` will spawn the default server for the current user. -If `username` and optionally `servername` are specified, +If the `username` and optionally `servername` are specified, then the specified server for the specified user will be spawned. Once spawn has been requested, the browser is redirected to `/hub/spawn-pending/...`. @@ -207,7 +205,7 @@ and a POST request will trigger the actual spawn and redirect. _Version added: 1.0_ -1.0 adds the ability to specify username and servername. +1.0 adds the ability to specify `username` and `servername`. Prior to 1.0, only `/hub/spawn` was recognized for the default server. _Version changed: 1.0_ @@ -247,7 +245,7 @@ against the [JupyterHub REST API](./rest.md). Administrators can take various administrative actions from this page: -1. add/remove users -2. grant admin privileges -3. start/stop user servers -4. shutdown JupyterHub itself +- add/remove users +- grant admin privileges +- start/stop user servers +- shutdown JupyterHub itself