Skip to content

✨ feature(hub): bounded activity digest contract and per-user /api/hub/activity - #16005

Merged
hivecommons-hive[bot] merged 3 commits into
v5from
hive/adopt-16001
Oct 31, 2026
Merged

hivecommons-hive[bot] merged 3 commits into
v5from
hive/adopt-16001

Conversation

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Supersedes #16001 (adopted in place, re-homed because a hive commit on the contributor branch cannot carry a squash-safe sign-off; original commits by @Karibhou preserved).

Closes #15951

This branch is #16001's head 51bd49a88b1b as pushed by @Karibhou (fork Karibhou/hive), unchanged. Last lane reason on the original: reviewer-verdict:changes_requested.

Hive fix agent: rebase this branch on v5, fix the failing checks / review asks, and push to THIS branch. Keep the original author's commits and their Signed-off-by; add your own sign-off on your commits. Do not open another PR.

Sign-off attribution: the original PR would squash the App's signed fixes as the contributor. This App-authored superseder keeps every original commit and sign-off unchanged and attributes the squash to the App instead. DCO and all merge gates still apply here.

Karibhou and others added 2 commits October 31, 2026 05:38
…b/activity

First implementation slice of the hub-wide Activity Monitor (RFC #15861 by
@hanthor, child #15951):

- pkg/hubactivity: shared wire contract for the heartbeat `activity` block.
  Build caps items at 100 by default under a hard 250-item ceiling, orders
  by urgency (needs-human/needs-decision, stalled, furthest stage, oldest),
  drops private-repo items unless the spoke opts in while still counting
  them in totals, and stamps a content etag independent of generated_at.
  Sanitize re-applies every bound on the hub: owner/name repos only,
  closed kind/author_kind sets, slug-only stage/mods, deduped repo#n rows,
  clamped integers, control/format/separator characters stripped from
  titles.
- Hub: the digest rides the existing per-hive heartbeat bearer, is
  sanitized and kept in memory only (leaf-locked activityStore, never in
  the persisted registry, forgotten after 24h of silence), and the beat
  response acknowledges the held etag (activity_etag) so a spoke can send
  an unchanged marker.
- GET /api/hub/activity (signed-in users): per-user/per-hive authorization
  before any block is read (admins all hives; others owned or unexpired
  granted hives), merged items tagged with hive_id, per-hive ok / stale /
  not_reporting / missing disclosure, digest and response truncation
  counts, bounded filters, ETag + If-None-Match polling, private no-cache.
- Spoke payload/response carry the optional fields; nothing populates the
  digest yet (#15963). No rollout, participation or broadcast setting
  changes.

Hive-Run: #15861
Hive-Plan: rfc-15861 decomposition, child 1 (#15951)
Hive-Spec: rfc-15861#A-B-C
Signed-off-by: Karibhou <157208370+Karibhou@users.noreply.github.com>
…i/hub/activity

The new activityStore field and /api/hub/activity registration in
pkg/hub/server.go shifted every cited line in the hub-server API reference,
so the changelog-fragment-guard citation check failed. Re-run the citation
fixer and align the documented Vary header with what the handler sets.

Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign hanthor for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Oct 31, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

No conflicting open PRs or same-file overlaps were found.

@hivecommons-hive hivecommons-hive Bot added author/hive This repository's own hive (the App or one of its agent lanes) authored this PR dco All commits are DCO signed-off role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Oct 31, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Conclusion: the Go change reads correct to me against v5 and does what #15951 scopes; CI is green at 51bd49a. One housekeeping gap in the PR body, no code findings.

What I verified (read src/pkg/hub/activity.go, src/pkg/hubactivity/hubactivity.go, the heartbeat/server wiring, and saas_hives_api.go at head)

  • Authorization before data. handleHubActivity is mounted behind requireAuth (src/pkg/hub/server.go:1728), resolves the visible hive set first (activity.go:346), and only then copies those hives' blocks out of the store (activityStore.snapshot, activity.go:128-138). The rule in visibleActivityHives (activity.go:154-183: hub admin → all; else owner or unexpired grant) matches buildMyHivesResponse (saas_hives_api.go:1332-1348) and is slightly stricter, since it also drops expired grants via accessGrantExpired.
  • Bounded. Sanitize (hubactivity.go:158-182) dedups by repo#n, truncates at MaxItemsCeiling (250) with overflow counted into Truncated, and clamps every integer and map; the merged response is further capped at 8 × 250 (activity.go:42,313-316). Filter values are bounded to 200 valid-UTF-8 runes (activity.go:205).
  • Memory only. HubServer.activity is a struct field never written to the registry (server.go:1002); record is called after s.mu is released (server.go:2737), consistent with the "leaf lock" comment at activity.go:62-63. Hives not refreshed for 24h are forgotten (activity.go:118-124).
  • Handshake. Unchanged marker compares against CleanETag of the stored form (activity.go:91) so an etag altered by sanitizing cannot wedge the spoke into re-sending forever; ActivityETag is returned on every beat (server.go:2826).
  • Private items. The hub-side Sanitize keeps Private items; exclusion happens in the spoke-side Build unless SharePrivate (hubactivity.go:133). That is what #15951 asks for ("private-item exclusion in the digest builder") — noting it so nobody expects the hub to re-filter.
  • ETag/caching. Cache-Control: private, no-cache + Vary: Cookie, Authorization (activity.go:362-363) — appropriate for per-user bodies.

Gap in the body (not code): #15951 inherits from RFC #15861 the requirement to "mention @hanthor in every implementation child and PR" and link the RFC. #16001's body did; this superseder's body links neither @hanthor nor #15861. Worth adding before merge so the attribution trail survives the squash.

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive

hivecommons-hive Bot commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor Author

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

Review findings from reviewer-2 (folded here because this head already carries its hive review):

Read against v5 at 51bd49a: the hub side of this looks correct to me. One contract edge below is worth pinning down before the spoke publisher (#15963) is written; it is not a defect in this diff.

What I verified in the tree (not from the body):

  • Store is written only after the beat is authenticated. handleHeartbeat rejects on verifyHeartbeatBearer(presentedBearer, payload.HiveID) (src/pkg/hub/server.go:~1897) long before s.activity.record(payload.HiveID, …) runs (:2737), and record is called after s.mu.Unlock() — so activityStore.mu really is a leaf lock as the comment claims. snapshot in handleHubActivity likewise runs after s.mu.RUnlock() (src/pkg/hub/activity.go:329-342).
  • Visibility rule matches My Hives, and is slightly stricter. visibleActivityHives (activity.go:150-180) admits admin / canonical owner / granted, the same three gates as buildMyHivesResponse (src/pkg/hub/saas_hives_api.go:747-777). The activity view additionally checks accessGrantExpired inline (activity.go:162), whereas My Hives only loses expired grants when pruneExpiredHiveGrants sweeps (access_expiry.go:64). Stricter in the safe direction; fine.
  • Authorization precedes data access. snapshot(ids) copies only the authorized hives' blocks (activity.go:124-134), so another hive's digest never enters the body or the ETag. Cache-Control: private, no-cache + Vary: Cookie, Authorization are right for a per-user body.
  • Filters are bounded (parseActivityFilter, 200 runes, UTF-8 checked) and f.Hive is applied to both items and the hives[] list, so a hive filter cannot leak items from a sibling hive.
  • Marker handshake after hub restart — empty store → record returns "" → spoke sends the full digest next beat. Comparison is on CleanETag in stored form, so a marker whose etag changes under cleaning cannot wedge.

Low — a full digest with zero items is indistinguishable from an "unchanged" marker unless Totals is non-nil. IsUnchangedMarker (src/pkg/hubactivity/hubactivity.go:104-106) is ETag != "" && Totals == nil && len(Items)==0 && Truncated==0. If a quiet spoke ever sends a full digest with no items and omits Totals, record (activity.go:86-97) treats it as a marker, finds no held etag, returns "", and never stores it — the spoke then resends the same full digest every beat and the hive stays not_reporting forever. The Digest doc (hubactivity.go:90-92) implies full digests carry Totals, but nothing enforces it. Suggest either stating "a full digest must always set Totals, even all-zero" in that doc for #15963, or having Sanitize fill an empty Totals{} when Items/Truncated are present. Suggestion, not a blocker.

Not approving (that is a human's signature); recording the verdict with the hive.

Review findings from reviewer (folded here because this head already carries its hive review):

Read the new packages against the tree at 97270f4; this looks correct to me.

What I verified, not inferred:

  • Authorization before aggregation. pkg/hub/activity.go visibleActivityHives applies the same owner/grant/admin rule as buildMyHivesResponse (pkg/hub/saas_hives_api.go:747-775) and is stricter: it drops grants where accessGrantExpired (pkg/hub/access_expiry.go:48) is true, which My Hives does not check in that loop. activityStore.snapshot only copies the IDs that survived, so another user's hive never enters the body or the ETag.
  • Lock ordering. s.activity.record(...) runs after s.mu.Unlock() in handleHeartbeat (pkg/hub/server.go:2737), and snapshot is called after s.mu.RUnlock() in handleHubActivity — the "leaf lock" comment holds. The unchanged-marker branch mutates a copy of storedActivity and never the shared *Totals, so views marshalling that pointer are race-free.
  • Bounds. The heartbeat body is already capped at maxPayloadBytes (1 MiB, pkg/hub/server.go:126); Sanitize re-applies the 250-item ceiling, token/title rune caps and clampCount on every spoke-supplied integer. The response cap 8 * MaxItemsCeiling = 2000 matches the "cap 2000" the docs state.
  • Freshness constant. activityHeartbeatInterval = 2m matches heartbeatSendInterval at pkg/dashboard/server.go:3263.
  • Docs. scripts/check-api-reference-citations.sh passes on this head; go build ./pkg/hubactivity/ ./pkg/hub/ ./pkg/hub/spoke/ compiles.

Body claims ("nothing populates the digest yet", memory-only, no participation change) match the diff: spoke.HeartbeatPayload.Activity is declared but never assigned, and activityStore is not part of Registry.

One non-blocking observation: forgetOldLocked only runs inside record, so a hub that receives no heartbeats at all keeps blocks past 24h — harmless, since the view already marks them stale.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

docs-currency review (head 97270f4)

Docs check out: src/docs/api-reference/hub-server.md:49 matches the handler in src/pkg/hub/activity.go (status values :49-54, 2000-item response cap :42 = 8×MaxItemsCeiling 250, ≤200-rune filters :45/:194, private, no-cache + Vary :340-341, 401 via requireAuth in saas_auth.go:29-35), item field names match src/pkg/hubactivity/hubactivity.go:67-79, and the re-numbered pkg/hub/server.go citations (:1711, :1720, :1731 …) are correct at head.

One advisory, per #15951's attribution requirement ("mention @hanthor in every implementation child and PR"): the superseded #16001 body carried the mention, but this PR's body does not. Add the RFC #15861 / #15951 attribution line (with the proposer's handle) to the PR body before merge so the squash commit carries it.

— hive: agent=adjudicator-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive
hivecommons-hive Bot merged commit 7a9c209 into v5 Oct 31, 2026
74 of 75 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the hive/adopt-16001 branch October 31, 2026 10:19
@hivecommons-hive

Copy link
Copy Markdown
Contributor Author
Evidence bundle `#1600597270f4` sha256:7b40d91395e7a9df94e30493445dbeaca1465d7a6546f9a5f3f515ed63d373b3 — download from the dashboard or `hivectl review evidence #16005`.

@github-actions

Copy link
Copy Markdown
Contributor

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback

@hivecommons-hive hivecommons-hive Bot removed role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Oct 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author/hive This repository's own hive (the App or one of its agent lanes) authored this PR copilot dco All commits are DCO signed-off dco-signoff: yes Indicates the PR's author has signed the DCO. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

✨ Bounded activity heartbeat contract and authorized hub aggregation API

1 participant