jupyterlab-rtclauncher

A small JupyterLab 4 extension for the NASA Research Platform. It adds a Launcher tile — "Open <project> Collaboration" — that opens the project's shared real-time-collaboration (RTC) server.

Without it, members reach the shared server through JupyterHub's admin UI (/hub/admin), which is why they were granted the broad-looking admin-ui scope. This extension replaces that route so the scope can be dropped.

How it works

The tile is state-aware: it starts the shared server when it is down, and stops it when it is up.

server down │ "Open abtesting Collaboration"  ──▶ /hub/spawn/abtesting-collab
            │                                  ──▶ /user/abtesting-collab/lab
────────────┼──────────────────────────────────────────────────────────────────
server up   │ "Stop abtesting Collaboration"  ──▶ confirm ──▶ DELETE server

1. On activation the frontend calls GET /jupyterlab-rtclauncher/config, which reads the spawn-time environment and answers with the project and shared account name.
2. It then polls GET /jupyterlab-rtclauncher/status (every 15s) to track whether the shared server is running.
3. Start is a plain navigation to <hubPrefix>/spawn/<project>-collab. Stop posts to /jupyterlab-rtclauncher/stop after a confirmation dialog, which proxies DELETE /hub/api/users/<project>-collab/server.

Why stopping matters

The shared server bills the project pool for as long as it runs. JupyterHub's idle culler reaps it after 1h idle, but an open browser tab keeps refreshing last_activity and can defeat that — and since the admin-ui scope was dropped, members have no other way to shut it down. The Stop action closes that gap.

Note the server's 10Gi EBS home persists whether it runs or not; stopping releases the compute, which is the expensive part.

Why the stop goes through the server extension

The hub's _xsrf cookie is scoped to Path=/hub/, so JavaScript served from /user/<name>/lab cannot read it — and JupyterHub 5 requires that XSRF token for cookie-authenticated, non-GET API calls. The stop therefore proxies through this extension's server handler, which authenticates with the notebook server's own JUPYTERHUB_API_TOKEN.

That token only carries admin:servers!user=<project>-collab when the user genuinely holds it: JupyterHub resolves Spawner.server_token_scopes against the user's own scopes and drops the rest. A user outside the project's Keycloak group gets a token without it and the hub answers 403. The extension grants nothing.

Requires rp-deployment to request that scope via Spawner.server_token_scopes (terraform/config/20-nojovyan.py). Without it, can_control is false and the tile degrades to start-only.

Which projects get a tile

Any project with collaboration enabled — there is no hardcoded project list and no allowlist to configure here.

The enablement signal is the RP_COLLAB_ACCOUNT environment variable:

1. A platform admin flips Real-Time Collaboration → Enable collaboration for a project in the RPAdmin console, which provisions its login-less <key>-collab principal.
2. RPAdmin's GET /api/me/spawn-identity — already called on every spawn — now returns collab_account: "<key>-collab" for that project, or null.
3. rp-deployment terraform/config/20-nojovyan.py forwards a non-null value to the notebook as RP_COLLAB_ACCOUNT.
4. This extension shows the tile only when that variable is present.

So enabling a new project is a toggle in RPAdmin — no change to this extension, the spawner, or the image. OSSProject supplies the project key for the tile's label; the account name comes from RP_COLLAB_ACCOUNT so the naming convention lives only in RPAdmin.

Operational note. JupyterHub access is granted separately, by the RP_COLLAB_PROJECT_KEYS allowlist in rp-deployment (the ISSO widening gate, feature 083). A project enabled in RPAdmin but missing from that allowlist will show a tile whose spawn the hub refuses — enabling collaboration is a two-step operation by design, and the two must be kept in sync.

The tile grants nothing

It is a link. Starting the shared server requires admin:servers!user=<acct> and entering it requires access:servers!user=<acct>; both are granted to the project's Keycloak /smdc-oss/<project> group by rp-deployment terraform/config/41-collab-accounts.py, and auto-revoke when Keycloak drops the membership. A user without them who follows the link is refused by the hub.

The tile hides itself when RP_COLLAB_ACCOUNT is unset (collaboration is off for the project), or when the current server is the collaboration server (JUPYTERHUB_USER ends in -collab).

Install

pip install jupyterlab-rtclauncher

Both the frontend and the server extension are enabled automatically. To verify:

jupyter labextension list   # jupyterlab-rtclauncher ... enabled OK
jupyter server extension list

Development

pip install -e ".[test]"
jupyter labextension develop . --overwrite
jlpm build

Run the tests:

python -m pytest tests/   # server extension
jlpm test                 # frontend

Rebuild after a source change with jlpm build, or run jlpm watch in one terminal and jupyter lab in another.

Uninstall

pip uninstall jupyterlab-rtclauncher

Related

• Feature 083 — RTC collaboration accounts (rpadmin/specs/083-rtc-collab-accounts/)
• jupyterlab-resource-tracker — the usage & cost extension shipped in the same image