Bump to 5.3.0

changelog for 5.3.0

.github/dependabot.yaml

@@ -14,3 +14,44 @@ updates:
       interval: monthly
       time: "05:00"
       timezone: Etc/UTC
+  - package-ecosystem: npm
+    directory: /
+    groups:
+      # one big pull request for minor bumps
+      npm-minor:
+        patterns:
+          - "*"
+        update-types:
+          - minor
+          - patch
+    schedule:
+      interval: monthly
+  - package-ecosystem: npm
+    directory: /jsx
+    groups:
+      # one big pull request for minor bumps
+      jsx-minor:
+        patterns:
+          - "*"
+        update-types:
+          - minor
+          - patch
+      # group major bumps of react-related dependencies
+      jsx-react:
+        patterns:
+          - "react*"
+          - "redux*"
+          - "*react"
+          - "recompose"
+        update-types:
+          - major
+      # group major bumps of webpack-related dependencies
+      jsx-webpack:
+        patterns:
+          - "*webpack*"
+          - "@babel/*"
+          - "*-loader"
+        update-types:
+          - major
+    schedule:
+      interval: monthly

.github/workflows/registry-overviews.yml

@@ -1,54 +0,0 @@
-name: Update Registry overviews
-
-env:
-  OWNER: ${{ github.repository_owner }}
-
-on:
-  push:
-    branches:
-      - main
-    paths:
-      - ".github/workflows/registry-overviews.yml"
-
-      - "README.md"
-      - "onbuild/README.md"
-      - "demo-image/README.md"
-      - "singleuser/README.md"
-  workflow_dispatch:
-
-jobs:
-  update-overview:
-    runs-on: ubuntu-latest
-    name: update-overview (${{matrix.image}})
-    if: github.repository_owner == 'jupyterhub'
-
-    steps:
-      - name: Checkout Repo ⚡️
-        uses: actions/checkout@v4
-
-      - name: Push README to Registry 🐳
-        uses: christian-korneck/update-container-description-action@d36005551adeaba9698d8d67a296bd16fa91f8e8 # v1
-        env:
-          DOCKER_USER: ${{ secrets.DOCKERHUB_USERNAME }}
-          DOCKER_PASS: ${{ secrets.DOCKERHUB_TOKEN }}
-        with:
-          destination_container_repo: ${{ env.OWNER }}/${{ matrix.image }}
-          provider: dockerhub
-          short_description: ${{ matrix.description }}
-          readme_file: ${{ matrix.readme_file }}
-
-    strategy:
-      matrix:
-        include:
-          - image: jupyterhub
-            description: "JupyterHub: multi-user Jupyter notebook server"
-            readme_file: README.md
-          - image: jupyterhub-onbuild
-            description: onbuild version of JupyterHub images
-            readme_file: onbuild/README.md
-          - image: jupyterhub-demo
-            description: Demo JupyterHub Docker image with a quick overview of what JupyterHub is and how it works
-            readme_file: demo-image/README.md
-          - image: singleuser
-            description: "single-user docker images for use with JupyterHub and DockerSpawner see also: jupyter/docker-stacks"
-            readme_file: singleuser/README.md

.github/workflows/release.yml

@@ -1,7 +1,7 @@
 # This is a GitHub workflow defining a set of jobs with a set of steps.
 # ref: https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions
 #
-# Test build release artifacts (PyPI package, Docker images) and publish them on
+# Test build release artifacts (PyPI package) and publish them on
 # pushed git tags.
 #
 name: Release
@@ -28,6 +28,9 @@ on:
       - "**"
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   build-release:
     runs-on: ubuntu-22.04
@@ -82,150 +85,3 @@ jobs:
         run: |
           pip install twine
           twine upload --skip-existing dist/*
-
-  publish-docker:
-    runs-on: ubuntu-22.04
-    timeout-minutes: 30
-
-    services:
-      # So that we can test this in PRs/branches
-      local-registry:
-        image: registry:2
-        ports:
-          - 5000:5000
-
-    steps:
-      - name: Should we push this image to a public registry?
-        run: |
-          if [ "${{ startsWith(github.ref, 'refs/tags/') || (github.ref == 'refs/heads/main') }}" = "true" ]; then
-              echo "REGISTRY=quay.io/" >> $GITHUB_ENV
-          else
-              echo "REGISTRY=localhost:5000/" >> $GITHUB_ENV
-          fi
-
-      - uses: actions/checkout@v4
-
-      # Setup docker to build for multiple platforms, see:
-      # https://github.com/docker/build-push-action/tree/v2.4.0#usage
-      # https://github.com/docker/build-push-action/blob/v2.4.0/docs/advanced/multi-platform.md
-      - name: Set up QEMU (for docker buildx)
-        uses: docker/setup-qemu-action@v3
-
-      - name: Set up Docker Buildx (for multi-arch builds)
-        uses: docker/setup-buildx-action@v3
-        with:
-          # Allows pushing to registry on localhost:5000
-          driver-opts: network=host
-
-      - name: Setup push rights to Docker Hub
-        # This was setup by...
-        # 1. Creating a [Robot Account](https://quay.io/organization/jupyterhub?tab=robots) in the JupyterHub
-        # .  Quay.io org
-        # 2. Giving it enough permissions to push to the jupyterhub and singleuser images
-        # 3. Putting the robot account's username and password in GitHub actions environment
-        if: env.REGISTRY != 'localhost:5000/'
-        run: |
-          docker login -u "${{ secrets.QUAY_USERNAME }}" -p "${{ secrets.QUAY_PASSWORD }}" "${{ env.REGISTRY }}"
-          docker login -u "${{ secrets.DOCKERHUB_USERNAME }}" -p "${{ secrets.DOCKERHUB_TOKEN }}" docker.io
-
-      # image: jupyterhub/jupyterhub
-      #
-      # https://github.com/jupyterhub/action-major-minor-tag-calculator
-      # If this is a tagged build this will return additional parent tags.
-      # E.g. 1.2.3 is expanded to Docker tags
-      # [{prefix}:1.2.3, {prefix}:1.2, {prefix}:1, {prefix}:latest] unless
-      # this is a backported tag in which case the newer tags aren't updated.
-      # For branches this will return the branch name.
-      # If GITHUB_TOKEN isn't available (e.g. in PRs) returns no tags [].
-      - name: Get list of jupyterhub tags
-        id: jupyterhubtags
-        uses: jupyterhub/action-major-minor-tag-calculator@v3
-        with:
-          githubToken: ${{ secrets.GITHUB_TOKEN }}
-          prefix: >-
-            ${{ env.REGISTRY }}jupyterhub/jupyterhub:
-            jupyterhub/jupyterhub:
-          defaultTag: "${{ env.REGISTRY }}jupyterhub/jupyterhub:noref"
-          branchRegex: ^\w[\w-.]*$
-
-      - name: Build and push jupyterhub
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          platforms: linux/amd64,linux/arm64
-          push: true
-          # tags parameter must be a string input so convert `gettags` JSON
-          # array into a comma separated list of tags
-          tags: ${{ join(fromJson(steps.jupyterhubtags.outputs.tags)) }}
-
-      # image: jupyterhub/jupyterhub-onbuild
-      #
-      - name: Get list of jupyterhub-onbuild tags
-        id: onbuildtags
-        uses: jupyterhub/action-major-minor-tag-calculator@v3
-        with:
-          githubToken: ${{ secrets.GITHUB_TOKEN }}
-          prefix: >-
-            ${{ env.REGISTRY }}jupyterhub/jupyterhub-onbuild:
-            jupyterhub/jupyterhub-onbuild:
-          defaultTag: "${{ env.REGISTRY }}jupyterhub/jupyterhub-onbuild:noref"
-          branchRegex: ^\w[\w-.]*$
-
-      - name: Build and push jupyterhub-onbuild
-        uses: docker/build-push-action@v6
-        with:
-          build-args: |
-            BASE_IMAGE=${{ fromJson(steps.jupyterhubtags.outputs.tags)[0] }}
-          context: onbuild
-          platforms: linux/amd64,linux/arm64
-          push: true
-          tags: ${{ join(fromJson(steps.onbuildtags.outputs.tags)) }}
-
-      # image: jupyterhub/jupyterhub-demo
-      #
-      - name: Get list of jupyterhub-demo tags
-        id: demotags
-        uses: jupyterhub/action-major-minor-tag-calculator@v3
-        with:
-          githubToken: ${{ secrets.GITHUB_TOKEN }}
-          prefix: >-
-            ${{ env.REGISTRY }}jupyterhub/jupyterhub-demo:
-            jupyterhub/jupyterhub-demo:
-          defaultTag: "${{ env.REGISTRY }}jupyterhub/jupyterhub-demo:noref"
-          branchRegex: ^\w[\w-.]*$
-
-      - name: Build and push jupyterhub-demo
-        uses: docker/build-push-action@v6
-        with:
-          build-args: |
-            BASE_IMAGE=${{ fromJson(steps.onbuildtags.outputs.tags)[0] }}
-          context: demo-image
-          # linux/arm64 currently fails:
-          # ERROR: Could not build wheels for argon2-cffi which use PEP 517 and cannot be installed directly
-          # ERROR: executor failed running [/bin/sh -c python3 -m pip install notebook]: exit code: 1
-          platforms: linux/amd64
-          push: true
-          tags: ${{ join(fromJson(steps.demotags.outputs.tags)) }}
-
-      # image: jupyterhub/singleuser
-      #
-      - name: Get list of jupyterhub/singleuser tags
-        id: singleusertags
-        uses: jupyterhub/action-major-minor-tag-calculator@v3
-        with:
-          githubToken: ${{ secrets.GITHUB_TOKEN }}
-          prefix: >-
-            ${{ env.REGISTRY }}jupyterhub/singleuser:
-            jupyterhub/singleuser:
-          defaultTag: "${{ env.REGISTRY }}jupyterhub/singleuser:noref"
-          branchRegex: ^\w[\w-.]*$
-
-      - name: Build and push jupyterhub/singleuser
-        uses: docker/build-push-action@v6
-        with:
-          build-args: |
-            JUPYTERHUB_VERSION=${{ github.ref_type == 'tag' && github.ref_name || format('git:{0}', github.sha) }}
-          context: singleuser
-          platforms: linux/amd64,linux/arm64
-          push: true
-          tags: ${{ join(fromJson(steps.singleusertags.outputs.tags)) }}

.github/workflows/test-docs.yml

@@ -29,6 +29,9 @@ on:
       - "**"
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 env:
   # UTF-8 content may be interpreted as ascii and causes errors without this.
   LANG: C.UTF-8
@@ -81,10 +84,12 @@ jobs:
           cd docs
           make html
 
+      # Output broken and permanently redirected links in a readable format
       - name: check links
-        run: |
-          cd docs
-          make linkcheck
+        uses: manics/action-sphinx-linkcheck-summary@main
+        with:
+          docs-dir: docs
+          build-dir: docs/_build
 
       # make rediraffecheckdiff compares files for different changesets
       # these diff targets aren't always available

.github/workflows/test.yml

@@ -173,7 +173,7 @@ jobs:
             # make sure our `>=` pins really do express our minimum supported versions
             pip install -r ci/oldest-dependencies/requirements.old -e .
           else
-            pip install -e ".[test]"
+            pip install --pre -e ".[test]"
           fi
 
           if [ "${{ matrix.main_dependencies }}" != "" ]; then
@@ -252,31 +252,10 @@ jobs:
 
       - name: Ensure browsers are installed for playwright
         if: matrix.browser
-        run: python -m playwright install --with-deps
+        run: python -m playwright install --with-deps firefox
 
       - name: Run pytest
         run: |
           pytest -k "${{ matrix.subset }}" --maxfail=2 --cov=jupyterhub jupyterhub/tests
 
-      - uses: codecov/codecov-action@v4
-
-  docker-build:
-    runs-on: ubuntu-22.04
-    timeout-minutes: 20
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: build images
-        run: |
-          DOCKER_BUILDKIT=1 docker build -t jupyterhub/jupyterhub .
-          docker build -t jupyterhub/jupyterhub-onbuild onbuild
-          docker build -t jupyterhub/singleuser singleuser
-
-      - name: smoke test jupyterhub
-        run: |
-          docker run --rm -t jupyterhub/jupyterhub jupyterhub --help
-
-      - name: verify static files
-        run: |
-          docker run --rm -t -v $PWD/dockerfiles:/io jupyterhub/jupyterhub python3 /io/test.py
+      - uses: codecov/codecov-action@v5

.gitignore

@@ -7,8 +7,6 @@ node_modules
 dist
 docs/_build
 docs/build
-docs/source/_static/rest-api
-docs/source/rbac/scope-table.md
 docs/source/reference/metrics.md
 
 .ipynb_checkpoints

.pre-commit-config.yaml

@@ -16,7 +16,7 @@ ci:
 repos:
   # autoformat and lint Python code
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.5.0
+    rev: v0.11.4
     hooks:
       - id: ruff
         types_or:
@@ -33,11 +33,11 @@ repos:
     rev: v4.0.0-alpha.8
     hooks:
       - id: prettier
-        exclude: .*/templates/.*
+        exclude: .*/templates/.*|docs/source/_static/rest-api.yml|docs/source/rbac/scope-table.md
 
   # autoformat HTML templates
   - repo: https://github.com/djlint/djLint
-    rev: v1.34.1
+    rev: v1.36.4
     hooks:
       - id: djlint-reformat-jinja
         files: ".*templates/.*.html"
@@ -49,10 +49,38 @@ repos:
 
   # Autoformat and linting, misc. details
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: end-of-file-fixer
         exclude: share/jupyterhub/static/js/admin-react.js
       - id: requirements-txt-fixer
       - id: check-case-conflict
       - id: check-executables-have-shebangs
+
+  # source docs: rest-api.yml and scope-table.md are autogenerated
+  - repo: local
+    hooks:
+      - id: update-api-and-scope-docs
+        name: Update rest-api.yml and scope-table.md based on scopes.py
+        language: python
+        additional_dependencies: ["pytablewriter", "ruamel.yaml"]
+        entry: python docs/source/rbac/generate-scope-table.py
+        args:
+          - --update
+        files: jupyterhub/scopes.py
+        pass_filenames: false
+
+      # run eslint in the jsx directory
+      # need to pass through 'jsx:install-run' hook in
+      # top-level package.json to ensure dependencies are installed
+      # eslint pre-commit hook doesn't really work with eslint 9,
+      # so use `npm run lint:fix`
+      - id: jsx-eslint
+        name: eslint in jsx/
+        entry: npm run jsx:install-run lint:fix
+        pass_filenames: false
+        language: node
+        files: "jsx/.*"
+        # can't run on pre-commit; hangs, for some reason
+        stages:
+          - manual

.readthedocs.yaml

@@ -8,10 +8,9 @@ sphinx:
   configuration: docs/source/conf.py
 
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    nodejs: "20"
-    python: "3.11"
+    python: "3.13"
 
 python:
   install:

CONTRIBUTING.md

