Skip to content

✨ feature(spoke): publish bounded activity digest from heartbeat - #16024

Merged
hivecommons-hive[bot] merged 4 commits into
v5from
scanner/fix-15963
Oct 31, 2026
Merged

hivecommons-hive[bot] merged 4 commits into
v5from
scanner/fix-15963

Conversation

@hivecommons-hive

@hivecommons-hive hivecommons-hive Bot commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

Closes #15963

Part of #15861 (hub-wide Activity Monitor RFC; remaining children #15964/#15965 track the hub aggregation and UI). Thanks to @hanthor for the RFC.

The hub side of the bounded activity digest (#16005) can only show what spokes send, and nothing populated the activity block yet. This makes the spoke publish it, built in process from the stage tracker it already keeps, so no extra GitHub calls or self-fetch are needed.

Per the owner decision on #15861, the digest rides the normal heartbeat, with an unchanged etag sending only the marker, plus coalesced activity-only updates (at most one per 15 s, with backpressure) on the same endpoint and bearer. #16005 only reads activity from a full heartbeat, so a small hub-side guard accepts the marked activity-only update for already-registered hives and touches nothing but the in-memory digest.

Scope: this is the spoke publisher plus the config surface. hub.activity.enabled defaults on only for hosted spokes; self-hosted stays opt-in. Nothing is activated or rolled out by this PR.

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88 requested_by=@hanthor

Dashboard import ratchet

pkg/dashboard now imports pkg/hubactivity (added to internal/testutil/dashboard_import_allowlist.txt). Justification: pkg/hubactivity is the leaf wire contract (ceilings, urgency order, sanitiser) shared by the spoke builder and hub re-validation; the dashboard builds the digest from its own stage tracker, so there is no existing seam that already carries these types without a circular import.

… coalesced updates

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Oct 31, 2026
@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 danathar 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
@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.

hive/awaiting-ci: pushed 86d6a16 raising the pkg/dashboard internal-import ratchet (56→57) for pkg/hubactivity — the only failure in the dashboard shards (TestDashboardInternalImportCountRatchet). CI pending — sweep will merge when green.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

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

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

Intent alignment (#15963) — approve, one advisory. Read at head 86d6a16.

The diff covers every bullet of #15963: in-process build from the memoised tracker (src/pkg/dashboard/hub_activity.go:46-66, no markServed so no SSE nudges, stage_tracker_build.go:808-815), cap/urgency/truncated via hubactivity.Build, etag-only marker once acked (src/pkg/hub/spoke/activity_publisher.go:150-158), 15 s coalesced updates with a 1-slot kick buffer (activity_publisher.go:176-203), hosted-default/self-hosted opt-in (src/pkg/config/hub_activity.go:33-42), changelog fragment, and @hanthor/#15861 attribution. The hub-side guard (src/pkg/hub/activity_update.go) is necessary for the acceptance criterion (a pre-#15963 hub 400s the activity_update body, activity_publisher.go:70-73), so not scope creep.

Advisory (in-scope, non-blocking): the issue says private-repository items are dropped, but the implementation defines "private" as not operator-declared public: Private: !public.allows(it.Repo) (src/pkg/dashboard/hub_activity.go:92), where publicRepos() is only HIVE_PUBLIC_REPOS plus project repos when hub.is_public is true (src/pkg/dashboard/battle_log.go:518-532). Consequence: a hosted spoke with the new default (enabled on) but hub.is_public: false and no HIVE_PUBLIC_REPOS publishes a digest with totals and zero items every beat, even for repos that are public on GitHub. This fails closed, and docs/telemetry.md documents it, so it is a defensible reading of the contract — flagging it so #15964/#15965 don't mistake empty rows for a hub bug.

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

docs-currency review of 86d6a16 (merge-base d8e1d41).

  1. hub.activity.* is a new operator-facing config surface with no Settings control and no parity allowlist entry — TestSettingsDialogReferencesEveryHiveYAMLLeaf will fail. src/pkg/config/hub_activity.go:12-25 adds hub.activity.enabled|max_items|share_private; src/internal/settingsparity/settingsparity.go:89-97 enumerates every yaml-tagged leaf, and src/pkg/dashboard/settings_parity_test.go:12-33 fails unless each leaf appears in pkg/dashboard/static/index.html / pkg/dashboard/**/*.go or in settings_parity_allowlist.txt. None of the dashboard files this PR touches mention hub.activity. and the allowlist is unchanged (line 319 still covers only hub.heartbeat_omit[]). Fix: add the three leaves to src/pkg/dashboard/settings_parity_allowlist.txt in the hub.* block with a yaml-only note pointing at docs/telemetry.md (same shape as github.notifications.mode on line 195), or add a Settings → Hub → Telemetry control.

  2. src/docs/telemetry.md inventory tables not updated for the new payload. The new "Activity digest" section is good, but (a) the Summary table's "Hub heartbeat" row (line 9) still lists what leaves the hive without PR/issue numbers, titles, author kind and stage pills, and its "Disable path" cell does not mention hub.activity.enabled: false; the page's own policy row says "Keep this page updated when heartbeat ... fields change" (line 29). (b) The hub.heartbeat_omit class table (repos row line 57, task_titles row line 60) lists withheld fields, but src/pkg/hub/spoke/activity_publisher.go:redactActivity now also drops digest items under repos and blanks digest titles under task_titles — only the prose in the new section says so. Add the activity fields to those three cells.

Verified against the code: the defaults, ceiling (hubactivity.MaxItemsCeiling=250), etag suppression (heartbeatDigestLocked) and 15 s coalescing described in telemetry.md and the hub-server.md heartbeat row match activity_publisher.go / hub/activity_update.go.

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

Style review (head 86d6a16, read the diff plus pkg/hub/server.go, pkg/hub/robots.go, pkg/hub/spoke/heartbeat.go, pkg/hubactivity, pkg/dashboard/server.go). No in-scope blocker; two maintainability advisories.

  1. Activity-update dispatch lives in a pre-mux middleware in robots.go, not in the heartbeat handler. Handler() now wraps the mux in activityUpdateGuard (src/pkg/hub/robots.go:141, src/pkg/hub/activity_update.go:23-31), so the fork for X-Hive-Activity-Update is invisible from handleHeartbeat (src/pkg/hub/server.go:1845) and from the route table (server.go:1711, which docs/api-reference/hub-server.md cites). The comment at robots.go:137-139 says tests normally serve s.mux directly; anything doing so sends a marked update into handleHeartbeat, which answers 400 "hive_id required" — exactly the status the spoke reads as "hub unsupported" and backs off for 10 minutes (src/pkg/hub/spoke/activity_publisher.go:218-224, :42-43). A two-line branch at the top of handleHeartbeat calling handleActivityUpdate would keep the route self-describing and drop the extra handler layer. Not blocking.

  2. Third copy of the heartbeat auth preamble. handleActivityUpdate (src/pkg/hub/activity_update.go:37-66) re-implements bearer capture → io.LimitReader body read → sanitizeHeartbeatField/isValidName → verifyHeartbeatBearer already present in handleHeartbeat (server.go:1854-1900) and handleTaskStatus (server.go:3699-3740). Consider a shared authenticateSpokeRequest(w, r) (hiveID string, body []byte, ok bool) helper so the next bearer-policy change lands once. Not blocking.

Otherwise the new code follows the package's idioms (package-level atomic.Pointer beside the existing heartbeat atomics in heartbeat.go:65-94; sync.Map keyed by *Server matches reviewQueueHistoryByServer in api_review_queue.go:30), the import ratchet bump is justified in-diff, and tests avoid time.Sleep via an injected clock.

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

Style review (read at head e150c77; diff plus pkg/dashboard/server.go, stage_tracker_build.go, pkg/hub/server.go around it). No in-scope blocker; two advisory maintainability notes.

  1. Package-level sync.Map keyed by *Server as a stand-in for a struct field — src/pkg/dashboard/hub_activity.go:21-40. OnStageTrackerPublish stores the hook in a global stageTrackerPublishHooks map keyed by the server pointer, "so the hook stays a pure addition". The Server struct already carries the sibling tracker state this hook belongs with (stageTrackerServed, stageTrackerNudge, stageTrackerCacheMu at server.go:159-179), there is no field-count ratchet forcing the side table, and the PR already edits stage_tracker_build.go:910-918 to call it. The side table is undiscoverable from the struct, has no precedent in pkg/dashboard, and pins every *Server that registered a hook until OnStageTrackerPublish(nil) is called (which main.go never does). Suggest a stageTrackerPublishHook atomic.Pointer[func()] field on Server (or a func() guarded by stageTrackerCacheMu, read before the unlock) and dropping the global.

  2. Duplicated heartbeat auth preamble — src/pkg/hub/activity_update.go:39-66 re-implements the bearer capture → body read → sanitizeHeartbeatField → isValidName → verifyHeartbeatBearer sequence from handleHeartbeat (src/pkg/hub/server.go:1854-1900), minus the audit comments that explain why the bearer is checked after the body is parsed. A shared authenticateHeartbeatRequest(w, r) (hiveID, body, ok) would keep the two paths from drifting; acceptable to defer, but worth noting since this is the security-sensitive bit of the hub.

Minor: docs/api-reference/hub-server.md:41 now documents the activity-only update under the /api/heartbeat row citing server.go:1711, while the behaviour actually lives in the activityUpdateGuard wrapper installed in robots.go:141; readers following the citation will not find it.

Evidence bundle `#16024e150c77` sha256:25234c2e476c7ea49ab317e85584fdedc133fa74d09a1daa84087fea58e5c81f — download from the dashboard or `hivectl review evidence #16024`.

@github-actions

github-actions Bot commented Oct 31, 2026 •

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.

PR Title Relation Files
#16032 🐛 Keep informational security notices separate from real human decision gates same files src/pkg/dashboard/stage_tracker_build.go

@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 added stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it and removed stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Oct 31, 2026
…wlist pkg/hubactivity import

TestAgentRuntimeConfigGolden: hub.activity is a non-pointer block so it
marshals as an empty object; record it in the golden (deliberate schema
change for #15963).

TestDashboardImportRatchet: pkg/dashboard builds the digest from its own
stage tracker and needs the shared wire contract in pkg/hubactivity (a
leaf package with no hive imports); allowlist it.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
@hivecommons-hive hivecommons-hive Bot added stage/050-review-pending Review swarm requested; awaiting a verdict for the current head and removed stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it labels Oct 31, 2026
@hivecommons-hive hivecommons-hive Bot added stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it and removed stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Oct 31, 2026
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
@hivecommons-hive hivecommons-hive Bot added stage/050-review-pending Review swarm requested; awaiting a verdict for the current head stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it and removed stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it 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.

Two CI failures on this head (86d6a16) are reproducible from the diff, not infra. Both look like small fixes; the design (digest riding the heartbeat, coalesced 15 s updates on the same bearer) reads correctly against heartbeat.go and the #16005 hub side.

1. pkg/hub/spoke hangs 20 min — test race in TestActivityUpdatesCoalesceToOnePer15sWithBackpressure (high, blocks merge)

CI goroutine dump: test parked at src/pkg/hub/spoke/activity_publisher_test.go:343 (<-waits), run parked at src/pkg/hub/spoke/activity_publisher.go:175 (case <-p.kick).

Mechanism: fire <- clock.Now() (test:338) is a synchronous handoff to run's <-p.after(wait). The test then calls p.notify() (test:342) immediately. If that kick lands before run reaches the non‑blocking drain at activity_publisher.go:186-189, the drain swallows it, update() runs the unchanged pass once and returns false, and run goes back to <-p.kick with nothing pending — so p.after is never called again and <-waits at test:343 blocks forever. The comment at test:339-341 ("receiving that wait also proves the unchanged pass has finished") assumes an ordering nothing enforces. Production code is fine (a kick merged into an in-progress pass is the intended behaviour); the test needs a sync point that the unchanged update() pass has completed before the final notify() — e.g. a test-only post-update hook on activityPublisher, or have rec.post/build signal completion. It failed in both test (rest 1/4) jobs on this run, so it is not a flake.

2. TestSettingsDialogReferencesEveryHiveYAMLLeaf fails (medium)

settings_parity_test.go:33: hub.activity.enabled, hub.activity.max_items, hub.activity.share_private (from src/pkg/config/hub_activity.go:17-23, wired at config.go:4436) are neither referenced by the Settings UI nor listed in src/pkg/dashboard/settings_parity_allowlist.txt. Either add a Settings UI reference or allowlist the three leaves with a reason.

Verified OK: pkg/hubactivity already exists at the merge base (d8e1d41), so the import-allowlist/ratchet bump to 57 is just bookkeeping; stageTrackerPayloadFrom(..., markServed=false) correctly avoids counting the in-process reader as a served client.

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

…wlist hub.activity settings

TestActivityUpdatesCoalesceToOnePer15sWithBackpressure raced: a notify
sent right after the timer fired could be swallowed by run's kick drain
ahead of the unchanged pass, leaving the test blocked on waits until the
20m package timeout (test (rest 1/4) on #16024). Observe each digest
build and only notify once the drain is past.

Allowlist hub.activity.{enabled,max_items,share_private} for the
Settings parity guard; they are yaml-only like hub.heartbeat_omit.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>

@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.

Read the hub receiver, the spoke publisher and the heartbeat integration against the tree at 86d6a16; the trust-boundary parts look correct to me.

Verified:

  • src/pkg/hub/activity_update.go:38-83 mirrors handleHeartbeat (server.go:1845-1900) step for step: bearer captured → body LimitReader(maxPayloadBytes) → sanitizeHeartbeatField + isValidName on the claimed hive_id → verifyHeartbeatBearer bound to that id → signed HeartbeatResponse. It additionally refuses unregistered hives (404), so an update cannot create registry state. /api/heartbeat is registered bare at server.go:1711, so routing the marked request ahead of the mux in Handler() bypasses no middleware.
  • Spoke side (activity_publisher.go:298-340) sends only the hubactivity.Digest, applies hub.heartbeat_omit via redactActivity and re-stamps the etag, and rejects an unsigned/invalid hub response before applying the ack. Cadence is coalesced to ≥15 s (run, line 173) with a backoff when the hub predates #15963.
  • heartbeat.go holds pub.mu across the full beat (and update() across its POST) so a beat and an out-of-band update cannot interleave their acks — deliberate per the comment, and bounded by heartbeatTimeout (10 s), so worst case a beat waits ≤10 s behind an update. Not a defect, just noting the serialization is intentional.

I did not read pkg/dashboard/hub_activity.go (the tracker-side source) in the same depth.

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

@hivecommons-hive hivecommons-hive Bot added stage/050-review-pending Review swarm requested; awaiting a verdict for the current head and removed stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it labels Oct 31, 2026
@hivecommons-hive
hivecommons-hive Bot merged commit 26754b1 into v5 Oct 31, 2026
81 of 84 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the scanner/fix-15963 branch October 31, 2026 13:31
@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

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. role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. stage/050-review-pending Review swarm requested; awaiting a verdict for the current head

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[scanner] Publish the bounded activity digest from the spoke heartbeat with coalesced 15 s change updates

0 participants