stellars-jupyterhub-ds/docs/notifications.md

# Notification Broadcast System

Admin-only broadcast system sending notifications to all active JupyterLab servers simultaneously. Accessible at `/hub/notifications`.

**Key Implementation Facts**:
- Concurrent delivery using `asyncio.gather()` with 5-second timeout per server
- Temporary API tokens generated per broadcast (5-minute expiry via `user.new_api_token()`)
- Dynamic endpoint URL construction: `http://jupyterlab-{username}:8888{base_url}jupyterlab-notifications-extension/ingest`
- 140-character message limit with live counter
- Six notification types: default, info, success, warning, error, in-progress
- Payload includes actions array with Dismiss button
- One-line logging per server: username, message preview, type, outcome (SUCCESS/FAILED/ERROR)

**Handler Implementation** (`services/jupyterhub/conf/bin/custom_handlers.py`):
- `NotificationsPageHandler` - Renders broadcast form at `/hub/notifications`
- `BroadcastNotificationHandler` - API endpoint for sending notifications at `/hub/api/notifications/broadcast`
- Both restricted to admin users via `@admin_only` decorator

**Template** (`services/jupyterhub/templates/notifications.html`):
- Bootstrap 5 form with message textarea, type selector, auto-close toggle
- RequireJS wrapped JavaScript for CSRF protection
- Results display with expandable per-user status table

**Dependencies**:
- Requires `jupyterlab_notifications_extension` installed on spawned JupyterLab servers
- Extension provides ingest endpoint at `/jupyterlab-notifications-extension/ingest`
- Extension repository: https://github.com/stellarshenson/jupyterlab_notifications_extension

**Error Handling**:
- Connection timeout -> "Server not responding"
- HTTP 404 -> "Notification extension not installed"
- HTTP 401/403 -> "Authentication failed"
- HTTP 500 -> "Server error processing notification"
- Failures don't block other deliveries (fault-tolerant)