@@ -12,3 +12,29 @@ Please see our documentation on
 - [Testing JupyterHub and linting code](https://jupyterhub.readthedocs.io/en/latest/contributing/tests.html)
 
 If you need some help, feel free to ask on [Gitter](https://gitter.im/jupyterhub/jupyterhub) or [Discourse](https://discourse.jupyter.org/).
+
+## Our Copyright Policy
+
+Jupyter uses a shared copyright model. Each contributor maintains copyright
+over their contributions to Jupyter. But, it is important to note that these
+contributions are typically only changes to the repositories. Thus, the Jupyter
+source code, in its entirety is not the copyright of any single person or
+institution. Instead, it is the collective copyright of the entire Jupyter
+Development Team. If individual contributors want to maintain a record of what
+changes/contributions they have specific copyright on, they should indicate
+their copyright in the commit message of the change, when they commit the
+change to one of the Jupyter repositories.
+
+With this in mind, the following banner should be used in any source code file
+to indicate the copyright and license terms:
+
+    # Copyright (c) Jupyter Development Team.
+    # Distributed under the terms of the Modified BSD License.
+
+### About the Jupyter Development Team
+
+The Jupyter Development Team is the set of all contributors to the Jupyter project.
+This includes all of the Jupyter subprojects.
+
+The team that coordinates JupyterHub subproject can be found here:
+https://jupyterhub-team-compass.readthedocs.io/en/latest/governance.html

COPYING.md

@@ -1,59 +0,0 @@
-# The Jupyter multi-user notebook server licensing terms
-
-Jupyter multi-user notebook server is licensed under the terms of the Modified BSD License
-(also known as New or Revised or 3-Clause BSD), as follows:
-
-- Copyright (c) 2014-, Jupyter Development Team
-
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-Redistributions of source code must retain the above copyright notice, this
-list of conditions and the following disclaimer.
-
-Redistributions in binary form must reproduce the above copyright notice, this
-list of conditions and the following disclaimer in the documentation and/or
-other materials provided with the distribution.
-
-Neither the name of the Jupyter Development Team nor the names of its
-contributors may be used to endorse or promote products derived from this
-software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-## About the Jupyter Development Team
-
-The Jupyter Development Team is the set of all contributors to the Jupyter project.
-This includes all of the Jupyter subprojects.
-
-The core team that coordinates development on GitHub can be found here:
-https://github.com/jupyter/.
-
-## Our Copyright Policy
-
-Jupyter uses a shared copyright model. Each contributor maintains copyright
-over their contributions to Jupyter. But, it is important to note that these
-contributions are typically only changes to the repositories. Thus, the Jupyter
-source code, in its entirety is not the copyright of any single person or
-institution. Instead, it is the collective copyright of the entire Jupyter
-Development Team. If individual contributors want to maintain a record of what
-changes/contributions they have specific copyright on, they should indicate
-their copyright in the commit message of the change, when they commit the
-change to one of the Jupyter repositories.
-
-With this in mind, the following banner should be used in any source code file
-to indicate the copyright and license terms:
-
-    # Copyright (c) Jupyter Development Team.
-    # Distributed under the terms of the Modified BSD License.

Dockerfile

@@ -1,146 +0,0 @@
-# An incomplete base Docker image for running JupyterHub
-#
-# Add your configuration to create a complete derivative Docker image.
-#
-# Include your configuration settings by starting with one of two options:
-#
-# Option 1:
-#
-# FROM quay.io/jupyterhub/jupyterhub:latest
-#
-# And put your configuration file jupyterhub_config.py in /srv/jupyterhub/jupyterhub_config.py.
-#
-# Option 2:
-#
-# Or you can create your jupyterhub config and database on the host machine, and mount it with:
-#
-# docker run -v $PWD:/srv/jupyterhub -t quay.io/jupyterhub/jupyterhub
-#
-# NOTE
-# If you base on quay.io/jupyterhub/jupyterhub-onbuild
-# your jupyterhub_config.py will be added automatically
-# from your docker directory.
-
-######################################################################
-# This Dockerfile uses multi-stage builds with optimisations to build
-# the JupyterHub wheel on the native architecture only
-# https://www.docker.com/blog/faster-multi-platform-builds-dockerfile-cross-compilation-guide/
-
-ARG BASE_IMAGE=ubuntu:22.04
-
-
-######################################################################
-# The JupyterHub wheel is pure Python so can be built for any platform
-# on the native architecture (avoiding QEMU emulation)
-FROM --platform=${BUILDPLATFORM:-linux/amd64} $BASE_IMAGE AS jupyterhub-builder
-
-ENV DEBIAN_FRONTEND=noninteractive
-
-# Don't clear apt cache, and don't combine RUN commands, so that cached layers can
-# be reused in other stages
-
-RUN apt-get update -qq \
- && apt-get install -yqq --no-install-recommends \
-    build-essential \
-    ca-certificates \
-    curl \
-    git \
-    gnupg \
-    locales \
-    python3-dev \
-    python3-pip \
-    python3-pycurl \
-    python3-venv \
- && python3 -m pip install --no-cache-dir --upgrade setuptools pip build wheel
-# Ubuntu 22.04 comes with Nodejs 12 which is too old for building JupyterHub JS
-# It's fine at runtime though (used only by configurable-http-proxy)
-ARG NODE_MAJOR=20
-RUN mkdir -p /etc/apt/keyrings \
- && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
- && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list \
- && apt-get update \
- && apt-get install -yqq --no-install-recommends \
-    nodejs
-
-WORKDIR /src/jupyterhub
-# copy everything except whats in .dockerignore, its a
-# compromise between needing to rebuild and maintaining
-# what needs to be part of the build
-COPY . .
-
-ARG PIP_CACHE_DIR=/tmp/pip-cache
-RUN --mount=type=cache,target=${PIP_CACHE_DIR} \
-    python3 -m build --wheel
-
-# verify installed files
-RUN --mount=type=cache,target=${PIP_CACHE_DIR} \
-    python3 -m pip install ./dist/*.whl \
- && cd ci \
- && python3 check_installed_data.py
-
-######################################################################
-# All other wheels required by JupyterHub, some are platform specific
-FROM $BASE_IMAGE AS wheel-builder
-
-ENV DEBIAN_FRONTEND=noninteractive
-
-RUN apt-get update -qq \
- && apt-get install -yqq --no-install-recommends \
-    build-essential \
-    ca-certificates \
-    curl \
-    locales \
-    python3-dev \
-    python3-pip \
-    python3-pycurl \
-    python3-venv \
- && python3 -m pip install --no-cache-dir --upgrade setuptools pip build wheel
-
-WORKDIR /src/jupyterhub
-
-COPY --from=jupyterhub-builder /src/jupyterhub/dist/*.whl /src/jupyterhub/dist/
-ARG PIP_CACHE_DIR=/tmp/pip-cache
-RUN --mount=type=cache,target=${PIP_CACHE_DIR} \
-    python3 -m pip wheel --wheel-dir wheelhouse dist/*.whl
-
-
-######################################################################
-# The final JupyterHub image, platform specific
-FROM $BASE_IMAGE AS jupyterhub
-
-ENV DEBIAN_FRONTEND=noninteractive \
-    SHELL=/bin/bash \
-    LC_ALL=en_US.UTF-8 \
-    LANG=en_US.UTF-8 \
-    LANGUAGE=en_US.UTF-8 \
-    PYTHONDONTWRITEBYTECODE=1
-
-EXPOSE 8000
-
-LABEL maintainer="Jupyter Project <jupyter@googlegroups.com>"
-LABEL org.jupyter.service="jupyterhub"
-
-WORKDIR /srv/jupyterhub
-
-RUN apt-get update -qq \
- && apt-get install -yqq --no-install-recommends \
-    ca-certificates \
-    curl \
-    gnupg \
-    locales \
-    python-is-python3 \
-    python3-pip \
-    python3-pycurl \
-    nodejs \
-    npm \
- && locale-gen $LC_ALL \
- && npm install -g configurable-http-proxy@^4.2.0 \
- # clean cache and logs
- && rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* ~/.npm
-# install the wheels we built in the previous stage
-RUN --mount=type=cache,from=wheel-builder,source=/src/jupyterhub/wheelhouse,target=/tmp/wheelhouse \
-    # always make sure pip is up to date!
-    python3 -m pip install --no-compile --no-cache-dir --upgrade setuptools pip \
- && python3 -m pip install --no-compile --no-cache-dir /tmp/wheelhouse/*
-
-CMD ["jupyterhub"]

LICENSE

@@ -0,0 +1,11 @@
+Copyright 2014-, Jupyter Development Team
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -111,7 +111,7 @@ Visit `http://localhost:8000` in your browser, and sign in with your system user
 
 _Note_: To allow multiple users to sign in to the server, you will need to
 run the `jupyterhub` command as a _privileged user_, such as root.
-The [wiki](https://github.com/jupyterhub/jupyterhub/wiki/Using-sudo-to-run-JupyterHub-without-root-privileges)
+The [documentation](https://jupyterhub.readthedocs.io/en/latest/howto/configuration/config-sudo.html)
 describes how to run the server as a _less privileged user_, which requires
 more configuration of the system.
 
@@ -220,7 +220,7 @@ docker container or Linux VM.
 We use a shared copyright model that enables all contributors to maintain the
 copyright on their contributions.
 
-All code is licensed under the terms of the [revised BSD license](./COPYING.md).
+All code is licensed under the terms of the [revised BSD license](./LICENSE).
 
 ## Help and resources
 

demo-image/Dockerfile

@@ -1,16 +0,0 @@
-# Demo JupyterHub Docker image
-#
-# This should only be used for demo or testing and not as a base image to build on.
-#
-# It includes the notebook package and it uses the DummyAuthenticator and the SimpleLocalProcessSpawner.
-ARG BASE_IMAGE=quay.io/jupyterhub/jupyterhub-onbuild
-FROM ${BASE_IMAGE}
-
-# Install the notebook package
-RUN python3 -m pip install notebook
-
-# Create a demo user
-RUN useradd --create-home demo
-RUN chown demo .
-
-USER demo

demo-image/README.md

@@ -1,26 +0,0 @@
-## Demo Dockerfile
-
-This is a demo JupyterHub Docker image to help you get a quick overview of what
-JupyterHub is and how it works.
-
-It uses the SimpleLocalProcessSpawner to spawn new user servers and
-DummyAuthenticator for authentication.
-The DummyAuthenticator allows you to log in with any username & password and the
-SimpleLocalProcessSpawner allows starting servers without having to create a
-local user for each JupyterHub user.
-
-### Important!
-
-This should only be used for demo or testing purposes!
-It shouldn't be used as a base image to build on.
-
-### Try it
-
-1. `cd` to the root of your jupyterhub repo.
-
-2. Build the demo image with `docker build -t jupyterhub-demo demo-image`.
-
-3. Run the demo image with `docker run -d -p 8000:8000 jupyterhub-demo`.
-
-4. Visit http://localhost:8000 and login with any username and password
-5. Happy demo-ing :tada:!

demo-image/jupyterhub_config.py

@@ -1,7 +0,0 @@
-# Configuration file for jupyterhub-demo
-
-c = get_config()  # noqa
-
-# Use DummyAuthenticator and SimpleSpawner
-c.JupyterHub.spawner_class = "simple"
-c.JupyterHub.authenticator_class = "dummy"

dockerfiles/test.py

@@ -1,14 +0,0 @@
-import os
-
-from jupyterhub._data import DATA_FILES_PATH
-
-print(f"DATA_FILES_PATH={DATA_FILES_PATH}")
-
-for sub_path in (
-    "templates",
-    "static/components",
-    "static/css/style.min.css",
-    "static/js/admin-react.js",
-):
-    path = os.path.join(DATA_FILES_PATH, sub_path)
-    assert os.path.exists(path), path

docs/Makefile

@@ -35,7 +35,7 @@ help:
 # - NOTE: If the pre-requisites for the html target is updated, also update the
 #         Read The Docs section in docs/source/conf.py.
 #
-html: metrics scopes
+html: metrics
 	$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
@@ -44,10 +44,6 @@ metrics: source/reference/metrics.md
 source/reference/metrics.md:
 	python3 generate-metrics.py
 
-scopes: source/rbac/scope-table.md
-source/rbac/scope-table.md:
-	python3 source/rbac/generate-scope-table.py
-
 
 # Manually added targets - related to development
 # ----------------------------------------------------------------------------
@@ -56,7 +52,7 @@ source/rbac/scope-table.md:
 # - requires sphinx-autobuild, see
 #   https://sphinxcontrib-spelling.readthedocs.io/en/latest/
 # - builds and rebuilds html on changes to source, but does not re-generate
-#   metrics/scopes files
+#   metrics files
 # - starts a livereload enabled webserver and opens up a browser
 devenv: html
 	sphinx-autobuild -b html --open-browser "$(SOURCEDIR)" "$(BUILDDIR)/html"

docs/requirements.txt

@@ -2,6 +2,7 @@
 # don't depend on it here, as that often results in a duplicate
 # installation of jupyterhub that's already installed
 autodoc-traits
+intersphinx-registry
 jupyterhub-sphinx-theme
 myst-parser>=0.19
 pre-commit

docs/source/_static/rest-api.yml

@@ -7,7 +7,7 @@ info:
   license:
     name: BSD-3-Clause
     identifier: BSD-3-Clause
-  version: 5.1.0
+  version: 5.3.0
 servers:
   - url: /hub/api
 security:
@@ -62,8 +62,7 @@ paths:
                     properties:
                       class:
                         type: string
-                        description:
-                          The Python class currently active for JupyterHub
+                        description: The Python class currently active for JupyterHub
                           Authentication
                       version:
                         type: string
@@ -73,8 +72,7 @@ paths:
                     properties:
                       class:
                         type: string
-                        description:
-                          The Python class currently active for spawning
+                        description: The Python class currently active for spawning
                           single-user notebook servers
                       version:
                         type: string
@@ -258,8 +256,7 @@ paths:
       parameters:
         - $ref: "#/components/parameters/userName"
       requestBody:
-        description:
-          Updated user info. At least one key to be updated (name or admin)
+        description: Updated user info. At least one key to be updated (name or admin)
           is required.
         content:
           application/json:
@@ -268,13 +265,11 @@ paths:
               properties:
                 name:
                   type: string
-                  description:
-                    the new name (optional, if another key is updated i.e.
+                  description: the new name (optional, if another key is updated i.e.
                     admin)
                 admin:
                   type: boolean
-                  description:
-                    update admin (optional, if another key is updated i.e.
+                  description: update admin (optional, if another key is updated i.e.
                     name)
         required: true
       responses:
@@ -291,8 +286,7 @@ paths:
     post:
       operationId: post-user-activity
       summary: Notify Hub of activity for a given user
-      description:
-        Notify the Hub of activity by the user, e.g. accessing a service
+      description: Notify the Hub of activity by the user, e.g. accessing a service
         or (more likely) actively using a server.
       parameters:
         - $ref: "#/components/parameters/userName"
@@ -372,8 +366,7 @@ paths:
           description: The user's notebook server has started
           content: {}
         202:
-          description:
-            The user's notebook server has not yet started, but has been
+          description: The user's notebook server has not yet started, but has been
             requested
           content: {}
       security:
@@ -387,8 +380,7 @@ paths:
         - $ref: "#/components/parameters/userName"
       responses:
         202:
-          description:
-            The user's notebook server has not yet stopped as it is taking
+          description: The user's notebook server has not yet stopped as it is taking
             a while to stop
           content: {}
         204:
@@ -420,8 +412,7 @@ paths:
           description: The user's notebook named-server has started
           content: {}
         202:
-          description:
-            The user's notebook named-server has not yet started, but has
+          description: The user's notebook named-server has not yet started, but has
             been requested
           content: {}
       security:
@@ -457,8 +448,7 @@ paths:
         required: false
       responses:
         202:
-          description:
-            The user's notebook named-server has not yet stopped as it
+          description: The user's notebook named-server has not yet stopped as it
             is taking a while to stop
           content: {}
         204:
@@ -472,8 +462,7 @@ paths:
     get:
       operationId: get-user-shared
       summary: List servers shared with user
-      description:
-        Returns list of Shares granting the user access to servers owned
+      description: Returns list of Shares granting the user access to servers owned
         by others (new in 5.0)
       parameters:
         - $ref: "#/components/parameters/userName"
@@ -587,8 +576,7 @@ paths:
                 expires_in:
                   type: number
                   example: 3600
-                  description:
-                    lifetime (in seconds) after which the requested token
+                  description: lifetime (in seconds) after which the requested token
                     will expire. Omit, or specify null or 0 for no expiration.
                 note:
                   type: string
@@ -1262,8 +1250,7 @@ paths:
     get:
       operationId: get-proxy
       summary: Get the proxy's routing table
-      description:
-        A convenience alias for getting the routing table directly from
+      description: A convenience alias for getting the routing table directly from
         the proxy
       parameters:
         - $ref: "#/components/parameters/paginationOffset"
@@ -1275,8 +1262,7 @@ paths:
             application/json:
               schema:
                 type: object
-                description:
-                  configurable-http-proxy routing table (see configurable-http-proxy
+                description: configurable-http-proxy routing table (see configurable-http-proxy
                   docs for details)
       security:
         - oauth2:
@@ -1296,8 +1282,7 @@ paths:
       summary: Notify the Hub about a new proxy
       description: Notifies the Hub of a new proxy to use.
       requestBody:
-        description:
-          Any values that have changed for the new proxy. All keys are
+        description: Any values that have changed for the new proxy. All keys are
           optional.
         content:
           application/json:
@@ -1389,8 +1374,7 @@ paths:
     get:
       operationId: get-auth-cookie
       summary: Identify a user from a cookie
-      description:
-        Used by single-user notebook servers to hand off cookie authentication
+      description: Used by single-user notebook servers to hand off cookie authentication
         to the Hub
       parameters:
         - name: cookie_name
@@ -1515,13 +1499,11 @@ paths:
               properties:
                 proxy:
                   type: boolean
-                  description:
-                    Whether the proxy should be shutdown as well (default
+                  description: Whether the proxy should be shutdown as well (default
                     from Hub config)
                 servers:
                   type: boolean
-                  description:
-                    Whether users' notebook servers should be shutdown
+                  description: Whether users' notebook servers should be shutdown
                     as well (default from Hub config)
         required: false
       responses:
@@ -1646,6 +1628,11 @@ components:
         name:
           type: string
           description: The user's name
+        kind:
+          type: string
+          description: the string 'user' to distinguish from 'service'
+          enum:
+            - user
         admin:
           type: boolean
           description: Whether the user is an admin
@@ -1661,8 +1648,7 @@ components:
             type: string
         server:
           type: string
-          description:
-            The user's notebook server's base URL, if running; null if
+          description: The user's notebook server's base URL, if running; null if
             not.
         pending:
           type: string
@@ -1694,8 +1680,7 @@ components:
       properties:
         name:
           type: string
-          description:
-            The server's name. The user's default server has an empty name
+          description: The server's name. The user's default server has an empty name
             ('')
         ready:
           type: boolean
@@ -1758,15 +1743,13 @@ components:
         state:
           type: object
           properties: {}
-          description:
-            Arbitrary internal state from this server's spawner. Only available
+          description: Arbitrary internal state from this server's spawner. Only available
             on the hub's users list or get-user-by-name method, and only with admin:users:server_state
             scope. None otherwise.
         user_options:
           type: object
           properties: {}
-          description:
-            User specified options for the user's spawned instance of a
+          description: User specified options for the user's spawned instance of a
             single-user server.
     RequestIdentity:
       description: |
@@ -1784,6 +1767,13 @@ components:
               service: "#/components/schemas/Service"
         - type: object
           properties:
+            kind:
+              type: string
+              description: |
+                'user' or 'service' depending on the entity which owns the token
+              enum:
+                - user
+                - service
             session_id:
               type:
                 - string
@@ -1820,6 +1810,11 @@ components:
         name:
           type: string
           description: The group's name
+        kind:
+          type: string
+          description: Always the string 'group'
+          enum:
+            - group
         users:
           type: array
           description: The names of users who are members of this group
@@ -1845,6 +1840,11 @@ components:
         name:
           type: string
           description: The service's name
+        kind:
+          type: string
+          description: the string 'service' to distinguish from 'user'
+          enum:
+            - service
         admin:
           type: boolean
           description: Whether the service is an admin
@@ -1918,8 +1918,7 @@ components:
           items:
             type: string
         group:
-          description:
-            the group being shared with (exactly one of 'user' or 'group'
+          description: the group being shared with (exactly one of 'user' or 'group'
             will be non-null, the other will be null)
           type:
             - object
@@ -1928,8 +1927,7 @@ components:
             name:
               type: string
         user:
-          description:
-            the user being shared with (exactly one of 'user' or 'group'
+          description: the user being shared with (exactly one of 'user' or 'group'
             will be non-null, the other will be null)
           type:
             - object
@@ -1943,8 +1941,7 @@ components:
           format: date-time
 
     ShareCode:
-      description:
-        A single sharing code. There is at most one of these objects per
+      description: A single sharing code. There is at most one of these objects per
         (server, user) or (server, group) combination.
       type: object
       properties:
@@ -1980,8 +1977,7 @@ components:
       properties:
         id:
           type: string
-          description:
-            The id of the API token. Used for modifying or deleting the
+          description: The id of the API token. Used for modifying or deleting the
             token.
         user:
           type: string
@@ -1991,22 +1987,19 @@ components:
           description: The service that owns the token (undefined of owned by a user)
         roles:
           type: array
-          description:
-            Deprecated in JupyterHub 3, always an empty list. Tokens have
+          description: Deprecated in JupyterHub 3, always an empty list. Tokens have
             'scopes' starting from JupyterHub 3.
           items:
             type: string
         scopes:
           type: array
-          description:
-            List of scopes this token has been assigned. New in JupyterHub
+          description: List of scopes this token has been assigned. New in JupyterHub
             3. In JupyterHub 2.x, tokens were assigned 'roles' instead of scopes.
           items:
             type: string
         note:
           type: string
-          description:
-            A note about the token, typically describing what it was created
+          description: A note about the token, typically describing what it was created
             for.
         created:
           type: string
@@ -2037,13 +2030,11 @@ components:
       properties:
         token:
           type: string
-          description:
-            The token itself. Only present in responses to requests for
+          description: The token itself. Only present in responses to requests for
             a new token.
         id:
           type: string
-          description:
-            The id of the API token. Used for modifying or deleting the
+          description: The id of the API token. Used for modifying or deleting the
             token.
         user:
           type: string
@@ -2053,22 +2044,19 @@ components:
           description: The service that owns the token (undefined of owned by a user)
         roles:
           type: array
-          description:
-            Deprecated in JupyterHub 3, always an empty list. Tokens have
+          description: Deprecated in JupyterHub 3, always an empty list. Tokens have
             'scopes' starting from JupyterHub 3.
           items:
             type: string
         scopes:
           type: array
-          description:
-            List of scopes this token has been assigned. New in JupyterHub
+          description: List of scopes this token has been assigned. New in JupyterHub
             3. In JupyterHub 2.x, tokens were assigned 'roles' instead of scopes.
           items:
             type: string
         note:
           type: string
-          description:
-            A note about the token, typically describing what it was created
+          description: A note about the token, typically describing what it was created
             for.
         created:
           type: string
@@ -2106,28 +2094,22 @@ components:
           tokenUrl: /hub/api/oauth2/token
           scopes:
             (no_scope): Identify the owner of the requesting entity.
-            self:
-              The user’s own resources _(metascope for users, resolves to (no_scope)
+            self: The user’s own resources _(metascope for users, resolves to (no_scope)
               for services)_
-            inherit:
-              Everything that the token-owning entity can access _(metascope
+            inherit: Everything that the token-owning entity can access _(metascope
               for tokens)_
-            admin-ui:
-              Access the admin page. Permission to take actions via the admin
+            admin-ui: Access the admin page. Permission to take actions via the admin
               page granted separately.
-            admin:users:
-              Read, modify, create, and delete users and their authentication
+            admin:users: Read, modify, create, and delete users and their authentication
               state, not including their servers or tokens. This is an extremely privileged
               scope and should be considered tantamount to superuser.
             admin:auth_state: Read a user’s authentication state.
-            users:
-              Read and write permissions to user models (excluding servers, tokens
+            users: Read and write permissions to user models (excluding servers, tokens
               and authentication state).
             delete:users: Delete users.
             list:users: List users, including at least their names.
-            read:users:
-              Read user models (including servers, tokens and authentication
-              state).
+            read:users: Read user models (including the URL of the default server
+              if it is running).
             read:users:name: Read names of users.
             read:users:groups: Read users’ group membership.
             read:users:activity: Read time of last user activity.
@@ -2136,27 +2118,23 @@ components:
             read:roles:services: Read service role assignments.
             read:roles:groups: Read group role assignments.
             users:activity: Update time of last user activity.
-            admin:servers:
-              Read, start, stop, create and delete user servers and their
+            admin:servers: Read, start, stop, create and delete user servers and their
               state.
             admin:server_state: Read and write users’ server state.
             servers: Start and stop user servers.
-            read:servers:
-              Read users’ names and their server models (excluding the
+            read:servers: Read users’ names and their server models (excluding the
               server state).
             delete:servers: Stop and delete users' servers.
             tokens: Read, write, create and delete user tokens.
             read:tokens: Read user tokens.
             admin:groups: Read and write group information, create and delete groups.
-            groups:
-              "Read and write group information, including adding/removing any
-              users to/from groups. Note: adding users to groups may affect permissions."
+            groups: 'Read and write group information, including adding/removing any
+              users to/from groups. Note: adding users to groups may affect permissions.'
             list:groups: List groups, including at least their names.
             read:groups: Read group models.
             read:groups:name: Read group names.
             delete:groups: Delete groups.
-            admin:services:
-              Create, read, update, delete services, not including services
+            admin:services: Create, read, update, delete services, not including services
               defined from config files.
             list:services: List services, including at least their names.
             read:services: Read service models.
@@ -2170,8 +2148,7 @@ components:
             read:groups:shares: Read servers shared with a group.
             read:shares: Read information about shared access to servers.
             shares: Manage access to shared servers.
-            proxy:
-              Read information about the proxy’s routing table, sync the Hub
+            proxy: Read information about the proxy’s routing table, sync the Hub
               with the proxy and notify the Hub about a new proxy.
             shutdown: Shutdown the hub.
             read:metrics: Read prometheus metrics.

docs/source/conf.py

@@ -12,6 +12,7 @@ from pathlib import Path
 from urllib.request import urlretrieve
 
 from docutils import nodes
+from intersphinx_registry import get_intersphinx_mapping
 from ruamel.yaml import YAML
 from sphinx.directives.other import SphinxDirective
 from sphinx.util import logging
@@ -294,6 +295,8 @@ linkcheck_ignore = [
     r"https://linux.die.net/.*",  # linux.die.net seems to block requests from CI with 403 sometimes
     # don't check links to unpublished advisories
     r"https://github.com/jupyterhub/jupyterhub/security/advisories/.*",
+    # Occasionally blocks CI checks with 403
+    r"https://www\.mysql\.com",
 ]
 linkcheck_anchors_ignore = [
     "/#!",
@@ -303,12 +306,15 @@ linkcheck_anchors_ignore = [
 # -- Intersphinx -------------------------------------------------------------
 # ref: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
 #
-intersphinx_mapping = {
-    "python": ("https://docs.python.org/3/", None),
-    "tornado": ("https://www.tornadoweb.org/en/stable/", None),
-    "jupyter-server": ("https://jupyter-server.readthedocs.io/en/stable/", None),
-    "nbgitpuller": ("https://nbgitpuller.readthedocs.io/en/latest", None),
-}
+
+intersphinx_mapping = get_intersphinx_mapping(
+    packages={
+        "python",
+        "tornado",
+        "jupyter-server",
+        "nbgitpuller",
+    }
+)
 
 # -- Options for the opengraph extension -------------------------------------
 # ref: https://github.com/wpilibsuite/sphinxext-opengraph#options

docs/source/explanation/capacity-planning.md

@@ -208,7 +208,7 @@ mybinder.org node CPU usage is low with 50-150 users sharing just 8 cores
 
 ### Concurrent users and culling idle servers
 
-Related to [][idleness], all of these resource consumptions and limits are calculated based on **concurrently active users**,
+Related to [](idleness), all of these resource consumptions and limits are calculated based on **concurrently active users**,
 not total users.
 You might have 10,000 users of your JupyterHub deployment, but only 100 of them running at any given time.
 That 100 is the main number you need to use for your capacity planning.

docs/source/explanation/concepts.md

@@ -3,7 +3,7 @@
 # JupyterHub: A conceptual overview
 
 ```{warning}
-This page could is missing cross-links to other parts of
+This page could be missing cross-links to other parts of
 the documentation. You can help by adding them!
 ```
 
@@ -88,7 +88,7 @@ The following authenticators are included with JupyterHub:
   of a ssh server, but providing a web-browser based way to access the
   machine.
 
-There are [plenty of others to choose from](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators).
+There are [plenty of others to choose from](authenticators-reference).
 You can connect to almost any other existing service to manage your
 users. You either use all users from this other service (e.g. your
 company), or enable only the allowed users (e.g. your group's

docs/source/faq/institutional-faq.md

@@ -66,7 +66,7 @@ industry, and government research labs. It is most-commonly used by two kinds of
 Here is a sample of organizations that use JupyterHub:
 
 - **Universities and colleges**: UC Berkeley, UC San Diego, Cal Poly SLO, Harvard University, University of Chicago,
-  University of Oslo, University of Sheffield, Université Paris Sud, University of Versailles
+  University of Oslo, University of Sheffield, Université Paris Sud, University of Versailles, University of Portland
 - **Research laboratories**: NASA, NCAR, NOAA, the Large Synoptic Survey Telescope, Brookhaven National Lab,
   Minnesota Supercomputing Institute, ALCF, CERN, Lawrence Livermore National Laboratory, HUNT
 - **Online communities**: Pangeo, Quantopian, mybinder.org, MathHub, Open Humans

docs/source/faq/troubleshooting.md

@@ -198,6 +198,23 @@ With a docker container, pass in the environment variable with the run command:
 
 [This example](https://github.com/jupyterhub/jupyterhub/tree/HEAD/examples/service-notebook/external) demonstrates how to combine the use of the `jupyterhub-singleuser` environment variables when launching a Notebook as an externally managed service.
 
+### Jupyter Notebook/Lab can be launched, but notebooks seem to hang when trying to execute a cell
+
+This often occurs when your browser is unable to open a websocket connection to a Jupyter kernel.
+
+#### Diagnose
+
+Open your browser console, e.g. [Chrome](https://developer.chrome.com/docs/devtools/console), [Firefox](https://firefox-source-docs.mozilla.org/devtools-user/web_console/).
+If you see errors related to opening websockets this is likely to be the problem.
+
+#### Solutions
+
+This could be caused by anything related to the network between your computer/browser and the server running JupyterHub, such as:
+
+- reverse proxies (see {ref}`howto:config:reverse-proxy` for example configurations)
+- anti-virus or firewalls running on your computer or JupyterHub server
+- transparent proxies running on your network
+
 ## How do I...?
 
 ### Use a chained SSL certificate
@@ -259,17 +276,6 @@ the entire filesystem and set the default to the user's home directory.
     c.Spawner.notebook_dir = '/'
     c.Spawner.default_url = '/home/%U' # %U will be replaced with the username
 
-### How do I increase the number of pySpark executors on YARN?
-
-From the command line, pySpark executors can be configured using a command
-similar to this one:
-
-    pyspark --total-executor-cores 2 --executor-memory 1G
-
-[Cloudera documentation for configuring spark on YARN applications](https://www.cloudera.com/documentation/enterprise/latest/topics/cdh_ig_running_spark_on_yarn.html#spark_on_yarn_config_apps)
-provides additional information. The [pySpark configuration documentation](https://spark.apache.org/docs/0.9.0/configuration.html)
-is also helpful for programmatic configuration examples.
-
 ### How do I use JupyterLab's pre-release version with JupyterHub?
 
 While JupyterLab is still under active development, we have had users
@@ -300,6 +306,52 @@ notebook servers to default to JupyterLab:
 
 Users will need a GitHub account to log in and be authenticated by the Hub.
 
+### I'm seeing "403 Forbidden XSRF cookie does not match POST" when users try to login
+
+During login, JupyterHub takes the request IP into account for CSRF protection.
+If proxies are not configured to properly set forwarded ips,
+JupyterHub will see all requests as coming from an internal ip,
+likely the ip of the proxy itself.
+You can see this in the JupyterHub logs, which log the ip address of requests.
+If most requests look like they are coming from a small number `10.0.x.x` or `172.16.x.x` ips, the proxy is not forwarding the true request ip properly.
+If the proxy has multiple replicas,
+then it is likely the ip may change from one request to the next,
+leading to this error during login:
+
+> 403 Forbidden XSRF cookie does not match POST argument
+
+The best way to fix this is to ensure your proxies set the forwarded headers, e.g. for nginx:
+
+```nginx
+proxy_set_header X-Real-IP $remote_addr;
+proxy_set_header Host $http_host;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+```
+
+But if this is not available to you, you can instruct jupyterhub to ignore IPs from certain networks
+with the environment variable `$JUPYTERHUB_XSRF_ANONYMOUS_IP_CIDRS`.
+For example, to ignore the common [private networks](https://en.wikipedia.org/wiki/Private_network#Private_IPv4_addresses):
+
+```bash
+export JUPYTERHUB_XSRF_ANONYMOUS_IP_CIDRS="10.0.0.0/8;172.16.0.0/12;192.168.0.0/16"
+```
+
+The result will be that any request from an ip on one of these networks will be treated as coming from the same source.
+
+To totally disable taking the ip into consideration, set
+
+```bash
+export JUPYTERHUB_XSRF_ANONYMOUS_IP_CIDRS="0.0.0.0/0"
+```
+
+If your proxy sets its own headers to identify a browser origin, you can instruct JupyterHub to use those:
+
+```bash
+export JUPYTERHUB_XSRF_ANONYMOUS_ID_HEADERS="My-Custom-Header;User-Agent"
+```
+
+Again, these things are only used to compute the XSRF token used while a user is not logged in (i.e. during login itself).
+
 ### How do I set up rotating daily logs?
 
 You can do this with [logrotate](https://linux.die.net/man/8/logrotate),

docs/source/howto/configuration/config-sudo.md

@@ -125,7 +125,7 @@ the shadow password database.
 **Note:** On [Fedora based distributions](https://fedoraproject.org/wiki/List_of_Fedora_remixes) there is no clear way to configure
 the PAM database to allow sufficient access for authenticating with the target user's password
 from JupyterHub. As a workaround we recommend use an
-[alternative authentication method](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators).
+[alternative authentication method](authenticators-reference).
 
 ```bash
 $ ls -l /etc/shadow

docs/source/rbac/generate-scope-table.py

@@ -14,26 +14,52 @@ The files are:
        scopes descriptions are updated in it.
 """
 
-import os
 from collections import defaultdict
 from pathlib import Path
-from subprocess import run
 
 from pytablewriter import MarkdownTableWriter
 from ruamel.yaml import YAML
 
-from jupyterhub import __version__
-from jupyterhub.scopes import scope_definitions
-
-HERE = os.path.abspath(os.path.dirname(__file__))
-DOCS = Path(HERE).parent.parent.absolute()
+HERE = Path(__file__).parent.absolute()
+DOCS = HERE / ".." / ".."
 REST_API_YAML = DOCS.joinpath("source", "_static", "rest-api.yml")
-SCOPE_TABLE_MD = Path(HERE).joinpath("scope-table.md")
+SCOPE_TABLE_MD = HERE.joinpath("scope-table.md")
+
+
+def _load_jupyterhub_info():
+    """
+    The equivalent of
+
+        from jupyterhub import __version__
+        from jupyterhub.scopes import scope_definitions
+
+    but without needing to install JupyterHub and dependencies
+    so that we can run this pre-commit
+    """
+    root = HERE / ".." / ".." / ".."
+    g = {}
+    exec((root / "jupyterhub" / "_version.py").read_text(), g)
+
+    # To avoid parsing the whole of scope_definitions.py just pull out
+    # the relevant lines
+    scopes_file = root / "jupyterhub" / "scopes.py"
+    scopes_lines = []
+    for line in scopes_file.read_text().splitlines():
+        if not scopes_lines and line == "scope_definitions = {":
+            scopes_lines.append(line)
+        elif scopes_lines:
+            scopes_lines.append(line)
+            if line == "}":
+                break
+
+    exec("\n".join(scopes_lines), g)
+
+    return g["__version__"], g["scope_definitions"]
 
 
 class ScopeTableGenerator:
     def __init__(self):
-        self.scopes = scope_definitions
+        self.version, self.scopes = _load_jupyterhub_info()
 
     @classmethod
     def create_writer(cls, table_name, headers, values):
@@ -131,7 +157,7 @@ class ScopeTableGenerator:
         with open(filename) as f:
             content = yaml.load(f.read())
 
-        content["info"]["version"] = __version__
+        content["info"]["version"] = self.version
         for scope in self.scopes:
             description = self.scopes[scope]['description']
             doc_description = self.scopes[scope].get('doc_description', '')
@@ -145,12 +171,6 @@ class ScopeTableGenerator:
         with open(filename, 'w') as f:
             yaml.dump(content, f)
 
-        run(
-            ['pre-commit', 'run', 'prettier', '--files', filename],
-            cwd=HERE,
-            check=False,
-        )
-
 
 def main():
     table_generator = ScopeTableGenerator()

docs/source/rbac/scope-table.md

@@ -0,0 +1,58 @@
+Table 1. Available scopes and their hierarchy
+|                                    Scope                                    |                                                                                         Grants permission to:                                                                                         |
+| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `(no_scope)`                                                                | Identify the owner of the requesting entity.                                                                                                                                                          |
+| `self`                                                                      | The user’s own resources _(metascope for users, resolves to (no_scope) for services)_                                                                                                                 |
+| `inherit`                                                                   | Everything that the token-owning entity can access _(metascope for tokens)_                                                                                                                           |
+| `admin-ui`                                                                  | Access the admin page. Permission to take actions via the admin page granted separately.                                                                                                              |
+| `admin:users`                                                               | Read, modify, create, and delete users and their authentication state, not including their servers or tokens. This is an extremely privileged scope and should be considered tantamount to superuser. |
+|    `admin:auth_state`                                        | Read a user’s authentication state.                                                                                                                                                                   |
+|    `users`                                                   | Read and write permissions to user models (excluding servers, tokens and authentication state).                                                                                                       |
+|       `read:users`                            | Read user models (including the URL of the default server if it is running).                                                                                                                          |
+|          `read:users:name`     | Read names of users.                                                                                                                                                                                  |
+|          `read:users:groups`   | Read users’ group membership.                                                                                                                                                                         |
+|          `read:users:activity` | Read time of last user activity.                                                                                                                                                                      |
+|       `list:users`                            | List users, including at least their names.                                                                                                                                                           |
+|          `read:users:name`     | Read names of users.                                                                                                                                                                                  |
+|       `users:activity`                        | Update time of last user activity.                                                                                                                                                                    |
+|          `read:users:activity` | Read time of last user activity.                                                                                                                                                                      |
+|    `read:roles:users`                                        | Read user role assignments.                                                                                                                                                                           |
+|    `delete:users`                                            | Delete users.                                                                                                                                                                                         |
+| `read:roles`                                                                | Read role assignments.                                                                                                                                                                                |
+|    `read:roles:users`                                        | Read user role assignments.                                                                                                                                                                           |
+|    `read:roles:services`                                     | Read service role assignments.                                                                                                                                                                        |
+|    `read:roles:groups`                                       | Read group role assignments.                                                                                                                                                                          |
+| `admin:servers`                                                             | Read, start, stop, create and delete user servers and their state.                                                                                                                                    |
+|    `admin:server_state`                                      | Read and write users’ server state.                                                                                                                                                                   |
+|    `servers`                                                 | Start and stop user servers.                                                                                                                                                                          |
+|       `read:servers`                          | Read users’ names and their server models (excluding the server state).                                                                                                                               |
+|          `read:users:name`     | Read names of users.                                                                                                                                                                                  |
+|       `delete:servers`                        | Stop and delete users' servers.                                                                                                                                                                       |
+| `tokens`                                                                    | Read, write, create and delete user tokens.                                                                                                                                                           |
+|    `read:tokens`                                             | Read user tokens.                                                                                                                                                                                     |
+| `admin:groups`                                                              | Read and write group information, create and delete groups.                                                                                                                                           |
+|    `groups`                                                  | Read and write group information, including adding/removing any users to/from groups. Note: adding users to groups may affect permissions.                                                            |
+|       `read:groups`                           | Read group models.                                                                                                                                                                                    |
+|          `read:groups:name`    | Read group names.                                                                                                                                                                                     |
+|       `list:groups`                           | List groups, including at least their names.                                                                                                                                                          |
+|          `read:groups:name`    | Read group names.                                                                                                                                                                                     |
+|    `read:roles:groups`                                       | Read group role assignments.                                                                                                                                                                          |
+|    `delete:groups`                                           | Delete groups.                                                                                                                                                                                        |
+| `admin:services`                                                            | Create, read, update, delete services, not including services defined from config files.                                                                                                              |
+|    `list:services`                                           | List services, including at least their names.                                                                                                                                                        |
+|       `read:services:name`                    | Read service names.                                                                                                                                                                                   |
+|    `read:services`                                           | Read service models.                                                                                                                                                                                  |
+|       `read:services:name`                    | Read service names.                                                                                                                                                                                   |
+|    `read:roles:services`                                     | Read service role assignments.                                                                                                                                                                        |
+| `read:hub`                                                                  | Read detailed information about the Hub.                                                                                                                                                              |
+| `access:services`                                                           | Access services via API or browser.                                                                                                                                                                   |
+| `shares`                                                                    | Manage access to shared servers.                                                                                                                                                                      |
+|    `access:servers`                                          | Access user servers via API or browser.                                                                                                                                                               |
+|    `read:shares`                                             | Read information about shared access to servers.                                                                                                                                                      |
+|    `users:shares`                                            | Read and revoke a user's access to shared servers.                                                                                                                                                    |
+|       `read:users:shares`                     | Read servers shared with a user.                                                                                                                                                                      |
+|    `groups:shares`                                           | Read and revoke a group's access to shared servers.                                                                                                                                                   |
+|       `read:groups:shares`                    | Read servers shared with a group.                                                                                                                                                                     |
+| `proxy`                                                                     | Read information about the proxy’s routing table, sync the Hub with the proxy and notify the Hub about a new proxy.                                                                                   |
+| `shutdown`                                                                  | Shutdown the hub.                                                                                                                                                                                     |
+| `read:metrics`                                                              | Read prometheus metrics.                                                                                                                                                                              |

docs/source/reference/api/auth.md

@@ -1,33 +1,42 @@
 # Authenticators
 
-## Module: {mod}`jupyterhub.auth`
-
 ```{eval-rst}
-.. automodule:: jupyterhub.auth
+.. module:: jupyterhub.auth
 ```
 
-### {class}`Authenticator`
+## {class}`Authenticator`
 
 ```{eval-rst}
 .. autoconfigurable:: Authenticator
    :members:
 ```
 
-### {class}`LocalAuthenticator`
+## {class}`LocalAuthenticator`
 
 ```{eval-rst}
 .. autoconfigurable:: LocalAuthenticator
    :members:
 ```
 
-### {class}`PAMAuthenticator`
+## {class}`PAMAuthenticator`
 
 ```{eval-rst}
 .. autoconfigurable:: PAMAuthenticator
 ```
 
-### {class}`DummyAuthenticator`
+## {class}`DummyAuthenticator`
 
 ```{eval-rst}
 .. autoconfigurable:: DummyAuthenticator
 ```
+
+```{eval-rst}
+.. module:: jupyterhub.authenticators.shared
+```
+
+## {class}`SharedPasswordAuthenticator`
+
+```{eval-rst}
+.. autoconfigurable:: SharedPasswordAuthenticator
+   :no-inherited-members:
+```

docs/source/reference/api/spawner.md

@@ -10,7 +10,7 @@
 
 ```{eval-rst}
 .. autoconfigurable:: Spawner
-   :members: options_from_form, poll, start, stop, get_args, get_env, get_state, template_namespace, format_string, create_certs, move_certs
+   :members: options_from_form, user_options, poll, start, stop, get_args, get_env, get_state, template_namespace, format_string, create_certs, move_certs
 ```
 
 ### {class}`LocalProcessSpawner`

docs/source/reference/authenticators.md

@@ -36,16 +36,56 @@ A [generic implementation](https://github.com/jupyterhub/oauthenticator/blob/mas
 
 ## The Dummy Authenticator
 
-When testing, it may be helpful to use the
-{class}`~.jupyterhub.auth.DummyAuthenticator`. This allows for any username and
-password unless a global password has been set. Once set, any username will
-still be accepted but the correct password will need to be provided.
+When testing, it may be helpful to use the {class}`~.jupyterhub.auth.DummyAuthenticator`:
+
+```python
+c.JupyterHub.authenticator_class = "dummy"
+# always a good idea to limit to localhost when testing with an insecure config
+c.JupyterHub.ip = "127.0.0.1"
+```
+
+This allows for any username and password to login, and is _wildly_ insecure.
+
+To use, specify
+
+```python
+c.JupyterHub.authenticator_class = "dummy"
+```
 
 :::{versionadded} 5.0
 The DummyAuthenticator's default `allow_all` is True,
 unlike most other Authenticators.
 :::
 
+:::{deprecated} 5.3
+Setting a password on DummyAuthenticator is deprecated.
+Use the new {class}`~.jupyterhub.authenticators.shared.SharedPasswordAuthenticator`
+if you want to set a shared password for users.
+:::
+
+## Shared Password Authenticator
+
+:::{versionadded} 5.3
+{class}`~.jupyterhub.authenticators.shared.SharedPasswordAuthenticator` is added and [DummyAuthenticator.password](#DummyAuthenticator.password) is deprecated.
+:::
+
+For short-term deployments like workshops where there is no real user data to protect and you trust users to not abuse the system or each other,
+{class}`~.jupyterhub.authenticators.shared.SharedPasswordAuthenticator` can be used.
+
+Set a [user password](#SharedPasswordAuthenticator.user_password) for users to login:
+
+```python
+c.JupyterHub.authenticator_class = "shared-password"
+c.SharedPasswordAuthenticator.user_password = "my-workshop-2042"
+```
+
+You can also grant admin users access by adding them to `admin_users` and setting a separate [admin password](#SharedPasswordAuthenticator.admin_password):
+
+```python
+c.Authenticator.admin_users = {"danger", "eggs"}
+c.SharedPasswordAuthenticator.admin_password = "extra-super-secret-secure-password"
+```
+
 ## Additional Authenticators
 
 Additional authenticators can be found on GitHub
@@ -469,8 +509,19 @@ which is a list of group names the user should be a member of:
 - If `None` is returned, no changes are made to the user's group membership
 
 If authenticator-managed groups are enabled,
-all group-management via the API is disabled,
-and roles cannot be specified with `load_groups` traitlet.
+groups cannot be specified with `load_groups` traitlet.
+
+:::{warning}
+When `manage_groups` is True,
+managing groups via the API is still permitted via the `admin:groups` scope (starting with 5.3),
+but any time a user logs in their group membership is completely reset via the login process.
+So it only really makes sense to make manual changes via the API that reflect upstream changes which are not automatically propagated, such as group deletion.
+
+:::
+
+:::{versionchanged} 5.3
+Prior to JupyterHub 5.3, all group management via the API was disabled if `Authenticator.manage_groups` is True.
+:::
 
 (authenticator-roles)=
 

docs/source/reference/changelog.md

@@ -20,6 +20,174 @@ Contributors to major version bumps in JupyterHub include:
 
 ## [Unreleased]
 
+## 5.3
+
+### 5.3.0 - 2025-04-15
+
+5.3.0 is a small release with lots of bugfixes and a few new features, including more configuration options for:
+
+- [User options for Spawners](#spawner_user_options)
+- [Prometheus bucket sizes](#monitoring_bucket_sizes)
+- A new [SharedPasswordAuthenticator](#SharedPasswordAuthenticator)
+
+We have also changed how we build the `jupyterhub` container images.
+Images are now built from [](https://github.com/jupyterhub/jupyterhub-container-images) instead of the JupyterHub repo.
+The main user-facing implication of this is that image for a given JupyterHub version will be rebuilt,
+which has the following consequences:
+
+1. `quay.io/jupyterhub/jupyterhub:5.3.0` will get security and dependency updates, which has the possibility of breaking things.
+2. Version tags are now also published with a build number that is incremented on each build of a given version.
+   So if you use a tag like `quay.io/jupyterhub/jupyterhub:5.3.0-1`, that image will not get updates.
+3. `jupyterhub-onbuild` images will no longer be published.
+   This image only saved one `COPY` line in your Dockerfile, so is replaced with the base `jupyterhub` image.
+
+([full changelog](https://github.com/jupyterhub/jupyterhub/compare/5.2.1...5.3.0))
+
+#### New features added
+
+- Allow configuration of stop duration metric buckets [#5045](https://github.com/jupyterhub/jupyterhub/pull/5045) ([@srikanthchelluri](https://github.com/srikanthchelluri), [@minrk](https://github.com/minrk))
+- Add SharedPasswordAuthenticator [#5037](https://github.com/jupyterhub/jupyterhub/pull/5037) ([@yuvipanda](https://github.com/yuvipanda), [@minrk](https://github.com/minrk), [@jules32](https://github.com/jules32), [@manics](https://github.com/manics), [@ateucher](https://github.com/ateucher))
+- add apply_user_options hook [#5012](https://github.com/jupyterhub/jupyterhub/pull/5012) ([@minrk](https://github.com/minrk), [@manics](https://github.com/manics), [@akhmerov](https://github.com/akhmerov))
+- allow group management API when managed_groups is True [#5004](https://github.com/jupyterhub/jupyterhub/pull/5004) ([@minrk](https://github.com/minrk), [@manics](https://github.com/manics))
+- Add `$JUPYTERHUB_XSRF_ANONYMOUS_{IP_CIDRS|HEADERS}` config for managing anonymous xsrf ids [#4991](https://github.com/jupyterhub/jupyterhub/pull/4991) ([@minrk](https://github.com/minrk), [@manics](https://github.com/manics), [@samyuh](https://github.com/samyuh))
+- Allow custom login input validation [#4979](https://github.com/jupyterhub/jupyterhub/pull/4979) ([@tlvu](https://github.com/tlvu), [@minrk](https://github.com/minrk))
+- Allow configuration of bucket sizes in metrics - #4833 [#4967](https://github.com/jupyterhub/jupyterhub/pull/4967) ([@kireetb](https://github.com/kireetb), [@minrk](https://github.com/minrk), [@manics](https://github.com/manics))
+
+#### Enhancements made
+
+- improve xsrf errors on login [#5022](https://github.com/jupyterhub/jupyterhub/pull/5022) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio))
+- More IPv6: Use bare IPv6 for configuration, use `[ipv6]` when displaying IPv6 outputs [#4988](https://github.com/jupyterhub/jupyterhub/pull/4988) ([@manics](https://github.com/manics), [@minrk](https://github.com/minrk))
+- Allow CORS requests to /hub/api by default [#4966](https://github.com/jupyterhub/jupyterhub/pull/4966) ([@agoose77](https://github.com/agoose77), [@minrk](https://github.com/minrk), [@yuvipanda](https://github.com/yuvipanda), [@manics](https://github.com/manics))
+
+#### Bugs fixed
+
+- url_path_join: handle empty trailing components [#5033](https://github.com/jupyterhub/jupyterhub/pull/5033) ([@manics](https://github.com/manics), [@minrk](https://github.com/minrk))
+- Try to improve admin paging consistency [#5025](https://github.com/jupyterhub/jupyterhub/pull/5025) ([@minrk](https://github.com/minrk))
+- make sure custom error messages are shown on regular error pages [#5020](https://github.com/jupyterhub/jupyterhub/pull/5020) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio))
+- raise spawn error if spawn failed while polling [#5011](https://github.com/jupyterhub/jupyterhub/pull/5011) ([@minrk](https://github.com/minrk))
+- Singleuser: listen on IPv4 and IPv6 if ip=="" [#4986](https://github.com/jupyterhub/jupyterhub/pull/4986) ([@manics](https://github.com/manics), [@minrk](https://github.com/minrk))
+- make insecure-login-warning visible in dark mode [#4982](https://github.com/jupyterhub/jupyterhub/pull/4982) ([@mishaschwartz](https://github.com/mishaschwartz), [@minrk](https://github.com/minrk))
+- Fix bug in `GroupEdit`: Users being reset when clicking the button to edit a group [#4968](https://github.com/jupyterhub/jupyterhub/pull/4968) ([@oboki](https://github.com/oboki), [@minrk](https://github.com/minrk))
+- Fixed code formatting for implicit_spawn_seconds (#4949) [#4950](https://github.com/jupyterhub/jupyterhub/pull/4950) ([@millenniumhand](https://github.com/millenniumhand), [@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio), [@manics](https://github.com/manics))
+- Stop All: include named servers [#4939](https://github.com/jupyterhub/jupyterhub/pull/4939) ([@manics](https://github.com/manics), [@minrk](https://github.com/minrk))
+
+#### Maintenance and upkeep improvements
+
+- set default permissions on workflows [#5049](https://github.com/jupyterhub/jupyterhub/pull/5049) ([@minrk](https://github.com/minrk))
+- skip js build on readthedocs [#5036](https://github.com/jupyterhub/jupyterhub/pull/5036) ([@minrk](https://github.com/minrk))
+- jsx: update and address eslint [#5030](https://github.com/jupyterhub/jupyterhub/pull/5030) ([@minrk](https://github.com/minrk))
+- stop publishing images from jupyterhub/jupyterhub [#5024](https://github.com/jupyterhub/jupyterhub/pull/5024) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio), [@manics](https://github.com/manics))
+- try to fix flaky spawn_pending browser test [#5023](https://github.com/jupyterhub/jupyterhub/pull/5023) ([@minrk](https://github.com/minrk))
+- add some debugging output for intermittent share code failure [#5021](https://github.com/jupyterhub/jupyterhub/pull/5021) ([@minrk](https://github.com/minrk))
+- temporarily disable docker build on ci [#5010](https://github.com/jupyterhub/jupyterhub/pull/5010) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio))
+- MockHub: randomize hub and proxy API ports [#5007](https://github.com/jupyterhub/jupyterhub/pull/5007) ([@manics](https://github.com/manics), [@minrk](https://github.com/minrk))
+- don't install unused browsers for playwright [#4990](https://github.com/jupyterhub/jupyterhub/pull/4990) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio))
+- close tornado FDs without closing asyncio loop [#4984](https://github.com/jupyterhub/jupyterhub/pull/4984) ([@minrk](https://github.com/minrk))
+- Standard formatting in LICENSE [#4975](https://github.com/jupyterhub/jupyterhub/pull/4975) ([@SamuelMarks](https://github.com/SamuelMarks), [@minrk](https://github.com/minrk), [@manics](https://github.com/manics))
+- Replace react-router-dom@6 with react-router@7 [#4961](https://github.com/jupyterhub/jupyterhub/pull/4961) ([@manics](https://github.com/manics), [@minrk](https://github.com/minrk))
+- Use intersphinx-registry to keep intersphinx URLs up to date. [#4948](https://github.com/jupyterhub/jupyterhub/pull/4948) ([@Carreau](https://github.com/Carreau), [@minrk](https://github.com/minrk), [@manics](https://github.com/manics))
+
+#### Documentation improvements
+
+- Fix outdated GitHub Wiki links in documentation [#5047](https://github.com/jupyterhub/jupyterhub/pull/5047) ([@chilin0525](https://github.com/chilin0525), [@minrk](https://github.com/minrk))
+- Fix broken link to `idleness` section in capacity-planning.md [#5046](https://github.com/jupyterhub/jupyterhub/pull/5046) ([@chilin0525](https://github.com/chilin0525), [@consideRatio](https://github.com/consideRatio))
+- changelog for 5.3.0 (RC) [#5042](https://github.com/jupyterhub/jupyterhub/pull/5042) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio))
+- Add instruction on how to select dummy authenticator [#5041](https://github.com/jupyterhub/jupyterhub/pull/5041) ([@ktaletsk](https://github.com/ktaletsk), [@GeorgianaElena](https://github.com/GeorgianaElena), [@minrk](https://github.com/minrk))
+- rm outdated claim that "copy shareable link" does not work in JupyterHub [#5018](https://github.com/jupyterhub/jupyterhub/pull/5018) ([@ctcjab](https://github.com/ctcjab), [@manics](https://github.com/manics))
+- Automatically generate rest-api.yml and scopes.md using pre-commit [#5009](https://github.com/jupyterhub/jupyterhub/pull/5009) ([@manics](https://github.com/manics), [@minrk](https://github.com/minrk))
+- doc: read:users only includes server not servers [#5006](https://github.com/jupyterhub/jupyterhub/pull/5006) ([@manics](https://github.com/manics), [@minrk](https://github.com/minrk))
+- make sure 'kind' shows up in rest api [#4995](https://github.com/jupyterhub/jupyterhub/pull/4995) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio))
+- Missing breaking change in 5.0.0 changelog: URL tokens [#4978](https://github.com/jupyterhub/jupyterhub/pull/4978) ([@manics](https://github.com/manics), [@minrk](https://github.com/minrk))
+- Update `load_groups` config in collaboration-users.md [#4964](https://github.com/jupyterhub/jupyterhub/pull/4964) ([@jrdnbradford](https://github.com/jrdnbradford), [@minrk](https://github.com/minrk), [@manics](https://github.com/manics))
+- Document Spawner.oauth_client_allowed_scopes always allows access [#4955](https://github.com/jupyterhub/jupyterhub/pull/4955) ([@manics](https://github.com/manics), [@minrk](https://github.com/minrk))
+- mention that `auth_refresh_age = 0` disables time-based refresh_user [#4947](https://github.com/jupyterhub/jupyterhub/pull/4947) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio))
+- add traitlets default import to auth allow_all override example for completeness [#4946](https://github.com/jupyterhub/jupyterhub/pull/4946) ([@kellyrowland](https://github.com/kellyrowland), [@minrk](https://github.com/minrk))
+
+#### Contributors to this release
+
+The following people contributed discussions, new ideas, code and documentation contributions, and review.
+See [our definition of contributors](https://github-activity.readthedocs.io/en/latest/#how-does-this-tool-define-contributions-in-the-reports).
+
+([GitHub contributors page for this release](https://github.com/jupyterhub/jupyterhub/graphs/contributors?from=2024-10-21&to=2025-04-15&type=c))
+
+@adsche ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aadsche+updated%3A2024-10-21..2025-04-15&type=Issues)) | @agoose77 ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aagoose77+updated%3A2024-10-21..2025-04-15&type=Issues)) | @akhmerov ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aakhmerov+updated%3A2024-10-21..2025-04-15&type=Issues)) | @ateucher ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aateucher+updated%3A2024-10-21..2025-04-15&type=Issues)) | @Carreau ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3ACarreau+updated%3A2024-10-21..2025-04-15&type=Issues)) | @chilin0525 ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Achilin0525+updated%3A2024-10-21..2025-04-15&type=Issues)) | @consideRatio ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3AconsideRatio+updated%3A2024-10-21..2025-04-15&type=Issues)) | @ctcjab ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Actcjab+updated%3A2024-10-21..2025-04-15&type=Issues)) | @davidbrochart ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Adavidbrochart+updated%3A2024-10-21..2025-04-15&type=Issues)) | @GeorgianaElena ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3AGeorgianaElena+updated%3A2024-10-21..2025-04-15&type=Issues)) | @jrdnbradford ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Ajrdnbradford+updated%3A2024-10-21..2025-04-15&type=Issues)) | @jules32 ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Ajules32+updated%3A2024-10-21..2025-04-15&type=Issues)) | @kellyrowland ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Akellyrowland+updated%3A2024-10-21..2025-04-15&type=Issues)) | @kireetb ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Akireetb+updated%3A2024-10-21..2025-04-15&type=Issues)) | @ktaletsk ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aktaletsk+updated%3A2024-10-21..2025-04-15&type=Issues)) | @manics ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Amanics+updated%3A2024-10-21..2025-04-15&type=Issues)) | @millenniumhand ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Amillenniumhand+updated%3A2024-10-21..2025-04-15&type=Issues)) | @minrk ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aminrk+updated%3A2024-10-21..2025-04-15&type=Issues)) | @mishaschwartz ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Amishaschwartz+updated%3A2024-10-21..2025-04-15&type=Issues)) | @oboki ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aoboki+updated%3A2024-10-21..2025-04-15&type=Issues)) | @SamuelMarks ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3ASamuelMarks+updated%3A2024-10-21..2025-04-15&type=Issues)) | @samyuh ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Asamyuh+updated%3A2024-10-21..2025-04-15&type=Issues)) | @srikanthchelluri ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Asrikanthchelluri+updated%3A2024-10-21..2025-04-15&type=Issues)) | @tlvu ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Atlvu+updated%3A2024-10-21..2025-04-15&type=Issues)) | @yuvipanda ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Ayuvipanda+updated%3A2024-10-21..2025-04-15&type=Issues))
+
+## 5.2
+
+### 5.2.1 - 2024-10-21
+
+([full changelog](https://github.com/jupyterhub/jupyterhub/compare/5.2.0...5.2.1))
+
+#### Enhancements made
+
+- informative error on missing dependencies for singleuser server [#4934](https://github.com/jupyterhub/jupyterhub/pull/4934) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio))
+
+#### Bugs fixed
+
+- Abort jupyterhub startup only if managed services fail [#4930](https://github.com/jupyterhub/jupyterhub/pull/4930) ([@consideRatio](https://github.com/consideRatio), [@minrk](https://github.com/minrk))
+- Loaded EntryPointTypes are types, not instances [#4922](https://github.com/jupyterhub/jupyterhub/pull/4922) ([@manics](https://github.com/manics), [@minrk](https://github.com/minrk))
+
+#### Documentation improvements
+
+- Remove out-of-date info from subdomain_hook doc [#4932](https://github.com/jupyterhub/jupyterhub/pull/4932) ([@manics](https://github.com/manics), [@minrk](https://github.com/minrk))
+
+#### Contributors to this release
+
+The following people contributed discussions, new ideas, code and documentation contributions, and review.
+See [our definition of contributors](https://github-activity.readthedocs.io/en/latest/#how-does-this-tool-define-contributions-in-the-reports).
+
+([GitHub contributors page for this release](https://github.com/jupyterhub/jupyterhub/graphs/contributors?from=2024-10-01&to=2024-10-21&type=c))
+
+@consideRatio ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3AconsideRatio+updated%3A2024-10-01..2024-10-21&type=Issues)) | @manics ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Amanics+updated%3A2024-10-01..2024-10-21&type=Issues)) | @minrk ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aminrk+updated%3A2024-10-01..2024-10-21&type=Issues))
+
+### 5.2.0 - 2024-10-01
+
+([full changelog](https://github.com/jupyterhub/jupyterhub/compare/5.1.0...5.2.0))
+
+#### New features added
+
+- add dark mode toggle [#4897](https://github.com/jupyterhub/jupyterhub/pull/4897) ([@minrk](https://github.com/minrk), [@benz0li](https://github.com/benz0li))
+- Revoke all permissions from Authenticator.blocked_users [#4865](https://github.com/jupyterhub/jupyterhub/pull/4865) ([@minrk](https://github.com/minrk), [@manics](https://github.com/manics))
+
+#### Enhancements made
+
+- Add `LD_LIBRARY_PATH` to `LocalProcessSpawner.env_keep`, move most env_keep defaults to LocalProcessSpawner [#4904](https://github.com/jupyterhub/jupyterhub/pull/4904) ([@edmorley](https://github.com/edmorley), [@minrk](https://github.com/minrk), [@manics](https://github.com/manics))
+- Add PAMAuthenticator.executor_threads configurable, increase default to 4 [#4863](https://github.com/jupyterhub/jupyterhub/pull/4863) ([@Will-Shanks](https://github.com/Will-Shanks), [@minrk](https://github.com/minrk))
+
+#### Bugs fixed
+
+- Fix incorrect rounding function with large spawn_throttle_retry_range upper bound [#4913](https://github.com/jupyterhub/jupyterhub/pull/4913) ([@emmanuel-ferdman](https://github.com/emmanuel-ferdman), [@minrk](https://github.com/minrk))
+- fix python3 -m jupyterhub.app [#4876](https://github.com/jupyterhub/jupyterhub/pull/4876) ([@minrk](https://github.com/minrk), [@manics](https://github.com/manics))
+- Admin pages: use inherited base_url from render_template [#4867](https://github.com/jupyterhub/jupyterhub/pull/4867) ([@manics](https://github.com/manics), [@minrk](https://github.com/minrk))
+- singleuser: fix shutdown mixin [#4864](https://github.com/jupyterhub/jupyterhub/pull/4864) ([@oliver-sanders](https://github.com/oliver-sanders), [@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio))
+
+#### Maintenance and upkeep improvements
+
+- browser tests: use text_content instead of inner_text [#4906](https://github.com/jupyterhub/jupyterhub/pull/4906) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio))
+- update-types typo in dependabot.yml [#4884](https://github.com/jupyterhub/jupyterhub/pull/4884) ([@minrk](https://github.com/minrk))
+- only group minor dependencies in dependabot [#4882](https://github.com/jupyterhub/jupyterhub/pull/4882) ([@minrk](https://github.com/minrk))
+- start metrics collector in start [#4870](https://github.com/jupyterhub/jupyterhub/pull/4870) ([@minrk](https://github.com/minrk), [@manics](https://github.com/manics))
+- bump require.js [#4868](https://github.com/jupyterhub/jupyterhub/pull/4868) ([@minrk](https://github.com/minrk))
+- unpin pytest-asyncio [#4664](https://github.com/jupyterhub/jupyterhub/pull/4664) ([@minrk](https://github.com/minrk), [@manics](https://github.com/manics), [@seifertm](https://github.com/seifertm))
+- Display Sphinx linkcheck output in a more readable format [#4881](https://github.com/jupyterhub/jupyterhub/pull/4881) ([@manics](https://github.com/manics), [@minrk](https://github.com/minrk))
+- add dependabot config for npm [#4869](https://github.com/jupyterhub/jupyterhub/pull/4869) ([@minrk](https://github.com/minrk), [@manics](https://github.com/manics))
+
+#### Documentation improvements
+
+- Fix typo in concepts.md [#4916](https://github.com/jupyterhub/jupyterhub/pull/4916) ([@dirtbirb](https://github.com/dirtbirb), [@consideRatio](https://github.com/consideRatio))
+- add University of Portland to sample orgs [#4896](https://github.com/jupyterhub/jupyterhub/pull/4896) ([@rinvii](https://github.com/rinvii), [@minrk](https://github.com/minrk))
+- docs: remove some outdated links [#4883](https://github.com/jupyterhub/jupyterhub/pull/4883) ([@minrk](https://github.com/minrk), [@manics](https://github.com/manics))
+- FAQ: websocket problems [#4880](https://github.com/jupyterhub/jupyterhub/pull/4880) ([@manics](https://github.com/manics), [@minrk](https://github.com/minrk))
+
+#### Contributors to this release
+
+The following people contributed discussions, new ideas, code and documentation contributions, and review.
+See [our definition of contributors](https://github-activity.readthedocs.io/en/latest/#how-does-this-tool-define-contributions-in-the-reports).
+
+([GitHub contributors page for this release](https://github.com/jupyterhub/jupyterhub/graphs/contributors?from=2024-07-31&to=2024-10-01&type=c))
+
+@benz0li ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Abenz0li+updated%3A2024-07-31..2024-10-01&type=Issues)) | @consideRatio ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3AconsideRatio+updated%3A2024-07-31..2024-10-01&type=Issues)) | @dirtbirb ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Adirtbirb+updated%3A2024-07-31..2024-10-01&type=Issues)) | @edmorley ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aedmorley+updated%3A2024-07-31..2024-10-01&type=Issues)) | @emmanuel-ferdman ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aemmanuel-ferdman+updated%3A2024-07-31..2024-10-01&type=Issues)) | @jelmd ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Ajelmd+updated%3A2024-07-31..2024-10-01&type=Issues)) | @manics ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Amanics+updated%3A2024-07-31..2024-10-01&type=Issues)) | @minrk ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aminrk+updated%3A2024-07-31..2024-10-01&type=Issues)) | @oliver-sanders ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aoliver-sanders+updated%3A2024-07-31..2024-10-01&type=Issues)) | @rinvii ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Arinvii+updated%3A2024-07-31..2024-10-01&type=Issues)) | @seifertm ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aseifertm+updated%3A2024-07-31..2024-10-01&type=Issues)) | @Will-Shanks ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3AWill-Shanks+updated%3A2024-07-31..2024-10-01&type=Issues))
+
 ## 5.1
 
 ### 5.1.0 - 2024-07-31
@@ -92,6 +260,7 @@ Changes that are likely to require effort to upgrade:
 - update bootstrap to v5 [#4774](https://github.com/jupyterhub/jupyterhub/pull/4774) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio), [@manics](https://github.com/manics))
 - explicitly require groups in auth model when Authenticator.manage_groups is enabled [#4645](https://github.com/jupyterhub/jupyterhub/pull/4645) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio))
 - add JupyterHub.subdomain_hook [#4471](https://github.com/jupyterhub/jupyterhub/pull/4471) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio), [@akhmerov](https://github.com/akhmerov))
+- Using a token as a query parameter to start a user session is disabled by default, set `JUPYTERHUB_ALLOW_TOKEN_IN_URL=true` to enable it
 
 #### New features added
 

docs/source/reference/gallery-jhub-deployments.md

@@ -82,15 +82,6 @@ Within CERN, there are two noteworthy JupyterHub deployments in operation:
 - Advanced Computing
   - [Palmetto cluster and JupyterHub](https://citi.sites.clemson.edu/2016/08/18/JupyterHub-for-Palmetto-Cluster.html)
 
-### University of Colorado Boulder
-
-- (CU Research Computing) CURC
-
-  - [JupyterHub User Guide](https://curc.readthedocs.io/en/latest/gateways/jupyterhub.html)
-    - Slurm job dispatched on Crestone compute cluster
-    - log troubleshooting
-    - Profiles in IPython Clusters tab
-
 ### ETH Zurich
 
 [ETH Zurich](https://ethz.ch/en.html), (Federal Institute of Technology Zurich), is a public research university in Zürich, Switzerland, with focus on science, technology, engineering, and mathematics, although its 16 departments span a variety of disciplines and subjects.

docs/source/reference/monitoring.md

@@ -33,6 +33,23 @@ export JUPYTERHUB_METRICS_PREFIX=jupyterhub_prod
 
 would result in the metric `jupyterhub_prod_active_users`, etc.
 
+(monitoring_bucket_sizes)=
+
+## Customizing bucket sizes
+
+As of JupyterHub 5.3, the following environment variables in the Hub's environment can be overridden to support custom bucket sizes - below are the defaults:
+
+| Variable                                           | Default                                                            |
+| -------------------------------------------------- | ------------------------------------------------------------------ |
+| `JUPYTERHUB_SERVER_SPAWN_DURATION_SECONDS_BUCKETS` | `0.5,1,2.5,5,10,15,30,60,120,180,300,600,inf`                      |
+| `JUPYTERHUB_SERVER_STOP_DURATION_SECONDS_BUCKETS`  | `0.005,0.01,0.025,0.05,0.075,0.1,0.25,0.5,0.75,1,2.5,5,7.5,10,inf` |
+
+For example,
+
+```bash
+export JUPYTERHUB_SERVER_SPAWN_DURATION_SECONDS_BUCKETS="1,2,4,6,12,30,60,120,inf"
+```
+
 ## Configuring metrics
 
 ```{eval-rst}

docs/source/reference/spawners.md

@@ -2,7 +2,7 @@
 
 # Spawners
 
-A [Spawner][] starts each single-user notebook server.
+A [Spawner](#Spawner) starts each single-user notebook server.
 The Spawner represents an abstract interface to a process,
 and a custom Spawner needs to be able to take three actions:
 
@@ -37,7 +37,7 @@ Some examples include:
 
 ### Spawner.start
 
-`Spawner.start` should start a single-user server for a single user.
+[](#Spawner.start) should start a single-user server for a single user.
 Information about the user can be retrieved from `self.user`,
 an object encapsulating the user's name, authentication, and server info.
 
@@ -68,11 +68,11 @@ async def start(self):
 When `Spawner.start` returns, the single-user server process should actually be running,
 not just requested. JupyterHub can handle `Spawner.start` being very slow
 (such as PBS-style batch queues, or instantiating whole AWS instances)
-via relaxing the `Spawner.start_timeout` config value.
+via relaxing the [](#Spawner.start_timeout) config value.
 
 #### Note on IPs and ports
 
-`Spawner.ip` and `Spawner.port` attributes set the _bind_ URL,
+[](#Spawner.ip) and [](#Spawner.port) attributes set the _bind_ URL,
 which the single-user server should listen on
 (passed to the single-user process via the `JUPYTERHUB_SERVICE_URL` environment variable).
 The _return_ value is the IP and port (or full URL) the Hub should _connect to_.
@@ -124,7 +124,7 @@ If both attributes are not present, the Exception will be shown to the user as u
 
 ### Spawner.poll
 
-`Spawner.poll` checks if the spawner is still running.
+[](#Spawner.poll) checks if the spawner is still running.
 It should return `None` if it is still running,
 and an integer exit status, otherwise.
 
@@ -133,7 +133,7 @@ to check if the local process is still running. On Windows, it uses `psutil.pid_
 
 ### Spawner.stop
 
-`Spawner.stop` should stop the process. It must be a tornado coroutine, which should return when the process has finished exiting.
+[](#Spawner.stop) should stop the process. It must be a tornado coroutine, which should return when the process has finished exiting.
 
 ## Spawner state
 
@@ -166,17 +166,18 @@ def clear_state(self):
     self.pid = 0
 ```
 
+(spawner_user_options)=
+
 ## Spawner options form
 
-(new in 0.4)
-
 Some deployments may want to offer options to users to influence how their servers are started.
-This may include cluster-based deployments, where users specify what resources should be available,
-or docker-based deployments where users can select from a list of base images.
+This may include cluster-based deployments, where users specify what memory or cpu resources should be available,
+or container-based deployments where users can select from a list of base images,
+or more complex configurations where users select a "profile" representing a bundle of settings to be applied together.
 
-This feature is enabled by setting `Spawner.options_form`, which is an HTML form snippet
+This feature is enabled by setting [](#Spawner.options_form), which is an HTML form snippet
 inserted unmodified into the spawn form.
-If the `Spawner.options_form` is defined, when a user tries to start their server, they will be directed to a form page, like this:
+If the `Spawner.options_form` is defined, when a user tries to start their server they will be directed to a form page, like this:
 
 ![spawn-form](/images/spawn-form.png)
 
@@ -186,28 +187,40 @@ See [this example](https://github.com/jupyterhub/jupyterhub/blob/HEAD/examples/s
 
 ### `Spawner.options_from_form`
 
-Options from this form will always be a dictionary of lists of strings, e.g.:
+Inputs from an HTML form always arrive as a dictionary of lists of strings, e.g.:
 
 ```python
-{
+formdata = {
   'integer': ['5'],
+  'checkbox': ['on'],
   'text': ['some text'],
   'select': ['a', 'b'],
 }
 ```
 
-When `formdata` arrives, it is passed through `Spawner.options_from_form(formdata)`,
-which is a method to turn the form data into the correct structure.
-This method must return a dictionary, and is meant to interpret the lists-of-strings into the correct types. For example, the `options_from_form` for the above form would look like:
+When `formdata` arrives, it is passed through [](#Spawner.options_from_form):
 
 ```python
-def options_from_form(self, formdata):
+spawner.user_options = spawner.options_from_form(formdata, spawner=spawner)
+```
+
+to create `spawner.user_options`.
+
+[](#Spawner.options_from_form) is a configurable function to turn the HTTP form data into the correct structure for [](#Spawner.user_options).
+`options_from_form` must return a dictionary, _may_ be async, and is meant to interpret the lists-of-strings a web form produces into the correct types.
+For example, the `options_from_form` for the above form might look like:
+
+```python
+def options_from_form(formdata, spawner=None):
     options = {}
     options['integer'] = int(formdata['integer'][0]) # single integer value
+    options['checkbox'] = formdata['checkbox'] == ['on']
     options['text'] = formdata['text'][0] # single string value
     options['select'] = formdata['select'] # list already correct
     options['notinform'] = 'extra info' # not in the form at all
     return options
+
+c.Spawner.options_from_form = options_from_form
 ```
 
 which would return:
@@ -215,15 +228,115 @@ which would return:
 ```python
 {
   'integer': 5,
+  'checkbox': True,
   'text': 'some text',
   'select': ['a', 'b'],
   'notinform': 'extra info',
 }
 ```
 
-When `Spawner.start` is called, this dictionary is accessible as `self.user_options`.
+### Applying user options
 
-[spawner]: https://github.com/jupyterhub/jupyterhub/blob/HEAD/jupyterhub/spawner.py
+The base Spawner class doesn't do anything with `user_options`, that is also up to your deployment and/or chosen Spawner.
+This is because the users can specify arbitrary option dictionary by using the API,
+so it is part of your Spawner and/or deployment configuration to expose the options you trust your users to set.
+
+[](#Spawner.apply_user_options) is the hook for taking `user_options` and applying whatever configuration it may represent.
+It is critical that `apply_user_options` validates all input, since these are provided by the user.
+
+```python
+def apply_user_options(spawner, user_options):
+    if "image" in user_options and isinstance(user_options["image"], str):
+        spawner.image = user_options["image"]
+
+c.Spawner.apply_user_options = apply_user_options
+```
+
+:::{versionadded} 5.3
+JupyterHub 5.3 introduces [](#Spawner.apply_user_options) configuration.
+Previously, [](#Spawner.user_options) could only be consumed during [](#Spawner.start),
+at which point `user_options` is available to the Spawner instance as `self.user_options`.
+This approach requires subclassing, so it was not possible to apply new `user_options` via configuration.
+In JupyterHub 5.3, it is possible to fully expose user options,
+and for some simple cases, fully with _declarative_ configuration.
+:::
+
+### Declarative configuration for user options
+
+While [](#Spawner.options_from_form) and [](#Spawner.apply_user_options) are callables by nature,
+some simple cases can be represented by declarative configuration,
+which is most conveniently expressed in e.g. the yaml of the JupyterHub helm chart.
+The cases currently handled are:
+
+```python
+c.Spawner.options_form = """
+<input name="image_input" type="text" value="quay.io/jupyterhub/singleuser:5.2"/>
+<input name="debug_checkbox" type="checkbox" />
+"""
+c.Spawner.options_from_form = "simple"
+c.Spawner.apply_user_options = {"image_input": "image", "debug_checkbox": "debug"}
+```
+
+`options_from_form = "simple"` uses a built-in method to do the very simplest interpretation of an html form,
+casting the lists of strings to single strings by getting the first item when there is only one.
+The only extra processing it performs is casting the checkbox value of `on` to True.
+
+So it turns this formdata:
+
+```python
+{
+  "image_input": ["my_image"],
+  "debug_checkbox": ["on"],
+}
+```
+
+into this `user_options`
+
+```python
+{
+  "image_input": "my_image",
+  "debug_checkbox": True
+}
+```
+
+When `apply_user_options` is a dictionary, any input in `user_options` is looked up in this dictionary,
+and assigned to the corresponding Spawner attribute.
+Strings are passed through traitlets' `from_string` logic (what is used for setting values on the command-line),
+which means you can set numbers and things this way as well,
+even though `options_from_form` leaves these as strings.
+
+So in the above configuration, we have exposed `Spawner.debug` and `Spawner.image` without needing to write any functions.
+In the JupyterHub helm chart YAML, this would look like:
+
+```yaml
+hub:
+  config:
+    KubeSpawner:
+      options_form: |
+        <input name="image_input" type="text" value="quay.io/jupyterhub/singleuser:5.2"/>
+        <input name="debug_checkbox" type="checkbox" />
+      options_from_form: simple
+      apply_user_options:
+        image_input: image
+        debug_checkbox: debug
+```
+
+### Setting `user_options` directly via the REST API
+
+In addition to going through the options form, `user_options` may be set directly, via the REST API.
+The body of a POST request to spawn a server may be a JSON dictionary,
+which will be used to set `user_options` directly.
+When used this way, neither `options_form` nor `options_from_form` are involved,
+`user_options` is set directly, and only `apply_user_options` is called.
+
+```
+POST /hub/api/users/servers/:name
+{
+  "option": 5,
+  "bool": True,
+  "string": "value"
+}
+```
 
 ## Writing a custom spawner
 

docs/source/reference/urls.md

@@ -183,13 +183,6 @@ will send user `hortense` to `/user/hortense/notebooks/Index.ipynb`
 This will not work in general,
 unless you grant those users access to your server.
 
-**Contributions welcome:** The JupyterLab "shareable link" should share this link
-when run with JupyterHub, but it does not.
-See [jupyterlab-hub](https://github.com/jupyterhub/jupyterlab-hub)
-where this should probably be done and
-[this issue in JupyterLab](https://github.com/jupyterlab/jupyterlab/issues/5388)
-that is intended to make it possible.
-
 ## Spawning
 
 ### `/hub/spawn[/:username[/:servername]]`

docs/source/tutorial/collaboration-users.md

@@ -78,7 +78,7 @@ c.JupyterHub.load_roles = []
 c.JupyterHub.load_groups = {
     # collaborative accounts get added to this group
     # so it's easy to see which accounts are collaboration accounts
-    "collaborative": [],
+    "collaborative": {"users": []},
 }
 ```
 
@@ -102,12 +102,12 @@ for project_name, project in project_config["projects"].items():
     members = project.get("members", [])
     print(f"Adding project {project_name} with members {members}")
     # add them to a group for the project
-    c.JupyterHub.load_groups[project_name] = members
+    c.JupyterHub.load_groups[project_name] = {"users": members}
     # define a new user for the collaboration
     collab_user = f"{project_name}-collab"
     # add the collab user to the 'collaborative' group
     # so we can identify it as a collab account
-    c.JupyterHub.load_groups["collaborative"].append(collab_user)
+    c.JupyterHub.load_groups["collaborative"]["users"].append(collab_user)
 
     # finally, grant members of the project collaboration group
     # access to the collab user's server,

docs/source/tutorial/quickstart.md

@@ -90,6 +90,6 @@ To **allow multiple users to sign in** to the Hub server, you must start
 sudo jupyterhub
 ```
 
-The [wiki](https://github.com/jupyterhub/jupyterhub/wiki/Using-sudo-to-run-JupyterHub-without-root-privileges)
+[](howto:config:no-sudo)
 describes how to run the server as a _less privileged user_. This requires
 additional configuration of the system.

jsx/.eslintrc.json

@@ -1,44 +0,0 @@
-{
-  "extends": ["plugin:react/recommended"],
-  "parserOptions": {
-    "ecmaVersion": 2018,
-    "sourceType": "module",
-    "ecmaFeatures": {
-      "jsx": true
-    }
-  },
-  "settings": {
-    "react": {
-      "version": "detect"
-    }
-  },
-  "plugins": ["eslint-plugin-react", "prettier", "unused-imports"],
-  "env": {
-    "es6": true,
-    "browser": true
-  },
-  "rules": {
-    "semi": "off",
-    "quotes": "off",
-    "prettier/prettier": "warn",
-    "no-unused-vars": "off",
-    "unused-imports/no-unused-imports": "error",
-    "unused-imports/no-unused-vars": [
-      "warn",
-      {
-        "vars": "all",
-        "varsIgnorePattern": "^regeneratorRuntime|^_",
-        "args": "after-used",
-        "argsIgnorePattern": "^_"
-      }
-    ]
-  },
-  "overrides": [
-    {
-      "files": ["**/*.test.js", "**/*.test.jsx"],
-      "env": {
-        "jest": true
-      }
-    }
-  ]
-}

jsx/eslint.config.mjs

@@ -0,0 +1,77 @@
+import { defineConfig } from "eslint/config";
+import react from "eslint-plugin-react";
+import prettier from "eslint-plugin-prettier";
+import unusedImports from "eslint-plugin-unused-imports";
+import globals from "globals";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import js from "@eslint/js";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+  recommendedConfig: js.configs.recommended,
+  allConfig: js.configs.all,
+});
+
+export default defineConfig([
+  {
+    extends: compat.extends("plugin:react/recommended"),
+
+    plugins: {
+      react,
+      prettier,
+      "unused-imports": unusedImports,
+    },
+
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+      },
+
+      ecmaVersion: 2018,
+      sourceType: "module",
+
+      parserOptions: {
+        ecmaFeatures: {
+          jsx: true,
+        },
+      },
+    },
+
+    settings: {
+      react: {
+        version: "detect",
+      },
+    },
+
+    rules: {
+      semi: "off",
+      quotes: "off",
+      "prettier/prettier": "warn",
+      "no-unused-vars": "off",
+      "unused-imports/no-unused-imports": "error",
+
+      "unused-imports/no-unused-vars": [
+        "warn",
+        {
+          vars: "all",
+          varsIgnorePattern: "^regeneratorRuntime|^_",
+          args: "after-used",
+          argsIgnorePattern: "^_",
+        },
+      ],
+    },
+  },
+  {
+    files: ["**/*.test.js", "**/*.test.jsx"],
+
+    languageOptions: {
+      globals: {
+        ...globals.jest,
+      },
+    },
+  },
+]);

jsx/package.json

@@ -22,51 +22,58 @@
     "plugins": []
   },
   "jest": {
+    "fakeTimers": {
+      "enableGlobally": true
+    },
     "moduleNameMapper": {
       "\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$": "<rootDir>/__mocks__/fileMock.js",
       "\\.(css|less)$": "identity-obj-proxy"
     },
+    "setupFiles": [
+      "./testing/setup.jest.js"
+    ],
     "testEnvironment": "jsdom"
   },
   "dependencies": {
-    "bootstrap": "^5.2.3",
+    "bootstrap": "^5.3.5",
     "history": "^5.3.0",
     "lodash": "^4.17.21",
     "prop-types": "^15.8.1",
-    "react": "^17.0.2",
-    "react-bootstrap": "^2.10.1",
-    "react-dom": "^17.0.2",
-    "react-icons": "^4.8.0",
-    "react-multi-select-component": "^4.3.4",
-    "react-redux": "^7.2.8",
-    "react-router-dom": "^6.22.2",
-    "recompose": "npm:react-recompose@^0.33.0",
-    "redux": "^4.2.1",
-    "regenerator-runtime": "^0.13.11"
+    "react": "^19.1.0",
+    "react-bootstrap": "^2.10.9",
+    "react-dom": "^19.1.0",
+    "react-icons": "^5.5.0",
+    "react-redux": "^9.2.0",
+    "react-router": "^7.5.0",
+    "redux": "^5.0.1",
+    "regenerator-runtime": "^0.14.1"
   },
   "devDependencies": {
-    "@babel/core": "^7.21.4",
-    "@babel/preset-env": "^7.21.4",
-    "@babel/preset-react": "^7.18.6",
-    "@testing-library/jest-dom": "^5.16.5",
-    "@testing-library/react": "^12.1.5",
-    "@testing-library/user-event": "^13.5.0",
-    "@webpack-cli/serve": "^2.0.1",
-    "babel-jest": "^29.5.0",
-    "babel-loader": "^9.1.2",
-    "css-loader": "^6.7.3",
-    "eslint": "^8.38.0",
-    "eslint-plugin-prettier": "^4.2.1",
-    "eslint-plugin-react": "^7.32.2",
-    "eslint-plugin-unused-imports": "^2.0.0",
+    "@babel/core": "^7.26.10",
+    "@babel/preset-env": "^7.26.9",
+    "@babel/preset-react": "^7.26.3",
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.24.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@webpack-cli/serve": "^3.0.1",
+    "babel-jest": "^29.7.0",
+    "babel-loader": "^10.0.0",
+    "css-loader": "^7.1.2",
+    "eslint": "^9.24.0",
+    "eslint-plugin-prettier": "^5.2.6",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-unused-imports": "^4.1.4",
     "file-loader": "^6.2.0",
+    "globals": "^16.0.0",
     "identity-obj-proxy": "^3.0.0",
-    "jest": "^29.5.0",
-    "jest-environment-jsdom": "^29.5.0",
-    "prettier": "^2.8.7",
-    "style-loader": "^3.3.2",
-    "webpack": "^5.79.0",
-    "webpack-cli": "^5.0.1",
-    "webpack-dev-server": "^4.13.3"
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "prettier": "^3.5.3",
+    "style-loader": "^4.0.0",
+    "webpack": "^5.99.5",
+    "webpack-cli": "^6.0.1",
+    "webpack-dev-server": "^5.2.1"
   }
 }

jsx/src/App.jsx

@@ -1,11 +1,11 @@
 import React from "react";
-import ReactDOM from "react-dom";
+import { createRoot } from "react-dom/client";
 import { Provider } from "react-redux";
 import { createStore } from "redux";
-import { compose } from "recompose";
+import { compose } from "./util/_recompose";
 import { initialState, reducers } from "./Store";
 import withAPI from "./util/withAPI";
-import { HashRouter, Routes, Route } from "react-router-dom";
+import { HashRouter, Routes, Route } from "react-router";
 
 import ServerDashboard from "./components/ServerDashboard/ServerDashboard";
 import Groups from "./components/Groups/Groups";
@@ -40,4 +40,5 @@ const App = () => {
   );
 };
 
-ReactDOM.render(<App />, document.getElementById("react-admin-hook"));
+const root = createRoot(document.getElementById("react-admin-hook"));
+root.render(<App />);

jsx/src/components/AddUser/AddUser.jsx

@@ -1,6 +1,6 @@
 import React, { useState } from "react";
 import { useDispatch, useSelector } from "react-redux";
-import { Link, useNavigate } from "react-router-dom";
+import { Link, useNavigate } from "react-router";
 import { Button, Col } from "react-bootstrap";
 import PropTypes from "prop-types";
 import ErrorAlert from "../../util/error";

jsx/src/components/AddUser/AddUser.test.js

@@ -1,11 +1,9 @@
-import React from "react";
+import React, { act } from "react";
 import "@testing-library/jest-dom";
-import { act } from "react-dom/test-utils";
 import { render, screen, fireEvent } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
 import { Provider, useDispatch, useSelector } from "react-redux";
 import { createStore } from "redux";
-import { HashRouter } from "react-router-dom";
+import { HashRouter } from "react-router";
 // eslint-disable-next-line
 import regeneratorRuntime from "regenerator-runtime";
 
@@ -46,6 +44,7 @@ beforeEach(() => {
 
 afterEach(() => {
   useDispatch.mockClear();
+  jest.runAllTimers();
 });
 
 test("Renders", async () => {
@@ -67,7 +66,7 @@ test("Removes users when they fail Regex", async () => {
 
   fireEvent.blur(textarea, { target: { value: "foo \n bar\na@b.co\n  \n\n" } });
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   expect(callbackSpy).toHaveBeenCalledWith(["foo", "bar", "a@b.co"], false);
@@ -79,15 +78,15 @@ test("Correctly submits admin", async () => {
   await act(async () => {
     render(addUserJsx(callbackSpy));
   });
-
   let textarea = screen.getByTestId("user-textarea");
   let submit = screen.getByTestId("submit");
   let check = screen.getByTestId("check");
 
-  userEvent.click(check);
-  fireEvent.blur(textarea, { target: { value: "foo" } });
+  await fireEvent.blur(textarea, { target: { value: "foo" } });
+  await fireEvent.click(check);
+  await fireEvent.click(submit);
   await act(async () => {
-    fireEvent.click(submit);
+    await jest.runAllTimers();
   });
 
   expect(callbackSpy).toHaveBeenCalledWith(["foo"], true);
@@ -103,7 +102,7 @@ test("Shows a UI error dialogue when user creation fails", async () => {
   let submit = screen.getByTestId("submit");
 
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   let errorDialog = screen.getByText("Failed to create user.");
@@ -122,7 +121,7 @@ test("Shows a more specific UI error dialogue when user creation returns an impr
   let submit = screen.getByTestId("submit");
 
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   let errorDialog = screen.getByText(

jsx/src/components/CreateGroup/CreateGroup.jsx

@@ -1,6 +1,6 @@
 import React, { useState } from "react";
 import { useDispatch, useSelector } from "react-redux";
-import { Link, useNavigate } from "react-router-dom";
+import { Link, useNavigate } from "react-router";
 import { Button, Card } from "react-bootstrap";
 import PropTypes from "prop-types";
 import { MainContainer } from "../../util/layout";

jsx/src/components/CreateGroup/CreateGroup.test.js

@@ -1,11 +1,10 @@
-import React from "react";
+import React, { act } from "react";
 import "@testing-library/jest-dom";
-import { act } from "react-dom/test-utils";
 import { render, screen, fireEvent } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { Provider, useDispatch, useSelector } from "react-redux";
 import { createStore } from "redux";
-import { HashRouter } from "react-router-dom";
+import { HashRouter } from "react-router";
 // eslint-disable-next-line
 import regeneratorRuntime from "regenerator-runtime";
 import CreateGroup from "./CreateGroup";
@@ -45,6 +44,7 @@ beforeEach(() => {
 
 afterEach(() => {
   useDispatch.mockClear();
+  jest.runAllTimers();
 });
 
 test("Renders", async () => {
@@ -63,9 +63,10 @@ test("Calls createGroup on submit", async () => {
 
   let input = screen.getByTestId("group-input");
   let submit = screen.getByTestId("submit");
+  const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime });
 
-  userEvent.type(input, "groupname");
-  await act(async () => fireEvent.click(submit));
+  await user.type(input, "groupname");
+  await act(async () => await fireEvent.click(submit));
 
   expect(callbackSpy).toHaveBeenNthCalledWith(1, "groupname");
 });
@@ -80,7 +81,7 @@ test("Shows a UI error dialogue when group creation fails", async () => {
   let submit = screen.getByTestId("submit");
 
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   let errorDialog = screen.getByText("Failed to create group.");
@@ -99,7 +100,7 @@ test("Shows a more specific UI error dialogue when user creation returns an impr
   let submit = screen.getByTestId("submit");
 
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   let errorDialog = screen.getByText(

jsx/src/components/EditUser/EditUser.jsx

@@ -1,7 +1,7 @@
 import React, { useEffect, useState } from "react";
 import { useDispatch, useSelector } from "react-redux";
 import PropTypes from "prop-types";
-import { Link, useLocation, useNavigate } from "react-router-dom";
+import { Link, useLocation, useNavigate } from "react-router";
 import { Button, Card } from "react-bootstrap";
 import { MainContainer } from "../../util/layout";
 

jsx/src/components/EditUser/EditUser.test.js

@@ -1,10 +1,9 @@
-import React from "react";
+import React, { act } from "react";
 import "@testing-library/jest-dom";
-import { act } from "react-dom/test-utils";
 import { render, screen, fireEvent } from "@testing-library/react";
 import { Provider, useDispatch, useSelector } from "react-redux";
 import { createStore } from "redux";
-import { HashRouter } from "react-router-dom";
+import { HashRouter } from "react-router";
 // eslint-disable-next-line
 import regeneratorRuntime from "regenerator-runtime";
 
@@ -16,8 +15,8 @@ jest.mock("react-redux", () => ({
   useSelector: jest.fn(),
 }));
 
-jest.mock("react-router-dom", () => ({
-  ...jest.requireActual("react-router-dom"),
+jest.mock("react-router", () => ({
+  ...jest.requireActual("react-router"),
   useLocation: jest.fn().mockImplementation(() => {
     return { state: { username: "foo", has_admin: false } };
   }),
@@ -58,6 +57,7 @@ beforeEach(() => {
 
 afterEach(() => {
   useDispatch.mockClear();
+  jest.runAllTimers();
 });
 
 test("Renders", async () => {
@@ -80,7 +80,7 @@ test("Calls the delete user function when the button is pressed", async () => {
   let deleteUser = screen.getByTestId("delete-user");
 
   await act(async () => {
-    fireEvent.click(deleteUser);
+    await fireEvent.click(deleteUser);
   });
 
   expect(callbackSpy).toHaveBeenCalled();
@@ -95,7 +95,7 @@ test("Submits the edits when the button is pressed", async () => {
 
   let submit = screen.getByTestId("submit");
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   expect(callbackSpy).toHaveBeenCalled();
@@ -113,7 +113,7 @@ test("Shows a UI error dialogue when user edit fails", async () => {
 
   fireEvent.blur(usernameInput, { target: { value: "whatever" } });
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   let errorDialog = screen.getByText("Failed to edit user.");
@@ -134,7 +134,7 @@ test("Shows a UI error dialogue when user edit returns an improper status code",
 
   fireEvent.blur(usernameInput, { target: { value: "whatever" } });
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   let errorDialog = screen.getByText("Failed to edit user.");

jsx/src/components/GroupEdit/GroupEdit.jsx

@@ -1,6 +1,6 @@
 import React, { useEffect, useState } from "react";
 import { useSelector, useDispatch } from "react-redux";
-import { Link, useNavigate, useLocation } from "react-router-dom";
+import { Link, useNavigate, useLocation } from "react-router";
 import PropTypes from "prop-types";
 import { Button, Card } from "react-bootstrap";
 import GroupSelect from "../GroupSelect/GroupSelect";
@@ -42,6 +42,10 @@ const GroupEdit = (props) => {
     }
   }, [location]);
 
+  useEffect(() => {
+    setSelected(group_data.users);
+  }, []);
+
   const { group_data } = location.state || {};
   if (!group_data) return <div></div>;
   const [propobject, setProp] = useState(group_data.properties);
@@ -175,6 +179,7 @@ GroupEdit.propTypes = {
   removeFromGroup: PropTypes.func,
   deleteGroup: PropTypes.func,
   updateGroups: PropTypes.func,
+  updateProp: PropTypes.func,
   validateUser: PropTypes.func,
 };
 

jsx/src/components/GroupEdit/GroupEdit.test.jsx

@@ -1,11 +1,10 @@
-import React from "react";
+import React, { act } from "react";
 import "@testing-library/jest-dom";
-import { act } from "react-dom/test-utils";
 import { render, screen, fireEvent } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { Provider, useSelector } from "react-redux";
 import { createStore } from "redux";
-import { HashRouter } from "react-router-dom";
+import { HashRouter } from "react-router";
 // eslint-disable-next-line
 import regeneratorRuntime from "regenerator-runtime";
 
@@ -16,8 +15,8 @@ jest.mock("react-redux", () => ({
   useSelector: jest.fn(),
 }));
 
-jest.mock("react-router-dom", () => ({
-  ...jest.requireActual("react-router-dom"),
+jest.mock("react-router", () => ({
+  ...jest.requireActual("react-router"),
   useLocation: jest.fn().mockImplementation(() => {
     return { state: { group_data: { users: ["foo"], name: "group" } } };
   }),
@@ -58,6 +57,7 @@ beforeEach(() => {
 
 afterEach(() => {
   useSelector.mockClear();
+  jest.runAllTimers();
 });
 
 test("Renders", async () => {
@@ -80,13 +80,15 @@ test("Adds user from input to user selectables on button click", async () => {
   let input = screen.getByTestId("username-input");
   let validateUser = screen.getByTestId("validate-user");
   let submit = screen.getByTestId("submit");
-
-  userEvent.type(input, "bar");
-  fireEvent.click(validateUser);
-  await act(async () => okPacket);
+  const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime });
+  await user.type(input, "bar");
+  await user.click(validateUser);
+  await act(async () => {
+    await jest.runAllTimers();
+  });
 
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   expect(callbackSpy).toHaveBeenNthCalledWith(1, ["bar"], "group");
@@ -100,7 +102,7 @@ test("Removes a user recently added from input from the selectables list", async
   });
 
   let selectedUser = screen.getByText("foo");
-  fireEvent.click(selectedUser);
+  await await fireEvent.click(selectedUser);
 
   let unselectedUser = screen.getByText("foo");
 
@@ -117,14 +119,14 @@ test("Grays out a user, already in the group, when unselected and calls deleteUs
   let submit = screen.getByTestId("submit");
 
   let groupUser = screen.getByText("foo");
-  fireEvent.click(groupUser);
+  await fireEvent.click(groupUser);
 
   let unselectedUser = screen.getByText("foo");
   expect(unselectedUser.className).toBe("item unselected");
 
   // test deleteUser call
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   expect(callbackSpy).toHaveBeenNthCalledWith(1, ["foo"], "group");
@@ -140,7 +142,7 @@ test("Calls deleteGroup on button click", async () => {
   let deleteGroup = screen.getByTestId("delete-group");
 
   await act(async () => {
-    fireEvent.click(deleteGroup);
+    await fireEvent.click(deleteGroup);
   });
 
   expect(callbackSpy).toHaveBeenNthCalledWith(1, "group");
@@ -154,12 +156,12 @@ test("Shows a UI error dialogue when group edit fails", async () => {
   });
 
   let groupUser = screen.getByText("foo");
-  fireEvent.click(groupUser);
+  await fireEvent.click(groupUser);
 
   let submit = screen.getByTestId("submit");
 
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   let errorDialog = screen.getByText("Failed to edit group.");
@@ -176,12 +178,12 @@ test("Shows a UI error dialogue when group edit returns an improper status code"
   });
 
   let groupUser = screen.getByText("foo");
-  fireEvent.click(groupUser);
+  await fireEvent.click(groupUser);
 
   let submit = screen.getByTestId("submit");
 
   await act(async () => {
-    fireEvent.click(submit);
+    await fireEvent.click(submit);
   });
 
   let errorDialog = screen.getByText("Failed to edit group.");
@@ -200,7 +202,7 @@ test("Shows a UI error dialogue when group delete fails", async () => {
   let deleteGroup = screen.getByTestId("delete-group");
 
   await act(async () => {
-    fireEvent.click(deleteGroup);
+    await fireEvent.click(deleteGroup);
   });
 
   let errorDialog = screen.getByText("Failed to delete group.");
@@ -219,7 +221,7 @@ test("Shows a UI error dialogue when group delete returns an improper status cod
   let deleteGroup = screen.getByTestId("delete-group");
 
   await act(async () => {
-    fireEvent.click(deleteGroup);
+    await fireEvent.click(deleteGroup);
   });
 
   let errorDialog = screen.getByText("Failed to delete group.");

jsx/src/components/Groups/Groups.jsx

@@ -3,7 +3,7 @@ import { useSelector, useDispatch } from "react-redux";
 import PropTypes from "prop-types";
 
 import { Button, Card } from "react-bootstrap";
-import { Link, useNavigate } from "react-router-dom";
+import { Link, useNavigate } from "react-router";
 import { usePaginationParams } from "../../util/paginationParams";
 import PaginationFooter from "../PaginationFooter/PaginationFooter";
 import { MainContainer } from "../../util/layout";
@@ -14,14 +14,13 @@ const Groups = (props) => {
   const dispatch = useDispatch();
   const navigate = useNavigate();
 
-  const { offset, handleLimit, limit, setPagination } = usePaginationParams();
+  const { offset, setOffset, handleLimit, limit } = usePaginationParams();
 
   const total = groups_page ? groups_page.total : undefined;
 
   const { updateGroups } = props;
 
   const dispatchPageUpdate = (data, page) => {
-    setPagination(page);
     dispatch({
       type: "GROUPS_PAGE",
       value: {
@@ -32,21 +31,39 @@ const Groups = (props) => {
   };
 
   // single callback to reload the page
-  // uses current state, or params can be specified if state
-  // should be updated _after_ load, e.g. offset
+  // uses current state
   const loadPageData = (params) => {
-    params = params || {};
-    return updateGroups(
-      params.offset === undefined ? offset : params.offset,
-      params.limit === undefined ? limit : params.limit,
-    )
-      .then((data) => dispatchPageUpdate(data.items, data._pagination))
-      .catch((err) => setErrorAlert("Failed to update group list."));
+    const abortHandle = { cancelled: false };
+    (async () => {
+      try {
+        const data = await updateGroups(offset, limit);
+        // cancelled (e.g. param changed while waiting for response)
+        if (abortHandle.cancelled) return;
+        if (
+          data._pagination.offset &&
+          data._pagination.total <= data._pagination.offset
+        ) {
+          // reset offset if we're out of bounds,
+          // then load again
+          setOffset(0);
+          return;
+        }
+        // actually update page data
+        dispatchPageUpdate(data.items, data._pagination);
+      } catch (e) {
+        console.error("Failed to update group list.", e);
+      }
+    })();
+    // returns cancellation callback
+    return () => {
+      // cancel stale load
+      abortHandle.cancelled = true;
+    };
   };
 
   useEffect(() => {
-    loadPageData();
-  }, [limit]);
+    return loadPageData();
+  }, [limit, offset]);
 
   if (!groups_data || !groups_page) {
     return <div data-testid="no-show"></div>;
@@ -78,13 +95,15 @@ const Groups = (props) => {
             )}
           </ul>
           <PaginationFooter
-            offset={offset}
+            offset={groups_page.offset}
             limit={limit}
             visible={groups_data.length}
             total={total}
-            next={() => loadPageData({ offset: offset + limit })}
+            next={() => setOffset(groups_page.offset + limit)}
             prev={() =>
-              loadPageData({ offset: limit > offset ? 0 : offset - limit })
+              setOffset(
+                limit > groups_page.offset ? 0 : groups_page.offset - limit,
+              )
             }
             handleLimit={handleLimit}
           />

jsx/src/components/Groups/Groups.test.js

@@ -1,10 +1,9 @@
-import React from "react";
+import React, { act } from "react";
 import "@testing-library/jest-dom";
-import { act } from "react-dom/test-utils";
 import { render, screen, fireEvent } from "@testing-library/react";
 import { Provider, useSelector } from "react-redux";
 import { createStore } from "redux";
-import { HashRouter, useSearchParams } from "react-router-dom";
+import { HashRouter, useSearchParams } from "react-router";
 // eslint-disable-next-line
 import regeneratorRuntime from "regenerator-runtime";
 
@@ -16,8 +15,8 @@ jest.mock("react-redux", () => ({
   useSelector: jest.fn(),
 }));
 
-jest.mock("react-router-dom", () => ({
-  ...jest.requireActual("react-router-dom"),
+jest.mock("react-router", () => ({
+  ...jest.requireActual("react-router"),
   useSearchParams: jest.fn(),
 }));
 
@@ -58,23 +57,45 @@ var mockAppState = () =>
     },
   });
 
+var mockUpdateGroups = () => {
+  const state = mockAppState();
+  return jest.fn().mockImplementation((offset, limit) =>
+    Promise.resolve({
+      items: state.groups_data.slice(0, limit),
+      _pagination: {
+        offset: offset,
+        limit: limit || 2,
+        total: state.groups_page.total,
+      },
+    }),
+  );
+};
+
+let searchParams = new URLSearchParams();
+
 beforeEach(() => {
   useSelector.mockImplementation((callback) => {
     return callback(mockAppState());
   });
-  useSearchParams.mockImplementation(() => {
-    return [new URLSearchParams(), jest.fn()];
-  });
+  searchParams = new URLSearchParams();
+  searchParams.set("limit", "2");
+  useSearchParams.mockImplementation(() => [
+    searchParams,
+    (callback) => {
+      searchParams = callback(searchParams);
+    },
+  ]);
 });
 
 afterEach(() => {
   useSelector.mockClear();
   mockReducers.mockClear();
   useSearchParams.mockClear();
+  jest.runAllTimers();
 });
 
 test("Renders", async () => {
-  let callbackSpy = mockAsync();
+  let callbackSpy = mockUpdateGroups();
 
   await act(async () => {
     render(groupsJsx(callbackSpy));
@@ -84,7 +105,7 @@ test("Renders", async () => {
 });
 
 test("Renders groups_data prop into links", async () => {
-  let callbackSpy = mockAsync();
+  let callbackSpy = mockUpdateGroups();
 
   await act(async () => {
     render(groupsJsx(callbackSpy));
@@ -102,7 +123,7 @@ test("Renders nothing if required data is not available", async () => {
     return callback({});
   });
 
-  let callbackSpy = mockAsync();
+  let callbackSpy = mockUpdateGroups();
 
   await act(async () => {
     render(groupsJsx(callbackSpy));
@@ -113,20 +134,9 @@ test("Renders nothing if required data is not available", async () => {
 });
 
 test("Interacting with PaginationFooter causes page refresh", async () => {
-  let updateGroupsSpy = mockAsync();
-  let setSearchParamsSpy = mockAsync();
-  let searchParams = new URLSearchParams({ limit: "2" });
-  useSearchParams.mockImplementation(() => [
-    searchParams,
-    (callback) => {
-      searchParams = callback(searchParams);
-      setSearchParamsSpy(searchParams.toString());
-    },
-  ]);
-  let _, setSearchParams;
+  let updateGroupsSpy = mockUpdateGroups();
   await act(async () => {
     render(groupsJsx(updateGroupsSpy));
-    [_, setSearchParams] = useSearchParams();
   });
 
   expect(updateGroupsSpy).toBeCalledWith(0, 2);
@@ -135,12 +145,13 @@ test("Interacting with PaginationFooter causes page refresh", async () => {
     mockReducers.mock.results[mockReducers.mock.results.length - 1].value;
   expect(lastState.groups_page.offset).toEqual(0);
   expect(lastState.groups_page.limit).toEqual(2);
+  expect(searchParams.get("offset")).toEqual(null);
 
   let next = screen.getByTestId("paginate-next");
   await act(async () => {
-    fireEvent.click(next);
+    await fireEvent.click(next);
   });
-  expect(updateGroupsSpy).toBeCalledWith(2, 2);
-  // mocked updateGroups means callback after load doesn't fire
-  // expect(setSearchParamsSpy).toBeCalledWith("limit=2&offset=2");
+  expect(searchParams.get("offset")).toEqual("2");
+  // FIXME: useSelector mocks prevent updateGroups from being called
+  // expect(updateGroupsSpy).toBeCalledWith(2, 2);
 });

jsx/src/components/PaginationFooter/PaginationFooter.jsx

@@ -2,8 +2,6 @@ import React from "react";
 import PropTypes from "prop-types";
 import { Button, FormControl } from "react-bootstrap";
 
-import "./pagination-footer.css";
-
 const PaginationFooter = (props) => {
   const { offset, limit, visible, total, next, prev, handleLimit } = props;
   return (
@@ -13,33 +11,45 @@ const PaginationFooter = (props) => {
         {total ? `of ${total}` : ""}
         <br />
         {offset >= 1 ? (
-          <Button variant="light" size="sm">
-            <span
-              className="active-pagination"
-              data-testid="paginate-prev"
-              onClick={prev}
-            >
-              Previous
-            </span>
+          <Button
+            variant="light"
+            size="sm"
+            onClick={prev}
+            className="me-2"
+            data-testid="paginate-prev"
+          >
+            Previous
           </Button>
         ) : (
-          <Button variant="light" size="sm">
-            <span className="inactive-pagination">Previous</span>
+          <Button
+            variant="light"
+            size="sm"
+            className="me-2"
+            disabled
+            aria-disabled="true"
+          >
+            Previous
           </Button>
         )}
         {offset + visible < total ? (
-          <Button variant="light" size="sm">
-            <span
-              className="active-pagination"
-              data-testid="paginate-next"
-              onClick={next}
-            >
-              Next
-            </span>
+          <Button
+            variant="light"
+            size="sm"
+            className="me-2"
+            onClick={next}
+            data-testid="paginate-next"
+          >
+            Next
           </Button>
         ) : (
-          <Button variant="light" size="sm">
-            <span className="inactive-pagination">Next</span>
+          <Button
+            variant="light"
+            size="sm"
+            className="me-2"
+            disabled
+            aria-disabled="true"
+          >
+            Next
           </Button>
         )}
         <label>

jsx/src/components/PaginationFooter/pagination-footer.css

@@ -1,14 +0,0 @@
-@import url(../../style/root.css);
-
-.pagination-footer * button {
-  margin-right: 10px;
-}
-
-.pagination-footer * .inactive-pagination {
-  color: gray;
-  cursor: not-allowed;
-}
-
-.pagination-footer * button.spaced {
-  color: var(--blue);
-}

jsx/src/components/ServerDashboard/ServerDashboard.jsx

@@ -3,6 +3,7 @@ import { useSelector, useDispatch } from "react-redux";
 import { debounce } from "lodash";
 import PropTypes from "prop-types";
 import ErrorAlert from "../../util/error";
+import { User, Server } from "../../util/jhapiUtil";
 
 import {
   Button,
@@ -16,7 +17,7 @@ import {
 } from "react-bootstrap";
 import ReactObjectTableViewer from "../ReactObjectTableViewer/ReactObjectTableViewer";
 
-import { Link, useSearchParams, useNavigate } from "react-router-dom";
+import { Link, useSearchParams, useNavigate } from "react-router";
 import { FaSort, FaSortUp, FaSortDown } from "react-icons/fa";
 
 import "./server-dashboard.css";
@@ -41,7 +42,7 @@ const ServerDashboard = (props) => {
   let user_data = useSelector((state) => state.user_data);
   const user_page = useSelector((state) => state.user_page);
 
-  const { offset, setLimit, handleLimit, limit, setPagination } =
+  const { offset, setOffset, setLimit, handleLimit, limit } =
     usePaginationParams();
 
   const name_filter = searchParams.get("name_filter") || "";
@@ -64,12 +65,6 @@ const ServerDashboard = (props) => {
   } = props;
 
   const dispatchPageUpdate = (data, page) => {
-    // trigger page update in state
-    // in response to fetching updated user list
-    // data is list of user records
-    // page is _pagination part of response
-    // persist page info in url query
-    setPagination(page);
     // persist user data, triggers rerender
     dispatch({
       type: "USER_PAGE",
@@ -127,35 +122,47 @@ const ServerDashboard = (props) => {
     });
   };
 
-  // the callback to update the displayed user list
-  const updateUsersWithParams = (params) => {
-    if (params) {
-      if (params.offset !== undefined && params.offset < 0) {
-        params.offset = 0;
-      }
-    }
-    return updateUsers({
-      offset: offset,
-      limit,
-      name_filter,
-      sort,
-      state: state_filter,
-      ...params,
-    });
-  };
-
   // single callback to reload the page
-  // uses current state, or params can be specified if state
-  // should be updated _after_ load, e.g. offset
-  const loadPageData = (params) => {
-    return updateUsersWithParams(params)
-      .then((data) => dispatchPageUpdate(data.items, data._pagination))
-      .catch((err) => setErrorAlert("Failed to update user list."));
+  // uses current state
+  const loadPageData = () => {
+    const abortHandle = { cancelled: false };
+    (async () => {
+      try {
+        const data = await updateUsers({
+          offset,
+          limit,
+          name_filter,
+          sort,
+          state: state_filter,
+        });
+        // cancelled (e.g. param changed while waiting for response)
+        if (abortHandle.cancelled) return;
+        if (
+          data._pagination.offset &&
+          data._pagination.total <= data._pagination.offset
+        ) {
+          // reset offset if we're out of bounds,
+          // then load again
+          setOffset(0);
+          return;
+        }
+        // actually update page data
+        dispatchPageUpdate(data.items, data._pagination);
+      } catch (e) {
+        console.error("Failed to update user list.", e);
+        setErrorAlert("Failed to update user list.");
+      }
+    })();
+    // returns cancellation callback
+    return () => {
+      // cancel stale load
+      abortHandle.cancelled = true;
+    };
   };
 
   useEffect(() => {
-    loadPageData();
-  }, [limit, name_filter, sort, state_filter]);
+    return loadPageData();
+  }, [limit, name_filter, offset, sort, state_filter]);
 
   if (!user_data || !user_page) {
     return <div data-testid="no-show"></div>;
@@ -203,6 +210,15 @@ const ServerDashboard = (props) => {
     );
   };
 
+  ServerButton.propTypes = {
+    server: Server,
+    user: User,
+    action: PropTypes.string,
+    name: PropTypes.string,
+    variant: PropTypes.string,
+    extraClass: PropTypes.string,
+  };
+
   const StopServerButton = ({ server, user }) => {
     if (!server.ready) {
       return null;
@@ -216,6 +232,12 @@ const ServerDashboard = (props) => {
       extraClass: "stop-button",
     });
   };
+
+  StopServerButton.propTypes = {
+    server: Server,
+    user: User,
+  };
+
   const DeleteServerButton = ({ server, user }) => {
     if (!server.name) {
       // It's not possible to delete unnamed servers
@@ -234,6 +256,11 @@ const ServerDashboard = (props) => {
     });
   };
 
+  DeleteServerButton.propTypes = {
+    server: Server,
+    user: User,
+  };
+
   const StartServerButton = ({ server, user }) => {
     if (server.ready) {
       return null;
@@ -248,6 +275,11 @@ const ServerDashboard = (props) => {
     });
   };
 
+  StartServerButton.propTypes = {
+    server: Server,
+    user: User,
+  };
+
   const SpawnPageButton = ({ server, user }) => {
     if (server.ready) {
       return null;
@@ -265,6 +297,11 @@ const ServerDashboard = (props) => {
     );
   };
 
+  SpawnPageButton.propTypes = {
+    server: Server,
+    user: User,
+  };
+
   const AccessServerButton = ({ server }) => {
     if (!server.ready) {
       return null;
@@ -277,6 +314,9 @@ const ServerDashboard = (props) => {
       </a>
     );
   };
+  AccessServerButton.propTypes = {
+    server: Server,
+  };
 
   const EditUserButton = ({ user }) => {
     return (
@@ -297,10 +337,17 @@ const ServerDashboard = (props) => {
     );
   };
 
-  const ServerRowTable = ({ data }) => {
+  EditUserButton.propTypes = {
+    user: User,
+  };
+
+  const ServerRowTable = ({ data, exclude }) => {
     const sortedData = Object.keys(data)
       .sort()
       .reduce(function (result, key) {
+        if (exclude && exclude.includes(key)) {
+          return result;
+        }
         let value = data[key];
         switch (key) {
           case "last_activity":
@@ -340,88 +387,101 @@ const ServerDashboard = (props) => {
     );
   };
 
-  const serverRow = (user, server) => {
-    const { servers, ...userNoServers } = user;
+  ServerRowTable.propTypes = {
+    data: Server,
+    exclude: PropTypes.arrayOf(PropTypes.string),
+  };
+
+  const ServerRow = ({ user, server }) => {
     const serverNameDash = server.name ? `-${server.name}` : "";
     const userServerName = user.name + serverNameDash;
     const open = collapseStates[userServerName] || false;
-    return [
-      <tr
-        key={`${userServerName}-row`}
-        data-testid={`user-row-${userServerName}`}
-        className="user-row"
-      >
-        <td data-testid="user-row-name">
-          <span>
-            <Button
-              onClick={() =>
-                setCollapseStates({
-                  ...collapseStates,
-                  [userServerName]: !open,
-                })
-              }
-              aria-controls={`${userServerName}-collapse`}
-              aria-expanded={open}
-              data-testid={`${userServerName}-collapse-button`}
-              variant={open ? "secondary" : "primary"}
-              size="sm"
-            >
-              <span className="fa fa-caret-down"></span>
-            </Button>{" "}
-          </span>
-          <span data-testid={`user-name-div-${userServerName}`}>
-            {user.name}
-          </span>
-        </td>
-        <td data-testid="user-row-admin">{user.admin ? "admin" : ""}</td>
-
-        <td data-testid="user-row-server">
-          <p className="text-secondary">{server.name}</p>
-        </td>
-        <td data-testid="user-row-last-activity">
-          {server.last_activity ? timeSince(server.last_activity) : "Never"}
-        </td>
-        <td data-testid="user-row-server-activity" className="actions">
-          <StartServerButton server={server} user={user} />
-          <StopServerButton server={server} user={user} />
-          <DeleteServerButton server={server} user={user} />
-          <AccessServerButton server={server} />
-          <SpawnPageButton server={server} user={user} />
-          <EditUserButton user={user} />
-        </td>
-      </tr>,
-      <tr key={`${userServerName}-detail`}>
-        <td
-          colSpan={6}
-          style={{ padding: 0 }}
-          data-testid={`${userServerName}-td`}
+    return (
+      <Fragment key={`${userServerName}-row`}>
+        <tr
+          key={`${userServerName}-row`}
+          data-testid={`user-row-${userServerName}`}
+          className="user-row"
         >
-          <Collapse in={open} data-testid={`${userServerName}-collapse`}>
-            <CardGroup
-              id={`${userServerName}-card-group`}
-              style={{ width: "100%", margin: "0 auto", float: "none" }}
-            >
-              <Card style={{ width: "100%", padding: 3, margin: "0 auto" }}>
-                <Card.Title>User</Card.Title>
-                <ServerRowTable data={userNoServers} />
-              </Card>
-              <Card style={{ width: "100%", padding: 3, margin: "0 auto" }}>
-                <Card.Title>Server</Card.Title>
-                <ServerRowTable data={server} />
-              </Card>
-            </CardGroup>
-          </Collapse>
-        </td>
-      </tr>,
-    ];
+          <td data-testid="user-row-name">
+            <span>
+              <Button
+                onClick={() =>
+                  setCollapseStates({
+                    ...collapseStates,
+                    [userServerName]: !open,
+                  })
+                }
+                aria-controls={`${userServerName}-collapse`}
+                aria-expanded={open}
+                data-testid={`${userServerName}-collapse-button`}
+                variant={open ? "secondary" : "primary"}
+                size="sm"
+              >
+                <span className="fa fa-caret-down"></span>
+              </Button>{" "}
+            </span>
+            <span data-testid={`user-name-div-${userServerName}`}>
+              {user.name}
+            </span>
+          </td>
+          <td data-testid="user-row-admin">{user.admin ? "admin" : ""}</td>
+
+          <td data-testid="user-row-server">
+            <p className="text-secondary">{server.name}</p>
+          </td>
+          <td data-testid="user-row-last-activity">
+            {server.last_activity ? timeSince(server.last_activity) : "Never"}
+          </td>
+          <td data-testid="user-row-server-activity" className="actions">
+            <StartServerButton server={server} user={user} />
+            <StopServerButton server={server} user={user} />
+            <DeleteServerButton server={server} user={user} />
+            <AccessServerButton server={server} />
+            <SpawnPageButton server={server} user={user} />
+            <EditUserButton user={user} />
+          </td>
+        </tr>
+        <tr key={`${userServerName}-detail`}>
+          <td
+            colSpan={6}
+            style={{ padding: 0 }}
+            data-testid={`${userServerName}-td`}
+          >
+            <Collapse in={open} data-testid={`${userServerName}-collapse`}>
+              <CardGroup
+                id={`${userServerName}-card-group`}
+                style={{ width: "100%", margin: "0 auto", float: "none" }}
+              >
+                <Card style={{ width: "100%", padding: 3, margin: "0 auto" }}>
+                  <Card.Title>User</Card.Title>
+                  <ServerRowTable data={user} exclude={["server", "servers"]} />
+                </Card>
+                <Card style={{ width: "100%", padding: 3, margin: "0 auto" }}>
+                  <Card.Title>Server</Card.Title>
+                  <ServerRowTable data={server} />
+                </Card>
+              </CardGroup>
+            </Collapse>
+          </td>
+        </tr>
+      </Fragment>
+    );
   };
 
-  let servers = user_data.flatMap((user) => {
-    let userServers = Object.values({
+  ServerRow.propTypes = {
+    user: User,
+    server: Server,
+  };
+
+  const serverRows = user_data.flatMap((user) => {
+    const userServers = Object.values({
+      // eslint-disable-next-line react/prop-types
       "": user.server || {},
+      // eslint-disable-next-line react/prop-types
       ...(user.servers || {}),
     });
-    return userServers.map((server) => [user, server]);
+    return userServers.map((server) => ServerRow({ user, server }));
   });
 
   return (
@@ -453,7 +513,7 @@ const ServerDashboard = (props) => {
                   setStateFilter(event.target.checked ? "active" : null);
                 }}
               />
-              <Form.Check.Label for="active-servers-filter">
+              <Form.Check.Label htmlFor="active-servers-filter">
                 {"only active servers"}
               </Form.Check.Label>
             </Form.Check>
@@ -508,7 +568,7 @@ const ServerDashboard = (props) => {
                   variant="primary"
                   className="start-all"
                   data-testid="start-all"
-                  title="start all servers on the current page"
+                  title="Start all default servers on the current page"
                   onClick={() => {
                     Promise.all(startAll(user_data.map((e) => e.name)))
                       .then((res) => {
@@ -539,11 +599,12 @@ const ServerDashboard = (props) => {
                   variant="danger"
                   className="stop-all"
                   data-testid="stop-all"
-                  title="stop all servers on the current page"
+                  title="Stop all servers including named servers on the current page"
                   onClick={() => {
                     Promise.all(stopAll(user_data.map((e) => e.name)))
                       .then((res) => {
-                        let failedServers = res.filter((e) => !e.ok);
+                        // Array of arrays of servers for each user
+                        let failedServers = res.flat().filter((e) => !e.ok);
                         if (failedServers.length > 0) {
                           setErrorAlert(
                             `Failed to stop ${failedServers.length} ${
@@ -576,20 +637,20 @@ const ServerDashboard = (props) => {
                 </Button>
               </td>
             </tr>
-            {servers.flatMap(([user, server]) => serverRow(user, server))}
+            {serverRows}
           </tbody>
         </table>
         <PaginationFooter
-          offset={offset}
+          // use user_page for display, which is what's on the page
+          // setOffset immediately updates url state and _requests_ an update
+          // but takes finite time before user_page is updated
+          offset={user_page.offset}
           limit={limit}
           visible={user_data.length}
           total={total}
-          // don't trigger via setOffset state change,
-          // which can cause infinite cycles.
-          // offset state will be set upon reply via setPagination
-          next={() => loadPageData({ offset: offset + limit })}
+          next={() => setOffset(user_page.offset + limit)}
           prev={() =>
-            loadPageData({ offset: limit > offset ? 0 : offset - limit })
+            setOffset(limit > user_page.offset ? 0 : user_page.offset - limit)
           }
           handleLimit={handleLimit}
         />
@@ -600,7 +661,7 @@ const ServerDashboard = (props) => {
 };
 
 ServerDashboard.propTypes = {
-  user_data: PropTypes.array,
+  user_data: PropTypes.arrayOf(User),
   updateUsers: PropTypes.func,
   shutdownHub: PropTypes.func,
   startServer: PropTypes.func,

jsx/src/components/ServerDashboard/ServerDashboard.test.js

@@ -1,7 +1,6 @@
-import React from "react";
-import { withProps } from "recompose";
+import React, { act } from "react";
+import { withProps } from "../../util/_recompose";
 import "@testing-library/jest-dom";
-import { act } from "react-dom/test-utils";
 import userEvent from "@testing-library/user-event";
 import {
   render,
@@ -10,8 +9,7 @@ import {
   getByText,
   getAllByRole,
 } from "@testing-library/react";
-import { HashRouter, Routes, Route, useSearchParams } from "react-router-dom";
-// import { CompatRouter,  } from "react-router-dom-v5-compat";
+import { HashRouter, Routes, Route, useSearchParams } from "react-router";
 import { Provider, useSelector } from "react-redux";
 import { createStore } from "redux";
 // eslint-disable-next-line
@@ -24,8 +22,8 @@ jest.mock("react-redux", () => ({
   ...jest.requireActual("react-redux"),
   useSelector: jest.fn(),
 }));
-jest.mock("react-router-dom", () => ({
-  ...jest.requireActual("react-router-dom"),
+jest.mock("react-router", () => ({
+  ...jest.requireActual("react-router"),
   useSearchParams: jest.fn(),
 }));
 
@@ -207,7 +205,6 @@ let mockUpdateUsers = jest.fn(({ offset, limit, sort, name_filter, state }) => {
 let searchParams = new URLSearchParams();
 
 beforeEach(() => {
-  jest.useFakeTimers();
   useSelector.mockImplementation((callback) => {
     return callback(mockAppState());
   });
@@ -291,7 +288,7 @@ test("Invokes the startServer event on button click", async () => {
   expect(start_elems.length).toBe(Object.keys(bar_servers).length);
 
   await act(async () => {
-    fireEvent.click(start_elems[0]);
+    await fireEvent.click(start_elems[0]);
   });
 
   expect(callbackSpy).toHaveBeenCalled();
@@ -307,7 +304,7 @@ test("Invokes the stopServer event on button click", async () => {
   let stop = screen.getByText("Stop Server");
 
   await act(async () => {
-    fireEvent.click(stop);
+    await fireEvent.click(stop);
   });
 
   expect(callbackSpy).toHaveBeenCalled();
@@ -323,7 +320,7 @@ test("Invokes the shutdownHub event on button click", async () => {
   let shutdown = screen.getByText("Shutdown Hub");
 
   await act(async () => {
-    fireEvent.click(shutdown);
+    await fireEvent.click(shutdown);
   });
 
   expect(callbackSpy).toHaveBeenCalled();
@@ -338,7 +335,7 @@ test("Sorts according to username", async () => {
 
   expect(searchParams.get("sort")).toEqual(null);
   let handler = screen.getByTestId(testId);
-  fireEvent.click(handler);
+  await fireEvent.click(handler);
   expect(searchParams.get("sort")).toEqual("name");
 
   await act(async () => {
@@ -346,7 +343,7 @@ test("Sorts according to username", async () => {
     handler = screen.getByTestId(testId);
   });
 
-  fireEvent.click(handler);
+  await fireEvent.click(handler);
   expect(searchParams.get("sort")).toEqual("-name");
 
   await act(async () => {
@@ -354,7 +351,7 @@ test("Sorts according to username", async () => {
     handler = screen.getByTestId(testId);
   });
 
-  fireEvent.click(handler);
+  await fireEvent.click(handler);
   expect(searchParams.get("sort")).toEqual("name");
 });
 
@@ -367,7 +364,7 @@ test("Sorts according to last activity", async () => {
 
   expect(searchParams.get("sort")).toEqual(null);
   let handler = screen.getByTestId(testId);
-  fireEvent.click(handler);
+  await fireEvent.click(handler);
   expect(searchParams.get("sort")).toEqual("last_activity");
 
   await act(async () => {
@@ -375,7 +372,7 @@ test("Sorts according to last activity", async () => {
     handler = screen.getByTestId(testId);
   });
 
-  fireEvent.click(handler);
+  await fireEvent.click(handler);
   expect(searchParams.get("sort")).toEqual("-last_activity");
 
   await act(async () => {
@@ -383,7 +380,7 @@ test("Sorts according to last activity", async () => {
     handler = screen.getByTestId(testId);
   });
 
-  fireEvent.click(handler);
+  await fireEvent.click(handler);
   expect(searchParams.get("sort")).toEqual("last_activity");
 });
 
@@ -392,12 +389,10 @@ test("Filter according to server status (running/not running)", async () => {
   await act(async () => {
     rerender = render(serverDashboardJsx()).rerender;
   });
-  console.log(rerender);
-  console.log("begin test");
   const label = "only active servers";
   let handler = screen.getByLabelText(label);
   expect(handler.checked).toEqual(false);
-  fireEvent.click(handler);
+  await fireEvent.click(handler);
 
   // FIXME: need to force a rerender to get updated checkbox
   // I don't think this should be required
@@ -408,7 +403,7 @@ test("Filter according to server status (running/not running)", async () => {
   expect(searchParams.get("state")).toEqual("active");
   expect(handler.checked).toEqual(true);
 
-  fireEvent.click(handler);
+  await fireEvent.click(handler);
 
   await act(async () => {
     rerender(serverDashboardJsx());
@@ -431,17 +426,14 @@ test("Shows server details with button click", async () => {
   expect(collapse).toHaveClass("collapse");
   expect(collapse).not.toHaveClass("show");
   expect(collapseBar).not.toHaveClass("show");
-
+  await fireEvent.click(button);
   await act(async () => {
-    fireEvent.click(button);
     jest.runAllTimers();
   });
-
   expect(collapse).toHaveClass("collapse show");
   expect(collapseBar).not.toHaveClass("show");
-
+  await fireEvent.click(button);
   await act(async () => {
-    fireEvent.click(button);
     jest.runAllTimers();
   });
 
@@ -449,8 +441,8 @@ test("Shows server details with button click", async () => {
   expect(collapse).not.toHaveClass("show");
   expect(collapseBar).not.toHaveClass("show");
 
+  await fireEvent.click(button);
   await act(async () => {
-    fireEvent.click(button);
     jest.runAllTimers();
   });
 
@@ -480,7 +472,7 @@ test("Shows a UI error dialogue when start all servers fails", async () => {
   let startAll = screen.getByTestId("start-all");
 
   await act(async () => {
-    fireEvent.click(startAll);
+    await fireEvent.click(startAll);
   });
 
   let errorDialog = screen.getByText("Failed to start servers.");
@@ -496,7 +488,7 @@ test("Shows a UI error dialogue when stop all servers fails", async () => {
   let stopAll = screen.getByTestId("stop-all");
 
   await act(async () => {
-    fireEvent.click(stopAll);
+    await fireEvent.click(stopAll);
   });
 
   let errorDialog = screen.getByText("Failed to stop servers.");
@@ -513,7 +505,7 @@ test("Shows a UI error dialogue when start user server fails", async () => {
   expect(start_elems.length).toBe(Object.keys(bar_servers).length);
 
   await act(async () => {
-    fireEvent.click(start_elems[0]);
+    await fireEvent.click(start_elems[0]);
   });
 
   let errorDialog = screen.getByText("Failed to start server.");
@@ -531,7 +523,7 @@ test("Shows a UI error dialogue when start user server returns an improper statu
   expect(start_elems.length).toBe(Object.keys(bar_servers).length);
 
   await act(async () => {
-    fireEvent.click(start_elems[0]);
+    await fireEvent.click(start_elems[0]);
   });
 
   let errorDialog = screen.getByText("Failed to start server.");
@@ -550,7 +542,7 @@ test("Shows a UI error dialogue when stop user servers fails", async () => {
   let stop = screen.getByText("Stop Server");
 
   await act(async () => {
-    fireEvent.click(stop);
+    await fireEvent.click(stop);
   });
 
   let errorDialog = screen.getByText("Failed to stop server.");
@@ -569,7 +561,7 @@ test("Shows a UI error dialogue when stop user server returns an improper status
   let stop = screen.getByText("Stop Server");
 
   await act(async () => {
-    fireEvent.click(stop);
+    await fireEvent.click(stop);
   });
 
   let errorDialog = screen.getByText("Failed to stop server.");
@@ -584,12 +576,13 @@ test("Search for user calls updateUsers with name filter", async () => {
     render(serverDashboardJsx());
   });
 
+  const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime });
   let search = screen.getByLabelText("user-search");
 
   expect(mockUpdateUsers.mock.calls).toHaveLength(1);
 
   expect(searchParams.get("offset")).toEqual("2");
-  userEvent.type(search, "a");
+  await user.type(search, "a");
   expect(search.value).toEqual("a");
   await act(async () => {
     jest.runAllTimers();
@@ -599,7 +592,7 @@ test("Search for user calls updateUsers with name filter", async () => {
   // FIXME: useSelector mocks prevent updateUsers from being called
   // expect(mockUpdateUsers.mock.calls).toHaveLength(2);
   // expect(mockUpdateUsers).toBeCalledWith(0, 100, "a");
-  userEvent.type(search, "b");
+  await user.type(search, "b");
   expect(search.value).toEqual("ab");
   await act(async () => {
     jest.runAllTimers();
@@ -624,11 +617,12 @@ test("Interacting with PaginationFooter requests page update", async () => {
     fireEvent.click(next);
     jest.runAllTimers();
   });
-
-  expect(mockUpdateUsers).toBeCalledWith({
-    ...defaultUpdateUsersParams,
-    offset: 2,
-  });
+  expect(searchParams.get("offset")).toEqual("2");
+  // FIXME: useSelector mocks prevent updateUsers from being called
+  // expect(mockUpdateUsers).toBeCalledWith({
+  //   ...defaultUpdateUsersParams,
+  //   offset: 2,
+  // });
 });
 
 test("Server delete button exists for named servers", async () => {
@@ -672,7 +666,7 @@ test("Start server and confirm pending state", async () => {
   expect(buttons[2].textContent).toBe("Edit User");
 
   await act(async () => {
-    fireEvent.click(buttons[0]);
+    await fireEvent.click(buttons[0]);
   });
   expect(mockUpdateUsers.mock.calls).toHaveLength(1);
 

jsx/src/util/_recompose.js

@@ -0,0 +1,35 @@
+// extracted tiny subset we use from react-recompose
+// we probably don't need these at all,
+// but vendor before refactoring
+
+// https://github.com/acdlite/recompose
+// License: MIT
+// Copyright (c) 2015-2018 Andrew Clark
+
+import { createElement } from "react";
+
+function createFactory(type) {
+  return createElement.bind(null, type);
+}
+
+export const compose = (...funcs) =>
+  funcs.reduce(
+    (a, b) =>
+      (...args) =>
+        a(b(...args)),
+    (arg) => arg,
+  );
+
+const mapProps = (propsMapper) => (BaseComponent) => {
+  const factory = createFactory(BaseComponent);
+  const MapProps = (props) => factory(propsMapper(props));
+  return MapProps;
+};
+
+export const withProps = (input) => {
+  const hoc = mapProps((props) => ({
+    ...props,
+    ...(typeof input === "function" ? input(props) : input),
+  }));
+  return hoc;
+};

jsx/src/util/jhapiUtil.js

@@ -1,9 +1,11 @@
+import PropTypes from "prop-types";
+
 const jhdata = window.jhdata || {};
 const base_url = jhdata.base_url || "/";
 const xsrfToken = jhdata.xsrf_token;
 
 export const jhapiRequest = (endpoint, method, data) => {
-  let api_url = new URL(`${base_url}hub/api` + endpoint, location.origin);
+  let api_url = new URL(`${base_url}api` + endpoint, location.origin);
   if (xsrfToken) {
     api_url.searchParams.set("_xsrf", xsrfToken);
   }
@@ -17,3 +19,21 @@ export const jhapiRequest = (endpoint, method, data) => {
     body: data ? JSON.stringify(data) : null,
   });
 };
+
+// need to declare the subset of fields we use, at least
+export const Server = PropTypes.shape({
+  name: PropTypes.string,
+  url: PropTypes.string,
+  active: PropTypes.boolean,
+  pending: PropTypes.string,
+  last_activity: PropTypes.string,
+});
+
+export const User = PropTypes.shape({
+  admin: PropTypes.boolean,
+  name: PropTypes.string,
+  last_activity: PropTypes.string,
+  url: PropTypes.string,
+  server: Server,
+  servers: PropTypes.objectOf(Server),
+});

jsx/src/util/layout.jsx

@@ -1,7 +1,7 @@
 import React from "react";
-import { withProps } from "recompose";
 import { Col, Row, Container } from "react-bootstrap";
 import PropTypes from "prop-types";
+import { withProps } from "./_recompose";
 import ErrorAlert from "./error";
 
 export const MainCol = (props) => {
@@ -34,5 +34,5 @@ export const MainContainer = (props) => {
 MainContainer.propTypes = {
   errorAlert: PropTypes.string,
   setErrorAlert: PropTypes.func,
-  children: PropTypes.array,
+  children: PropTypes.node,
 };

jsx/src/util/paginationParams.js

@@ -1,5 +1,5 @@
 import { debounce } from "lodash";
-import { useSearchParams } from "react-router-dom";
+import { useSearchParams } from "react-router";
 
 export const usePaginationParams = () => {
   // get offset, limit, name filter from URL

jsx/src/util/withAPI.js

@@ -1,4 +1,4 @@
-import { withProps } from "recompose";
+import { withProps } from "./_recompose";
 import { jhapiRequest } from "./jhapiUtil";
 
 const withAPI = withProps(() => ({
@@ -30,7 +30,17 @@ const withAPI = withProps(() => ({
   startAll: (names) =>
     names.map((e) => jhapiRequest("/users/" + e + "/server", "POST")),
   stopAll: (names) =>
-    names.map((e) => jhapiRequest("/users/" + e + "/server", "DELETE")),
+    names.map((name) =>
+      jhapiRequest("/users/" + name, "GET")
+        .then((data) => data.json())
+        .then((data) =>
+          Promise.all(
+            Object.keys(data.servers).map((server) =>
+              jhapiRequest("/users/" + name + "/servers/" + server, "DELETE"),
+            ),
+          ),
+        ),
+    ),
   addToGroup: (users, groupname) =>
     jhapiRequest("/groups/" + groupname + "/users", "POST", { users }),
   updateProp: (propobject, groupname) =>

jsx/testing/setup.jest.js

@@ -0,0 +1,5 @@
+// Workaround "ReferenceError: TextEncoder is not defined"
+// https://stackoverflow.com/questions/68468203/why-am-i-getting-textencoder-is-not-defined-in-jest/68468204#68468204
+// https://jestjs.io/docs/configuration#setupfiles-array
+import { TextEncoder, TextDecoder } from "util";
+Object.assign(global, { TextDecoder, TextEncoder });

jupyterhub/_version.py

@@ -3,7 +3,7 @@
 # Copyright (c) Jupyter Development Team.
 # Distributed under the terms of the Modified BSD License.
 # version_info updated by running `tbump`
-version_info = (5, 1, 0, "", "")
+version_info = (5, 3, 0, "", "")
 
 # pep 440 version: no dot before beta/rc, but before .dev
 # 0.1.0rc1

jupyterhub/_xsrf_utils.py

@@ -10,7 +10,9 @@ in both Hub and single-user code
 
 import base64
 import hashlib
+import os
 from http.cookies import SimpleCookie
+from ipaddress import ip_address, ip_network
 
 from tornado import web
 from tornado.log import app_log
@@ -104,9 +106,12 @@ def _get_xsrf_token_cookie(handler):
     return (None, None)
 
 
-def _set_xsrf_cookie(handler, xsrf_id, *, cookie_path="", authenticated=None):
+def _set_xsrf_cookie(
+    handler, xsrf_id, *, cookie_path="", authenticated=None, xsrf_token=None
+):
     """Set xsrf token cookie"""
-    xsrf_token = _create_signed_value_urlsafe(handler, "_xsrf", xsrf_id)
+    if xsrf_token is None:
+        xsrf_token = _create_signed_value_urlsafe(handler, "_xsrf", xsrf_id)
     xsrf_cookie_kwargs = {}
     xsrf_cookie_kwargs.update(handler.settings.get('xsrf_cookie_kwargs', {}))
     xsrf_cookie_kwargs.setdefault("path", cookie_path)
@@ -128,6 +133,7 @@ def _set_xsrf_cookie(handler, xsrf_id, *, cookie_path="", authenticated=None):
         xsrf_cookie_kwargs,
     )
     handler.set_cookie("_xsrf", xsrf_token, **xsrf_cookie_kwargs)
+    return xsrf_token
 
 
 def get_xsrf_token(handler, cookie_path=""):
@@ -173,7 +179,9 @@ def get_xsrf_token(handler, cookie_path=""):
             )
 
     if _set_cookie:
-        _set_xsrf_cookie(handler, xsrf_id, cookie_path=cookie_path)
+        _set_xsrf_cookie(
+            handler, xsrf_id, cookie_path=cookie_path, xsrf_token=xsrf_token
+        )
     handler._xsrf_token = xsrf_token
     return xsrf_token
 
@@ -230,18 +238,71 @@ def check_xsrf_cookie(handler):
         )
 
 
+# allow disabling using ip in anonymous id
+def _get_anonymous_ip_cidrs():
+    """
+    List of CIDRs to consider anonymous from $JUPYTERHUB_XSRF_ANONYMOUS_IP_CIDRS
+
+    e.g. private network IPs, which likely mean proxy ips
+    and do not meaningfully distinguish users
+    (fixing proxy headers would usually fix this).
+    """
+    cidr_list_env = os.environ.get("JUPYTERHUB_XSRF_ANONYMOUS_IP_CIDRS")
+    if not cidr_list_env:
+        return []
+    return [ip_network(cidr) for cidr in cidr_list_env.split(";")]
+
+
+_anonymous_ip_cidrs = _get_anonymous_ip_cidrs()
+
+# allow specifying which headers to use for anonymous id
+# (default: User-Agent)
+# these should be stable (over a few minutes) for a single client and unlikely
+# to be shared across users
+_anonymous_id_headers = os.environ.get(
+    "JUPYTERHUB_XSRF_ANONYMOUS_ID_HEADERS", "User-Agent"
+).split(";")
+
+
 def _anonymous_xsrf_id(handler):
     """Generate an appropriate xsrf token id for an anonymous request
 
     Currently uses hash of request ip and user-agent
 
+    These are typically used only for the initial login page,
+    and don't need to be perfectly unique, just:
+
+    1. reasonably stable for a single user for the duration of a login
+       (a few requests, which may pass through different proxies)
+    2. somewhat unlikely to be shared across users
+
     These are typically used only for the initial login page,
     so only need to be valid for a few seconds to a few minutes
     (enough to submit a login form with MFA).
     """
     hasher = hashlib.sha256()
-    hasher.update(handler.request.remote_ip.encode("ascii"))
-    hasher.update(
-        handler.request.headers.get("User-Agent", "").encode("utf8", "replace")
-    )
+    ip = ip_to_hash = handler.request.remote_ip
+    try:
+        ip_addr = ip_address(ip)
+    except ValueError as e:
+        # invalid ip ?!
+        app_log.error("Error parsing remote ip %r: %s", ip, e)
+    else:
+        # if the ip is private (e.g. a cluster ip),
+        # this is almost certainly a proxy ip and not useful
+        # for distinguishing request origin.
+        # A proxy has the double downside of multiple replicas
+        # meaning the value can change from one request to the next for the
+        # same 'true' origin, resulting in unavoidable xsrf mismatch errors
+        for cidr in _anonymous_ip_cidrs:
+            if ip_addr in cidr:
+                # use matching cidr
+                ip_to_hash = str(cidr)
+                break
+    hasher.update(ip_to_hash.encode("ascii"))
+    for name in _anonymous_id_headers:
+        header = handler.request.headers.get(name, "")
+        hasher.update(header.encode("utf8", "replace"))
+        # field delimiter (should be something not valid utf8)
+        hasher.update(b"\xff")
     return base64.urlsafe_b64encode(hasher.digest()).decode("ascii")

jupyterhub/apihandlers/groups.py

@@ -3,6 +3,7 @@
 # Copyright (c) Jupyter Development Team.
 # Distributed under the terms of the Modified BSD License.
 import json
+from warnings import warn
 
 from tornado import web
 
@@ -35,6 +36,11 @@ class _GroupAPIHandler(APIHandler):
 
     def check_authenticator_managed_groups(self):
         """Raise error on group-management APIs if Authenticator is managing groups"""
+        warn(
+            "check_authenticator_managed_groups is deprecated in JupyterHub 5.3.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         if self.authenticator.manage_groups:
             raise web.HTTPError(400, "Group management via API is disabled")
 
@@ -73,9 +79,6 @@ class GroupListAPIHandler(_GroupAPIHandler):
     @needs_scope('admin:groups')
     async def post(self):
         """POST creates Multiple groups"""
-
-        self.check_authenticator_managed_groups()
-
         model = self.get_json_body()
         if not model or not isinstance(model, dict) or not model.get('groups'):
             raise web.HTTPError(400, "Must specify at least one group to create")
@@ -115,7 +118,6 @@ class GroupAPIHandler(_GroupAPIHandler):
     @needs_scope('admin:groups')
     async def post(self, group_name):
         """POST creates a group by name"""
-        self.check_authenticator_managed_groups()
         model = self.get_json_body()
         if model is None:
             model = {}
@@ -143,7 +145,6 @@ class GroupAPIHandler(_GroupAPIHandler):
     @needs_scope('delete:groups')
     def delete(self, group_name):
         """Delete a group by name"""
-        self.check_authenticator_managed_groups()
         group = self.find_group(group_name)
         self.log.info("Deleting group %s", group_name)
         self.db.delete(group)
@@ -157,7 +158,6 @@ class GroupUsersAPIHandler(_GroupAPIHandler):
     @needs_scope('groups')
     def post(self, group_name):
         """POST adds users to a group"""
-        self.check_authenticator_managed_groups()
         group = self.find_group(group_name)
         data = self.get_json_body()
         self._check_group_model(data)
@@ -176,7 +176,6 @@ class GroupUsersAPIHandler(_GroupAPIHandler):
     @needs_scope('groups')
     async def delete(self, group_name):
         """DELETE removes users from a group"""
-        self.check_authenticator_managed_groups()
         group = self.find_group(group_name)
         data = self.get_json_body()
         self._check_group_model(data)

jupyterhub/apihandlers/hub.py

@@ -52,6 +52,17 @@ class ShutdownAPIHandler(APIHandler):
 
 
 class RootAPIHandler(APIHandler):
+    def set_default_headers(self):
+        """
+        Set any headers passed as tornado_settings['headers'].
+
+        Also responsible for setting content-type header
+        """
+        if 'Access-Control-Allow-Origin' not in self.settings.get("headers", {}):
+            # allow CORS requests to this endpoint by default
+            self.set_header('Access-Control-Allow-Origin', '*')
+        super().set_default_headers()
+
     def check_xsrf_cookie(self):
         return
 

jupyterhub/apihandlers/users.py

@@ -260,7 +260,7 @@ class UserListAPIHandler(APIHandler):
             raise web.HTTPError(400, msg)
 
         if not to_create:
-            raise web.HTTPError(409, "All %i users already exist" % len(usernames))
+            raise web.HTTPError(409, f"All {len(usernames)} users already exist")
 
         created = []
         for name in to_create:

jupyterhub/app.py

@@ -282,7 +282,7 @@ class JupyterHub(Application):
 
     @default('classes')
     def _load_classes(self):
-        classes = [Spawner, Authenticator, CryptKeeper]
+        classes = {Spawner, Authenticator, CryptKeeper}
         for name, trait in self.traits(config=True).items():
             # load entry point groups into configurable class list
             # so that they show up in config files, etc.
@@ -298,9 +298,9 @@ class JupyterHub(Application):
                             e,
                         )
                         continue
-                    if cls not in classes and isinstance(cls, Configurable):
-                        classes.append(cls)
-        return classes
+                    if issubclass(cls, Configurable):
+                        classes.add(cls)
+        return list(classes)
 
     load_groups = Dict(
         Union([Dict(), List()]),
@@ -873,13 +873,7 @@ class JupyterHub(Application):
         but your identity provider is likely much more strict,
         allowing you to make assumptions about the name.
 
-        The default behavior is to have all services
-        on a single `services.{domain}` subdomain,
-        and each user on `{username}.{domain}`.
-        This is the 'legacy' scheme,
-        and doesn't work for all usernames.
-
-        The 'idna' scheme is a new scheme that should produce a valid domain name for any user,
+        The 'idna' hook should produce a valid domain name for any user,
         using IDNA encoding for unicode usernames, and a truncate-and-hash approach for
         any usernames that can't be easily encoded into a domain component.
 
@@ -1698,7 +1692,11 @@ class JupyterHub(Application):
         """add a url prefix to handlers"""
         for i, tup in enumerate(handlers):
             lis = list(tup)
-            lis[0] = url_path_join(prefix, tup[0])
+            if tup[0]:
+                lis[0] = url_path_join(prefix, tup[0])
+            else:
+                # the '' route should match /prefix not /prefix/
+                lis[0] = prefix.rstrip("/")
             handlers[i] = tuple(lis)
         return handlers
 
@@ -1928,7 +1926,11 @@ class JupyterHub(Application):
                 self.internal_ssl_components_trust
             )
 
-            default_alt_names = ["IP:127.0.0.1", "DNS:localhost"]
+            default_alt_names = [
+                "IP:127.0.0.1",
+                "IP:0:0:0:0:0:0:0:1",
+                "DNS:localhost",
+            ]
             if self.subdomain_host:
                 default_alt_names.append(
                     f"DNS:{urlparse(self.subdomain_host).hostname}"
@@ -2182,7 +2184,11 @@ class JupyterHub(Application):
         # but changes to the allowed_users set can occur in the database,
         # and persist across sessions.
         total_users = 0
+        blocked_users = self.authenticator.blocked_users
         for user in db.query(orm.User):
+            if user.name in blocked_users:
+                # don't call add_user with blocked users
+                continue
             try:
                 f = self.authenticator.add_user(user)
                 if f:
@@ -2238,6 +2244,35 @@ class JupyterHub(Application):
                 await maybe_future(f)
         return user
 
+    async def init_blocked_users(self):
+        """Revoke all permissions for users in Authenticator.blocked_users"""
+        blocked_users = self.authenticator.blocked_users
+        if not blocked_users:
+            # nothing to check
+            return
+        db = self.db
+        for user in db.query(orm.User).filter(orm.User.name.in_(blocked_users)):
+            # revoke permissions from blocked users
+            # so already-issued credentials have no access to the API
+            self.log.debug(f"Found blocked user in database: {user.name}")
+            if user.admin:
+                self.log.warning(
+                    f"Removing admin permissions from blocked user {user.name}"
+                )
+                user.admin = False
+            if user.roles:
+                self.log.warning(
+                    f"Removing blocked user {user.name} from roles: {', '.join(role.name for role in user.roles)}"
+                )
+                user.roles = []
+            if user.groups:
+                self.log.warning(
+                    f"Removing blocked user {user.name} from groups: {', '.join(group.name for group in user.groups)}"
+                )
+                user.groups = []
+
+        db.commit()
+
     async def init_groups(self):
         """Load predefined groups into the database"""
         db = self.db
@@ -2965,6 +3000,18 @@ class JupyterHub(Application):
         async def check_spawner(user, name, spawner):
             status = 0
             if spawner.server:
+                if user.name in self.authenticator.blocked_users:
+                    self.log.warning(
+                        f"Stopping spawner for blocked user: {spawner._log_name}"
+                    )
+                    try:
+                        await user.stop(name)
+                    except Exception:
+                        self.log.exception(
+                            f"Failed to stop {spawner._log_name}",
+                            exc_info=True,
+                        )
+                    return
                 try:
                     status = await spawner.poll()
                 except Exception:
@@ -3281,7 +3328,7 @@ class JupyterHub(Application):
         if self.pid_file:
             self.log.debug("Writing PID %i to %s", pid, self.pid_file)
             with open(self.pid_file, 'w') as f:
-                f.write('%i' % pid)
+                f.write(str(pid))
 
     @catch_config_error
     async def initialize(self, *args, **kwargs):
@@ -3356,6 +3403,7 @@ class JupyterHub(Application):
         self.init_services()
         await self.init_api_tokens()
         await self.init_role_assignment()
+        await self.init_blocked_users()
         self.init_tornado_settings()
         self.init_handlers()
         self.init_tornado_application()
@@ -3414,7 +3462,6 @@ class JupyterHub(Application):
         metrics_collector = self.metrics_collector = PeriodicMetricsCollector(
             parent=self, db=self.db
         )
-        metrics_collector.start()
 
     async def cleanup(self):
         """Shutdown managed services and various subprocesses. Cleanup runtime files."""
@@ -3595,7 +3642,7 @@ class JupyterHub(Application):
                     if service.managed:
                         status = await service.spawner.poll()
                         if status is not None:
-                            self.log.error(
+                            self.log.critical(
                                 "Service %s exited with status %s",
                                 service_name,
                                 status,
@@ -3604,12 +3651,19 @@ class JupyterHub(Application):
                 else:
                     return True
             else:
-                self.log.error(
-                    "Cannot connect to %s service %s at %s. Is it running?",
-                    service.kind,
-                    service_name,
-                    service.url,
-                )
+                if service.managed:
+                    self.log.critical(
+                        "Cannot connect to %s service %s",
+                        service_name,
+                        service.kind,
+                    )
+                else:
+                    self.log.warning(
+                        "Cannot connect to %s service %s at %s. Is it running?",
+                        service.kind,
+                        service_name,
+                        service.url,
+                    )
                 return False
         return True
 
@@ -3643,6 +3697,9 @@ class JupyterHub(Application):
             loop.stop()
             return
 
+        # start collecting metrics
+        self.metrics_collector.start()
+
         # start the proxy
         if self.proxy.should_start:
             try:
@@ -3697,18 +3754,8 @@ class JupyterHub(Application):
         # start the service(s)
         for service_name, service in self._service_map.items():
             service_ready = await self.start_service(service_name, service, ssl_context)
-            if not service_ready:
-                if service.from_config:
-                    # Stop the application if a config-based service failed to start.
-                    self.exit(1)
-                else:
-                    # Only warn for database-based service, so that admin can connect
-                    # to hub to remove the service.
-                    self.log.error(
-                        "Failed to reach externally managed service %s",
-                        service_name,
-                        exc_info=True,
-                    )
+            if not service_ready and service.managed:
+                self.exit(1)
 
         await self.proxy.check_routes(self.users, self._service_map)
 
@@ -3900,4 +3947,8 @@ UpgradeDB.classes.append(JupyterHub)
 main = JupyterHub.launch_instance
 
 if __name__ == "__main__":
-    main()
+    # don't invoke __main__.main here because __main__.JupyterHub
+    # is not jupyterhub.app.JupyterHub. There will be two!
+    from jupyterhub import app
+
+    app.JupyterHub.launch_instance()

jupyterhub/auth.py

@@ -77,10 +77,16 @@ class Authenticator(LoggingConfigurable):
         help="""The max age (in seconds) of authentication info
         before forcing a refresh of user auth info.
 
-        Refreshing auth info allows, e.g. requesting/re-validating auth tokens.
+        Authenticators that support it may re-load managed groups,
+        refresh auth tokens, etc., or force a new login if auth info cannot be refreshed.
 
-        See :meth:`.refresh_user` for what happens when user auth info is refreshed
-        (nothing by default).
+        See :meth:`.refresh_user` for what happens when user auth info is refreshed,
+        which varies by authenticator.
+        If an Authenticator does not implement `refresh_user`,
+        auth info will never be considered stale.
+
+        Set `auth_refresh_age = 0` to disable time-based calls to `refresh_user`.
+        You can still use :attr:`refresh_pre_spawn` if `auth_refresh_age` is disabled.
         """,
     )
 
@@ -223,6 +229,7 @@ class Authenticator(LoggingConfigurable):
 
         Authenticator subclasses may override the default with e.g.::
 
+            from traitlets import default
             @default("allow_all")
             def _default_allow_all(self):
                 # if _any_ auth config (depends on the Authenticator)
@@ -300,6 +307,14 @@ class Authenticator(LoggingConfigurable):
         If empty, does not perform any additional restriction.
 
         .. versionadded: 0.9
+        
+        .. versionchanged:: 5.2
+            Users blocked via `blocked_users` that may have logged in in the past
+            have all permissions and group membership revoked
+            and all servers stopped at JupyterHub startup.
+            Previously, User permissions (e.g. API tokens)
+            and servers were unaffected and required additional
+            administrator operations to block after a user is added to `blocked_users`.
 
         .. versionchanged:: 1.2
             `Authenticator.blacklist` renamed to `blocked_users`
@@ -1210,7 +1225,7 @@ class LocalAuthenticator(Authenticator):
         cmd = [arg.replace('USERNAME', name) for arg in self.add_user_cmd]
         try:
             uid = self.uids[name]
-            cmd += ['--uid', '%d' % uid]
+            cmd += ['--uid', str(uid)]
         except KeyError:
             self.log.debug(f"No UID for user {name}")
         cmd += [name]
@@ -1230,7 +1245,20 @@ class PAMAuthenticator(LocalAuthenticator):
 
     @default('executor')
     def _default_executor(self):
-        return ThreadPoolExecutor(1)
+        return ThreadPoolExecutor(self.executor_threads)
+
+    executor_threads = Integer(
+        4,
+        config=True,
+        help="""
+        Number of executor threads.
+
+        PAM auth requests happen in this thread, so it is mostly
+        waiting for the pam stack. One thread is usually enough,
+        unless your pam stack is doing something slow like network
+        requests
+        """,
+    )
 
     encoding = Unicode(
         'utf8',
@@ -1476,12 +1504,19 @@ class DummyAuthenticator(Authenticator):
     password = Unicode(
         config=True,
         help="""
-        Set a global password for all users wanting to log in.
-
-        This allows users with any username to log in with the same static password.
+        .. deprecated:: 5.3
+        
+            Setting a password in DummyAuthenticator is deprecated.
+            Use `SharedPasswordAuthenticator` instead.
         """,
     )
 
+    @observe("password")
+    def _password_changed(self, change):
+        msg = "DummyAuthenticator.password is deprecated in JupyterHub 5.3. Use SharedPasswordAuthenticator.user_password instead."
+        warnings.warn(msg, DeprecationWarning)
+        self.log.warning(msg)
+
     def check_allow_config(self):
         super().check_allow_config()
         self.log.warning(
@@ -1492,7 +1527,7 @@ class DummyAuthenticator(Authenticator):
         """Checks against a global password if it's been set. If not, allow any user/pass combo"""
         if self.password:
             if data['password'] == self.password:
-                return data['username']
+                return data["username"]
             return None
         return data['username']
 

jupyterhub/authenticators/shared.py

@@ -0,0 +1,149 @@
+from secrets import compare_digest
+
+from traitlets import Unicode, validate
+
+from ..auth import Authenticator
+
+
+class SharedPasswordAuthenticator(Authenticator):
+    """
+    Authenticator with static shared passwords.
+
+    For use in short-term deployments with negligible security concerns.
+
+    Enable with::
+
+        c.JupyterHub.authenticator_class = "shared-password"
+
+    .. warning::
+        This is an insecure Authenticator only appropriate for short-term
+        deployments with no requirement to protect users from each other.
+
+        - The password is stored in plain text at rest in config
+        - Anyone with the password can login as **any user**
+        - All users are able to login as all other (non-admin) users with the same password
+    """
+
+    _USER_PASSWORD_MIN_LENGTH = 8
+    _ADMIN_PASSWORD_MIN_LENGTH = 32
+
+    user_password = Unicode(
+        None,
+        allow_none=True,
+        config=True,
+        help=f"""
+        Set a global password for all *non admin* users wanting to log in.
+
+        Must be {_USER_PASSWORD_MIN_LENGTH} characters or longer.
+
+        If not set, regular users cannot login.
+
+        If `allow_all` is True, anybody can register unlimited new users with any username by logging in with this password.
+        Users may be allowed by name by specifying `allowed_users`.
+
+        Any user will also be able to login as **any other non-admin user** with this password.
+
+        If `admin_users` is set, those users *must* use `admin_password` to log in.
+        """,
+    )
+
+    admin_password = Unicode(
+        None,
+        allow_none=True,
+        config=True,
+        help=f"""
+        Set a global password that grants *admin* privileges to users logging in with this password.
+        Only usernames declared in `admin_users` may login with this password.
+
+        Must meet the following requirements:
+
+        - Be {_ADMIN_PASSWORD_MIN_LENGTH} characters or longer
+        - Not be the same as `user_password`
+
+        If not set, admin users cannot login.
+        """,
+    )
+
+    @validate("admin_password")
+    def _validate_admin_password(self, proposal):
+        new = proposal.value
+        trait_name = f"{self.__class__.__name__}.{proposal.trait.name}"
+
+        if not new:
+            # no admin password; do nothing
+            return None
+        if len(new) < self._ADMIN_PASSWORD_MIN_LENGTH:
+            raise ValueError(
+                f"{trait_name} must be at least {self._ADMIN_PASSWORD_MIN_LENGTH} characters, not {len(new)}."
+            )
+        if self.user_password == new:
+            # Checked here and in validating password, to ensure we don't miss issues due to ordering
+            raise ValueError(
+                f"{self.__class__.__name__}.user_password and {trait_name} cannot be the same"
+            )
+        return new
+
+    @validate("user_password")
+    def _validate_password(self, proposal):
+        new = proposal.value
+        trait_name = f"{self.__class__.__name__}.{proposal.trait.name}"
+
+        if not new:
+            # no user password; do nothing
+            return None
+        if len(new) < self._USER_PASSWORD_MIN_LENGTH:
+            raise ValueError(
+                f"{trait_name} must be at least {self._USER_PASSWORD_MIN_LENGTH} characters long, got {len(new)} characters"
+            )
+        if self.admin_password == new:
+            # Checked here and in validating password, to ensure we don't miss issues due to ordering
+            raise ValueError(
+                f"{trait_name} and {self.__class__.__name__}.admin_password cannot be the same"
+            )
+        return new
+
+    def check_allow_config(self):
+        """Validate and warn about any suspicious allow config"""
+        super().check_allow_config()
+        clsname = self.__class__.__name__
+        if self.admin_password and not self.admin_users:
+            self.log.warning(
+                f"{clsname}.admin_password set, but {clsname}.admin_users is not."
+                " No admin users will be able to login."
+                f" Add usernames to {clsname}.admin_users to grant users admin permissions."
+            )
+        if self.admin_users and not self.admin_password:
+            self.log.warning(
+                f"{clsname}.admin_users set, but {clsname}.admin_password is not."
+                " No admin users will be able to login."
+                f" Set {clsname}.admin_password to allow admins to login."
+            )
+        if not self.user_password:
+            if not self.admin_password:
+                # log as an error, but don't raise, because disabling all login is valid
+                self.log.error(
+                    f"Neither {clsname}.admin_password nor {clsname}.user_password is set."
+                    " Nobody will be able to login!"
+                )
+            else:
+                self.log.warning(
+                    f"{clsname}.user_password not set."
+                    " No non-admin users will be able to login."
+                )
+
+    async def authenticate(self, handler, data):
+        """Checks against shared password"""
+        if data["username"] in self.admin_users:
+            # Admin user
+            if self.admin_password and compare_digest(
+                data["password"], self.admin_password
+            ):
+                return {"name": data["username"], "admin": True}
+        else:
+            if self.user_password and compare_digest(
+                data["password"], self.user_password
+            ):
+                # Anyone logging in with the standard password is *never* admin
+                return {"name": data["username"], "admin": False}
+
+        return None

jupyterhub/handlers/base.py

@@ -1061,10 +1061,12 @@ class BaseHandler(RequestHandler):
             # round suggestion to nicer human value (nearest 10 seconds or minute)
             if retry_time <= 90:
                 # round human seconds up to nearest 10
-                human_retry_time = "%i0 seconds" % math.ceil(retry_time / 10.0)
+                delay = math.ceil(retry_time / 10.0)
+                human_retry_time = f"{delay}0 seconds"
             else:
                 # round number of minutes
-                human_retry_time = "%i minutes" % math.round(retry_time / 60.0)
+                delay = round(retry_time / 60.0)
+                human_retry_time = f"{delay} minutes"
 
             self.log.warning(
                 '%s pending spawns, throttling. Suggested retry in %s seconds.',
@@ -1099,12 +1101,12 @@ class BaseHandler(RequestHandler):
         self.log.debug(
             "%i%s concurrent spawns",
             spawn_pending_count,
-            '/%i' % concurrent_spawn_limit if concurrent_spawn_limit else '',
+            f'/{concurrent_spawn_limit}' if concurrent_spawn_limit else '',
         )
         self.log.debug(
             "%i%s active servers",
             active_count,
-            '/%i' % active_server_limit if active_server_limit else '',
+            f'/{active_server_limit}' if active_server_limit else '',
         )
 
         spawner = user.spawners[server_name]
@@ -1246,6 +1248,20 @@ class BaseHandler(RequestHandler):
                     status=ServerSpawnStatus.failure
                 ).observe(time.perf_counter() - spawn_start_time)
 
+                # if it stopped, give the original spawn future a second chance to raise
+                # this avoids storing the generic 500 error as the spawn failure,
+                # when the original may be more informative
+                try:
+                    await asyncio.wait_for(
+                        asyncio.shield(finish_spawn_future), timeout=1
+                    )
+                except TimeoutError:
+                    pass
+
+                if finish_spawn_future.exception():
+                    # raise original exception if it already failed
+                    await finish_spawn_future
+
                 raise web.HTTPError(
                     500,
                     f"Spawner failed to start [status={status}]. The logs for {spawner._log_name} may contain details.",
@@ -1471,6 +1487,7 @@ class BaseHandler(RequestHandler):
         """render custom error pages"""
         exc_info = kwargs.get('exc_info')
         message = ''
+        message_html = ''
         exception = None
         status_message = responses.get(status_code, 'Unknown HTTP Error')
         if exc_info:
@@ -1480,12 +1497,17 @@ class BaseHandler(RequestHandler):
                 message = exception.log_message % exception.args
             except Exception:
                 pass
+            # allow custom html messages
+            message_html = getattr(exception, "jupyterhub_html_message", "")
 
             # construct the custom reason, if defined
             reason = getattr(exception, 'reason', '')
             if reason:
                 message = reasons.get(reason, reason)
 
+            # get special jupyterhub_message, if defined
+            message = getattr(exception, "jupyterhub_message", message)
+
         if exception and isinstance(exception, SQLAlchemyError):
             self.log.warning("Rolling back session due to database error %s", exception)
             self.db.rollback()
@@ -1495,6 +1517,7 @@ class BaseHandler(RequestHandler):
             status_code=status_code,
             status_message=status_message,
             message=message,
+            message_html=message_html,
             extra_error_html=getattr(self, 'extra_error_html', ''),
             exception=exception,
         )

jupyterhub/handlers/login.py

@@ -9,6 +9,7 @@ from tornado import web
 from tornado.escape import url_escape
 from tornado.httputil import url_concat
 
+from .._xsrf_utils import _set_xsrf_cookie
 from ..utils import maybe_future
 from .base import BaseHandler
 
@@ -94,7 +95,37 @@ class LogoutHandler(BaseHandler):
 class LoginHandler(BaseHandler):
     """Render the login page."""
 
-    def _render(self, login_error=None, username=None):
+    def render_template(self, name, **ns):
+        # intercept error page rendering for form submissions
+        if (
+            name == "error.html"
+            and self.request.method.lower() == "post"
+            and self.request.headers.get("Sec-Fetch-Mode", "navigate") == "navigate"
+        ):
+            # regular login form submission
+            # render login form with error message
+            ns["login_error"] = ns.get("message") or ns.get("status_message", "")
+            ns["username"] = self.get_argument("username", strip=True, default="")
+            return self._render(**ns)
+        else:
+            return super().render_template(name, **ns)
+
+    def check_xsrf_cookie(self):
+        try:
+            return super().check_xsrf_cookie()
+        except web.HTTPError as e:
+            # rewrite xsrf error on login form for nicer message
+            # suggest retry, which is likely to succeed
+            # log the original error so admins can debug
+            self.log.error("XSRF error on login form: %s", e)
+            if self.request.headers.get("Sec-Fetch-Mode", "navigate") == "navigate":
+                raise web.HTTPError(
+                    e.status_code, "Login form invalid or expired. Try again."
+                )
+            else:
+                raise
+
+    def _render(self, login_error=None, username=None, **kwargs):
         context = {
             "next": url_escape(self.get_argument('next', default='')),
             "username": username,
@@ -116,6 +147,7 @@ class LoginHandler(BaseHandler):
             'login.html',
             **context,
             custom_html=custom_html,
+            **kwargs,
         )
 
     async def get(self):
@@ -147,6 +179,18 @@ class LoginHandler(BaseHandler):
                     self.redirect(auto_login_url)
                 return
             username = self.get_argument('username', default='')
+
+            # always set a fresh xsrf cookie when the login page is rendered
+            # ensures we are as far from expiration as possible
+            # to restart the timer
+            xsrf_token = self.xsrf_token
+            if self.request.headers.get("Sec-Fetch-Mode", "navigate") == "navigate":
+                _set_xsrf_cookie(
+                    self,
+                    self._xsrf_token_id,
+                    cookie_path=self.hub.base_url,
+                    xsrf_token=xsrf_token,
+                )
             self.finish(await self._render(username=username))
 
     async def post(self):
@@ -169,6 +213,7 @@ class LoginHandler(BaseHandler):
             self._jupyterhub_user = user
             self.redirect(self.get_next_url(user))
         else:
+            self.set_status(403)
             html = await self._render(
                 login_error='Invalid username or password', username=data['username']
             )

jupyterhub/handlers/pages.py

@@ -375,7 +375,10 @@ class SpawnPendingHandler(BaseHandler):
             spawn_url = url_path_join(
                 self.hub.base_url, "spawn", user.escaped_name, escaped_server_name
             )
-            self.set_status(500)
+            status_code = 500
+            if isinstance(exc, web.HTTPError):
+                status_code = exc.status_code
+            self.set_status(status_code)
             html = await self.render_template(
                 "not_running.html",
                 user=user,
@@ -466,7 +469,6 @@ class AdminHandler(BaseHandler):
             named_server_limit_per_user=await self.get_current_user_named_server_limit(),
             server_version=f'{__version__} {self.version_hash}',
             api_page_limit=self.settings["api_page_default_limit"],
-            base_url=self.settings["base_url"],
         )
         self.finish(html)
 

jupyterhub/metrics.py

@@ -38,6 +38,57 @@ from .utils import utcnow
 
 metrics_prefix = os.getenv('JUPYTERHUB_METRICS_PREFIX', 'jupyterhub')
 
+_env_spawn_duration_buckets = os.environ.get(
+    'JUPYTERHUB_SERVER_SPAWN_DURATION_SECONDS_BUCKETS', ""
+).strip()
+_env_stop_duration_buckets = os.environ.get(
+    "JUPYTERHUB_SERVER_STOP_DURATION_SECONDS_BUCKETS", ""
+).strip()
+
+if _env_spawn_duration_buckets:
+    spawn_duration_buckets = [
+        float(_s) for _s in _env_spawn_duration_buckets.split(",")
+    ]
+else:
+    spawn_duration_buckets = [
+        0.5,
+        1,
+        2.5,
+        5,
+        10,
+        15,
+        30,
+        60,
+        120,
+        180,
+        300,
+        600,
+        float("inf"),
+    ]
+
+if _env_stop_duration_buckets:
+    stop_duration_buckets = [float(_s) for _s in _env_stop_duration_buckets.split(",")]
+else:
+    # We default to the same buckets as upstream Prometheus (as it was before) so we don't
+    # break anything that was consuming this metric before bucket configuration was possible
+    stop_duration_buckets = [
+        0.005,
+        0.01,
+        0.025,
+        0.05,
+        0.075,
+        0.1,
+        0.25,
+        0.5,
+        0.75,
+        1,
+        2.5,
+        5,
+        7.5,
+        10,
+        float("inf"),
+    ]
+
 REQUEST_DURATION_SECONDS = Histogram(
     'request_duration_seconds',
     'Request duration for all HTTP requests',
@@ -51,7 +102,7 @@ SERVER_SPAWN_DURATION_SECONDS = Histogram(
     ['status'],
     # Use custom bucket sizes, since the default bucket ranges
     # are meant for quick running processes. Spawns can take a while!
-    buckets=[0.5, 1, 2.5, 5, 10, 15, 30, 60, 120, 180, 300, 600, float("inf")],
+    buckets=spawn_duration_buckets,
     namespace=metrics_prefix,
 )
 
@@ -175,6 +226,7 @@ SERVER_STOP_DURATION_SECONDS = Histogram(
     'server_stop_seconds',
     'Time taken for server stopping operation',
     ['status'],
+    buckets=stop_duration_buckets,
     namespace=metrics_prefix,
 )
 
@@ -319,7 +371,7 @@ class PeriodicMetricsCollector(LoggingConfigurable):
         config=True,
         help="""
         Enable event_loop_interval_seconds metric.
-        
+
         Measures event-loop responsiveness.
         """,
     )
@@ -328,7 +380,7 @@ class PeriodicMetricsCollector(LoggingConfigurable):
         config=True,
         help="""
         Interval (in seconds) on which to measure the event loop interval.
-        
+
         This is the _sensitivity_ of the `event_loop_interval` metric.
         Setting it too low (e.g. below 20ms) can end up slowing down the whole event loop
         by measuring too often,

jupyterhub/objects.py

@@ -12,6 +12,7 @@ from . import orm
 from .traitlets import URLPrefix
 from .utils import (
     can_connect,
+    fmt_ip_url,
     make_ssl_context,
     random_port,
     url_path_join,
@@ -50,7 +51,7 @@ class Server(HasTraits):
         since it can be non-connectable value, such as '', meaning all interfaces.
         """
         if self.ip in {'', '0.0.0.0', '::'}:
-            return self.url.replace(self._connect_ip, self.ip or '*', 1)
+            return self.url.replace(self._connect_ip, fmt_ip_url(self.ip) or '*', 1)
         return self.url
 
     @observe('bind_url')
@@ -216,4 +217,4 @@ class Hub(Server):
         return url_path_join(self.url, 'api')
 
     def __repr__(self):
-        return f"<{self.__class__.__name__} {self.ip}:{self.port}>"
+        return f"<{self.__class__.__name__} {fmt_ip_url(self.ip)}:{self.port}>"

jupyterhub/orm.py

@@ -46,7 +46,7 @@ from sqlalchemy.pool import StaticPool
 from sqlalchemy.types import LargeBinary, Text, TypeDecorator
 from tornado.log import app_log
 
-from .utils import compare_token, hash_token, new_token, random_port, utcnow
+from .utils import compare_token, fmt_ip_url, hash_token, new_token, random_port, utcnow
 
 # top-level variable for easier mocking in tests
 utcnow = partial(utcnow, with_tz=False)
@@ -157,7 +157,7 @@ class Server(Base):
     spawner = relationship("Spawner", back_populates="server", uselist=False)
 
     def __repr__(self):
-        return f"<Server({self.ip}:{self.port})>"
+        return f"<Server({fmt_ip_url(self.ip)}:{self.port})>"
 
 
 # lots of things have roles
@@ -945,7 +945,7 @@ class ShareCode(_Share, Hashed, Base):
         else:
             server_name = "unknown/deleted"
 
-        return f"<{self.__class__.__name__}(server={server_name}, scopes={self.scopes}, expires_at={self.expires_at})>"
+        return f"<{self.__class__.__name__}(id={self.id}, server={server_name}, scopes={self.scopes}, expires_at={self.expires_at})>"
 
     @classmethod
     def new(
@@ -1050,7 +1050,7 @@ class APIToken(Hashed, Base):
 
     @property
     def api_id(self):
-        return 'a%i' % self.id
+        return f"a{self.id}"
 
     @property
     def owner(self):
@@ -1141,7 +1141,6 @@ class APIToken(Hashed, Base):
         expires_in=None,
         client_id=None,
         oauth_client=None,
-        return_orm=False,
     ):
         """Generate a new API token for a user or service"""
         assert user or service

jupyterhub/scopes.py

@@ -31,8 +31,11 @@ from tornado.log import app_log
 from . import orm, roles
 from ._memoize import DoNotCache, FrozenDict, lru_cache_key
 
-"""when modifying the scope definitions, make sure that `docs/source/rbac/generate-scope-table.py` is run
-   so that changes are reflected in the documentation and REST API description."""
+"""when modifying the scope definitions
+   `docs/source/rbac/generate-scope-table.py` must be run
+   so that changes are reflected in the documentation and REST API description.
+   `pre-commit run -a` should automatically take care of this.
+   """
 scope_definitions = {
     '(no_scope)': {'description': 'Identify the owner of the requesting entity.'},
     'self': {
@@ -64,7 +67,7 @@ scope_definitions = {
         'subscopes': ['read:users:name'],
     },
     'read:users': {
-        'description': 'Read user models (including servers, tokens and authentication state).',
+        'description': 'Read user models (including the URL of the default server if it is running).',
         'subscopes': [
             'read:users:name',
             'read:users:groups',

jupyterhub/services/service.py

@@ -436,7 +436,10 @@ class Service(LoggingConfigurable):
             # since they are always local subprocesses
             hub = copy.deepcopy(self.hub)
             hub.connect_url = ''
-            hub.connect_ip = '127.0.0.1'
+            if self.hub.ip and ":" in self.hub.ip:
+                hub.connect_ip = "::1"
+            else:
+                hub.connect_ip = "127.0.0.1"
 
         self.spawner = _ServiceSpawner(
             cmd=self.command,

jupyterhub/singleuser/__init__.py

@@ -63,9 +63,29 @@ if _as_extension:
             f"Cannot use JUPYTERHUB_SINGLEUSER_EXTENSION={_extension_env} with JUPYTERHUB_SINGLEUSER_APP={_app_env}."
             " Please pick one or the other."
         )
-    from .extension import main
+    try:
+        from .extension import main
+    except ImportError as e:
+        # raise from to preserve original import error
+        raise ImportError(
+            "Failed to import JupyterHub singleuser extension."
+            " Make sure to install dependencies for your single-user server, e.g.\n"
+            "    pip install jupyterlab"
+        ) from e
 else:
-    from .app import SingleUserNotebookApp, main
+    try:
+        from .app import SingleUserNotebookApp, main
+    except ImportError as e:
+        # raise from to preserve original import error
+        if _app_env:
+            _app_env_log = f"JUPYTERHUB_SINGLEUSER_APP={_app_env}"
+        else:
+            _app_env_log = "default single-user server"
+        raise ImportError(
+            f"Failed to import {_app_env_log}."
+            " Make sure to install dependencies for your single-user server, e.g.\n"
+            "    pip install jupyterlab"
+        ) from e
 
     # backward-compatibility
     if SingleUserNotebookApp is not None:

jupyterhub/singleuser/_disable_user_config.py

@@ -22,8 +22,6 @@ rather than keeing these monkey patches around.
 import os
 from pathlib import Path
 
-from jupyter_core import paths
-
 
 def _is_relative_to(path, prefix):
     """
@@ -68,6 +66,10 @@ def _disable_user_config(serverapp):
     2. Search paths for extensions, etc.
     3. import path
     """
+    # delayed import to avoid triggering early ImportError
+    # with unmet dependencies
+    from jupyter_core import paths
+
     original_jupyter_path = paths.jupyter_path()
     jupyter_path_without_home = list(_exclude_home(original_jupyter_path))
 

jupyterhub/singleuser/extension.py

@@ -518,7 +518,8 @@ class JupyterHubSingleUser(ExtensionApp):
         if url.hostname:
             cfg.ip = url.hostname
         else:
-            cfg.ip = "127.0.0.1"
+            # All interfaces (ipv4+ipv6)
+            cfg.ip = ""
 
         cfg.base_url = os.environ.get('JUPYTERHUB_SERVICE_PREFIX') or '/'
 

jupyterhub/singleuser/mixins.py

@@ -288,6 +288,8 @@ class SingleUserNotebookAppMixin(Configurable):
             url = urlparse(os.environ['JUPYTERHUB_SERVICE_URL'])
             if url.hostname:
                 return url.hostname
+            # All interfaces (ipv4+ipv6)
+            return ""
         return '127.0.0.1'
 
     # disable some single-user configurables
@@ -361,9 +363,8 @@ class SingleUserNotebookAppMixin(Configurable):
         """override default log format to include time"""
         return "%(color)s[%(levelname)1.1s %(asctime)s.%(msecs).03d %(name)s %(module)s:%(lineno)d]%(end_color)s %(message)s"
 
-    def _confirm_exit(self):
-        # disable the exit confirmation for background notebook processes
-        self.io_loop.add_callback_from_signal(self.io_loop.stop)
+    def _handle_sigint(self, *args, **kwargs):
+        self._signal_stop(*args, **kwargs)
 
     def migrate_config(self):
         if self.disable_user_config:

jupyterhub/spawner.py

@@ -12,7 +12,7 @@ import shutil
 import signal
 import sys
 import warnings
-from inspect import signature
+from inspect import isawaitable, signature
 from subprocess import Popen
 from tempfile import mkdtemp
 from textwrap import dedent
@@ -24,6 +24,7 @@ else:
     from async_generator import aclosing
 
 from sqlalchemy import inspect
+from tornado import web
 from tornado.ioloop import PeriodicCallback
 from traitlets import (
     Any,
@@ -48,6 +49,7 @@ from .traitlets import ByteSpecification, Callable, Command
 from .utils import (
     AnyTimeoutError,
     exponential_backoff,
+    fmt_ip_url,
     maybe_future,
     random_port,
     recursive_update,
@@ -365,14 +367,6 @@ class Spawner(LoggingConfigurable):
         help="""Allowed roles for oauth tokens.
 
         Deprecated in 3.0: use oauth_client_allowed_scopes
-
-        This sets the maximum and default roles
-        assigned to oauth tokens issued by a single-user server's
-        oauth client (i.e. tokens stored in browsers after authenticating with the server),
-        defining what actions the server can take on behalf of logged-in users.
-
-        Default is an empty list, meaning minimal permissions to identify users,
-        no actions can be taken on their behalf.
         """,
     ).tag(config=True)
 
@@ -385,6 +379,8 @@ class Spawner(LoggingConfigurable):
         oauth client (i.e. tokens stored in browsers after authenticating with the server),
         defining what actions the server can take on behalf of logged-in users.
 
+        Access to the current server will always be included in this list.
+        This property contains additional scopes.
         Default is an empty list, meaning minimal permissions to identify users,
         no actions can be taken on their behalf.
 
@@ -412,7 +408,7 @@ class Spawner(LoggingConfigurable):
             allowed_scopes = self.oauth_client_allowed_scopes
             if callable(allowed_scopes):
                 allowed_scopes = allowed_scopes(self)
-                if inspect.isawaitable(allowed_scopes):
+                if isawaitable(allowed_scopes):
                     allowed_scopes = await allowed_scopes
             scopes.extend(allowed_scopes)
 
@@ -475,20 +471,40 @@ class Spawner(LoggingConfigurable):
         The IP address (or hostname) the single-user server should listen on.
 
         Usually either '127.0.0.1' (default) or '0.0.0.0'.
+        On IPv6 only networks use '::1' or '::'.
+
+        If the spawned singleuser server is running JupyterHub 5.3.0 later
+        You can set this to the empty string '' to indicate both IPv4 and IPv6.
 
         The JupyterHub proxy implementation should be able to send packets to this interface.
 
         Subclasses which launch remotely or in containers
         should override the default to '0.0.0.0'.
 
+        .. versionchanged:: 5.3
+            An empty string '' means all interfaces (IPv4 and IPv6). Prior to this
+            the behaviour of '' was not defined.
+
         .. versionchanged:: 2.0
-            Default changed to '127.0.0.1', from ''.
-            In most cases, this does not result in a change in behavior,
-            as '' was interpreted as 'unspecified',
-            which used the subprocesses' own default, itself usually '127.0.0.1'.
+            Default changed to '127.0.0.1', from unspecified.
         """,
     ).tag(config=True)
 
+    @validate("ip")
+    def _strip_ipv6(self, proposal):
+        """
+        Prior to 5.3.0 it was necessary to use [] when specifying an
+        [ipv6] due to the IP being concatenated with the port when forming URLs
+        without [].
+
+        To avoid breaking existing workarounds strip [].
+        """
+        v = proposal["value"]
+        if v.startswith("[") and v.endswith("]"):
+            self.log.warning("Removing '[' ']' from Spawner.ip %s", self.ip)
+            v = v[1:-1]
+        return v
+
     port = Integer(
         0,
         help="""
@@ -617,7 +633,8 @@ class Spawner(LoggingConfigurable):
 
         return options_form
 
-    options_from_form = Callable(
+    options_from_form = Union(
+        [Callable(), Unicode()],
         help="""
         Interpret HTTP form data
 
@@ -629,7 +646,8 @@ class Spawner(LoggingConfigurable):
         though it can contain bytes in addition to standard JSON data types.
 
         This method should not have any side effects.
-        Any handling of `user_options` should be done in `.start()`
+        Any handling of `user_options` should be done in `.apply_user_options()` (JupyterHub 5.3)
+        or `.start()` (JupyterHub 5.2 or older)
         to ensure consistent behavior across servers
         spawned via the API and form submission page.
 
@@ -643,16 +661,88 @@ class Spawner(LoggingConfigurable):
             (with additional support for bytes in case of uploaded file data),
             and any non-bytes non-jsonable values will be replaced with None
             if the user_options are re-used.
+
+        .. versionadded:: 5.3
+            The strings `'simple'` and `'passthrough'` may be specified to select some predefined behavior.
+            These are the only string values accepted.
+            
+            `'passthrough'` is the longstanding default behavior,
+            where form data is stored in `user_options` without modification.
+            With `'passthrough'`, `user_options` from a form will always be a dict of lists of strings.
+
+            `'simple'` applies some minimal processing that works for most simple forms:
+
+            - Single-value fields get unpacked from lists.
+              They are still always strings, no attempt is made to parse numbers, etc..
+            - Multi-value fields are left alone.
+            - The default checked value of "on" for a checkbox is converted to True.
+              This is the only non-string value that can be produced.
+
+            Example for `'simple'`::
+
+                {
+                    "image": ["myimage"],
+                    "checked": ["on"], # checkbox
+                    "multi-select": ["a", "b"],
+                }
+                # becomes
+                {
+                    "image": "myimage",
+                    "checked": True,
+                    "multi-select": ["a", "b"],
+                }
         """,
     ).tag(config=True)
 
     @default("options_from_form")
     def _options_from_form(self):
-        return self._default_options_from_form
+        return self._passthrough_options_from_form
 
-    def _default_options_from_form(self, form_data):
+    @validate("options_from_form")
+    def _validate_options_from_form(self, proposal):
+        # coerce special string values to callable
+        if proposal.value == "passthrough":
+            return self._passthrough_options_from_form
+        elif proposal.value == "simple":
+            return self._simple_options_from_form
+        else:
+            return proposal.value
+
+    @staticmethod
+    def _passthrough_options_from_form(form_data):
+        """The longstanding default behavior for options_from_form
+
+        explicit opt-in via `options_from_form = 'passthrough'`
+        """
         return form_data
 
+    @staticmethod
+    def _simple_options_from_form(form_data):
+        """Simple options_from_form
+
+        Enable via `options_from_form = 'simple'
+
+        Transforms simple single-value string inputs to actual strings,
+        when they arrive as length-1 lists.
+
+        The default "checked" value of "on" for checkboxes is converted to True.
+        Note: when a checkbox is unchecked in a form, its value is generally omitted, not set to any false value.
+
+        Multi-value inputs are left unmodifed as lists of strings.
+        """
+        user_options = {}
+        for key, value_list in form_data.items():
+            if len(value_list) == 1:
+                value = value_list[0]
+                if value == "on":
+                    # default for checkbox
+                    value = True
+            else:
+                value = value_list
+
+            user_options[key] = value
+        return user_options
+
     def run_options_from_form(self, form_data):
         sig = signature(self.options_from_form)
         if 'spawner' in sig.parameters:
@@ -691,26 +781,145 @@ class Spawner(LoggingConfigurable):
         """
         return self.options_from_form(query_data)
 
+    apply_user_options = Union(
+        [Callable(), Dict()],
+        config=True,
+        default_value=None,
+        allow_none=True,
+        help="""
+            Hook to apply inputs from user_options to the Spawner.
+
+            Typically takes values in user_options, validates them, and updates Spawner attributes::
+
+                def apply_user_options(spawner, user_options):
+                    if "image" in user_options and isinstance(user_options["image"], str):
+                        spawner.image = user_options["image"]
+
+                c.Spawner.apply_user_options = apply_user_options
+
+            `apply_user_options` *may* be async.
+
+            Default: do nothing.
+
+            Typically a callable which takes `(spawner: Spawner, user_options: dict)`,
+            but for simple cases this can be a dict mapping user option fields to Spawner attribute names,
+            e.g.::
+
+                c.Spawner.apply_user_options = {"image_input": "image"}
+                c.Spawner.options_from_form = "simple"
+
+            allows users to specify the image attribute, but not any others.
+            Because `user_options` generally comes in as strings in form data,
+            the dictionary mode uses traitlets `from_string` to coerce strings to values,
+            which allows setting simple values from strings (e.g. numbers)
+            without needing to implement callable hooks.
+
+            .. note::
+
+                Because `user_options` is user input
+                and may be set directly via the REST API,
+                no assumptions should be made on its structure or contents.
+                An empty dict should always be supported.
+                Make sure to validate any inputs before applying them,
+                either in this callable, or in whatever is consuming the value
+                if this is a dict.
+        
+            .. versionadded:: 5.3
+        
+                Prior to 5.3, applying user options must be done in `Spawner.start()`
+                or `Spawner.pre_spawn_hook()`.
+            """,
+    )
+
+    async def _run_apply_user_options(self, user_options):
+        """Run the apply_user_options hook
+
+        and turn errors into HTTP 400
+        """
+        r = None
+        try:
+            if isinstance(self.apply_user_options, dict):
+                r = self._apply_user_options_dict(user_options)
+            elif self.apply_user_options:
+                r = self.apply_user_options(self, user_options)
+            elif user_options:
+                keys = list(user_options)
+                self.log.warning(
+                    f"Received unhandled user_options for {self._log_name}: {', '.join(keys)}"
+                )
+            if isawaitable(r):
+                await r
+        except Exception as e:
+            # this may not be the users' fault...
+            # should we catch less?
+            # likely user errors are ValueError, TraitError, TypeError
+            self.log.exception("Exception applying user_options for %s", self._log_name)
+            if isinstance(e, web.HTTPError):
+                # passthrough hook's HTTPError, so it can display a custom message
+                raise
+            else:
+                raise web.HTTPError(400, "Invalid user options")
+
+    def _apply_user_options_dict(self, user_options):
+        """if apply_user_options is a dict
+
+        Allows fully declarative apply_user_options configuration
+        for simple cases where users may set attributes directly
+        from values in user_options.
+        """
+        traits = self.traits()
+        for key, value in user_options.items():
+            attr = self.apply_user_options.get(key, None)
+            if attr is None:
+                self.log.warning(f"Unhandled user option {key} for {self._log_name}")
+            elif hasattr(self, attr):
+                # require traits? I think not, but we should require declaration, at least
+                # use trait from_string for string coercion if available, though
+                try:
+                    setattr(self, attr, value)
+                except Exception as e:
+                    # try coercion from string via traits
+                    # this will mostly affect numbers
+                    if attr in traits and isinstance(value, str):
+                        # try coercion, may not work
+                        try:
+                            value = traits[attr].from_string(value)
+                        except Exception:
+                            # raise original assignment error, likely more informative
+                            raise e
+                        else:
+                            setattr(self, attr, value)
+                    else:
+                        raise
+            else:
+                self.log.error(
+                    f"No such Spawner attribute {attr} for user option {key} on {self._log_name}"
+                )
+
     user_options = Dict(
         help="""
         Dict of user specified options for the user's spawned instance of a single-user server.
 
         These user options are usually provided by the `options_form` displayed to the user when they start
         their server.
+        If specified via an `options_form`, form data is passed through `options_from_form` before storing
+        in `user_options`.
+        `user_options` may also be passed as the JSON body to a spawn request via the REST API,
+        in which case it is stored directly, unmodifed.
+        
+        `user_options` has no effect on its own, it must be handled by the Spawner in `spawner.start`,
+        or via deployment configuration in `apply_user_options` or `pre_spawn_hook`.
+        
+        .. seealso::
+        
+            - :attr:`options_form`
+            - :attr:`options_from_form`
+            - :attr:`apply_user_options`
         """
     )
 
     env_keep = List(
-        [
-            'PATH',
-            'PYTHONPATH',
-            'CONDA_ROOT',
-            'CONDA_DEFAULT_ENV',
-            'VIRTUAL_ENV',
-            'LANG',
-            'LC_ALL',
-            'JUPYTERHUB_SINGLEUSER_APP',
-        ],
+        ['JUPYTERHUB_SINGLEUSER_APP'],
         help="""
         List of environment variables for the single-user server to inherit from the JupyterHub process.
 
@@ -1108,7 +1317,7 @@ class Spawner(LoggingConfigurable):
             base_url = '/'
 
         proto = 'https' if self.internal_ssl else 'http'
-        bind_url = f"{proto}://{self.ip}:{self.port}{base_url}"
+        bind_url = f"{proto}://{fmt_ip_url(self.ip)}:{self.port}{base_url}"
         env["JUPYTERHUB_SERVICE_URL"] = bind_url
 
         # the public URLs of this server and the Hub
@@ -1716,6 +1925,20 @@ class LocalProcessSpawner(Spawner):
         """,
     )
 
+    @default("env_keep")
+    def _env_keep_default(self):
+        return [
+            "CONDA_DEFAULT_ENV",
+            "CONDA_ROOT",
+            "JUPYTERHUB_SINGLEUSER_APP",
+            "LANG",
+            "LC_ALL",
+            "LD_LIBRARY_PATH",
+            "PATH",
+            "PYTHONPATH",
+            "VIRTUAL_ENV",
+        ]
+
     def make_preexec_fn(self, name):
         """
         Return a function that can be used to set the user id of the spawned process to user with name `name`

jupyterhub/tests/browser/test_browser.py

@@ -283,7 +283,7 @@ async def test_spawn_pending_progress(
         await launch_btn.click()
     # wait for progress message to appear
     progress = browser.locator("#progress-message")
-    progress_message = await progress.inner_text()
+    progress_message = await progress.text_content()
     async with browser.expect_navigation(url=re.compile(".*/user/" + f"{urlname}/")):
         # wait for log messages to appear
         expected_messages = [
@@ -291,9 +291,10 @@ async def test_spawn_pending_progress(
             "Spawning server...",
             f"Server ready at {app.base_url}user/{urlname}/",
         ]
-        while not user.spawner.ready:
+        logs_list = []
+        while not user.spawner.ready and len(logs_list) < len(expected_messages):
             logs_list = [
-                await log.inner_text()
+                await log.text_content()
                 for log in await browser.locator("div.progress-log-event").all()
             ]
             if progress_message:
@@ -654,7 +655,7 @@ async def test_request_token_expiration(
         await api_token_table_area.locator("tr.token-row")
         .get_by_role("cell")
         .nth(0)
-        .inner_text()
+        .text_content()
     )
 
     assert note_on_page == expected_note
@@ -663,7 +664,7 @@ async def test_request_token_expiration(
         await api_token_table_area.locator("tr.token-row")
         .get_by_role("cell")
         .nth(2)
-        .inner_text()
+        .text_content()
     )
     assert last_used_text == "Never"
 
@@ -671,7 +672,7 @@ async def test_request_token_expiration(
         await api_token_table_area.locator("tr.token-row")
         .get_by_role("cell")
         .nth(4)
-        .inner_text()
+        .text_content()
     )
 
     if token_opt == "Never":
@@ -734,7 +735,7 @@ async def test_request_token_permissions(
     if not granted:
         error_dialog = browser.locator("#error-dialog")
         await expect(error_dialog).to_be_visible()
-        error_message = await error_dialog.locator(".modal-body").inner_text()
+        error_message = await error_dialog.locator(".modal-body").text_content()
         assert "API request failed (400)" in error_message
         assert expected_error in error_message
         await error_dialog.locator("button[aria-label='Close']").click()
@@ -1087,6 +1088,7 @@ async def open_admin_page(app, browser, login_as=None):
         # url = url_path_join(public_host(app), app.hub.base_url, "/login?next=" + admin_page)
         await browser.goto(admin_page)
         await expect(browser).to_have_url(re.compile(".*/hub/admin"))
+    await browser.wait_for_load_state("networkidle")
 
 
 def create_list_of_users(create_user_with_scopes, n):
@@ -1186,7 +1188,7 @@ async def test_paging_on_admin_page(
         re.compile(".*" + f"1-{min(users_count_db, 50)}" + ".*")
     )
     if users_count_db > 50:
-        await expect(btn_next.locator("//span")).to_have_class("active-pagination")
+        await expect(btn_next).to_be_enabled()
         # click on Next button
         await btn_next.click()
         if users_count_db <= 100:
@@ -1195,15 +1197,13 @@ async def test_paging_on_admin_page(
             )
         else:
             await expect(displaying).to_have_text(re.compile(".*" + "51-100" + ".*"))
-            await expect(btn_next.locator("//span")).to_have_class("active-pagination")
-        await expect(btn_previous.locator("//span")).to_have_class("active-pagination")
+            await expect(btn_next).to_be_enabled()
+        await expect(btn_previous).to_be_enabled()
         # click on Previous button
         await btn_previous.click()
     else:
-        await expect(btn_next.locator("//span")).to_have_class("inactive-pagination")
-        await expect(btn_previous.locator("//span")).to_have_class(
-            "inactive-pagination"
-        )
+        await expect(btn_next).to_be_disabled()
+        await expect(btn_previous).to_be_disabled()
 
 
 @pytest.mark.parametrize(
@@ -1234,18 +1234,16 @@ async def test_search_on_admin_page(
     await element_search.fill(search_value, force=True)
     await browser.wait_for_load_state("networkidle")
     # get the result of the search from db
-    users_count_db_filtered = (
+    total = (
         app.db.query(orm.User).filter(orm.User.name.like(f'%{search_value}%')).count()
     )
     # get the result of the search
     filtered_list_on_page = browser.locator('//tr[@class="user-row"]')
     displaying = browser.get_by_text("Displaying")
-    if users_count_db_filtered <= 50:
-        await expect(filtered_list_on_page).to_have_count(users_count_db_filtered)
-        start = 1 if users_count_db_filtered else 0
-        await expect(displaying).to_contain_text(
-            re.compile(f"{start}-{users_count_db_filtered}")
-        )
+    if total <= 50:
+        await expect(filtered_list_on_page).to_have_count(total)
+        start = 1 if total else 0
+        await expect(displaying).to_contain_text(f"{start}-{total}")
         # check that users names contain the search value in the filtered list
         for element in await filtered_list_on_page.get_by_test_id(
             "user-row-name"
@@ -1253,11 +1251,19 @@ async def test_search_on_admin_page(
             await expect(element).to_contain_text(re.compile(f".*{search_value}.*"))
     else:
         await expect(filtered_list_on_page).to_have_count(50)
-        await expect(displaying).to_contain_text(re.compile("1-50"))
+        # make sure we wait for 'of {total}', otherwise we might not have waited
+        # until the name filter has been applied
+        await expect(displaying).to_contain_text(f"1-50 of {total}")
+        # check that users names contain the search value in the filtered list
+        for element in await filtered_list_on_page.get_by_test_id(
+            "user-row-name"
+        ).all():
+            await expect(element).to_contain_text(re.compile(f".*{search_value}.*"))
         # click on Next button to verify that the rest part of filtered list is displayed on the next page
         await browser.get_by_role("button", name="Next").click()
+        await browser.wait_for_load_state("networkidle")
         filtered_list_on_next_page = browser.locator('//tr[@class="user-row"]')
-        await expect(filtered_list_on_page).to_have_count(users_count_db_filtered - 50)
+        await expect(filtered_list_on_page).to_have_count(total - 50)
         for element in await filtered_list_on_next_page.get_by_test_id(
             "user-row-name"
         ).all():
@@ -1414,15 +1420,31 @@ async def test_login_xsrf_initial_cookies(app, browser, case, username):
     # after visiting page, cookies get re-established
     await browser.goto(login_url)
     cookies = await browser.context.cookies()
+    cookies = sorted(cookies, key=lambda cookie: len(cookie['path'] or ''))
     print(cookies)
-    cookie = cookies[0]
+    cookie = cookies[-1]
     assert cookie['name'] == '_xsrf'
     assert cookie["path"] == app.hub.base_url
+    # make sure cookie matches form input
+    xsrf_input = browser.locator('//input[@name="_xsrf"]')
+    await expect(xsrf_input).to_have_value(cookie["value"])
 
-    # next page visit, cookies don't change
+    # every visit to login page resets the xsrf cookie
+    # value will only change if timestamp advances
+    await asyncio.sleep(1.5)
     await browser.goto(login_url)
     cookies_2 = await browser.context.cookies()
-    assert cookies == cookies_2
+    cookies_2 = sorted(cookies_2, key=lambda cookie: len(cookie['path'] or ''))
+    print(cookies_2)
+    new_cookie = cookies_2[-1]
+    # xsrf cookie reset
+    assert new_cookie['name'] == "_xsrf"
+    assert new_cookie != cookie
+    assert new_cookie["expires"] > cookie["expires"]
+    # make sure cookie matches form input
+    xsrf_input = browser.locator('//input[@name="_xsrf"]')
+    await expect(xsrf_input).to_have_value(new_cookie["value"])
+
     # login is successful
     await login(browser, username, username)
 

jupyterhub/tests/conftest.py

@@ -32,8 +32,11 @@ import os
 import sys
 from subprocess import TimeoutExpired
 from unittest import mock
+from warnings import warn
 
-from pytest import fixture, raises
+import pytest_asyncio
+from packaging.version import parse as parse_version
+from pytest import fixture, mark, raises
 from sqlalchemy import event
 from tornado.httpclient import HTTPError
 from tornado.platform.asyncio import AsyncIOMainLoop
@@ -57,6 +60,41 @@ from .utils import add_user
 # global db session object
 _db = None
 
+_pytest_asyncio_24 = parse_version(pytest_asyncio.__version__) >= parse_version(
+    "0.24.0.dev0"
+)
+
+
+def pytest_collection_modifyitems(items):
+    if _pytest_asyncio_24:
+        # apply loop_scope="module" to all async tests by default
+        # this is only for pytest_asyncio >= 0.24
+        # pytest_asyncio < 0.24 uses overridden `event_loop` fixture
+        # this can be hopefully be removed in favor of config if
+        # https://github.com/pytest-dev/pytest-asyncio/issues/793
+        # is addressed
+        pytest_asyncio_tests = (
+            item for item in items if pytest_asyncio.is_async_test(item)
+        )
+        asyncio_scope_marker = mark.asyncio(loop_scope="module")
+        for async_test in pytest_asyncio_tests:
+            # add asyncio marker _if_ not already present
+            asyncio_marker = async_test.get_closest_marker('asyncio')
+            if not asyncio_marker or not asyncio_marker.kwargs:
+                async_test.add_marker(asyncio_scope_marker, append=False)
+
+
+if not _pytest_asyncio_24:
+    # pre-pytest-asyncio 0.24, overriding event_loop fixture
+    # was the way to change scope of event_loop
+    # post-0.24 uses modifyitems above
+    @fixture(scope='module')
+    def event_loop(request):
+        """Same as pytest-asyncio.event_loop, but re-scoped to module-level"""
+        event_loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(event_loop)
+        return event_loop
+
 
 @fixture(scope='module')
 def ssl_tmpdir(tmpdir_factory):
@@ -125,15 +163,7 @@ def db():
 
 
 @fixture(scope='module')
-def event_loop(request):
-    """Same as pytest-asyncio.event_loop, but re-scoped to module-level"""
-    event_loop = asyncio.new_event_loop()
-    asyncio.set_event_loop(event_loop)
-    return event_loop
-
-
-@fixture(scope='module')
-async def io_loop(event_loop, request):
+async def io_loop(request):
     """Mostly obsolete fixture for tornado event loop
 
     Main purpose is to register cleanup (close) after we're done with the loop.
@@ -141,12 +171,26 @@ async def io_loop(event_loop, request):
     happens before the io_loop is closed.
     """
     io_loop = AsyncIOMainLoop()
+    event_loop = asyncio.get_running_loop()
     assert asyncio.get_event_loop() is event_loop
     assert io_loop.asyncio_loop is event_loop
 
     def _close():
+        # cleanup everything
+        try:
+            event_loop.run_until_complete(event_loop.shutdown_asyncgens())
+        except (asyncio.CancelledError, RuntimeError):
+            pass
         io_loop.close(all_fds=True)
 
+        # workaround pytest-asyncio trying to cleanup after loop is closed
+        # problem introduced in pytest-asyncio 0.25.2
+        def noop(*args, **kwargs):
+            warn("Loop used after close...", RuntimeWarning, stacklevel=2)
+            return
+
+        event_loop.run_until_complete = noop
+
     request.addfinalizer(_close)
     return io_loop
 
@@ -328,14 +372,15 @@ async def _mockservice(request, app, name, external=False, url=False):
           (as opposed to headless, API-only).
     """
     spec = {'name': name, 'command': mockservice_cmd, 'admin': True}
+    port = random_port()
     if url:
         if app.internal_ssl:
-            spec['url'] = 'https://127.0.0.1:%i' % random_port()
+            spec['url'] = f'https://127.0.0.1:{port}'
         else:
-            spec['url'] = 'http://127.0.0.1:%i' % random_port()
+            spec['url'] = f'http://127.0.0.1:{port}'
 
     if external:
-        spec['oauth_redirect_uri'] = 'http://127.0.0.1:%i' % random_port()
+        spec['oauth_redirect_uri'] = f'http://127.0.0.1:{port}'
 
     event_loop = asyncio.get_running_loop()
 

jupyterhub/tests/mocking.py

@@ -246,6 +246,13 @@ class MockHub(JupyterHub):
         if 'allow_all' not in self.config.Authenticator:
             self.config.Authenticator.allow_all = True
 
+        if 'api_url' not in self.config.ConfigurableHTTPProxy:
+            proxy_port = random_port()
+            proxy_proto = "https" if self.internal_ssl else "http"
+            self.config.ConfigurableHTTPProxy.api_url = (
+                f"{proxy_proto}://127.0.0.1:{proxy_port}"
+            )
+
     @default('subdomain_host')
     def _subdomain_host_default(self):
         return os.environ.get('JUPYTERHUB_TEST_SUBDOMAIN_HOST', '')
@@ -256,7 +263,7 @@ class MockHub(JupyterHub):
             port = urlparse(self.subdomain_host).port
         else:
             port = random_port()
-        return 'http://127.0.0.1:%i/@/space%%20word/' % (port,)
+        return f'http://127.0.0.1:{port}/@/space%20word/'
 
     @default('ip')
     def _ip_default(self):
@@ -270,6 +277,10 @@ class MockHub(JupyterHub):
                 return port
         return random_port()
 
+    @default('hub_port')
+    def _hub_port_default(self):
+        return random_port()
+
     @default('authenticator_class')
     def _authenticator_class_default(self):
         return MockPAMAuthenticator

jupyterhub/tests/test_api.py

@@ -2238,13 +2238,15 @@ async def test_auth_managed_groups(request, app, group, user):
     app.authenticator.manage_groups = True
     request.addfinalizer(lambda: setattr(app.authenticator, "manage_groups", False))
     # create groups
-    r = await api_request(app, 'groups', method='post')
-    assert r.status_code == 400
+    r = await api_request(
+        app,
+        'groups',
+        method='post',
+        data=json.dumps({"groups": {"groupname": [user.name]}}),
+    )
+    assert r.status_code == 201
     r = await api_request(app, 'groups/newgroup', method='post')
-    assert r.status_code == 400
-    # delete groups
-    r = await api_request(app, f'groups/{group.name}', method='delete')
-    assert r.status_code == 400
+    assert r.status_code == 201
     # add users to group
     r = await api_request(
         app,
@@ -2252,7 +2254,7 @@ async def test_auth_managed_groups(request, app, group, user):
         method='post',
         data=json.dumps({"users": [user.name]}),
     )
-    assert r.status_code == 400
+    assert r.status_code == 200
     # remove users from group
     r = await api_request(
         app,
@@ -2260,7 +2262,10 @@ async def test_auth_managed_groups(request, app, group, user):
         method='delete',
         data=json.dumps({"users": [user.name]}),
     )
-    assert r.status_code == 400
+    assert r.status_code == 200
+    # delete groups
+    r = await api_request(app, f'groups/{group.name}', method='delete')
+    assert r.status_code == 204
 
 
 # -----------------

jupyterhub/tests/test_app.py

@@ -8,6 +8,7 @@ import os
 import re
 import sys
 import time
+from concurrent.futures import ThreadPoolExecutor
 from subprocess import PIPE, Popen, check_output
 from tempfile import NamedTemporaryFile, TemporaryDirectory
 from unittest.mock import patch
@@ -16,6 +17,8 @@ import pytest
 import traitlets
 from traitlets.config import Config
 
+from jupyterhub.scopes import get_scopes_for
+
 from .. import orm
 from ..app import COOKIE_SECRET_BYTES, JupyterHub
 from .mocking import MockHub
@@ -289,8 +292,7 @@ def persist_db(tmpdir):
 def new_hub(request, tmpdir, persist_db):
     """Fixture to launch a new hub for testing"""
 
-    async def new_hub():
-        kwargs = {}
+    async def new_hub(**kwargs):
         ssl_enabled = getattr(request.module, "ssl_enabled", False)
         if ssl_enabled:
             kwargs['internal_certs_location'] = str(tmpdir)
@@ -306,17 +308,6 @@ def new_hub(request, tmpdir, persist_db):
 
 
 async def test_resume_spawners(tmpdir, request, new_hub):
-    async def new_hub():
-        kwargs = {}
-        ssl_enabled = getattr(request.module, "ssl_enabled", False)
-        if ssl_enabled:
-            kwargs['internal_certs_location'] = str(tmpdir)
-        app = MockHub(test_clean_db=False, **kwargs)
-        app.config.ConfigurableHTTPProxy.should_start = False
-        app.config.ConfigurableHTTPProxy.auth_token = 'unused'
-        await app.initialize([])
-        return app
-
     app = await new_hub()
     db = app.db
     # spawn a user's server
@@ -537,3 +528,74 @@ async def test_recreate_service_from_database(
     # start one more, service should be gone
     app = await new_hub()
     assert service_name not in app._service_map
+
+
+async def test_revoke_blocked_users(username, groupname, new_hub):
+    config = Config()
+    config.Authenticator.admin_users = {username}
+    kept_username = username + "-kept"
+    config.Authenticator.allowed_users = {username, kept_username}
+    config.JupyterHub.load_groups = {
+        groupname: {
+            "users": [username],
+        },
+    }
+    config.JupyterHub.load_roles = [
+        {
+            "name": "testrole",
+            "scopes": ["access:services"],
+            "groups": [groupname],
+        }
+    ]
+    app = await new_hub(config=config)
+    user = app.users[username]
+
+    # load some credentials, start server
+    await user.spawn()
+    # await app.proxy.add_user(user)
+    spawner = user.spawners['']
+    token = user.new_api_token()
+    orm_token = orm.APIToken.find(app.db, token)
+    app.cleanup_servers = False
+    app.stop()
+
+    # before state
+    assert await spawner.poll() is None
+    assert sorted(role.name for role in user.roles) == ['admin', 'user']
+    assert [g.name for g in user.groups] == [groupname]
+    assert user.admin
+    user_scopes = get_scopes_for(user)
+    assert "access:servers" in user_scopes
+    token_scopes = get_scopes_for(orm_token)
+    assert "access:servers" in token_scopes
+
+    # start a new hub, now with blocked users
+    config = Config()
+    name_doesnt_exist = user.name + "-doesntexist"
+    config.Authenticator.blocked_users = {user.name, name_doesnt_exist}
+    config.JupyterHub.init_spawners_timeout = 60
+    # background spawner.proc.wait to avoid waiting for zombie process here
+    with ThreadPoolExecutor(1) as pool:
+        pool.submit(spawner.proc.wait)
+        app2 = await new_hub(config=config)
+    assert app2.db_url == app.db_url
+
+    # check that blocked user has no permissions
+    user2 = app2.users[user.name]
+    assert user2.roles == []
+    assert user2.groups == []
+    assert user2.admin is False
+    user_scopes = get_scopes_for(user2)
+    assert user_scopes == set()
+    orm_token = orm.APIToken.find(app2.db, token)
+    token_scopes = get_scopes_for(orm_token)
+    assert token_scopes == set()
+
+    # spawner stopped
+    assert user2.spawners == {}
+    assert await spawner.poll() is not None
+
+    # (sanity check) didn't lose other user
+    kept_user = app2.users[kept_username]
+    assert 'user' in [r.name for r in kept_user.roles]
+    app2.stop()

jupyterhub/tests/test_crypto.py

@@ -7,7 +7,7 @@ import pytest
 from .. import crypto
 from ..crypto import decrypt, encrypt
 
-keys = [('%i' % i).encode('ascii') * 32 for i in range(3)]
+keys = [str(i).encode('ascii') * 32 for i in range(3)]
 hex_keys = [b2a_hex(key).decode('ascii') for key in keys]
 b64_keys = [b2a_base64(key).decode('ascii').strip() for key in keys]
 
@@ -36,7 +36,7 @@ def test_env_constructor(key_env, keys):
     "key",
     [
         'a' * 44,  # base64, not 32 bytes
-        ('%44s' % 'notbase64'),  # not base64
+        f"{'notbase64':44}",  # not base64
         b'x' * 64,  # not hex
         b'short',  # not 32 bytes
     ],

jupyterhub/tests/test_dummyauth.py

@@ -2,6 +2,7 @@
 
 # Copyright (c) Jupyter Development Team.
 # Distributed under the terms of the Modified BSD License.
+
 from jupyterhub.auth import DummyAuthenticator
 
 

jupyterhub/tests/test_orm.py

@@ -33,19 +33,19 @@ def test_server(db):
 
     # test wrapper
     server = objects.Server(orm_server=server)
-    assert server.host == 'http://%s:%i' % (socket.gethostname(), server.port)
+    assert server.host == f'http://{socket.gethostname()}:{server.port}'
     assert server.url == server.host + '/'
-    assert server.bind_url == 'http://*:%i/' % server.port
+    assert server.bind_url == f'http://*:{server.port}/'
     server.ip = '127.0.0.1'
-    assert server.host == 'http://127.0.0.1:%i' % server.port
+    assert server.host == f'http://127.0.0.1:{server.port}'
     assert server.url == server.host + '/'
 
     server.connect_ip = 'hub'
-    assert server.host == 'http://hub:%i' % server.port
+    assert server.host == f'http://hub:{server.port}'
     assert server.url == server.host + '/'
 
-    server.connect_url = 'http://hub-url:%i/connect' % server.port
-    assert server.host == 'http://hub-url:%i' % server.port
+    server.connect_url = f'http://hub-url:{server.port}/connect'
+    assert server.host == f'http://hub-url:{server.port}'
 
     server.bind_url = 'http://127.0.0.1/'
     assert server.port == 80

jupyterhub/tests/test_pages.py

@@ -2,11 +2,14 @@
 
 import asyncio
 import sys
+from contextlib import nullcontext
+from functools import partial
 from unittest import mock
 from urllib.parse import parse_qs, urlencode, urlparse
 
 import pytest
 from bs4 import BeautifulSoup
+from tornado import web
 from tornado.httputil import url_concat
 
 from .. import orm, roles, scopes
@@ -720,14 +723,50 @@ async def test_page_with_token(app, user, url, token_in):
 
 
 async def test_login_fail(app):
+    name = 'wash'
+    base_url = public_url(app)
+    login_url = base_url + 'hub/login'
+    r = await async_requests.get(login_url)
+    r.raise_for_status()
+    xsrf = r.cookies['_xsrf']
+    r = await async_requests.get(login_url)
+    assert set(r.cookies.keys()).issubset({"_xsrf"})
+    r = await async_requests.post(
+        login_url,
+        data={'username': name, 'password': 'wrong', '_xsrf': xsrf},
+        allow_redirects=False,
+        cookies=r.cookies,
+    )
+    assert r.status_code == 403
+    assert set(r.cookies.keys()).issubset({"_xsrf"})
+    page = BeautifulSoup(r.content, "html.parser")
+    assert "Sign in" in page.text
+    login = page.find("form")
+    login_error = login.find(class_="login_error")
+    assert login_error
+    assert "Invalid user" in login_error.text
+
+
+async def test_login_fail_xsrf_expired(app):
     name = 'wash'
     base_url = public_url(app)
     r = await async_requests.post(
         base_url + 'hub/login',
-        data={'username': name, 'password': 'wrong'},
+        data={
+            'username': name,
+            'password': name,
+            '_xsrf': "wrong",
+        },
         allow_redirects=False,
     )
+    assert r.status_code == 403
     assert set(r.cookies.keys()).issubset({"_xsrf"})
+    page = BeautifulSoup(r.content, "html.parser")
+    assert "Sign in" in page.text
+    login = page.find("form")
+    login_error = login.find(class_="login_error")
+    assert login_error
+    assert "Try again" in login_error.text
 
 
 @pytest.mark.parametrize(
@@ -1060,7 +1099,7 @@ async def test_oauth_token_page(app):
 
 @pytest.mark.parametrize("error_status", [503, 404])
 async def test_proxy_error(app, error_status):
-    r = await get_page('/error/%i' % error_status, app)
+    r = await get_page(f'/error/{error_status}', app)
     assert r.status_code == 200
 
 
@@ -1335,3 +1374,86 @@ async def test_services_nav_links(
         assert service.href in nav_urls
     else:
         assert service.href not in nav_urls
+
+
+class TeapotError(web.HTTPError):
+    text = "I'm a <🫖>"
+    html = "<b>🕸️🫖</b>"
+
+    def __init__(self, log_msg, kind="text"):
+        super().__init__(418, log_msg)
+        self.jupyterhub_message = self.text
+        if kind == "html":
+            self.jupyterhub_html_message = self.html
+
+
+def hook_fail_fast(spawner, kind):
+    if kind == "unhandled":
+        raise RuntimeError("unhandle me!!!")
+    raise TeapotError("log_msg", kind=kind)
+
+
+async def hook_fail_slow(spawner, kind):
+    await asyncio.sleep(1)
+    hook_fail_fast(spawner, kind)
+
+
+@pytest.mark.parametrize("speed", ["fast", "slow"])
+@pytest.mark.parametrize("kind", ["text", "html", "unhandled"])
+async def test_spawn_fails_custom_message(app, user, kind, speed):
+    if speed == 'slow':
+        speed_context = mock.patch.dict(
+            app.tornado_settings, {'slow_spawn_timeout': 0.1}
+        )
+        hook = hook_fail_slow
+    else:
+        speed_context = nullcontext()
+        hook = hook_fail_fast
+    # test the response when spawn fails before redirecting to progress
+    with mock.patch.dict(
+        app.config.Spawner, {"pre_spawn_hook": partial(hook, kind=kind)}
+    ), speed_context:
+        cookies = await app.login_user(user.name)
+        assert user.spawner.pre_spawn_hook
+        r = await get_page("spawn", app, cookies=cookies)
+        if speed == "slow":
+            # go through spawn_pending, render not_running.html
+            assert r.ok
+            assert "spawn-pending" in r.url
+            # wait for ready signal before checking next redirect
+            while user.spawner.active:
+                await asyncio.sleep(0.1)
+            app.log.info(
+                f"pending {user.spawner.active=}, {user.spawner._spawn_future=}"
+            )
+            # this should fetch the not-running page
+            app.log.info("getting again")
+            r = await get_page(
+                f"spawn-pending/{user.escaped_name}", app, cookies=cookies
+            )
+            target_class = "container"
+            unhandled_text = "Spawn failed"
+        else:
+            unhandled_text = "Unhandled error"
+            target_class = "error"
+        page = BeautifulSoup(r.content)
+        if kind == "unhandled":
+            assert r.status_code == 500
+        else:
+            assert r.status_code == 418
+        error = page.find(class_=target_class)
+        # check escaping properly
+        error_html = str(error)
+        if kind == "text":
+            assert "<🫖>" in error.text
+            assert "🕸️" not in error.text
+            assert "&lt;🫖&gt;" in error_html
+        elif kind == "html":
+            assert "<🫖>" not in error.text
+            assert "🕸️" in error.text
+            assert "<b>🕸️🫖</b>" in error_html
+        elif kind == "unhandled":
+            assert unhandled_text in error.text
+            assert "unhandle me" not in error.text
+        else:
+            raise ValueError(f"unexpected {kind=}")

jupyterhub/tests/test_proxy.py

@@ -35,7 +35,7 @@ async def test_external_proxy(request):
     proxy_port = random_port()
     cfg = Config()
     cfg.ConfigurableHTTPProxy.auth_token = auth_token
-    cfg.ConfigurableHTTPProxy.api_url = 'http://%s:%i' % (proxy_ip, proxy_port)
+    cfg.ConfigurableHTTPProxy.api_url = f'http://{proxy_ip}:{proxy_port}'
     cfg.ConfigurableHTTPProxy.should_start = False
 
     app = MockHub.instance(config=cfg)
@@ -76,7 +76,7 @@ async def test_external_proxy(request):
     request.addfinalizer(_cleanup_proxy)
 
     def wait_for_proxy():
-        return wait_for_http_server('http://%s:%i' % (proxy_ip, proxy_port))
+        return wait_for_http_server(f'http://{proxy_ip}:{proxy_port}')
 
     await wait_for_proxy()
 
@@ -141,7 +141,7 @@ async def test_external_proxy(request):
         '--api-port',
         str(proxy_port),
         '--default-target',
-        'http://%s:%i' % (app.hub_ip, app.hub_port),
+        f'http://{app.hub_ip}:{app.hub_port}',
     ]
     if app.subdomain_host:
         cmd.append('--host-routing')

jupyterhub/tests/test_services.py

@@ -27,7 +27,7 @@ async def external_service(app, name='mockservice'):
         'JUPYTERHUB_API_TOKEN': hexlify(os.urandom(5)),
         'JUPYTERHUB_SERVICE_NAME': name,
         'JUPYTERHUB_API_URL': url_path_join(app.hub.url, 'api/'),
-        'JUPYTERHUB_SERVICE_URL': 'http://127.0.0.1:%i' % random_port(),
+        'JUPYTERHUB_SERVICE_URL': f'http://127.0.0.1:{random_port()}',
     }
     proc = Popen(mockservice_cmd, env=env)
     try:

jupyterhub/tests/test_shared_password.py

@@ -0,0 +1,162 @@
+import pytest
+from traitlets.config import Config
+
+from jupyterhub.authenticators.shared import SharedPasswordAuthenticator
+
+
+@pytest.fixture
+def admin_password():
+    return "a" * 32
+
+
+@pytest.fixture
+def user_password():
+    return "user_password"
+
+
+@pytest.fixture
+def authenticator(admin_password, user_password):
+    return SharedPasswordAuthenticator(
+        admin_password=admin_password,
+        user_password=user_password,
+        admin_users={"admin"},
+        allow_all=True,
+    )
+
+
+async def test_password_validation():
+    authenticator = SharedPasswordAuthenticator()
+    # Validate length
+    with pytest.raises(
+        ValueError,
+        match="admin_password must be at least 32 characters",
+    ):
+        authenticator.admin_password = "a" * 31
+
+    with pytest.raises(
+        ValueError,
+        match="user_password must be at least 8 characters",
+    ):
+        authenticator.user_password = "a" * 7
+
+    # Validate that the passwords aren't the same
+    authenticator.user_password = "a" * 32
+    with pytest.raises(
+        ValueError,
+        match="SharedPasswordAuthenticator.user_password and SharedPasswordAuthenticator.admin_password cannot be the same",
+    ):
+        authenticator.admin_password = "a" * 32
+
+    # ok
+    authenticator.admin_password = "a" * 33
+
+    # check collision in the other order
+    with pytest.raises(
+        ValueError,
+        match="SharedPasswordAuthenticator.user_password and SharedPasswordAuthenticator.admin_password cannot be the same",
+    ):
+        authenticator.user_password = "a" * 33
+
+
+async def test_admin_password(authenticator, user_password, admin_password):
+    # Regular user, regular password
+    authorized = await authenticator.get_authenticated_user(
+        None, {'username': 'test_user', 'password': user_password}
+    )
+    assert authorized['name'] == 'test_user'
+    assert not authorized['admin']
+
+    # Regular user, admin password
+    authorized = await authenticator.get_authenticated_user(
+        None, {'username': 'test_user', 'password': admin_password}
+    )
+    assert not authorized
+
+    # Admin user, admin password
+    authorized = await authenticator.get_authenticated_user(
+        None, {'username': 'admin', 'password': admin_password}
+    )
+    assert authorized['name'] == 'admin'
+    assert authorized['admin']
+
+    # Admin user, regular password
+    authorized = await authenticator.get_authenticated_user(
+        None, {'username': 'admin', 'password': user_password}
+    )
+    assert not authorized
+
+    # Regular user, wrong password
+    authorized = await authenticator.get_authenticated_user(
+        None, {'username': 'test_user', 'password': 'blah'}
+    )
+    assert not authorized
+
+    # New username, allow_all is False
+    authenticator.allow_all = False
+    authorized = await authenticator.get_authenticated_user(
+        None, {'username': 'new_user', 'password': 'user_password'}
+    )
+    assert not authorized
+
+
+async def test_empty_passwords():
+    authenticator = SharedPasswordAuthenticator(
+        allow_all=True,
+        admin_users={"admin"},
+        user_password="",
+        admin_password="",
+    )
+    authorized = await authenticator.get_authenticated_user(
+        None, {'username': 'admin', 'password': ''}
+    )
+    assert not authorized
+    authorized = await authenticator.get_authenticated_user(
+        None, {'username': 'user', 'password': ''}
+    )
+    assert not authorized
+
+
+@pytest.mark.parametrize(
+    "auth_config, warns, not_warns",
+    [
+        pytest.param({}, "nobody can login", "", id="default"),
+        pytest.param(
+            {"allow_all": True},
+            "Nobody will be able to login",
+            "regular users",
+            id="no passwords",
+        ),
+        pytest.param(
+            {"admin_password": "a" * 32}, "admin_users is not", "", id="no admin_users"
+        ),
+        pytest.param(
+            {"admin_users": {"admin"}},
+            "admin_password is not",
+            "",
+            id="no admin_password",
+        ),
+        pytest.param(
+            {"admin_users": {"admin"}, "admin_password": "a" * 32, "allow_all": True},
+            "No non-admin users will be able to login",
+            "",
+            id="only_admin",
+        ),
+    ],
+)
+def test_check_allow_config(caplog, auth_config, warns, not_warns):
+    # check log warnings
+    config = Config()
+    for key, value in auth_config.items():
+        setattr(config.SharedPasswordAuthenticator, key, value)
+    authenticator = SharedPasswordAuthenticator(config=config)
+    authenticator.check_allow_config()
+    if warns:
+        if isinstance(warns, str):
+            warns = [warns]
+        for snippet in warns:
+            assert snippet in caplog.text
+    if not_warns:
+        if isinstance(not_warns, str):
+            not_warns = [not_warns]
+        for snippet in not_warns:
+            assert snippet not in caplog.text

jupyterhub/tests/test_shares.py

@@ -1342,6 +1342,13 @@ async def test_share_codes_api_revoke(
         method="delete",
         name=requester.name,
     )
+    if r.status_code != status:
+        # debug intermittent failure
+        print(f"{share_code=}")
+        print(f"{code=}")
+        print(f"{url=}")
+        for sc in db.query(orm.ShareCode):
+            print(f"{sc.id=}, {sc.prefix=}, {sc.hashed=}, {sc=}")
     assert r.status_code == status
 
     # other code unaffected

jupyterhub/tests/test_singleuser.py

@@ -103,7 +103,7 @@ async def test_singleuser_auth(
     assert r.status_code == 200
 
     # logout
-    r = await s.get(url_path_join(url, 'logout'))
+    r = await s.get(url_path_join(url, 'logout'), allow_redirects=False)
     assert len(r.cookies) == 0
 
     # accessing another user's server hits the oauth confirmation page
@@ -201,9 +201,9 @@ async def test_disable_user_config(request, app, tmp_path, full_spawn):
     # (symlink and real)
     def assert_not_in_home(path, name):
         path = Path(path).resolve()
-        assert not (str(path) + os.path.sep).startswith(
-            str(tmp_path) + os.path.sep
-        ), f"{name}: {path} is in home {tmp_path}"
+        assert not (str(path) + os.path.sep).startswith(str(tmp_path) + os.path.sep), (
+            f"{name}: {path} is in home {tmp_path}"
+        )
 
     for path in info['config_file_paths']:
         assert_not_in_home(path, 'config_file_paths')

jupyterhub/tests/test_spawner.py

@@ -260,7 +260,7 @@ async def test_shell_cmd(db, tmpdir, request):
     s.server.port = port
     db.commit()
     await wait_for_spawner(s)
-    r = await async_requests.get('http://%s:%i/env' % (ip, port))
+    r = await async_requests.get(f'http://{ip}:{port}/env')
     r.raise_for_status()
     env = r.json()
     assert env['TESTVAR'] == 'foo'
@@ -524,14 +524,53 @@ async def test_spawner_oauth_roles_bad(app, user):
 
 async def test_spawner_options_from_form(db):
     def options_from_form(form_data):
-        return form_data
+        options = {}
+        for key, value in form_data.items():
+            options[key] = value[0]
+        options["default"] = "added"
+        return options
 
     spawner = new_spawner(db, options_from_form=options_from_form)
     form_data = {"key": ["value"]}
     result = spawner.run_options_from_form(form_data)
-    for key, value in form_data.items():
-        assert key in result
-        assert result[key] == value
+    assert result == {
+        "key": "value",
+        "default": "added",
+    }
+
+
+@pytest.mark.parametrize(
+    "options_from_form, expected",
+    [
+        pytest.param(None, "unchanged", id="default"),
+        pytest.param("passthrough", "unchanged", id="passthrough"),
+        pytest.param(
+            "simple",
+            {
+                "single": "value",
+                "multiple": ["a", "b"],
+                "checkbox": True,
+                "number": "1",
+            },
+            id="simple",
+        ),
+    ],
+)
+async def test_predefined_options_from_form(db, options_from_form, expected):
+    kwargs = {}
+    if options_from_form:
+        kwargs["options_from_form"] = options_from_form
+    spawner = new_spawner(db, **kwargs)
+    form_data = {
+        "single": ["value"],
+        "multiple": ["a", "b"],
+        "checkbox": ["on"],
+        "number": ["1"],
+    }
+    if expected == "unchanged":
+        expected = form_data
+    result = spawner.run_options_from_form(form_data)
+    assert result == expected
 
 
 async def test_spawner_options_from_form_with_spawner(db):
@@ -546,6 +585,44 @@ async def test_spawner_options_from_form_with_spawner(db):
         assert result[key] == value
 
 
+async def test_apply_user_options_dict(db):
+    apply_user_options = {
+        # from_string doesn't work,
+        # but string assignment does
+        "mem": "mem_limit",
+        "notebook_dir": "notebook_dir",
+        "term_timeout": "term_timeout",
+        "start_timeout": "start_timeout",
+        "environment": "environment",
+        "unsupported": "unsupported",
+    }
+    user_options = {
+        "mem": "1G",
+        "notebook_dir": "/tmp",
+        "term_timeout": 1,
+        "start_timeout": "10",
+        "environment": {
+            "key": "value",
+        },
+        # shouldn't set these values:
+        # unsupported, but declared;
+        "unsupported": 5,
+        # undeclared, but available
+        "cpu_limit": "1m",
+    }
+    if sys.version_info < (3, 9):
+        # traitlets added `from_string` after requiring Python 3.9
+        user_options["start_timeout"] = int(user_options["start_timeout"])
+    spawner = new_spawner(db, apply_user_options=apply_user_options)
+    await spawner._run_apply_user_options(user_options)
+    assert spawner.mem_limit == 1 << 30
+    assert spawner.notebook_dir == "/tmp"
+    assert spawner.term_timeout == 1
+    assert spawner.environment == {"key": "value"}
+    assert not hasattr(spawner, "unsupported")
+    assert spawner.cpu_limit is None
+
+
 def test_spawner_server(db):
     spawner = new_spawner(db)
     spawner.orm_spawner = None