Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-16063-hub-fleet-activity-page.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The hub has a read-only **Fleet activity** page at `/activity`, linked as **📡 Fleet activity** next to **🔬 Evidence**. It shows the open issues and PRs of the hives you can see, from `GET /api/hub/activity`, which scopes every hive to you server-side. It polls every 15 s with `If-None-Match` and redraws only when the ETag changes. A **Hive** column carries a colour chip that opens the hive's own tracker; rows link to GitHub, titles render as text, and there are no action menus. Group-by-hive draws a header per hive with its item count and freshness (`stale` after two missed heartbeats, "upgrade to report activity" for hives that send no activity, missing hives). A list above the board always names truncated items, dropped events and stale or missing hives. Rows use the shared tracker row asset, and the page is served with its own Content-Security-Policy (no inline scripts, handlers or styles). Display mode follows separately ([#16063](https://github.com/hivecommons/hive/issues/16063), part of [#15965](https://github.com/hivecommons/hive/issues/15965), RFC [#15861](https://github.com/hivecommons/hive/issues/15861)).
2 changes: 2 additions & 0 deletions src/docs/api-reference/hub-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `GET` | `/api/reach` | Hub admin | PR Reach Report (?pr=NNN or ?recent=K) | `pkg/hub/saas.go:522` |
| `GET` | `/fleet` | Hub handler-specific | My-Hives Fleet Page (static; data via `/api/saas/my-hives`) | `pkg/hub/server.go:1773` |
| `GET` | `/my-hives` | Hub handler-specific | 301 redirect to `/fleet` (query preserved) | `pkg/hub/server.go:1774` |
| `GET` | `/activity` | Signed-in user | Fleet activity page ([#16063](https://github.com/hivecommons/hive/issues/16063)): read-only, data-free shell that polls `/api/hub/activity` every 15 s with `If-None-Match`. No session → `307` to `/login`; blocked user → `403`. Own Content-Security-Policy (scripts and styles from `'self'` only, `script-src-attr`/`style-src-attr` `'none'`), `Cache-Control: no-cache` + content `ETag`. See [Hub Fleet activity page](../hub-fleet-activity.md) | `pkg/hub/activity_page.go` |
| `GET` | `/activity/assets/{name}` | Public | The shared tracker row asset (`pkg/webassets/trackerrow`, [#16062](https://github.com/hivecommons/hive/issues/16062)) the Fleet activity page draws rows with, byte-identical; only names in `trackerrow.Files`, else `404`. `Cache-Control: no-cache` + content `ETag` | `pkg/hub/activity_page.go` |
| `POST` | `/api/shared-agent-pool/leases` | Hub handler-specific | Acquire or renew a shared CLI session lease | `pkg/hub/server.go:1708` |
| `PUT` | `/api/shared-agent-pool/leases` | Hub handler-specific | Renew an active shared CLI session lease | `pkg/hub/server.go:1709` |
| `DELETE` | `/api/shared-agent-pool/leases` | Hub handler-specific | Release a shared CLI session lease | `pkg/hub/server.go:1710` |
Expand Down
1 change: 1 addition & 0 deletions src/docs/documentation-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ Documentation for the current Hive line (branch `v5`; the code and docs live und
### First installation

- [Hosted Hive Hub onboarding](hosted-hub.md) — signing in at `https://hive.hivecommons.dev`, requesting a hosted hive, installing the GitHub App, configuring model gateways and Copilot login, reading `/fleet`, and fixing common setup problems.
- [Hub Fleet activity page](hub-fleet-activity.md) — the read-only `/activity` board of open issues and PRs across the hives you can see: per-viewer scoping, hive chips, group-by-hive freshness headers, always-visible truncation and stale-source disclosures, and 15-second ETag polling.
- [Docker Compose quick start](quickstart-docker-compose.md) — default standalone installation, prerequisites, and verification.
- [Podman quick start](quickstart-podman.md) — standalone Quadlet/systemd installation, with rootless/rootful prerequisites.
- [Kubernetes deployment](kubernetes-deployment.md) — standalone cluster installation, storage, authentication, and dashboard access. Related: [health checks](health-checks.md).
Expand Down
6 changes: 6 additions & 0 deletions src/docs/hosted-hub.md
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,12 @@ Key signals:
(hive owner vs hub operator) are listed in the
[fleet drift signals reference](fleet-drift-signals.md).

For the open issues and pull requests the hives you can see are working on,
open **📡 Fleet activity** (next to **🔬 Evidence**) or
<https://hive.hivecommons.dev/activity>. It is a read-only board that refreshes
every 15 seconds and says which hives are stale or not reporting. See
[Hub Fleet activity page](hub-fleet-activity.md).

## Common problems and fixes

| Symptom | Likely cause | Fix |
Expand Down
112 changes: 112 additions & 0 deletions src/docs/hub-fleet-activity.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
# Hub Fleet activity page

The **Fleet activity** page at `https://<hub>/activity` is a read-only board of
the open issues and pull requests that the hives you can see are working on.
It is the hub-side view of the Activity Monitor: each spoke attaches a bounded
activity digest to its heartbeat, and the hub merges the digests of your hives
into one board.

Open it from the **📡 Fleet activity** link next to **🔬 Evidence** on the
dashboard's Fleet quadrant card, or go to `/activity` directly. You must be
signed in; a browser without a hub session is sent to `/login`.

The design is RFC [#15861](https://github.com/hivecommons/hive/issues/15861)
by @hanthor, delivered in [#15965](https://github.com/hivecommons/hive/issues/15965)
and its children. The page itself is [#16063](https://github.com/hivecommons/hive/issues/16063).

## Who sees what

The page shows exactly what `GET /api/hub/activity` returns for you. That
endpoint decides access per hive on the server before it reads any data:

- A hub admin sees every registered hive.
- Everyone else sees the hives they own and the hives they hold an unexpired
grant for.
- Another hive's rows, counts and freshness never reach your browser, so they
are not in the page and not in its ETag.

The page itself carries no fleet data. It is a static shell that loads the
board from the endpoint.

## Reading the board

Each row is one open issue or PR:

| Column | Shows |
| --- | --- |
| **Hive** | A colour chip per hive. The colour is stable per hive id. The chip opens that hive's own dashboard and tracker through the hub's hive route (`/api/saas/hives/<id>/open`), which signs you in or explains why it cannot. |
| **Item** | `owner/repo#N` and whether it is an issue or a PR. It links to the item on GitHub. |
| **Title** | The item title as plain text, capped at 200 characters by the hub. A leading `[agent]` tag is drawn as a chip. |
| **Stage** | The strip column the spoke tracker would light (Open, Actionable, Claimed, PR in progress, CI / Review, Merge gate, Merged) and the stage slug. |
| **Author** | `human`, `clanker` or `hive` when the spoke knows it. |

Rows come in the endpoint's order: most urgent first, then furthest stage.

**Group by hive** is on by default. It draws one header row per hive, even when
the hive has no open items. The header shows:

- the item count, plus the hive's tracked total when the digest held some back;
- freshness:
- `fresh`: the hive's activity report is recent;
- `stale`: the last activity report is older than two missed heartbeats
(more than 4 minutes);
- `not reporting`: the hive heartbeats but sends no activity block.
Upgrade it to report activity;
- `missing`: you hold a grant for a hive the hub registry does not know.

Turn grouping off for one flat list. The Hive column still tells rows apart.

## What the board leaves out

The list above the table is always visible. It never hides in a tooltip. It
names every gap in the data:

- items left out by the hub's response cap;
- items a hive's own digest cap left out (`truncated`);
- events dropped before they reached the hub (`events_dropped`);
- stale, not-reporting and missing hives.

When nothing is missing it says so: "All N hives reporting; nothing left out".

## Refresh

The page polls `GET /api/hub/activity` every 15 seconds with `If-None-Match`.
The hub answers `304 Not Modified` while nothing in your view changed, and the
board is redrawn only when the ETag changes. Polling pauses while the tab is
hidden and resumes, with an immediate refresh, when you come back. The status
line shows when the data last changed and when it was last checked. If your
session expires, the page sends you to `/login`.

## What the page does not do

- It has no action menus. The hub is visibility-only: act on an item on
GitHub, or from the hive's own tracker.
- Display mode (`?kiosk=1`, `am.*` URL state, `?display=1` and a
`hub-activity` playlist view) is not part of this page yet; it is tracked in
[#16064](https://github.com/hivecommons/hive/issues/16064).

## Security

- The page is served with its own Content-Security-Policy. Scripts and styles
load only as files from the hub (`'self'`). Inline scripts, inline event
handlers and inline style attributes are refused, and the page loads nothing
from other origins.
- Titles and every other value from a spoke are written as text, never parsed
as HTML.
- The page, its script and the shared row-presentation asset are revalidated
on every load (`Cache-Control: no-cache` with a content ETag), so a hub
upgrade is picked up on the next visit.
- `/activity` is marked `noindex` and is disallowed in `robots.txt`.

## For operators

- A spoke publishes its digest only when `hub.activity.enabled` is on. It is
on by default for hosted spokes and opt-in for self-hosted ones. A hive that
heartbeats without it shows as `not reporting`.
- Digests live in hub memory only. After a hub restart, hives show
`not reporting` until a later heartbeat carries a full digest again.
- Rows are drawn with the tracker's own row-presentation asset
(`src/pkg/webassets/trackerrow`), which the hub serves under
`/activity/assets/`. The page defines the stage constants that asset reads,
with the spoke's values, so a hub row lights the same column as the spoke
tracker.
98 changes: 98 additions & 0 deletions src/pkg/hub/activity_page.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
package hub

import (
"io/fs"
"net/http"
"slices"

"github.com/hivecommons/hive/pkg/dashboard/webstatic"
"github.com/hivecommons/hive/pkg/webassets/trackerrow"
)

// Fleet activity page (#16063, part of #15965 / RFC #15861 by @hanthor).
//
// GET /activity serves a data-free shell to signed-in users; the board is
// filled in the browser by polling GET /api/hub/activity (activity.go),
// which scopes every hive to the viewer server-side. The page is read-only:
// rows link to GitHub and the hive chip to the hive's own tracker, with no
// action menus. Rows are drawn with the shared tracker row asset
// (pkg/webassets/trackerrow, #16062), served from activityAssetPrefix.

const (
activityPagePath = "/activity"
activityAssetPrefix = "/activity/assets/"
activityPageFile = "static/activity.html"

// activityPageCSP follows the script-src split of
// pkg/dashboard/webstatic/csp_script_src.go: scripts are files under
// 'self' (the document has no inline <script>, so script-src-elem is
// recomputed from the served bytes and stays 'self'), inline event
// handlers and style attributes are refused, and nothing else loads.
activityPageCSP = "default-src 'none'; " +
"script-src 'self'; script-src-elem 'self'; script-src-attr 'none'; " +
"style-src 'self'; style-src-elem 'self'; style-src-attr 'none'; " +
"img-src 'self' data:; font-src 'self'; connect-src 'self'; " +
"base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
)

// handleActivityPage serves the Fleet activity shell. A browser without a
// valid session (no cookie, or an expired or forged one) is sent to /login
// like /dashboard; everyone else goes through requireAuth, so a blocked
// account is refused before the shell is written.
func (s *HubServer) handleActivityPage(w http.ResponseWriter, r *http.Request) {
if s.getAuthUser(r) == "" {
http.Redirect(w, r, "/login", http.StatusTemporaryRedirect)
return
}
s.requireAuth(s.serveActivityShell)(w, r)
}

func (s *HubServer) serveActivityShell(w http.ResponseWriter, r *http.Request) {
page, err := staticFS.ReadFile(activityPageFile)
if err != nil {
s.logger.Error("hub activity page: read embedded shell", "error", err)
s.writeHubErrorPage(w, http.StatusInternalServerError)
return
}
h := w.Header()
h.Set("Content-Type", "text/html; charset=utf-8")
h.Set("X-Content-Type-Options", "nosniff")
h.Set("Referrer-Policy", "same-origin")
h.Set("Content-Security-Policy", activityPageCSP)
webstatic.ApplyDocumentScriptSrcElem(w, page)
if webstatic.WriteCacheHeaders(w, r, webstatic.ETagFor(page)) {
return
}
_, _ = w.Write(page)
}

// handleActivityAsset serves one file of the shared tracker row asset,
// byte-identical to pkg/webassets/trackerrow, with the static no-cache +
// content ETag headers. Only names listed in trackerrow.Files are served.
// The files are pure presentation code the spoke dashboard also ships, so
// they need no session.
func (s *HubServer) handleActivityAsset(w http.ResponseWriter, r *http.Request) {
name := r.PathValue("name")
if !slices.Contains(trackerrow.Files, name) {
s.writeHubErrorPage(w, http.StatusNotFound)
return
}
body, err := fs.ReadFile(trackerrow.FS, name)
if err != nil {
s.writeHubErrorPage(w, http.StatusNotFound)
return
}
h := w.Header()
h.Set("Content-Type", "text/javascript; charset=utf-8")
h.Set("X-Content-Type-Options", "nosniff")
if webstatic.WriteCacheHeaders(w, r, webstatic.ETagFor(body)) {
return
}
_, _ = w.Write(body)
}

// registerActivityPageRoutes mounts the page and its row asset.
func (s *HubServer) registerActivityPageRoutes() {
s.mux.HandleFunc("GET "+activityPagePath, s.handleActivityPage)
s.mux.HandleFunc("GET "+activityAssetPrefix+"{name}", s.handleActivityAsset)
}
Loading
Loading