From 7746f4d770ba0367e3883be8a0bb5f9f874c6667 Mon Sep 17 00:00:00 2001 From: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Sat, 31 Oct 2026 07:19:04 -0400 Subject: [PATCH 1/4] =?UTF-8?q?=E2=9C=A8=20feature(spoke):=20publish=20bou?= =?UTF-8?q?nded=20activity=20digest=20from=20heartbeat=20with=20coalesced?= =?UTF-8?q?=20updates?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- .../added-15963-spoke-activity-digest.md | 1 + src/cmd/hive/boot_heartbeat_deps_test.go | 23 +- src/cmd/hive/main.go | 26 +- src/docs/api-reference/hub-server.md | 2 +- src/docs/telemetry.md | 14 + src/pkg/config/config.go | 3 + src/pkg/config/hub_activity.go | 42 ++ src/pkg/config/hub_activity_test.go | 53 ++ src/pkg/dashboard/hub_activity.go | 96 +++ src/pkg/dashboard/hub_activity_test.go | 111 ++++ src/pkg/dashboard/stage_tracker_build.go | 12 +- src/pkg/hub/activity_update.go | 97 +++ src/pkg/hub/activity_update_test.go | 150 +++++ src/pkg/hub/robots.go | 5 +- src/pkg/hub/spoke/activity_publisher.go | 341 +++++++++++ src/pkg/hub/spoke/activity_publisher_test.go | 561 ++++++++++++++++++ src/pkg/hub/spoke/heartbeat.go | 30 +- 17 files changed, 1557 insertions(+), 10 deletions(-) create mode 100644 changelog.d/added-15963-spoke-activity-digest.md create mode 100644 src/pkg/config/hub_activity.go create mode 100644 src/pkg/config/hub_activity_test.go create mode 100644 src/pkg/dashboard/hub_activity.go create mode 100644 src/pkg/dashboard/hub_activity_test.go create mode 100644 src/pkg/hub/activity_update.go create mode 100644 src/pkg/hub/activity_update_test.go create mode 100644 src/pkg/hub/spoke/activity_publisher.go create mode 100644 src/pkg/hub/spoke/activity_publisher_test.go diff --git a/changelog.d/added-15963-spoke-activity-digest.md b/changelog.d/added-15963-spoke-activity-digest.md new file mode 100644 index 0000000000..9146dd7ba5 --- /dev/null +++ b/changelog.d/added-15963-spoke-activity-digest.md @@ -0,0 +1 @@ +- Spokes now publish the bounded activity digest to the hub: each heartbeat carries it, built in process from the stage tracker, with up to `hub.activity.max_items` items (default 100, hub ceiling 250). When the cap applies, the most urgent items are kept and `truncated` reports how many were left out. Private-repository items are left out unless `hub.activity.share_private` is set, but totals still count them. Once the hub acknowledges an etag, later beats send only that etag. A tracker change sends an activity-only update on the heartbeat endpoint at most once every 15 seconds, and changes that arrive meanwhile are merged into it. `hub.activity.enabled` defaults on for hosted spokes and stays opt-in for self-hosted ones ([#15963](https://github.com/hivecommons/hive/issues/15963), RFC [#15861](https://github.com/hivecommons/hive/issues/15861)). diff --git a/src/cmd/hive/boot_heartbeat_deps_test.go b/src/cmd/hive/boot_heartbeat_deps_test.go index 1447cebd4f..798f4964b6 100644 --- a/src/cmd/hive/boot_heartbeat_deps_test.go +++ b/src/cmd/hive/boot_heartbeat_deps_test.go @@ -181,9 +181,26 @@ func TestBootHeartbeatWith_PublishesIdentityBeforeTheLoopAndWiresEveryCallback(t heartbeatCallback[spoke.ClusterIDCallback](t, f) heartbeatCallback[spoke.FreshStatusCollector](t, f) heartbeatCallback[spoke.UpgradeAnnounceCallback](t, f) - if len(f.callbacks) != 15 { - t.Fatalf("registered %d callbacks, want 15 (one of each)", len(f.callbacks)) - } + activity := heartbeatCallback[spoke.ActivitySource](t, f) + if len(f.callbacks) != 16 { + t.Fatalf("registered %d callbacks, want 16 (one of each)", len(f.callbacks)) + } + // hub.activity is self-hosted opt-in: this config is not hosted, so the + // digest stays off until the operator enables it, and the options are + // read per build so a reload applies without restarting the loop. + if opts := activity.Options(); opts.Enabled { + t.Fatalf("self-hosted activity options = %+v, want disabled by default", opts) + } + on := true + cfg.Hub.Activity = config.HubActivityConfig{Enabled: &on, MaxItems: 40, SharePrivate: true} + if opts := activity.Options(); !opts.Enabled || opts.MaxItems != 40 || !opts.SharePrivate { + t.Fatalf("opted-in activity options = %+v, want enabled with the configured cap and share_private", opts) + } + if items, ok := activity.Items(context.Background()); ok || items != nil { + t.Fatalf("activity items before any status = %v, %v; want none", items, ok) + } + activity.Subscribe(func() {}) + activity.Subscribe(nil) // The collector honours a runtime hub.enabled=false without being torn // down: it returns nil so StartHeartbeat skips the beat. diff --git a/src/cmd/hive/main.go b/src/cmd/hive/main.go index 95bb09c5a8..207bf617db 100644 --- a/src/cmd/hive/main.go +++ b/src/cmd/hive/main.go @@ -52,6 +52,7 @@ import ( "github.com/hivecommons/hive/pkg/hooks" "github.com/hivecommons/hive/pkg/hub" spoke "github.com/hivecommons/hive/pkg/hub/spoke" + "github.com/hivecommons/hive/pkg/hubactivity" "github.com/hivecommons/hive/pkg/intent" "github.com/hivecommons/hive/pkg/ioscan" "github.com/hivecommons/hive/pkg/jev" @@ -5667,7 +5668,30 @@ func (b *boot) bootHeartbeatWith(deps bootHeartbeatDeps) { RepoTargetMisconfigured: b.repoTargetMisconfigured(), RepoTargetIssue: b.repoTargetIssueMessage(), } - })) + }), + // Hub-wide activity digest (#15963): built from the dashboard's + // memoised stage tracker; tracker publishes trigger coalesced + // activity-only updates. hub.activity is read per build. + spoke.ActivitySource{ + Options: func() spoke.ActivityOptions { + return spoke.ActivityOptions{ + Enabled: b.cfg.Hub.Enabled && b.cfg.Hub.ActivityEnabled(), + MaxItems: b.cfg.Hub.Activity.MaxItems, + SharePrivate: b.cfg.Hub.Activity.SharePrivate, + } + }, + Items: func(ctx context.Context) ([]hubactivity.Item, bool) { + if b.dashSrv == nil { + return nil, false + } + return b.dashSrv.HubActivityItems(ctx) + }, + Subscribe: func(notify func()) { + if b.dashSrv != nil { + b.dashSrv.OnStageTrackerPublish(notify) + } + }, + }) if b.cfg.Hub.TaskStatusPushEnabled() { deps.startTaskStatusPush(b.ctx, b.hubURL, func() *spoke.TaskStatusPayload { diff --git a/src/docs/api-reference/hub-server.md b/src/docs/api-reference/hub-server.md index 1d60681c1b..ab623d6bee 100644 --- a/src/docs/api-reference/hub-server.md +++ b/src/docs/api-reference/hub-server.md @@ -38,7 +38,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `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` | -| `POST` | `/api/heartbeat` | Hub handler-specific | Heartbeat | `pkg/hub/server.go:1711` | +| `POST` | `/api/heartbeat` | Hub handler-specific | Heartbeat. A request carrying `X-Hive-Activity-Update` is an activity-only update ([#15963](https://github.com/hivecommons/hive/issues/15963)): body `{"activity_update":{"hive_id","activity"}}`, the same per-hive bearer, accepted only for a hive already in the registry (`404` otherwise); it replaces the in-memory activity digest and nothing else, and the signed response carries `ok` and `activity_etag` | `pkg/hub/server.go:1711` | | `POST` | `/api/task-status` | Hub handler-specific | Task Status | `pkg/hub/server.go:1712` | | `GET` | `/api/registry` | Hub handler-specific | Registry | `pkg/hub/server.go:1720` | | `GET` | `/api/hub/leaderboard` | Hub handler-specific | Leaderboard | `pkg/hub/server.go:1721` | diff --git a/src/docs/telemetry.md b/src/docs/telemetry.md index 7a2be84e1c..ce3713ab55 100644 --- a/src/docs/telemetry.md +++ b/src/docs/telemetry.md @@ -60,6 +60,20 @@ hub: | `task_titles` | Leaderboard `current_task` | Hub leaderboard shows who is active but not what they are working on. | | `dashboard_urls` | `dashboard_url`, `snapshot_url`, public-URL self-check | Hub cannot link to the hive's dashboard or snapshot, and cannot probe URL reachability. | +## Activity digest + +`hub.activity` controls the bounded, read-only activity digest the heartbeat carries for the hub-wide Activity Monitor ([#15963](https://github.com/hivecommons/hive/issues/15963), RFC [#15861](https://github.com/hivecommons/hive/issues/15861)). It is built in process from the dashboard's stage tracker: repo, number, kind, title, author kind, stage and modifier pills of open items, plus totals by stage and modifier. + +```yaml +hub: + activity: + enabled: true # default: on for hosted spokes (hub.hive_type: hosted) not withholding repos; off for self-hosted + max_items: 100 # default 100; clamped to the hub's 250-item ceiling + share_private: false # private-repository items are dropped (still counted in totals) unless true +``` + +When the cap applies, items needing a human or a decision are kept first, then stalled ones, then the furthest stage, and the number left out is reported as `truncated`. A repository counts as public only when the hub lists the hive as public (`hub.is_public`, its project repos) or it is on `HIVE_PUBLIC_REPOS`. Once the hub acknowledges a digest's etag, later beats send only `etag` and `generated_at` until the tracker changes. A tracker change also sends an activity-only update over the heartbeat endpoint and bearer, at most one every 15 seconds; changes arriving meanwhile are merged into it. `hub.heartbeat_omit` applies: `repos` withholds every item (totals remain) and `task_titles` blanks titles. + ## Telemetry agent The telemetry agent audits and, once opted in, improves the **observability of the managed project** — the repositories the hive watches, not the hive's own internal metrics/tracing (see [Config.OTel/Tracing](operator-reference.md) for that, a deliberately separate concern). It is an L5/L6-only agent: absent from the roster below L5 and paused in every governor mode at L5/L6 until an operator explicitly opts in. diff --git a/src/pkg/config/config.go b/src/pkg/config/config.go index c2089268c7..86131724c4 100644 --- a/src/pkg/config/config.go +++ b/src/pkg/config/config.go @@ -4431,6 +4431,9 @@ type HubConfig struct { // dashboard_urls. Upgrade/config delivery is unaffected. See // docs/telemetry.md and HeartbeatOmitClasses. HeartbeatOmit []string `yaml:"heartbeat_omit,omitempty" json:"heartbeat_omit,omitempty"` + // Activity configures the bounded activity digest published to the hub + // with the heartbeat (#15963). See HubActivityConfig and ActivityEnabled. + Activity HubActivityConfig `yaml:"activity,omitempty" json:"activity,omitempty"` // ContributeWallEnabled opts a hive into the public contributor wall on // /contribute. Default false so no deployment gets a public posting surface // without an operator decision. diff --git a/src/pkg/config/hub_activity.go b/src/pkg/config/hub_activity.go new file mode 100644 index 0000000000..094a9a41bf --- /dev/null +++ b/src/pkg/config/hub_activity.go @@ -0,0 +1,42 @@ +package config + +import ( + "slices" + "strings" +) + +// HubActivityConfig is the hub.activity block: the bounded, read-only +// activity digest a spoke attaches to its hub heartbeat for the hub-wide +// Activity Monitor (RFC hivecommons/hive#15861, #15963). The wire contract +// and its ceilings live in pkg/hubactivity. +type HubActivityConfig struct { + // Enabled publishes the digest. A POINTER so an absent value means "use + // the default": ON for a hosted spoke (hub.hive_type: hosted) whose + // hub.heartbeat_omit does not withhold repos, OFF for every self-hosted + // or standalone install. Resolve with HubConfig.ActivityEnabled. + Enabled *bool `yaml:"enabled,omitempty" json:"enabled,omitempty"` + // MaxItems caps the items in one digest. 0/unset means 100; values above + // the hub's finite ceiling (hubactivity.MaxItemsCeiling, 250) are clamped. + MaxItems int `yaml:"max_items,omitempty" json:"max_items,omitempty"` + // SharePrivate keeps items from private repositories in the digest. + // Default false: they are dropped but still counted in totals. + SharePrivate bool `yaml:"share_private,omitempty" json:"share_private,omitempty"` +} + +// ActivityEnabled reports whether this spoke publishes its activity digest. +// +// An explicit hub.activity.enabled always wins. Otherwise the digest is on +// only for a hosted spoke, whose hub already operates the hive, and only +// when hub.heartbeat_omit does not withhold repos: a digest names +// repositories, so an operator who withheld them from the heartbeat has not +// agreed to share them here either. Self-hosted spokes stay opt-in. +func (h HubConfig) ActivityEnabled() bool { + if h.Activity.Enabled != nil { + return *h.Activity.Enabled + } + if !strings.EqualFold(strings.TrimSpace(h.HiveType), HiveTypeHosted) { + return false + } + omit, err := HeartbeatOmitClasses(h.HeartbeatOmit) + return err == nil && !slices.Contains(omit, HeartbeatOmitRepos) +} diff --git a/src/pkg/config/hub_activity_test.go b/src/pkg/config/hub_activity_test.go new file mode 100644 index 0000000000..5e6ff46440 --- /dev/null +++ b/src/pkg/config/hub_activity_test.go @@ -0,0 +1,53 @@ +package config + +import ( + "testing" + + "gopkg.in/yaml.v3" +) + +func TestHubActivityEnabledDefaults(t *testing.T) { + on, off := true, false + for _, tc := range []struct { + name string + hub HubConfig + want bool + }{ + {"self-hosted defaults off", HubConfig{}, false}, + {"local hive type defaults off", HubConfig{HiveType: "local"}, false}, + {"hosted spoke defaults on", HubConfig{HiveType: HiveTypeHosted}, true}, + {"hosted match is case and space insensitive", HubConfig{HiveType: " Hosted "}, true}, + {"hosted withholding repos defaults off", HubConfig{HiveType: HiveTypeHosted, HeartbeatOmit: []string{"users", "repos"}}, false}, + {"hosted withholding other classes stays on", HubConfig{HiveType: HiveTypeHosted, HeartbeatOmit: []string{"users", "task_titles"}}, true}, + {"hosted with an invalid omit list fails closed", HubConfig{HiveType: HiveTypeHosted, HeartbeatOmit: []string{"bogus"}}, false}, + {"self-hosted explicit opt-in", HubConfig{Activity: HubActivityConfig{Enabled: &on}}, true}, + {"hosted explicit opt-out", HubConfig{HiveType: HiveTypeHosted, Activity: HubActivityConfig{Enabled: &off}}, false}, + {"explicit opt-in wins over withheld repos", HubConfig{HeartbeatOmit: []string{"repos"}, Activity: HubActivityConfig{Enabled: &on}}, true}, + } { + t.Run(tc.name, func(t *testing.T) { + if got := tc.hub.ActivityEnabled(); got != tc.want { + t.Fatalf("ActivityEnabled() = %v, want %v", got, tc.want) + } + }) + } +} + +func TestHubActivityConfigYAMLKeys(t *testing.T) { + var cfg Config + src := "hub:\n activity:\n enabled: true\n max_items: 40\n share_private: true\n" + if err := yaml.Unmarshal([]byte(src), &cfg); err != nil { + t.Fatal(err) + } + a := cfg.Hub.Activity + if a.Enabled == nil || !*a.Enabled || a.MaxItems != 40 || !a.SharePrivate { + t.Fatalf("hub.activity decoded as %+v", a) + } + + var empty Config + if err := yaml.Unmarshal([]byte("hub:\n url: https://hub.example.test\n"), &empty); err != nil { + t.Fatal(err) + } + if empty.Hub.Activity.Enabled != nil || empty.Hub.Activity.MaxItems != 0 || empty.Hub.Activity.SharePrivate { + t.Fatalf("absent hub.activity must stay unset, got %+v", empty.Hub.Activity) + } +} diff --git a/src/pkg/dashboard/hub_activity.go b/src/pkg/dashboard/hub_activity.go new file mode 100644 index 0000000000..ed575d880a --- /dev/null +++ b/src/pkg/dashboard/hub_activity.go @@ -0,0 +1,96 @@ +package dashboard + +import ( + "context" + "encoding/json" + "slices" + "sync" + "time" + + "github.com/hivecommons/hive/pkg/hubactivity" +) + +// Hub activity digest source (RFC hivecommons/hive#15861, #15963). The +// spoke's heartbeat builds its bounded activity digest from the stage +// tracker this server already memoises: no HTTP self-fetch and no GitHub +// call of its own. + +// stageTrackerPublishHooks maps a *Server to the hook run on every tracker +// invalidation (status publish or webhook re-read). Kept beside the Server +// rather than in it so the hook stays a pure addition. +var stageTrackerPublishHooks sync.Map + +// OnStageTrackerPublish registers fn to run on every tracker publish, +// replacing any earlier hook; nil removes it. fn runs on the publish and +// webhook paths and must not block. +func (s *Server) OnStageTrackerPublish(fn func()) { + if s == nil { + return + } + if fn == nil { + stageTrackerPublishHooks.Delete(s) + return + } + stageTrackerPublishHooks.Store(s, fn) +} + +func (s *Server) notifyStageTrackerPublish() { + if v, ok := stageTrackerPublishHooks.Load(s); ok { + v.(func())() + } +} + +// HubActivityItems returns every tracked item as a hub activity row, with +// Private set unless the repo is known public (hub.is_public project repos +// or HIVE_PUBLIC_REPOS, the same set the Battle Log trusts). ok is false +// while the spoke has no status or the tracker cannot be built. Reading +// does not count as a tracker client, so it adds no SSE nudges. +func (s *Server) HubActivityItems(ctx context.Context) ([]hubactivity.Item, bool) { + if s == nil { + return nil, false + } + s.statusMu.RLock() + status := s.status + s.statusMu.RUnlock() + if status == nil { + return nil, false + } + body, _, _, _ := s.stageTrackerPayloadFrom(ctx, status, time.Now().UTC(), false) + if body == nil { + return nil, false + } + var tracker struct { + Items []StageTrackerItem `json:"items"` + } + if err := json.Unmarshal(body, &tracker); err != nil { + return nil, false + } + return hubActivityItems(tracker.Items, s.publicRepos()), true +} + +// hubActivityItems maps tracker rows to digest rows. A row the tracker +// flags NeedsHuman (a stage-only human wait such as ready-for-human-merge +// included) carries the needs-human modifier so the digest's urgency order +// matches the tracker's "Needs attention". +func hubActivityItems(items []StageTrackerItem, public publicRepoSet) []hubactivity.Item { + out := make([]hubactivity.Item, 0, len(items)) + for _, it := range items { + mods := slices.Clone(it.Modifiers) + if it.NeedsHuman && !slices.Contains(mods, hubactivity.ModNeedsHuman) && !slices.Contains(mods, hubactivity.ModNeedsDecision) { + mods = append([]string{hubactivity.ModNeedsHuman}, mods...) + } + out = append(out, hubactivity.Item{ + Repo: it.Repo, + Number: it.Number, + Kind: it.Kind, + Title: it.Title, + AuthorKind: it.AuthorKind, + Stage: it.StageSlug, + StageNumber: it.Stage, + Since: it.StageSince, + Mods: mods, + Private: !public.allows(it.Repo), + }) + } + return out +} diff --git a/src/pkg/dashboard/hub_activity_test.go b/src/pkg/dashboard/hub_activity_test.go new file mode 100644 index 0000000000..0542c96fe6 --- /dev/null +++ b/src/pkg/dashboard/hub_activity_test.go @@ -0,0 +1,111 @@ +package dashboard + +import ( + "context" + "slices" + "testing" + "time" + + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/hubactivity" + "github.com/hivecommons/hive/pkg/stagelabels" +) + +func TestHubActivityItemsMapsTrackerRows(t *testing.T) { + since := time.Date(2026, 10, 31, 8, 0, 0, 0, time.UTC) + rows := []StageTrackerItem{ + {Repo: "acme/widget", Number: 1, Kind: "pr", Title: "Ship it", AuthorKind: "human", Stage: 90, StageSlug: "ready-for-human-merge", StageSince: &since, NeedsHuman: true, Modifiers: []string{"hold"}}, + {Repo: "acme/widget", Number: 2, Kind: "issue", Title: "Decide", NeedsHuman: true, Modifiers: []string{"needs-decision"}}, + {Repo: "acme/secret", Number: 3, Kind: "pr", Title: "Hidden", Modifiers: []string{"stalled"}}, + } + got := hubActivityItems(rows, publicRepoSet{"acme/widget": true}) + if len(got) != 3 { + t.Fatalf("mapped %d rows, want 3", len(got)) + } + first := got[0] + if first.Repo != "acme/widget" || first.Number != 1 || first.Kind != "pr" || first.Title != "Ship it" || first.AuthorKind != "human" || + first.Stage != "ready-for-human-merge" || first.StageNumber != 90 || first.Since == nil || !first.Since.Equal(since) || first.Private { + t.Fatalf("row 1 = %+v", first) + } + if !slices.Equal(first.Mods, []string{hubactivity.ModNeedsHuman, "hold"}) { + t.Fatalf("a NeedsHuman row's mods = %v, want needs-human first so urgency ordering sees it", first.Mods) + } + if !slices.Equal(got[1].Mods, []string{"needs-decision"}) { + t.Fatalf("row already marked needs-decision got mods %v, want no duplicate marker", got[1].Mods) + } + if !got[2].Private || !slices.Equal(got[2].Mods, []string{"stalled"}) { + t.Fatalf("repo outside the public set = %+v, want private", got[2]) + } + if !slices.Equal(rows[0].Modifiers, []string{"hold"}) { + t.Fatalf("mapping modified the tracker row: %v", rows[0].Modifiers) + } +} + +func TestHubActivityItemsReadsTheMemoisedTracker(t *testing.T) { + t.Setenv("HIVE_PUBLIC_REPOS", "") + var nilServer *Server + if items, ok := nilServer.HubActivityItems(context.Background()); ok || items != nil { + t.Fatal("a nil server must report no tracker") + } + + now := time.Date(2026, 10, 31, 9, 0, 0, 0, time.UTC) + s := newTestServer() + s.stageStore = stagelabels.NewStore("", func() time.Time { return now }) + s.deps = &Dependencies{Config: &config.Config{ + Project: config.ProjectConfig{Org: "acme", PrimaryRepo: "acme/widget", Repos: []string{"acme/widget"}}, + Hub: config.HubConfig{IsPublic: true}, + }} + builds := 0 + s.stageTrackerBuildFn = func(_ *StatusPayload, _ *stagelabels.Store, at time.Time) StageTrackerResponse { + builds++ + return StageTrackerResponse{GeneratedAt: at, Items: []StageTrackerItem{ + {Repo: "acme/widget", Number: 7, Kind: "pr", Title: "Public", Stage: 70, StageSlug: "ci", Modifiers: []string{}}, + {Repo: "acme/private", Number: 8, Kind: "issue", Title: "Private", Modifiers: []string{}}, + }} + } + + if items, ok := s.HubActivityItems(context.Background()); ok || items != nil { + t.Fatal("a spoke with no status yet must report no tracker") + } + + s.statusMu.Lock() + s.status = minimalPayload() + s.statusMu.Unlock() + items, ok := s.HubActivityItems(context.Background()) + if !ok || len(items) != 2 { + t.Fatalf("HubActivityItems = %+v, %v; want both tracker rows", items, ok) + } + if items[0].Number != 7 || items[0].Private || items[0].StageNumber != 70 || !items[1].Private { + t.Fatalf("items = %+v, want the hub.is_public project repo public and the other private", items) + } + if _, ok := s.HubActivityItems(context.Background()); !ok || builds != 1 { + t.Fatalf("second read rebuilt the tracker (%d builds); want the memoised payload", builds) + } + s.stageTrackerCacheMu.Lock() + served := s.stageTrackerServed + s.stageTrackerCacheMu.Unlock() + if served { + t.Fatal("the in-process digest read counted as a tracker client and would add SSE nudges") + } +} + +func TestOnStageTrackerPublishFiresOnInvalidation(t *testing.T) { + s := newTestServer() + other := newTestServer() + fired := 0 + s.OnStageTrackerPublish(func() { fired++ }) + t.Cleanup(func() { s.OnStageTrackerPublish(nil) }) + + s.invalidateStageTrackerCache() + other.invalidateStageTrackerCache() + if fired != 1 { + t.Fatalf("hook fired %d times, want once for its own server only", fired) + } + s.OnStageTrackerPublish(nil) + s.invalidateStageTrackerCache() + if fired != 1 { + t.Fatal("a removed hook still fired") + } + var nilServer *Server + nilServer.OnStageTrackerPublish(func() {}) +} diff --git a/src/pkg/dashboard/stage_tracker_build.go b/src/pkg/dashboard/stage_tracker_build.go index b1a71f8d06..2442277c2f 100644 --- a/src/pkg/dashboard/stage_tracker_build.go +++ b/src/pkg/dashboard/stage_tracker_build.go @@ -802,9 +802,18 @@ func (s *Server) stageTrackerPayload(status *StatusPayload, now time.Time) (body // came from (stageTrackerSource*Name; "" with a nil body when the build // failed or ctx ended while waiting on an in-flight build). func (s *Server) stageTrackerPayloadSource(ctx context.Context, status *StatusPayload, now time.Time) (body []byte, etag string, generatedAt time.Time, source string) { + return s.stageTrackerPayloadFrom(ctx, status, now, true) +} + +// stageTrackerPayloadFrom is stageTrackerPayloadSource; markServed false +// reads the tracker without counting as a client that asked for it, so an +// in-process reader (the hub activity digest) adds no SSE nudges. +func (s *Server) stageTrackerPayloadFrom(ctx context.Context, status *StatusPayload, now time.Time, markServed bool) (body []byte, etag string, generatedAt time.Time, source string) { ttl := s.stageTrackerCacheTTL() s.stageTrackerCacheMu.Lock() - s.stageTrackerServed = true + if markServed { + s.stageTrackerServed = true + } c := s.stageTrackerCache if len(c.body) > 0 && !c.stale && now.Sub(c.generatedAt) < ttl { s.stageTrackerCacheMu.Unlock() @@ -904,6 +913,7 @@ func (s *Server) invalidateStageTrackerCache() (served bool) { s.stageTrackerGen++ served = s.stageTrackerServed s.stageTrackerCacheMu.Unlock() + s.notifyStageTrackerPublish() return served } diff --git a/src/pkg/hub/activity_update.go b/src/pkg/hub/activity_update.go new file mode 100644 index 0000000000..11f5ed7e49 --- /dev/null +++ b/src/pkg/hub/activity_update.go @@ -0,0 +1,97 @@ +package hub + +import ( + "encoding/json" + "io" + "net/http" + "strings" + "time" + + "github.com/hivecommons/hive/pkg/hub/spoke" +) + +// Activity-only updates (#15963). A spoke sends one on a stage-tracker +// publish, at most every 15 s, so the hub-wide Activity Monitor +// (#15951) shows a change before the next 2-minute heartbeat. The owner +// decision on #15861 was to reuse the heartbeat endpoint and bearer, so the +// update is a POST /api/heartbeat marked with spoke.ActivityUpdateHeader and +// carrying only the activity block. It touches nothing but the in-memory +// activity store: the registry entry, timeline and every other heartbeat +// side effect are left to the full beat. + +// activityUpdateGuard routes marked activity-only updates to +// handleActivityUpdate and passes every other request through untouched. +func (s *HubServer) activityUpdateGuard(next http.Handler) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodPost && r.URL.Path == "/api/heartbeat" && r.Header.Get(spoke.ActivityUpdateHeader) != "" { + s.handleActivityUpdate(w, r) + return + } + next.ServeHTTP(w, r) + }) +} + +// handleActivityUpdate authenticates an activity-only update exactly like a +// heartbeat (per-hive bearer bound to the claimed hive_id) and records its +// digest for a hive already in the registry. The response is a signed +// HeartbeatResponse carrying only ok and the acknowledged activity_etag. +func (s *HubServer) handleActivityUpdate(w http.ResponseWriter, r *http.Request) { + presentedBearer := "" + if s.hubSecret != "" { + auth := r.Header.Get("Authorization") + if !strings.HasPrefix(auth, "Bearer ") { + http.Error(w, "unauthorized", http.StatusUnauthorized) + return + } + presentedBearer = strings.TrimPrefix(auth, "Bearer ") + } + body, err := io.ReadAll(io.LimitReader(r.Body, maxPayloadBytes)) + if err != nil { + http.Error(w, "read error", http.StatusBadRequest) + return + } + var payload spoke.ActivityUpdatePayload + if err := json.Unmarshal(body, &payload); err != nil || payload.Update == nil { + http.Error(w, "invalid activity update", http.StatusBadRequest) + return + } + hiveID := sanitizeHeartbeatField(payload.Update.HiveID) + if hiveID == "" || !isValidName(hiveID) { + http.Error(w, "invalid hive_id", http.StatusBadRequest) + return + } + if s.hubSecret != "" && !s.verifyHeartbeatBearer(presentedBearer, hiveID) { + http.Error(w, "unauthorized", http.StatusUnauthorized) + return + } + if payload.Update.Activity == nil { + http.Error(w, "activity required", http.StatusBadRequest) + return + } + // Only a hive the registry already holds: an update must not create + // state for a hive that never beat or was removed. + if !s.hiveRegistered(hiveID) { + http.Error(w, "unknown hive; send a heartbeat first", http.StatusNotFound) + return + } + resp := HeartbeatResponse{OK: true} + resp.ActivityETag = s.activity.record(hiveID, payload.Update.Activity, time.Now().UTC()) + w.Header().Set("Content-Type", "application/json") + s.signHeartbeatResponse(w, &resp, hiveID) + data, _ := json.Marshal(resp) + _, _ = w.Write(data) +} + +// hiveRegistered reports whether the registry holds hiveID. It takes s.mu +// for reading only and releases it before the caller touches the activity +// store (a leaf lock). +func (s *HubServer) hiveRegistered(hiveID string) bool { + s.mu.RLock() + defer s.mu.RUnlock() + for _, h := range s.registry.Hives { + if h.ID == hiveID { + return true + } + } + return false +} diff --git a/src/pkg/hub/activity_update_test.go b/src/pkg/hub/activity_update_test.go new file mode 100644 index 0000000000..97dee35fbe --- /dev/null +++ b/src/pkg/hub/activity_update_test.go @@ -0,0 +1,150 @@ +package hub + +import ( + "encoding/json" + "net/http" + "net/http/httptest" + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/hub/spoke" + "github.com/hivecommons/hive/pkg/hubactivity" +) + +func activityUpdateBody(t *testing.T, hiveID string, d *hubactivity.Digest) string { + t.Helper() + body, err := json.Marshal(spoke.ActivityUpdatePayload{Update: &spoke.ActivityUpdate{HiveID: hiveID, Activity: d}}) + if err != nil { + t.Fatal(err) + } + return string(body) +} + +func postActivityUpdate(s *HubServer, body, bearer string) *httptest.ResponseRecorder { + req := httptest.NewRequest(http.MethodPost, "/api/heartbeat", strings.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set(spoke.ActivityUpdateHeader, "1") + if bearer != "" { + req.Header.Set("Authorization", bearer) + } + rec := httptest.NewRecorder() + s.Handler().ServeHTTP(rec, req) + return rec +} + +// An activity-only update replaces the held digest and touches nothing else: +// the registry entry keeps what the last full heartbeat reported. +func TestActivityUpdateRecordsOnlyTheDigest(t *testing.T) { + cleanup := helperSetupTempDirs(t) + defer cleanup() + s := newActivityHub() + postActivityHeartbeat(t, s, "hive-a", activityDigest("o/a", 1)) + s.mu.RLock() + before := s.registry.Hives[0] + s.mu.RUnlock() + + next := activityDigest("o/a", 1, 2, 3) + rec := postActivityUpdate(s, activityUpdateBody(t, "hive-a", next), heartbeatBearer(testHubSecret, "hive-a")) + if rec.Code != http.StatusOK { + t.Fatalf("activity update: status %d body=%s", rec.Code, rec.Body.String()) + } + var resp HeartbeatResponse + if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil { + t.Fatal(err) + } + if !resp.OK || resp.ActivityETag != next.ETag { + t.Fatalf("response = %+v, want ok and the new etag acknowledged", resp) + } + held := s.activity.snapshot([]string{"hive-a"})["hive-a"] + if len(held.digest.Items) != 3 { + t.Fatalf("held digest has %d items, want the update's 3", len(held.digest.Items)) + } + s.mu.RLock() + after := s.registry.Hives[0] + s.mu.RUnlock() + if len(s.registry.Hives) != 1 || after.Org != before.Org || after.PrimaryRepo != before.PrimaryRepo || + len(after.Repos) != len(before.Repos) || after.LastHeartbeat != before.LastHeartbeat { + t.Fatalf("activity update changed the registry entry: before=%+v after=%+v", before, after) + } + + // An unchanged marker for the held etag is acknowledged too. + marker := &hubactivity.Digest{ETag: next.ETag, GeneratedAt: next.GeneratedAt} + rec = postActivityUpdate(s, activityUpdateBody(t, "hive-a", marker), heartbeatBearer(testHubSecret, "hive-a")) + var markerResp HeartbeatResponse + if err := json.Unmarshal(rec.Body.Bytes(), &markerResp); err != nil || rec.Code != http.StatusOK || markerResp.ActivityETag != next.ETag { + t.Fatalf("marker update: status %d body=%s", rec.Code, rec.Body.String()) + } +} + +func TestActivityUpdateRejections(t *testing.T) { + cleanup := helperSetupTempDirs(t) + defer cleanup() + s := newActivityHub() + postActivityHeartbeat(t, s, "hive-a", activityDigest("o/a", 1)) + d := activityDigest("o/a", 1, 2) + good := heartbeatBearer(testHubSecret, "hive-a") + + for _, tc := range []struct { + name string + body string + bearer string + want int + }{ + {"missing bearer", activityUpdateBody(t, "hive-a", d), "", http.StatusUnauthorized}, + {"another hive's bearer", activityUpdateBody(t, "hive-a", d), heartbeatBearer(testHubSecret, "hive-b"), http.StatusUnauthorized}, + {"malformed body", "{", good, http.StatusBadRequest}, + {"no activity_update", `{"hive_id":"hive-a"}`, good, http.StatusBadRequest}, + {"invalid hive id", activityUpdateBody(t, "", d), good, http.StatusBadRequest}, + {"no activity block", activityUpdateBody(t, "hive-a", nil), good, http.StatusBadRequest}, + {"hive not in the registry", activityUpdateBody(t, "hive-new", d), heartbeatBearer(testHubSecret, "hive-new"), http.StatusNotFound}, + } { + t.Run(tc.name, func(t *testing.T) { + if rec := postActivityUpdate(s, tc.body, tc.bearer); rec.Code != tc.want { + t.Fatalf("status %d, want %d (body=%s)", rec.Code, tc.want, rec.Body.String()) + } + }) + } + if held := s.activity.snapshot([]string{"hive-a", "hive-new"}); len(held) != 1 || len(held["hive-a"].digest.Items) != 1 { + t.Fatalf("a rejected update changed the store: %+v", held) + } +} + +// Only a marked POST to the heartbeat path is diverted; everything else, +// including an ordinary heartbeat, reaches the mux. +func TestActivityUpdateGuardPassesOtherRequestsThrough(t *testing.T) { + s := newActivityHub() + reached := 0 + h := s.activityUpdateGuard(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { reached++ })) + for _, req := range []*http.Request{ + httptest.NewRequest(http.MethodPost, "/api/heartbeat", strings.NewReader("{}")), + httptest.NewRequest(http.MethodGet, "/api/heartbeat", nil), + httptest.NewRequest(http.MethodPost, "/api/task-status", strings.NewReader("{}")), + } { + if req.URL.Path != "/api/heartbeat" || req.Method != http.MethodPost { + req.Header.Set(spoke.ActivityUpdateHeader, "1") + } + h.ServeHTTP(httptest.NewRecorder(), req) + } + if reached != 3 { + t.Fatalf("%d of 3 unmarked or off-path requests reached the mux", reached) + } +} + +// A hub without the update path decodes the body as a heartbeat with no +// top-level hive_id and rejects it, so an older hub can never record an +// update as an empty beat; the spoke backs off on that 400. +func TestActivityUpdateBodyIsRejectedByThePlainHeartbeatHandler(t *testing.T) { + cleanup := helperSetupTempDirs(t) + defer cleanup() + s := newActivityHub() + req := httptest.NewRequest(http.MethodPost, "/api/heartbeat", strings.NewReader(activityUpdateBody(t, "hive-a", activityDigest("o/a", 1)))) + req.Header.Set("Authorization", heartbeatBearer(testHubSecret, "hive-a")) + rec := httptest.NewRecorder() + s.handleHeartbeat(rec, req) + if rec.Code != http.StatusBadRequest { + t.Fatalf("plain heartbeat handler answered %d, want 400", rec.Code) + } + if len(s.registry.Hives) != 0 { + t.Fatal("an activity update body created a registry entry") + } +} diff --git a/src/pkg/hub/robots.go b/src/pkg/hub/robots.go index 959b1ae62e..8c0d166324 100644 --- a/src/pkg/hub/robots.go +++ b/src/pkg/hub/robots.go @@ -136,9 +136,10 @@ func (s *HubServer) handleRobotsTxt(w http.ResponseWriter, r *http.Request) { // Handler is the hub's full HTTP handler: the mux wrapped in the search-engine // guard. Start serves this; tests that need the X-Robots-Tag behaviour go -// through it rather than s.mux. +// through it rather than s.mux. Activity-only heartbeat updates are routed +// ahead of the mux (activityUpdateGuard). func (s *HubServer) Handler() http.Handler { - return searchEngineGuard(s.mux) + return searchEngineGuard(s.activityUpdateGuard(s.mux)) } // searchEngineGuard stamps X-Robots-Tag: noindex, nofollow on every response diff --git a/src/pkg/hub/spoke/activity_publisher.go b/src/pkg/hub/spoke/activity_publisher.go new file mode 100644 index 0000000000..4e2ed4ec6e --- /dev/null +++ b/src/pkg/hub/spoke/activity_publisher.go @@ -0,0 +1,341 @@ +package spoke + +import ( + "bytes" + "context" + "encoding/json" + "io" + "log/slog" + "net/http" + "slices" + "sync" + "sync/atomic" + "time" + + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/hubactivity" + spokesig "github.com/hivecommons/hive/pkg/spoke" +) + +// Activity digest publisher (RFC hivecommons/hive#15861, #15963). The spoke +// builds the bounded hubactivity.Digest in process from its stage tracker +// (ActivitySource; no HTTP self-fetch, no GitHub call of its own) and +// publishes it two ways: +// +// - On every heartbeat: the full digest, or only its etag and generated_at +// when the hub already acknowledged that etag (no redundant snapshots). +// - Out of band on a tracker publish: an activity-only update on the +// heartbeat endpoint and bearer, at most one per +// activityUpdateMinInterval. Publishes that arrive while one is waiting +// or in flight merge into it; the rest are dropped (the next heartbeat +// carries the digest anyway). + +// ActivityUpdateHeader marks an activity-only update on POST /api/heartbeat. +const ActivityUpdateHeader = "X-Hive-Activity-Update" + +// activityUpdateMinInterval is the owner-decided ceiling on out-of-band +// updates (#15861): no more than one per 15 seconds. +const activityUpdateMinInterval = 15 * time.Second + +var ( + // activityItemsTimeout bounds reading the tracker so a slow build never + // holds a heartbeat; the beat then goes out without an activity block + // and the hub keeps the one it holds. A var so tests can shorten it. + activityItemsTimeout = 5 * time.Second + // activityUpdateBackoff pauses out-of-band updates after a hub answered + // one as unsupported; heartbeats keep carrying the digest meanwhile. + activityUpdateBackoff = 10 * time.Minute +) + +// ActivityOptions are the resolved hub.activity settings. +type ActivityOptions struct { + Enabled bool + MaxItems int + SharePrivate bool +} + +// ActivitySource is the StartHeartbeat callback that feeds the activity +// digest. Options is read on every build so a config reload applies to the +// next beat. Items returns the tracked items with Private set for +// private-repository rows (ok=false: no tracker yet). Subscribe, optional, +// registers a non-blocking hook run on every tracker publish. +type ActivitySource struct { + Options func() ActivityOptions + Items func(ctx context.Context) (items []hubactivity.Item, ok bool) + Subscribe func(notify func()) +} + +// ActivityUpdatePayload is the body of an activity-only update. hive_id sits +// inside activity_update, not at the top level, so a hub that predates the +// update path rejects the body ("hive_id required") instead of recording it +// as an empty heartbeat that would blank the hive's registry entry. +type ActivityUpdatePayload struct { + Update *ActivityUpdate `json:"activity_update"` +} + +// ActivityUpdate is the hive identity and the digest it publishes. +type ActivityUpdate struct { + HiveID string `json:"hive_id"` + Activity *hubactivity.Digest `json:"activity"` +} + +// activityPostFunc sends one activity-only update. ok is true only for an +// accepted, verified response; status is the HTTP status (0 = no response). +type activityPostFunc func(ctx context.Context, d *hubactivity.Digest) (ack string, status int, ok bool) + +type activityPublisher struct { + src ActivitySource + logger *slog.Logger + now func() time.Time + after func(time.Duration) <-chan time.Time + post activityPostFunc + // kick holds at most one pending tracker publish: the coalescing buffer. + kick chan struct{} + + // mu serializes build + post + acknowledge across the heartbeat and the + // out-of-band update, so acknowledgements (and the signed responses' + // sequence numbers) are applied in the order they were sent. + mu sync.Mutex + acked string + lastUpdate time.Time + backoff time.Time +} + +// activityPub is the running heartbeat loop's publisher (nil when no +// ActivitySource was registered). A hive runs at most one heartbeat loop. +var activityPub atomic.Pointer[activityPublisher] + +func newActivityPublisher(src ActivitySource, hubURL string, logger *slog.Logger) *activityPublisher { + if logger == nil { + logger = slog.Default() + } + p := &activityPublisher{ + src: src, + logger: logger, + now: time.Now, + after: time.After, + kick: make(chan struct{}, 1), + } + p.post = func(ctx context.Context, d *hubactivity.Digest) (string, int, bool) { + return postActivityUpdate(ctx, hubURL, heartbeatHiveID(), d, logger) + } + return p +} + +// build returns the current digest, redacted for hub.heartbeat_omit. +// ok is false when publishing is off or the tracker has nothing to give. +func (p *activityPublisher) build(ctx context.Context) (hubactivity.Digest, bool) { + if p.src.Options == nil || p.src.Items == nil { + return hubactivity.Digest{}, false + } + opts := p.src.Options() + if !opts.Enabled { + return hubactivity.Digest{}, false + } + items, ok := activityItemsWithTimeout(ctx, p.src.Items, activityItemsTimeout, p.logger) + if !ok { + return hubactivity.Digest{}, false + } + d := hubactivity.Build(items, hubactivity.BuildOptions{MaxItems: opts.MaxItems, SharePrivate: opts.SharePrivate, Now: p.now()}) + return redactActivity(d, omitSet()), true +} + +// heartbeatDigestLocked is the activity block for a heartbeat: nil when +// there is nothing to publish, an unchanged marker when the hub already +// holds this etag, else the full digest. Callers hold p.mu. +func (p *activityPublisher) heartbeatDigestLocked(ctx context.Context) *hubactivity.Digest { + d, ok := p.build(ctx) + if !ok { + return nil + } + if d.ETag != "" && d.ETag == p.acked { + return &hubactivity.Digest{ETag: d.ETag, GeneratedAt: d.GeneratedAt} + } + return &d +} + +// acknowledgeLocked records the etag the hub reported holding. Callers hold +// p.mu and call it only for an accepted, verified response. +func (p *activityPublisher) acknowledgeLocked(etag string) { + p.acked = etag +} + +// notify signals a tracker publish without blocking: a publish arriving +// while one is already pending merges into it. +func (p *activityPublisher) notify() { + select { + case p.kick <- struct{}{}: + default: + } +} + +// run sends coalesced out-of-band updates until ctx ends. +func (p *activityPublisher) run(ctx context.Context) { + for { + select { + case <-ctx.Done(): + return + case <-p.kick: + } + p.mu.Lock() + wait := p.lastUpdate.Add(activityUpdateMinInterval).Sub(p.now()) + p.mu.Unlock() + if wait > 0 { + select { + case <-ctx.Done(): + return + case <-p.after(wait): + } + } + // A publish signalled while waiting is covered by this update. + select { + case <-p.kick: + default: + } + p.update(ctx) + } +} + +// update sends one activity-only update when the digest differs from what +// the hub acknowledged. It reports whether an update was accepted. +func (p *activityPublisher) update(ctx context.Context) bool { + p.mu.Lock() + defer p.mu.Unlock() + now := p.now() + if now.Before(p.backoff) { + return false + } + d, ok := p.build(ctx) + if !ok || d.ETag == p.acked { + return false + } + p.lastUpdate = now + ack, status, sent := p.post(ctx, &d) + if !sent { + if activityUpdateUnsupported(status) { + p.backoff = now.Add(activityUpdateBackoff) + } + return false + } + p.acknowledgeLocked(ack) + return true +} + +// activityUpdateUnsupported reports a status meaning the hub does not take +// activity-only updates (a hub before #15963 answers 400 "hive_id +// required"). +func activityUpdateUnsupported(status int) bool { + switch status { + case http.StatusBadRequest, http.StatusMethodNotAllowed, http.StatusNotImplemented: + return true + } + return false +} + +// redactActivity applies hub.heartbeat_omit to a digest and re-stamps its +// etag: withheld repos drop every item (totals stay), withheld task titles +// blank the titles. +func redactActivity(d hubactivity.Digest, omit map[string]bool) hubactivity.Digest { + switch { + case omit[config.HeartbeatOmitRepos]: + d.Items = nil + d.Truncated = 0 + case omit[config.HeartbeatOmitTaskTitles]: + items := slices.Clone(d.Items) + for i := range items { + items[i].Title = "" + } + d.Items = items + default: + return d + } + d.ETag = hubactivity.ContentETag(d) + return d +} + +// activityItemsWithTimeout runs items with an upper bound, recovering a +// panic, so the tracker can never stall or crash the heartbeat loop. +func activityItemsWithTimeout(ctx context.Context, items func(context.Context) ([]hubactivity.Item, bool), timeout time.Duration, logger *slog.Logger) ([]hubactivity.Item, bool) { + type result struct { + items []hubactivity.Item + ok bool + } + cctx, cancel := context.WithTimeout(ctx, timeout) + defer cancel() + done := make(chan result, 1) + go func() { + defer func() { + if r := recover(); r != nil { + logger.Warn("hub activity digest: tracker read panicked; sending no activity block", "recover", r) + done <- result{} + } + }() + its, ok := items(cctx) + done <- result{items: its, ok: ok} + }() + select { + case r := <-done: + return r.items, r.ok + case <-cctx.Done(): + logger.Warn("hub activity digest: tracker read timed out; sending no activity block", "timeout", timeout.String()) + return nil, false + } +} + +// heartbeatHiveID is the hive ID from the published heartbeat identity. +func heartbeatHiveID() string { + heartbeatIdentity.Lock() + defer heartbeatIdentity.Unlock() + if heartbeatIdentity.payload == nil { + return "" + } + return heartbeatIdentity.payload.HiveID +} + +// postActivityUpdate sends an activity-only update with the heartbeat +// bearer and verifies the hub's signed acknowledgement the same way as a +// heartbeat response. +func postActivityUpdate(ctx context.Context, hubURL, hiveID string, d *hubactivity.Digest, logger *slog.Logger) (string, int, bool) { + if hubURL == "" || hiveID == "" || d == nil { + return "", 0, false + } + body, err := json.Marshal(ActivityUpdatePayload{Update: &ActivityUpdate{HiveID: hiveID, Activity: d}}) + if err != nil { + return "", 0, false + } + reqCtx, cancel := context.WithTimeout(ctx, heartbeatTimeout) + defer cancel() + req, err := http.NewRequestWithContext(reqCtx, http.MethodPost, hubURL+"/api/heartbeat", bytes.NewReader(body)) + if err != nil { + return "", 0, false + } + req.Header.Set("Content-Type", "application/json") + req.Header.Set(ActivityUpdateHeader, "1") + if secret := SpokeHeartbeatKey(); secret != "" { + req.Header.Set("Authorization", "Bearer "+secret) + } + resp, err := http.DefaultClient.Do(req) + if err != nil { + logger.Debug("hub activity update unreachable", "error", err) + return "", 0, false + } + defer func() { _ = resp.Body.Close() }() + if resp.StatusCode >= 300 { + logger.Debug("hub activity update rejected", "status", resp.StatusCode) + return "", resp.StatusCode, false + } + raw, err := io.ReadAll(io.LimitReader(resp.Body, maxPayloadBytes)) + if err != nil { + return "", resp.StatusCode, false + } + result := spokeHeartbeatVerifier(logger).Verify(SpokeSSOPublicKeys(), hiveID, raw, resp.Header.Get(spokesig.SigHeader), time.Now()) + if !result.Accepted { + logger.Warn("hub activity update response REJECTED by signature verification", "reason", result.Reason, "hive_id", hiveID) + return "", resp.StatusCode, false + } + var hbResp HeartbeatResponse + if err := json.Unmarshal(raw, &hbResp); err != nil { + return "", resp.StatusCode, false + } + return hbResp.ActivityETag, resp.StatusCode, true +} diff --git a/src/pkg/hub/spoke/activity_publisher_test.go b/src/pkg/hub/spoke/activity_publisher_test.go new file mode 100644 index 0000000000..f1a5be2012 --- /dev/null +++ b/src/pkg/hub/spoke/activity_publisher_test.go @@ -0,0 +1,561 @@ +package spoke + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "sync" + "testing" + "time" + + "github.com/hivecommons/hive/pkg/hubactivity" +) + +var activityTestT0 = time.Date(2026, 10, 31, 12, 0, 0, 0, time.UTC) + +// activityClock is a hand-driven clock for the publisher. +type activityClock struct { + mu sync.Mutex + now time.Time +} + +func (c *activityClock) Now() time.Time { + c.mu.Lock() + defer c.mu.Unlock() + return c.now +} + +func (c *activityClock) Advance(d time.Duration) { + c.mu.Lock() + c.now = c.now.Add(d) + c.mu.Unlock() +} + +// activityItemsBox is a tracker whose items a test can swap. +type activityItemsBox struct { + mu sync.Mutex + items []hubactivity.Item +} + +func (b *activityItemsBox) Set(items ...hubactivity.Item) { + b.mu.Lock() + b.items = items + b.mu.Unlock() +} + +func (b *activityItemsBox) Items(context.Context) ([]hubactivity.Item, bool) { + b.mu.Lock() + defer b.mu.Unlock() + return append([]hubactivity.Item(nil), b.items...), true +} + +func activityItem(repo string, n, stage int, mods ...string) hubactivity.Item { + return hubactivity.Item{Repo: repo, Number: n, Kind: "pr", Title: "item", Stage: "stage", StageNumber: stage, Mods: mods} +} + +func testActivityPublisher(opts ActivityOptions, box *activityItemsBox, clock *activityClock) *activityPublisher { + p := newActivityPublisher(ActivitySource{ + Options: func() ActivityOptions { return opts }, + Items: box.Items, + }, "", nil2Logger()) + p.now = clock.Now + return p +} + +func digestNumbers(d *hubactivity.Digest) []int { + out := make([]int, 0, len(d.Items)) + for _, it := range d.Items { + out = append(out, it.Number) + } + return out +} + +func TestActivityDigestCapKeepsTheMostUrgentAndDisclosesTruncation(t *testing.T) { + box := &activityItemsBox{} + box.Set( + activityItem("o/r", 1, 10), + activityItem("o/r", 2, 90), + activityItem("o/r", 3, 20, "stalled"), + activityItem("o/r", 4, 5, "needs-decision"), + activityItem("o/r", 5, 50), + activityItem("o/r", 6, 30, "needs-human"), + ) + p := testActivityPublisher(ActivityOptions{Enabled: true, MaxItems: 4}, box, &activityClock{now: activityTestT0}) + + d := p.heartbeatDigestLocked(context.Background()) + if d == nil { + t.Fatal("enabled publisher produced no digest") + } + // needs-human/needs-decision first (furthest stage first among them), + // then stalled, then furthest stage. + want := []int{6, 4, 3, 2} + if got := digestNumbers(d); len(got) != len(want) || got[0] != want[0] || got[1] != want[1] || got[2] != want[2] || got[3] != want[3] { + t.Fatalf("capped items = %v, want %v", got, want) + } + if d.Truncated != 2 { + t.Fatalf("truncated = %d, want the 2 items the cap left out", d.Truncated) + } + if d.Totals == nil || d.Totals.Items != 6 { + t.Fatalf("totals = %+v, want all 6 tracked items counted", d.Totals) + } + if !d.GeneratedAt.Equal(activityTestT0) || d.ETag == "" { + t.Fatalf("digest generated_at=%v etag=%q, want the injected clock and a content etag", d.GeneratedAt, d.ETag) + } +} + +func TestActivityDigestDefaultCapAndCeiling(t *testing.T) { + box := &activityItemsBox{} + items := make([]hubactivity.Item, 0, hubactivity.MaxItemsCeiling+5) + for n := 1; n <= hubactivity.MaxItemsCeiling+5; n++ { + items = append(items, activityItem("o/r", n, 10)) + } + box.Set(items...) + clock := &activityClock{now: activityTestT0} + + d := testActivityPublisher(ActivityOptions{Enabled: true}, box, clock).heartbeatDigestLocked(context.Background()) + if len(d.Items) != hubactivity.DefaultMaxItems || d.Truncated != len(items)-hubactivity.DefaultMaxItems { + t.Fatalf("default cap: %d items truncated=%d, want %d", len(d.Items), d.Truncated, hubactivity.DefaultMaxItems) + } + d = testActivityPublisher(ActivityOptions{Enabled: true, MaxItems: 10_000}, box, clock).heartbeatDigestLocked(context.Background()) + if len(d.Items) != hubactivity.MaxItemsCeiling || d.Truncated != 5 { + t.Fatalf("over-ceiling cap: %d items truncated=%d, want the %d-item ceiling", len(d.Items), d.Truncated, hubactivity.MaxItemsCeiling) + } +} + +func TestActivityDigestDropsPrivateItemsButCountsThem(t *testing.T) { + box := &activityItemsBox{} + priv := activityItem("o/secret", 2, 40, "needs-human") + priv.Private = true + box.Set(activityItem("o/public", 1, 10), priv) + clock := &activityClock{now: activityTestT0} + + d := testActivityPublisher(ActivityOptions{Enabled: true}, box, clock).heartbeatDigestLocked(context.Background()) + if got := digestNumbers(d); len(got) != 1 || got[0] != 1 { + t.Fatalf("items = %v, want only the public item", got) + } + if d.Truncated != 0 { + t.Fatalf("truncated = %d: a dropped private item is not a capped one", d.Truncated) + } + if d.Totals.Items != 2 || d.Totals.ByModifier["needs-human"] != 1 { + t.Fatalf("totals = %+v, want the private item still counted", d.Totals) + } + + shared := testActivityPublisher(ActivityOptions{Enabled: true, SharePrivate: true}, box, clock).heartbeatDigestLocked(context.Background()) + if len(shared.Items) != 2 || shared.Items[0].Number != 2 || !shared.Items[0].Private { + t.Fatalf("share_private items = %+v, want the private item kept and marked", shared.Items) + } +} + +func TestActivityDigestSendsOnlyTheEtagOnceAcknowledged(t *testing.T) { + box := &activityItemsBox{} + box.Set(activityItem("o/r", 1, 10)) + clock := &activityClock{now: activityTestT0} + p := testActivityPublisher(ActivityOptions{Enabled: true}, box, clock) + ctx := context.Background() + + full := p.heartbeatDigestLocked(ctx) + if full.IsUnchangedMarker() { + t.Fatal("first digest must be the full snapshot") + } + p.acknowledgeLocked(full.ETag) + + clock.Advance(2 * time.Minute) + marker := p.heartbeatDigestLocked(ctx) + if !marker.IsUnchangedMarker() || marker.ETag != full.ETag || !marker.GeneratedAt.Equal(activityTestT0.Add(2*time.Minute)) { + t.Fatalf("acknowledged digest = %+v, want only etag %q and the new generated_at", marker, full.ETag) + } + raw, err := json.Marshal(marker) + if err != nil { + t.Fatal(err) + } + var keys map[string]json.RawMessage + if err := json.Unmarshal(raw, &keys); err != nil { + t.Fatal(err) + } + if len(keys) != 2 || keys["etag"] == nil || keys["generated_at"] == nil { + t.Fatalf("marker wire form = %s, want only etag and generated_at", raw) + } + + box.Set(activityItem("o/r", 1, 10), activityItem("o/r", 2, 20)) + if changed := p.heartbeatDigestLocked(ctx); changed.IsUnchangedMarker() || changed.ETag == full.ETag { + t.Fatalf("changed tracker produced %+v, want a new full digest", changed) + } + + // A hub that lost the block (restart) acknowledges nothing: resend. + p.acknowledgeLocked("") + box.Set(activityItem("o/r", 1, 10)) + if resent := p.heartbeatDigestLocked(ctx); resent.IsUnchangedMarker() { + t.Fatal("a digest the hub no longer holds must be sent in full") + } +} + +func TestActivityDigestAbsentWhenDisabledOrUnavailable(t *testing.T) { + ctx := context.Background() + box := &activityItemsBox{} + clock := &activityClock{now: activityTestT0} + if d := testActivityPublisher(ActivityOptions{}, box, clock).heartbeatDigestLocked(ctx); d != nil { + t.Fatalf("disabled publisher sent %+v", d) + } + if d := newActivityPublisher(ActivitySource{}, "", nil).heartbeatDigestLocked(ctx); d != nil { + t.Fatalf("publisher without a source sent %+v", d) + } + none := newActivityPublisher(ActivitySource{ + Options: func() ActivityOptions { return ActivityOptions{Enabled: true} }, + Items: func(context.Context) ([]hubactivity.Item, bool) { return nil, false }, + }, "", nil2Logger()) + if d := none.heartbeatDigestLocked(ctx); d != nil { + t.Fatalf("publisher without a tracker sent %+v", d) + } +} + +func TestActivityItemsWithTimeoutBoundsASlowOrPanickingTracker(t *testing.T) { + release := make(chan struct{}) + defer close(release) + slow := func(context.Context) ([]hubactivity.Item, bool) { + <-release + return []hubactivity.Item{activityItem("o/r", 1, 1)}, true + } + if items, ok := activityItemsWithTimeout(context.Background(), slow, time.Millisecond, nil2Logger()); ok || items != nil { + t.Fatalf("slow tracker = %v, %v; want no items", items, ok) + } + panicky := func(context.Context) ([]hubactivity.Item, bool) { panic("boom") } + if items, ok := activityItemsWithTimeout(context.Background(), panicky, time.Minute, nil2Logger()); ok || items != nil { + t.Fatalf("panicking tracker = %v, %v; want no items", items, ok) + } +} + +func TestRedactActivityHonoursHeartbeatOmit(t *testing.T) { + d := hubactivity.Build([]hubactivity.Item{activityItem("o/r", 1, 10), activityItem("o/r", 2, 20)}, hubactivity.BuildOptions{MaxItems: 1, Now: activityTestT0}) + + if same := redactActivity(d, nil); same.ETag != d.ETag || len(same.Items) != 1 { + t.Fatalf("no omit classes changed the digest: %+v", same) + } + noRepos := redactActivity(d, map[string]bool{"repos": true}) + if len(noRepos.Items) != 0 || noRepos.Truncated != 0 || noRepos.Totals.Items != 2 || noRepos.ETag == d.ETag || noRepos.ETag == "" { + t.Fatalf("withheld repos = %+v, want totals only under a new etag", noRepos) + } + noTitles := redactActivity(d, map[string]bool{"task_titles": true}) + if len(noTitles.Items) != 1 || noTitles.Items[0].Title != "" || noTitles.ETag == d.ETag { + t.Fatalf("withheld titles = %+v, want blank titles under a new etag", noTitles) + } + if d.Items[0].Title == "" { + t.Fatal("redaction must not modify the input digest") + } +} + +func TestActivityDigestAppliesConfiguredOmitClasses(t *testing.T) { + SetHeartbeatOmit([]string{"repos"}) + t.Cleanup(func() { SetHeartbeatOmit(nil) }) + box := &activityItemsBox{} + box.Set(activityItem("o/r", 1, 10)) + d := testActivityPublisher(ActivityOptions{Enabled: true}, box, &activityClock{now: activityTestT0}).heartbeatDigestLocked(context.Background()) + if len(d.Items) != 0 || d.Totals.Items != 1 { + t.Fatalf("hub.heartbeat_omit [repos] digest = %+v, want totals without items", d) + } +} + +// recordingPost is an activityPostFunc that reports each send and, when +// gate is non-nil, holds the send in flight until the test releases it. +type recordingPost struct { + sent chan *hubactivity.Digest + gate chan struct{} + status int + ok bool +} + +func (r *recordingPost) post(_ context.Context, d *hubactivity.Digest) (string, int, bool) { + r.sent <- d + if r.gate != nil { + <-r.gate + } + if !r.ok { + return "", r.status, false + } + return d.ETag, r.status, true +} + +func TestActivityUpdatesCoalesceToOnePer15sWithBackpressure(t *testing.T) { + box := &activityItemsBox{} + box.Set(activityItem("o/r", 1, 10)) + clock := &activityClock{now: activityTestT0} + p := testActivityPublisher(ActivityOptions{Enabled: true}, box, clock) + rec := &recordingPost{sent: make(chan *hubactivity.Digest, 8), gate: make(chan struct{}), status: http.StatusOK, ok: true} + p.post = rec.post + waits := make(chan time.Duration, 8) + fire := make(chan time.Time) + p.after = func(d time.Duration) <-chan time.Time { + waits <- d + return fire + } + + ctx, cancel := context.WithCancel(context.Background()) + done := make(chan struct{}) + go func() { + defer close(done) + p.run(ctx) + }() + defer func() { + cancel() + <-done + }() + + // First publish: nothing sent recently, so the update goes out at once. + p.notify() + first := <-rec.sent + if digestNumbers(first)[0] != 1 { + t.Fatalf("first update = %v", digestNumbers(first)) + } + + // While it is in flight, a burst of publishes merges into one pending + // signal; notify never blocks. + box.Set(activityItem("o/r", 1, 10), activityItem("o/r", 2, 20)) + for range 5 { + p.notify() + } + rec.gate <- struct{}{} + + // The merged signal waits out the rest of the 15 s window. + if wait := <-waits; wait != activityUpdateMinInterval { + t.Fatalf("second update waited %v, want %v after the first", wait, activityUpdateMinInterval) + } + p.notify() + p.notify() + clock.Advance(activityUpdateMinInterval) + fire <- clock.Now() + second := <-rec.sent + rec.gate <- struct{}{} + if got := digestNumbers(second); len(got) != 2 { + t.Fatalf("second update = %v, want the merged latest tracker", got) + } + + // A publish with no change since the acknowledged etag sends nothing. + p.notify() + if wait := <-waits; wait != activityUpdateMinInterval { + t.Fatalf("third signal waited %v, want %v", wait, activityUpdateMinInterval) + } + clock.Advance(time.Second) + fire <- clock.Now() + // An unchanged pass does not restart the window, so the next signal + // waits out the remainder of the last real update's 15 s; receiving + // that wait also proves the unchanged pass has finished. + p.notify() + if wait := <-waits; wait != activityUpdateMinInterval-time.Second { + t.Fatalf("signal after an unchanged pass waited %v, want %v", wait, activityUpdateMinInterval-time.Second) + } + select { + case d := <-rec.sent: + t.Fatalf("unchanged tracker sent a redundant update: %+v", d) + default: + } +} + +func TestActivityUpdateBacksOffWhenTheHubDoesNotSupportIt(t *testing.T) { + box := &activityItemsBox{} + box.Set(activityItem("o/r", 1, 10)) + clock := &activityClock{now: activityTestT0} + p := testActivityPublisher(ActivityOptions{Enabled: true}, box, clock) + rec := &recordingPost{sent: make(chan *hubactivity.Digest, 8), status: http.StatusBadRequest} + p.post = rec.post + ctx := context.Background() + + if p.update(ctx) { + t.Fatal("a rejected update reported success") + } + <-rec.sent + if p.update(ctx) || len(rec.sent) != 0 { + t.Fatal("updates continued during the unsupported-hub backoff") + } + clock.Advance(activityUpdateBackoff) + rec.status, rec.ok = http.StatusOK, true + if !p.update(ctx) { + t.Fatal("update did not resume after the backoff") + } + <-rec.sent + if p.update(ctx) || len(rec.sent) != 0 { + t.Fatal("an acknowledged, unchanged digest was sent again") + } + + // Not-yet-registered (404) is transient: no backoff. + box.Set(activityItem("o/r", 2, 10)) + rec.status, rec.ok = http.StatusNotFound, false + p.update(ctx) + <-rec.sent + clock.Advance(time.Second) + p.update(ctx) + if len(rec.sent) != 1 { + t.Fatal("a 404 must not pause updates") + } +} + +func TestActivityUpdateUnsupportedStatuses(t *testing.T) { + for status, want := range map[int]bool{ + http.StatusBadRequest: true, + http.StatusMethodNotAllowed: true, + http.StatusNotImplemented: true, + http.StatusNotFound: false, + http.StatusUnauthorized: false, + http.StatusInternalServerError: false, + 0: false, + } { + if got := activityUpdateUnsupported(status); got != want { + t.Errorf("activityUpdateUnsupported(%d) = %v, want %v", status, got, want) + } + } +} + +func TestPostActivityUpdateCarriesOnlyTheActivityBlock(t *testing.T) { + type seen struct { + header string + body map[string]json.RawMessage + update ActivityUpdatePayload + } + got := make(chan seen, 1) + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + var s seen + s.header = r.Header.Get(ActivityUpdateHeader) + raw := json.RawMessage{} + _ = json.NewDecoder(r.Body).Decode(&raw) + _ = json.Unmarshal(raw, &s.body) + _ = json.Unmarshal(raw, &s.update) + got <- s + if r.URL.Path != "/api/heartbeat" { + http.NotFound(w, r) + return + } + _ = json.NewEncoder(w).Encode(HeartbeatResponse{OK: true, ActivityETag: s.update.Update.Activity.ETag}) + })) + defer srv.Close() + + d := hubactivity.Build([]hubactivity.Item{activityItem("o/r", 1, 10)}, hubactivity.BuildOptions{Now: activityTestT0}) + ack, status, ok := postActivityUpdate(context.Background(), srv.URL, "hive-act", &d, nil2Logger()) + if !ok || status != http.StatusOK || ack != d.ETag { + t.Fatalf("postActivityUpdate = %q, %d, %v; want the acknowledged etag", ack, status, ok) + } + s := <-got + if s.header == "" { + t.Fatal("update not marked with the activity-update header") + } + if len(s.body) != 1 || s.body["activity_update"] == nil { + t.Fatalf("update body keys = %v, want only activity_update (no top-level hive_id)", s.body) + } + if s.update.Update.HiveID != "hive-act" || s.update.Update.Activity.ETag != d.ETag { + t.Fatalf("update = %+v", s.update.Update) + } + + if _, _, ok := postActivityUpdate(context.Background(), srv.URL, "", &d, nil2Logger()); ok { + t.Fatal("an update without a hive identity must not be sent") + } +} + +func TestPostActivityUpdateReportsRejectionStatus(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + http.Error(w, "hive_id required", http.StatusBadRequest) + })) + defer srv.Close() + d := hubactivity.Build(nil, hubactivity.BuildOptions{Now: activityTestT0}) + if _, status, ok := postActivityUpdate(context.Background(), srv.URL, "hive-act", &d, nil2Logger()); ok || status != http.StatusBadRequest { + t.Fatalf("rejected update = %d, %v; want the 400 reported", status, ok) + } + if _, status, ok := postActivityUpdate(context.Background(), "http://127.0.0.1:0", "hive-act", &d, nil2Logger()); ok || status != 0 { + t.Fatalf("unreachable hub = %d, %v; want no status", status, ok) + } +} + +func TestPostHeartbeatToHubAttachesTheDigestAndHonoursTheAck(t *testing.T) { + box := &activityItemsBox{} + box.Set(activityItem("o/r", 1, 10)) + p := testActivityPublisher(ActivityOptions{Enabled: true}, box, &activityClock{now: activityTestT0}) + activityPub.Store(p) + t.Cleanup(func() { activityPub.Store(nil) }) + + blocks := make(chan *hubactivity.Digest, 4) + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + var payload HeartbeatPayload + _ = json.NewDecoder(r.Body).Decode(&payload) + blocks <- payload.Activity + ack := "" + if payload.Activity != nil { + ack = payload.Activity.ETag + } + _ = json.NewEncoder(w).Encode(HeartbeatResponse{OK: true, ActivityETag: ack}) + })) + defer srv.Close() + + cached := &HeartbeatPayload{HiveID: "hive-act"} + if resp := postHeartbeatToHub(context.Background(), srv.URL, cached, nil2Logger()); resp == nil || resp.ActivityETag == "" { + t.Fatalf("first beat response = %+v, want an acknowledged etag", resp) + } + first := <-blocks + if first == nil || first.IsUnchangedMarker() || len(first.Items) != 1 { + t.Fatalf("first beat activity = %+v, want the full digest", first) + } + if cached.Activity != nil { + t.Fatal("the caller's (cached) payload must not be modified") + } + + postHeartbeatToHub(context.Background(), srv.URL, cached, nil2Logger()) + if second := <-blocks; second == nil || !second.IsUnchangedMarker() || second.ETag != first.ETag { + t.Fatalf("second beat activity = %+v, want only the acknowledged etag", second) + } +} + +func TestStartHeartbeatWiresTheActivitySource(t *testing.T) { + resetSingleLoopGuard(t) + collapseReadinessWait(t) + + beats := make(chan *hubactivity.Digest, 8) + updates := make(chan ActivityUpdate, 8) + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Header.Get(ActivityUpdateHeader) != "" { + var u ActivityUpdatePayload + _ = json.NewDecoder(r.Body).Decode(&u) + if u.Update != nil { + updates <- *u.Update + } + _ = json.NewEncoder(w).Encode(HeartbeatResponse{OK: true}) + return + } + var payload HeartbeatPayload + _ = json.NewDecoder(r.Body).Decode(&payload) + beats <- payload.Activity + // Acknowledge nothing, so the out-of-band update has news to send. + _ = json.NewEncoder(w).Encode(HeartbeatResponse{OK: true}) + })) + defer srv.Close() + + box := &activityItemsBox{} + box.Set(activityItem("o/r", 7, 10)) + subscribed := make(chan func(), 1) + src := ActivitySource{ + Options: func() ActivityOptions { return ActivityOptions{Enabled: true} }, + Items: box.Items, + Subscribe: func(notify func()) { subscribed <- notify }, + } + + ctx, cancel := context.WithCancel(context.Background()) + done := make(chan struct{}) + go func() { + defer close(done) + StartHeartbeat(ctx, srv.URL, func() *HeartbeatPayload { return &HeartbeatPayload{HiveID: "hive-act"} }, time.Hour, nil2Logger(), src) + }() + + notify := <-subscribed + if beat := <-beats; beat == nil || len(beat.Items) != 1 || beat.Items[0].Number != 7 { + t.Fatalf("heartbeat activity = %+v, want the tracker digest", beat) + } + notify() + select { + case u := <-updates: + if u.HiveID != "hive-act" || u.Activity == nil || len(u.Activity.Items) != 1 { + t.Fatalf("activity update = %+v", u) + } + case <-time.After(5 * time.Second): + t.Fatal("tracker publish sent no activity update") + } + cancel() + <-done + if activityPub.Load() != nil { + t.Fatal("the stopped loop left its publisher installed") + } +} diff --git a/src/pkg/hub/spoke/heartbeat.go b/src/pkg/hub/spoke/heartbeat.go index efd0ab086b..858be8e59e 100644 --- a/src/pkg/hub/spoke/heartbeat.go +++ b/src/pkg/hub/spoke/heartbeat.go @@ -1163,8 +1163,9 @@ type HeartbeatPayload struct { // SelfExperimentsOptIn is local consent; absent or false means opted out. SelfExperimentsOptIn bool `json:"self_experiments_opt_in,omitempty"` // Activity is the optional bounded activity digest for the hub-wide - // Activity Monitor (#15861/#15951). Nil until the publisher (#15963) - // populates it; omitempty keeps the beat unchanged meanwhile. + // Activity Monitor (#15861/#15951), attached by the activity publisher + // (#15963) at send time; nil when hub.activity is off or the tracker has + // nothing yet, an etag-only marker when the hub holds it already. Activity *hubactivity.Digest `json:"activity,omitempty"` } @@ -1385,6 +1386,7 @@ func StartHeartbeat(ctx context.Context, hubURL string, collect StatusCollector, var freshCollect FreshStatusCollector var onUpgradePolicy UpgradePolicyCallback var onUpgradeAnnounce UpgradeAnnounceCallback + var activitySrc *ActivitySource for _, cb := range callbacks { switch fn := cb.(type) { case UpgradeCallback: @@ -1417,6 +1419,8 @@ func StartHeartbeat(ctx context.Context, hubURL string, collect StatusCollector, onUpgradePolicy = fn case UpgradeAnnounceCallback: onUpgradeAnnounce = fn + case ActivitySource: + activitySrc = &fn } } @@ -1424,6 +1428,16 @@ func StartHeartbeat(ctx context.Context, hubURL string, collect StatusCollector, waitForReady(ctx, logger) + if activitySrc != nil { + pub := newActivityPublisher(*activitySrc, hubURL, logger) + activityPub.Store(pub) + defer activityPub.CompareAndSwap(pub, nil) + go pub.run(ctx) + if activitySrc.Subscribe != nil { + activitySrc.Subscribe(pub.notify) + } + } + processHeartbeatResponse := func(resp *HeartbeatResponse) { if resp == nil { return @@ -1777,6 +1791,15 @@ func postHeartbeatToHub(ctx context.Context, hubURL string, payload *HeartbeatPa if !payload.SelfExperimentsOptIn { nous.SelfExperiments.Apply(false, nil) } + // The activity digest is built at send time and its acknowledgement + // applied under the publisher's lock, so an out-of-band update cannot + // interleave between this beat and its response. + pub := activityPub.Load() + if pub != nil { + pub.mu.Lock() + defer pub.mu.Unlock() + payload.Activity = pub.heartbeatDigestLocked(ctx) + } body, err := json.Marshal(payload) if err != nil { logger.Warn("hub heartbeat marshal failed", "error", err) @@ -1850,6 +1873,9 @@ func postHeartbeatToHub(ctx context.Context, hubURL string, payload *HeartbeatPa "installation_id", hbResp.GitHubAppConfig.InstallationID, ) } + if pub != nil { + pub.acknowledgeLocked(hbResp.ActivityETag) + } return &hbResp } return nil From 4548da6d3ef1ae9fa1f897540fea782b092677bf Mon Sep 17 00:00:00 2001 From: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Sat, 31 Oct 2026 07:39:41 -0400 Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=A7=AA=20test(config,dashboard):=20pi?= =?UTF-8?q?n=20hub.activity=20in=20runtime=20golden=20and=20allowlist=20pk?= =?UTF-8?q?g/hubactivity=20import?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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> --- src/internal/testutil/dashboard_import_allowlist.txt | 1 + src/pkg/config/testdata/agent_runtime_golden.json | 1 + 2 files changed, 2 insertions(+) diff --git a/src/internal/testutil/dashboard_import_allowlist.txt b/src/internal/testutil/dashboard_import_allowlist.txt index ca6a37199c..b7ac00bb75 100644 --- a/src/internal/testutil/dashboard_import_allowlist.txt +++ b/src/internal/testutil/dashboard_import_allowlist.txt @@ -44,6 +44,7 @@ github.com/hivecommons/hive/pkg/hivestate github.com/hivecommons/hive/pkg/hooks github.com/hivecommons/hive/pkg/housestyle github.com/hivecommons/hive/pkg/hub +github.com/hivecommons/hive/pkg/hubactivity github.com/hivecommons/hive/pkg/hubbackup github.com/hivecommons/hive/pkg/inferencehealth github.com/hivecommons/hive/pkg/ioscan diff --git a/src/pkg/config/testdata/agent_runtime_golden.json b/src/pkg/config/testdata/agent_runtime_golden.json index 5ee4c4fb08..900aa724fb 100644 --- a/src/pkg/config/testdata/agent_runtime_golden.json +++ b/src/pkg/config/testdata/agent_runtime_golden.json @@ -557,6 +557,7 @@ "AutoUpgrade": false, "AutoUpgradeMode": "", "ContributeSuspended": false, + "activity": {}, "ContributeWallEnabled": false, "ContributeWallRetentionDays": 0, "NPSEnabled": null, From 86d6a16f589b32c340a6eaf680a171f67f0ac510 Mon Sep 17 00:00:00 2001 From: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Sat, 31 Oct 2026 07:49:58 -0400 Subject: [PATCH 3/4] =?UTF-8?q?=F0=9F=A7=AA=20test(dashboard):=20raise=20i?= =?UTF-8?q?nternal=20import=20ratchet=20for=20pkg/hubactivity?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- src/pkg/dashboard/import_count_test.go | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/pkg/dashboard/import_count_test.go b/src/pkg/dashboard/import_count_test.go index 68756c2f2d..80828584f6 100644 --- a/src/pkg/dashboard/import_count_test.go +++ b/src/pkg/dashboard/import_count_test.go @@ -54,8 +54,11 @@ func TestDashboardInternalImportCountRatchet(t *testing.T) { // surface the dashboard holds instead of *agent.Manager; pkg/agent stays // for the audit, trailer, provider-status and agent-mode helpers the // Runtime does not cover, and leaves when those move behind the boundary - // (hivecommons/hive#13536). - const maxDashboardInternalImports = 56 + // (hivecommons/hive#13536), plus pkg/hubactivity, the leaf wire contract + // (ceilings, urgency order, sanitiser) the spoke's heartbeat activity + // digest is built against from the dashboard's own stage tracker + // (hivecommons/hive#15963). + const maxDashboardInternalImports = 57 entries, err := os.ReadDir(".") if err != nil { From e150c77da9c77d7452a773a47af84b2cd389f175 Mon Sep 17 00:00:00 2001 From: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Sat, 31 Oct 2026 08:17:59 -0400 Subject: [PATCH 4/4] =?UTF-8?q?=F0=9F=A7=AA=20test(spoke,dashboard):=20syn?= =?UTF-8?q?c=20coalesce=20test=20on=20digest=20builds=20and=20allowlist=20?= =?UTF-8?q?hub.activity=20settings?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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> --- src/pkg/dashboard/settings_parity_allowlist.txt | 3 +++ src/pkg/hub/spoke/activity_publisher_test.go | 17 +++++++++++++++-- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/src/pkg/dashboard/settings_parity_allowlist.txt b/src/pkg/dashboard/settings_parity_allowlist.txt index ce7bf641d3..593f90d185 100644 --- a/src/pkg/dashboard/settings_parity_allowlist.txt +++ b/src/pkg/dashboard/settings_parity_allowlist.txt @@ -297,6 +297,9 @@ hooks[].on # TODO #11854 hooks[].params. # TODO #11854 hooks[].rate_limit_per_minute # TODO #11854 hooks[].when # TODO #11854 +hub.activity.enabled # spoke activity digest publish; yaml-only, see telemetry.md (#15963) +hub.activity.max_items # spoke activity digest cap; yaml-only, see telemetry.md (#15963) +hub.activity.share_private # spoke activity digest private-repo opt-in; yaml-only, see telemetry.md (#15963) hub.contribute_allow_labels[] # TODO #11854 hub.contribute_allow_models[] # TODO #11854 hub.contribute_delegatable_roles[] # TODO #11854 diff --git a/src/pkg/hub/spoke/activity_publisher_test.go b/src/pkg/hub/spoke/activity_publisher_test.go index f1a5be2012..6da771926f 100644 --- a/src/pkg/hub/spoke/activity_publisher_test.go +++ b/src/pkg/hub/spoke/activity_publisher_test.go @@ -282,6 +282,15 @@ func TestActivityUpdatesCoalesceToOnePer15sWithBackpressure(t *testing.T) { p := testActivityPublisher(ActivityOptions{Enabled: true}, box, clock) rec := &recordingPost{sent: make(chan *hubactivity.Digest, 8), gate: make(chan struct{}), status: http.StatusOK, ok: true} p.post = rec.post + // built reports each digest build. run drains a pending kick just + // before it builds, so a build observed here proves a later notify + // is not swallowed by that drain. + built := make(chan struct{}, 8) + items := p.src.Items + p.src.Items = func(ctx context.Context) ([]hubactivity.Item, bool) { + built <- struct{}{} + return items(ctx) + } waits := make(chan time.Duration, 8) fire := make(chan time.Time) p.after = func(d time.Duration) <-chan time.Time { @@ -302,6 +311,7 @@ func TestActivityUpdatesCoalesceToOnePer15sWithBackpressure(t *testing.T) { // First publish: nothing sent recently, so the update goes out at once. p.notify() + <-built first := <-rec.sent if digestNumbers(first)[0] != 1 { t.Fatalf("first update = %v", digestNumbers(first)) @@ -323,6 +333,7 @@ func TestActivityUpdatesCoalesceToOnePer15sWithBackpressure(t *testing.T) { p.notify() clock.Advance(activityUpdateMinInterval) fire <- clock.Now() + <-built second := <-rec.sent rec.gate <- struct{}{} if got := digestNumbers(second); len(got) != 2 { @@ -336,9 +347,11 @@ func TestActivityUpdatesCoalesceToOnePer15sWithBackpressure(t *testing.T) { } clock.Advance(time.Second) fire <- clock.Now() + // Wait for the unchanged pass to build before signalling again, + // otherwise the kick-drain ahead of that build swallows the signal. + <-built // An unchanged pass does not restart the window, so the next signal - // waits out the remainder of the last real update's 15 s; receiving - // that wait also proves the unchanged pass has finished. + // waits out the remainder of the last real update's 15 s. p.notify() if wait := <-waits; wait != activityUpdateMinInterval-time.Second { t.Fatalf("signal after an unchanged pass waited %v, want %v", wait, activityUpdateMinInterval-time.Second)